@mmerterden/multi-agent-toolkit-mcp 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -15,6 +15,83 @@ Releases before this file exists are recorded in the git tags and commit history
 
 ---
 
+## 3.5.0
+
+### Added
+
+- **`ios_accessibility_audit` checks the reading order.** A screen with perfect
+  labels is still unusable if VoiceOver walks it in the wrong order, and nothing
+  was looking. The audit compares the reading sequence against the visual layout
+  and reports the first element that arrives out of place.
+
+  The comparison is rows-then-columns, not a naive top-to-bottom sort: a home
+  screen is a grid, a toolbar is a row, and sorting by `y` alone calls every
+  correct grid broken. Elements share a row when their vertical extents overlap
+  by more than half the shorter one, which absorbs the few points of jitter real
+  layouts carry. `rtl: true` expects right-to-left within a row.
+
+  It is an `important` finding and never a `critical` one: a deliberate reading
+  order that differs from the visual one is legitimate, so this is a question
+  worth asking rather than a proven defect. Verified on a live home screen grid:
+  13 elements, reading order correct, no false positive.
+
+- **Traits and hints.** The dumper now reads `AXRoleDescription` (what a screen
+  reader announces the element AS) and `AXHelp` (where the iOS
+  `accessibilityHint` bridges to). A control with no role announcement is read
+  out as bare text and the user cannot tell it is actionable, so that is an
+  `important` finding. A missing hint is not: hints are not required on every
+  element, so the result reports `hints_present` as a count and leaves the
+  judgement to the reader.
+
+  `AXSubrole` was probed first and carries nothing at all through this bridge,
+  so it is not read. Guessing at it would have produced a check that never fires.
+
+### Note
+
+Stage 2 of 4. Contrast, Dynamic Type and clipped text still cannot be reached
+from a tree dump; they need Apple's own `XCUIAccessibilityAudit`, which is an
+XCUITest run rather than a simctl call. The Android side is stage 4 and is
+unverifiable on a machine with no adb.
+
+## 3.4.0
+
+### Fixed
+
+- **The accessibility audits reported a clean screen they had never read.** On a
+  tree that came back empty they returned `elements_scanned: 0, total_issues: 0,
+  critical: 0, important: 0, warning: 0` - a full clean bill of health,
+  indistinguishable from an accessible screen, and the first reading is the one
+  anyone believes. Both audits now carry `measurable` and a `reason`, and an
+  unmeasurable run reports `total_issues: null`, never 0. A count of zero is a
+  measurement; none was taken.
+
+- **The iOS tree was empty until the Simulator window had been activated.**
+  Measured on a live simulator: 1 node before activation, 28 after, and it stays
+  populated once the window is backgrounded again. The dumper now activates the
+  window itself. It also says what to do when Simulator.app is not running at
+  all, because booting a device with `simctl` is not enough - the accessibility
+  bridge lives in the UI app.
+
+- **The iOS audit scored Simulator.app's own chrome as app findings.** The
+  dumped window carries the hardware buttons, the toolbar and the title text
+  beside the device screen, so Apple's 17x65pt Volume Up button was reported as
+  an app tap-target violation. The audit now scopes to the device screen, the
+  largest AXGroup child of the window. On a live Home screen this took the
+  result from 23 findings over 23 elements to 1 finding over 13: 22 of the 23
+  were the simulator's own interface.
+
+- The scoring moved to `tools/a11y/` with a suite covering the degenerate tree,
+  the chrome exclusion, a scope that matches nothing, and the rule that an
+  element with no identifier is audited whatever the scope - you cannot scope
+  what you cannot identify, and skipping it would hide the finding that says so.
+
+### Note
+
+This is the first of four stages. It buys nothing new for a blind user yet; it
+makes the existing checks honest so the next stages can be trusted. Reading
+order, traits and hints come next, then Apple's own `XCUIAccessibilityAudit`
+(contrast, Dynamic Type, clipped text), then the Android side.
+
 ## 3.3.0
 
 ### Added

package/index.js

