execbro 2.3.0 → 2.5.0

package/build/core/android.js

@@ -4,19 +4,10 @@ import os from "os";
 import sharp from "sharp";
 import { notifyDriverMissing } from "./logbox.js";
 import { execAsync } from "./exec.js";
-// XML parsing for uiautomator dump
 import { XMLParser } from "fast-xml-parser";
-// ADB command timeout in milliseconds
 const ADB_TIMEOUT = 30000;
-// Module-level cache for ADB availability — checked once per session.
-// `null` = unchecked, boolean = decided. Reset only via `resetAdbAvailabilityCache()` (tests).
 let adbAvailableCache = null;
 let adbPathFixApplied = false;
-/**
- * Standard locations where the Android SDK platform-tools may live when adb is
- * installed but not on the spawned process's PATH (very common on macOS where
- * users add platform-tools only to ~/.zshrc, which GUI-spawned processes don't read).
- */
 function candidateAdbDirs() {
     const dirs = [];
     const env = process.env;
@@ -40,19 +31,6 @@ function candidateAdbDirs() {
 function adbBinaryName() {
     return process.platform === "win32" ? "adb.exe" : "adb";
 }
-/**
- * Check if ADB is reachable. Caches the result for the lifetime of the process.
- *
- * Resolution order:
- *   1. `adb version` against the inherited PATH.
- *   2. Standard SDK install paths (ANDROID_HOME, ~/Library/Android/sdk/..., etc).
- *      If found, prepend the directory to process.env.PATH so subsequent bare
- *      `adb` invocations work without any call-site changes.
- *
- * The recovery path covers the common case of macOS users with Android Studio
- * installed but adb missing from PATH because ~/.zshrc isn't sourced by GUI-spawned
- * processes (Claude Code, VS Code MCP, etc).
- */
 export async function isAdbAvailable() {
     if (adbAvailableCache !== null)
         return adbAvailableCache;
@@ -62,7 +40,6 @@ export async function isAdbAvailable() {
         return true;
     }
     catch {
-        // Fall through to path discovery below.
     }
     if (!adbPathFixApplied) {
         for (const dir of candidateAdbDirs()) {
@@ -78,7 +55,6 @@ export async function isAdbAvailable() {
                 return true;
             }
             catch {
-                // Found the binary but it didn't run — try next candidate.
                 continue;
             }
         }
@@ -86,27 +62,17 @@ export async function isAdbAvailable() {
     adbAvailableCache = false;
     return false;
 }
-/**
- * Test-only: clear the ADB availability cache so the next call re-probes.
- */
 export function resetAdbAvailabilityCache() {
     adbAvailableCache = null;
     adbPathFixApplied = false;
 }
 const ADB_MISSING_ERROR = "ADB is not installed or not in PATH. To fix:\n1. Install Android SDK Platform Tools: https://developer.android.com/tools/releases/platform-tools\n2. Add to PATH: export PATH=$PATH:~/Library/Android/sdk/platform-tools\n3. Verify: run 'adb devices' in terminal";
-/**
- * Check ADB availability and push a LogBox notification if missing.
- * Returns an AdbResult error if ADB is unavailable, or null if ready.
- */
 async function requireAdb() {
     if (await isAdbAvailable())
         return null;
     notifyDriverMissing("android");
     return { success: false, error: ADB_MISSING_ERROR };
 }
-/**
- * List connected Android devices
- */
 export async function listAndroidDevices() {
     try {
         const adbMissing = await requireAdb();
@@ -114,7 +80,6 @@ export async function listAndroidDevices() {
             return adbMissing;
         const { stdout } = await execAsync("adb devices -l", { timeout: ADB_TIMEOUT });
         const lines = stdout.trim().split("\n");
-        // Skip the "List of devices attached" header
         const deviceLines = lines.slice(1).filter((line) => line.trim().length > 0);
         if (deviceLines.length === 0) {
             return {
@@ -127,7 +92,6 @@ export async function listAndroidDevices() {
             const id = parts[0];
             const status = parts[1];
             const device = { id, status };
-            // Parse additional info like product:xxx model:xxx device:xxx transport_id:xxx
             for (let i = 2; i < parts.length; i++) {
                 const [key, value] = parts[i].split(":");
                 if (key === "product")
@@ -164,9 +128,6 @@ export async function listAndroidDevices() {
         };
     }
 }
-/**
- * Get the first connected Android device ID
- */
 export async function getDefaultAndroidDevice() {
     try {
         const { stdout } = await execAsync("adb devices", { timeout: ADB_TIMEOUT });
@@ -184,19 +145,12 @@ export async function getDefaultAndroidDevice() {
         return null;
     }
 }
-/**
- * Locate the `emulator` binary. Returns the command string to invoke it
- * (either bare "emulator" if it's on PATH, or a quoted absolute path).
- * Returns null when the binary cannot be located. Mirrors `isAdbAvailable`'s
- * PATH → ANDROID_HOME → common-install-paths discovery order.
- */
 async function findEmulatorBinary() {
     try {
         await execAsync("emulator -help", { timeout: 3000 });
         return "emulator";
     }
     catch {
-        // not on PATH — try standard install locations
     }
     const env = process.env;
     const candidates = [];
@@ -211,20 +165,10 @@ async function findEmulatorBinary() {
             return `"${candidate}"`;
         }
         catch {
-            // try next
         }
     }
     return null;
 }
-/**
- * List all Android Virtual Devices defined on the host machine, regardless of
- * whether they are currently running.
- *
- * Returns `[]` when adb is missing, the emulator binary cannot be located, or
- * the listing fails. Callers should treat that as "no inventory available"
- * rather than an error so the surrounding tool can still surface other
- * platforms.
- */
 export async function getAndroidEmulatorAvds() {
     const adbMissing = await requireAdb();
     if (adbMissing)
@@ -243,22 +187,13 @@ export async function getAndroidEmulatorAvds() {
         return [];
     }
 }
-/**
- * Map a running emulator's AVD name to its adb serial (e.g. "emulator-5554").
- *
- * Strategy: list adb devices, filter to `emulator-NNNN` serials, then call
- * `adb -s <serial> emu avd name` per serial until one matches the requested
- * AVD name. Returns `null` if no running emulator matches or if adb is
- * unavailable. This is the slow path for the resolver — callers should prefer
- * the cached registry entry first.
- */
 export async function getAdbIdForAvd(avdName) {
     const adbMissing = await requireAdb();
     if (adbMissing)
         return null;
     try {
         const { stdout: devicesOut } = await execAsync("adb devices", { timeout: ADB_TIMEOUT });
-        const lines = devicesOut.trim().split("\n").slice(1); // skip "List of devices attached" header
+        const lines = devicesOut.trim().split("\n").slice(1);
         const emulatorSerials = lines
             .map((line) => line.trim().split(/\s+/)[0])
             .filter((id) => /^emulator-\d+$/.test(id));
@@ -273,7 +208,6 @@ export async function getAdbIdForAvd(avdName) {
                     return serial;
             }
             catch {
-                // skip this serial, try next
             }
         }
         return null;
@@ -282,15 +216,9 @@ export async function getAdbIdForAvd(avdName) {
         return null;
     }
 }
-/**
- * Build device selector for ADB command
- */
 function buildDeviceArg(deviceId) {
     return deviceId ? `-s ${deviceId}` : "";
 }
-/**
- * Take a screenshot from an Android device
- */
 export async function androidScreenshot(outputPath, deviceId, signal) {
     try {
         const adbMissing = await requireAdb();
@@ -304,29 +232,22 @@ export async function androidScreenshot(outputPath, deviceId, signal) {
             };
         }
         const deviceArg = buildDeviceArg(device);
-        // Generate output path if not provided
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
         const finalOutputPath = outputPath || path.join(os.tmpdir(), `android-screenshot-${timestamp}.png`);
-        // Capture screenshot on device
         const remotePath = "/sdcard/screenshot-temp.png";
         await execAsync(`adb ${deviceArg} shell screencap -p ${remotePath}`, {
             timeout: ADB_TIMEOUT,
             signal
         });
-        // Pull screenshot to local machine
         await execAsync(`adb ${deviceArg} pull ${remotePath} "${finalOutputPath}"`, {
             timeout: ADB_TIMEOUT,
             signal
         });
-        // Clean up remote file
         await execAsync(`adb ${deviceArg} shell rm ${remotePath}`, {
             timeout: ADB_TIMEOUT,
             signal
         }).catch(() => {
-            // Ignore cleanup errors
         });
-        // Resize image if needed (API limit: 2000px max for multi-image requests)
-        // Return scale factor so AI can convert image coords to device coords
         const MAX_DIMENSION = 2000;
         const image = sharp(finalOutputPath);
         const metadata = await image.metadata();
@@ -335,7 +256,6 @@ export async function androidScreenshot(outputPath, deviceId, signal) {
         let imageData;
         let scaleFactor = 1;
         if (originalWidth > MAX_DIMENSION || originalHeight > MAX_DIMENSION) {
-            // Calculate scale to fit within MAX_DIMENSION
             scaleFactor = Math.max(originalWidth, originalHeight) / MAX_DIMENSION;
             imageData = await image
                 .resize(MAX_DIMENSION, MAX_DIMENSION, {
@@ -366,15 +286,11 @@ export async function androidScreenshot(outputPath, deviceId, signal) {
         };
     }
 }
-/**
- * Install an APK on an Android device
- */
 export async function androidInstallApp(apkPath, deviceId, options) {
     try {
         const adbMissing = await requireAdb();
         if (adbMissing)
             return adbMissing;
-        // Verify APK exists
         if (!existsSync(apkPath)) {
             return {
                 success: false,
@@ -389,15 +305,13 @@ export async function androidInstallApp(apkPath, deviceId, options) {
             };
         }
         const deviceArg = buildDeviceArg(device);
-        // Build install flags
         const flags = [];
         if (options?.replace)
             flags.push("-r");
         if (options?.grantPermissions)
             flags.push("-g");
         const flagsStr = flags.length > 0 ? flags.join(" ") + " " : "";
-        const { stdout, stderr } = await execAsync(`adb ${deviceArg} install ${flagsStr}"${apkPath}"`, { timeout: 120000 } // 2 minute timeout for install
-        );
+        const { stdout, stderr } = await execAsync(`adb ${deviceArg} install ${flagsStr}"${apkPath}"`, { timeout: 120000 });
         const output = stdout + stderr;
         if (output.includes("Success")) {
             return {
@@ -419,9 +333,6 @@ export async function androidInstallApp(apkPath, deviceId, options) {
         };
     }
 }
-/**
- * Launch an app on an Android device
- */
 export async function androidLaunchApp(packageName, activityName, deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -437,16 +348,13 @@ export async function androidLaunchApp(packageName, activityName, deviceId) {
         const deviceArg = buildDeviceArg(device);
         let command;
         if (activityName) {
-            // Launch specific activity
             command = `adb ${deviceArg} shell am start -n ${packageName}/${activityName}`;
         }
         else {
-            // Launch main/launcher activity
             command = `adb ${deviceArg} shell monkey -p ${packageName} -c android.intent.category.LAUNCHER 1`;
         }
         const { stdout, stderr } = await execAsync(command, { timeout: ADB_TIMEOUT });
         const output = stdout + stderr;
-        // Check for errors
         if (output.includes("Error") || output.includes("Exception")) {
             return {
                 success: false,
@@ -465,9 +373,6 @@ export async function androidLaunchApp(packageName, activityName, deviceId) {
         };
     }
 }
-/**
- * Get list of installed packages on the device
- */
 export async function androidListPackages(deviceId, filter) {
     try {
         const adbMissing = await requireAdb();
@@ -511,12 +416,6 @@ export async function androidListPackages(deviceId, filter) {
         };
     }
 }
-// ============================================================================
-// UI Input Functions (Phase 2)
-// ============================================================================
-/**
- * Common key event codes for Android
- */
 export const ANDROID_KEY_EVENTS = {
     HOME: 3,
     BACK: 4,
@@ -541,9 +440,6 @@ export const ANDROID_KEY_EVENTS = {
     APP_SWITCH: 187,
     ESCAPE: 111
 };
-/**
- * Tap at coordinates on an Android device
- */
 export async function androidTap(x, y, deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -572,9 +468,6 @@ export async function androidTap(x, y, deviceId) {
         };
     }
 }
-/**
- * Long press at coordinates on an Android device
- */
 export async function androidLongPress(x, y, durationMs = 1000, deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -588,7 +481,6 @@ export async function androidLongPress(x, y, durationMs = 1000, deviceId) {
             };
         }
         const deviceArg = buildDeviceArg(device);
-        // Long press is implemented as a swipe from the same point to the same point
         const xRounded = Math.round(x);
         const yRounded = Math.round(y);
         await execAsync(`adb ${deviceArg} shell input swipe ${xRounded} ${yRounded} ${xRounded} ${yRounded} ${durationMs}`, { timeout: ADB_TIMEOUT + durationMs });
@@ -604,9 +496,6 @@ export async function androidLongPress(x, y, durationMs = 1000, deviceId) {
         };
     }
 }
-/**
- * Swipe on an Android device
- */
 export async function androidSwipe(startX, startY, endX, endY, durationMs = 300, deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -637,12 +526,6 @@ export async function androidSwipe(startX, startY, endX, endY, durationMs = 300,
         };
     }
 }
-/**
- * Input text on an Android device
- *
- * ADB input text has limitations with special characters.
- * This function handles escaping properly for URLs, emails, and special strings.
- */
 export async function androidInputText(text, deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -656,21 +539,15 @@ export async function androidInputText(text, deviceId) {
             };
         }
         const deviceArg = buildDeviceArg(device);
-        // For complex strings with special characters, type character by character
-        // using key events for reliability
         const hasComplexChars = /[/:?=&#@%+]/.test(text);
         if (hasComplexChars) {
-            // Use character-by-character input for strings with special chars
-            // This is slower but more reliable for URLs, emails, etc.
             for (const char of text) {
                 let keyCmd;
-                // Map special characters to their escaped form or use direct input
                 switch (char) {
                     case " ":
                         keyCmd = `adb ${deviceArg} shell input text "%s"`;
                         break;
                     case "'":
-                        // Single quote needs special handling
                         keyCmd = `adb ${deviceArg} shell input text "\\'"`;
                         break;
                     case '"':
@@ -707,13 +584,9 @@ export async function androidInputText(text, deviceId) {
                         keyCmd = `adb ${deviceArg} shell input text "\\\`"`;
                         break;
                     case "#":
-                        // # is a shell comment character — single quotes don't prevent interpretation
-                        // on some Android shell versions, so use backslash escaping in double quotes
                         keyCmd = `adb ${deviceArg} shell input text "\\#"`;
                         break;
                     default:
-                        // For most characters, wrap in single quotes to prevent shell interpretation
-                        // Single quotes preserve literal meaning of all characters except single quote itself
                         keyCmd = `adb ${deviceArg} shell input text '${char}'`;
                 }
                 await execAsync(keyCmd, { timeout: 5000 });
@@ -723,8 +596,6 @@ export async function androidInputText(text, deviceId) {
                 result: `Typed: "${text}"`
             };
         }
-        // For simple alphanumeric strings, use the faster bulk input
-        // Escape basic special characters
         const escapedText = text
             .replace(/\\/g, "\\\\")
             .replace(/"/g, '\\"')
@@ -747,9 +618,6 @@ export async function androidInputText(text, deviceId) {
         };
     }
 }
-/**
- * Send a key event to an Android device
- */
 export async function androidKeyEvent(keyCode, deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -763,7 +631,6 @@ export async function androidKeyEvent(keyCode, deviceId) {
             };
         }
         const deviceArg = buildDeviceArg(device);
-        // Resolve key code from name if needed
         const resolvedKeyCode = typeof keyCode === "string" ? ANDROID_KEY_EVENTS[keyCode] : keyCode;
         if (resolvedKeyCode === undefined) {
             return {
@@ -774,7 +641,6 @@ export async function androidKeyEvent(keyCode, deviceId) {
         await execAsync(`adb ${deviceArg} shell input keyevent ${resolvedKeyCode}`, {
             timeout: ADB_TIMEOUT
         });
-        // Get key name for display
         const keyName = typeof keyCode === "string"
             ? keyCode
             : Object.entries(ANDROID_KEY_EVENTS).find(([_, v]) => v === keyCode)?.[0] ||
@@ -791,9 +657,6 @@ export async function androidKeyEvent(keyCode, deviceId) {
         };
     }
 }
-/**
- * Parse bounds string like "[0,0][1080,1920]" to AndroidUIElement bounds
- */
 function parseBoundsForUIElement(boundsStr) {
     const match = boundsStr.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
     if (!match)
@@ -811,19 +674,14 @@ function parseBoundsForUIElement(boundsStr) {
         height: bottom - top
     };
 }
-/**
- * Parse uiautomator XML dump into element array
- */
 function parseUIAutomatorXML(xml) {
     const elements = [];
-    // Match all node elements with their attributes
     const nodeRegex = /<node\s+([^>]+)\/?>|<node\s+([^>]+)>/g;
     let match;
     while ((match = nodeRegex.exec(xml)) !== null) {
         const attrStr = match[1] || match[2];
         if (!attrStr)
             continue;
-        // Extract attributes
         const getAttr = (name) => {
             const attrMatch = attrStr.match(new RegExp(`${name}="([^"]*)"`));
             return attrMatch ? attrMatch[1] : "";
@@ -852,23 +710,11 @@ function parseUIAutomatorXML(xml) {
     }
     return elements;
 }
-/**
- * Match element against find options
- */
-/**
- * Check if an element's center is within the screen viewport.
- * Filters out off-screen elements in scroll views, pagers, etc.
- */
 function isAndroidElementInViewport(element, screenWidth, screenHeight) {
     const { center } = element;
     return center.x >= 0 && center.x <= screenWidth && center.y >= 0 && center.y <= screenHeight;
 }
-/**
- * Extract screen dimensions from the uiautomator XML.
- * The root hierarchy node's bounds represent the screen size.
- */
 function extractAndroidScreenSize(rawXml) {
-    // Match the first node's bounds (root element = screen)
     const match = rawXml.match(/<(?:hierarchy|node)[^>]*bounds="\[0,0\]\[(\d+),(\d+)\]"/);
     if (match) {
         return { width: parseInt(match[1], 10), height: parseInt(match[2], 10) };
@@ -893,16 +739,12 @@ function matchesElement(element, options) {
             return false;
     }
     if (options.resourceId !== undefined) {
-        // Support both full "com.app:id/button" and short "button" forms
         const shortId = element.resourceId.split("/").pop() || "";
         if (element.resourceId !== options.resourceId && shortId !== options.resourceId)
             return false;
     }
     return true;
 }
-/**
- * Get UI accessibility tree from Android device using uiautomator
- */
 export async function androidGetUITree(deviceId, signal) {
     try {
         const adbMissing = await requireAdb();
@@ -916,21 +758,15 @@ export async function androidGetUITree(deviceId, signal) {
             };
         }
         const deviceArg = buildDeviceArg(device);
-        // Dump UI hierarchy to device. The `signal` is passed so a strategy-level
-        // timeout in tap.ts can SIGKILL the host adb process — the device-side
-        // uiautomator dump is independent and finishes silently, but we stop
-        // waiting on the ADB channel so the next strategy can use it.
         const remotePath = "/sdcard/ui_dump.xml";
         await execAsync(`adb ${deviceArg} shell uiautomator dump ${remotePath}`, {
             timeout: ADB_TIMEOUT,
             signal
         });
-        // Read the XML content
         const { stdout } = await execAsync(`adb ${deviceArg} shell cat ${remotePath}`, {
             timeout: ADB_TIMEOUT,
             signal
         });
-        // Clean up remote file
         await execAsync(`adb ${deviceArg} shell rm ${remotePath}`, {
             timeout: ADB_TIMEOUT,
             signal
@@ -951,7 +787,6 @@ export async function androidGetUITree(deviceId, signal) {
 }
 export async function androidFindElement(options, deviceId, signal, tree) {
     try {
-        // Validate that at least one search criteria is provided
         if (!options.text && !options.textContains && !options.contentDesc &&
             !options.contentDescContains && !options.resourceId) {
             return {
@@ -960,9 +795,6 @@ export async function androidFindElement(options, deviceId, signal, tree) {
                 error: "At least one search criteria (text, textContains, contentDesc, contentDescContains, or resourceId) must be provided"
             };
         }
-        // A caller that already dumped the hierarchy can pass it in — uiautomator
-        // dumps are the single most expensive step of an Android accessibility
-        // tap, and the tap strategy runs two passes over the same screen.
         const treeResult = tree ?? (await androidGetUITree(deviceId, signal));
         if (!treeResult.success || !treeResult.elements) {
             return {
@@ -971,15 +803,11 @@ export async function androidFindElement(options, deviceId, signal, tree) {
                 error: treeResult.error
             };
         }
-        // Filter to viewport-visible elements first, then match criteria.
-        // This prevents selecting off-screen duplicates in scroll views / pagers.
         const screenSize = treeResult.rawXml ? extractAndroidScreenSize(treeResult.rawXml) : null;
         const visibleElements = screenSize
             ? treeResult.elements.filter(el => isAndroidElementInViewport(el, screenSize.width, screenSize.height))
             : treeResult.elements;
         let matches = visibleElements.filter(el => matchesElement(el, options));
-        // If no visible matches, fall back to all elements (element may be partially visible
-        // or the screen size extraction failed)
         if (matches.length === 0) {
             matches = treeResult.elements.filter(el => matchesElement(el, options));
         }
@@ -990,7 +818,6 @@ export async function androidFindElement(options, deviceId, signal, tree) {
                 matchCount: 0
             };
         }
-        // Select the element at the specified index (default 0)
         const index = options.index ?? 0;
         const selectedElement = matches[index];
         if (!selectedElement) {
@@ -1017,14 +844,10 @@ export async function androidFindElement(options, deviceId, signal, tree) {
         };
     }
 }
-/**
- * Wait for element to appear on screen with polling
- */
 export async function androidWaitForElement(options, deviceId) {
     const timeoutMs = options.timeoutMs ?? 10000;
     const pollIntervalMs = options.pollIntervalMs ?? 500;
     const startTime = Date.now();
-    // Validate that at least one search criteria is provided
     if (!options.text && !options.textContains && !options.contentDesc &&
         !options.contentDescContains && !options.resourceId) {
         return {
@@ -1043,7 +866,6 @@ export async function androidWaitForElement(options, deviceId) {
                 timedOut: false
             };
         }
-        // If there was an error (not just "not found"), return it
         if (!result.success) {
             return {
                 ...result,
@@ -1051,7 +873,6 @@ export async function androidWaitForElement(options, deviceId) {
                 timedOut: false
             };
         }
-        // Wait before next poll
         await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
     }
     return {
@@ -1062,9 +883,6 @@ export async function androidWaitForElement(options, deviceId) {
         error: `Timed out after ${timeoutMs}ms waiting for element`
     };
 }
-/**
- * Get device screen size
- */
 export async function androidGetScreenSize(deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -1081,7 +899,6 @@ export async function androidGetScreenSize(deviceId) {
         const { stdout } = await execAsync(`adb ${deviceArg} shell wm size`, {
             timeout: ADB_TIMEOUT
         });
-        // Parse output like "Physical size: 1080x1920"
         const match = stdout.match(/(\d+)x(\d+)/);
         if (match) {
             return {
@@ -1102,9 +919,6 @@ export async function androidGetScreenSize(deviceId) {
         };
     }
 }
-/**
- * Get device display density (dpi)
- */
 export async function androidGetDensity(deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -1121,7 +935,6 @@ export async function androidGetDensity(deviceId) {
         const { stdout } = await execAsync(`adb ${deviceArg} shell wm density`, {
             timeout: ADB_TIMEOUT
         });
-        // Parse output like "Physical density: 440" or "Override density: 440"
         const match = stdout.match(/density:\s*(\d+)/i);
         if (match) {
             return {
@@ -1141,30 +954,21 @@ export async function androidGetDensity(deviceId) {
         };
     }
 }
-/**
- * Get status bar height in pixels
- * Android status bar is typically 24dp, but can vary by device/OS version
- */
 export async function androidGetStatusBarHeight(deviceId) {
     try {
-        // Get density first
         const densityResult = await androidGetDensity(deviceId);
         if (!densityResult.success || !densityResult.density) {
-            // Fallback to common estimate
             return {
                 success: true,
-                heightPixels: 63, // Common for 420dpi devices (24dp * 2.625)
+                heightPixels: 63,
                 heightDp: 24
             };
         }
         const density = densityResult.density;
-        const densityScale = density / 160; // Android baseline is 160dpi
-        // Try to get actual status bar height from resources
+        const densityScale = density / 160;
         const deviceArg = buildDeviceArg(deviceId);
         try {
             const { stdout } = await execAsync(`adb ${deviceArg} shell "dumpsys window | grep -E 'statusBars|mStatusBarLayer|InsetsSource.*statusBars'"`, { timeout: ADB_TIMEOUT });
-            // Try to parse status bar height from dumpsys output
-            // Look for patterns like "statusBars frame=[0,0][1080,63]"
             const frameMatch = stdout.match(/statusBars.*frame=\[[\d,]+\]\[(\d+),(\d+)\]/);
             if (frameMatch) {
                 const heightPixels = parseInt(frameMatch[2], 10);
@@ -1176,9 +980,7 @@ export async function androidGetStatusBarHeight(deviceId) {
             }
         }
         catch {
-            // Fallback to standard calculation
         }
-        // Standard status bar height is 24dp on most devices
         const statusBarDp = 24;
         const statusBarPixels = Math.round(statusBarDp * densityScale);
         return {
@@ -1194,20 +996,12 @@ export async function androidGetStatusBarHeight(deviceId) {
         };
     }
 }
-/**
- * Simplify Android class name for display
- * android.widget.Button -> Button
- * android.widget.TextView -> TextView
- */
 function simplifyClassName(className) {
     if (!className)
         return "Unknown";
     const parts = className.split(".");
     return parts[parts.length - 1];
 }
-/**
- * Parse bounds string "[left,top][right,bottom]" to object
- */
 function parseBounds(boundsStr) {
     const match = boundsStr?.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
     if (!match)
@@ -1219,9 +1013,6 @@ function parseBounds(boundsStr) {
         bottom: parseInt(match[4], 10)
     };
 }
-/**
- * Parse a single node from uiautomator XML
- */
 function parseUiNode(node) {
     const attrs = node["@_bounds"]
         ? node
@@ -1253,7 +1044,6 @@ function parseUiNode(node) {
         },
         children: []
     };
-    // Add optional attributes
     if (attrs["@_text"])
         element.text = attrs["@_text"];
     if (attrs["@_content-desc"])
@@ -1278,16 +1068,11 @@ function parseUiNode(node) {
         element.selected = true;
     return element;
 }
-/**
- * Recursively parse UI hierarchy from XML node
- */
 function parseHierarchy(node) {
     const results = [];
-    // Handle the node itself
     if (node["@_bounds"]) {
         const element = parseUiNode(node);
         if (element) {
-            // Parse children
             if (node.node) {
                 const children = Array.isArray(node.node) ? node.node : [node.node];
                 for (const child of children) {
@@ -1298,7 +1083,6 @@ function parseHierarchy(node) {
         }
     }
     else if (node.node) {
-        // This is a container without bounds (like hierarchy root)
         const children = Array.isArray(node.node) ? node.node : [node.node];
         for (const child of children) {
             results.push(...parseHierarchy(child));
@@ -1306,35 +1090,25 @@ function parseHierarchy(node) {
     }
     return results;
 }
-/**
- * Format accessibility tree for display (similar to iOS format)
- */
 function formatAndroidAccessibilityTree(elements, indent = 0) {
     const lines = [];
     const prefix = "  ".repeat(indent);
     for (const element of elements) {
         const parts = [];
-        // [ClassName] "text" or "content-desc"
         parts.push(`[${element.class}]`);
-        // Add label (text or content-desc)
         const label = element.text || element.contentDesc;
         if (label) {
             parts.push(`"${label}"`);
         }
-        // Add frame and tap coordinates
         const f = element.frame;
         parts.push(`frame=(${f.x}, ${f.y}, ${f.width}x${f.height}) tap=(${element.tap.x}, ${element.tap.y})`);
         lines.push(`${prefix}${parts.join(" ")}`);
-        // Recurse into children
         if (element.children.length > 0) {
             lines.push(formatAndroidAccessibilityTree(element.children, indent + 1));
         }
     }
     return lines.join("\n");
 }
-/**
- * Flatten element tree to array for searching
- */
 function flattenElements(elements) {
     const result = [];
     for (const element of elements) {
@@ -1345,9 +1119,6 @@ function flattenElements(elements) {
     }
     return result;
 }
-/**
- * Get the UI hierarchy from the connected Android device using uiautomator dump
- */
 export async function androidDescribeAll(deviceId) {
     try {
         const adbMissing = await requireAdb();
@@ -1361,8 +1132,6 @@ export async function androidDescribeAll(deviceId) {
             };
         }
         const deviceArg = buildDeviceArg(device);
-        // Use file-based approach (most reliable across devices)
-        // /dev/tty doesn't work on most emulators/devices
         const remotePath = "/sdcard/ui_dump.xml";
         await execAsync(`adb ${deviceArg} shell uiautomator dump ${remotePath}`, {
             timeout: ADB_TIMEOUT
@@ -1372,7 +1141,6 @@ export async function androidDescribeAll(deviceId) {
             maxBuffer: 10 * 1024 * 1024
         });
         const xmlContent = stdout.trim();
-        // Clean up
         await execAsync(`adb ${deviceArg} shell rm ${remotePath}`, {
             timeout: 5000
         }).catch(() => { });
@@ -1382,7 +1150,6 @@ export async function androidDescribeAll(deviceId) {
                 error: "Failed to get UI hierarchy. Make sure the device screen is unlocked and the app is in foreground."
             };
         }
-        // Parse XML
         const parser = new XMLParser({
             ignoreAttributes: false,
             attributeNamePrefix: "@_"
@@ -1409,19 +1176,13 @@ export async function androidDescribeAll(deviceId) {
         };
     }
 }
-/**
- * Get accessibility info for the UI element at specific coordinates
- */
 export async function androidDescribePoint(x, y, deviceId) {
     try {
-        // First get the full hierarchy
         const result = await androidDescribeAll(deviceId);
         if (!result.success || !result.elements) {
             return result;
         }
-        // Flatten and find elements containing the point
         const allElements = flattenElements(result.elements);
-        // Find all elements whose bounds contain the point
         const matchingElements = allElements.filter((el) => {
             const b = el.bounds;
             return x >= b.left && x <= b.right && y >= b.top && y <= b.bottom;
@@ -1432,15 +1193,12 @@ export async function androidDescribePoint(x, y, deviceId) {
                 formatted: `No element found at (${x}, ${y})`
             };
         }
-        // Return the deepest (smallest) element that contains the point
-        // Sort by area (smallest first) to get the most specific element
         matchingElements.sort((a, b) => {
             const areaA = a.frame.width * a.frame.height;
             const areaB = b.frame.width * b.frame.height;
             return areaA - areaB;
         });
         const element = matchingElements[0];
-        // Format detailed output
         const lines = [];
         const label = element.text || element.contentDesc;
         lines.push(`[${element.class}]${label ? ` "${label}"` : ""} frame=(${element.frame.x}, ${element.frame.y}, ${element.frame.width}x${element.frame.height}) tap=(${element.tap.x}, ${element.tap.y})`);
@@ -1448,14 +1206,11 @@ export async function androidDescribePoint(x, y, deviceId) {
             lines.push(`  resource-id: ${element.resourceId}`);
         }
         if (element.contentDesc && element.text) {
-            // Show content-desc separately if we showed text as label
             lines.push(`  content-desc: ${element.contentDesc}`);
         }
         if (element.text && element.contentDesc) {
-            // Show text separately if we showed content-desc as label
             lines.push(`  text: ${element.text}`);
         }
-        // Show state flags
         const flags = [];
         if (element.clickable)
             flags.push("clickable");
@@ -1487,20 +1242,15 @@ export async function androidDescribePoint(x, y, deviceId) {
         };
     }
 }
-/**
- * Tap an element by its text, content-description, or resource-id
- */
 export async function androidTapElement(options) {
     try {
         const { text, textContains, contentDesc, contentDescContains, resourceId, index = 0, deviceId } = options;
-        // Validate that at least one search criterion is provided
         if (!text && !textContains && !contentDesc && !contentDescContains && !resourceId) {
             return {
                 success: false,
                 error: "At least one of text, textContains, contentDesc, contentDescContains, or resourceId must be provided"
             };
         }
-        // Get the UI hierarchy
         const result = await androidDescribeAll(deviceId);
         if (!result.success || !result.elements) {
             return {
@@ -1508,9 +1258,7 @@ export async function androidTapElement(options) {
                 error: result.error || "Failed to get UI hierarchy"
             };
         }
-        // Flatten and search
         const allElements = flattenElements(result.elements);
-        // Filter elements based on search criteria
         const matchingElements = allElements.filter((el) => {
             if (text && el.text !== text)
                 return false;
@@ -1521,7 +1269,6 @@ export async function androidTapElement(options) {
             if (contentDescContains && (!el.contentDesc || !el.contentDesc.toLowerCase().includes(contentDescContains.toLowerCase())))
                 return false;
             if (resourceId) {
-                // Support both full resource-id and short form
                 if (!el.resourceId)
                     return false;
                 if (el.resourceId !== resourceId && !el.resourceId.endsWith(`:id/${resourceId}`))
@@ -1554,7 +1301,6 @@ export async function androidTapElement(options) {
         }
         const element = matchingElements[index];
         const label = element.text || element.contentDesc || element.resourceId || element.class;
-        // Log if multiple matches
         let resultMessage;
         if (matchingElements.length > 1) {
             resultMessage = `Found ${matchingElements.length} elements, tapping "${label}" (index ${index}) at (${element.tap.x}, ${element.tap.y})`;
@@ -1562,7 +1308,6 @@ export async function androidTapElement(options) {
         else {
             resultMessage = `Tapped "${label}" at (${element.tap.x}, ${element.tap.y})`;
         }
-        // Perform the tap
         const tapResult = await androidTap(element.tap.x, element.tap.y, deviceId);
         if (!tapResult.success) {
             return tapResult;