mobile-debug-mcp 0.32.1 → 0.32.4

package/skills/mobile-debug-tools-usage/SKILL.md

@@ -1,35 +1,55 @@
 ---
 name: mobile-debug-mcp
-description: Verify Android app behaviour efficiently with mobile-debug MCP, especially session playback, background work, and notifications. Use for emulator/device QA; do not use for implementation-only checks.
+description: Use mobile-debug MCP to inspect, interact with, and verify any Android or iOS app on a device or emulator.
 metadata:
-  author: modul8-team
-  version: "1.0"
+  author: mobile-debug-mcp contributors
+  version: "1.1"
 ---
 
-# Mobile-debug MCP verification
+# Mobile-debug MCP usage
 
-Use mobile-debug MCP to make a product claim observable on a real device or emulator. A successful tap proves only that the input was delivered; verify the resulting UI, notification, or persisted state before reporting success.
+Use mobile-debug MCP when a task needs evidence from a running Android or iOS app. Identify the device and the state or behaviour to check, then choose the smallest observation or action that can establish it. A successful tool call confirms only what that tool reports; check the resulting app state before claiming an outcome.
 
 ## Choose the lightest evidence that proves the claim
 
-- Use an accessibility assertion such as `expect_element_visible` or
-  `wait_for_ui` for an accessible label, enabled state, or changed control.
-- Use a screenshot when visual layout, system UI, or notification content matters.
-- Use a debug snapshot only when the screen does not explain a failed action or an accessibility-tree assertion is needed.
-- Use Android shell commands only for device navigation or system surfaces that MCP cannot expose. Do not treat shell output as proof of user-visible behaviour.
+- Prefer a screenshot for routine visual navigation, layout checks, and visible
+  outcomes that can be established from the image.
+- Use UI-tree reads and accessibility assertions such as `expect_element_visible`,
+  `expect_state`, or `wait_for_ui` when reliable element selection or a structured
+  property check is required. An image alone does not establish accessibility
+  properties such as enabled state.
+- Use a debug snapshot when an ordinary observation does not explain a failure or multiple kinds of evidence are needed together.
+- Use logs or network activity for claims about errors or requests. Correlate them with the relevant action and time window; they do not establish what the user saw.
+- Use platform shell commands only for device or system operations that the MCP tools cannot expose. Treat shell output as evidence of that operation, not of the app's visible state.
 
-Avoid repeated screenshots and snapshots when a targeted accessibility assertion is enough.
+Choose one observation that proves the required outcome. Avoid automatically
+reading the UI tree after a screenshot or taking a screenshot after a sufficient
+structured assertion.
+
+## Keep Android inspection APK-free
+
+Use the standard ADB path for Android inspection. It requires no helper APK.
+The normal hierarchy dump
+can take several seconds; account for this rather than treating it as a fast
+poll. Compressed dumps can omit nodes and should not be assumed faster.
 
 ## Keep interaction fast
 
 Treat each MCP call as a round trip and use the fastest path that still proves
-the behaviour. Prefer the following sequence:
+the behaviour. For an interaction, prefer this sequence:
 
-1. Wait for one stable, uniquely identifiable control.
-2. Tap its returned element id.
-3. Wait for the specific resulting state.
+1. Observe the current screen or wait for a uniquely identifiable target if its presence is uncertain.
+2. Perform the requested action using a stable selector or element id when available.
+3. Check the specific resulting state once it has had time to occur.
 
-Do not wait before every tap when the current screen and element id are already known. Do not poll unchanged screens. Use short timeouts for ordinary controls; reserve longer waits for known asynchronous work such as model initialisation or network calls.
+Do not wait before every action when its target and current state are already
+known. Do not poll unchanged screens. Set bounded assertion timeouts that cover
+the expected app transition plus a complete fresh observation and a margin.
+For Android ADB tree reads taking 2–3 seconds, start with a 5-second timeout for
+a simple assertion; allow more when loading or repeated observations are
+required. A 2-second timeout cannot reliably accommodate a 3-second tree read.
+Adjust to measured device latency and supported tool limits. Report an
+observation timeout separately from evidence that a control is absent.
 
 Use compact responses for routine actions. If action dispatch is reliable but
 verification is slow or unavailable, dispatch with verification disabled and