@@ -30,6 +30,7 @@ import {
 import { DESIGN_TOOLS, handleDesign } from "./tools/design-check/index.js";
 import { parseLaunchOutput } from "./tools/launch-time/index.js";
 import { parseLeaksOutput, parseMeminfoOutput, diffMeminfo } from "./tools/memory/index.js";
+import { auditIosTree, auditAndroidDump } from "./tools/a11y/index.js";
 import { interactiveElements } from "./tools/ui-inspect/index.js";
 import { selectCrashReports } from "./tools/crash-logs/index.js";
 import {
@@ -350,7 +351,7 @@ const IOS_TOOLS = [
   { name: "ios_get_app_container", description: "Get iOS app container path", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, container: { type: "string", enum: ["app", "data", "groups"] }, device_id: { type: "string" } }, required: ["bundle_id"] } },
   { name: "ios_erase_device", description: "Factory reset iOS simulator", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
   { name: "ios_get_ui_tree", description: "Get iOS accessibility UI tree via macOS AX APIs. Pass `path` to write the raw dump to a file and return only its location - the full tree can be tens of KB.", inputSchema: { type: "object", properties: { max_depth: { type: "number" }, path: { type: "string", description: "Absolute file path to write the raw tree JSON to. The parent directory must already exist." } } } },
-  { name: "ios_accessibility_audit", description: "Audit iOS app accessibility: missing labels, small tap targets (<44pt), missing identifiers. Use scope to filter by identifier prefix (e.g. 'login_' only checks login screen elements).", inputSchema: { type: "object", properties: { max_depth: { type: "number" }, scope: { type: "string", description: "Filter: only audit elements whose identifier starts with this prefix (e.g. 'login_', 'settings_'). Omit to audit all." } } } },
+  { name: "ios_accessibility_audit", description: "Audit iOS app accessibility on the booted simulator: missing labels, controls a screen reader cannot name, tap targets under 44pt, missing identifiers, and whether the reading order follows the visual layout. Reports measurable:false with a reason rather than a clean result when the tree could not be read - booting a device is not enough, Simulator.app must be running. Scopes to the device screen, never the simulator own chrome.", inputSchema: { type: "object", properties: { max_depth: { type: "number" }, scope: { type: "string", description: "Filter: only audit elements whose identifier starts with this prefix (e.g. 'login_', 'settings_'). Omit to audit all." }, rtl: { type: "boolean", description: "Expect right-to-left reading within a row. Default false." } } } },
   { name: "ios_biometric", description: "Simulate Face ID / Touch ID on iOS simulator (match or nomatch)", inputSchema: { type: "object", properties: { match: { type: "boolean", description: "true=success, false=failure" }, device_id: { type: "string" } }, required: ["match"] } },
   { name: "ios_archive_audit", description: "DEPRECATED - use ios_app_store_audit (18-rule deep scan). Lighter 6-check audit kept for backward compatibility; will be removed in the next major.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Path to .xcarchive" } }, required: ["archive_path"] } },
   { name: "ios_export_ipa", description: "Export a .xcarchive to a signed .ipa via xcodebuild -exportArchive. Generates the exportOptions.plist from the arguments (method defaults to app-store-connect), so callers do not have to hand-maintain one. Returns the .ipa path plus parsed errors; a run that exits 0 without producing an .ipa is reported as a failure. Pair with ios_testflight_validate for the pre-submission gate.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive" }, output_dir: { type: "string", description: "Directory to write the .ipa into" }, method: { type: "string", description: "Export method: app-store-connect (default) | release-testing | enterprise | development" }, team_id: { type: "string", description: "Apple Developer team ID" }, provisioning_profiles: { type: "object", description: "Map of bundleId -> provisioning profile name (manual signing)" }, signing_style: { type: "string", description: "automatic | manual" }, upload_symbols: { type: "boolean", description: "Include symbols (default true)" }, allow_provisioning_updates: { type: "boolean", description: "Off by default. Lets xcodebuild register devices and create/modify provisioning profiles in the developer account - a change on Apple's side, so it is opt-in" }, timeout_sec: { type: "number", description: "Default 900" } }, required: ["archive_path", "output_dir"] } },
