react-native-ai-debugger 1.6.16 → 1.8.0

package/build/pro/tap.js

@@ -90,6 +90,76 @@ export function hasProblematicUnicode(text) {
 function normalizeForMatch(text) {
     return text.trim().replace(/\s+/g, " ").toLowerCase();
 }
+export function reconstructLinesFromWords(words) {
+    if (!words.length)
+        return [];
+    const sorted = [...words].sort((a, b) => a.bbox.y0 - b.bbox.y0);
+    const groups = [];
+    let current = [];
+    let runningMidY = -Infinity;
+    let runningHeight = 0;
+    for (const w of sorted) {
+        const wMid = (w.bbox.y0 + w.bbox.y1) / 2;
+        const wHeight = Math.max(1, w.bbox.y1 - w.bbox.y0);
+        const tolerance = Math.min(wHeight, runningHeight || wHeight) * 0.5;
+        if (current.length === 0 || Math.abs(wMid - runningMidY) <= tolerance) {
+            current.push(w);
+            const n = current.length;
+            runningMidY = runningMidY === -Infinity ? wMid : (runningMidY * (n - 1) + wMid) / n;
+            runningHeight = (runningHeight * (n - 1) + wHeight) / n;
+        }
+        else {
+            groups.push(current);
+            current = [w];
+            runningMidY = wMid;
+            runningHeight = wHeight;
+        }
+    }
+    if (current.length > 0)
+        groups.push(current);
+    return groups.map(group => {
+        const sortedWords = [...group].sort((a, b) => a.bbox.x0 - b.bbox.x0);
+        const text = sortedWords.map(w => w.text).join(" ");
+        const x0 = Math.min(...sortedWords.map(w => w.bbox.x0));
+        const y0 = Math.min(...sortedWords.map(w => w.bbox.y0));
+        const x1 = Math.max(...sortedWords.map(w => w.bbox.x1));
+        const y1 = Math.max(...sortedWords.map(w => w.bbox.y1));
+        const tapX = sortedWords.reduce((s, w) => s + w.tapCenter.x, 0) / sortedWords.length;
+        const tapY = sortedWords.reduce((s, w) => s + w.tapCenter.y, 0) / sortedWords.length;
+        return { text, bbox: { x0, y0, x1, y1 }, tapCenter: { x: tapX, y: tapY }, words: sortedWords };
+    });
+}
+/**
+ * Narrow the tap point to just the words that produced the substring match.
+ * Without this, a query for "Remotely" against a reconstructed line "Yes Remotely No"
+ * would tap at the line's centroid (middle of "Remotely" in this case, but easily wrong
+ * for asymmetric layouts). Tracks character offsets through the joined text so we know
+ * which constituent words contributed to the matched range.
+ */
+function refineTapCenterToMatchingWords(line, normalizedNeedle) {
+    const normalizedFull = normalizeForMatch(line.text);
+    const startChar = normalizedFull.indexOf(normalizedNeedle);
+    if (startChar < 0)
+        return line.tapCenter;
+    const endChar = startChar + normalizedNeedle.length;
+    let offset = 0;
+    const covered = [];
+    for (const w of line.words) {
+        const wNorm = normalizeForMatch(w.text);
+        const wordStart = offset;
+        const wordEnd = offset + wNorm.length;
+        // Word overlaps the matched range
+        if (wordEnd > startChar && wordStart < endChar) {
+            covered.push(w);
+        }
+        offset = wordEnd + 1; // +1 for the joining space
+    }
+    if (covered.length === 0)
+        return line.tapCenter;
+    const tapX = covered.reduce((s, w) => s + w.tapCenter.x, 0) / covered.length;
+    const tapY = covered.reduce((s, w) => s + w.tapCenter.y, 0) / covered.length;
+    return { x: tapX, y: tapY };
+}
 export function findOcrMatch(ocrResult, query) {
     const needle = normalizeForMatch(query);
     if (!needle)
@@ -108,6 +178,19 @@ export function findOcrMatch(ocrResult, query) {
     const substringWord = words.find((w) => normalizeForMatch(w.text).includes(needle));
     if (substringWord)
         return { text: substringWord.text, tapCenter: substringWord.tapCenter };
+    // Fall through to phrases reconstructed from word detections. Tap point is
+    // refined to only the words covering the matched substring, so a query for
+    // "Continue with Google" inside "[icon] Continue with Google" lands on the
+    // text run instead of the line centroid (and won't drift onto the icon).
+    const reconstructed = reconstructLinesFromWords(words);
+    const exactRecon = reconstructed.find((l) => normalizeForMatch(l.text) === needle);
+    if (exactRecon) {
+        return { text: exactRecon.text, tapCenter: refineTapCenterToMatchingWords(exactRecon, needle) };
+    }
+    const substringRecon = reconstructed.find((l) => normalizeForMatch(l.text).includes(needle));
+    if (substringRecon) {
+        return { text: substringRecon.text, tapCenter: refineTapCenterToMatchingWords(substringRecon, needle) };
+    }
     return null;
 }
 export function getAvailableStrategies(query, strategy) {
@@ -240,16 +323,29 @@ export async function getCurrentScreen() {
 }
 export function formatTapSuccess(data) {
     const { screenshot, verification, ...rest } = data;
+    // I3 (2026-05-16): when the tap landed on a TextInput-like element and the diff
+    // reports no visual change, that does NOT mean the focus failed. iOS simulators with
+    // the hardware keyboard connected (Cmd+K) suppress the on-screen keyboard, so the
+    // input is focused but the screen looks identical. Surface this so the agent doesn't
+    // assume the tap missed and retry the wrong thing.
+    const isTextInputComponent = (() => {
+        const name = data.component ?? data.pressed ?? "";
+        return /textfield|textinput|edittext|searchfield/i.test(name);
+    })();
+    const note = verification && !verification.skipped && verification.meaningful === false && isTextInputComponent
+        ? "TextInput focused but no visual change detected. If the simulator has a hardware keyboard connected (Cmd+K), the software keyboard is suppressed even though the input is focused — proceed with text entry via ios_input_text / android_input_text."
+        : undefined;
     return {
         success: true,
         ...rest,
         ...(verification && { verification }),
-        ...(screenshot && { screenshot })
+        ...(screenshot && { screenshot }),
+        ...(note && { warning: note })
     };
 }
 export function formatTapFailure(data) {
     const errorMsg = data.error || buildErrorMessage(data.query);
-    const warning = data.verification && !data.verification.meaningful
+    const warning = data.verification && !data.verification.skipped && data.verification.meaningful === false
         ? "Tap executed but no visual change detected. The element may not exist at these coordinates. Examine the screenshot to verify and retry with adjusted coordinates."
         : undefined;
     const lastStrategy = data.attempted.length > 0 ? data.attempted[data.attempted.length - 1].strategy : undefined;
@@ -279,11 +375,41 @@ function buildErrorMessage(query) {
         parts.push(`component="${query.component}"`);
     return `No element found matching ${parts.join(", ")}`;
 }
+// I2 (2026-05-16): RN component composition routinely produces N matches at the same
+// coordinates for the same testID/text (e.g. ThemedButton → TouchableOpacity → TouchableOpacity).
+// The C1 ambiguity guard refuses all such taps and demands `index=`. That's correct in the
+// spatial-ambiguity case (two distinct buttons share a label) but wrong in the
+// wrapper-ambiguity case — there's only one logical button, just stacked components.
+//
+// Collapse matches that share the same (testID, text) and overlap geometrically
+// (centers within TOLERANCE_PX). Keeps the first occurrence — fiber/a11y walks parent-first,
+// so the outermost wrapper survives (its onPress almost always proxies to inner handlers).
+// Spatial ambiguity (different x/y) is preserved and continues to surface the C1 refusal.
+function collapseGeometricallyEquivalentMatches(matches, getCenter, getKey) {
+    if (matches.length <= 1)
+        return matches;
+    const TOLERANCE_PX = 2;
+    const out = [];
+    for (const m of matches) {
+        const mc = getCenter(m);
+        const mk = getKey(m);
+        const isDuplicate = out.some(o => {
+            if (getKey(o) !== mk)
+                return false;
+            const oc = getCenter(o);
+            return Math.abs((mc.x ?? 0) - (oc.x ?? 0)) <= TOLERANCE_PX &&
+                Math.abs((mc.y ?? 0) - (oc.y ?? 0)) <= TOLERANCE_PX;
+        });
+        if (!isDuplicate)
+            out.push(m);
+    }
+    return out;
+}
 export function makeEmptyEvidenceSink() {
     return {
         fiber: { ran: false, durationMs: 0, metroConnected: false, pressables: [] },
         accessibility: { ran: false, durationMs: 0, elements: [] },
-        ocr: { ran: false, durationMs: 0, detections: [], closestMatch: null }
+        ocr: { ran: false, durationMs: 0, detections: [], closestMatch: null, bestCandidate: null }
     };
 }
 function ocrSimilarity(a, b) {
@@ -330,6 +456,12 @@ export function findClosestOcrText(ocrResult, query) {
         candidates.push(...ocrResult.words.map(w => ({ text: w.text })));
     if (ocrResult?.lines?.length)
         candidates.push(...ocrResult.lines.map(l => ({ text: l.text })));
+    // Include reconstructed phrases so the diagnostic surfaces "Continue with Google@1.00"
+    // instead of "Continue@0.54" when the engine fragmented a multi-word phrase into
+    // separate word detections.
+    if (ocrResult?.words?.length) {
+        candidates.push(...reconstructLinesFromWords(ocrResult.words).map(l => ({ text: l.text })));
+    }
     if (!candidates.length)
         return null;
     let best = null;
@@ -421,12 +553,19 @@ async function tryFiberAtDepth(query, index, maxTraversalDepth) {
             // specify an explicit index, refuse to tap and surface the full list
             // so the agent can pick the right one.
             if ((parsed.totalMatches ?? 1) > 1 && index === undefined) {
-                return {
-                    success: false,
-                    reason: `Ambiguous: ${parsed.totalMatches} elements match this query — use index= to pick one`,
-                    matches: parsed.allMatches || [],
-                    ambiguous: true
-                };
+                // I2: collapse geometrically-identical wrapper matches before refusing.
+                const collapsed = collapseGeometricallyEquivalentMatches(parsed.allMatches ?? [], (m) => ({ x: m.x, y: m.y }), (m) => `${m.testID ?? ""}::${m.text ?? ""}`);
+                if (collapsed.length > 1) {
+                    return {
+                        success: false,
+                        reason: `Ambiguous: ${collapsed.length} elements match this query — use index= to pick one`,
+                        matches: collapsed,
+                        ambiguous: true
+                    };
+                }
+                // Collapsed to one logical element — fall through and tap. The JS-side
+                // search already picked allMatches[0] (the outermost wrapper) for
+                // parsed.pressed/parsed.nativeTapTarget.
             }
             const elementType = parsed.isInput ? "input element" : "pressable element";
             if (parsed.nativeTapTarget && parsed.nativeTapTarget.x && parsed.nativeTapTarget.y) {
@@ -462,7 +601,7 @@ async function tryFiberAtDepth(query, index, maxTraversalDepth) {
         };
     }
 }
-async function tryAccessibilityStrategy(query, index, platform, udid, sink) {
+async function tryAccessibilityStrategy(query, index, platform, udid, sink, signal) {
     if (sink)
         sink.accessibility.ran = true;
     const startedAt = Date.now();
@@ -535,11 +674,15 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink) {
             // refuse to tap without an explicit index — picking allMatches[0] silently
             // landed on non-interactive header elements in production telemetry.
             // Mirrors the fiber-strategy guard further up the file.
-            if (result.allMatches.length > 1 && index === undefined) {
+            // I2: collapse geometrically-identical wrapper matches before refusing.
+            const iosEffectiveMatches = result.allMatches.length > 1
+                ? collapseGeometricallyEquivalentMatches(result.allMatches, (m) => ({ x: m.center?.x, y: m.center?.y }), (m) => `${m.identifier ?? ""}::${m.label ?? ""}`)
+                : result.allMatches;
+            if (iosEffectiveMatches.length > 1 && index === undefined) {
                 return {
                     success: false,
-                    reason: `Ambiguous: ${result.allMatches.length} elements match this query — use index= to pick one`,
-                    matches: result.allMatches.map((m, i) => ({
+                    reason: `Ambiguous: ${iosEffectiveMatches.length} elements match this query — use index= to pick one`,
+                    matches: iosEffectiveMatches.map((m, i) => ({
                         index: i,
                         component: m.type ?? "",
                         text: m.label ?? "",
@@ -550,11 +693,11 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink) {
                     ambiguous: true
                 };
             }
-            const match = result.allMatches[index ?? 0];
+            const match = iosEffectiveMatches[index ?? 0];
             if (!match) {
                 return {
                     success: false,
-                    reason: `Index ${index} out of bounds (${result.allMatches.length} matches)`
+                    reason: `Index ${index} out of bounds (${iosEffectiveMatches.length} matches)`
                 };
             }
             await iosTap(match.center.x, match.center.y, { udid });
@@ -576,14 +719,14 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink) {
             else if (hasText) {
                 searchOptions.textContains = query.text;
             }
-            let result = await androidFindElement(searchOptions);
+            let result = await androidFindElement(searchOptions, undefined, signal);
             // If testID search via resourceId failed, try contentDescContains
             // (older RN versions map testID to content-description)
             if (hasTestID && !hasText && (!result.success || !result.allMatches || result.allMatches.length === 0)) {
                 result = await androidFindElement({
                     contentDescContains: query.testID,
                     index
-                });
+                }, undefined, signal);
             }
             if (sink && result.allMatches?.length) {
                 sink.accessibility.elements = result.allMatches.slice(0, 50).map(el => ({
@@ -601,11 +744,15 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink) {
                 };
             }
             // Ambiguity guard — see iOS branch above for rationale.
-            if (result.allMatches.length > 1 && index === undefined) {
+            // I2: collapse geometrically-identical wrapper matches before refusing.
+            const androidEffectiveMatches = result.allMatches.length > 1
+                ? collapseGeometricallyEquivalentMatches(result.allMatches, (m) => ({ x: m.center?.x, y: m.center?.y }), (m) => `${m.resourceId ?? ""}::${m.text ?? m.contentDesc ?? ""}`)
+                : result.allMatches;
+            if (androidEffectiveMatches.length > 1 && index === undefined) {
                 return {
                     success: false,
-                    reason: `Ambiguous: ${result.allMatches.length} elements match this query — use index= to pick one`,
-                    matches: result.allMatches.map((m, i) => ({
+                    reason: `Ambiguous: ${androidEffectiveMatches.length} elements match this query — use index= to pick one`,
+                    matches: androidEffectiveMatches.map((m, i) => ({
                         index: i,
                         component: m.className ?? "",
                         text: m.text ?? m.contentDesc ?? "",
@@ -616,11 +763,11 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink) {
                     ambiguous: true
                 };
             }
-            const match = result.allMatches[index ?? 0];
+            const match = androidEffectiveMatches[index ?? 0];
             if (!match) {
                 return {
                     success: false,
-                    reason: `Index ${index} out of bounds (${result.allMatches.length} matches)`
+                    reason: `Index ${index} out of bounds (${androidEffectiveMatches.length} matches)`
                 };
             }
             await androidTap(match.center.x, match.center.y);
@@ -645,7 +792,14 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink) {
             sink.accessibility.durationMs = Date.now() - startedAt;
     }
 }
-async function tryOcrStrategy(query, platform, udid, sink) {
+/**
+ * Run OCR sense (capture + recognize + match). When `probeOnly` is true,
+ * populates `sink.ocr.bestCandidate` but does NOT tap — caller is responsible
+ * for tapping via tryOcrRecovery() once it decides to use the result.
+ * This is the foundation for Step 4's OCR pre-warm: run the slow OCR probe
+ * concurrently with fiber/a11y so that when neither wins, OCR is already done.
+ */
+async function tryOcrStrategy(query, platform, udid, sink, signal, probeOnly = false) {
     if (sink)
         sink.ocr.ran = true;
     const ocrStartedAt = Date.now();
@@ -669,7 +823,7 @@ async function tryOcrStrategy(query, platform, udid, sink) {
         }
         else {
             const { androidScreenshot } = await import("../core/android.js");
-            const screenshot = await androidScreenshot();
+            const screenshot = await androidScreenshot(undefined, undefined, signal);
             if (!screenshot.success || !screenshot.data) {
                 return {
                     success: false,
@@ -682,7 +836,8 @@ async function tryOcrStrategy(query, platform, udid, sink) {
         const { recognizeText } = await import("../core/ocr.js");
         const ocrResult = await recognizeText(imageBuffer, {
             scaleFactor,
-            platform
+            platform,
+            signal
         });
         if (sink && ocrResult) {
             const allDetections = [
@@ -697,12 +852,35 @@ async function tryOcrStrategy(query, platform, udid, sink) {
             sink.ocr.closestMatch = findClosestOcrText(ocrResult, searchText);
         }
         const match = findOcrMatch(ocrResult, searchText);
+        // Step 2 (2026-05-15 plan): record the best candidate with coordinates
+        // BEFORE any tap-execution code runs. If the strategy's withTimeout
+        // races us by 30ms (real production case: COMPRAR/Portuguese-Android
+        // cluster — `findOcrMatch` returned `COMPRAR@1.00` 30ms past the cap),
+        // the orchestrator can recover by tapping at these coords with the
+        // `ocr-recovered` strategy label.
+        if (sink && match) {
+            const closest = sink.ocr.closestMatch;
+            sink.ocr.bestCandidate = {
+                text: match.text,
+                score: closest && closest.text === match.text ? closest.score : 1,
+                tapCenter: { x: match.tapCenter.x, y: match.tapCenter.y },
+                scaleFactor
+            };
+        }
         if (!match) {
             return {
                 success: false,
                 reason: `OCR did not find text "${searchText}" on screen`
             };
         }
+        // Step 4 pre-warm: bestCandidate is set; let the orchestrator decide
+        // whether to actually tap (it may have already won the race via fiber).
+        if (probeOnly) {
+            return {
+                success: false,
+                reason: `OCR probe completed (probeOnly) — match "${match.text}" recorded in evidence`
+            };
+        }
         if (platform === "ios") {
             // tapCenter is in image-pixel space (downscaled) — convert to points
             const { getDevicePixelRatio } = await import("../core/ios.js");
@@ -741,6 +919,39 @@ async function tryOcrStrategy(query, platform, udid, sink) {
             sink.ocr.durationMs = Date.now() - ocrStartedAt;
     }
 }
+/**
+ * Step 2 (2026-05-15 plan): OCR-strategy timeout recovery. If the OCR sense
+ * already wrote a high-confidence candidate to the evidence sink (perfect
+ * match found ~30ms past the strategy cap, COMPRAR cluster), tap directly at
+ * the candidate's coordinates. Returns null when there's no candidate worth
+ * acting on so the caller falls back to normal failure handling.
+ */
+async function tryOcrRecovery(evidence, platform, udid) {
+    const bc = evidence.ocr.bestCandidate;
+    if (!bc || bc.score < 0.9)
+        return null;
+    try {
+        if (platform === "ios") {
+            const { getDevicePixelRatio } = await import("../core/ios.js");
+            const dpr = await getDevicePixelRatio(udid);
+            const tapResult = await iosTap(Math.round((bc.tapCenter.x * bc.scaleFactor) / dpr), Math.round((bc.tapCenter.y * bc.scaleFactor) / dpr), { udid });
+            if (!tapResult.success)
+                return null;
+        }
+        else {
+            await androidTap(Math.round(bc.tapCenter.x * bc.scaleFactor), Math.round(bc.tapCenter.y * bc.scaleFactor));
+        }
+        return {
+            success: true,
+            reason: `OCR recovered after timeout — tapped "${bc.text}"@${bc.score.toFixed(2)}`,
+            text: bc.text,
+            convertedTo: { x: bc.tapCenter.x, y: bc.tapCenter.y, unit: "pixels" }
+        };
+    }
+    catch {
+        return null;
+    }
+}
 async function tryCoordinateStrategy(pixelX, pixelY, platform, lastScreenshot, udid) {
     try {
         if (platform === "ios") {
@@ -800,12 +1011,20 @@ async function tryCoordinateStrategy(pixelX, pixelY, platform, lastScreenshot, u
 const SETTLE_DELAY_MS = 800;
 const TAP_TIMEOUT_MS = 20000;
 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.
 const MAX_STRATEGY_MS = {
     fiber: 5000,
     accessibility: 3000,
     ocr: 5000,
     coordinate: 3000
 };
+function maxStrategyMs(strategy, platform) {
+    if (strategy === "ocr" && platform === "android")
+        return 7000;
+    return MAX_STRATEGY_MS[strategy] ?? 5000;
+}
 // Matches only the outer withTimeout wrapper message for a tap strategy.
 // Nested sub-operation errors inside a strategy (e.g. "CDP getProperties timed out after 150ms")
 // must NOT be classified as a tap-level timeout.
@@ -825,6 +1044,22 @@ function withTimeout(promise, ms, label) {
         });
     });
 }
+/**
+ * Like withTimeout, but creates an AbortController whose signal is handed to
+ * the inner factory. On timeout the signal aborts so subprocess work
+ * (uiautomator dump, OCR fetch, screencap) can be killed instead of running
+ * past the strategy cap and bleeding into total tap duration.
+ */
+function withCancelableTimeout(make, ms, label) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), ms);
+    return make(ctrl.signal).then((val) => { clearTimeout(timer); return val; }, (err) => {
+        clearTimeout(timer);
+        if (ctrl.signal.aborted)
+            throw new Error(`${label} timed out after ${ms}ms`);
+        throw err;
+    });
+}
 async function captureScreenshot(platform, udid) {
     try {
         const result = platform === "ios" ? await iosScreenshot(undefined, udid) : await androidScreenshot();
@@ -916,23 +1151,60 @@ function computeMarkerPx(args) {
     };
 }
 async function verifyAndCapture(platform, shouldVerify, shouldScreenshot, beforeBuffer, udid, beforeScaleFactor, markerPx) {
-    if (!shouldScreenshot)
-        return {};
+    // 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 (!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 = {
-        image: screenshotToBase64(afterWithMarker),
-        width: after.width,
-        height: after.height,
-        scaleFactor: after.scaleFactor
-    };
+    const screenshot = shouldScreenshot
+        ? {
+            image: screenshotToBase64(afterWithMarker),
+            width: after.width,
+            height: after.height,
+            scaleFactor: after.scaleFactor
+        }
+        : undefined;
     let verification;
-    if (shouldVerify && beforeBuffer) {
+    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;
@@ -953,8 +1225,12 @@ async function verifyAndCapture(platform, shouldVerify, shouldScreenshot, before
                 })
             };
         }
-        catch {
-            // Diff failed — still return the screenshot
+        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)}`;
@@ -1076,6 +1352,40 @@ async function burstCaptureAndVerify(platform, beforeBuffer, udid, beforeScaleFa
         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
+// window get suppressed.
+const recentCoordArtifacts = new Map();
+const COORD_DEDUP_WINDOW_MS = 60_000;
+const COORD_DEDUP_BUCKET = 20;
+function shouldDedupArtifact(ctx) {
+    // Only applies to coordinate-strategy artifacts where we have x,y coords.
+    const winningStrat = ctx.attempted.find(a => a.reason === "success")?.strategy
+        ?? ctx.attempted[ctx.attempted.length - 1]?.strategy;
+    if (winningStrat !== "coordinate")
+        return false;
+    const x = ctx.chosenTapPoint?.x ?? ctx.query.x;
+    const y = ctx.chosenTapPoint?.y ?? ctx.query.y;
+    if (typeof x !== "number" || typeof y !== "number")
+        return false;
+    const key = `${Math.round(x / COORD_DEDUP_BUCKET)}:${Math.round(y / COORD_DEDUP_BUCKET)}`;
+    const now = Date.now();
+    // Sweep stale entries opportunistically — keeps the map from growing.
+    for (const [k, ts] of recentCoordArtifacts) {
+        if (now - ts > COORD_DEDUP_WINDOW_MS)
+            recentCoordArtifacts.delete(k);
+    }
+    const last = recentCoordArtifacts.get(key);
+    if (last !== undefined && (now - last) < COORD_DEDUP_WINDOW_MS)
+        return true;
+    recentCoordArtifacts.set(key, now);
+    return false;
+}
+/** Test-only: drop the dedup state so a fresh tap always uploads. */
+export function resetCoordArtifactDedup() {
+    recentCoordArtifacts.clear();
+}
 async function captureTapArtifact(ctx) {
     try {
         const { getServerVersion, categorizeError } = await import("../core/telemetry.js");
@@ -1089,6 +1399,20 @@ async function captureTapArtifact(ctx) {
         if (errorCategory === "driver_missing") {
             return undefined;
         }
+        // D1 (Step 6): no-metro unmeaningful taps have no diagnostic signal
+        // beyond a screenshot diff that's already below threshold by definition.
+        // ~50% of recent failure-artifact rows were these — they crowd out real
+        // failures in the dashboard. Telemetry row still flows; just no R2 bundle.
+        const noMetro = ctx.evidence ? !ctx.evidence.fiber.metroConnected : connectedApps.size === 0;
+        if (ctx.outcome === "unmeaningful" && noMetro) {
+            return undefined;
+        }
+        // D2 (Step 6): retry deduplication — coord-strategy taps at the same
+        // grid cell within 60s upload the same near-identical artifact. The
+        // first capture is enough; subsequent ones are noise.
+        if (shouldDedupArtifact(ctx)) {
+            return undefined;
+        }
         const result = await captureFailureArtifact({
             outcome: ctx.outcome,
             predicate: ctx.query,
@@ -1101,7 +1425,12 @@ async function captureTapArtifact(ctx) {
             meaningful: ctx.verification?.meaningful,
             senses: ctx.evidence
                 ? {
-                    ocr: ctx.evidence.ocr,
+                    ocr: {
+                        ran: ctx.evidence.ocr.ran,
+                        durationMs: ctx.evidence.ocr.durationMs,
+                        detections: ctx.evidence.ocr.detections,
+                        closestMatch: ctx.evidence.ocr.closestMatch
+                    },
                     fiber: {
                         ran: ctx.evidence.fiber.ran,
                         durationMs: ctx.evidence.fiber.durationMs,
@@ -1283,7 +1612,8 @@ export async function tap(options) {
                     undefined;
         }
         const nativeShouldScreenshot = options.screenshot !== false;
-        const nativeShouldVerify = nativeShouldScreenshot && options.verify !== false;
+        // Decoupled (I5, 2026-05-16): verify runs even when image bytes aren't returned.
+        const nativeShouldVerify = options.verify !== false;
         let nativeBeforeBuffer = null;
         let nativeScreenshotMeta;
         if (nativeShouldVerify) {
@@ -1339,6 +1669,8 @@ export async function tap(options) {
             });
             if (options.burst && nativeShouldVerify && nativeBeforeBuffer) {
                 ({ screenshot, verification } = await burstCaptureAndVerify(platform, nativeBeforeBuffer, nativeUdid, nativeScreenshotMeta?.scaleFactor, nativeMarker));
+                if (!nativeShouldScreenshot)
+                    screenshot = undefined;
             }
             else {
                 ({ screenshot, verification } = await verifyAndCapture(platform, nativeShouldVerify, nativeShouldScreenshot, nativeBeforeBuffer, nativeUdid, nativeScreenshotMeta?.scaleFactor, nativeMarker));
@@ -1508,11 +1840,11 @@ export async function tap(options) {
             error: errorMessage
         };
     }
-    // Determine screenshot and verification behavior
+    // Determine screenshot and verification behavior.
+    // Decoupled (I5, 2026-05-16): verify can run without returning image bytes —
+    // capture cost is paid either way; bandwidth cost is what `screenshot` toggles.
     const shouldScreenshot = options.screenshot !== false;
-    // Always capture before screenshot when screenshots are enabled and verify isn't explicitly off
-    // Verification decision is deferred until we know which strategy actually succeeded
-    const canVerify = shouldScreenshot && options.verify !== false;
+    const canVerify = options.verify !== false;
     // Capture "before" screenshot for verification
     let beforeBuffer = null;
     let beforeScaleFactor;
@@ -1521,6 +1853,23 @@ export async function tap(options) {
         beforeBuffer = before?.buffer || null;
         beforeScaleFactor = before?.scaleFactor;
     }
+    // Step 4: pre-warm the OCR sense if it's in the chain after a faster strategy.
+    // Runs concurrently with fiber/a11y so that when the loop reaches OCR, the
+    // probe is likely already complete (saving ~5s in OCR-win rows). Probe
+    // populates evidence.ocr.bestCandidate; the orchestrator decides whether
+    // to actually tap based on bestCandidate score.
+    const ocrIdx = filteredStrategies.indexOf("ocr");
+    const ocrCanPrewarm = ocrIdx > 0 && !!query.text;
+    let ocrPrewarmCtrl = null;
+    let ocrPrewarmPromise = null;
+    if (ocrCanPrewarm) {
+        ocrPrewarmCtrl = new AbortController();
+        const ctrl = ocrPrewarmCtrl;
+        const ocrCap = maxStrategyMs("ocr", platform);
+        const timer = setTimeout(() => ctrl.abort(), ocrCap);
+        ocrPrewarmPromise = tryOcrStrategy(query, platform, targetUdid, evidence, ctrl.signal, /* probeOnly */ true)
+            .then((result) => { clearTimeout(timer); return { result, aborted: ctrl.signal.aborted }; }, (err) => { clearTimeout(timer); return { result: { success: false, reason: err instanceof Error ? err.message : String(err) }, aborted: ctrl.signal.aborted }; });
+    }
     // Execute strategies in order with per-strategy caps and overall budget
     for (const strat of filteredStrategies) {
         const remaining = remainingMs();
@@ -1531,19 +1880,50 @@ export async function tap(options) {
             });
             continue;
         }
-        const cap = MAX_STRATEGY_MS[strat] ?? 5000;
+        const cap = maxStrategyMs(strat, platform);
         const budget = Math.min(cap, remaining);
         let result;
+        let strategyLabel = strat;
         try {
             switch (strat) {
                 case "fiber":
+                    // Fiber is JS-only against a CDP target — no subprocess to cancel,
+                    // so the cheaper non-cancellable wrapper is fine.
                     result = await withTimeout(tryFiberStrategy(query, index, maxTraversalDepth, evidence), budget, `fiber`);
                     break;
                 case "accessibility":
-                    result = await withTimeout(tryAccessibilityStrategy(query, index, platform, targetUdid, evidence), budget, `accessibility`);
+                    result = await withCancelableTimeout((signal) => tryAccessibilityStrategy(query, index, platform, targetUdid, evidence, signal), budget, `accessibility`);
                     break;
                 case "ocr":
-                    result = await withTimeout(tryOcrStrategy(query, platform, targetUdid, evidence), budget, `ocr`);
+                    if (ocrPrewarmPromise) {
+                        // Pre-warmed probe: await its completion (capped at the
+                        // remaining budget so we don't blow past the overall
+                        // tap timeout if the prewarm is taking forever) and then
+                        // tap based on the recorded bestCandidate.
+                        const prewarmRace = withCancelableTimeout((signal) => Promise.race([
+                            ocrPrewarmPromise,
+                            new Promise((_, reject) => signal.addEventListener("abort", () => reject(new Error("ocr timed out after " + budget + "ms")), { once: true }))
+                        ]), budget, `ocr`);
+                        try {
+                            await prewarmRace;
+                        }
+                        catch (e) {
+                            // Pre-warm timed out beyond what budget allows. Abort it.
+                            ocrPrewarmCtrl?.abort();
+                            throw e;
+                        }
+                        const recovered = await tryOcrRecovery(evidence, platform, targetUdid);
+                        if (recovered) {
+                            result = recovered;
+                            strategyLabel = "ocr"; // not "ocr-recovered" — this is the normal path now
+                        }
+                        else {
+                            result = { success: false, reason: `OCR did not find a viable match for "${query.text}"` };
+                        }
+                    }
+                    else {
+                        result = await withCancelableTimeout((signal) => tryOcrStrategy(query, platform, targetUdid, evidence, signal), budget, `ocr`);
+                    }
                     break;
                 case "coordinate":
                     result = await withTimeout(tryCoordinateStrategy(query.x, query.y, platform, app?.lastScreenshot, targetUdid), budget, `coordinate`);
@@ -1553,13 +1933,31 @@ export async function tap(options) {
             }
         }
         catch (err) {
-            attempted.push({
-                strategy: strat,
-                reason: err instanceof Error ? err.message : String(err)
-            });
-            continue;
+            const reason = err instanceof Error ? err.message : String(err);
+            // Step 2 recovery: when the OCR strategy times out but already
+            // produced a high-confidence candidate (race condition: the tap
+            // was queued ~30ms past the cap in the COMPRAR cluster), tap the
+            // candidate directly and label the strategy `ocr-recovered`.
+            // Score is from sink.ocr.closestMatch's similarity to the search;
+            // a perfect match is 1.0 — gate at 0.9 to skip "not on screen".
+            const recoveredResult = (strat === "ocr" && /ocr timed out after \d+ms$/.test(reason))
+                ? await tryOcrRecovery(evidence, platform, targetUdid)
+                : null;
+            if (recoveredResult) {
+                result = recoveredResult;
+                strategyLabel = "ocr-recovered";
+                // Fall through past the catch block to the success handler.
+            }
+            else {
+                attempted.push({ strategy: strat, reason });
+                continue;
+            }
         }
         if (result.success) {
+            // Higher-priority strategy won — kill the OCR pre-warm so its
+            // device-side screencap doesn't keep running.
+            if (strat !== "ocr")
+                ocrPrewarmCtrl?.abort();
             let screenshot;
             let verification;
             let afterBuffer;
@@ -1575,7 +1973,7 @@ export async function tap(options) {
                 }
             }
             const strategyMarker = computeMarkerPx({
-                strategy: strat,
+                strategy: strategyLabel,
                 input: strat === "coordinate" ? { x: query.x, y: query.y } : undefined,
                 convertedTo: result.convertedTo,
                 platform,
@@ -1584,6 +1982,11 @@ export async function tap(options) {
             });
             if (options.burst && canVerify && beforeBuffer) {
                 ({ screenshot, verification, afterBuffer, afterWithMarkerBuffer } = await burstCaptureAndVerify(platform, beforeBuffer, targetUdid, beforeScaleFactor, 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)
+                    screenshot = undefined;
             }
             else {
                 ({ screenshot, verification, afterBuffer, afterWithMarkerBuffer } = await verifyAndCapture(platform, canVerify, shouldScreenshot, beforeBuffer, targetUdid, beforeScaleFactor, strategyMarker));
@@ -1596,7 +1999,7 @@ export async function tap(options) {
                 };
             }
             const successResult = formatTapSuccess({
-                method: strat,
+                method: strategyLabel,
                 query,
                 pressed: result.pressed,
                 text: result.text,
@@ -1611,7 +2014,7 @@ 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.changeRate < 0.001) {
+            if (verification && !verification.skipped && (verification.changeRate ?? 1) < 0.001) {
                 const unmeaningfulSignals = await captureTapArtifact({
                     query,
                     outcome: "unmeaningful",