react-native-ai-debugger 1.9.0 → 1.10.0

package/build/pro/tap.js

@@ -1,29 +1,34 @@
-import { connectedApps, imageBuffer } from "../core/state.js";
+import { connectedApps } from "../core/state.js";
 import { executeInApp } from "../core/executor.js";
 import { pressElement } from "../core/executor.js";
-import { iosTap, iosFindElement, iosScreenshot, getActiveOrBootedSimulatorUdid, findSimulatorByName, isUiDriverAvailable, getUiDriverInstallHint, getIOSSafeAreaTop } from "../core/ios.js";
-import { androidTap, androidFindElement, getDefaultAndroidDevice, androidScreenshot } from "../core/android.js";
+import { iosTap, iosFindElement, iosScreenshot, isUiDriverAvailable, getUiDriverInstallHint, getIOSSafeAreaTop } from "../core/ios.js";
+import { androidTap, androidFindElement } from "../core/android.js";
 import { compareScreenshots } from "./screenshot-diff.js";
 import { scanMetroPorts, fetchDevices, selectMainDevice } from "../core/metro.js";
 import { connectToDevice, clearReconnectionSuppression, getConnectedAppByDevice } from "../core/connection.js";
+import { resolveDeviceTarget, formatResolverError } from "../core/deviceResolver.js";
 import { notifyDriverMissing } from "../core/logbox.js";
 import { captureFailureArtifact } from "../core/failureArtifact.js";
+import { captureScreenshot, verifyAndCapture, burstCaptureAndVerify, } from "./verifyAction.js";
 export function buildVerificationExplanation(v) {
     const pct = (rate) => (rate * 100).toFixed(1) + "%";
+    const action = v.action ?? "tap";
+    const Action = action[0].toUpperCase() + action.slice(1);
+    const target = action === "swipe" ? "scroll surface" : "element";
     if (v.meaningful && !v.transientChangeDetected) {
-        return `Tap caused a visible UI change (${pct(v.changeRate)} pixel diff). The screen updated as expected.`;
+        return `${Action} caused a visible UI change (${pct(v.changeRate)} pixel diff). The screen updated as expected.`;
     }
     if (v.meaningful && v.transientChangeDetected) {
         return (`No persistent change, but transient visual feedback detected ` +
             `(frame ${v.peakFrame} peak ${pct(v.peakChangeRate || 0)} diff). ` +
-            `Tap triggered a press animation that settled back to original state.`);
+            `${Action} triggered a momentary animation that settled back to original state.`);
     }
     if (v.transientChangeDetected === false) {
         return (`No visual change detected — neither persistent nor transient across burst frames. ` +
-            `The element may not respond visually or the tap may have missed.`);
+            `The ${target} may not respond visually or the ${action} may have missed.`);
     }
     return (`No visual change detected between before and after screenshots. ` +
-        `The element may not respond visually or the tap may have missed.`);
+        `The ${target} may not respond visually or the ${action} may have missed.`);
 }
 const BURST_CHANGE_THRESHOLD = 0.005;
 export async function analyzeBurstFrames(frames, options) {
@@ -1008,21 +1013,24 @@ async function tryCoordinateStrategy(pixelX, pixelY, platform, lastScreenshot, u
         };
     }
 }
-const SETTLE_DELAY_MS = 800;
-const TAP_TIMEOUT_MS = 20000;
+const TAP_TIMEOUT_MS = 25000;
 const MIN_STRATEGY_BUDGET_MS = 500;
 // Per-strategy budget. OCR cap on Android is bumped via maxStrategyMs() because
 // the ADB screencap+pull leg has ~2s variance on real devices; iOS stays at 5s
 // where xcrun simctl screenshot is consistent.
+// Heavy strategies (fiber on deep trees with multi-depth retries, axe accessibility
+// dumps on dense iOS screens) need more headroom — previous caps produced spurious
+// timeouts that the agent read as "element missing" when the strategy simply didn't
+// get to finish. The overall TAP_TIMEOUT_MS budget still bounds the worst case.
 const MAX_STRATEGY_MS = {
-    fiber: 5000,
-    accessibility: 3000,
-    ocr: 5000,
+    fiber: 8000,
+    accessibility: 6000,
+    ocr: 6000,
     coordinate: 3000
 };
 function maxStrategyMs(strategy, platform) {
     if (strategy === "ocr" && platform === "android")
-        return 7000;
+        return 9000;
     return MAX_STRATEGY_MS[strategy] ?? 5000;
 }
 // Matches only the outer withTimeout wrapper message for a tap strategy.