@@ -37,11 +57,12 @@ verify at meaningful checkpoints with one focused accessibility assertion or
 screenshot. Do not assume `light` verification is faster: use it only when it
 has returned useful results reliably on the current MCP version and device.
 
-Prefer a stable element selector when the accessibility tree exposes one. Use
-coordinates only when needed, and take a fresh screenshot immediately before a
-coordinate tap on system UI, notifications, or any screen where layout may have
-changed. Never reuse coordinates after expanding/collapsing a notification,
-changing orientation, or switching screens.
+Prefer a stable element selector when it is already known and valid. For a
+clearly identifiable visual target, use coordinates from a fresh screenshot
+without requiring a tree read solely to rediscover it. If the target is
+ambiguous or a semantic check is required, resolve it from the hierarchy.
+Reacquire coordinates after scrolling,
+changing orientation, switching screens, or opening a system surface.
 
 Element discovery can be the slowest part of a journey. Avoid repeated
 `find_element` calls for the same screen: resolve a control once, use the
@@ -55,20 +76,21 @@ express the needed observable checks and it returns enough evidence to report
 the outcome. Measure the whole journey and compare equivalent steps on the same
 device; do not infer a performance improvement from a single fast action.
 
-## Session playback checks
-
-For a claimed playback start, observe a running timer or Pause state after Play. For a claimed pause, observe Resume and unchanged elapsed time. For a claimed stop, observe that playback ends and the notification disappears.
+## Match the evidence to the claim
 
-For background playback, press Home, open the notification shade, and verify
-the notification title, progress/status, and available actions. Expand the
-session notification if necessary, then capture its current layout before
-tapping an action. Exercise each action needed for the change and observe its
-result: Pause becomes Resume; Resume returns to active playback; Stop ends
-playback and clears the notification. After each action, reacquire the current
-screen state before using another coordinate.
+For a state change, check the state after the action rather than inferring it
+from successful dispatch. For an asynchronous update, start a fresh observation
+after the relevant event and wait for the expected condition within a bounded
+timeout. If an accessibility tree appears stale or incomplete, use another
+appropriate observation such as a screenshot and report the discrepancy.
 
-Do not claim spoken guidance was verified unless audio output was actually inspected. A running timer or active notification verifies playback state, not audible wording.
+For behaviour outside the app's foreground screen, inspect the relevant system
+surface or device state. For content that cannot be established visually, such
+as audio output, use a suitable direct check or state that it was not verified.
 
 ## Report evidence precisely
 
-State the device journey, observed result, and any untested scope. Mention whether evidence came from an accessibility assertion, screenshot, or system notification. Do not say a feature works solely because the build compiled or an MCP action returned success.
+State the device, actions taken, observed result, evidence source, and any
+untested scope. Distinguish an observed outcome from an inference. Do not say
+a feature works solely because the build compiled or an MCP action returned
+success.

package/skills/spec-review/SKILL.md

@@ -49,4 +49,4 @@ Activate when an agent needs to:
 - `references/spec-review-checklist.md` — questions to apply while reviewing a spec
 
 # License
-Same as repository (MIT).
+Same as repository (Apache-2.0).

package/skills/test-authoring/SKILL.md

@@ -54,4 +54,4 @@ Activate when an agent needs to:
 - `references/test-quality-checklist.md` — what a good test in this repo should prove before it is considered done
 
 # License
-Same as repository (MIT).
+Same as repository (Apache-2.0).

package/src/observe/android.ts

@@ -10,7 +10,6 @@ import { parsePngSize } from "../utils/image.js"
 import { deriveSnapshotMetadata } from "./snapshot-metadata.js"
 import { remainingBudget } from '../utils/operation-budget.js'
 import { createObservationMeasurement } from './performance-metrics.js'
