execbro 2.3.0 → 2.6.0

package/build/pro/tap.js

@@ -14,9 +14,8 @@ export function buildVerificationExplanation(v) {
     const action = v.action ?? "tap";
     const Action = action[0].toUpperCase() + action.slice(1);
     const target = action === "swipe" ? "scroll surface" : "element";
-    // Burst path with typed verdict
     if (v.kind === "settled_elsewhere") {
-        return `${Action} 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). Something on screen responded; a pixel diff cannot identify which element, so this is not confirmation that the intended target handled it.`;
     }
     if (v.kind === "snap_back") {
         if (action === "swipe") {
@@ -31,9 +30,8 @@ export function buildVerificationExplanation(v) {
         return (`No visual change detected — neither persistent nor transient across burst frames. ` +
             `The ${target} may not respond visually or the ${action} may have missed its target.`);
     }
-    // Legacy non-burst path
     if (v.meaningful) {
-        return `${Action} 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). Something on screen responded; a pixel diff cannot identify which element, so this is not confirmation that the intended target handled it.`;
     }
     return (`No visual change detected between before and after screenshots. ` +
         `The ${target} may not respond visually or the ${action} may have missed.`);
@@ -67,9 +65,6 @@ export async function analyzeBurstFrames(frames, options) {
     const persistentDiff = await compareScreenshots(frames[0], frames[frames.length - 1], options);
     const persistentChangeRate = persistentDiff.changeRate;
     const transientChangeDetected = !persistentDiff.changed && framesWithChange.length > 0;
-    // Snap-back (transient motion that reverts) is NOT a successful gesture —
-    // the content moved during the drag but returned to its starting position.
-    // Callers diagnosing scroll failures need this to read as "didn't work".
     const meaningful = persistentDiff.changed;
     let kind;
     if (persistentDiff.changed) {
@@ -91,7 +86,6 @@ export async function analyzeBurstFrames(frames, options) {
         kind
     };
 }
-// --- Helpers ---
 export function buildQuery(options) {
     const query = {};
     if (options.text !== undefined)
@@ -106,11 +100,6 @@ export function buildQuery(options) {
         query.y = options.y;
     return query;
 }
-/**
- * Check if text contains characters that break Hermes Runtime.evaluate.
- * Standard accented Latin characters (Polish, Vietnamese, French, German, etc.)
- * and Cyrillic work fine in Hermes. Only emoji and special Unicode ranges cause issues.
- */
 export function hasProblematicUnicode(text) {
     const emojiPattern = /[\u{1F600}-\u{1F64F}]|[\u{1F300}-\u{1F5FF}]|[\u{1F680}-\u{1F6FF}]|[\u{1F1E0}-\u{1F1FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]|[\u{FE00}-\u{FE0F}]|[\u{1F900}-\u{1F9FF}]|[\u{200D}]|[\u{20E3}]|[\u{E0020}-\u{E007F}]/u;
     return emojiPattern.test(text);
@@ -157,13 +146,6 @@ export function reconstructLinesFromWords(words) {
         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);
@@ -176,11 +158,10 @@ function refineTapCenterToMatchingWords(line, normalizedNeedle) {
         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
+        offset = wordEnd + 1;
     }
     if (covered.length === 0)
         return line.tapCenter;
@@ -206,10 +187,6 @@ 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) {
@@ -226,7 +203,6 @@ export function getAvailableStrategies(query, strategy) {
         return ["coordinate"];
     }
     if (strategy !== "auto") {
-        // Always fallback to OCR for text queries — explicit strategy may miss visible text
         if (query.text && strategy !== "ocr" && strategy !== "coordinate") {
             return [strategy, "ocr"];
         }
@@ -249,16 +225,6 @@ export function getAvailableStrategies(query, strategy) {
     }
     return ["fiber", "accessibility", "ocr"];
 }
-/**
- * Convert screenshot image coordinates to platform-native tap coordinates.
- *
- * For iOS: screenshot pixels → device pixels (undo downscale) → points (÷ DPR)
- * For Android: screenshot pixels → device pixels (undo downscale)
- *
- * IMPORTANT: Only use this for EXTERNAL coordinates from screenshots.
- * Internal strategies (OCR, accessibility, fiber) produce tap-ready coordinates
- * and call iosTap/androidTap directly — they must NOT go through this function.
- */
 export function convertScreenshotToTapCoords(pixelX, pixelY, platform, devicePixelRatio, scaleFactor = 1) {
     const deviceX = pixelX * scaleFactor;
     const deviceY = pixelY * scaleFactor;
@@ -270,16 +236,7 @@ export function convertScreenshotToTapCoords(pixelX, pixelY, platform, devicePix
         y: Math.round(deviceY / devicePixelRatio)
     };
 }
-/** @deprecated Use convertScreenshotToTapCoords instead */
 export const convertPixelsToPoints = convertScreenshotToTapCoords;
-/**
- * Turn a swipe direction (+ optional pixel distance) into screenshot-pixel
- * start/end coordinates, centered on the screen. Content-scroll semantics:
- * "up" = finger travels bottom→top, revealing content below.
- * Distance defaults to 33% of the relevant axis and endpoints clamp to the
- * 10%–90% margin so the gesture never runs off-screen. Exact travel length is
- * preserved; for odd distances the band may sit ≤1px off the axis midpoint.
- */
 export function computeSwipeFromDirection(direction, distance, width, height) {
     const vertical = direction === "up" || direction === "down";
     const axis = vertical ? height : width;
@@ -288,11 +245,10 @@ export function computeSwipeFromDirection(direction, distance, width, height) {
     const cy = Math.round(height / 2);
     const lo = Math.round(0.1 * axis);
     const hi = Math.round(0.9 * axis);
-    // Center a band of length d on the axis midpoint, then clamp to [lo, hi].
     const mid = Math.round(axis / 2);
     const half = Math.floor(d / 2);
-    let far = mid - half; // smaller-coordinate end
-    let near = far + d; // exact length d
+    let far = mid - half;
+    let near = far + d;
     if (near > hi) {
         near = hi;
         far = near - d;
@@ -301,29 +257,23 @@ export function computeSwipeFromDirection(direction, distance, width, height) {
         far = lo;
         near = far + d;
     }
-    // distance exceeds the available span — collapse to the full margin
     if (near > hi)
         near = hi;
     if (far < lo)
         far = lo;
     switch (direction) {
-        case "up": // finger bottom→top: start at larger Y, end at smaller Y
+        case "up":
             return { startX: cx, startY: near, endX: cx, endY: far };
-        case "down": // finger top→bottom
+        case "down":
             return { startX: cx, startY: far, endX: cx, endY: near };
-        case "left": // finger right→left
+        case "left":
             return { startX: near, startY: cy, endX: far, endY: cy };
-        case "right": // finger left→right
+        case "right":
             return { startX: far, startY: cy, endX: near, endY: cy };
     }
 }
 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);
@@ -370,16 +320,6 @@ 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;
@@ -412,7 +352,6 @@ function ocrSimilarity(a, b) {
         return 0;
     if (a === b)
         return 1;
-    // Dice coefficient over character bigrams (case/space-insensitive)
     const bigrams = (s) => {
         const m = new Map();
         if (s.length < 2) {
@@ -451,9 +390,6 @@ 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 })));
     }
@@ -470,7 +406,6 @@ export function findClosestOcrText(ocrResult, query) {
     }
     return best;
 }
-// --- Strategy Functions ---
 async function tryFiberStrategy(query, index, maxTraversalDepth, sink, device) {
     if (sink) {
         sink.fiber.ran = true;
@@ -478,10 +413,8 @@ async function tryFiberStrategy(query, index, maxTraversalDepth, sink, device) {
     }
     const startedAt = Date.now();
     try {
-        // Retry with increasing depth if the initial traversal finds nothing
         const baseDepth = maxTraversalDepth ?? 15;
         const depthAttempts = [baseDepth];
-        // Only add deeper retries if user didn't explicitly set a high depth
         if (baseDepth <= 15) {
             depthAttempts.push(30, 45);
         }
@@ -540,16 +473,8 @@ async function tryFiberAtDepth(query, index, maxTraversalDepth, device) {
             }
             return strategyResult;
         }
-        // Fiber finds the element by text/testID/component, then measures its
-        // host component's screen position for a native tap. This ensures the tap
-        // goes through React's event pipeline, executing any onPress wrappers
-        // (analytics, debouncing, state tracking) inside the component.
         if (parsed.needsNativeTap) {
-            // Ambiguity guard: if multiple elements match and the caller didn't
-            // 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) {
-                // 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 {
@@ -559,9 +484,6 @@ async function tryFiberAtDepth(query, index, maxTraversalDepth, device) {
                         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) {
@@ -584,7 +506,6 @@ async function tryFiberAtDepth(query, index, maxTraversalDepth, device) {
                 reason: `Found ${parsed.pressed} (${elementType}) but could not measure coordinates — falling through to next strategy`
             };
         }
-        // All elements now use needsNativeTap — this shouldn't be reached
         return {
             success: false,
             reason: "Unexpected: element did not request native tap"
@@ -611,28 +532,20 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink, sign
             };
         }
         if (platform === "ios") {
-            // One accessibility dump serves every pass below: `axe describe-ui`
-            // costs ~210ms and the screen cannot change between predicates, so
-            // re-fetching per pass was pure overhead (2-3 dumps per tap).
             const { iosGetUITree } = await import("../core/ios.js");
             const tree = await iosGetUITree(udid);
-            // iOS: testID maps to accessibilityIdentifier — search by identifier first,
-            // then fall back to labelContains for text-based searches
             let result;
             if (hasTestID && !hasText) {
-                // Try exact identifier match first (testID → accessibilityIdentifier)
                 result = await iosFindElement({
                     identifier: query.testID,
                     index
                 }, udid, tree);
-                // Fall back to identifierContains if exact match fails
                 if (!result.success || !result.allMatches || result.allMatches.length === 0) {
                     result = await iosFindElement({
                         identifierContains: query.testID,
                         index
                     }, udid, tree);
                 }
-                // Last resort: try labelContains in case testID is reflected in label
                 if (!result.success || !result.allMatches || result.allMatches.length === 0) {
                     result = await iosFindElement({
                         labelContains: query.testID,
@@ -642,8 +555,6 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink, sign
             }
             else {
                 const searchText = query.text;
-                // Exact label match first to avoid matching dialog titles like "Clear All"
-                // when the query is a single word that happens to be a substring ("Clear").
                 result = await iosFindElement({
                     label: searchText,
                     index
@@ -670,12 +581,6 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink, sign
                     reason: result.error ?? "No iOS accessibility match"
                 };
             }
-            // Ambiguity guard: when the predicate matches multiple a11y elements
-            // (e.g. text="My Events" hits both the header title AND the bottom tab),
-            // 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.
-            // 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;
@@ -712,7 +617,6 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink, sign
             };
         }
         else {
-            // Android: testID maps to resource-id, text maps to text content
             const searchOptions = { index };
             if (hasTestID && !hasText) {
                 searchOptions.resourceId = query.testID;
@@ -720,13 +624,9 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink, sign
             else if (hasText) {
                 searchOptions.textContains = query.text;
             }
-            // Same single-dump reuse as iOS above — a uiautomator hierarchy dump
-            // is the most expensive step of an Android accessibility tap.
             const { androidGetUITree } = await import("../core/android.js");
             const androidTree = await androidGetUITree(undefined, signal);
             let result = await androidFindElement(searchOptions, undefined, signal, androidTree);
-            // 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,
@@ -748,8 +648,6 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink, sign
                     reason: result.error ?? "No Android accessibility match"
                 };
             }
-            // Ambiguity guard — see iOS branch above for rationale.
-            // 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;
@@ -797,11 +695,6 @@ async function tryAccessibilityStrategy(query, index, platform, udid, sink, sign
             sink.accessibility.durationMs = Date.now() - startedAt;
     }
 }
-/**
- * Run OCR sense (capture + recognize + match) and tap the match. Also records
- * `sink.ocr.bestCandidate` (matched text + tap coords) into the evidence sink,
- * which is serialized into the R2 failure bundle for diagnostics.
- */
 async function tryOcrStrategy(query, platform, udid, sink, signal) {
     if (sink)
         sink.ocr.ran = true;
@@ -855,10 +748,6 @@ async function tryOcrStrategy(query, platform, udid, sink, signal) {
             sink.ocr.closestMatch = findClosestOcrText(ocrResult, searchText);
         }
         const match = findOcrMatch(ocrResult, searchText);
-        // Record the best candidate (matched text + tap coords) into the
-        // evidence sink. This is serialized into the R2 failure bundle and is
-        // useful when diagnosing OCR taps (e.g. OCR found the match at these
-        // coords but the tap didn't register a visual change).
         if (sink && match) {
             const closest = sink.ocr.closestMatch;
             sink.ocr.bestCandidate = {
@@ -875,7 +764,6 @@ async function tryOcrStrategy(query, platform, udid, sink, signal) {
             };
         }
         if (platform === "ios") {
-            // tapCenter is in image-pixel space (downscaled) — convert to points
             const { getDevicePixelRatio } = await import("../core/ios.js");
             const dpr = await getDevicePixelRatio(udid);
             const tapResult = await iosTap(Math.round((match.tapCenter.x * scaleFactor) / dpr), Math.round((match.tapCenter.y * scaleFactor) / dpr), { udid });
@@ -887,7 +775,6 @@ async function tryOcrStrategy(query, platform, udid, sink, signal) {
             }
         }
         else {
-            // Android: image-pixel → device-pixel (undo downscale), ADB accepts pixels
             await androidTap(Math.round(match.tapCenter.x * scaleFactor), Math.round(match.tapCenter.y * scaleFactor));
         }
         return {
@@ -917,8 +804,6 @@ async function tryCoordinateStrategy(pixelX, pixelY, platform, lastScreenshot, u
         if (platform === "ios") {
             const scaleFactor = lastScreenshot?.scaleFactor ?? 1;
             const { getDevicePixelRatio } = await import("../core/ios.js");
-            // Reuse the caller's frame dimensions when it has them, so the first
-            // coordinate tap of a session doesn't pay for an extra screenshot.
             const dprHint = lastScreenshot && lastScreenshot.originalWidth > 0 && lastScreenshot.originalHeight > 0
                 ? { width: lastScreenshot.originalWidth, height: lastScreenshot.originalHeight }
                 : undefined;
@@ -957,18 +842,7 @@ async function tryCoordinateStrategy(pixelX, pixelY, platform, lastScreenshot, u
 }
 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.
-// Coordinate looks "light" (one tap subprocess) but on iOS it pairs an axe/idb
-// invocation with a CDP getDevicePixelRatio + best-effort fiber inspection;
-// the 3000ms cap surfaced as spurious "coordinate timed out" failures while
-// 20+ seconds of the overall budget were still unused. Align with the other
-// strategies — the global TAP_TIMEOUT_MS still bounds the worst case.
+const OVERLAY_GUARD_BUDGET_MS = 3000;
 const MAX_STRATEGY_MS = {
     fiber: 8000,
     accessibility: 6000,
@@ -980,9 +854,6 @@ function maxStrategyMs(strategy, platform) {
         return 9000;
     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.
 const STRATEGY_TIMEOUT_RE = /^(fiber|accessibility|ocr|coordinate) timed out after \d+ms$/;
 export function isTapTimeout(attempted) {
     return attempted.some((a) => a.outcome === "timeout" || a.outcome === "skipped" || STRATEGY_TIMEOUT_RE.test(a.reason) || a.reason.startsWith("Skipped —"));
@@ -999,12 +870,6 @@ 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);
@@ -1015,15 +880,6 @@ function withCancelableTimeout(make, ms, label) {
         throw err;
     });
 }
-/**
- * Compute marker coordinates in screenshot-pixel space (what the returned PNG uses).
- * Unit rules by strategy, assuming screenshotScale = downscale factor:
- *   coordinate  : input is already screenshot pixels → pass through
- *   ocr         : match.tapCenter is image-pixel (= screenshot-pixel) → pass through
- *   iOS points  : point * DPR / screenshotScale
- *   android dp  : dp * densityScale / screenshotScale
- *   android devicePx : devicePx / screenshotScale
- */
 function computeMarkerPx(args) {
     const { strategy, input, convertedTo, platform, screenshotScale, devicePixelRatio, androidDensityScale } = args;
     const scale = screenshotScale || 1;
@@ -1036,36 +892,27 @@ function computeMarkerPx(args) {
         return { x: Math.round(convertedTo.x), y: Math.round(convertedTo.y) };
     }
     if (platform === "ios") {
-        // fiber/accessibility on iOS return points
         const dpr = devicePixelRatio || 3;
         return {
             x: Math.round((convertedTo.x * dpr) / scale),
             y: Math.round((convertedTo.y * dpr) / scale)
         };
     }
-    // Android
     if (strategy === "fiber+native" && androidDensityScale) {
-        // Fabric fiber returns dp; fiber+native path scales to device pixels before tap
         return {
             x: Math.round((convertedTo.x * androidDensityScale) / scale),
             y: Math.round((convertedTo.y * androidDensityScale) / scale)
         };
     }
-    // accessibility android: convertedTo is device pixels
     return {
         x: Math.round(convertedTo.x / scale),
         y: Math.round(convertedTo.y / scale)
     };
 }
-// 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")
@@ -1076,7 +923,6 @@ function shouldDedupArtifact(ctx) {
         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);
@@ -1087,47 +933,29 @@ function shouldDedupArtifact(ctx) {
     recentCoordArtifacts.set(key, now);
     return false;
 }
-/** Test-only: drop the dedup state so a fresh tap always uploads. */
 export function resetCoordArtifactDedup() {
     recentCoordArtifacts.clear();
 }
-/**
- * Turn an unmeaningful coordinate tap into an explanation.
- *
- * The tricky part is coordinate spaces. The caller works in screenshot pixels;
- * the tap was executed in points (iOS) or device pixels (Android); the screen
- * state reports points/dp. We map the tapped point INTO screen-state space to
- * do the hit test, and map the answer BACK into the caller's screenshot pixels
- * so any suggested coordinates can be passed straight to another tap().
- */
 async function diagnoseCoordinateMiss(args) {
     try {
         const { getScreenState } = await import("../core/screenState.js");
         const { explainCoordinateMiss } = await import("./coordinateMiss.js");
+        const { screenStateToScreenSpace, screenStateToDeliveredPx } = await import("../core/screenSpace.js");
+        const { resolveScreenSpaceMetrics } = await import("../core/screenSpaceDevice.js");
+        const { getConnectedAppByDevice, getFirstConnectedApp } = await import("../core/index.js");
         const ss = await getScreenState({ device: args.deviceName });
         if (!ss.success || !ss.screenState)
             return undefined;
-        // Android taps are executed in device pixels; screen state speaks dp.
-        let pointInState = args.point;
-        if (args.pointUnit === "pixels") {
-            const { androidGetDensity } = await import("../core/android.js");
-            const density = await androidGetDensity();
-            const densityScale = (density.density || 420) / 160;
-            pointInState = { x: args.point.x / densityScale, y: args.point.y / densityScale };
-        }
-        // Ratio between screen-state space and the caller's screenshot pixels,
-        // derived from the conversion this very tap already performed. Uses the
-        // larger axis so a near-zero coordinate can't amplify rounding error.
-        const useY = Math.abs(pointInState.y) > Math.abs(pointInState.x);
-        const numerator = useY ? args.inputPoint.y : args.inputPoint.x;
-        const denominator = useY ? pointInState.y : pointInState.x;
-        const factor = denominator !== 0 && Number.isFinite(numerator / denominator)
-            ? numerator / denominator
-            : 1;
-        return explainCoordinateMiss(pointInState, ss.screenState, (v) => Math.round(v * factor)) ?? undefined;
+        const app = (args.deviceName ? getConnectedAppByDevice(args.deviceName) : null) ?? getFirstConnectedApp();
+        const metrics = await resolveScreenSpaceMetrics({
+            platform: app?.platform ?? "ios",
+            udid: app?.simulatorUdid,
+            deviceId: app?.adbSerial
+        });
+        const normalised = screenStateToDeliveredPx(screenStateToScreenSpace(ss.screenState, metrics), metrics);
+        return explainCoordinateMiss(args.inputPoint, normalised) ?? undefined;
     }
     catch {
-        // Diagnosis is best-effort — never let it turn a successful tap into an error.
         return undefined;
     }
 }
@@ -1135,26 +963,15 @@ async function captureTapArtifact(ctx) {
     try {
         const { getServerVersion, categorizeError } = await import("../core/telemetry.js");
         const strategyChain = ctx.attempted.map(a => `${a.strategy}:${a.reason.slice(0, 40)}`).join("|");
-        // Resolve error category up-front so we can short-circuit driver-missing failures.
-        // These aren't tap-tool bugs — they're host setup problems (no idb/axe/adb on PATH).
-        // Skipping the artifact upload saves R2 storage and stops these from polluting the
-        // failure dashboard, which is the signal we use to triage genuine tap regressions.
         const errorCategory = ctx.errorCategory
             ?? categorizeError(ctx.errorMessage ?? "", strategyChain);
         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;
         }
@@ -1250,7 +1067,6 @@ function attachArtifactSignals(result, signals) {
         result.accessibilityMatchCount = signals.accessibilityMatchCount;
     if (signals.appRoute)
         result.appRoute = signals.appRoute;
-    // Append agent-facing hints to error message
     if (result.error) {
         if (signals.ocrClosestMatch) {
             result.error = `${result.error}\nClosest OCR match: ${signals.ocrClosestMatch}`;
@@ -1267,7 +1083,6 @@ function attachArtifactSignals(result, signals) {
     }
     return result;
 }
-// --- Orchestrator ---
 export async function tap(options) {
     const query = buildQuery(options);
     const strategy = options.strategy || "auto";
@@ -1275,7 +1090,6 @@ export async function tap(options) {
     const maxTraversalDepth = options.maxTraversalDepth;
     const deadline = Date.now() + TAP_TIMEOUT_MS;
     const remainingMs = () => Math.max(0, deadline - Date.now());
-    // Validate inputs
     const hasSearchParam = query.text || query.testID || query.component;
     const hasCoordinates = query.x !== undefined || query.y !== undefined;
     if (!hasSearchParam && !hasCoordinates) {
@@ -1292,7 +1106,6 @@ export async function tap(options) {
             error: "Both x and y coordinates must be provided"
         };
     }
-    // Native mode: bypass React Native connection, tap directly via ADB/simctl
     if (options.native && hasCoordinates) {
         const nativeResolved = await resolveDeviceTarget(options.device);
         if (!nativeResolved.ok) {
@@ -1305,7 +1118,6 @@ export async function tap(options) {
         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;
         let nativeBeforeBuffer = null;
         let nativeScreenshotMeta;
@@ -1320,7 +1132,6 @@ export async function tap(options) {
                 };
             }
         }
-        // If no screenshot was taken for verification, take one just for scaleFactor
         if (!nativeScreenshotMeta) {
             const ref = await captureScreenshot(platform, nativeUdid);
             if (ref) {
@@ -1329,7 +1140,6 @@ export async function tap(options) {
                     originalHeight: ref.height,
                     scaleFactor: ref.scaleFactor
                 };
-                // Also use it for verification if buffer is needed
                 if (!nativeBeforeBuffer) {
                     nativeBeforeBuffer = ref.buffer;
                 }
@@ -1398,10 +1208,6 @@ export async function tap(options) {
             suggestion: `Take a screenshot (${platform === "ios" ? "ios_screenshot" : "android_screenshot"}) to verify coordinates.`
         });
     }
-    // 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 {
@@ -1413,10 +1219,6 @@ export async function tap(options) {
     const deviceNote = resolved.note;
     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;
     let app;
@@ -1431,16 +1233,11 @@ export async function tap(options) {
             app = getConnectedAppByDevice(options.device) ?? undefined;
         }
         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 = 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.
     if (!hasMetro) {
         try {
             await withTimeout((async () => {
@@ -1463,26 +1260,17 @@ export async function tap(options) {
             }
         }
         catch {
-            // Auto-connect failed — Metro-dependent strategies will be skipped
         }
     }
-    // The response's `device` label must reflect the RESOLVED target, not the
-    // registry-app fallback. When the registry lookup couldn't find a matching
-    // app (e.g. simulatorUdid hadn't been backfilled yet), `app` lands on the
-    // first iOS entry — which on a multi-sim setup is the WRONG device. The
-    // resolver already knows the right deviceName; trust it. Bug #5 (2026-05-20).
     const deviceName = resolved.target.deviceName || app?.deviceInfo?.deviceName;
-    // Determine strategies
     const strategies = getAvailableStrategies(query, strategy);
     const attempted = [];
     const evidence = makeEmptyEvidenceSink();
-    // Early UI driver check for iOS — fail fast instead of falling through every strategy
     const UI_DRIVER_REQUIRED_STRATEGIES = ["accessibility", "ocr", "coordinate"];
     let uiDriverMissing = false;
     if (platform === "ios") {
         uiDriverMissing = !(await isUiDriverAvailable());
     }
-    // Filter strategies by available capabilities
     const filteredStrategies = strategies.filter((strat) => {
         if (strat === "fiber" && !hasMetro) {
             attempted.push({
@@ -1516,18 +1304,56 @@ export async function tap(options) {
             error: errorMessage
         };
     }
-    // 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.
+    let shadowWarning;
+    if (hasMetro) {
+        const guardBudget = Math.min(remainingMs(), OVERLAY_GUARD_BUDGET_MS);
+        if (guardBudget >= MIN_STRATEGY_BUDGET_MS) {
+            let blockedBy = null;
+            try {
+                const { checkOverlayBlocking } = await import("./overlayGuard.js");
+                blockedBy = await withTimeout(checkOverlayBlocking({
+                    query,
+                    platform,
+                    udid: targetUdid,
+                    deviceId: resolved.target.androidSerial,
+                    deviceName
+                }), guardBudget, "overlay-guard");
+            }
+            catch {
+                blockedBy = null;
+            }
+            if (blockedBy?.kind === "blocked") {
+                attempted.push({
+                    strategy: "overlay-guard",
+                    reason: `refused — target covered by ${blockedBy.overlay}`,
+                    outcome: "skipped"
+                });
+                return {
+                    success: false,
+                    query,
+                    attempted,
+                    device: deviceName,
+                    platform,
+                    error: `Refused: ${blockedBy.element} is covered by ${blockedBy.overlay}. ` +
+                        `A tap here would be delivered to the overlay, not to the target, ` +
+                        `so it was not dispatched.`,
+                    suggestion: `Dismiss or close the overlay first, then retry. ` +
+                        `get_screen_state lists the overlay's own controls, and everything behind it under "🚫 Blocked by overlay". ` +
+                        `To tap the overlay itself, use coordinates from its own group.`
+                };
+            }
+            if (blockedBy?.kind === "shadowed") {
+                shadowWarning =
+                    `This coordinate is occupied by ${blockedBy.hit}, part of ${blockedBy.overlay} — ` +
+                        `that is what received the tap. ${blockedBy.covered} sits underneath it and ` +
+                        `cannot be tapped until the overlay closes.`;
+            }
+        }
+    }
     const shouldScreenshot = options.screenshot !== false;
     const canVerify = options.verify !== false;
-    // 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;
-    // Pixel dimensions of the frame we just captured. getDevicePixelRatio would
-    // otherwise shell out for a screenshot of its own to learn exactly this.
     let beforeDims;
     {
         const before = await captureScreenshot(platform, targetUdid);
@@ -1537,16 +1363,6 @@ export async function tap(options) {
             beforeDims = { width: before.width, height: before.height };
         }
     }
-    // OCR runs lazily when the loop reaches it (see the `case "ocr"` branch).
-    // A concurrent pre-warm probe used to fire here to shave ~5s off OCR-win
-    // rows, but it dispatched a paid Google Vision request at t=0 on every
-    // text-predicate tap — and since cloud OCR (~200ms) finishes well before
-    // the higher-priority strategy that usually wins, the post-win abort came
-    // too late to cancel the billed request. OCR wins only ~1.9% of taps, so
-    // the pre-warm paid for cloud Vision on ~42% of eligible taps to help a
-    // tiny minority. Removed 2026-06-02; the timeout-recovery path below still
-    // salvages the perfect-match-past-cap case.
-    // Execute strategies in order with per-strategy caps and overall budget
     for (const strat of filteredStrategies) {
         const remaining = remainingMs();
         if (remaining < MIN_STRATEGY_BUDGET_MS) {
@@ -1563,8 +1379,6 @@ export async function tap(options) {
         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, deviceName), budget, `fiber`);
                     break;
                 case "accessibility":
@@ -1574,9 +1388,6 @@ export async function tap(options) {
                     result = await withCancelableTimeout((signal) => tryOcrStrategy(query, platform, targetUdid, evidence, signal), budget, `ocr`);
                     break;
                 case "coordinate":
-                    // Prefer `beforeScaleFactor` (captured against `targetUdid` this turn)
-                    // over `app.lastScreenshot.scaleFactor` (stale and may belong to a
-                    // different device on a multi-sim setup). Bug #5 (2026-05-20).
                     result = await withTimeout(tryCoordinateStrategy(query.x, query.y, platform, beforeScaleFactor != null
                         ? {
                             originalWidth: beforeDims?.width ?? 0,
@@ -1591,11 +1402,6 @@ export async function tap(options) {
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
-            // 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;
@@ -1630,11 +1436,6 @@ export async function tap(options) {
                     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
-                // 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;
             }
@@ -1648,8 +1449,6 @@ export async function tap(options) {
                     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;
             }
@@ -1674,18 +1473,12 @@ export async function tap(options) {
                 screenshot,
                 verification
             });
-            // Capture an artifact for "successful but unmeaningful" taps so we can
-            // diagnose taps that landed wrong or hit non-responsive elements.
-            // Uses the same `meaningful` flag the agent sees so dashboard outcomes
-            // stay consistent with what the caller observed.
+            if (shadowWarning) {
+                successResult.warning = successResult.warning
+                    ? `${successResult.warning}\n${shadowWarning}`
+                    : shadowWarning;
+            }
             if (verification && !verification.skipped && verification.meaningful === false) {
-                // A coordinate tap that changed nothing is the one case where the
-                // agent has no idea what went wrong — it estimated x/y from a
-                // screenshot and got back "nothing happened". Screen state knows
-                // what sits at that point and what an overlay blocks; spend the
-                // ~200ms here (already the slow path) to turn a dead end into a
-                // next step. Text/testID/component predicates don't need this:
-                // their failure modes are already named in `attempted`.
                 if (strat === "coordinate" && result.convertedTo) {
                     const diagnosis = await diagnoseCoordinateMiss({
                         point: { x: result.convertedTo.x, y: result.convertedTo.y },
@@ -1721,10 +1514,6 @@ export async function tap(options) {
             }
             return successResult;
         }
-        // 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)
@@ -1734,36 +1523,26 @@ export async function tap(options) {
         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 {
                 const coords = result.convertedTo;
                 if (platform === "ios") {
-                    // react-native-screens modal/sheet presentations cause measureInWindow to
-                    // return y relative to the screen's content origin, not the window. If the
-                    // measured y falls inside the safe-area band, shift it down by the inset.
                     const safeAreaTop = await getIOSSafeAreaTop(targetUdid);
                     const tapY = (safeAreaTop > 0 && coords.y < safeAreaTop) ? coords.y + safeAreaTop : coords.y;
                     await iosTap(coords.x, tapY, { udid: targetUdid });
                     coords.y = tapY;
                 }
                 else {
-                    // Fabric returns dp — androidTap expects pixels
-                    // Convert dp to pixels using device density
                     const { androidGetDensity } = await import("../core/android.js");
                     const densityResult = await androidGetDensity();
                     const densityScale = (densityResult.density || 420) / 160;
                     const pxX = Math.round(coords.x * densityScale);
                     const pxY = Math.round(coords.y * densityScale);
                     await androidTap(pxX, pxY);
-                    // Report the actual tap coords (pixels) the caller can pass straight
-                    // to coordinate tools / verification — not the raw dp from fiber.
-                    // Matches every other Android coord report in the tool (OB1, 2026-05-20).
                     coords.x = pxX;
                     coords.y = pxY;
                     coords.unit = "pixels";
                 }
-                // fiber+native uses native tap — always verify
                 let screenshot;
                 let verification;
                 let fnDpr;
@@ -1840,12 +1619,8 @@ export async function tap(options) {
                 });
             }
             catch {
-                // Native tap at fiber coordinates failed — continue to next strategy
             }
         }
-        // Ambiguous fiber result — multiple elements matched, no index given.
-        // Return immediately with the full list so the agent can decide.
-        // Do NOT fall through to other strategies (they can't resolve ambiguity).
         if (result.matches && result.ambiguous) {
             const { screenshot: matchScreenshot } = shouldScreenshot
                 ? await verifyAndCapture({ platform, shouldVerify: false, shouldScreenshot: true, beforeBuffer: null, udid: targetUdid })
@@ -1869,15 +1644,8 @@ export async function tap(options) {
             });
         }
     }
-    // All strategies failed — check if the tap budget was the cause.
-    // Only outer withTimeout wrapper messages or Skipped entries count; nested
-    // sub-op errors that happen to contain "timed out" do not imply the tap
-    // itself ran out of time.
     const hitTimeout = isTapTimeout(attempted);
     const elapsed = TAP_TIMEOUT_MS - remainingMs();
-    // 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);
@@ -1885,8 +1653,6 @@ export async function tap(options) {
         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
@@ -1899,8 +1665,6 @@ 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)`;
@@ -1935,10 +1699,6 @@ export async function tap(options) {
     });
     return attachArtifactSignals(failureResult, failSignals);
 }
-// Matches testIDs typical of virtualized list items: trailing `-<digits>` (e.g. `store-item-0`,
-// `route-item-6`) or containing a UUID v4 fragment (e.g. `group-card-e4566bc6-9164-4fd0-...`).
-// Used by buildSuggestion() to tell the agent to scroll first when a list-item testID
-// can't be found in the visible fiber tree.
 const VIRTUALIZED_TESTID_RE = /(-\d+$)|([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i;
 function looksLikeVirtualizedListItem(testID) {
     return VIRTUALIZED_TESTID_RE.test(testID);
@@ -1960,10 +1720,6 @@ function buildSuggestion(query, triedStrategies, platform) {
     if (query.testID && !triedStrategies.includes("ocr")) {
         suggestions.push("testID not found in fiber/accessibility tree — verify the element is on the current screen with a screenshot");
     }
-    // List-item testIDs (suffix `-N` or containing a UUID) are typically rendered inside a
-    // virtualized list — items beyond the viewport are unmounted, so the fiber tree genuinely
-    // doesn't contain them. Adding the hint as a separate suggestion (rather than rewriting
-    // 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 " +
             `(swipe()${platform === "ios" ? " or ios_button arrow keys" : ""}) before tapping`);