@@ -500,38 +501,29 @@ async function handleIOS(name, args, ctx = {}) {
       const script = join(__dirname, "ui-tree-dumper.swift");
       if (!existsSync(script)) return "ui-tree-dumper.swift not found";
       const depth = num(args.max_depth ?? 10, "max_depth");
-      const scope = args.scope || null;
-      const treeJson = run(`swift ${shq(script)} ${depth}`, { timeout: 15000 });
+      const treeJson = run(`swift ${shq(script)} ${depth}`, { timeout: 30000 });
+      let tree = null;
       try {
-        const issues = [];
-        let totalScanned = 0, totalSkipped = 0;
-        function auditNode(node, path = "") {
-          const loc = path ? `${path} > ${node.role}` : node.role;
-          const w = node.frame?.w || 0, h = node.frame?.h || 0;
-          const isInteractive = ["AXButton", "AXLink", "AXTextField", "AXTextArea", "AXCheckBox", "AXRadioButton", "AXSlider", "AXSwitch", "AXTab"].includes(node.role);
-          if (isInteractive) {
-            // Scope filter: skip elements outside scope
-            if (scope && node.identifier && !node.identifier.startsWith(scope)) { totalSkipped++; if (node.children) node.children.forEach(c => auditNode(c, loc)); return; }
-            if (scope && !node.identifier) { /* no identifier = can't scope, still audit */ }
-            totalScanned++;
-            if (!node.title && !node.description && !node.value) issues.push({ severity: "critical", issue: "Missing accessibility label", element: loc, identifier: node.identifier, frame: node.frame });
-            if (!node.identifier) issues.push({ severity: "warning", issue: "Missing accessibility identifier (UI testing)", element: loc });
-            if (w > 0 && h > 0 && (w < 44 || h < 44)) issues.push({ severity: "important", issue: `Tap target too small: ${w.toFixed(0)}x${h.toFixed(0)}pt (min 44x44)`, element: loc, identifier: node.identifier, frame: node.frame });
-          }
-          if (node.children) node.children.forEach(c => auditNode(c, loc));
-        }
-        const tree = JSON.parse(treeJson);
-        auditNode(tree);
-        return JSON.stringify({ scope: scope || "all", elements_scanned: totalScanned, elements_skipped: totalSkipped, total_issues: issues.length, critical: issues.filter(i => i.severity === "critical").length, important: issues.filter(i => i.severity === "important").length, warning: issues.filter(i => i.severity === "warning").length, issues }, null, 2);
-      } catch (e) { return `ERROR parsing UI tree: ${e.message}\n\nRaw output:\n${treeJson?.substring(0, 500)}`; }
+        tree = JSON.parse(treeJson);
+      } catch {
+        tree = null;
+      }
+      const r = auditIosTree({ tree, scope: args.scope || null, rtl: args.rtl === true });
+      return JSON.stringify({
+        scope: r.scope,
+        measurable: r.measurable,
+        reason: r.reason,
+        elements_scanned: r.elementsScanned,
+        elements_skipped: r.elementsSkipped,
+        reading_order_ok: r.readingOrderOk ?? null,
+        hints_present: r.hintsPresent ?? null,
+        total_issues: r.totalIssues,
+        critical: r.critical,
+        important: r.important,
+        warning: r.warning,
+        issues: r.issues,
+      }, null, 2);
     }