-import { androidTreeBridgeEnabled, readAndroidTreeFromBridge } from './android-tree-bridge.js'
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
@@ -54,19 +53,7 @@ export class AndroidObserve {
            }
            remainingBudget()
 
-           let bridgeContent: string | null = null
-           if (androidTreeBridgeEnabled()) {
-             try {
-               bridgeContent = await measurement.physicalRead(async () => {
-                 const content = await readAndroidTreeFromBridge(deviceInfo.id)
-                 if (!content) throw new Error('Android UI tree bridge unavailable')
-                 return content
-               })
-             } catch (error) {
-               if (error instanceof Error && (error.message === 'ACTION_TIMEOUT' || error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))) throw error
-             }
-           }
-           xmlContent = bridgeContent ?? await measurement.physicalRead(async () => {
+           xmlContent = await measurement.physicalRead(async () => {
              await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId)
              const content = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId)
              if (!content || !content.trim() || content.includes('ERROR:')) throw new Error('Empty or invalid UI dump')
@@ -74,7 +61,7 @@ export class AndroidObserve {
            })
            break
         } catch (e) {
-           if (e instanceof Error && (e.message === 'ACTION_TIMEOUT' || e.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))) throw e
+           if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
            console.error(`Attempt ${attempts} failed: ${e}`);
         }
         

package/src/server-core.ts

