execbro 2.3.0 → 2.6.0

package/build/core/ios.js

@@ -8,13 +8,9 @@ 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",
@@ -22,35 +18,19 @@ export const IOS_BUTTON_TYPES = [
     "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, {
@@ -61,10 +41,6 @@ async function runAxe(...args) {
         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, {
@@ -75,9 +51,6 @@ async function runIdb(...args) {
         stderr: stderr.trim(),
     };
 }
-/**
- * Check if IDB is available
- */
 export async function isIdbAvailable() {
     try {
         await runIdb("--help");
@@ -87,9 +60,6 @@ export async function isIdbAvailable() {
         return false;
     }
 }
-/**
- * Check if AXe CLI is available
- */
 export async function isAxeAvailable() {
     try {
         await runAxe("--version");
@@ -99,17 +69,10 @@ export async function isAxeAvailable() {
         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") {
@@ -117,9 +80,6 @@ export function getUiDriverInstallHint() {
     }
     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",
@@ -130,12 +90,7 @@ function toAxeButtonName(idbButton) {
     };
     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 };
     }
@@ -146,7 +101,6 @@ 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")) {
             connectedIdbSimulators.add(udid);
@@ -158,12 +112,6 @@ async function ensureIdbConnected(udid) {
         };
     }
 }
-/**
- * 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") {
@@ -205,19 +153,11 @@ async function ensureUiDriverReady(udid) {
     }
     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;
@@ -232,15 +172,9 @@ export async function isSimctlAvailable() {
     })();
     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();
@@ -255,7 +189,6 @@ export async function listIOSSimulators(onlyBooted = false) {
         });
         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;
@@ -264,7 +197,6 @@ export async function listIOSSimulators(onlyBooted = false) {
                     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("-", ".")}`
@@ -288,7 +220,6 @@ export async function listIOSSimulators(onlyBooted = false) {
                 simulators: [],
             };
         }
-        // Sort: Booted first, then by name
         simulators.sort((a, b) => {
             if (a.state === "Booted" && b.state !== "Booted")
                 return -1;
@@ -315,11 +246,6 @@ export async function listIOSSimulators(onlyBooted = false) {
         };
     }
 }
-/**
- * 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), " +
@@ -350,9 +276,6 @@ export async function buildNoSimulatorError() {
         return base;
     }
 }
-/**
- * Get the booted simulator UDID
- */
 export async function getBootedSimulatorUdid() {
     try {
         const { stdout } = await execAsync("xcrun simctl list devices booted -j", {
@@ -374,10 +297,6 @@ export async function getBootedSimulatorUdid() {
         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", {
@@ -392,11 +311,9 @@ export async function findSimulatorByName(deviceName) {
                 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;
@@ -409,28 +326,16 @@ export async function findSimulatorByName(deviceName) {
         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();
@@ -440,7 +345,6 @@ export async function iosScreenshot(outputPath, udid) {
                 error: XCODE_MISSING_ERROR,
             };
         }
-        // Resolve target UDID (prefer Metro-connected simulator)
         const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
         if (!targetUdid) {
             return {
@@ -448,14 +352,11 @@ export async function iosScreenshot(outputPath, udid) {
                 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();
@@ -464,7 +365,6 @@ export async function iosScreenshot(outputPath, udid) {
         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, {
@@ -493,9 +393,6 @@ export async function iosScreenshot(outputPath, udid) {
         };
     }
 }
-/**
- * Install an app on an iOS simulator
- */
 export async function iosInstallApp(appPath, udid) {
     try {
         const simctlAvailable = await isSimctlAvailable();
@@ -505,14 +402,12 @@ export async function iosInstallApp(appPath, udid) {
                 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 {
@@ -521,7 +416,7 @@ export async function iosInstallApp(appPath, udid) {
             };
         }
         await execAsync(`xcrun simctl install ${targetUdid} "${appPath}"`, {
-            timeout: 120000, // 2 minute timeout for install
+            timeout: 120000,
         });
         return {
             success: true,
@@ -535,9 +430,6 @@ export async function iosInstallApp(appPath, udid) {
         };
     }
 }
-/**
- * Launch an app on an iOS simulator
- */
 export async function iosLaunchApp(bundleId, udid) {
     try {
         const simctlAvailable = await isSimctlAvailable();
@@ -547,7 +439,6 @@ export async function iosLaunchApp(bundleId, udid) {
                 error: XCODE_MISSING_ERROR,
             };
         }
-        // Resolve target UDID (prefer Metro-connected simulator)
         const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
         if (!targetUdid) {
             return {
@@ -576,9 +467,6 @@ export async function iosLaunchApp(bundleId, udid) {
         };
     }
 }
-/**
- * Open a URL in the iOS simulator
- */
 export async function iosOpenUrl(url, udid) {
     try {
         const simctlAvailable = await isSimctlAvailable();
@@ -588,7 +476,6 @@ export async function iosOpenUrl(url, udid) {
                 error: XCODE_MISSING_ERROR,
             };
         }
-        // Resolve target UDID (prefer Metro-connected simulator)
         const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
         if (!targetUdid) {
             return {
@@ -618,9 +505,6 @@ export async function iosOpenUrl(url, udid) {
         };
     }
 }
-/**
- * Terminate an app on an iOS simulator
- */
 export async function iosTerminateApp(bundleId, udid) {
     try {
         const simctlAvailable = await isSimctlAvailable();
@@ -630,7 +514,6 @@ export async function iosTerminateApp(bundleId, udid) {
                 error: XCODE_MISSING_ERROR,
             };
         }
-        // Resolve target UDID (prefer Metro-connected simulator)
         const targetUdid = udid || (await getActiveOrBootedSimulatorUdid());
         if (!targetUdid) {
             return {
@@ -653,9 +536,6 @@ export async function iosTerminateApp(bundleId, udid) {
         };
     }
 }
-/**
- * Boot an iOS simulator
- */
 export async function iosBootSimulator(udid) {
     try {
         const simctlAvailable = await isSimctlAvailable();
@@ -666,14 +546,10 @@ export async function iosBootSimulator(udid) {
             };
         }
         await execAsync(`xcrun simctl boot ${udid}`, {
-            timeout: 60000, // 1 minute timeout for boot
+            timeout: 60000,
         });
-        // Open Simulator app
         await execAsync("open -a Simulator", { timeout: 10000 }).catch(() => {
-            // Ignore if Simulator app doesn't open
         });
-        // The device inventory just changed — drop the cached copy so the next
-        // resolve/tap sees this simulator as booted without waiting out the TTL.
         const { resetDeviceDiscoveryCache } = await import("./deviceDiscovery.js");
         resetDeviceDiscoveryCache();
         return {
@@ -683,7 +559,6 @@ export async function iosBootSimulator(udid) {
     }
     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,
@@ -696,16 +571,6 @@ export async function iosBootSimulator(udid) {
         };
     }
 }
-// ============================================================================
-// 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);
@@ -716,7 +581,6 @@ export async function iosTap(x, y, options) {
         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);
             }
@@ -746,9 +610,6 @@ export async function iosTap(x, y, options) {
         };
     }
 }
-/**
- * Swipe gesture on an iOS simulator
- */
 export async function iosSwipe(startX, startY, endX, endY, options) {
     try {
         const preflight = await ensureUiDriverReady(options?.udid);
@@ -772,7 +633,6 @@ export async function iosSwipe(startX, startY, endX, endY, options) {
                 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) {
@@ -806,9 +666,6 @@ export async function iosSwipe(startX, startY, endX, endY, options) {
         };
     }
 }
-/**
- * Input text into the active field on an iOS simulator
- */
 export async function iosInputText(text, udid) {
     try {
         const preflight = await ensureUiDriverReady(udid);
@@ -816,12 +673,6 @@ export async function iosInputText(text, udid) {
             return preflight.error;
         const { driver, targetUdid } = preflight;
         if (driver === "axe") {
-            // Submit one HID event per chunk instead of AXe's default 200. Text
-            // arriving out of order has been observed on device ("Alice" landing as
-            // "Aicel", "CASEB" as "CSEBA" — in both cases the second keystroke last),
-            // and a single large submission is the plausible cause. Measured at the
-            // same latency as plain `axe type` (1432ms vs 1519ms for 19 chars), so
-            // the serialisation is free.
             await runAxe("batch", "--udid", targetUdid, "--type-chunk-size", "1", "--step", `type '${text.replace(/'/g, "'\\''")}'`);
         }
         else {
@@ -841,12 +692,8 @@ export async function iosInputText(text, udid) {
         };
     }
 }
-/**
- * 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,
@@ -887,9 +734,6 @@ export async function iosButton(button, options) {
         };
     }
 }
-/**
- * Send a key event to an iOS simulator
- */
 export async function iosKeyEvent(keycode, options) {
     try {
         const preflight = await ensureUiDriverReady(options?.udid);
@@ -926,9 +770,6 @@ export async function iosKeyEvent(keycode, options) {
         };
     }
 }
-/**
- * Send a sequence of key events to an iOS simulator
- */
 export async function iosKeySequence(keycodes, udid) {
     try {
         if (!keycodes || keycodes.length === 0) {
@@ -968,9 +809,6 @@ export async function iosKeySequence(keycodes, udid) {
         };
     }
 }
-/**
- * Format accessibility tree for human-readable output
- */
 function formatAccessibilityTree(elements, depth = 0) {
     const lines = [];
     const indent = "  ".repeat(depth);
@@ -997,25 +835,15 @@ function formatAccessibilityTree(elements, depth = 0) {
     }
     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 so repeated taps don't each incur a describe-ui call. The probe costs
- * ~200ms and ran on essentially every fiber+native tap under the old 5s TTL;
- * the inset itself only changes on rotation, so a longer TTL is safe (a rotation
- * mid-session costs at most one stale correction until the entry expires).
- */
 const SAFE_AREA_CACHE_TTL_MS = 30_000;
 const safeAreaTopCache = new Map();
-export async function getIOSSafeAreaTop(udid) {
+async function probeIOSRootFrame(udid) {
     const cacheKey = udid || "__default__";
     const cached = safeAreaTopCache.get(cacheKey);
     if (cached && cached.expires > Date.now())
-        return cached.value;
+        return cached;
     let value = 0;
+    let screen = null;
     try {
         const preflight = await ensureUiDriverReady(udid);
         if (preflight.ready) {
@@ -1033,17 +861,25 @@ export async function getIOSSafeAreaTop(udid) {
             const y = root?.frame?.y;
             if (typeof y === "number" && y > 0)
                 value = Math.round(y);
+            const w = root?.frame?.width;
+            const h = root?.frame?.height;
+            if (typeof w === "number" && w > 0 && typeof h === "number" && h > 0) {
+                screen = { width: w, height: h };
+            }
         }
     }
     catch {
-        // Fall through: value stays 0 (no correction)
     }
-    safeAreaTopCache.set(cacheKey, { value, expires: Date.now() + SAFE_AREA_CACHE_TTL_MS });
-    return value;
+    const entry = { value, screen, expires: Date.now() + SAFE_AREA_CACHE_TTL_MS };
+    safeAreaTopCache.set(cacheKey, entry);
+    return entry;
+}
+export async function getIOSSafeAreaTop(udid) {
+    return (await probeIOSRootFrame(udid)).value;
+}
+export async function getIOSScreenPointSize(udid) {
+    return (await probeIOSRootFrame(udid)).screen;
 }
-/**
- * Get accessibility info for the entire screen
- */
 export async function iosDescribeAll(udid) {
     try {
         const preflight = await ensureUiDriverReady(udid);
@@ -1061,9 +897,7 @@ export async function iosDescribeAll(udid) {
                 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 {
@@ -1079,27 +913,8 @@ export async function iosDescribeAll(udid) {
         };
     }
 }
-/**
- * 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;
@@ -1146,9 +961,6 @@ export function formatIOSSystemOverlayWarning(detection) {
         `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);
@@ -1168,7 +980,6 @@ export async function iosDescribePoint(x, y, udid) {
                 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);
@@ -1181,7 +992,6 @@ export async function iosDescribePoint(x, y, udid) {
                 elements: [],
             };
         }
-        // Format for human-readable output
         const parts = [];
         if (element.type)
             parts.push(`Type: ${element.type}`);
@@ -1211,9 +1021,6 @@ export async function iosDescribePoint(x, y, udid) {
         };
     }
 }
-/**
- * Helper to flatten nested accessibility elements
- */
 function flattenElements(elements) {
     const result = [];
     for (const el of elements) {
@@ -1224,10 +1031,6 @@ function flattenElements(elements) {
     }
     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;
@@ -1237,7 +1040,6 @@ export async function iosTapElement(options) {
                 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 {
@@ -1245,7 +1047,6 @@ export async function iosTapElement(options) {
                 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)
@@ -1265,7 +1066,6 @@ export async function iosTapElement(options) {
                 error: `No element found with ${searchTerm}`,
             };
         }
-        // Select element by index (default 0 = first match)
         if (index >= matches.length) {
             return {
                 success: false,
@@ -1273,17 +1073,14 @@ export async function iosTapElement(options) {
             };
         }
         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 {
@@ -1300,9 +1097,6 @@ export async function iosTapElement(options) {
         };
     }
 }
-/**
- * Parse IDB accessibility output into simplified element array
- */
 function parseIdbAccessibilityForFindElement(output) {
     const elements = [];
     try {
@@ -1355,14 +1149,9 @@ function parseIdbAccessibilityForFindElement(output) {
         }
     }
     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 &&
@@ -1370,10 +1159,6 @@ function isIOSElementInViewport(element, screenWidth, screenHeight) {
         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);
@@ -1384,13 +1169,9 @@ function extractIOSScreenSize(rawOutput) {
         }
     }
     catch {
-        // Fall through
     }
     return null;
 }
-/**
- * Match iOS element against find options
- */
 function matchesIOSFindElement(element, options) {
     if (options.label !== undefined) {
         if (element.label !== options.label)
@@ -1424,9 +1205,6 @@ function matchesIOSFindElement(element, options) {
     }
     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);
@@ -1456,20 +1234,6 @@ export async function iosGetUITree(udid) {
         };
     }
 }
-/**
- * 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;
@@ -1487,15 +1251,6 @@ function isAggregatorWrapper(element, query, screenSize) {
     }
     return isLongConcatenatedLabel || isFullScreenFrame;
 }
-/**
- * Find element(s) in the iOS UI tree matching the given criteria.
- *
- * `tree` lets a caller reuse an accessibility dump it already has. Each fetch
- * shells out to `axe describe-ui` (~210ms measured 2026-08-01) and the tap
- * strategy runs two or three passes with different predicates, so re-fetching
- * per pass was costing 400-600ms per accessibility tap for a tree that cannot
- * change between passes.
- */
 export async function iosFindElement(options, udid, tree) {
     try {
         if (!options.label &&
@@ -1519,8 +1274,6 @@ export async function iosFindElement(options, udid, tree) {
                 error: treeResult.error,
             };
         }
-        // Filter to viewport-visible elements first, then match criteria.
-        // This prevents selecting off-screen duplicates in scroll views / pagers.
         const screenSize = treeResult.rawOutput
             ? extractIOSScreenSize(treeResult.rawOutput)
             : null;
@@ -1528,21 +1281,9 @@ export async function iosFindElement(options, udid, tree) {
             ? 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) {
@@ -1608,20 +1349,11 @@ export async function iosFindElement(options, udid, tree) {
         };
     }
 }
-// DPR cache: UDID → device pixel ratio (never changes during session)
 const dprCache = new Map();
-/**
- * Pure calculation: DPR = screenshotPixelWidth / screenPointWidth.
- * Exported for unit testing.
- */
+const pixelSizeCache = new Map();
 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, pixelDims) {
     const cacheKey = udid || "__default__";
     const cached = dprCache.get(cacheKey);
@@ -1634,14 +1366,10 @@ export async function getDevicePixelRatio(udid, pixelDims) {
     let pixelWidth;
     let pixelHeight;
     if (pixelDims && pixelDims.width > 0 && pixelDims.height > 0) {
-        // The caller already captured a frame this turn (tap always does) — reuse
-        // its dimensions instead of shelling out for a screenshot of our own, which
-        // measured ~230ms of the ~470ms first-call cost.
         pixelWidth = pixelDims.width;
         pixelHeight = pixelDims.height;
     }
     else {
-        // 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}"`, {
@@ -1651,7 +1379,9 @@ export async function getDevicePixelRatio(udid, pixelDims) {
         pixelWidth = metadata.width;
         pixelHeight = metadata.height;
     }
-    // Try accessibility tree for exact DPR, fall back to inference
+    if (pixelWidth > 0 && pixelHeight > 0) {
+        pixelSizeCache.set(cacheKey, { width: pixelWidth, height: pixelHeight });
+    }
     const driver = getIosDriver();
     const driverOk = driver === "axe" ? await isAxeAvailable() : await isIdbAvailable();
     if (driverOk) {
@@ -1674,22 +1404,25 @@ export async function getDevicePixelRatio(udid, pixelDims) {
             }
         }
         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 async function getIOSScreenPixelSize(udid, pixelDims) {
+    const cacheKey = udid || "__default__";
+    const cached = pixelSizeCache.get(cacheKey);
+    if (cached)
+        return cached;
+    await getDevicePixelRatio(udid, pixelDims).catch(() => undefined);
+    return pixelSizeCache.get(cacheKey) ?? null;
+}
 export function clearDPRCache() {
     dprCache.clear();
+    pixelSizeCache.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;