@devicelab/maestro-runner-darwin-arm64 1.1.25 → 1.1.28

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerTests+CommandExecution.swift

@@ -122,10 +122,15 @@ extension RunnerTests {
 
   private func executeOnMain(command: Command) throws -> Response {
     var activeApp = currentApp ?? app
-    if !isRunnerLifecycleCommand(command.command) {
-      let normalizedBundleId = command.appBundleId?
-        .trimmingCharacters(in: .whitespacesAndNewlines)
-      let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+    if isPassiveReadCommand(command.command) {
+      switch passiveReadTarget(requestedBundleId: normalizedBundleId(command)) {
+      case .app(let target):
+        activeApp = target
+      case .refused(let response):
+        return response
+      }
+    } else if !isRunnerLifecycleCommand(command.command) {
+      let requestedBundleId = normalizedBundleId(command)
       if let bundleId = requestedBundleId {
         if currentBundleId != bundleId || currentApp == nil {
           _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
@@ -445,6 +450,12 @@ extension RunnerTests {
       let y = Double(matched.frame.midY)
       let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
       var outcome = RunnerInteractionOutcome.performed
+      // A no-op recovery guard: capture the screen just before the tap so we
+      // can tell, after, whether the tap actually did anything. Only when the
+      // activation-retry path is enabled (default off; opt in with
+      // DEVICELAB_ENABLE_TAP_ACTIVATION_RETRY=1) — otherwise we pay nothing.
+      let beforeTap: RunnerImage? = tapActivationRetryEnabled
+        ? XCUIScreen.main.screenshot().image : nil
       let timing = measureGesture {
         withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
           outcome = tapAt(app: activeApp, x: x, y: y)
@@ -453,6 +464,26 @@ extension RunnerTests {
       if let response = unsupportedResponse(for: outcome) {
         return response
       }
+      // A coordinate tap on some React Native controls reports success but
+      // never fires the control's handler — the navigation simply does not
+      // happen (observed on native-stack "Pop to top" after a deep push; WDA
+      // passes the same flow). Detect that exact no-op — the screen did not
+      // change AND the same element is still on screen and hittable — and
+      // re-tap through the element's activation point, which resolves the
+      // handler the way WDA's element.tap() does. Gated on a proven no-op, so
+      // a normal tap costs one screenshot and no extra tap. The primary tap
+      // and its returned x/y are unchanged, so inputText's tapped-coordinate
+      // coupling still holds.
+      if let before = beforeTap {
+        Thread.sleep(forTimeInterval: 0.3)
+        let after = XCUIScreen.main.screenshot().image
+        if computePixelDiffFraction(before, after) < tapNoOpDiffThreshold,
+           let live = liveElementForSnapshot(activeApp, matched),
+           live.exists, live.isHittable {
+          NSLog("DL_TAP_ACTIVATION_RETRY selector=%@", selectorValue)
+          live.tap()
+        }
+      }
       // Note: response returns the raw element-relative x/y, not
       // touchFrame.x/y. touchFrame applies the appFrame origin (screen-
       // absolute), but the Go side feeds these into the next inputText's
@@ -593,8 +624,10 @@ extension RunnerTests {
       guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
         return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
       }
-      let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
+      // A hold of 0 is allowed: a synthesized swipe needs no press first.
+      let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0), 10.0)
       let moveDuration = command.moveDurationMs.map { min(max($0 / 1000.0, 0.05), 30.0) }
+      let restDuration = command.restMs.map { min(max($0 / 1000.0, 0), 10.0) }
       let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
       let dragFrame = resolvedDragVisualizationFrame(
         app: activeApp,
@@ -613,7 +646,8 @@ extension RunnerTests {
             x2: dragPoints.x2,
             y2: dragPoints.y2,
             holdDuration: holdDuration,
-            moveDuration: moveDuration
+            moveDuration: moveDuration,
+            restDuration: restDuration
           )
         }
       }
@@ -765,20 +799,29 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "readText did not resolve text"))
       }
       return Response(ok: true, data: DataPayload(text: text))
+    case .idle:
+      return executeIdle(app: activeApp, command: command)
+    case .settle:
+      return executeSettle(command: command)
     case .snapshot:
+      if let refused = unreadableSnapshotTarget(activeApp) {
+        return refused
+      }
       let options = SnapshotOptions(
         interactiveOnly: command.interactiveOnly ?? false,
         compact: command.compact ?? false,
         depth: command.depth,
         scope: command.scope,
-        raw: command.raw ?? false
+        raw: command.raw ?? false,
+        followsScreen: (command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "").isEmpty,
+        visibleOnly: command.visibleOnly ?? false
       )
-      if options.raw {
-        needsPostSnapshotInteractionDelay = true
-        return Response(ok: true, data: snapshotRaw(app: activeApp, options: options))
+      let target = activeApp
+      return withSnapshotRequestTimeout {
+        options.raw
+          ? snapshotRaw(app: target, options: options)
+          : snapshotFast(app: target, options: options)
       }
-      needsPostSnapshotInteractionDelay = true
-      return Response(ok: true, data: snapshotFast(app: activeApp, options: options))
     case .screenshot:
       let screenshot: XCUIScreenshot
 #if os(macOS)
@@ -935,7 +978,12 @@ extension RunnerTests {
           (command.x != nil && command.y != nil)
           ? "no text input found at the provided coordinates to clear"
           : "no focused text input to clear"
-        return Response(ok: false, error: ErrorPayload(message: message))
+        return Response(ok: false, error: ErrorPayload(code: "NO_TEXT_INPUT", message: message))
+      }
+      if text.isEmpty, let count = command.deleteCount, count > 0,
+        let erased = eraseTrailingCharacters(app: activeApp, target: target, count: count)
+      {
+        return erased
       }
     }
     let textResult = typeTextReliably(
@@ -945,17 +993,23 @@ extension RunnerTests {
       delaySeconds: delaySeconds,
       repairMode: textEntryMode
     )
+    let outcome = DataPayload(
+      message: textResult.repaired ? "typed after repair" : "typed",
+      verified: textResult.verified,
+      repaired: textResult.repaired
+    )
     if textResult.verified == false {
       let expected = textResult.expectedText ?? ""
       let observed = textResult.observedText ?? ""
       return Response(
         ok: false,
+        data: outcome,
         error: ErrorPayload(
           code: "TEXT_ENTRY_MISMATCH",
           message: "text entry verification failed: expected \"\(expected)\", observed \"\(observed)\""
         )
       )
     }
-    return Response(ok: true, data: DataPayload(message: textResult.repaired ? "typed after repair" : "typed"))
+    return Response(ok: true, data: outcome)
   }
 }

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerTests+Interaction.swift

@@ -455,58 +455,49 @@ extension RunnerTests {
     // tree-signature, flat node list) in a single pass. We accumulate
     // hash bits into a Hasher as we visit each node and collect matches
     // along the way.
+    // walkOnce returns the best on-screen match and the tree signature. Only
+    // a match whose centre is on screen, with at least 10% of it visible,
+    // counts: a web page parks copies of a link off the edge, and tapping
+    // one of those "succeeded" while touching nothing. A miss sends no tree
+    // back — the Go side re-reads its own (visible-only) snapshot anyway.
     func walkOnce(root: XCUIElementSnapshot) -> (XCUIElementSnapshot?, UInt64, [SnapshotNode]) {
       var hasher = Hasher()
-      var allNodes: [SnapshotNode] = []
       var matches: [(XCUIElementSnapshot, Int, Int)] = []
+      let viewport = root.children.first {
+        $0.elementType == .window && !$0.frame.isNull && !$0.frame.isEmpty
+      }?.frame ?? root.frame
 
-      func walk(_ snap: XCUIElementSnapshot, depth: Int, parentIdx: Int?) {
+      func walk(_ snap: XCUIElementSnapshot) {
+        let frame = snap.frame
         // Tree-signature contribution: geometry + identity bits.
         hasher.combine(snap.elementType.rawValue)
         hasher.combine(snap.identifier)
         hasher.combine(snap.label)
-        hasher.combine(Int(snap.frame.origin.x))
-        hasher.combine(Int(snap.frame.origin.y))
-        hasher.combine(Int(snap.frame.size.width))
-        hasher.combine(Int(snap.frame.size.height))
-
-        // Match-candidate collection + flat-node serialisation.
-        let label = snap.label.trimmingCharacters(in: .whitespacesAndNewlines)
-        let identifier = snap.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-        let valueText = String(describing: snap.value ?? "")
-          .trimmingCharacters(in: .whitespacesAndNewlines)
-        let nodeIdx = allNodes.count
-        allNodes.append(SnapshotNode(
-          index: nodeIdx,
-          type: elementTypeName(snap.elementType),
-          label: label.isEmpty ? nil : label,
-          identifier: identifier.isEmpty ? nil : identifier,
-          value: valueText.isEmpty ? nil : valueText,
-          placeholderValue: nil,
-          rect: snapshotRect(from: snap.frame),
-          enabled: snap.isEnabled,
-          focused: nil,
-          selected: snap.isSelected ? true : nil,
-          hittable: false,
-          depth: depth,
-          parentIndex: parentIdx,
-          hiddenContentAbove: nil,
-          hiddenContentBelow: nil
-        ))
-        if let kind = nodeMatchKind(label: label, identifier: identifier, valueText: valueText) {
-          if !snap.frame.isNull && !snap.frame.isEmpty {
+        hasher.combine(Int(frame.origin.x))
+        hasher.combine(Int(frame.origin.y))
+        hasher.combine(Int(frame.size.width))
+        hasher.combine(Int(frame.size.height))
+
+        let onScreen = viewport.contains(CGPoint(x: frame.midX, y: frame.midY))
+          && Self.visibleFraction(frame, in: viewport) >= Self.minVisibleFraction
+        if onScreen {
+          let label = snap.label.trimmingCharacters(in: .whitespacesAndNewlines)
+          let identifier = snap.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
+          let valueText = String(describing: snap.value ?? "")
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+          if let kind = nodeMatchKind(label: label, identifier: identifier, valueText: valueText) {
             matches.append((snap, kind, typeRank(snap.elementType)))
           }
         }
         for child in snap.children {
-          walk(child, depth: depth + 1, parentIdx: nodeIdx)
+          walk(child)
         }
       }
-      walk(root, depth: 0, parentIdx: nil)
+      walk(root)
 
       matches.sort { ($0.1, $0.2) < ($1.1, $1.2) }
       let sig = UInt64(bitPattern: Int64(hasher.finalize()))
-      return (matches.first?.0, sig, allNodes)
+      return (matches.first?.0, sig, [])
     }
 
     let started = Date()
@@ -616,6 +607,26 @@ extension RunnerTests {
     return nil
   }
 
+  /// Local edit (eraseText with a count): delete `count` characters from the
+  /// end of the field, as Maestro does. Returns nil when the count covers the
+  /// whole value, so the caller clears the field through the verified path.
+  func eraseTrailingCharacters(
+    app: XCUIApplication, target: TextEntryTarget, count: Int
+  ) -> Response? {
+    guard let element = resolveTextEntryElement(app: app, target: target) else {
+      return nil
+    }
+    let current = normalizedElementText(element.value)
+    guard !current.isEmpty, count < current.count else {
+      return nil
+    }
+#if !os(tvOS)
+    moveCaretToEnd(element: element)
+#endif
+    element.typeText(String(repeating: XCUIKeyboardKey.delete.rawValue, count: count))
+    return Response(ok: true, data: DataPayload(message: "erased \(count) characters"))
+  }
+
   func clearTextInput(_ element: XCUIElement) {
 #if !os(tvOS)
     moveCaretToEnd(element: element)
@@ -866,6 +877,13 @@ extension RunnerTests {
     repairMode: TextTypingRepairMode = .none
   ) -> TextEntryResult {
     guard !text.isEmpty else {
+      // Replacing a field WITH "" is the clear-field primitive (eraseText,
+      // Playwright fill("")/clear()): the typing is vacuous but the clear is
+      // not. Append and unrepaired entry stay no-ops, which is what an empty
+      // payload means for them.
+      if repairMode == .replacement {
+        return clearTextEntry(app: app, target: target)
+      }
       return TextEntryResult(verified: true, repaired: false, expectedText: "", observedText: "")
     }
     var activeTarget = target
@@ -993,6 +1011,61 @@ extension RunnerTests {
     )
   }
 
+  /// Clears the resolved text input and verifies it reads back empty (a
+  /// visible placeholder counts as empty), clearing once more if the first
+  /// pass left text behind — the same single repair the non-empty
+  /// replacement path gets. Local edit, adapted from upstream agent-device
+  /// #2066, which fixed the same early return but without the repair pass.
+  /// `verified` stays nil when the value is unreadable (secure fields) or
+  /// the input cannot be resolved, matching the non-empty replacement path.
+  private func clearTextEntry(app: XCUIApplication, target: TextEntryTarget) -> TextEntryResult {
+    guard let clearTarget = resolveTextEntryElement(app: app, target: target) else {
+      return TextEntryResult(verified: nil, repaired: false, expectedText: "", observedText: nil)
+    }
+    let activeTarget = target.withElement(clearTarget)
+    clearTextInput(clearTarget)
+    let firstObserved = awaitClearedTextValue(app: app, target: activeTarget)
+    guard let leftover = firstObserved, !leftover.isEmpty else {
+      return TextEntryResult(
+        verified: firstObserved.map { $0.isEmpty },
+        repaired: false,
+        expectedText: "",
+        observedText: firstObserved
+      )
+    }
+    NSLog("DEVICELAB_RUNNER_REPAIR_CLEAR_TEXT observedLength=%d", leftover.count)
+    if let repairTarget = resolveTextEntryElement(app: app, target: activeTarget) {
+      clearTextInput(repairTarget)
+    }
+    let observed = awaitClearedTextValue(app: app, target: activeTarget)
+    return TextEntryResult(
+      verified: observed.map { $0.isEmpty },
+      repaired: true,
+      expectedText: "",
+      observedText: observed
+    )
+  }
+
+  /// Polls the input's value (placeholder read as empty) until it is empty
+  /// or the verification window elapses, so a value still committing the
+  /// deletes is not mistaken for a failed clear. Returns the last reading;
+  /// nil when the value is unreadable.
+  private func awaitClearedTextValue(app: XCUIApplication, target: TextEntryTarget) -> String? {
+    let deadline = Date().addingTimeInterval(TextEntryTiming.verificationStabilityWindow)
+    var observed = editableTextValue(
+      for: resolveTextEntryElement(app: app, target: target),
+      treatingPlaceholderAsEmpty: true
+    )
+    while observed?.isEmpty == false && Date() < deadline {
+      sleepFor(TextEntryTiming.pollInterval)
+      observed = editableTextValue(
+        for: resolveTextEntryElement(app: app, target: target),
+        treatingPlaceholderAsEmpty: true
+      )
+    }
+    return observed
+  }
+
   private func repairTextEntryIfNeeded(
     app: XCUIApplication,
     target: TextEntryTarget,
@@ -1506,7 +1579,8 @@ extension RunnerTests {
     x2: Double,
     y2: Double,
     holdDuration: TimeInterval,
-    moveDuration: TimeInterval? = nil
+    moveDuration: TimeInterval? = nil,
+    restDuration: TimeInterval? = nil
   ) -> RunnerInteractionOutcome {
     // tvOS has no coordinate drag. Preserve the direction as a focus move.
     let dx = x2 - x
@@ -1519,7 +1593,7 @@ extension RunnerTests {
     }
     return performCoordinateDrag(
       app: app, x: x, y: y, x2: x2, y2: y2,
-      holdDuration: holdDuration, moveDuration: moveDuration)
+      holdDuration: holdDuration, moveDuration: moveDuration, restDuration: restDuration)
   }
 
   func keyboardAvoidingDragPoints(
@@ -1531,6 +1605,13 @@ extension RunnerTests {
   ) -> DragPoints {
     let original = DragPoints(x: x, y: y, x2: x2, y2: y2)
 #if os(iOS)
+    // No keyboard reaches the upper part of the screen, and looking for one
+    // is a query that walks the whole tree on a web page — skip it for a
+    // gesture that stays up there (every scroll: centre to 10% from the top).
+    let screenHeight = Double(UIScreen.main.bounds.height)
+    if screenHeight > 0 && max(y, y2) < screenHeight * 0.55 {
+      return original
+    }
     guard let keyboardFrame = visibleKeyboardFrame(app: app) else {
       return original
     }
@@ -1584,17 +1665,12 @@ extension RunnerTests {
 #endif
   }
 
+  /// The touch point echoed in a gesture's response. It used to resolve the
+  /// app frame, its windows and the keyboard — three or four queries, each
+  /// walking the whole tree on a web page — on every tap and drag, for
+  /// reference sizes no host reads. The point is already in screen space.
   func resolvedTouchVisualizationFrame(app: XCUIApplication, x: Double, y: Double) -> TouchVisualizationFrame {
-    let appFrame = app.frame
-    let referenceFrame = resolvedTouchReferenceFrame(app: app, appFrame: appFrame)
-    let originX = appFrame.isEmpty ? referenceFrame.minX : appFrame.minX
-    let originY = appFrame.isEmpty ? referenceFrame.minY : appFrame.minY
-    return TouchVisualizationFrame(
-      x: originX + x,
-      y: originY + y,
-      referenceWidth: referenceFrame.width,
-      referenceHeight: referenceFrame.height
-    )
+    return TouchVisualizationFrame(x: x, y: y, referenceWidth: 0, referenceHeight: 0)
   }
 
   func resolvedDragVisualizationFrame(
@@ -1769,10 +1845,62 @@ extension RunnerTests {
     return app
   }
 
+  // MARK: - Synthesized touches
+  //
+  // Taps, swipes and scrolls go to the screen as synthesized touch events
+  // (Maestro's and WebDriverAgent's mechanism), in screen points — the space
+  // snapshot frames are in. XCUICoordinate first resolves the app's windows
+  // (a query that walks the whole tree on a web page) and waits for the app
+  // to go idle before and after; its press(forDuration:thenDragTo:) also has
+  // no way to fling. The XCUICoordinate path stays as the fallback.
+
+  /// Press time of a synthesized tap, and the gap between the taps of a
+  /// double tap.
+  static let syntheticTapPress: TimeInterval = 0.05
+  static let syntheticDoubleTapGap: TimeInterval = 0.1
+
+  /// UIInterfaceOrientation to stamp on a synthesized event, or nil when the
+  /// device is rotated: synthesized points are used only in portrait, where
+  /// screen points and snapshot frames coincide. Rotated screens keep the
+  /// XCUICoordinate path.
+  private func syntheticOrientation() -> Int64? {
+    switch XCUIDevice.shared.orientation {
+    case .portrait, .unknown, .faceUp, .faceDown:
+      return Int64(UIInterfaceOrientation.portrait.rawValue)
+    default:
+      return nil
+    }
+  }
+
+  private func sendSyntheticTaps(x: Double, y: Double, count: Int, press: TimeInterval) -> Bool {
+    guard let orientation = syntheticOrientation() else { return false }
+    var error: NSError?
+    if DLSendSyntheticTaps(CGPoint(x: x, y: y), UInt(count), press, Self.syntheticDoubleTapGap, orientation, &error) {
+      return true
+    }
+    NSLog("DL_SYNTH_FALLBACK taps error=%@", error?.localizedDescription ?? "unknown")
+    return false
+  }
+
+  private func sendSyntheticTouch(
+    from: CGPoint, to: CGPoint, hold: TimeInterval, move: TimeInterval, rest: TimeInterval
+  ) -> Bool {
+    guard let orientation = syntheticOrientation() else { return false }
+    var error: NSError?
+    if DLSendSyntheticTouch(from, to, hold, move, rest, orientation, &error) {
+      return true
+    }
+    NSLog("DL_SYNTH_FALLBACK touch error=%@", error?.localizedDescription ?? "unknown")
+    return false
+  }
+
   private func performCoordinateTap(app: XCUIApplication, x: Double, y: Double) -> RunnerInteractionOutcome {
 #if os(tvOS)
     return .unsupported("coordinate tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element")
 #else
+    if sendSyntheticTaps(x: x, y: y, count: 1, press: Self.syntheticTapPress) {
+      return .performed
+    }
     interactionCoordinate(app: app, x: x, y: y).tap()
     return .performed
 #endif
@@ -1782,6 +1910,9 @@ extension RunnerTests {
 #if os(tvOS)
     return .unsupported("coordinate double tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element")
 #else
+    if sendSyntheticTaps(x: x, y: y, count: 2, press: Self.syntheticTapPress) {
+      return .performed
+    }
     interactionCoordinate(app: app, x: x, y: y).doubleTap()
     return .performed
 #endif
@@ -1791,11 +1922,21 @@ extension RunnerTests {
 #if os(tvOS)
     return .unsupported("coordinate long press is not supported on tvOS; move focus with swipe or scroll, then long-select the focused element")
 #else
+    if sendSyntheticTaps(x: x, y: y, count: 1, press: duration) {
+      return .performed
+    }
     interactionCoordinate(app: app, x: x, y: y).press(forDuration: duration)
     return .performed
 #endif
   }
 
+  /// A hold longer than this is a drag-and-drop lift, which keeps
+  /// XCUICoordinate's paced drag; anything shorter is a swipe or a scroll.
+  static let maxSwipeHold: TimeInterval = 0.05
+  /// Move time of a synthesized swipe when the caller gives none — the 0.1s
+  /// Maestro's swipes use.
+  static let defaultSwipeMove: TimeInterval = 0.1
+
   private func performCoordinateDrag(
     app: XCUIApplication,
     x: Double,
@@ -1803,11 +1944,26 @@ extension RunnerTests {
     x2: Double,
     y2: Double,
     holdDuration: TimeInterval,
-    moveDuration: TimeInterval? = nil
+    moveDuration: TimeInterval? = nil,
+    restDuration: TimeInterval? = nil
   ) -> RunnerInteractionOutcome {
 #if os(tvOS)
     return .unsupported("coordinate drag is not supported on tvOS")
 #else
+    if holdDuration <= Self.maxSwipeHold {
+      // A paced move used to end with a 0.25s hold; keep that when the
+      // caller asks for a pace but no rest.
+      let rest = restDuration ?? (moveDuration != nil ? 0.25 : 0)
+      if sendSyntheticTouch(
+        from: CGPoint(x: x, y: y),
+        to: CGPoint(x: x2, y: y2),
+        hold: holdDuration,
+        move: moveDuration ?? Self.defaultSwipeMove,
+        rest: rest
+      ) {
+        return .performed
+      }
+    }
     let start = interactionCoordinate(app: app, x: x, y: y)
     let end = interactionCoordinate(app: app, x: x2, y: y2)
     if let moveDuration, moveDuration > 0 {
@@ -1841,6 +1997,58 @@ extension RunnerTests {
   }
 #endif
 
+  // tapNoOpDiffThreshold is the pixel-diff fraction below which the screen is
+  // considered unchanged after a tap. A real navigation changes far more than
+  // this; a button's brief press highlight has faded by the 0.3s settle. Used
+  // only to detect a tap that fired nothing, so it can be re-tried via the
+  // element's activation point.
+  var tapNoOpDiffThreshold: Double { 0.004 }
+
+  // tapActivationRetryEnabled gates the no-op recovery re-tap. Default OFF —
+  // it closes the native-stack "Pop to top" no-op flows, but the no-op probe
+  // costs a screenshot plus a 0.3s settle on EVERY tap, which erodes the
+  // driver's speed lead, and the pixel-diff no-op signal is not yet precise
+  // enough to ship on by default. Opt in with
+  // DEVICELAB_ENABLE_TAP_ACTIVATION_RETRY=1 until the probe is made cheap and
+  // precise (a targeted post-tap check, not a blanket screenshot+sleep).
+  var tapActivationRetryEnabled: Bool {
+    RunnerEnv.isTruthy("DEVICELAB_ENABLE_TAP_ACTIVATION_RETRY")
+  }
+
+  // liveElementForSnapshot resolves the live XCUIElement behind a matched
+  // snapshot, so the no-op recovery can re-tap it through its activation point
+  // (a snapshot has no tap()). Queries by the snapshot's own type + identifier
+  // / label, disambiguating multiple matches by frame proximity. Returns nil
+  // when it cannot be uniquely resolved — the caller then leaves the tap as
+  // the coordinate tap it already did.
+  func liveElementForSnapshot(_ app: XCUIApplication, _ snapshot: XCUIElementSnapshot) -> XCUIElement? {
+    let id = snapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
+    let label = snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
+    var clauses: [String] = []
+    var args: [String] = []
+    if !id.isEmpty {
+      clauses.append("identifier == %@")
+      args.append(id)
+    }
+    if !label.isEmpty {
+      clauses.append("label == %@")
+      args.append(label)
+    }
+    guard !clauses.isEmpty else { return nil }
+    let predicate = NSPredicate(format: clauses.joined(separator: " OR "), argumentArray: args)
+    let matches = app.descendants(matching: snapshot.elementType)
+      .matching(predicate)
+      .allElementsBoundByIndex
+    if matches.isEmpty { return nil }
+    if matches.count == 1 { return matches[0] }
+    let target = snapshot.frame
+    return matches.min(by: { a, b in
+      let da = abs(a.frame.midX - target.midX) + abs(a.frame.midY - target.midY)
+      let db = abs(b.frame.midX - target.midX) + abs(b.frame.midY - target.midY)
+      return da < db
+    })
+  }
+
   private func tapElementCenter(app: XCUIApplication, element: XCUIElement) {
     let frame = element.frame
     if !frame.isEmpty {