@@ -16,7 +16,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.32.1'
+  version: '0.32.4'
 }
 
 export function createServer() {

package/test/fixtures/latency-journey-app/src/MainActivity.java

@@ -2,7 +2,12 @@ package dev.mobiledebugmcp.latencyfixture;
 
 import android.app.Activity;
 import android.content.Intent;
+import android.graphics.Canvas;
+import android.graphics.Color;
+import android.graphics.Paint;
 import android.os.Bundle;
+import android.view.View;
+import android.view.accessibility.AccessibilityNodeInfo;
 import android.widget.Button;
 import android.widget.LinearLayout;
 import android.widget.TextView;
@@ -30,9 +35,35 @@ public final class MainActivity extends Activity {
         super.onCreate(state);
         String networkBaseUrl = getIntent().getStringExtra("networkBaseUrl");
         String networkRunId = getIntent().getStringExtra("networkRunId");
-        if (networkBaseUrl != null && networkRunId != null) networkScreen(networkBaseUrl, networkRunId);
+        if (getIntent().getBooleanExtra("silentTimer", false)) silentTimerScreen();
+        else if (networkBaseUrl != null && networkRunId != null) networkScreen(networkBaseUrl, networkRunId);
         else home();
     }
+    private void silentTimerScreen() {
+        layout = new LinearLayout(this);
+        layout.setPadding(32, 100, 32, 32);
+        setContentView(layout);
+        SilentTimerView timer = new SilentTimerView();
+        layout.addView(timer, new LinearLayout.LayoutParams(-1, 200));
+        timer.postDelayed(() -> timer.setValue("0:01"), 2000);
+    }
+    private final class SilentTimerView extends View {
+        private final Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
+        private String value = "0:00";
+        SilentTimerView() {
+            super(MainActivity.this);
+            setImportantForAccessibility(IMPORTANT_FOR_ACCESSIBILITY_YES);
+            paint.setColor(Color.BLACK);
+            paint.setTextSize(72);
+        }
+        // Deliberately redraw without an accessibility event to expose stale node caches.
+        void setValue(String next) { value = next; invalidate(); }
+        @Override protected void onDraw(Canvas canvas) { canvas.drawText(value, 20, 110, paint); }
+        @Override public void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) {
+            super.onInitializeAccessibilityNodeInfo(info);
+            info.setContentDescription("silent timer " + value);
+        }
+    }
     private void networkScreen(String baseUrl, String runId) {
         layout = new LinearLayout(this);
         layout.setOrientation(LinearLayout.VERTICAL);

package/test/unit/observe/android_tree_acquisition.test.ts

@@ -11,6 +11,7 @@ async function run() {
   const adbPath = path.join(directory, 'adb')
   const previousAdb = process.env.ADB_PATH
   const previousMetrics = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
+  const previousBridgeApk = process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK
   const previousFailure = process.env.MCP_FAKE_ADB_FAIL
   const previousWrite = process.stderr.write
   const lines: string[] = []
@@ -27,6 +28,7 @@ else process.exit(1)
   chmodSync(adbPath, 0o755)
   process.env.ADB_PATH = adbPath
   process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = '1'
+  process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK = path.join(directory, 'missing-bridge.apk')
   ;(process.stderr as any).write = (chunk: string) => { lines.push(chunk); return true }
   resetSnapshotMetadataForTests()
   try {
@@ -60,6 +62,8 @@ else process.exit(1)
     else process.env.ADB_PATH = previousAdb
     if (previousMetrics === undefined) delete process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
     else process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = previousMetrics
+    if (previousBridgeApk === undefined) delete process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK
+    else process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK = previousBridgeApk
     if (previousFailure === undefined) delete process.env.MCP_FAKE_ADB_FAIL
     else process.env.MCP_FAKE_ADB_FAIL = previousFailure
     rmSync(directory, { recursive: true, force: true })

package/test/unit/observe/ios-getlogs.test.ts

@@ -9,9 +9,9 @@ function stubExecCommand(expectedArgsChecker: (args: string[]) => boolean, outpu
 }
 
 async function run() {
-  const bundle = 'com.ideamechanics.modul8'
+  const bundle = 'com.example.sampleapp'
   const pgrepOutput = '12345\n'
-  const logOutput = '2026-03-31 09:21:20.085 Module[12345:678] <Info> Modul8: Test message'
+  const logOutput = '2026-03-31 09:21:20.085 SampleApp[12345:678] <Info> SampleApp: Test message'
 
   try {
     const obs = new iOSObserve()
@@ -28,7 +28,7 @@ async function run() {
     })
 
     const pidResult = await obs.getLogs({ appId: bundle, deviceId: 'booted' })
-    assert(pidResult.meta.processNameUsed === 'modul8' || pidResult.meta.processNameUsed === 'Modul8' || !!pidResult.meta.processNameUsed)
+    assert(pidResult.meta.processNameUsed === 'sampleapp')
     assert(pidResult.meta.detectedPid === 12345)
     assert(pidResult.source === 'pid')
     assert(pidResult.logCount === 1)

package/src/observe/android-tree-bridge.ts

@@ -1,170 +0,0 @@
-import { execFile, spawn, spawnSync, type ChildProcess } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { connect } from 'node:net'
-import path from 'node:path'
-import { execAdb, getAdbCmd } from '../utils/android/utils.js'
-import { remainingBudget } from '../utils/operation-budget.js'
-
-const packageName = 'dev.mobiledebugmcp.treebridge'
-const component = `${packageName}/.TreeInstrumentation`
-const devicePort = 39019
-
-interface Bridge {
-  deviceId: string
-  hostPort: number
-  child: ChildProcess
-  closed: boolean
-  childClosed: boolean
-}
-
-const active = new Map<string, Bridge>()
-const starting = new Map<string, Promise<Bridge>>()
-const stopping = new Map<string, Promise<void>>()
-
-export function androidTreeBridgeEnabled(): boolean {
-  return Boolean(process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK)
-}
-
-function configuredApk() {
-  const configured = process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK
-  if (!configured) return null
-  const apk = path.resolve(configured)
-  if (!existsSync(apk)) throw new Error(`Android UI tree bridge APK does not exist: ${apk}`)
-  return apk
-}
-
-function unbudgetedAdb(deviceId: string, args: string[]): Promise<void> {
-  return new Promise((resolve, reject) => {
-    execFile(getAdbCmd(), ['-s', deviceId, ...args], { timeout: 5000 }, (error) => error ? reject(error) : resolve())
-  })
-}
-
-function request(bridge: Bridge, command: 'PING' | 'TREE' | 'STOP', timeoutMs: number): Promise<string> {
-  return new Promise((resolve, reject) => {
-    let output = ''
-    const socket = connect(bridge.hostPort, '127.0.0.1', () => socket.write(`${command}\n`))
-    socket.setTimeout(timeoutMs, () => socket.destroy(new Error(`Android UI tree bridge ${command} timed out`)))
-    socket.on('data', (chunk) => {
-      output += chunk.toString()
-      if (command === 'STOP' && output.startsWith('OK\n')) {
-        resolve(output)
-        socket.destroy()
-      }
-    })
-    socket.on('error', reject)
-    socket.on('end', () => resolve(output))
-  })
-}
-
-function waitForChildClose(bridge: Bridge, timeoutMs: number): Promise<void> {
-  if (bridge.childClosed) return Promise.resolve()
-  return new Promise((resolve, reject) => {
-    const onClose = () => { clearTimeout(timer); resolve() }
-    const timer = setTimeout(() => {
-      bridge.child.off('close', onClose)
-      reject(new Error('Android UI tree bridge child did not exit'))
-    }, timeoutMs)
-    bridge.child.once('close', onClose)
-  })
-}
-
-async function stop(bridge: Bridge): Promise<void> {
-  const pending = stopping.get(bridge.deviceId)
-  if (pending) return pending
-  bridge.closed = true
-  const cleanup = (async () => {
-    await request(bridge, 'STOP', 1000).catch(() => '')
-    let forceStopError: unknown
-    try { await unbudgetedAdb(bridge.deviceId, ['shell', 'am', 'force-stop', packageName]) }
-    catch (error) { forceStopError = error }
-    try { await waitForChildClose(bridge, 1000) }
-    catch {
-      bridge.child.kill('SIGTERM')
-      try { await waitForChildClose(bridge, 1000) }
-      catch {
-        bridge.child.kill('SIGKILL')
-        await waitForChildClose(bridge, 2000).catch(() => {})
-      }
-    }
-    let forwardError: unknown
-    try { await unbudgetedAdb(bridge.deviceId, ['forward', '--remove', `tcp:${bridge.hostPort}`]) }
-    catch (error) { forwardError = error }
-    if (forceStopError || !bridge.childClosed || forwardError) {
-      const reason = forceStopError ?? (!bridge.childClosed ? 'instrumentation child did not close' : forwardError)
-      throw new Error(`BRIDGE_CLEANUP_UNCONFIRMED: ${reason instanceof Error ? reason.message : String(reason)}`)
-    }
-    if (active.get(bridge.deviceId) === bridge) active.delete(bridge.deviceId)
-  })()
-  stopping.set(bridge.deviceId, cleanup)
-  try { await cleanup } finally { stopping.delete(bridge.deviceId) }
-}
-
-async function launch(deviceId: string, apk: string): Promise<Bridge> {
-  await unbudgetedAdb(deviceId, ['shell', 'am', 'force-stop', packageName])
-  try {
-    await execAdb(['install', '-r', apk], deviceId)
-  } catch (error) {
-    if (!(error instanceof Error) || !error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE')) throw error
-    await execAdb(['uninstall', packageName], deviceId)
-    await execAdb(['install', '-r', apk], deviceId)
-  }
-  const hostPort = Number(await execAdb(['forward', 'tcp:0', `tcp:${devicePort}`], deviceId))
-  if (!Number.isInteger(hostPort) || hostPort <= 0) throw new Error('Android UI tree bridge could not obtain a host port')
-  const child = spawn(getAdbCmd(), ['-s', deviceId, 'shell', 'am', 'instrument', '-w', component], { stdio: 'ignore' })
-  const bridge: Bridge = { deviceId, hostPort, child, closed: false, childClosed: false }
-  child.once('close', () => { bridge.childClosed = true })
-  child.once('error', () => { /* Startup detects the failed child before a tree read. */ })
-  active.set(deviceId, bridge)
-  try {
-    const deadline = Date.now() + Math.min(remainingBudget(3000), 3000)
-    while (Date.now() < deadline) {
-      if (bridge.childClosed || child.exitCode !== null || child.signalCode !== null) throw new Error('Android UI tree bridge exited during startup')
-      try {
-        if ((await request(bridge, 'PING', 250)).startsWith('OK\n')) {
-          return bridge
-        }
-      } catch { /* The instrumentation process may still be starting. */ }
-      await new Promise((resolve) => setTimeout(resolve, 100))
-    }
-    throw new Error('Android UI tree bridge did not become ready')
-  } catch (error) {
-    await stop(bridge)
-    throw error
-  }
-}
-
-async function ensure(deviceId: string, apk: string): Promise<Bridge> {
-  const pending = starting.get(deviceId)
-  if (pending) return pending
-  const ready = active.get(deviceId)
-  if (ready && !ready.closed && !ready.childClosed && ready.child.exitCode === null && ready.child.signalCode === null) return ready
-  if (ready) await stop(ready)
-  const promise = launch(deviceId, apk)
-  starting.set(deviceId, promise)
-  try { return await promise } finally { starting.delete(deviceId) }
-}
-
-/** Returns null only after the bridge has been stopped, so legacy acquisition is safe. */
-export async function readAndroidTreeFromBridge(deviceId: string): Promise<string | null> {
-  const apk = configuredApk()
-  if (!apk) return null
-  let bridge: Bridge | undefined
-  try {
-    bridge = await ensure(deviceId, apk)
-    const output = await request(bridge, 'TREE', remainingBudget(10000))
-    if (!output.startsWith('OK\n') || !output.includes('<hierarchy')) throw new Error('Android UI tree bridge returned invalid hierarchy output')
-    return output.slice(3)
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED')) throw error
-    if (bridge) await stop(bridge)
-    if (error instanceof Error && error.message === 'ACTION_TIMEOUT') throw error
-    return null
-  }
-}
-
-process.once('exit', () => {
-  for (const bridge of active.values()) {
-    spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'shell', 'am', 'force-stop', packageName], { timeout: 2000, stdio: 'ignore' })
-    spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'forward', '--remove', `tcp:${bridge.hostPort}`], { timeout: 2000, stdio: 'ignore' })
-  }
-})

package/test/device/automated/ui-tree-performance/bridge-probe.ts

@@ -1,183 +0,0 @@
-import { execFileSync, spawn, type ChildProcess } from 'node:child_process'
-import { createServer } from 'node:http'
-import { connect } from 'node:net'
-import { mkdirSync, writeFileSync } from 'node:fs'
-import path from 'node:path'
-import { randomUUID } from 'node:crypto'
-import { XMLParser } from 'fast-xml-parser'
-import { buildBridge } from '../../../fixtures/ui-tree-bridge/build.js'
-import { buildFixture } from '../../../fixtures/latency-journey-app/build.js'
-import { summarize } from '../latency/report.js'
-
-const deviceId = process.env.LATENCY_DEVICE_ID ?? ''
-if (!deviceId) throw new Error('Set LATENCY_DEVICE_ID to one Android emulator')
-const bridgePackage = 'dev.mobiledebugmcp.treebridge'
-const fixturePackage = 'dev.mobiledebugmcp.latencyfixture'
-const hostPort = 39020
-const devicePort = 39019
-const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_' })
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
-const elapsedMs = (start: bigint) => Number(process.hrtime.bigint() - start) / 1e6
-const adb = (...args: string[]) => execFileSync('adb', ['-s', deviceId!, ...args], { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] }).trim()
-
-function install(apk: string, appId: string) {
-  try { adb('install', '-r', apk) }
-  catch (error) {
-    if (!(error instanceof Error) || !error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE')) throw error
-    adb('uninstall', appId)
-    adb('install', '-r', apk)
-  }
-}
-
-function nodes(xml: string): Array<Record<string, string>> {
-  const tree = parser.parse(xml)
-  const result: Array<Record<string, string>> = []
-  const visit = (item: any) => {
-    if (!item) return
-    if (Array.isArray(item)) return item.forEach(visit)
-    if (item['@_class']) result.push(item)
-    visit(item.node)
-  }
-  visit(tree.hierarchy)
-  return result
-}
-
-function bridgeRead(): Promise<{ xml: string; elapsed_ms: number; started_ns: bigint }> {
-  const started_ns = process.hrtime.bigint()
-  return new Promise((resolve, reject) => {
-    let output = ''
-    const socket = connect(hostPort, '127.0.0.1', () => socket.write('TREE\n'))
-    socket.setTimeout(10000, () => socket.destroy(new Error('Bridge read timed out')))
-    socket.on('data', (chunk) => { output += chunk.toString() })
-    socket.on('error', reject)
-    socket.on('end', () => {
-      if (!output.startsWith('OK\n') || !output.includes('<hierarchy')) return reject(new Error(`Bridge response failed: ${output.slice(0, 80)}`))
-      resolve({ xml: output.slice(3), elapsed_ms: elapsedMs(started_ns), started_ns })
-    })
-  })
-}
-
-async function readyBridge() {
-  const deadline = Date.now() + 10000
-  while (Date.now() < deadline) {
-    try { return await bridgeRead() } catch { await sleep(100) }
-  }
-  throw new Error('Bridge did not become ready')
-}
-
-async function stopBridge() {
-  await new Promise<void>((resolve, reject) => {
-    const socket = connect(hostPort, '127.0.0.1', () => socket.write('STOP\n'))
-    socket.setTimeout(5000, () => socket.destroy(new Error('Bridge stop timed out')))
-    socket.on('error', reject)
-    socket.on('data', (chunk) => {
-      if (chunk.toString().startsWith('OK\n')) {
-        socket.destroy()
-        resolve()
-      }
-    })
-  })
-}
-
-async function main() {
-  const bridgeApk = buildBridge()
-  const fixtureApk = buildFixture()
-  install(bridgeApk, bridgePackage)
-  install(fixtureApk, fixturePackage)
-  const runId = randomUUID()
-  let releaseResponse!: () => void
-  let requestSeen!: () => void
-  let responseSentNs = 0n
-  const requestPromise = new Promise<void>((resolve) => { requestSeen = resolve })
-  const releasePromise = new Promise<void>((resolve) => { releaseResponse = resolve })
-  const server = createServer(async (request, response) => {
-    const url = new URL(request.url ?? '/', 'http://localhost')
-    if (url.pathname !== '/data' || url.searchParams.get('run_id') !== runId) return response.writeHead(404).end()
-    requestSeen()
-    await releasePromise
-    await sleep(100)
-    responseSentNs = process.hrtime.bigint()
-    response.writeHead(200, { 'content-type': 'text/plain', 'cache-control': 'no-store' }).end(`${runId}|value-${runId}`)
-  })
-  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(0, '0.0.0.0', resolve) })
-  const address = server.address()
-  if (!address || typeof address === 'string') throw new Error('Fixture server did not bind')
-  const instrumentation: ChildProcess = spawn('adb', ['-s', deviceId, 'shell', 'am', 'instrument', '-w', `${bridgePackage}/.TreeInstrumentation`], { stdio: ['ignore', 'pipe', 'pipe'] })
-  let bridgeStarted = false
-  let forwarded = false
-  try {
-    adb('forward', `tcp:${hostPort}`, `tcp:${devicePort}`)
-    forwarded = true
-    await readyBridge()
-    bridgeStarted = true
-    adb('shell', 'am', 'force-stop', fixturePackage)
-    adb('shell', 'pm', 'clear', fixturePackage)
-    adb('shell', 'am', 'start', '-n', `${fixturePackage}/.MainActivity`, '--es', 'networkBaseUrl', `http://10.0.2.2:${address.port}`, '--es', 'networkRunId', runId)
-    await Promise.race([requestPromise, sleep(10000).then(() => { throw new Error('Fixture request timed out') })])
-    const loadingDeadline = Date.now() + 10000
-    let loadingOnly = false
-    while (Date.now() < loadingDeadline) {
-      const tree = nodes((await bridgeRead()).xml)
-      loadingOnly = tree.some((node) => node['@_content-desc'] === 'loading') && !tree.some((node) => node['@_content-desc'] === 'ready' || node['@_content-desc'] === 'value')
-      if (loadingOnly) break
-      await sleep(50)
-    }
-    if (!loadingOnly) throw new Error('Bridge did not observe loading-only state')
-    releaseResponse()
-    while (!responseSentNs) await sleep(10)
-    const readyDeadline = Date.now() + 10000
-    let readyRead: Awaited<ReturnType<typeof bridgeRead>> | undefined
-    while (Date.now() < readyDeadline) {
-      const read = await bridgeRead()
-      const tree = nodes(read.xml)
-      if (tree.some((node) => node['@_content-desc'] === 'ready') && tree.some((node) => node['@_content-desc'] === 'value' && node['@_text'] === `value-${runId}`)) {
-        readyRead = read
-        break
-      }
-      await sleep(50)
-    }
-    if (!readyRead || readyRead.started_ns <= responseSentNs) throw new Error('Bridge ready/value assertion was not based on a post-response read')
-    const bridgeSamples = []
-    for (let index = 0; index < 10; index++) bridgeSamples.push(await bridgeRead())
-    await stopBridge()
-    bridgeStarted = false
-    if (instrumentation.exitCode === null) await new Promise<void>((resolve) => instrumentation.once('close', () => resolve()))
-    adb('forward', '--remove', `tcp:${hostPort}`)
-    forwarded = false
-    const legacySamples: Array<{ xml: string; elapsed_ms: number }> = []
-    for (let index = 0; index < 10; index++) {
-      const started = process.hrtime.bigint()
-      // Android may still be releasing the instrumentation accessibility connection.
-      for (let retry = 0; ; retry++) {
-        try { adb('shell', 'uiautomator', 'dump', '/sdcard/ui.xml'); break }
-        catch (error) {
-          if (retry === 2) throw error
-          await sleep(500)
-        }
-      }
-      const xml = adb('shell', 'cat', '/sdcard/ui.xml')
-      legacySamples.push({ xml, elapsed_ms: elapsedMs(started) })
-    }
-    const bridgeNodes = nodes(bridgeSamples[0].xml)
-    const legacyNodes = nodes(legacySamples[0].xml)
-    const countIdentifiers = (items: Array<Record<string, string>>) => items.filter((node) => node['@_resource-id'] || node['@_content-desc']).length
-    const report = {
-      platform: 'android', device_id: '[redacted]', fixture: 'latency-journey-app',
-      network_freshness_passed: true,
-      bridge: { samples: summarize(bridgeSamples.map((sample) => sample.elapsed_ms)), node_count: bridgeNodes.length, identified_nodes: countIdentifiers(bridgeNodes) },
-      legacy: { samples: summarize(legacySamples.map((sample) => sample.elapsed_ms)), node_count: legacyNodes.length, identified_nodes: countIdentifiers(legacyNodes) }
-    }
-    const output = path.resolve('docs/benchmarks/ui-tree-performance/bridge-probe.json')
-    mkdirSync(path.dirname(output), { recursive: true })
-    writeFileSync(output, JSON.stringify(report, null, 2))
-    console.log(JSON.stringify(report))
-  } finally {
-    if (bridgeStarted) await stopBridge().catch(() => instrumentation.kill())
-    if (forwarded) { try { adb('forward', '--remove', `tcp:${hostPort}`) } catch { /* Best-effort cleanup. */ } }
-    if (!instrumentation.killed && instrumentation.exitCode === null) instrumentation.kill()
-    server.closeAllConnections()
-    await new Promise<void>((resolve) => server.close(() => resolve()))
-  }
-}
-
-main().catch((error) => { console.error(error); process.exitCode = 1 })

package/test/fixtures/ui-tree-bridge/AndroidManifest.xml

@@ -1,6 +0,0 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="dev.mobiledebugmcp.treebridge">
-  <uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36" />
-  <uses-permission android:name="android.permission.INTERNET" />
-  <application android:label="UI Tree Bridge" />
-  <instrumentation android:name=".TreeInstrumentation" android:targetPackage="dev.mobiledebugmcp.treebridge" android:exported="true" />
-</manifest>