-    // `simctl keychain <device> biometric-enroll` / `biometric-match` do not
-    // exist -  `keychain` supports only add-root-cert/add-cert/reset. The only
-    // available lever is the (undocumented) BiometricKit notification, which is
-    // posted via notifyutil inside the simulator. notifyutil exits 0 even when
-    // it cannot set or post the name, so its output has to be inspected: a
-    // "Failed with code N" line means the notification did not land, and that
-    // must be reported as a failure rather than as a simulated success.
     case "ios_biometric": {
       const d = iosDevice(args.device_id);
       const action = args.match ? "match" : "nomatch";
@@ -1062,34 +1054,20 @@ async function handleAndroid(name, args, ctx = {}) {
       const f = join(SCREENSHOT_DIR, `a11y_${Date.now()}.xml`);
       run(`adb ${df} pull /sdcard/_mcp_a11y.xml ${shq(f)}`);
       run(`adb ${df} shell rm /sdcard/_mcp_a11y.xml`);
-      if (!existsSync(f)) return "ERROR: UI dump failed";
-      const xml = readFileSync(f, "utf-8");
-      const scope = args.scope || null;
-      const issues = [];
-      let totalScanned = 0, totalSkipped = 0;
-      const nodeRegex = /<node[^>]*>/g;
-      let match;
-      while ((match = nodeRegex.exec(xml)) !== null) {
-        const node = match[0];
-        const cls = node.match(/class="([^"]*)"/)?.[1] || "";
-        const desc = node.match(/content-desc="([^"]*)"/)?.[1] || "";
-        const rid = node.match(/resource-id="([^"]*)"/)?.[1] || "";
-        const text = node.match(/text="([^"]*)"/)?.[1] || "";
-        const clickable = node.includes('clickable="true"');
-        const bounds = node.match(/bounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/);
-        if (clickable) {
-          if (scope && rid && !rid.includes(scope)) { totalSkipped++; continue; }
-          totalScanned++;
-          if (!desc && !text) issues.push({ severity: "critical", issue: "Missing contentDescription", element: cls, resourceId: rid });
-          if (!rid) issues.push({ severity: "warning", issue: "Missing resource-id (UI testing)", element: cls });
-          if (bounds) {
-            const w = parseInt(bounds[3]) - parseInt(bounds[1]);
-            const h = parseInt(bounds[4]) - parseInt(bounds[2]);
-            if (w < 48 || h < 48) issues.push({ severity: "important", issue: `Touch target too small: ${w}x${h}dp (min 48x48)`, element: cls, resourceId: rid });
-          }
-        }
-      }
-      return JSON.stringify({ scope: scope || "all", elements_scanned: totalScanned, elements_skipped: totalSkipped, total_issues: issues.length, critical: issues.filter(i => i.severity === "critical").length, important: issues.filter(i => i.severity === "important").length, warning: issues.filter(i => i.severity === "warning").length, issues }, null, 2);
+      const xml = existsSync(f) ? readFileSync(f, "utf-8") : "";
+      const r = auditAndroidDump({ xml, scope: args.scope || null });
+      return JSON.stringify({
+        scope: r.scope,
+        measurable: r.measurable,
+        reason: r.reason,
+        elements_scanned: r.elementsScanned,
+        elements_skipped: r.elementsSkipped,
+        total_issues: r.totalIssues,
+        critical: r.critical,
+        important: r.important,
+        warning: r.warning,
+        issues: r.issues,
+      }, null, 2);
     }
     case "android_launch_time": {
       run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`);
@@ -1557,17 +1535,25 @@ const ISSUE_LIST = {
   },
 };
 
+// The counts are nullable on purpose. An audit that could not read the tree
+// reports null, never 0: a count of zero is a measurement, and none was taken.
+// `measurable` is the field to branch on; the counts are only meaningful when
+// it is true.
 const ACCESSIBILITY_AUDIT_SCHEMA = {
   type: "object",
-  required: ["total_issues", "critical", "important", "warning", "issues"],
+  required: ["measurable", "total_issues", "critical", "important", "warning", "issues"],
   properties: {
     scope: { type: "string" },
+    measurable: { type: "boolean" },
+    reason: { type: ["string", "null"] },
     elements_scanned: { type: "integer" },
     elements_skipped: { type: "integer" },
-    total_issues: { type: "integer" },
-    critical: { type: "integer" },
-    important: { type: "integer" },
-    warning: { type: "integer" },
+    reading_order_ok: { type: ["boolean", "null"] },
+    hints_present: { type: ["integer", "null"] },
+    total_issues: { type: ["integer", "null"] },
+    critical: { type: ["integer", "null"] },
+    important: { type: ["integer", "null"] },
+    warning: { type: ["integer", "null"] },
     issues: ISSUE_LIST,
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 86 tools: device automation (tap/swipe/type), accessibility audits, visual diff, crash logs, App Store / Play Store pre-submission compliance. Runs standalone over stdio with any MCP client.",
   "type": "module",
   "main": "index.js",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node --test tools/design-check/__tests__/design-check.test.mjs tools/design-check/__tests__/plan-determinism.test.mjs tools/ios-app-store-audit/__tests__/app-store-audit.test.mjs tools/ios-testflight/__tests__/testflight.test.mjs tools/ui-inspect/__tests__/ui-inspect.test.mjs tools/crash-logs/__tests__/crash-logs.test.mjs tools/launch-time/__tests__/launch-time.test.mjs tools/memory/__tests__/memory.test.mjs tools/offload/__tests__/offload.test.mjs __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
+    "test": "node --test tools/design-check/__tests__/design-check.test.mjs tools/design-check/__tests__/plan-determinism.test.mjs tools/ios-app-store-audit/__tests__/app-store-audit.test.mjs tools/ios-testflight/__tests__/testflight.test.mjs tools/ui-inspect/__tests__/ui-inspect.test.mjs tools/crash-logs/__tests__/crash-logs.test.mjs tools/a11y/__tests__/a11y.test.mjs tools/launch-time/__tests__/launch-time.test.mjs tools/memory/__tests__/memory.test.mjs tools/offload/__tests__/offload.test.mjs __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
     "gates": "bash scripts/gates.sh"
   },
   "keywords": [

package/tools/a11y/index.js

@@ -0,0 +1,335 @@
+/**
+ * a11y - accessibility audit scoring, split out of index.js so it can be tested.
+ *
+ * The audits used to return a full clean table for a tree they never read:
+ * `elements_scanned: 0, total_issues: 0, critical: 0, important: 0, warning: 0`.
+ * On iOS the tree comes from Simulator.app's host accessibility bridge, and that
+ * bridge stays empty until the Simulator window has been activated at least
+ * once, verified on a live simulator: 1 node before activation, 28 after. So
+ * "no issues" and "never looked" were the same answer, and the first is the one
+ * a reader believes.
+ *
+ * Every result therefore carries `measurable` and, when false, a `reason`. A
+ * result that could not be measured reports `totalIssues: null`, never 0.
+ */
+
+const IOS_INTERACTIVE_ROLES = new Set([
+  "AXButton",
+  "AXLink",
+  "AXTextField",
+  "AXTextArea",
+  "AXCheckBox",
+  "AXRadioButton",
+  "AXSlider",
+  "AXPopUpButton",
+  "AXMenuButton",
+  "AXSwitch",
+]);
+
+const IOS_MIN_TAP_PT = 44;
+const ANDROID_MIN_TAP_DP = 48;
+
+/**
+ * An accessibility tree with no children is not a screen without controls, it
+ * is a tree that was never populated. Callers must not score it.
+ *
+ * @param {object|null} tree - parsed ui-tree-dumper output
+ * @returns {boolean}
+ */
+export function isDegenerateTree(tree) {
+  if (!tree || typeof tree !== "object") return true;
+  if (tree.error) return true;
+  const kids = Array.isArray(tree.children) ? tree.children : [];
+  return kids.length === 0;
+}
+
+/**
+ * The device screen inside Simulator.app's window.
+ *
+ * The dumped window holds the simulator's own chrome as direct children -
+ * hardware buttons (Action, Volume Up, Sleep/Wake), the toolbar, the title
+ * text - and the iOS app underneath a single large AXGroup. Verified on a live
+ * simulator: seven chrome children beside one 402x873 AXGroup with the app in
+ * it. Auditing the window whole reports Apple's 17x35pt Volume button as an
+ * app tap-target violation, which is a false positive in exactly the place an
+ * accessibility report has to be trusted.
+ *
+ * @param {object} tree
+ * @returns {object|null} the screen subtree, or null when it cannot be found
+ */
+export function deviceScreenSubtree(tree) {
+  if (!tree || tree.role !== "AXWindow") return tree || null;
+  const groups = (tree.children || []).filter((c) => c && c.role === "AXGroup");
+  if (groups.length === 0) return null;
+  const area = (n) => (n.frame?.w || 0) * (n.frame?.h || 0);
+  return groups.reduce((best, c) => (area(c) > area(best) ? c : best), groups[0]);
+}
+
+/**
+ * Flatten the interactive elements in the order a screen reader would visit
+ * them, which is the order the accessibility tree presents them in.
+ *
+ * @param {object} node
+ * @param {Set<string>} roles
+ * @returns {object[]}
+ */
+function readingSequence(node, roles) {
+  const out = [];
+  const visit = (n) => {
+    if (!n || typeof n !== "object") return;
+    if (roles.has(n.role)) out.push(n);
+    (n.children || []).forEach(visit);
+  };
+  visit(node);
+  return out;
+}
+
+/**
+ * Group elements into visual rows.
+ *
+ * A screen is not a single top-to-bottom column. A home screen is a grid, a
+ * toolbar is a row, and comparing the reading order against a naive
+ * top-to-bottom sort reports every grid as broken. Two elements share a row
+ * when their vertical extents overlap by more than half the shorter one.
+ *
+ * @param {object[]} els
+ * @returns {object[][]} rows, top to bottom, each sorted left to right
+ */
+export function visualRows(els) {
+  const sorted = [...els].sort((a, b) => (a.frame?.y || 0) - (b.frame?.y || 0));
+  const rows = [];
+  for (const el of sorted) {
+    const y = el.frame?.y || 0;
+    const h = el.frame?.h || 0;
+    const row = rows.find((r) => {
+      const ry = r.top;
+      const rh = r.height;
+      const overlap = Math.min(y + h, ry + rh) - Math.max(y, ry);
+      return overlap > Math.min(h, rh) / 2;
+    });
+    if (row) {
+      row.items.push(el);
+      row.top = Math.min(row.top, y);
+      row.height = Math.max(row.height, h);
+    } else {
+      rows.push({ top: y, height: h, items: [el] });
+    }
+  }
+  return rows.map((r) => r.items.sort((a, b) => (a.frame?.x || 0) - (b.frame?.x || 0)));
+}
+
+/**
+ * Does the reading order follow the visual layout?
+ *
+ * The check is deliberately coarse: it compares the reading sequence against
+ * rows-then-columns, and reports the first element that arrives out of place.
+ * A screen can carry a deliberate reading order that differs from the visual
+ * one, so this is an `important` finding and never a `critical` one: it is a
+ * question worth asking, not a proven defect.
+ *
+ * @param {object[]} sequence - elements in reading order
+ * @param {boolean} rtl - right-to-left layout
+ * @returns {{ok: boolean, firstOutOfPlace: object|null, expectedIndex: number|null}}
+ */
+export function checkReadingOrder(sequence, rtl = false) {
+  if (sequence.length < 2) return { ok: true, firstOutOfPlace: null, expectedIndex: null };
+  const rows = visualRows(sequence);
+  const expected = rows.flatMap((r) => (rtl ? [...r].reverse() : r));
+  for (let i = 0; i < sequence.length; i++) {
+    if (sequence[i] !== expected[i]) {
+      return { ok: false, firstOutOfPlace: sequence[i], expectedIndex: expected.indexOf(sequence[i]) };
+    }
+  }
+  return { ok: true, firstOutOfPlace: null, expectedIndex: null };
+}
+
+/**
+ * @param {object} params
+ * @param {object|null} params.tree - parsed ui-tree-dumper output
+ * @param {string|null} [params.scope] - only audit identifiers with this prefix
+ * @returns {{measurable: boolean, reason: string|null, scope: string,
+ *            elementsScanned: number, elementsSkipped: number,
+ *            totalIssues: number|null, critical: number|null,
+ *            important: number|null, warning: number|null, issues: object[]}}
+ */
+export function auditIosTree({ tree, scope = null, rtl = false }) {
+  if (isDegenerateTree(tree)) {
+    return unmeasurable(
+      scope,
+      tree && tree.error
+        ? String(tree.error)
+        : "the accessibility tree came back empty; open Simulator.app and bring its window to the front, then retry - the host bridge does not populate until the window has been activated once",
+    );
+  }
+
+  const screen = deviceScreenSubtree(tree);
+  if (!screen) {
+    return unmeasurable(
+      scope,
+      "the window held no device screen group; the simulator may still be starting up",
+    );
+  }
+
+  const issues = [];
+  let elementsScanned = 0;
+  let elementsSkipped = 0;
+  const sequence = [];
+
+  const visit = (node, path = "") => {
+    if (!node || typeof node !== "object") return;
+    const loc = path ? `${path} > ${node.role}` : node.role;
+    const w = node.frame?.w || 0;
+    const h = node.frame?.h || 0;
+
+    if (IOS_INTERACTIVE_ROLES.has(node.role)) {
+      if (scope && node.identifier && !node.identifier.startsWith(scope)) {
+        elementsSkipped++;
+        (node.children || []).forEach((c) => visit(c, loc));
+        return;
+      }
+      elementsScanned++;
+      sequence.push(node);
+      // What a screen reader announces the element AS. Without it a control is
+      // read out as bare text and the user cannot tell it is actionable.
+      if (!node.roleDescription) {
+        issues.push({ severity: "important", issue: "No role announced (VoiceOver cannot say what this control is)", element: loc, identifier: node.identifier || null });
+      }
+      if (!node.title && !node.description && !node.value) {
+        issues.push({ severity: "critical", issue: "Missing accessibility label", element: loc, identifier: node.identifier || null });
+      }
+      if (!node.identifier) {
+        issues.push({ severity: "warning", issue: "Missing accessibility identifier (UI testing)", element: loc });
+      }
+      if (w > 0 && h > 0 && (w < IOS_MIN_TAP_PT || h < IOS_MIN_TAP_PT)) {
+        issues.push({ severity: "important", issue: `Tap target too small: ${Math.round(w)}x${Math.round(h)}pt (min ${IOS_MIN_TAP_PT}x${IOS_MIN_TAP_PT})`, element: loc, identifier: node.identifier || null });
+      }
+    }
+    (node.children || []).forEach((c) => visit(c, loc));
+  };
+  visit(screen);
+
+  // A populated window whose interactive elements were all filtered out is a
+  // scope that matched nothing, not a clean screen.
+  if (elementsScanned === 0) {
+    return unmeasurable(
+      scope,
+      scope
+        ? `no interactive element matched scope "${scope}"`
+        : "the tree was readable but held no interactive elements to audit",
+      elementsSkipped,
+    );
+  }
+
+  const order = checkReadingOrder(sequence, rtl);
+  if (!order.ok) {
+    const el = order.firstOutOfPlace;
+    issues.push({
+      severity: "important",
+      issue: `Reading order does not follow the visual layout: this element is read at position ${sequence.indexOf(el) + 1} but sits at position ${order.expectedIndex + 1} on screen`,
+      element: el.role,
+      identifier: el.identifier || null,
+      label: el.title || el.description || el.value || null,
+    });
+  }
+
+  return {
+    measurable: true,
+    reason: null,
+    scope: scope || "all",
+    elementsScanned,
+    elementsSkipped,
+    readingOrderOk: order.ok,
+    hintsPresent: sequence.filter((n) => n.help).length,
+    ...tally(issues),
+  };
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.xml - uiautomator dump output
+ * @param {string|null} [params.scope] - only audit resource-ids containing this
+ * @returns {object} same shape as auditIosTree
+ */
+export function auditAndroidDump({ xml, scope = null }) {
+  const text = typeof xml === "string" ? xml : "";
+  if (!/<node\b/.test(text)) {
+    return unmeasurable(scope, "the uiautomator dump held no nodes; the dump failed or the screen was not ready");
+  }
+
+  const issues = [];
+  let elementsScanned = 0;
+  let elementsSkipped = 0;
+
+  for (const match of text.matchAll(/<node[^>]*>/g)) {
+    const node = match[0];
+    const attr = (name) => node.match(new RegExp(`${name}="([^"]*)"`))?.[1] || "";
+    if (!node.includes('clickable="true"')) continue;
+
+    const cls = attr("class");
+    const desc = attr("content-desc");
+    const rid = attr("resource-id");
+    const label = attr("text");
+
+    if (scope && rid && !rid.includes(scope)) {
+      elementsSkipped++;
+      continue;
+    }
+    elementsScanned++;
+
+    if (!desc && !label) issues.push({ severity: "critical", issue: "Missing contentDescription", element: cls, resourceId: rid || null });
+    if (!rid) issues.push({ severity: "warning", issue: "Missing resource-id (UI testing)", element: cls });
+
+    const bounds = node.match(/bounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/);
+    if (bounds) {
+      const w = parseInt(bounds[3], 10) - parseInt(bounds[1], 10);
+      const h = parseInt(bounds[4], 10) - parseInt(bounds[2], 10);
+      if (w < ANDROID_MIN_TAP_DP || h < ANDROID_MIN_TAP_DP) {
+        issues.push({ severity: "important", issue: `Touch target too small: ${w}x${h}dp (min ${ANDROID_MIN_TAP_DP}x${ANDROID_MIN_TAP_DP})`, element: cls, resourceId: rid || null });
+      }
+    }
+  }
+
+  if (elementsScanned === 0) {
+    return unmeasurable(
+      scope,
+      scope ? `no clickable element matched scope "${scope}"` : "the dump was readable but held no clickable elements to audit",
+      elementsSkipped,
+    );
+  }
+
+  return {
+    measurable: true,
+    reason: null,
+    scope: scope || "all",
+    elementsScanned,
+    elementsSkipped,
+    ...tally(issues),
+  };
+}
+
+function tally(issues) {
+  const by = (s) => issues.filter((i) => i.severity === s).length;
+  return {
+    totalIssues: issues.length,
+    critical: by("critical"),
+    important: by("important"),
+    warning: by("warning"),
+    issues,
+  };
+}
+
+function unmeasurable(scope, reason, elementsSkipped = 0) {
+  return {
+    measurable: false,
+    reason,
+    scope: scope || "all",
+    elementsScanned: 0,
+    elementsSkipped,
+    // null rather than 0: a count of zero is a measurement, and none was taken.
+    totalIssues: null,
+    critical: null,
+    important: null,
+    warning: null,
+    issues: [],
+  };
+}