@@ -1030,7 +1038,7 @@ function maxStrategyMs(strategy, platform) {
 // must NOT be classified as a tap-level timeout.
 const STRATEGY_TIMEOUT_RE = /^(fiber|accessibility|ocr|coordinate) timed out after \d+ms$/;
 export function isTapTimeout(attempted) {
-    return attempted.some((a) => STRATEGY_TIMEOUT_RE.test(a.reason) || a.reason.startsWith("Skipped —"));
+    return attempted.some((a) => a.outcome === "timeout" || a.outcome === "skipped" || STRATEGY_TIMEOUT_RE.test(a.reason) || a.reason.startsWith("Skipped —"));
 }
 function withTimeout(promise, ms, label) {
     return new Promise((resolve, reject) => {
@@ -1060,54 +1068,6 @@ function withCancelableTimeout(make, ms, label) {
         throw err;
     });
 }
-async function captureScreenshot(platform, udid) {
-    try {
-        const result = platform === "ios" ? await iosScreenshot(undefined, udid) : await androidScreenshot();
-        if (!result.success || !result.data)
-            return null;
-        return {
-            buffer: result.data,
-            width: result.originalWidth || 0,
-            height: result.originalHeight || 0,
-            scaleFactor: result.scaleFactor || 1
-        };
-    }
-    catch {
-        return null;
-    }
-}
-function screenshotToBase64(buffer) {
-    return buffer.toString("base64");
-}
-/**
- * Composite a red crosshair marker onto a screenshot at the given pixel coordinates.
- * Uses sharp + SVG so we don't need to inject into the app. Coordinates are in the
- * screenshot's own pixel space (i.e. the space the returned image uses).
- */
-async function drawTapMarker(input, x, y) {
-    try {
-        const sharp = (await import("sharp")).default;
-        const size = 72;
-        const half = size / 2;
-        const svg = `<svg width="${size}" height="${size}" xmlns="http://www.w3.org/2000/svg">
-  <circle cx="${half}" cy="${half}" r="${half - 8}" fill="none" stroke="white" stroke-width="6" opacity="0.85"/>
-  <circle cx="${half}" cy="${half}" r="${half - 8}" fill="none" stroke="#FF2D55" stroke-width="3" opacity="1"/>
-  <line x1="${half}" y1="8" x2="${half}" y2="${size - 8}" stroke="white" stroke-width="6" opacity="0.85"/>
-  <line x1="8" y1="${half}" x2="${size - 8}" y2="${half}" stroke="white" stroke-width="6" opacity="0.85"/>
-  <line x1="${half}" y1="8" x2="${half}" y2="${size - 8}" stroke="#FF2D55" stroke-width="2.5"/>
-  <line x1="8" y1="${half}" x2="${size - 8}" y2="${half}" stroke="#FF2D55" stroke-width="2.5"/>
-  <circle cx="${half}" cy="${half}" r="3" fill="#FF2D55"/>
-</svg>`;
-        const left = Math.round(x - half);
-        const top = Math.round(y - half);
-        return await sharp(input)
-            .composite([{ input: Buffer.from(svg), left, top }])
-            .toBuffer();
-    }
-    catch {
-        return input;
-    }
-}
 /**
  * Compute marker coordinates in screenshot-pixel space (what the returned PNG uses).
  * Unit rules by strategy, assuming screenshotScale = downscale factor:
@@ -1150,208 +1110,6 @@ function computeMarkerPx(args) {
         y: Math.round(convertedTo.y / scale)
     };
 }
-async function verifyAndCapture(platform, shouldVerify, shouldScreenshot, beforeBuffer, udid, beforeScaleFactor, markerPx) {
-    // Decoupled 2026-05-16 (I5): screenshot and verify are independent knobs.
-    // - shouldVerify=true:    capture after-screenshot internally, diff against beforeBuffer, return verification.
-    // - shouldScreenshot=true: also return the (marker-overlaid) image bytes in the response.
-    // - both false:           fastest path, return only a `skipped` verification stub so the agent can tell apart "ran clean" from "skipped intentionally".
-    if (!shouldVerify && !shouldScreenshot) {
-        return {
-            verification: {
-                skipped: true,
-                skippedReason: "screenshot=false, verify=false",
-                explanation: "Verification skipped (screenshot=false and verify=false)."
-            }
-        };
-    }
-    await new Promise((resolve) => setTimeout(resolve, SETTLE_DELAY_MS));
-    const after = await captureScreenshot(platform, udid);
-    if (!after) {
-        if (shouldVerify) {
-            return {
-                verification: {
-                    skipped: true,
-                    skippedReason: "after-screenshot capture failed",
-                    explanation: "Verification skipped — could not capture post-tap screenshot."
-                }
-            };
-        }
-        return {};
-    }
-    const afterWithMarker = markerPx
-        ? await drawTapMarker(after.buffer, markerPx.x, markerPx.y)
-        : after.buffer;
-    const screenshot = shouldScreenshot
-        ? {
-            image: screenshotToBase64(afterWithMarker),
-            width: after.width,
-            height: after.height,
-            scaleFactor: after.scaleFactor
-        }
-        : undefined;
-    let verification;
-    if (!shouldVerify) {
-        verification = {
-            skipped: true,
-            skippedReason: "verify=false",
-            explanation: "Verification skipped (verify=false)."
-        };
-    }
-    else if (!beforeBuffer) {
-        verification = {
-            skipped: true,
-            skippedReason: "before-screenshot unavailable",
-            explanation: "Verification skipped — could not capture pre-tap screenshot."
-        };
-    }
-    else {
-        try {
-            const rawStatusBar = platform === "ios" ? 177 : 142; // pixels in original screenshot space
-            const scale = beforeScaleFactor || after.scaleFactor || 1;
-            const statusBarHeight = Math.round(rawStatusBar / scale);
-            const diff = await compareScreenshots(beforeBuffer, after.buffer, {
-                statusBarHeight
-            });
-            verification = {
-                meaningful: diff.changed,
-                changeRate: diff.changeRate,
-                changedPixels: diff.changedPixels,
-                totalPixels: diff.totalPixels,
-                explanation: buildVerificationExplanation({
-                    meaningful: diff.changed,
-                    changeRate: diff.changeRate,
-                    changedPixels: diff.changedPixels,
-                    totalPixels: diff.totalPixels
-                })
-            };
-        }
-        catch (err) {
-            verification = {
-                skipped: true,
-                skippedReason: `diff failed: ${err instanceof Error ? err.message : String(err)}`,
-                explanation: "Verification skipped — pixel diff threw."
-            };
-        }
-    }
-    const verifyGroupId = `verify-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    if (beforeBuffer) {
-        imageBuffer.add({
-            id: `${verifyGroupId}-before`,
-            image: beforeBuffer,
-            timestamp: Date.now(),
-            source: "tap-verify",
-            groupId: verifyGroupId,
-            metadata: { phase: "before" }
-        });
-    }
-    imageBuffer.add({
-        id: `${verifyGroupId}-after`,
-        image: afterWithMarker,
-        timestamp: Date.now(),
-        source: "tap-verify",
-        groupId: verifyGroupId,
-        metadata: { phase: "after", changeRate: verification?.changeRate }
-    });
-    return { screenshot, verification, afterBuffer: after.buffer, afterWithMarkerBuffer: afterWithMarker };
-}
-// --- Burst Capture ---
-const BURST_FRAME_COUNT = 4;
-const BURST_FRAME_INTERVAL_MS = 150;
-async function burstCaptureAndVerify(platform, beforeBuffer, udid, beforeScaleFactor, markerPx) {
-    if (!beforeBuffer)
-        return {};
-    const frames = [beforeBuffer];
-    let capturedScaleFactor = beforeScaleFactor || 1;
-    for (let i = 0; i < BURST_FRAME_COUNT; i++) {
-        await new Promise((resolve) => setTimeout(resolve, BURST_FRAME_INTERVAL_MS));
-        const capture = await captureScreenshot(platform, udid);
-        if (capture) {
-            frames.push(capture.buffer);
-            if (i === 0)
-                capturedScaleFactor = capture.scaleFactor || capturedScaleFactor;
-        }
-    }
-    if (frames.length < 2)
-        return {};
-    const rawStatusBar = platform === "ios" ? 177 : 142; // pixels in original screenshot space
-    const statusBarHeight = Math.round(rawStatusBar / capturedScaleFactor);
-    // Run the diff on clean frames (no marker) so the cross doesn't register as change.
-    const analysis = await analyzeBurstFrames(frames, { statusBarHeight });
-    // Apply marker to post-tap frames only (frames[0] is the before state).
-    const markedFrames = [];
-    for (let i = 0; i < frames.length; i++) {
-        if (markerPx && i > 0) {
-            markedFrames.push(await drawTapMarker(frames[i], markerPx.x, markerPx.y));
-        }
-        else {
-            markedFrames.push(frames[i]);
-        }
-    }
-    const groupId = `burst-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    for (let i = 0; i < markedFrames.length; i++) {
-        imageBuffer.add({
-            id: `${groupId}-f${i}`,
-            image: markedFrames[i],
-            timestamp: Date.now(),
-            source: "tap-burst",
-            groupId,
-            metadata: {
-                frameIndex: i,
-                isBefore: i === 0,
-                changeRate: i === 0 ? 0 : analysis.framesWithChange.includes(i) ? analysis.peakChangeRate : 0
-            }
-        });
-    }
-    imageBuffer.addGroup({
-        groupId,
-        intent: "tap-verification",
-        source: "tap-burst",
-        timestamp: Date.now(),
-        frameCount: frames.length,
-        summary: {
-            peakChangeRate: analysis.peakChangeRate,
-            peakFrame: analysis.peakFrame,
-            framesWithChange: analysis.framesWithChange,
-            transientChangeDetected: analysis.transientChangeDetected,
-            persistentChangeRate: analysis.persistentChangeRate
-        }
-    });
-    // Get dimensions from the last frame using sharp
-    const sharp = (await import("sharp")).default;
-    const meta = await sharp(markedFrames[markedFrames.length - 1]).metadata();
-    const screenshot = {
-        image: screenshotToBase64(markedFrames[markedFrames.length - 1]),
-        width: meta.width || 0,
-        height: meta.height || 0,
-        scaleFactor: 1
-    };
-    const verification = {
-        meaningful: analysis.meaningful,
-        changeRate: analysis.persistentChangeRate,
-        changedPixels: 0,
-        totalPixels: 0,
-        transientChangeDetected: analysis.transientChangeDetected,
-        peakChangeRate: analysis.peakChangeRate,
-        peakFrame: analysis.peakFrame,
-        burstGroupId: groupId,
-        explanation: buildVerificationExplanation({
-            meaningful: analysis.meaningful,
-            changeRate: analysis.persistentChangeRate,
-            changedPixels: 0,
-            totalPixels: 0,
-            transientChangeDetected: analysis.transientChangeDetected,
-            peakChangeRate: analysis.peakChangeRate,
-            peakFrame: analysis.peakFrame
-        })
-    };
-    const lastFrameIdx = frames.length - 1;
-    return {
-        screenshot,
-        verification,
-        afterBuffer: frames[lastFrameIdx],
-        afterWithMarkerBuffer: markedFrames[lastFrameIdx]
-    };
-}
 // D2 (Step 6): in-memory ring buffer of recent coord-strategy artifact keys
 // `${round(x/20)}:${round(y/20)}`. Entries expire after 60s. The first
 // failed coord tap at a grid cell uploads its artifact; retries within the
@@ -1478,7 +1236,6 @@ async function captureTapArtifact(ctx) {
             chosenElement: null,
             screenshots: {
                 before: ctx.screenshotBuffer ?? null,
-                after: ctx.afterBuffer ?? null,
                 afterWithMarker: ctx.afterWithMarker ?? null
             },
             deviceMeta: {
@@ -1550,67 +1307,16 @@ export async function tap(options) {
     }
     // Native mode: bypass React Native connection, tap directly via ADB/simctl
     if (options.native && hasCoordinates) {
-        let platform = options.platform;
-        // Explicit udid forces iOS targeting. If platform is also explicit and conflicts,
-        // surface a clear error rather than silently overriding.
-        if (options.udid && platform === "android") {
+        const nativeResolved = await resolveDeviceTarget(options.device);
+        if (!nativeResolved.ok) {
             return {
                 success: false,
                 query,
-                error: 'udid is only valid for iOS. Got platform: "android".'
+                error: formatResolverError(nativeResolved.error)
             };
         }
-        // Auto-detect platform if not specified
-        let nativeUdid;
-        if (options.udid) {
-            platform = "ios";
-            nativeUdid = options.udid;
-        }
-        else if (!platform) {
-            // If `device` is provided, try resolving it as an iOS simulator name first —
-            // otherwise the auto-detect would fall through to getActiveOrBootedSimulatorUdid()
-            // and ignore the caller's targeting hint when multiple simulators are booted.
-            const deviceMatchedUdid = options.device
-                ? await findSimulatorByName(options.device).catch(() => null)
-                : null;
-            if (deviceMatchedUdid) {
-                platform = "ios";
-                nativeUdid = deviceMatchedUdid;
-            }
-            else {
-                const [androidDevice, iosSimulator] = await Promise.all([
-                    getDefaultAndroidDevice().catch(() => null),
-                    getActiveOrBootedSimulatorUdid().catch(() => null)
-                ]);
-                if (androidDevice && iosSimulator) {
-                    return {
-                        success: false,
-                        query,
-                        error: 'Multiple platforms detected (both Android and iOS). Specify platform: "android" or platform: "ios" to target the correct device.'
-                    };
-                }
-                if (androidDevice) {
-                    platform = "android";
-                }
-                else if (iosSimulator) {
-                    platform = "ios";
-                    nativeUdid = iosSimulator;
-                }
-                else {
-                    return {
-                        success: false,
-                        query,
-                        error: "No Android device or iOS simulator found. Connect a device or start a simulator."
-                    };
-                }
-            }
-        }
-        else if (platform === "ios") {
-            nativeUdid =
-                (options.device ? await findSimulatorByName(options.device) : null) ??
-                    (await getActiveOrBootedSimulatorUdid()) ??
-                    undefined;
-        }
+        const platform = nativeResolved.target.platform;
+        const nativeUdid = nativeResolved.target.iosUdid;
         const nativeShouldScreenshot = options.screenshot !== false;
         // Decoupled (I5, 2026-05-16): verify runs even when image bytes aren't returned.
         const nativeShouldVerify = options.verify !== false;
@@ -1668,12 +1374,26 @@ export async function tap(options) {
                 screenshotScale: nativeScreenshotMeta?.scaleFactor || 1
             });
             if (options.burst && nativeShouldVerify && nativeBeforeBuffer) {
-                ({ screenshot, verification } = await burstCaptureAndVerify(platform, nativeBeforeBuffer, nativeUdid, nativeScreenshotMeta?.scaleFactor, nativeMarker));
+                ({ screenshot, verification } = await burstCaptureAndVerify({
+                    platform,
+                    beforeBuffer: nativeBeforeBuffer,
+                    udid: nativeUdid,
+                    beforeScaleFactor: nativeScreenshotMeta?.scaleFactor,
+                    markerPx: nativeMarker
+                }));
                 if (!nativeShouldScreenshot)
                     screenshot = undefined;
             }
             else {
-                ({ screenshot, verification } = await verifyAndCapture(platform, nativeShouldVerify, nativeShouldScreenshot, nativeBeforeBuffer, nativeUdid, nativeScreenshotMeta?.scaleFactor, nativeMarker));
+                ({ screenshot, verification } = await verifyAndCapture({
+                    platform,
+                    shouldVerify: nativeShouldVerify,
+                    shouldScreenshot: nativeShouldScreenshot,
+                    beforeBuffer: nativeBeforeBuffer,
+                    udid: nativeUdid,
+                    beforeScaleFactor: nativeScreenshotMeta?.scaleFactor,
+                    markerPx: nativeMarker
+                }));
             }
             return formatTapSuccess({
                 method: "native-coordinate",
@@ -1691,46 +1411,48 @@ export async function tap(options) {
             suggestion: `Take a screenshot (${platform === "ios" ? "ios_screenshot" : "android_screenshot"}) to verify coordinates.`
         });
     }
-    // udid is iOS-only. Reject early if combined with android.
-    if (options.udid && options.platform === "android") {
+    // Resolve device target via the unified resolver. Replaces the prior chain
+    // of (udid → connectedApp → findSimulatorByName) lookups and the standalone
+    // "no platform → probe OS for devices" branch. Returns a structured error
+    // when ambiguous; surface that to the caller so they can disambiguate.
+    const resolved = await resolveDeviceTarget(options.device);
+    if (!resolved.ok) {
         return {
             success: false,
             query,
-            error: 'udid is only valid for iOS. Got platform: "android".'
+            error: formatResolverError(resolved.error)
         };
     }
-    // Detect available capabilities
+    const platform = resolved.target.platform;
+    let targetUdid = resolved.target.iosUdid;
+    // Pick the connected app to bias strategy selection. Prefer the registry
+    // entry whose identifier matches the resolved target; fall back to a
+    // device-name match (handy when registry entries lack identifiers yet);
+    // last resort is the first connected app on the matching platform.
     const allApps = Array.from(connectedApps.values());
     let hasMetro = allApps.length > 0;
-    // Pick the connected app to bias platform/strategy selection.
-    // Precedence:
-    //   1. udid → match the iOS app whose simulatorUdid equals udid (if any)
-    //   2. device → substring match against connected app's deviceName/title
-    //   3. platform → first app on that platform
-    //   4. first connected app
     let app;
-    if (options.udid) {
-        app = allApps.find((a) => a.platform === "ios" && a.simulatorUdid === options.udid);
+    if (resolved.target.iosUdid) {
+        app = allApps.find((a) => a.platform === "ios" && a.simulatorUdid === resolved.target.iosUdid);
+    }
+    else if (resolved.target.androidSerial) {
+        app = allApps.find((a) => a.platform === "android" && a.adbSerial === resolved.target.androidSerial);
     }
     if (!app && options.device) {
         try {
             app = getConnectedAppByDevice(options.device) ?? undefined;
         }
-        catch (err) {
-            // getConnectedAppByDevice throws on ambiguous matches — surface that to the caller
-            return {
-                success: false,
-                query,
-                error: err instanceof Error ? err.message : String(err)
-            };
+        catch {
+            // getConnectedAppByDevice throws on ambiguous matches; the resolver
+            // would have already returned that error, so reaching here means
+            // the resolved target's identifier just doesn't appear in the
+            // registry yet — fall through to the platform-first pick below.
         }
     }
     if (!app) {
-        app = options.platform
-            ? (allApps.find((a) => a.platform === options.platform) ?? allApps[0])
-            : allApps[0];
+        app = allApps.find((a) => a.platform === platform) ?? allApps[0];
     }
-    // Try to auto-connect to Metro (for fiber strategy), but don't fail if it doesn't work
+    // Try to auto-connect to Metro (for fiber strategy), but don't fail if it doesn't work.
     if (!hasMetro) {
         try {
             await withTimeout((async () => {
@@ -1747,56 +1469,15 @@ export async function tap(options) {
             })(), Math.min(remainingMs(), 3000), "auto-connect");
             const apps = Array.from(connectedApps.values());
             hasMetro = apps.length > 0;
-            app = apps[0];
+            app = apps.find((a) => a.platform === platform) ?? apps[0];
+            if (platform === "ios" && !targetUdid) {
+                targetUdid = app?.simulatorUdid ?? targetUdid;
+            }
         }
         catch {
             // Auto-connect failed — Metro-dependent strategies will be skipped
         }
     }
-    // Detect platform — from Metro connection or from available devices
-    let platform = options.platform;
-    if (!platform) {
-        if (app) {
-            platform = app.platform;
-        }
-        else {
-            // No Metro — detect from available devices
-            const [androidDevice, iosSimulator] = await Promise.all([
-                getDefaultAndroidDevice().catch(() => null),
-                getActiveOrBootedSimulatorUdid().catch(() => null)
-            ]);
-            if (androidDevice && iosSimulator) {
-                return {
-                    success: false,
-                    query,
-                    error: 'Both iOS and Android devices detected but no Metro connection. Specify platform="ios" or platform="android".'
-                };
-            }
-            if (androidDevice)
-                platform = "android";
-            else if (iosSimulator)
-                platform = "ios";
-        }
-    }
-    if (!platform) {
-        return {
-            success: false,
-            query,
-            error: "No devices found. Boot a simulator or connect an Android device."
-        };
-    }
-    // Resolve target iOS simulator UDID.
-    // Precedence: explicit udid → connected app's simulatorUdid → findSimulatorByName(device or app deviceName)
-    // This ensures taps go to the correct device when multiple simulators are booted.
-    let targetUdid;
-    if (platform === "ios") {
-        targetUdid =
-            options.udid ??
-                app?.simulatorUdid ??
-                (options.device ? await findSimulatorByName(options.device) : null) ??
-                (app?.deviceInfo?.deviceName ? await findSimulatorByName(app.deviceInfo.deviceName) : null) ??
-                undefined;
-    }
     const deviceName = app?.deviceInfo?.deviceName;
     // Determine strategies
     const strategies = getAvailableStrategies(query, strategy);
@@ -1813,14 +1494,16 @@ export async function tap(options) {
         if (strat === "fiber" && !hasMetro) {
             attempted.push({
                 strategy: "fiber",
-                reason: "Skipped — no Metro connection (required for fiber)"
+                reason: "Skipped — no Metro connection (required for fiber)",
+                outcome: "skipped"
             });
             return false;
         }
         if (uiDriverMissing && UI_DRIVER_REQUIRED_STRATEGIES.includes(strat)) {
             attempted.push({
                 strategy: strat,
-                reason: "Skipped — iOS UI driver is not installed (required for iOS tap/accessibility/OCR)"
+                reason: "Skipped — iOS UI driver is not installed (required for iOS tap/accessibility/OCR)",
+                outcome: "skipped"
             });
             return false;
         }
@@ -1845,10 +1528,12 @@ export async function tap(options) {
     // capture cost is paid either way; bandwidth cost is what `screenshot` toggles.
     const shouldScreenshot = options.screenshot !== false;
     const canVerify = options.verify !== false;
-    // Capture "before" screenshot for verification
+    // Capture "before" screenshot. Always attempted (independent of canVerify)
+    // so failure artifacts always carry a before.png — the diagnostic value of
+    // the before frame doesn't depend on whether we run the post-tap diff.
     let beforeBuffer = null;
     let beforeScaleFactor;
-    if (canVerify) {
+    {
         const before = await captureScreenshot(platform, targetUdid);
         beforeBuffer = before?.buffer || null;
         beforeScaleFactor = before?.scaleFactor;
@@ -1876,7 +1561,8 @@ export async function tap(options) {
         if (remaining < MIN_STRATEGY_BUDGET_MS) {
             attempted.push({
                 strategy: strat,
-                reason: `Skipped — only ${remaining}ms remaining (budget ${TAP_TIMEOUT_MS}ms)`
+                reason: `Skipped — only ${remaining}ms remaining (budget ${TAP_TIMEOUT_MS}ms)`,
+                outcome: "skipped"
             });
             continue;
         }
@@ -1949,7 +1635,13 @@ export async function tap(options) {
                 // Fall through past the catch block to the success handler.
             }
             else {
-                attempted.push({ strategy: strat, reason });
+                // Classify the throw: a strategy-level timeout means "result UNKNOWN"
+                // (the strategy didn't finish), distinct from "ran clean and found
+                // nothing". Agents must not infer absence from timeouts. The
+                // `outcome` field carries that distinction; `reason` stays the raw
+                // message so existing log-matchers / classifiers keep working.
+                const outcome = STRATEGY_TIMEOUT_RE.test(reason) ? "timeout" : "error";
+                attempted.push({ strategy: strat, reason, outcome });
                 continue;
             }
         }
@@ -1960,7 +1652,6 @@ export async function tap(options) {
                 ocrPrewarmCtrl?.abort();
             let screenshot;
             let verification;
-            let afterBuffer;
             let afterWithMarkerBuffer;
             let dprForMarker;
             if (platform === "ios") {
@@ -1981,15 +1672,35 @@ export async function tap(options) {
                 devicePixelRatio: dprForMarker
             });
             if (options.burst && canVerify && beforeBuffer) {
-                ({ screenshot, verification, afterBuffer, afterWithMarkerBuffer } = await burstCaptureAndVerify(platform, beforeBuffer, targetUdid, beforeScaleFactor, strategyMarker));
+                ({ screenshot, verification, afterWithMarkerBuffer } = await burstCaptureAndVerify({
+                    platform,
+                    beforeBuffer,
+                    udid: targetUdid,
+                    beforeScaleFactor,
+                    markerPx: strategyMarker
+                }));
                 // Burst always produces a screenshot for diff visualization. Drop the
-                // bytes when the caller didn't ask for them — frames are still in
-                // imageBuffer (accessible via get_images(groupId=verification.burstGroupId)).
-                if (!shouldScreenshot)
+                // bytes when the caller didn't ask for them AND the tap was meaningful
+                // — keeping the screenshot on unmeaningful taps saves the agent a
+                // round-trip when it needs to diagnose. Frames remain in imageBuffer
+                // either way (accessible via get_images(groupId=verification.burstGroupId)).
+                if (!shouldScreenshot && verification?.meaningful !== false)
                     screenshot = undefined;
             }
             else {
-                ({ screenshot, verification, afterBuffer, afterWithMarkerBuffer } = await verifyAndCapture(platform, canVerify, shouldScreenshot, beforeBuffer, targetUdid, beforeScaleFactor, strategyMarker));
+                ({ screenshot, verification, afterWithMarkerBuffer } = await verifyAndCapture({
+                    platform,
+                    shouldVerify: canVerify,
+                    shouldScreenshot: true,
+                    beforeBuffer,
+                    udid: targetUdid,
+                    beforeScaleFactor,
+                    markerPx: strategyMarker
+                }));
+                // Mirror the burst-path gate: drop the screenshot only when the
+                // caller didn't ask for it AND the tap was meaningful.
+                if (!shouldScreenshot && verification?.meaningful !== false)
+                    screenshot = undefined;
             }
             if (screenshot && app) {
                 app.lastScreenshot = {
@@ -2014,7 +1725,9 @@ export async function tap(options) {
             });
             // Capture an artifact for "successful but unmeaningful" taps so we can
             // diagnose taps that landed wrong or hit non-responsive elements.
-            if (verification && !verification.skipped && (verification.changeRate ?? 1) < 0.001) {
+            // Uses the same `meaningful` flag the agent sees so dashboard outcomes
+            // stay consistent with what the caller observed.
+            if (verification && !verification.skipped && verification.meaningful === false) {
                 const unmeaningfulSignals = await captureTapArtifact({
                     query,
                     outcome: "unmeaningful",
@@ -2024,7 +1737,6 @@ export async function tap(options) {
                     deviceName,
                     screenshotMeta: screenshot ? { width: screenshot.width, height: screenshot.height } : undefined,
                     screenshotBuffer: beforeBuffer,
-                    afterBuffer: afterBuffer ?? null,
                     afterWithMarker: afterWithMarkerBuffer ?? null,
                     chosenTapPoint: strategyMarker ? { x: strategyMarker.x, y: strategyMarker.y } : null,
                     verification,
@@ -2034,7 +1746,19 @@ export async function tap(options) {
             }
             return successResult;
         }
-        attempted.push({ strategy: strat, reason: result.reason });
+        // Classify the strategy's non-success result. The reason string carries
+        // the diagnostic from the strategy; outcome lets agents branch on category
+        // without parsing prose. "invisible" / "ambiguous" are pinned by substring
+        // matches the fiber strategy emits via pressables.ts.
+        const reasonStr = result.reason || "";
+        let attemptOutcome = "not-found";
+        if (result.ambiguous)
+            attemptOutcome = "ambiguous";
+        else if (reasonStr.indexOf("but none are visible") !== -1)
+            attemptOutcome = "invisible";
+        else if (STRATEGY_TIMEOUT_RE.test(reasonStr))
+            attemptOutcome = "timeout";
+        attempted.push({ strategy: strat, reason: reasonStr, outcome: attemptOutcome });
         // If fiber found an element with measured coordinates, do a native tap directly
         if (strat === "fiber" && result.convertedTo && result.pressed) {
             try {
@@ -2089,11 +1813,27 @@ export async function tap(options) {
                     androidDensityScale: fnDensity
                 });
                 if (options.burst && canVerify && beforeBuffer) {
-                    ({ screenshot, verification } = await burstCaptureAndVerify(platform, beforeBuffer, targetUdid, beforeScaleFactor, fiberMarker));
+                    ({ screenshot, verification } = await burstCaptureAndVerify({
+                        platform,
+                        beforeBuffer,
+                        udid: targetUdid,
+                        beforeScaleFactor,
+                        markerPx: fiberMarker
+                    }));
                 }
                 else {
-                    ({ screenshot, verification } = await verifyAndCapture(platform, canVerify, shouldScreenshot, beforeBuffer, targetUdid, beforeScaleFactor, fiberMarker));
+                    ({ screenshot, verification } = await verifyAndCapture({
+                        platform,
+                        shouldVerify: canVerify,
+                        shouldScreenshot: true,
+                        beforeBuffer,
+                        udid: targetUdid,
+                        beforeScaleFactor,
+                        markerPx: fiberMarker
+                    }));
                 }
+                if (!shouldScreenshot && verification?.meaningful !== false)
+                    screenshot = undefined;
                 if (screenshot && app) {
                     app.lastScreenshot = {
                         originalWidth: screenshot.width,
@@ -2124,7 +1864,7 @@ export async function tap(options) {
         // Do NOT fall through to other strategies (they can't resolve ambiguity).
         if (result.matches && result.ambiguous) {
             const { screenshot: matchScreenshot } = shouldScreenshot
-                ? await verifyAndCapture(platform, false, true, null, targetUdid)
+                ? await verifyAndCapture({ platform, shouldVerify: false, shouldScreenshot: true, beforeBuffer: null, udid: targetUdid })
                 : { screenshot: undefined };
             if (matchScreenshot && app) {
                 app.lastScreenshot = {
@@ -2151,9 +1891,22 @@ export async function tap(options) {
     // itself ran out of time.
     const hitTimeout = isTapTimeout(attempted);
     const elapsed = TAP_TIMEOUT_MS - remainingMs();
-    const suggestion = buildSuggestion(query, strategies, platform);
+    // If fiber located the element but visibility filtered it out, prepend a
+    // scroll-or-dismiss hint so the agent doesn't waste a turn assuming the
+    // testID/component is missing.
+    const fiberSawInvisible = attempted.some(a => a.strategy === "fiber" && a.outcome === "invisible");
+    const allTimedOut = attempted.length > 0 && attempted.every(a => a.outcome === "timeout" || a.outcome === "skipped");
+    let suggestion = buildSuggestion(query, strategies, platform);
+    if (fiberSawInvisible) {
+        suggestion = `Element exists in the React tree but is not on screen. Try scrolling it into view with swipe(), dismiss any overlay covering it, or wait for layout to settle. ` + suggestion;
+    }
+    else if (allTimedOut) {
+        // No strategy got to a definitive answer — don't let the agent conclude
+        // the element is missing. Steer toward retry or a different strategy.
+        suggestion = `All strategies timed out — the element's presence is UNKNOWN. Retry the tap (transient slowness is common on dense screens), or try a different strategy explicitly (e.g. strategy='fiber' if accessibility timed out). ` + suggestion;
+    }
     const { screenshot: failScreenshot } = shouldScreenshot
-        ? await verifyAndCapture(platform, false, true, null, targetUdid)
+        ? await verifyAndCapture({ platform, shouldVerify: false, shouldScreenshot: true, beforeBuffer: null, udid: targetUdid })
         : { screenshot: undefined };
     if (failScreenshot && app) {
         app.lastScreenshot = {
@@ -2162,10 +1915,22 @@ export async function tap(options) {
             scaleFactor: failScreenshot.scaleFactor
         };
     }
+    // Pick the right error framing: a definitive "not found" is different from
+    // "all strategies timed out — we don't know whether it exists".
+    let errorOverride;
+    if (hitTimeout) {
+        errorOverride = `Tap timed out after ${elapsed}ms (budget ${TAP_TIMEOUT_MS}ms)`;
+    }
+    else if (allTimedOut) {
+        errorOverride = `All tap strategies timed out before completing — element presence is UNKNOWN`;
+    }
+    else if (fiberSawInvisible) {
+        errorOverride = `Element matches the query but is not visible on screen`;
+    }
     const failureResult = formatTapFailure({
         query,
         attempted,
-        error: hitTimeout ? `Tap timed out after ${elapsed}ms (budget ${TAP_TIMEOUT_MS}ms)` : undefined,
+        error: errorOverride,
         suggestion,
         device: deviceName,
         screenshot: failScreenshot
@@ -2217,7 +1982,7 @@ function buildSuggestion(query, triedStrategies, platform) {
     // the error) keeps the existing message stable for tooling that parses it.
     if (query.testID && looksLikeVirtualizedListItem(query.testID)) {
         suggestions.push("testID looks like a virtualized list item — scroll it on-screen first " +
-            `(${platform === "ios" ? "ios_button arrow keys / swipe" : "android_swipe"}) before tapping`);
+            `(swipe()${platform === "ios" ? " or ios_button arrow keys" : ""}) before tapping`);
     }
     suggestions.push(`Take a screenshot (${platform === "ios" ? "ios_screenshot" : "android_screenshot"}) ` +
         "to verify the element is visible, then use x/y coordinates");