react-native-ai-debugger 1.1.6 → 1.4.33

package/build/core/ios.js

@@ -5,14 +5,23 @@ import path from "path";
 import os from "os";
 import sharp from "sharp";
 import { getActiveSimulatorUdid } from "./state.js";
+import { notifyDriverMissing } from "./logbox.js";
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
 // simctl command timeout in milliseconds
 const SIMCTL_TIMEOUT = 30000;
 // IDB command timeout in milliseconds
 const IDB_TIMEOUT = 30000;
+// AXe command timeout in milliseconds
+const AXE_TIMEOUT = 30000;
 // Valid button types for IDB ui button command
-export const IOS_BUTTON_TYPES = ["HOME", "LOCK", "SIDE_BUTTON", "SIRI", "APPLE_PAY"];
+export const IOS_BUTTON_TYPES = [
+    "HOME",
+    "LOCK",
+    "SIDE_BUTTON",
+    "SIRI",
+    "APPLE_PAY",
+];
 // Track connected IDB simulators to avoid redundant connect calls
 const connectedIdbSimulators = new Set();
 /**
@@ -22,6 +31,36 @@ const connectedIdbSimulators = new Set();
 function getIdbPath() {
     return process.env.IDB_PATH || "idb";
 }
+/**
+ * Get the active iOS UI driver.
+ * Set IOS_DRIVER=axe in MCP server env to use AXe CLI instead of IDB.
+ */
+function getIosDriver() {
+    const driver = process.env.IOS_DRIVER?.toLowerCase();
+    if (driver === "axe")
+        return "axe";
+    return "idb";
+}
+/**
+ * Get the AXe executable path.
+ * Supports AXE_PATH environment variable for custom installations.
+ */
+function getAxePath() {
+    return process.env.AXE_PATH || "axe";
+}
+/**
+ * Run AXe command with execFile (no shell) for proper argument handling.
+ */
+async function runAxe(...args) {
+    const axePath = getAxePath();
+    const { stdout, stderr } = await execFileAsync(axePath, args, {
+        timeout: AXE_TIMEOUT,
+    });
+    return {
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+    };
+}
 /**
  * Run IDB command with execFile (no shell) for proper argument handling
  * This matches the original ios-simulator-mcp implementation
@@ -29,11 +68,11 @@ function getIdbPath() {
 async function runIdb(...args) {
     const idbPath = getIdbPath();
     const { stdout, stderr } = await execFileAsync(idbPath, args, {
-        timeout: IDB_TIMEOUT
+        timeout: IDB_TIMEOUT,
     });
     return {
         stdout: stdout.trim(),
-        stderr: stderr.trim()
+        stderr: stderr.trim(),
     };
 }
 /**
@@ -48,6 +87,49 @@ export async function isIdbAvailable() {
         return false;
     }
 }
+/**
+ * Check if AXe CLI is available
+ */
+export async function isAxeAvailable() {
+    try {
+        await runAxe("--version");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if the active iOS UI driver is available.
+ * Used by tap.ts for early fail-fast checks.
+ */
+export async function isUiDriverAvailable() {
+    const driver = getIosDriver();
+    return driver === "axe" ? isAxeAvailable() : isIdbAvailable();
+}
+/**
+ * Get install instructions for the active iOS UI driver.
+ */
+export function getUiDriverInstallHint() {
+    const driver = getIosDriver();
+    if (driver === "axe") {
+        return "AXe is not installed. Install with: brew install cameroncooke/axe/axe\nAXe is the recommended iOS UI driver. See: https://github.com/cameroncooke/AXe";
+    }
+    return "IDB is not installed. Install with: brew install idb-companion\nTip: Consider switching to AXe (recommended) — brew install cameroncooke/axe/axe and set IOS_DRIVER=axe";
+}
+/**
+ * Map IDB button names (uppercase/underscores) to AXe button names (lowercase/hyphens).
+ */
+function toAxeButtonName(idbButton) {
+    const map = {
+        HOME: "home",
+        LOCK: "lock",
+        SIDE_BUTTON: "side-button",
+        SIRI: "siri",
+        APPLE_PAY: "apple-pay",
+    };
+    return map[idbButton];
+}
 /**
  * Ensure IDB is connected to the specified simulator
  * IDB requires `idb connect <UDID>` before any UI commands work
@@ -65,15 +147,63 @@ async function ensureIdbConnected(udid) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         // "Already connected" is not an error
-        if (errorMessage.includes("already connected") || errorMessage.includes("Connected")) {
+        if (errorMessage.includes("already connected") ||
+            errorMessage.includes("Connected")) {
             connectedIdbSimulators.add(udid);
             return { success: true };
         }
         return {
             success: false,
-            error: `Failed to connect IDB to simulator: ${errorMessage}`
+            error: `Failed to connect IDB to simulator: ${errorMessage}`,
+        };
+    }
+}
+/**
+ * Shared pre-flight check for all UI driver functions:
+ * 1. Check driver availability
+ * 2. Resolve target simulator UDID
+ * 3. Ensure IDB connection (IDB only)
+ */
+async function ensureUiDriverReady(udid) {
+    const driver = getIosDriver();
+    if (driver === "axe") {
+        if (!(await isAxeAvailable())) {
+            notifyDriverMissing("ios");
+            return {
+                ready: false,
+                error: { success: false, error: getUiDriverInstallHint() },
+            };
+        }
+    }
+    else {
+        if (!(await isIdbAvailable())) {
+            notifyDriverMissing("ios");
+            return {
+                ready: false,
+                error: { success: false, error: getUiDriverInstallHint() },
+            };
+        }
+    }
+    const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
+    if (!targetUdid) {
+        return {
+            ready: false,
+            error: {
+                success: false,
+                error: "No iOS simulator is currently running. Start a simulator first.",
+            },
         };
     }
+    if (driver === "idb") {
+        const connectResult = await ensureIdbConnected(targetUdid);
+        if (!connectResult.success) {
+            return {
+                ready: false,
+                error: { success: false, error: connectResult.error },
+            };
+        }
+    }
+    return { ready: true, driver, targetUdid };
 }
 /**
  * Check if simctl is available
@@ -96,11 +226,11 @@ export async function listIOSSimulators(onlyBooted = false) {
         if (!simctlAvailable) {
             return {
                 success: false,
-                error: "Xcode command line tools not available. Install Xcode from the App Store."
+                error: "Xcode command line tools not available. Install Xcode from the App Store.",
             };
         }
         const { stdout } = await execAsync("xcrun simctl list devices -j", {
-            timeout: SIMCTL_TIMEOUT
+            timeout: SIMCTL_TIMEOUT,
         });
         const data = JSON.parse(stdout);
         const simulators = [];
@@ -115,14 +245,16 @@ export async function listIOSSimulators(onlyBooted = false) {
                     continue;
                 // Extract iOS version from runtime string
                 const runtimeMatch = runtime.match(/iOS[- ](\d+[.-]\d+)/i);
-                const runtimeVersion = runtimeMatch ? `iOS ${runtimeMatch[1].replace("-", ".")}` : runtime;
+                const runtimeVersion = runtimeMatch
+                    ? `iOS ${runtimeMatch[1].replace("-", ".")}`
+                    : runtime;
                 simulators.push({
                     udid: device.udid,
                     name: device.name,
                     state: device.state,
                     runtime: runtimeVersion,
                     deviceType: device.deviceTypeIdentifier,
-                    isAvailable: device.isAvailable
+                    isAvailable: device.isAvailable,
                 });
             }
         }
@@ -132,7 +264,7 @@ export async function listIOSSimulators(onlyBooted = false) {
                 result: onlyBooted
                     ? "No booted iOS simulators. Start a simulator first."
                     : "No available iOS simulators found.",
-                simulators: []
+                simulators: [],
             };
         }
         // Sort: Booted first, then by name
@@ -152,13 +284,13 @@ export async function listIOSSimulators(onlyBooted = false) {
         return {
             success: true,
             result: `iOS Simulators:\n\n${formatted}`,
-            simulators
+            simulators,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to list simulators: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to list simulators: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -168,7 +300,7 @@ export async function listIOSSimulators(onlyBooted = false) {
 export async function getBootedSimulatorUdid() {
     try {
         const { stdout } = await execAsync("xcrun simctl list devices booted -j", {
-            timeout: SIMCTL_TIMEOUT
+            timeout: SIMCTL_TIMEOUT,
         });
         const data = JSON.parse(stdout);
         for (const devices of Object.values(data.devices)) {
@@ -193,7 +325,7 @@ export async function getBootedSimulatorUdid() {
 export async function findSimulatorByName(deviceName) {
     try {
         const { stdout } = await execAsync("xcrun simctl list devices booted -j", {
-            timeout: SIMCTL_TIMEOUT
+            timeout: SIMCTL_TIMEOUT,
         });
         const data = JSON.parse(stdout);
         const normalizedDeviceName = deviceName.toLowerCase().trim();
@@ -249,7 +381,7 @@ export async function iosScreenshot(outputPath, udid) {
         if (!simctlAvailable) {
             return {
                 success: false,
-                error: "Xcode command line tools not available. Install Xcode from the App Store."
+                error: "Xcode command line tools not available. Install Xcode from the App Store.",
             };
         }
         // Resolve target UDID (prefer Metro-connected simulator)
@@ -257,14 +389,14 @@ export async function iosScreenshot(outputPath, udid) {
         if (!targetUdid) {
             return {
                 success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
+                error: "No iOS simulator is currently running. Start a simulator first.",
             };
         }
         // Generate output path if not provided
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
         const finalOutputPath = outputPath || path.join(os.tmpdir(), `ios-screenshot-${timestamp}.png`);
         await execAsync(`xcrun simctl io ${targetUdid} screenshot "${finalOutputPath}"`, {
-            timeout: SIMCTL_TIMEOUT
+            timeout: SIMCTL_TIMEOUT,
         });
         // Resize image if needed (API limit: 2000px max for multi-image requests)
         // Return scale factor so AI can convert image coords to device coords
@@ -281,15 +413,13 @@ export async function iosScreenshot(outputPath, udid) {
             imageData = await image
                 .resize(MAX_DIMENSION, MAX_DIMENSION, {
                 fit: "inside",
-                withoutEnlargement: true
+                withoutEnlargement: true,
             })
                 .jpeg({ quality: 85 })
                 .toBuffer();
         }
         else {
-            imageData = await image
-                .jpeg({ quality: 85 })
-                .toBuffer();
+            imageData = await image.jpeg({ quality: 85 }).toBuffer();
         }
         return {
             success: true,
@@ -297,13 +427,13 @@ export async function iosScreenshot(outputPath, udid) {
             data: imageData,
             scaleFactor,
             originalWidth,
-            originalHeight
+            originalHeight,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to capture screenshot: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to capture screenshot: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -316,14 +446,14 @@ export async function iosInstallApp(appPath, udid) {
         if (!simctlAvailable) {
             return {
                 success: false,
-                error: "Xcode command line tools not available. Install Xcode from the App Store."
+                error: "Xcode command line tools not available. Install Xcode from the App Store.",
             };
         }
         // Verify app exists
         if (!existsSync(appPath)) {
             return {
                 success: false,
-                error: `App bundle not found: ${appPath}`
+                error: `App bundle not found: ${appPath}`,
             };
         }
         // Resolve target UDID (prefer Metro-connected simulator)
@@ -331,21 +461,21 @@ export async function iosInstallApp(appPath, udid) {
         if (!targetUdid) {
             return {
                 success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
+                error: "No iOS simulator is currently running. Start a simulator first.",
             };
         }
         await execAsync(`xcrun simctl install ${targetUdid} "${appPath}"`, {
-            timeout: 120000 // 2 minute timeout for install
+            timeout: 120000, // 2 minute timeout for install
         });
         return {
             success: true,
-            result: `Successfully installed ${path.basename(appPath)}`
+            result: `Successfully installed ${path.basename(appPath)}`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to install app: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to install app: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -358,7 +488,7 @@ export async function iosLaunchApp(bundleId, udid) {
         if (!simctlAvailable) {
             return {
                 success: false,
-                error: "Xcode command line tools not available. Install Xcode from the App Store."
+                error: "Xcode command line tools not available. Install Xcode from the App Store.",
             };
         }
         // Resolve target UDID (prefer Metro-connected simulator)
@@ -366,21 +496,27 @@ export async function iosLaunchApp(bundleId, udid) {
         if (!targetUdid) {
             return {
                 success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
+                error: "No iOS simulator is currently running. Start a simulator first.",
             };
         }
         await execAsync(`xcrun simctl launch ${targetUdid} ${bundleId}`, {
-            timeout: SIMCTL_TIMEOUT
+            timeout: SIMCTL_TIMEOUT,
         });
         return {
             success: true,
-            result: `Launched ${bundleId}`
+            result: `Launched ${bundleId}`,
         };
     }
     catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        let hint = "";
+        if (msg.includes("FBSOpenApplicationErrorDomain")) {
+            hint =
+                "\n\nCommon causes:\n- App is not installed on this simulator (install it first with ios_install_app)\n- Bundle ID is incorrect (check with: xcrun simctl listapps booted)";
+        }
         return {
             success: false,
-            error: `Failed to launch app: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to launch app: ${msg}${hint}`,
         };
     }
 }
@@ -393,7 +529,7 @@ export async function iosOpenUrl(url, udid) {
         if (!simctlAvailable) {
             return {
                 success: false,
-                error: "Xcode command line tools not available. Install Xcode from the App Store."
+                error: "Xcode command line tools not available. Install Xcode from the App Store.",
             };
         }
         // Resolve target UDID (prefer Metro-connected simulator)
@@ -401,21 +537,28 @@ export async function iosOpenUrl(url, udid) {
         if (!targetUdid) {
             return {
                 success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
+                error: "No iOS simulator is currently running. Start a simulator first.",
             };
         }
         await execAsync(`xcrun simctl openurl ${targetUdid} "${url}"`, {
-            timeout: SIMCTL_TIMEOUT
+            timeout: SIMCTL_TIMEOUT,
         });
         return {
             success: true,
-            result: `Opened URL: ${url}`
+            result: `Opened URL: ${url}`,
         };
     }
     catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        let hint = "";
+        if (msg.includes("LSApplicationWorkspaceError") ||
+            msg.includes("OpenApplicationErrorDomain")) {
+            hint =
+                "\n\nCommon causes:\n- Custom URL scheme not registered in the app's Info.plist\n- App that handles this URL scheme is not installed\n- For Expo apps, use the exp:// URL format";
+        }
         return {
             success: false,
-            error: `Failed to open URL: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to open URL: ${msg}${hint}`,
         };
     }
 }
@@ -428,7 +571,7 @@ export async function iosTerminateApp(bundleId, udid) {
         if (!simctlAvailable) {
             return {
                 success: false,
-                error: "Xcode command line tools not available. Install Xcode from the App Store."
+                error: "Xcode command line tools not available. Install Xcode from the App Store.",
             };
         }
         // Resolve target UDID (prefer Metro-connected simulator)
@@ -436,21 +579,21 @@ export async function iosTerminateApp(bundleId, udid) {
         if (!targetUdid) {
             return {
                 success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
+                error: "No iOS simulator is currently running. Start a simulator first.",
             };
         }
         await execAsync(`xcrun simctl terminate ${targetUdid} ${bundleId}`, {
-            timeout: SIMCTL_TIMEOUT
+            timeout: SIMCTL_TIMEOUT,
         });
         return {
             success: true,
-            result: `Terminated ${bundleId}`
+            result: `Terminated ${bundleId}`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to terminate app: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to terminate app: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -463,11 +606,11 @@ export async function iosBootSimulator(udid) {
         if (!simctlAvailable) {
             return {
                 success: false,
-                error: "Xcode command line tools not available. Install Xcode from the App Store."
+                error: "Xcode command line tools not available. Install Xcode from the App Store.",
             };
         }
         await execAsync(`xcrun simctl boot ${udid}`, {
-            timeout: 60000 // 1 minute timeout for boot
+            timeout: 60000, // 1 minute timeout for boot
         });
         // Open Simulator app
         await execAsync("open -a Simulator", { timeout: 10000 }).catch(() => {
@@ -475,7 +618,7 @@ export async function iosBootSimulator(udid) {
         });
         return {
             success: true,
-            result: `Simulator ${udid} is now booting`
+            result: `Simulator ${udid} is now booting`,
         };
     }
     catch (error) {
@@ -484,301 +627,277 @@ export async function iosBootSimulator(udid) {
         if (errorMessage.includes("Unable to boot device in current state: Booted")) {
             return {
                 success: true,
-                result: "Simulator is already booted"
+                result: "Simulator is already booted",
             };
         }
         return {
             success: false,
-            error: `Failed to boot simulator: ${errorMessage}`
+            error: `Failed to boot simulator: ${errorMessage}`,
         };
     }
 }
 // ============================================================================
-// IDB-Based UI Interaction Tools
-// These tools require Facebook IDB (iOS Development Bridge) to be installed
-// Install with: brew install idb-companion
+// iOS UI Interaction Tools
+// These tools require an iOS UI driver to be installed:
+//   Recommended: AXe — brew install cameroncooke/axe/axe
+//   Alternative: IDB — brew install idb-companion
+// Set IOS_DRIVER=axe env var to use AXe (default is idb)
 // ============================================================================
 /**
  * Tap at coordinates on an iOS simulator using IDB
  */
 export async function iosTap(x, y, options) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
-        // Get simulator UDID (prefer Metro-connected, then fall back to booted)
-        const targetUdid = options?.udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
-        }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
-        }
+        const preflight = await ensureUiDriverReady(options?.udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
         const xRounded = Math.round(x);
         const yRounded = Math.round(y);
-        // Build args array for execFile (no shell)
-        const args = ["ui", "tap", "--udid", targetUdid];
-        if (options?.duration !== undefined) {
-            args.push("--duration", String(options.duration));
-        }
-        args.push("--json", "--", String(xRounded), String(yRounded));
-        const { stderr } = await runIdb(...args);
-        if (stderr)
-            throw new Error(stderr);
+        if (driver === "axe") {
+            if (options?.duration !== undefined) {
+                // Long press: use axe touch with delay (convert ms to seconds)
+                const delaySecs = String(options.duration / 1000);
+                await runAxe("touch", "-x", String(xRounded), "-y", String(yRounded), "--down", "--up", "--delay", delaySecs, "--udid", targetUdid);
+            }
+            else {
+                await runAxe("tap", "-x", String(xRounded), "-y", String(yRounded), "--udid", targetUdid);
+            }
+        }
+        else {
+            const args = ["ui", "tap", "--udid", targetUdid];
+            if (options?.duration !== undefined) {
+                args.push("--duration", String(options.duration));
+            }
+            args.push("--json", "--", String(xRounded), String(yRounded));
+            const { stderr } = await runIdb(...args);
+            if (stderr)
+                throw new Error(stderr);
+        }
         return {
             success: true,
-            result: `Tapped at (${xRounded}, ${yRounded})`
+            result: `Tapped at (${xRounded}, ${yRounded})`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to tap: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to tap: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
 /**
- * Swipe gesture on an iOS simulator using IDB
+ * Swipe gesture on an iOS simulator
  */
 export async function iosSwipe(startX, startY, endX, endY, options) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
-        const targetUdid = options?.udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
-        }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
-        }
+        const preflight = await ensureUiDriverReady(options?.udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
         const x1 = Math.round(startX);
         const y1 = Math.round(startY);
         const x2 = Math.round(endX);
         const y2 = Math.round(endY);
-        // Build args array for execFile (no shell)
-        const args = ["ui", "swipe", "--udid", targetUdid];
-        if (options?.duration !== undefined) {
-            args.push("--duration", String(options.duration));
-        }
-        if (options?.delta !== undefined) {
-            args.push("--delta", String(options.delta));
-        }
-        args.push("--json", "--", String(x1), String(y1), String(x2), String(y2));
-        const { stderr } = await runIdb(...args);
-        if (stderr)
-            throw new Error(stderr);
+        if (driver === "axe") {
+            const args = [
+                "swipe",
+                "--start-x",
+                String(x1),
+                "--start-y",
+                String(y1),
+                "--end-x",
+                String(x2),
+                "--end-y",
+                String(y2),
+            ];
+            if (options?.duration !== undefined) {
+                args.push("--duration", String(options.duration / 1000));
+            }
+            if (options?.delta !== undefined) {
+                args.push("--delta", String(options.delta));
+            }
+            args.push("--udid", targetUdid);
+            await runAxe(...args);
+        }
+        else {
+            const args = ["ui", "swipe", "--udid", targetUdid];
+            if (options?.duration !== undefined) {
+                args.push("--duration", String(options.duration));
+            }
+            if (options?.delta !== undefined) {
+                args.push("--delta", String(options.delta));
+            }
+            args.push("--json", "--", String(x1), String(y1), String(x2), String(y2));
+            const { stderr } = await runIdb(...args);
+            if (stderr)
+                throw new Error(stderr);
+        }
         return {
             success: true,
-            result: `Swiped from (${x1}, ${y1}) to (${x2}, ${y2})`
+            result: `Swiped from (${x1}, ${y1}) to (${x2}, ${y2})`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to swipe: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to swipe: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
 /**
- * Input text into the active field on an iOS simulator using IDB
+ * Input text into the active field on an iOS simulator
  */
 export async function iosInputText(text, udid) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
-        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
+        const preflight = await ensureUiDriverReady(udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
+        if (driver === "axe") {
+            await runAxe("type", text, "--udid", targetUdid);
         }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
+        else {
+            const { stderr } = await runIdb("ui", "text", "--udid", targetUdid, text);
+            if (stderr)
+                throw new Error(stderr);
         }
-        // Use execFile with args array (no shell escaping needed)
-        const { stderr } = await runIdb("ui", "text", "--udid", targetUdid, text);
-        if (stderr)
-            throw new Error(stderr);
         return {
             success: true,
-            result: `Typed text: "${text}"`
+            result: `Typed text: "${text}"`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to input text: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to input text: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
 /**
- * Press a hardware button on an iOS simulator using IDB
+ * Press a hardware button on an iOS simulator
  */
 export async function iosButton(button, options) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
         // Validate button type
         if (!IOS_BUTTON_TYPES.includes(button)) {
             return {
                 success: false,
-                error: `Invalid button type: ${button}. Valid options: ${IOS_BUTTON_TYPES.join(", ")}`
+                error: `Invalid button type: ${button}. Valid options: ${IOS_BUTTON_TYPES.join(", ")}`,
             };
         }
-        const targetUdid = options?.udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
-        }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
+        const preflight = await ensureUiDriverReady(options?.udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
+        if (driver === "axe") {
+            const args = ["button", toAxeButtonName(button)];
+            if (options?.duration !== undefined) {
+                args.push("--duration", String(options.duration));
+            }
+            args.push("--udid", targetUdid);
+            await runAxe(...args);
         }
-        // Build args array for execFile (no shell)
-        const args = ["ui", "button", "--udid", targetUdid];
-        if (options?.duration !== undefined) {
-            args.push("--duration", String(options.duration));
+        else {
+            const args = ["ui", "button", "--udid", targetUdid];
+            if (options?.duration !== undefined) {
+                args.push("--duration", String(options.duration));
+            }
+            args.push(button);
+            const { stderr } = await runIdb(...args);
+            if (stderr)
+                throw new Error(stderr);
         }
-        args.push(button);
-        const { stderr } = await runIdb(...args);
-        if (stderr)
-            throw new Error(stderr);
         return {
             success: true,
-            result: `Pressed ${button} button`
+            result: `Pressed ${button} button`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to press button: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to press button: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
 /**
- * Send a key event to an iOS simulator using IDB
+ * Send a key event to an iOS simulator
  */
 export async function iosKeyEvent(keycode, options) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
-        const targetUdid = options?.udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
-        }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
+        const preflight = await ensureUiDriverReady(options?.udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
+        if (driver === "axe") {
+            const args = ["key", String(keycode)];
+            if (options?.duration !== undefined) {
+                args.push("--duration", String(options.duration));
+            }
+            args.push("--udid", targetUdid);
+            await runAxe(...args);
         }
-        // Build args array for execFile (no shell)
-        const args = ["ui", "key", "--udid", targetUdid];
-        if (options?.duration !== undefined) {
-            args.push("--duration", String(options.duration));
+        else {
+            const args = ["ui", "key", "--udid", targetUdid];
+            if (options?.duration !== undefined) {
+                args.push("--duration", String(options.duration));
+            }
+            args.push(String(keycode));
+            const { stderr } = await runIdb(...args);
+            if (stderr)
+                throw new Error(stderr);
         }
-        args.push(String(keycode));
-        const { stderr } = await runIdb(...args);
-        if (stderr)
-            throw new Error(stderr);
         return {
             success: true,
-            result: `Sent key event: ${keycode}`
+            result: `Sent key event: ${keycode}`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to send key event: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to send key event: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
 /**
- * Send a sequence of key events to an iOS simulator using IDB
+ * Send a sequence of key events to an iOS simulator
  */
 export async function iosKeySequence(keycodes, udid) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
         if (!keycodes || keycodes.length === 0) {
             return {
                 success: false,
-                error: "At least one keycode is required"
+                error: "At least one keycode is required",
             };
         }
-        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
+        const preflight = await ensureUiDriverReady(udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
+        if (driver === "axe") {
+            await runAxe("key-sequence", "--keycodes", keycodes.join(","), "--udid", targetUdid);
         }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
+        else {
+            const args = [
+                "ui",
+                "key-sequence",
+                "--udid",
+                targetUdid,
+                ...keycodes.map(String),
+            ];
+            const { stderr } = await runIdb(...args);
+            if (stderr)
+                throw new Error(stderr);
         }
-        // Build args array for execFile (no shell)
-        const args = ["ui", "key-sequence", "--udid", targetUdid, ...keycodes.map(String)];
-        const { stderr } = await runIdb(...args);
-        if (stderr)
-            throw new Error(stderr);
         return {
             success: true,
-            result: `Sent key sequence: ${keycodes.join(", ")}`
+            result: `Sent key sequence: ${keycodes.join(", ")}`,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to send key sequence: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to send key sequence: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -812,80 +931,65 @@ function formatAccessibilityTree(elements, depth = 0) {
     return lines.join("\n");
 }
 /**
- * Get accessibility info for the entire screen using IDB
+ * Get accessibility info for the entire screen
  */
 export async function iosDescribeAll(udid) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
-        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
+        const preflight = await ensureUiDriverReady(udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
+        let stdout;
+        if (driver === "axe") {
+            const result = await runAxe("describe-ui", "--udid", targetUdid);
+            stdout = result.stdout;
         }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
+        else {
+            const result = await runIdb("ui", "describe-all", "--udid", targetUdid, "--json", "--nested");
+            if (result.stderr)
+                throw new Error(result.stderr);
+            stdout = result.stdout;
         }
-        // Use execFile with args array (no shell)
-        const { stdout, stderr } = await runIdb("ui", "describe-all", "--udid", targetUdid, "--json", "--nested");
-        if (stderr)
-            throw new Error(stderr);
         // Parse JSON response
         const elements = JSON.parse(stdout);
         // Format for human-readable output
         const formatted = formatAccessibilityTree(elements);
+        const header = 'Note: All coordinates are in iOS points. Use tap(text="...") for tapping — do not pass these coordinates to tap(x, y) directly.\n\n';
         return {
             success: true,
-            result: formatted || "No accessibility elements found",
-            elements
+            result: header + (formatted || "No accessibility elements found"),
+            elements,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to describe screen: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to describe screen: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
 /**
- * Get accessibility info at a specific point using IDB
+ * Get accessibility info at a specific point
  */
 export async function iosDescribePoint(x, y, udid) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
-        }
-        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
-        }
-        // Ensure IDB is connected to the simulator
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
-        }
+        const preflight = await ensureUiDriverReady(udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
         const xRounded = Math.round(x);
         const yRounded = Math.round(y);
-        // Use execFile with args array (no shell)
-        const { stdout, stderr } = await runIdb("ui", "describe-point", "--udid", targetUdid, "--json", "--", String(xRounded), String(yRounded));
-        if (stderr)
-            throw new Error(stderr);
+        let stdout;
+        if (driver === "axe") {
+            const result = await runAxe("describe-ui", "--point", `${xRounded},${yRounded}`, "--udid", targetUdid);
+            stdout = result.stdout;
+        }
+        else {
+            const result = await runIdb("ui", "describe-point", "--udid", targetUdid, "--json", "--", String(xRounded), String(yRounded));
+            if (result.stderr)
+                throw new Error(result.stderr);
+            stdout = result.stdout;
+        }
         // Parse JSON response - may be single element or array
         let element;
         try {
@@ -896,7 +1000,7 @@ export async function iosDescribePoint(x, y, udid) {
             return {
                 success: true,
                 result: `No accessibility element found at (${xRounded}, ${yRounded})`,
-                elements: []
+                elements: [],
             };
         }
         // Format for human-readable output
@@ -919,13 +1023,13 @@ export async function iosDescribePoint(x, y, udid) {
             result: parts.length > 0
                 ? `Element at (${xRounded}, ${yRounded}):\n${parts.join("\n")}`
                 : `No accessibility element found at (${xRounded}, ${yRounded})`,
-            elements: element ? [element] : []
+            elements: element ? [element] : [],
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to describe point: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to describe point: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -952,7 +1056,7 @@ export async function iosTapElement(options) {
         if (!label && !labelContains) {
             return {
                 success: false,
-                error: "Either 'label' (exact match) or 'labelContains' (partial match) is required"
+                error: "Either 'label' (exact match) or 'labelContains' (partial match) is required",
             };
         }
         // Get all accessibility elements
@@ -960,12 +1064,12 @@ export async function iosTapElement(options) {
         if (!describeResult.success || !describeResult.elements) {
             return {
                 success: false,
-                error: describeResult.error || "Failed to get accessibility elements"
+                error: describeResult.error || "Failed to get accessibility elements",
             };
         }
         // Flatten the tree and find matching elements
         const allElements = flattenElements(describeResult.elements);
-        const matches = allElements.filter(el => {
+        const matches = allElements.filter((el) => {
             if (!el.AXLabel)
                 return false;
             if (label)
@@ -975,17 +1079,19 @@ export async function iosTapElement(options) {
             return false;
         });
         if (matches.length === 0) {
-            const searchTerm = label ? `label="${label}"` : `labelContains="${labelContains}"`;
+            const searchTerm = label
+                ? `label="${label}"`
+                : `labelContains="${labelContains}"`;
             return {
                 success: false,
-                error: `No element found with ${searchTerm}`
+                error: `No element found with ${searchTerm}`,
             };
         }
         // Select element by index (default 0 = first match)
         if (index >= matches.length) {
             return {
                 success: false,
-                error: `Index ${index} out of range. Found ${matches.length} matching element(s).`
+                error: `Index ${index} out of range. Found ${matches.length} matching element(s).`,
             };
         }
         const element = matches[index];
@@ -993,7 +1099,7 @@ export async function iosTapElement(options) {
         if (!element.frame) {
             return {
                 success: false,
-                error: `Element "${element.AXLabel}" has no frame coordinates`
+                error: `Element "${element.AXLabel}" has no frame coordinates`,
             };
         }
         // Calculate center
@@ -1004,7 +1110,7 @@ export async function iosTapElement(options) {
         if (tapResult.success) {
             return {
                 success: true,
-                result: `Tapped "${element.AXLabel}" at (${centerX}, ${centerY})`
+                result: `Tapped "${element.AXLabel}" at (${centerX}, ${centerY})`,
             };
         }
         return tapResult;
@@ -1012,7 +1118,7 @@ export async function iosTapElement(options) {
     catch (error) {
         return {
             success: false,
-            error: `Failed to tap element: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to tap element: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -1030,20 +1136,27 @@ function parseIdbAccessibilityForFindElement(output) {
                     label: node.AXLabel || node.label || "",
                     value: node.AXValue || node.value || "",
                     type: node.type || node.AXType || "",
+                    identifier: node.AXIdentifier ||
+                        node.identifier ||
+                        node.AXUniqueId ||
+                        "",
                     frame: {
                         x: frame.x || 0,
                         y: frame.y || 0,
                         width: frame.width || 0,
-                        height: frame.height || 0
+                        height: frame.height || 0,
                     },
                     center: {
                         x: Math.round((frame.x || 0) + (frame.width || 0) / 2),
-                        y: Math.round((frame.y || 0) + (frame.height || 0) / 2)
+                        y: Math.round((frame.y || 0) + (frame.height || 0) / 2),
                     },
                     enabled: node.enabled !== false,
-                    traits: node.traits || []
+                    traits: node.traits || [],
                 };
-                if (element.label || element.value || element.type) {
+                if (element.label ||
+                    element.value ||
+                    element.type ||
+                    element.identifier) {
                     elements.push(element);
                 }
             }
@@ -1068,6 +1181,35 @@ function parseIdbAccessibilityForFindElement(output) {
     }
     return elements;
 }
+/**
+ * Check if an element's center is within the screen viewport.
+ * Filters out off-screen elements in scroll views, horizontal pagers, etc.
+ */
+function isIOSElementInViewport(element, screenWidth, screenHeight) {
+    const { center } = element;
+    return (center.x >= 0 &&
+        center.x <= screenWidth &&
+        center.y >= 0 &&
+        center.y <= screenHeight);
+}
+/**
+ * Extract screen dimensions from the parsed UI tree.
+ * The root Application element's frame represents the screen size.
+ */
+function extractIOSScreenSize(rawOutput) {
+    try {
+        const data = JSON.parse(rawOutput);
+        const root = Array.isArray(data) ? data[0] : data;
+        const frame = root?.frame;
+        if (frame?.width && frame?.height) {
+            return { width: frame.width, height: frame.height };
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return null;
+}
 /**
  * Match iOS element against find options
  */
@@ -1092,6 +1234,16 @@ function matchesIOSFindElement(element, options) {
         if (!element.type.toLowerCase().includes(options.type.toLowerCase()))
             return false;
     }
+    if (options.identifier !== undefined) {
+        if (element.identifier !== options.identifier)
+            return false;
+    }
+    if (options.identifierContains !== undefined) {
+        if (!element.identifier
+            .toLowerCase()
+            .includes(options.identifierContains.toLowerCase()))
+            return false;
+    }
     return true;
 }
 /**
@@ -1099,36 +1251,30 @@ function matchesIOSFindElement(element, options) {
  */
 export async function iosGetUITree(udid) {
     try {
-        const idbAvailable = await isIdbAvailable();
-        if (!idbAvailable) {
-            return {
-                success: false,
-                error: "IDB is not installed. Install with: brew install idb-companion"
-            };
+        const preflight = await ensureUiDriverReady(udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
+        let stdout;
+        if (driver === "axe") {
+            const result = await runAxe("describe-ui", "--udid", targetUdid);
+            stdout = result.stdout;
         }
-        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
-        if (!targetUdid) {
-            return {
-                success: false,
-                error: "No iOS simulator is currently running. Start a simulator first."
-            };
-        }
-        const connectResult = await ensureIdbConnected(targetUdid);
-        if (!connectResult.success) {
-            return { success: false, error: connectResult.error };
+        else {
+            const result = await runIdb("ui", "describe-all", "--udid", targetUdid);
+            stdout = result.stdout;
         }
-        const { stdout } = await runIdb("ui", "describe-all", "--udid", targetUdid);
         const elements = parseIdbAccessibilityForFindElement(stdout);
         return {
             success: true,
             elements,
-            rawOutput: stdout
+            rawOutput: stdout,
         };
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to get UI tree: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to get UI tree: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
@@ -1137,12 +1283,17 @@ export async function iosGetUITree(udid) {
  */
 export async function iosFindElement(options, udid) {
     try {
-        if (!options.label && !options.labelContains && !options.value &&
-            !options.valueContains && !options.type) {
+        if (!options.label &&
+            !options.labelContains &&
+            !options.value &&
+            !options.valueContains &&
+            !options.type &&
+            !options.identifier &&
+            !options.identifierContains) {
             return {
                 success: false,
                 found: false,
-                error: "At least one search criteria (label, labelContains, value, valueContains, or type) must be provided"
+                error: "At least one search criteria (label, labelContains, value, valueContains, identifier, identifierContains, or type) must be provided",
             };
         }
         const treeResult = await iosGetUITree(udid);
@@ -1150,15 +1301,28 @@ export async function iosFindElement(options, udid) {
             return {
                 success: false,
                 found: false,
-                error: treeResult.error
+                error: treeResult.error,
             };
         }
-        const matches = treeResult.elements.filter(el => matchesIOSFindElement(el, options));
+        // Filter to viewport-visible elements first, then match criteria.
+        // This prevents selecting off-screen duplicates in scroll views / pagers.
+        const screenSize = treeResult.rawOutput
+            ? extractIOSScreenSize(treeResult.rawOutput)
+            : null;
+        const visibleElements = screenSize
+            ? treeResult.elements.filter((el) => isIOSElementInViewport(el, screenSize.width, screenSize.height))
+            : treeResult.elements;
+        let matches = visibleElements.filter((el) => matchesIOSFindElement(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) => matchesIOSFindElement(el, options));
+        }
         if (matches.length === 0) {
             return {
                 success: true,
                 found: false,
-                matchCount: 0
+                matchCount: 0,
             };
         }
         const index = options.index ?? 0;
@@ -1168,7 +1332,7 @@ export async function iosFindElement(options, udid) {
                 success: true,
                 found: false,
                 matchCount: matches.length,
-                error: `Index ${index} out of bounds. Found ${matches.length} matching element(s).`
+                error: `Index ${index} out of bounds. Found ${matches.length} matching element(s).`,
             };
         }
         return {
@@ -1176,17 +1340,85 @@ export async function iosFindElement(options, udid) {
             found: true,
             element: selectedElement,
             allMatches: matches,
-            matchCount: matches.length
+            matchCount: matches.length,
         };
     }
     catch (error) {
         return {
             success: false,
             found: false,
-            error: `Failed to find element: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to find element: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
 }
+// DPR cache: UDID → device pixel ratio (never changes during session)
+const dprCache = new Map();
+/**
+ * Pure calculation: DPR = screenshotPixelWidth / screenPointWidth.
+ * Exported for unit testing.
+ */
+export function calculateDPR(screenshotPixelWidth, screenPointWidth) {
+    return Math.round(screenshotPixelWidth / screenPointWidth);
+}
+/**
+ * Query the actual device pixel ratio for an iOS simulator.
+ * Uses screenshot pixel width vs accessibility root frame width.
+ * Result is cached per UDID for the session.
+ */
+export async function getDevicePixelRatio(udid) {
+    const cacheKey = udid || "__default__";
+    const cached = dprCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const resolvedUdid = udid || (await getActiveOrBootedSimulatorUdid());
+    if (!resolvedUdid) {
+        throw new Error("No iOS simulator is currently running. Start a simulator first.");
+    }
+    // Take screenshot to get pixel dimensions
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const screenshotPath = path.join(os.tmpdir(), `ios-dpr-screenshot-${timestamp}.png`);
+    await execAsync(`xcrun simctl io ${resolvedUdid} screenshot "${screenshotPath}"`, {
+        timeout: SIMCTL_TIMEOUT,
+    });
+    const metadata = await sharp(screenshotPath).metadata();
+    const pixelWidth = metadata.width;
+    const pixelHeight = metadata.height;
+    // Try accessibility tree for exact DPR, fall back to inference
+    const driver = getIosDriver();
+    const driverOk = driver === "axe" ? await isAxeAvailable() : await isIdbAvailable();
+    if (driverOk) {
+        try {
+            let stdout;
+            if (driver === "axe") {
+                const result = await runAxe("describe-ui", "--udid", resolvedUdid);
+                stdout = result.stdout;
+            }
+            else {
+                await ensureIdbConnected(resolvedUdid);
+                const result = await runIdb("ui", "describe-all", "--udid", resolvedUdid, "--json", "--nested");
+                stdout = result.stdout;
+            }
+            const screenSize = extractIOSScreenSize(stdout);
+            if (screenSize) {
+                const dpr = calculateDPR(pixelWidth, screenSize.width);
+                dprCache.set(cacheKey, dpr);
+                return dpr;
+            }
+        }
+        catch {
+            // driver failed — fall through to inference
+        }
+    }
+    // Fallback: infer DPR from screenshot pixel dimensions
+    const { inferIOSDevicePixelRatio } = await import("./ocr.js");
+    const dpr = inferIOSDevicePixelRatio(pixelWidth, pixelHeight);
+    dprCache.set(cacheKey, dpr);
+    return dpr;
+}
+/** Clear DPR cache (for testing or when devices change) */
+export function clearDPRCache() {
+    dprCache.clear();
+}
 /**
  * Wait for element to appear on iOS screen with polling
  */
@@ -1194,13 +1426,16 @@ export async function iosWaitForElement(options, udid) {
     const timeoutMs = options.timeoutMs ?? 10000;
     const pollIntervalMs = options.pollIntervalMs ?? 500;
     const startTime = Date.now();
-    if (!options.label && !options.labelContains && !options.value &&
-        !options.valueContains && !options.type) {
+    if (!options.label &&
+        !options.labelContains &&
+        !options.value &&
+        !options.valueContains &&
+        !options.type) {
         return {
             success: false,
             found: false,
             timedOut: false,
-            error: "At least one search criteria (label, labelContains, value, valueContains, or type) must be provided"
+            error: "At least one search criteria (label, labelContains, value, valueContains, or type) must be provided",
         };
     }
     while (Date.now() - startTime < timeoutMs) {
@@ -1209,24 +1444,24 @@ export async function iosWaitForElement(options, udid) {
             return {
                 ...result,
                 elapsedMs: Date.now() - startTime,
-                timedOut: false
+                timedOut: false,
             };
         }
         if (!result.success) {
             return {
                 ...result,
                 elapsedMs: Date.now() - startTime,
-                timedOut: false
+                timedOut: false,
             };
         }
-        await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     }
     return {
         success: true,
         found: false,
         elapsedMs: Date.now() - startTime,
         timedOut: true,
-        error: `Timed out after ${timeoutMs}ms waiting for element`
+        error: `Timed out after ${timeoutMs}ms waiting for element`,
     };
 }
 //# sourceMappingURL=ios.js.map