package/ui-tree-dumper.swift

@@ -9,6 +9,12 @@ import Foundation
 
 struct AXNode: Codable {
     let role: String
+    // What a screen reader announces the element AS. Probed on a live simulator:
+    // AXRoleDescription carries "button" and friends, AXSubrole carries nothing
+    // at all through this bridge, so only the former is read.
+    let roleDescription: String?
+    // The iOS accessibilityHint bridges to AXHelp ("Double tap to open").
+    let help: String?
     let title: String?
     let value: String?
     let description: String?
@@ -53,6 +59,8 @@ func dumpElement(_ element: AXUIElement, depth: Int, maxDepth: Int) -> AXNode? {
     let value = getString(element, kAXValueAttribute)
     let desc = getString(element, kAXDescriptionAttribute)
     let identifier = getString(element, kAXIdentifierAttribute)
+    let roleDescription = getString(element, "AXRoleDescription")
+    let help = getString(element, "AXHelp")
     let enabled = getBool(element, kAXEnabledAttribute)
     let focused = getBool(element, kAXFocusedAttribute)
     let frame = getFrame(element)
@@ -75,6 +83,8 @@ func dumpElement(_ element: AXUIElement, depth: Int, maxDepth: Int) -> AXNode? {
 
     return AXNode(
         role: role,
+        roleDescription: roleDescription,
+        help: help,
         title: title,
         value: value,
         description: desc,
@@ -86,10 +96,22 @@ func dumpElement(_ element: AXUIElement, depth: Int, maxDepth: Int) -> AXNode? {
     )
 }
 
+// The host accessibility bridge does not populate the iOS app's elements until
+// the Simulator window has been activated at least once. Measured on a live
+// simulator: 1 node before activation, 28 after, and it stays populated once
+// the window has been backgrounded again. Without this the tree comes back
+// holding only the window, which reads as a screen with no controls.
+func activateSimulator(_ app: NSRunningApplication) {
+    if app.isActive { return }
+    app.activate(options: [])
+    Thread.sleep(forTimeInterval: 1.2)
+}
+
 func findSimulatorWindow() -> AXUIElement? {
     let apps = NSWorkspace.shared.runningApplications
     for app in apps {
         if app.bundleIdentifier == "com.apple.iphonesimulator" {
+            activateSimulator(app)
             let axApp = AXUIElementCreateApplication(app.processIdentifier)
             var windows: AnyObject?
             AXUIElementCopyAttributeValue(axApp, kAXWindowsAttribute as CFString, &windows)
@@ -105,7 +127,7 @@ func findSimulatorWindow() -> AXUIElement? {
 let maxDepth = CommandLine.arguments.count > 1 ? Int(CommandLine.arguments[1]) ?? 10 : 10
 
 guard let simWindow = findSimulatorWindow() else {
-    let error = ["error": "Simulator not running or no window found"]
+    let error = ["error": "Simulator.app is not running or has no window. Booting a device with simctl is not enough - the accessibility bridge lives in the Simulator UI app. Run: open -a Simulator"]
     let data = try! JSONSerialization.data(withJSONObject: error)
     FileHandle.standardOutput.write(data)
     exit(1)