execbro 0.0.1-reserve → 1.10.12

package/build/core/ios.js

@@ -0,0 +1,1705 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { existsSync } from "fs";
+import path from "path";
+import os from "os";
+import sharp from "sharp";
+import { getActiveSimulatorUdid } from "./state.js";
+import { notifyDriverMissing } from "./logbox.js";
+import { execAsync } from "./exec.js";
+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",
+];
+// Track connected IDB simulators to avoid redundant connect calls
+const connectedIdbSimulators = new Set();
+/**
+ * Get the IDB executable path
+ * Supports IDB_PATH environment variable for custom installations
+ */
+function getIdbPath() {
+    return process.env.IDB_PATH || "idb";
+}
+/**
+ * Get the active iOS UI driver.
+ * Defaults to AXe; set IOS_DRIVER=idb in MCP server env to use IDB instead.
+ */
+function getIosDriver() {
+    const driver = process.env.IOS_DRIVER?.toLowerCase();
+    if (driver === "idb")
+        return "idb";
+    return "axe";
+}
+/**
+ * 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
+ */
+async function runIdb(...args) {
+    const idbPath = getIdbPath();
+    const { stdout, stderr } = await execFileAsync(idbPath, args, {
+        timeout: IDB_TIMEOUT,
+    });
+    return {
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+    };
+}
+/**
+ * Check if IDB is available
+ */
+export async function isIdbAvailable() {
+    try {
+        await runIdb("--help");
+        return true;
+    }
+    catch {
+        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
+ */
+async function ensureIdbConnected(udid) {
+    // Skip if already connected in this session
+    if (connectedIdbSimulators.has(udid)) {
+        return { success: true };
+    }
+    try {
+        await runIdb("connect", udid);
+        connectedIdbSimulators.add(udid);
+        return { success: true };
+    }
+    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")) {
+            connectedIdbSimulators.add(udid);
+            return { success: true };
+        }
+        return {
+            success: false,
+            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: await buildNoSimulatorError(),
+            },
+        };
+    }
+    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 };
+}
+// Shared message for callers that hit a missing-Xcode preflight. Includes
+// the actual install command so the agent (or user) can act without guessing.
+export const XCODE_MISSING_ERROR = "Xcode command line tools are not installed or not selected. " +
+    "Run `xcode-select --install` for the CLT, or install full Xcode from the App Store " +
+    "and run `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`. " +
+    "simctl ships with full Xcode (the standalone CLT does not include it).";
+// Memoized result — Xcode CLT presence does not change mid-session in
+// practice, and `xcrun simctl help` adds 50–200 ms per ios_* call without
+// caching. Re-resolve once per process; restart the MCP server after install.
+let simctlAvailableCache = null;
+/**
+ * Check if simctl is available (cached for the lifetime of the process).
+ */
+export async function isSimctlAvailable() {
+    if (simctlAvailableCache)
+        return simctlAvailableCache;
+    simctlAvailableCache = (async () => {
+        try {
+            await execAsync("xcrun simctl help", { timeout: 5000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return simctlAvailableCache;
+}
+/**
+ * Reset the cached simctl availability check. Test-only.
+ */
+export function resetSimctlAvailableCache() {
+    simctlAvailableCache = null;
+}
+/**
+ * List iOS simulators
+ */
+export async function listIOSSimulators(onlyBooted = false) {
+    try {
+        const simctlAvailable = await isSimctlAvailable();
+        if (!simctlAvailable) {
+            return {
+                success: false,
+                error: XCODE_MISSING_ERROR,
+            };
+        }
+        const { stdout } = await execAsync("xcrun simctl list devices -j", {
+            timeout: SIMCTL_TIMEOUT,
+        });
+        const data = JSON.parse(stdout);
+        const simulators = [];
+        // Parse devices from each runtime
+        for (const [runtime, devices] of Object.entries(data.devices)) {
+            if (!Array.isArray(devices))
+                continue;
+            for (const device of devices) {
+                if (!device.isAvailable)
+                    continue;
+                if (onlyBooted && device.state !== "Booted")
+                    continue;
+                // Extract iOS version from runtime string
+                const runtimeMatch = runtime.match(/iOS[- ](\d+[.-]\d+)/i);
+                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,
+                });
+            }
+        }
+        if (simulators.length === 0) {
+            return {
+                success: true,
+                result: onlyBooted
+                    ? "No booted iOS simulators. Start a simulator first."
+                    : "No available iOS simulators found.",
+                simulators: [],
+            };
+        }
+        // Sort: Booted first, then by name
+        simulators.sort((a, b) => {
+            if (a.state === "Booted" && b.state !== "Booted")
+                return -1;
+            if (a.state !== "Booted" && b.state === "Booted")
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        const formatted = simulators
+            .map((s) => {
+            const status = s.state === "Booted" ? "🟢 Booted" : "⚪ Shutdown";
+            return `${s.name} (${s.runtime}) - ${status}\n  UDID: ${s.udid}`;
+        })
+            .join("\n\n");
+        return {
+            success: true,
+            result: `iOS Simulators:\n\n${formatted}`,
+            simulators,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to list simulators: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Build the actionable "no booted simulator" error message. Lists up to 6
+ * recently-available shutdown simulators by name+UDID and points the agent
+ * at `ios_boot_simulator`, so it can recover instead of giving up.
+ */
+export async function buildNoSimulatorError() {
+    const base = "No iOS simulator is currently running. " +
+        "Boot one with `ios_boot_simulator` (pass udid or name), " +
+        "or run `xcrun simctl boot <udid>` directly.";
+    try {
+        const { stdout } = await execAsync("xcrun simctl list devices -j", {
+            timeout: SIMCTL_TIMEOUT,
+        });
+        const data = JSON.parse(stdout);
+        const shutdown = [];
+        for (const list of Object.values(data.devices)) {
+            if (!Array.isArray(list))
+                continue;
+            for (const d of list) {
+                if (d.isAvailable === false)
+                    continue;
+                if (d.state === "Shutdown")
+                    shutdown.push({ name: d.name, udid: d.udid });
+            }
+        }
+        if (shutdown.length === 0)
+            return base;
+        const top = shutdown.slice(0, 6).map((d) => `  - ${d.name} (${d.udid})`).join("\n");
+        const more = shutdown.length > 6 ? `\n  ...and ${shutdown.length - 6} more (run list_ios_simulators)` : "";
+        return `${base}\n\nAvailable simulators (shutdown):\n${top}${more}`;
+    }
+    catch {
+        return base;
+    }
+}
+/**
+ * Get the booted simulator UDID
+ */
+export async function getBootedSimulatorUdid() {
+    try {
+        const { stdout } = await execAsync("xcrun simctl list devices booted -j", {
+            timeout: SIMCTL_TIMEOUT,
+        });
+        const data = JSON.parse(stdout);
+        for (const devices of Object.values(data.devices)) {
+            if (!Array.isArray(devices))
+                continue;
+            for (const device of devices) {
+                if (device.state === "Booted") {
+                    return device.udid;
+                }
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find a booted simulator's UDID by its device name
+ * Matches Metro's deviceName against simulator names from simctl
+ */
+export async function findSimulatorByName(deviceName) {
+    try {
+        const { stdout } = await execAsync("xcrun simctl list devices booted -j", {
+            timeout: SIMCTL_TIMEOUT,
+        });
+        const data = JSON.parse(stdout);
+        const normalizedDeviceName = deviceName.toLowerCase().trim();
+        for (const devices of Object.values(data.devices)) {
+            if (!Array.isArray(devices))
+                continue;
+            for (const device of devices) {
+                if (device.state !== "Booted")
+                    continue;
+                const normalizedSimName = device.name.toLowerCase().trim();
+                // Exact match
+                if (normalizedSimName === normalizedDeviceName) {
+                    return device.udid;
+                }
+                // Partial match (deviceName contains simulator name or vice versa)
+                if (normalizedSimName.includes(normalizedDeviceName) ||
+                    normalizedDeviceName.includes(normalizedSimName)) {
+                    return device.udid;
+                }
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the active simulator UDID (Metro-connected) or fall back to first booted simulator
+ * This enables automatic device scoping based on Metro connection
+ */
+export async function getActiveOrBootedSimulatorUdid() {
+    // First, check if there's an active Metro-connected simulator
+    const activeUdid = getActiveSimulatorUdid();
+    if (activeUdid) {
+        return activeUdid;
+    }
+    // Fall back to first booted simulator
+    return getBootedSimulatorUdid();
+}
+/**
+ * Build device selector for simctl command
+ */
+function buildDeviceArg(udid) {
+    return udid || "booted";
+}
+/**
+ * Take a screenshot from an iOS simulator
+ */
+export async function iosScreenshot(outputPath, udid) {
+    try {
+        const simctlAvailable = await isSimctlAvailable();
+        if (!simctlAvailable) {
+            return {
+                success: false,
+                error: XCODE_MISSING_ERROR,
+            };
+        }
+        // Resolve target UDID (prefer Metro-connected simulator)
+        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
+        if (!targetUdid) {
+            return {
+                success: false,
+                error: await buildNoSimulatorError(),
+            };
+        }
+        // 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,
+        });
+        // 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();
+        const originalWidth = metadata.width || 0;
+        const originalHeight = metadata.height || 0;
+        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, {
+                fit: "inside",
+                withoutEnlargement: true,
+            })
+                .jpeg({ quality: 85 })
+                .toBuffer();
+        }
+        else {
+            imageData = await image.jpeg({ quality: 85 }).toBuffer();
+        }
+        return {
+            success: true,
+            result: finalOutputPath,
+            data: imageData,
+            scaleFactor,
+            originalWidth,
+            originalHeight,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to capture screenshot: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Install an app on an iOS simulator
+ */
+export async function iosInstallApp(appPath, udid) {
+    try {
+        const simctlAvailable = await isSimctlAvailable();
+        if (!simctlAvailable) {
+            return {
+                success: false,
+                error: XCODE_MISSING_ERROR,
+            };
+        }
+        // Verify app exists
+        if (!existsSync(appPath)) {
+            return {
+                success: false,
+                error: `App bundle not found: ${appPath}`,
+            };
+        }
+        // Resolve target UDID (prefer Metro-connected simulator)
+        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
+        if (!targetUdid) {
+            return {
+                success: false,
+                error: await buildNoSimulatorError(),
+            };
+        }
+        await execAsync(`xcrun simctl install ${targetUdid} "${appPath}"`, {
+            timeout: 120000, // 2 minute timeout for install
+        });
+        return {
+            success: true,
+            result: `Successfully installed ${path.basename(appPath)}`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to install app: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Launch an app on an iOS simulator
+ */
+export async function iosLaunchApp(bundleId, udid) {
+    try {
+        const simctlAvailable = await isSimctlAvailable();
+        if (!simctlAvailable) {
+            return {
+                success: false,
+                error: XCODE_MISSING_ERROR,
+            };
+        }
+        // Resolve target UDID (prefer Metro-connected simulator)
+        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
+        if (!targetUdid) {
+            return {
+                success: false,
+                error: await buildNoSimulatorError(),
+            };
+        }
+        await execAsync(`xcrun simctl launch ${targetUdid} ${bundleId}`, {
+            timeout: SIMCTL_TIMEOUT,
+        });
+        return {
+            success: true,
+            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: ${msg}${hint}`,
+        };
+    }
+}
+/**
+ * Open a URL in the iOS simulator
+ */
+export async function iosOpenUrl(url, udid) {
+    try {
+        const simctlAvailable = await isSimctlAvailable();
+        if (!simctlAvailable) {
+            return {
+                success: false,
+                error: XCODE_MISSING_ERROR,
+            };
+        }
+        // Resolve target UDID (prefer Metro-connected simulator)
+        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
+        if (!targetUdid) {
+            return {
+                success: false,
+                error: await buildNoSimulatorError(),
+            };
+        }
+        await execAsync(`xcrun simctl openurl ${targetUdid} "${url}"`, {
+            timeout: SIMCTL_TIMEOUT,
+        });
+        return {
+            success: true,
+            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: ${msg}${hint}`,
+        };
+    }
+}
+/**
+ * Terminate an app on an iOS simulator
+ */
+export async function iosTerminateApp(bundleId, udid) {
+    try {
+        const simctlAvailable = await isSimctlAvailable();
+        if (!simctlAvailable) {
+            return {
+                success: false,
+                error: XCODE_MISSING_ERROR,
+            };
+        }
+        // Resolve target UDID (prefer Metro-connected simulator)
+        const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
+        if (!targetUdid) {
+            return {
+                success: false,
+                error: await buildNoSimulatorError(),
+            };
+        }
+        await execAsync(`xcrun simctl terminate ${targetUdid} ${bundleId}`, {
+            timeout: SIMCTL_TIMEOUT,
+        });
+        return {
+            success: true,
+            result: `Terminated ${bundleId}`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to terminate app: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Boot an iOS simulator
+ */
+export async function iosBootSimulator(udid) {
+    try {
+        const simctlAvailable = await isSimctlAvailable();
+        if (!simctlAvailable) {
+            return {
+                success: false,
+                error: XCODE_MISSING_ERROR,
+            };
+        }
+        await execAsync(`xcrun simctl boot ${udid}`, {
+            timeout: 60000, // 1 minute timeout for boot
+        });
+        // Open Simulator app
+        await execAsync("open -a Simulator", { timeout: 10000 }).catch(() => {
+            // Ignore if Simulator app doesn't open
+        });
+        return {
+            success: true,
+            result: `Simulator ${udid} is now booting`,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Already booted is not an error
+        if (errorMessage.includes("Unable to boot device in current state: Booted")) {
+            return {
+                success: true,
+                result: "Simulator is already booted",
+            };
+        }
+        return {
+            success: false,
+            error: `Failed to boot simulator: ${errorMessage}`,
+        };
+    }
+}
+// ============================================================================
+// 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
+// AXe is the default driver. Set IOS_DRIVER=idb to fall back to IDB.
+// ============================================================================
+/**
+ * Tap at coordinates on an iOS simulator using IDB
+ */
+export async function iosTap(x, y, options) {
+    try {
+        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);
+        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})`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to tap: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Swipe gesture on an iOS simulator
+ */
+export async function iosSwipe(startX, startY, endX, endY, options) {
+    try {
+        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);
+        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) {
+                // Both axe and idb expect duration in seconds (matches the MCP tool schema).
+                args.push("--duration", String(options.duration));
+            }
+            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})`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to swipe: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Input text into the active field on an iOS simulator
+ */
+export async function iosInputText(text, udid) {
+    try {
+        const preflight = await ensureUiDriverReady(udid);
+        if (!preflight.ready)
+            return preflight.error;
+        const { driver, targetUdid } = preflight;
+        if (driver === "axe") {
+            await runAxe("type", text, "--udid", targetUdid);
+        }
+        else {
+            const { stderr } = await runIdb("ui", "text", "--udid", targetUdid, text);
+            if (stderr)
+                throw new Error(stderr);
+        }
+        return {
+            success: true,
+            result: `Typed text: "${text}"`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to input text: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Press a hardware button on an iOS simulator
+ */
+export async function iosButton(button, options) {
+    try {
+        // Validate button type
+        if (!IOS_BUTTON_TYPES.includes(button)) {
+            return {
+                success: false,
+                error: `Invalid button type: ${button}. Valid options: ${IOS_BUTTON_TYPES.join(", ")}`,
+            };
+        }
+        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);
+        }
+        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);
+        }
+        return {
+            success: true,
+            result: `Pressed ${button} button`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to press button: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Send a key event to an iOS simulator
+ */
+export async function iosKeyEvent(keycode, options) {
+    try {
+        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);
+        }
+        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);
+        }
+        return {
+            success: true,
+            result: `Sent key event: ${keycode}`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to send key event: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Send a sequence of key events to an iOS simulator
+ */
+export async function iosKeySequence(keycodes, udid) {
+    try {
+        if (!keycodes || keycodes.length === 0) {
+            return {
+                success: false,
+                error: "At least one keycode is required",
+            };
+        }
+        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);
+        }
+        else {
+            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(", ")}`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to send key sequence: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Format accessibility tree for human-readable output
+ */
+function formatAccessibilityTree(elements, depth = 0) {
+    const lines = [];
+    const indent = "  ".repeat(depth);
+    for (const element of elements) {
+        const parts = [];
+        if (element.type)
+            parts.push(`[${element.type}]`);
+        if (element.AXLabel)
+            parts.push(`"${element.AXLabel}"`);
+        if (element.AXValue)
+            parts.push(`value="${element.AXValue}"`);
+        if (element.frame) {
+            const f = element.frame;
+            const centerX = Math.round(f.x + f.width / 2);
+            const centerY = Math.round(f.y + f.height / 2);
+            parts.push(`frame=(${f.x}, ${f.y}, ${f.width}x${f.height}) tap=(${centerX}, ${centerY})`);
+        }
+        if (parts.length > 0) {
+            lines.push(`${indent}${parts.join(" ")}`);
+        }
+        if (element.children && element.children.length > 0) {
+            lines.push(formatAccessibilityTree(element.children, depth + 1));
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Probe the iOS root accessibility element for the top safe-area inset in points.
+ * React-native-screens modal/sheet presentations cause measureInWindow to return y
+ * relative to the content origin (below the inset) instead of the window. Knowing
+ * the inset lets us detect and correct the shifted coordinate space.
+ *
+ * Cached briefly so a single tap flow doesn't incur multiple describe-ui calls.
+ */
+const SAFE_AREA_CACHE_TTL_MS = 5000;
+const safeAreaTopCache = new Map();
+export async function getIOSSafeAreaTop(udid) {
+    const cacheKey = udid || "__default__";
+    const cached = safeAreaTopCache.get(cacheKey);
+    if (cached && cached.expires > Date.now())
+        return cached.value;
+    let value = 0;
+    try {
+        const preflight = await ensureUiDriverReady(udid);
+        if (preflight.ready) {
+            const { driver, targetUdid } = preflight;
+            let stdout;
+            if (driver === "axe") {
+                stdout = (await runAxe("describe-ui", "--udid", targetUdid)).stdout;
+            }
+            else {
+                const r = await runIdb("ui", "describe-all", "--udid", targetUdid, "--json", "--nested");
+                stdout = r.stdout;
+            }
+            const data = JSON.parse(stdout);
+            const root = Array.isArray(data) ? data[0] : data;
+            const y = root?.frame?.y;
+            if (typeof y === "number" && y > 0)
+                value = Math.round(y);
+        }
+    }
+    catch {
+        // Fall through: value stays 0 (no correction)
+    }
+    safeAreaTopCache.set(cacheKey, { value, expires: Date.now() + SAFE_AREA_CACHE_TTL_MS });
+    return value;
+}
+/**
+ * Get accessibility info for the entire screen
+ */
+export async function iosDescribeAll(udid) {
+    try {
+        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;
+        }
+        else {
+            const result = await runIdb("ui", "describe-all", "--udid", targetUdid, "--json", "--nested");
+            if (result.stderr)
+                throw new Error(result.stderr);
+            stdout = result.stdout;
+        }
+        // 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: header + (formatted || "No accessibility elements found"),
+            elements,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to describe screen: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * I1 (2026-05-16): when a native iOS system sheet (auth prompt, permission request,
+ * Safari sign-in sheet) is on screen, the RN app's fiber tree still describes the
+ * underlying screen — but those pressables aren't interactable until the sheet is
+ * dismissed. Detect the overlay so the screenshot output can warn the agent and
+ * point it at tap(x, y, native=true) for the overlay's actual buttons.
+ *
+ * Heuristic: scan the top three levels of the AXe accessibility tree for an
+ * element whose type matches an iOS sheet/alert role, OR whose AXLabel matches a
+ * well-known system-overlay phrase. False positives are rare because the patterns
+ * are specific to system-presented sheets — RN content rarely uses these labels.
+ */
+const IOS_SYSTEM_OVERLAY_TYPES = /^(Alert|ActionSheet|Sheet|Dialog|SystemDialog)$/i;
+const IOS_SYSTEM_OVERLAY_LABEL_PATTERNS = /Wants to Use|Sign in to|Sign In to|Allow .* to (use|access)|Open in Safari|Continue with|Use Face ID|Use Touch ID|Use Passcode/i;
+/**
+ * Telltale of an RN accessibilityLabel rollup vs a system-presented sheet:
+ * a rollup concatenates multiple child labels with commas / newlines (3+ separators),
+ * while a system sheet's label is a single sentence. Without this guard the label
+ * patterns above false-positive on screens like gifted.co's login wrapper whose
+ * rollup happens to contain "Continue with" amongst many other phrases.
+ */
+function looksLikeRNLabelRollup(label) {
+    const commas = (label.match(/,/g) ?? []).length;
+    const newlines = (label.match(/\n/g) ?? []).length;
+    return commas + newlines >= 3;
+}
+export async function detectIOSSystemOverlay(udid) {
+    try {
+        const desc = await iosDescribeAll(udid);
+        if (!desc.success || !desc.elements)
+            return null;
+        const found = (function walk(elements, depth) {
+            if (depth > 2)
+                return null;
+            for (const el of elements) {
+                if (el.type && IOS_SYSTEM_OVERLAY_TYPES.test(el.type)) {
+                    return { type: el.type, label: el.AXLabel ?? "" };
+                }
+                if (el.AXLabel &&
+                    IOS_SYSTEM_OVERLAY_LABEL_PATTERNS.test(el.AXLabel) &&
+                    !looksLikeRNLabelRollup(el.AXLabel)) {
+                    return { type: el.type ?? "Unknown", label: el.AXLabel };
+                }
+                if (el.children && el.children.length > 0) {
+                    const nested = walk(el.children, depth + 1);
+                    if (nested)
+                        return nested;
+                }
+            }
+            return null;
+        })(desc.elements, 0);
+        if (!found)
+            return { detected: false };
+        return { detected: true, description: found.label || found.type };
+    }
+    catch {
+        return null;
+    }
+}
+export function formatIOSSystemOverlayWarning(detection) {
+    if (!detection.detected)
+        return "";
+    const desc = detection.description?.slice(0, 120) ?? "system sheet";
+    return (`\n\n⚠️ Native iOS overlay detected: "${desc}". The pressables list above reflects the ` +
+        `React Native screen UNDERNEATH and may be stale. For overlay buttons, take the coordinates ` +
+        `from the screenshot and call tap(x, y, native=true, platform="ios").`);
+}
+/**
+ * Get accessibility info at a specific point
+ */
+export async function iosDescribePoint(x, y, udid) {
+    try {
+        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);
+        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 {
+            const parsed = JSON.parse(stdout);
+            element = Array.isArray(parsed) ? parsed[0] : parsed;
+        }
+        catch {
+            return {
+                success: true,
+                result: `No accessibility element found at (${xRounded}, ${yRounded})`,
+                elements: [],
+            };
+        }
+        // Format for human-readable output
+        const parts = [];
+        if (element.type)
+            parts.push(`Type: ${element.type}`);
+        if (element.AXLabel)
+            parts.push(`Label: "${element.AXLabel}"`);
+        if (element.AXValue)
+            parts.push(`Value: "${element.AXValue}"`);
+        if (element.frame) {
+            const f = element.frame;
+            const centerX = Math.round(f.x + f.width / 2);
+            const centerY = Math.round(f.y + f.height / 2);
+            parts.push(`Frame: (${f.x}, ${f.y}) ${f.width}x${f.height}`);
+            parts.push(`Tap: (${centerX}, ${centerY})`);
+        }
+        return {
+            success: true,
+            result: parts.length > 0
+                ? `Element at (${xRounded}, ${yRounded}):\n${parts.join("\n")}`
+                : `No accessibility element found at (${xRounded}, ${yRounded})`,
+            elements: element ? [element] : [],
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to describe point: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Helper to flatten nested accessibility elements
+ */
+function flattenElements(elements) {
+    const result = [];
+    for (const el of elements) {
+        result.push(el);
+        if (el.children && el.children.length > 0) {
+            result.push(...flattenElements(el.children));
+        }
+    }
+    return result;
+}
+/**
+ * Tap an element by its accessibility label using IDB
+ * This simplifies the workflow: no need to manually find coordinates
+ */
+export async function iosTapElement(options) {
+    try {
+        const { label, labelContains, index = 0, duration, udid } = options;
+        if (!label && !labelContains) {
+            return {
+                success: false,
+                error: "Either 'label' (exact match) or 'labelContains' (partial match) is required",
+            };
+        }
+        // Get all accessibility elements
+        const describeResult = await iosDescribeAll(udid);
+        if (!describeResult.success || !describeResult.elements) {
+            return {
+                success: false,
+                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) => {
+            if (!el.AXLabel)
+                return false;
+            if (label)
+                return el.AXLabel === label;
+            if (labelContains)
+                return el.AXLabel.toLowerCase().includes(labelContains.toLowerCase());
+            return false;
+        });
+        if (matches.length === 0) {
+            const searchTerm = label
+                ? `label="${label}"`
+                : `labelContains="${labelContains}"`;
+            return {
+                success: false,
+                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).`,
+            };
+        }
+        const element = matches[index];
+        // Check if element has frame coordinates
+        if (!element.frame) {
+            return {
+                success: false,
+                error: `Element "${element.AXLabel}" has no frame coordinates`,
+            };
+        }
+        // Calculate center
+        const centerX = Math.round(element.frame.x + element.frame.width / 2);
+        const centerY = Math.round(element.frame.y + element.frame.height / 2);
+        // Tap at center
+        const tapResult = await iosTap(centerX, centerY, { duration, udid });
+        if (tapResult.success) {
+            return {
+                success: true,
+                result: `Tapped "${element.AXLabel}" at (${centerX}, ${centerY})`,
+            };
+        }
+        return tapResult;
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to tap element: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Parse IDB accessibility output into simplified element array
+ */
+function parseIdbAccessibilityForFindElement(output) {
+    const elements = [];
+    try {
+        const data = JSON.parse(output);
+        const extractElements = (node) => {
+            const frame = node.frame;
+            if (frame) {
+                const element = {
+                    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,
+                    },
+                    center: {
+                        x: Math.round((frame.x || 0) + (frame.width || 0) / 2),
+                        y: Math.round((frame.y || 0) + (frame.height || 0) / 2),
+                    },
+                    enabled: node.enabled !== false,
+                    traits: node.traits || [],
+                };
+                if (element.label ||
+                    element.value ||
+                    element.type ||
+                    element.identifier) {
+                    elements.push(element);
+                }
+            }
+            const children = node.children;
+            if (children && Array.isArray(children)) {
+                for (const child of children) {
+                    extractElements(child);
+                }
+            }
+        };
+        if (Array.isArray(data)) {
+            for (const item of data) {
+                extractElements(item);
+            }
+        }
+        else {
+            extractElements(data);
+        }
+    }
+    catch {
+        // If JSON parsing fails, return empty array
+    }
+    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
+ */
+function matchesIOSFindElement(element, options) {
+    if (options.label !== undefined) {
+        if (element.label !== options.label)
+            return false;
+    }
+    if (options.labelContains !== undefined) {
+        if (!element.label.toLowerCase().includes(options.labelContains.toLowerCase()))
+            return false;
+    }
+    if (options.value !== undefined) {
+        if (element.value !== options.value)
+            return false;
+    }
+    if (options.valueContains !== undefined) {
+        if (!element.value.toLowerCase().includes(options.valueContains.toLowerCase()))
+            return false;
+    }
+    if (options.type !== undefined) {
+        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;
+}
+/**
+ * Get UI accessibility tree from iOS simulator using IDB (for find_element)
+ */
+export async function iosGetUITree(udid) {
+    try {
+        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;
+        }
+        else {
+            const result = await runIdb("ui", "describe-all", "--udid", targetUdid);
+            stdout = result.stdout;
+        }
+        const elements = parseIdbAccessibilityForFindElement(stdout);
+        return {
+            success: true,
+            elements,
+            rawOutput: stdout,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to get UI tree: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Bug 3 (2026-05-16): RN rolls up child Text labels into a parent View's
+ * accessibilityLabel when the parent is marked `accessible`. Result: a screen-root
+ * View whose label is a 200+ char concatenation of every visible text. `labelContains`
+ * matches it, frame is the whole screen, centroid happens to land on whatever button
+ * sits near the middle — and the tap silently lands on the wrong target.
+ *
+ * Heuristic filter: an element is an aggregator wrapper when EITHER
+ *   (a) its label is much longer than the query AND contains concatenation hints
+ *       (newlines, commas, semicolons — RN rollup typically joins with `, ` or `\n`)
+ *   (b) its frame covers >50% of the viewport (a real button never does this)
+ *
+ * Both heuristics together catch the gifted.co LoginScreen wrapper case the doc cites.
+ */
+function isAggregatorWrapper(element, query, screenSize) {
+    const labelLen = element.label?.length ?? 0;
+    const queryLen = query.length;
+    const isLongConcatenatedLabel = queryLen > 0 &&
+        labelLen > queryLen * 5 &&
+        labelLen > 60 &&
+        /[,;\n]/.test(element.label ?? "");
+    let isFullScreenFrame = false;
+    if (screenSize && element.frame) {
+        const elArea = (element.frame.width ?? 0) * (element.frame.height ?? 0);
+        const screenArea = screenSize.width * screenSize.height;
+        if (screenArea > 0) {
+            isFullScreenFrame = elArea > screenArea * 0.5;
+        }
+    }
+    return isLongConcatenatedLabel || isFullScreenFrame;
+}
+/**
+ * Find element(s) in the iOS UI tree matching the given criteria
+ */
+export async function iosFindElement(options, udid) {
+    try {
+        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, identifier, identifierContains, or type) must be provided",
+            };
+        }
+        const treeResult = await iosGetUITree(udid);
+        if (!treeResult.success || !treeResult.elements) {
+            return {
+                success: false,
+                found: false,
+                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.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));
+        }
+        // Bug 3 (2026-05-16): when matching by partial string (labelContains / identifierContains),
+        // drop aggregator-wrapper elements that match only because their label rolls up every
+        // visible child's text. Without this filter, tapping such a wrapper's centroid
+        // silently lands on the wrong on-screen element.
+        //
+        // When ALL matches are aggregator wrappers (the common case — RN often rolls labels
+        // up to a single accessible wrapper, leaving no individual element with a matching
+        // label), refuse with a clear error pointing the agent at component= or coordinates.
+        // This is safer than silently tapping the wrapper centroid (which lands wherever the
+        // wrapper's geometric center happens to be — usually NOT on the requested button).
+        if (options.labelContains !== undefined && matches.length > 0) {
+            const filtered = matches.filter((el) => !isAggregatorWrapper(el, options.labelContains, screenSize));
+            if (filtered.length > 0) {
+                matches = filtered;
+            }
+            else {
+                return {
+                    success: true,
+                    found: false,
+                    matchCount: 0,
+                    error: `Only matches for labelContains="${options.labelContains}" were aggregator wrappers ` +
+                        `(RN accessibilityLabel rollup of a parent View covering the whole screen). ` +
+                        `Tapping the wrapper would land on the wrong element. ` +
+                        `Try component="ComponentName" instead, or pass coordinates (x, y) from a screenshot.`,
+                };
+            }
+        }
+        if (options.identifierContains !== undefined && matches.length > 0) {
+            const filtered = matches.filter((el) => !isAggregatorWrapper(el, options.identifierContains, screenSize));
+            if (filtered.length > 0) {
+                matches = filtered;
+            }
+            else {
+                return {
+                    success: true,
+                    found: false,
+                    matchCount: 0,
+                    error: `Only matches for identifierContains="${options.identifierContains}" were aggregator wrappers. ` +
+                        `Try component="ComponentName" or pass coordinates (x, y) from a screenshot.`,
+                };
+            }
+        }
+        if (matches.length === 0) {
+            return {
+                success: true,
+                found: false,
+                matchCount: 0,
+            };
+        }
+        const index = options.index ?? 0;
+        const selectedElement = matches[index];
+        if (!selectedElement) {
+            return {
+                success: true,
+                found: false,
+                matchCount: matches.length,
+                error: `Index ${index} out of bounds. Found ${matches.length} matching element(s).`,
+            };
+        }
+        return {
+            success: true,
+            found: true,
+            element: selectedElement,
+            allMatches: matches,
+            matchCount: matches.length,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            found: false,
+            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(await buildNoSimulatorError());
+    }
+    // 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
+ */
+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) {
+        return {
+            success: false,
+            found: false,
+            timedOut: false,
+            error: "At least one search criteria (label, labelContains, value, valueContains, or type) must be provided",
+        };
+    }
+    while (Date.now() - startTime < timeoutMs) {
+        const result = await iosFindElement(options, udid);
+        if (result.found && result.element) {
+            return {
+                ...result,
+                elapsedMs: Date.now() - startTime,
+                timedOut: false,
+            };
+        }
+        if (!result.success) {
+            return {
+                ...result,
+                elapsedMs: Date.now() - startTime,
+                timedOut: false,
+            };
+        }
+        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`,
+    };
+}
+//# sourceMappingURL=ios.js.map