react-native-ai-debugger 1.9.1 → 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,7 +1013,6 @@ async function tryCoordinateStrategy(pixelX, pixelY, platform, lastScreenshot, u
         };
     }
 }
-const SETTLE_DELAY_MS = 800;
 const TAP_TIMEOUT_MS = 25000;
 const MIN_STRATEGY_BUDGET_MS = 500;
 // Per-strategy budget. OCR cap on Android is bumped via maxStrategyMs() because
@@ -1064,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:
@@ -1154,209 +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;
-    // Construct the screenshot eagerly. Caller decides whether to drop it
-    // based on `shouldScreenshot` AND the verification outcome — when a tap
-    // is unmeaningful we surface the image regardless so the agent can
-    // diagnose without an extra round-trip.
-    const screenshot = {
-        image: screenshotToBase64(afterWithMarker),
-        width: after.width,
-        height: after.height,
-        scaleFactor: after.scaleFactor
-    };
-    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, 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,
-        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
@@ -1554,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;
@@ -1672,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",
@@ -1695,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 () => {
@@ -1751,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);
@@ -1995,7 +1672,13 @@ export async function tap(options) {
                 devicePixelRatio: dprForMarker
             });
             if (options.burst && canVerify && beforeBuffer) {
-                ({ screenshot, verification, 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 AND the tap was meaningful
                 // — keeping the screenshot on unmeaningful taps saves the agent a
@@ -2005,8 +1688,15 @@ export async function tap(options) {
                     screenshot = undefined;
             }
             else {
-                ({ screenshot, verification, afterWithMarkerBuffer } = await verifyAndCapture(platform, canVerify, 
-                /* shouldScreenshot */ true, 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)
@@ -2123,11 +1813,24 @@ 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 */ true, 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;
@@ -2161,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 = {
@@ -2195,7 +1898,7 @@ export async function tap(options) {
     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 (${platform === "ios" ? "ios_swipe / arrow keys" : "android_swipe"}), dismiss any overlay covering it, or wait for layout to settle. ` + suggestion;
+        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
@@ -2203,7 +1906,7 @@ export async function tap(options) {
         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 = {
@@ -2279,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");