agent-device 0.20.2 → 0.20.4

package/android/ime-helper/dist/agent-device-android-ime-helper-0.20.4.apk.sha256

@@ -0,0 +1 @@
+019ebbda52976df5cff05f9e5a764c8d6e280be3640e8dea0a2d7cca6c25021f  agent-device-android-ime-helper-0.20.4.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.2.manifest.json → agent-device-android-ime-helper-0.20.4.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.20.2",
-  "assetName": "agent-device-android-ime-helper-0.20.2.apk",
-  "sha256": "941f2997c4315e753fb2f5411562a2907b3a188370c3d52e762692843be1b50f",
+  "version": "0.20.4",
+  "assetName": "agent-device-android-ime-helper-0.20.4.apk",
+  "sha256": "019ebbda52976df5cff05f9e5a764c8d6e280be3640e8dea0a2d7cca6c25021f",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20002,
+  "versionCode": 20004,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.20.4.apk.sha256

@@ -0,0 +1 @@
+e3799afe5549776e047744efe46939a9146a4742a5328bb2e22f0b9d6abd2b52  agent-device-android-snapshot-helper-0.20.4.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.2.manifest.json → agent-device-android-snapshot-helper-0.20.4.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.20.2",
-  "releaseTag": "v0.20.2",
-  "assetName": "agent-device-android-snapshot-helper-0.20.2.apk",
+  "version": "0.20.4",
+  "releaseTag": "v0.20.4",
+  "assetName": "agent-device-android-snapshot-helper-0.20.4.apk",
   "apkUrl": null,
-  "sha256": "003859ea5dc5d1ed8ddc5daf786eacb790ff471bbb0c3b0e1239712f73f37684",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.2.apk.sha256",
+  "sha256": "e3799afe5549776e047744efe46939a9146a4742a5328bb2e22f0b9d6abd2b52",
+  "checksumName": "agent-device-android-snapshot-helper-0.20.4.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20002,
+  "versionCode": 20004,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -922,6 +922,49 @@ extension RunnerTests {
             x: touchPoint.x,
             y: touchPoint.y
           )
+          var fallback: GestureFallback?
+          if command.synthesized == true {
+            let policyKind = SynthesizedGesturePolicyKind.coordinateTap
+            let context = synthesizedCoordinateContext(
+              app: activeApp,
+              policy: synthesizedGesturePolicy(policyKind)
+            )
+            let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+              synthesizedTapAt(
+                app: activeApp,
+                x: touchPoint.x,
+                y: touchPoint.y,
+                context: context
+              )
+            }
+            if case .performed = outcome {
+              logSynthesizedGesturePolicyDecision(
+                kind: policyKind,
+                context: context,
+                fallbackAttempted: false
+              )
+              if isTextEntry {
+                waitForTextEntryReadinessAfterTap(app: activeApp, element: element)
+              }
+              return gestureResponse(
+                message: match.usedNonHittableFallback
+                  ? "tapped via non-hittable coordinate fallback"
+                  : "tapped",
+                timing: timing,
+                frame: .touch(touchFrame),
+                maestroNonHittableCoordinateFallbackUsed:
+                  command.allowNonHittableCoordinateFallback == true
+                  ? match.usedNonHittableFallback
+                  : nil
+              )
+            }
+            logSynthesizedGesturePolicyDecision(
+              kind: policyKind,
+              context: context,
+              fallbackAttempted: true
+            )
+            fallback = gestureFallback(strategy: "xctest-coordinate-tap", from: outcome)
+          }
           let (timing, outcome) = performGesture(activeApp) {
             if expectedPoint != nil || match.usedNonHittableFallback {
               // Maestro compatibility: RN E2E backdoor controls can be 1x1 and
@@ -942,6 +985,7 @@ extension RunnerTests {
             message: match.usedNonHittableFallback ? "tapped via non-hittable coordinate fallback" : "tapped",
             timing: timing,
             frame: .touch(touchFrame),
+            fallback: fallback,
             maestroNonHittableCoordinateFallbackUsed:
               command.allowNonHittableCoordinateFallback == true
               ? match.usedNonHittableFallback
@@ -954,7 +998,10 @@ extension RunnerTests {
         var fallback: GestureFallback?
         if command.synthesized == true {
           let policyKind = SynthesizedGesturePolicyKind.coordinateTap
-          let context = synthesizedCoordinateContext(policy: synthesizedGesturePolicy(policyKind))
+          let context = synthesizedCoordinateContext(
+            app: activeApp,
+            policy: synthesizedGesturePolicy(policyKind)
+          )
           let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
             synthesizedTapAt(app: activeApp, x: x, y: y, context: context)
           }
@@ -1045,7 +1092,10 @@ extension RunnerTests {
         )
       }
       let scrollPolicyKind = SynthesizedGesturePolicyKind.scroll
-      guard let scrollContext = synthesizedCoordinateContext(policy: synthesizedGesturePolicy(scrollPolicyKind)) else {
+      guard let scrollContext = synthesizedCoordinateContext(
+        app: activeApp,
+        policy: synthesizedGesturePolicy(scrollPolicyKind)
+      ) else {
         return Response(
           ok: false,
           error: ErrorPayload(message: "scroll could not resolve a usable interaction frame")
@@ -1439,7 +1489,10 @@ extension RunnerTests {
     var fallback: GestureFallback?
     if synthesized {
       let durationMs = min(max(durationMs ?? 250, 16), 10000)
-      let context = synthesizedCoordinateContext(policy: synthesizedGesturePolicy(synthesizedPolicyKind))
+      let context = synthesizedCoordinateContext(
+        app: activeApp,
+        policy: synthesizedGesturePolicy(synthesizedPolicyKind)
+      )
       let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
         synthesizedDragAt(
           app: activeApp,
@@ -1495,7 +1548,7 @@ extension RunnerTests {
   ) -> Response? {
 #if os(iOS)
     let policy = synthesizedGesturePolicy(policyKind)
-    let context = context ?? synthesizedCoordinateContext(policy: policy)
+    let context = context ?? synthesizedCoordinateContext(app: activeApp, policy: policy)
     guard let plan = axFreeSynthesizedDragPlan(
       app: activeApp,
       x: x,

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -335,168 +335,6 @@ extension RunnerTests {
       && point.y <= frame.maxY + tolerance
   }
 
-  func isKeyboardVisible(app: XCUIApplication) -> Bool {
-    return visibleKeyboardFrame(app: app) != nil
-  }
-
-  func dismissKeyboard(app: XCUIApplication) -> (wasVisible: Bool, dismissed: Bool, visible: Bool) {
-    let wasVisible = isKeyboardVisible(app: app)
-    guard wasVisible else {
-      return (wasVisible: false, dismissed: false, visible: false)
-    }
-
-#if os(tvOS)
-    _ = pressTvRemote(.menu)
-    sleepFor(0.2)
-    let visible = isKeyboardVisible(app: app)
-    return (wasVisible: true, dismissed: !visible, visible: visible)
-#else
-    if tapKeyboardDismissControl(app: app) {
-      sleepFor(0.2)
-      let visible = isKeyboardVisible(app: app)
-      return (wasVisible: true, dismissed: !visible, visible: visible)
-    }
-
-    return (wasVisible: true, dismissed: false, visible: isKeyboardVisible(app: app))
-#endif
-  }
-
-  func pressKeyboardReturn(app: XCUIApplication) -> (wasVisible: Bool, pressed: Bool, visible: Bool) {
-#if os(tvOS)
-    return (wasVisible: false, pressed: pressTvRemote(.select), visible: false)
-#elseif os(iOS)
-    let wasVisible = isKeyboardVisible(app: app)
-    if tapKeyboardReturnControl(app: app) {
-      sleepFor(0.2)
-      return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app))
-    }
-
-    var typed = false
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      app.typeText(XCUIKeyboardKey.return.rawValue)
-      typed = true
-    })
-    if let exceptionMessage {
-      NSLog(
-        "AGENT_DEVICE_RUNNER_KEYBOARD_RETURN_IGNORED_EXCEPTION=%@",
-        exceptionMessage
-      )
-      if let singleTarget = singleTextEntryElement(app: app) {
-        return pressKeyboardReturn(on: singleTarget, app: app, wasVisible: wasVisible)
-      }
-      return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app))
-    }
-    sleepFor(0.2)
-    return (wasVisible: wasVisible, pressed: typed, visible: isKeyboardVisible(app: app))
-#else
-    return (wasVisible: false, pressed: false, visible: false)
-#endif
-  }
-
-  private func pressKeyboardReturn(
-    on element: XCUIElement,
-    app: XCUIApplication,
-    wasVisible: Bool
-  ) -> (wasVisible: Bool, pressed: Bool, visible: Bool) {
-#if os(iOS)
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      element.tap()
-      element.typeText(XCUIKeyboardKey.return.rawValue)
-    })
-    if let exceptionMessage {
-      NSLog(
-        "AGENT_DEVICE_RUNNER_KEYBOARD_RETURN_TARGET_IGNORED_EXCEPTION=%@",
-        exceptionMessage
-      )
-      return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app))
-    }
-    sleepFor(0.2)
-    return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app))
-#else
-    return (wasVisible: wasVisible, pressed: false, visible: false)
-#endif
-  }
-
-  private func singleTextEntryElement(app: XCUIApplication) -> XCUIElement? {
-#if os(iOS)
-    let matches = safely("KEYBOARD_RETURN_TEXT_ENTRY_QUERY", []) {
-      app.descendants(matching: .any).allElementsBoundByIndex.filter { element in
-        guard element.exists else { return false }
-        switch element.elementType {
-        case .textField, .secureTextField, .searchField, .textView:
-          return true
-        default:
-          return false
-        }
-      }
-    }
-    return matches.count == 1 ? matches[0] : nil
-#else
-    return nil
-#endif
-  }
-
-  private func tapKeyboardDismissControl(app: XCUIApplication) -> Bool {
-#if os(tvOS)
-    return false
-#else
-    guard let keyboardFrame = visibleKeyboardFrame(app: app) else {
-      return false
-    }
-    for label in ["Hide keyboard", "Dismiss keyboard", "Done"] {
-      let candidates = [
-        app.keyboards.buttons[label],
-        app.keyboards.keys[label],
-        app.keyboards.toolbars.buttons[label],
-      ]
-      if let hittable = candidates.first(where: { $0.exists && $0.isHittable }) {
-        hittable.tap()
-        return true
-      }
-
-      let toolbarButtonPredicate = NSPredicate(
-        format: "label == %@ OR identifier == %@",
-        label,
-        label
-      )
-      let toolbarButtons = app.descendants(matching: .button)
-        .matching(toolbarButtonPredicate)
-        .allElementsBoundByIndex
-      if let hittable = toolbarButtons.first(where: {
-        $0.exists && $0.isHittable && isKeyboardAccessoryControl($0, keyboardFrame: keyboardFrame)
-      }) {
-        hittable.tap()
-        return true
-      }
-    }
-    return false
-#endif
-  }
-
-  private func tapKeyboardReturnControl(app: XCUIApplication) -> Bool {
-#if os(iOS)
-    for label in ["return", "Return", "Enter", "Go", "Search", "Next", "Done", "Send", "Join"] {
-      let candidates = [
-        app.keyboards.buttons[label],
-        app.keyboards.keys[label],
-      ]
-      if let hittable = candidates.first(where: { $0.exists && $0.isHittable }) {
-        hittable.tap()
-        return true
-      }
-    }
-#endif
-    return false
-  }
-
-  private func isKeyboardAccessoryControl(_ element: XCUIElement, keyboardFrame: CGRect) -> Bool {
-    let frame = element.frame
-    guard !frame.isEmpty && !keyboardFrame.isEmpty else {
-      return false
-    }
-    return frame.intersects(keyboardFrame) || abs(frame.maxY - keyboardFrame.minY) <= 80
-  }
-
   private func readableText(for element: XCUIElement) -> String? {
     let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
     let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -779,7 +617,10 @@ extension RunnerTests {
       )
     }
     let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
-    guard let context = context ?? synthesizedCoordinateContext(policy: synthesizedGesturePolicy(.synthesizedDrag)) else {
+    guard let context = context ?? synthesizedCoordinateContext(
+      app: app,
+      policy: synthesizedGesturePolicy(.synthesizedDrag)
+    ) else {
       return .unsupported(
         message: "synthesized coordinate drag could not resolve a finite screen frame",
         hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
@@ -842,7 +683,10 @@ extension RunnerTests {
       )
     }
     let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
-    guard let context = context ?? synthesizedCoordinateContext(policy: synthesizedGesturePolicy(.coordinateTap)) else {
+    guard let context = context ?? synthesizedCoordinateContext(
+      app: app,
+      policy: synthesizedGesturePolicy(.coordinateTap)
+    ) else {
       return .unsupported(
         message: "synthesized coordinate tap could not resolve a finite screen frame",
         hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
@@ -1005,20 +849,6 @@ extension RunnerTests {
 #endif
   }
 
-  private func visibleKeyboardFrame(app: XCUIApplication) -> CGRect? {
-#if os(iOS)
-    return safely("KEYBOARD_FRAME") {
-      let keyboard = app.keyboards.firstMatch
-      guard keyboard.exists else { return nil }
-      let keyboardFrame = keyboard.frame
-      guard !keyboardFrame.isEmpty else { return nil }
-      return keyboardFrame
-    }
-#else
-    return nil
-#endif
-  }
-
   func axFreeSynthesizedDragPlan(
     app: XCUIApplication,
     x: Double,
@@ -1028,7 +858,10 @@ extension RunnerTests {
     context: SynthesizedCoordinateContext? = nil
   ) -> SynthesizedDragPlan? {
 #if os(iOS)
-    let context = context ?? synthesizedCoordinateContext(policy: synthesizedGesturePolicy(.synthesizedDrag))
+    let context = context ?? synthesizedCoordinateContext(
+      app: app,
+      policy: synthesizedGesturePolicy(.synthesizedDrag)
+    )
     guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite,
       let context
     else {
@@ -1068,11 +901,18 @@ extension RunnerTests {
     )
   }
 
-  func synthesizedCoordinateContext(policy: SynthesizedGesturePolicy) -> SynthesizedCoordinateContext? {
+  func synthesizedCoordinateContext(
+    app: XCUIApplication,
+    policy: SynthesizedGesturePolicy
+  ) -> SynthesizedCoordinateContext? {
 #if os(iOS)
     let health = runnerAccessibilityHealth
-    guard let referenceFrame = synthesizedScreenshotReferenceFrame(
-      screenshotSize: { XCUIScreen.main.screenshot().image.size }
+    let orientation = Int(
+      RunnerSynthesizedGesture.interfaceOrientation(forApplication: app)
+    )
+    guard let referenceFrame = orientedSynthesizedScreenshotReferenceFrame(
+      screenshotSize: XCUIScreen.main.screenshot().image.size,
+      interfaceOrientation: orientation
     ) else {
       return nil
     }
@@ -1087,15 +927,35 @@ extension RunnerTests {
 #endif
   }
 
-  func synthesizedScreenshotReferenceFrame(screenshotSize: () -> CGSize) -> CGRect? {
-    let screenshotSize = screenshotSize()
+  func orientedSynthesizedScreenshotReferenceFrame(
+    screenshotSize: CGSize,
+    interfaceOrientation: Int
+  ) -> CGRect? {
+    // Physical iOS screenshots can retain portrait dimensions after the interface rotates,
+    // while accessibility frames remain in the logical landscape coordinate space.
     guard screenshotSize.width.isFinite, screenshotSize.height.isFinite,
       screenshotSize.width > 0,
       screenshotSize.height > 0
     else {
       return nil
     }
-    return CGRect(x: 0, y: 0, width: screenshotSize.width, height: screenshotSize.height)
+    let isLandscape = interfaceOrientation == RunnerInterfaceOrientation.landscapeLeft
+      || interfaceOrientation == RunnerInterfaceOrientation.landscapeRight
+    let isPortrait = interfaceOrientation == RunnerInterfaceOrientation.portrait
+      || interfaceOrientation == RunnerInterfaceOrientation.portraitUpsideDown
+    let width: CGFloat
+    let height: CGFloat
+    if isLandscape {
+      width = max(screenshotSize.width, screenshotSize.height)
+      height = min(screenshotSize.width, screenshotSize.height)
+    } else if isPortrait {
+      width = min(screenshotSize.width, screenshotSize.height)
+      height = max(screenshotSize.width, screenshotSize.height)
+    } else {
+      width = screenshotSize.width
+      height = screenshotSize.height
+    }
+    return CGRect(x: 0, y: 0, width: width, height: height)
   }
 
   func synthesizedFrameAvoidingKeyboardWhenAllowed(

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift

@@ -0,0 +1,257 @@
+import XCTest
+
+private enum KeyboardDismissObservationTiming {
+  static let timeout: TimeInterval = 2
+  // #1542: dismissing the keyboard can trigger the host app's own content-offset
+  // adjustment (e.g. a ScrollView correcting the inset it grew to keep a focused
+  // field above the keyboard). That adjustment is a separate, unsynchronized
+  // animation the keyboard's own `waitForNonExistence` above knows nothing about:
+  // the keyboard AX element can vanish well before the app settles. The very next
+  // command is frequently a synthesized, AX-free drag (scroll/gesture — kept
+  // AX-free so it still works under #1105-family AX degradation), which has no
+  // XCTest quiescence wait of its own, so it can land mid-animation and net to
+  // zero. These bounds cap the settle wait this trades in.
+  // A spring-driven content-offset correction can pass through a near-zero-
+  // velocity inflection (the top of an overshoot) that two adjacent samples
+  // alone cannot distinguish from true rest. Requiring 3 consecutive matching
+  // samples demands ~2 full sample intervals of actual stillness before
+  // stopping early, so a momentary pause mid-animation cannot look settled.
+  static let settleTimeout: TimeInterval = 2.0
+  static let settleSampleInterval: TimeInterval = 0.15
+  static let settleRequiredConsecutiveMatches: Int = 3
+}
+
+extension RunnerTests {
+  func isKeyboardVisible(app: XCUIApplication) -> Bool {
+    return visibleKeyboardFrame(app: app) != nil
+  }
+
+  func dismissKeyboard(app: XCUIApplication) -> (wasVisible: Bool, dismissed: Bool, visible: Bool) {
+    let keyboard = app.keyboards.firstMatch
+    let wasVisible = isKeyboardVisible(app: app)
+    guard wasVisible else {
+      return (wasVisible: false, dismissed: false, visible: false)
+    }
+
+#if os(tvOS)
+    _ = pressTvRemote(.menu)
+    sleepFor(0.2)
+    let visible = isKeyboardVisible(app: app)
+    return (wasVisible: true, dismissed: !visible, visible: visible)
+#else
+    if tapKeyboardDismissControl(app: app) {
+      _ = keyboard.waitForNonExistence(timeout: KeyboardDismissObservationTiming.timeout)
+      waitForScreenshotStability(
+        timeout: KeyboardDismissObservationTiming.settleTimeout,
+        sampleInterval: KeyboardDismissObservationTiming.settleSampleInterval,
+        requiredConsecutiveMatches: KeyboardDismissObservationTiming.settleRequiredConsecutiveMatches
+      )
+      let visible = isKeyboardVisible(app: app)
+      return (wasVisible: true, dismissed: !visible, visible: visible)
+    }
+
+    return (wasVisible: true, dismissed: false, visible: isKeyboardVisible(app: app))
+#endif
+  }
+
+  // AX-free on purpose (screenshot bytes, not the accessibility tree) so it holds
+  // under the same AX degradation the synthesized gesture lane is built to survive.
+  // Bounded and self-terminating: returns as soon as `requiredConsecutiveMatches`
+  // consecutive samples match, so an already-settled screen (the common case)
+  // pays close to nothing. The stopping decision itself
+  // (`runnerScreenshotStabilitySettled`) is a pure function of the samples taken
+  // so far, so it is unit-testable without a real screenshot pipeline; this loop
+  // is the thin, untestable I/O shell around it.
+  private func waitForScreenshotStability(
+    timeout: TimeInterval,
+    sampleInterval: TimeInterval,
+    requiredConsecutiveMatches: Int
+  ) {
+    let deadline = Date().addingTimeInterval(timeout)
+    var samples: [Data?] = [screenshotFingerprintForStabilityCheck()]
+    while Date() < deadline {
+      sleepFor(sampleInterval)
+      samples.append(screenshotFingerprintForStabilityCheck())
+      if runnerScreenshotStabilitySettled(samples, requiredConsecutiveMatches: requiredConsecutiveMatches) {
+        return
+      }
+    }
+  }
+
+  private func screenshotFingerprintForStabilityCheck() -> Data? {
+    guard let image = captureRunnerFrame() else { return nil }
+    return runnerPngData(for: image)
+  }
+
+  func pressKeyboardReturn(app: XCUIApplication) -> (wasVisible: Bool, pressed: Bool, visible: Bool) {
+#if os(tvOS)
+    return (wasVisible: false, pressed: pressTvRemote(.select), visible: false)
+#elseif os(iOS)
+    let wasVisible = isKeyboardVisible(app: app)
+    if tapKeyboardReturnControl(app: app) {
+      sleepFor(0.2)
+      return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app))
+    }
+
+    var typed = false
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      app.typeText(XCUIKeyboardKey.return.rawValue)
+      typed = true
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_KEYBOARD_RETURN_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      if let singleTarget = singleTextEntryElement(app: app) {
+        return pressKeyboardReturn(on: singleTarget, app: app, wasVisible: wasVisible)
+      }
+      return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app))
+    }
+    sleepFor(0.2)
+    return (wasVisible: wasVisible, pressed: typed, visible: isKeyboardVisible(app: app))
+#else
+    return (wasVisible: false, pressed: false, visible: false)
+#endif
+  }
+
+  func visibleKeyboardFrame(app: XCUIApplication) -> CGRect? {
+#if os(iOS)
+    return safely("KEYBOARD_FRAME") {
+      let keyboard = app.keyboards.firstMatch
+      guard keyboard.exists else { return nil }
+      let keyboardFrame = keyboard.frame
+      guard !keyboardFrame.isEmpty else { return nil }
+      return keyboardFrame
+    }
+#else
+    return nil
+#endif
+  }
+
+  private func pressKeyboardReturn(
+    on element: XCUIElement,
+    app: XCUIApplication,
+    wasVisible: Bool
+  ) -> (wasVisible: Bool, pressed: Bool, visible: Bool) {
+#if os(iOS)
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      element.tap()
+      element.typeText(XCUIKeyboardKey.return.rawValue)
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_KEYBOARD_RETURN_TARGET_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return (wasVisible: wasVisible, pressed: false, visible: isKeyboardVisible(app: app))
+    }
+    sleepFor(0.2)
+    return (wasVisible: wasVisible, pressed: true, visible: isKeyboardVisible(app: app))
+#else
+    return (wasVisible: wasVisible, pressed: false, visible: false)
+#endif
+  }
+
+  private func singleTextEntryElement(app: XCUIApplication) -> XCUIElement? {
+#if os(iOS)
+    let matches = safely("KEYBOARD_RETURN_TEXT_ENTRY_QUERY", []) {
+      app.descendants(matching: .any).allElementsBoundByIndex.filter { element in
+        guard element.exists else { return false }
+        switch element.elementType {
+        case .textField, .secureTextField, .searchField, .textView:
+          return true
+        default:
+          return false
+        }
+      }
+    }
+    return matches.count == 1 ? matches[0] : nil
+#else
+    return nil
+#endif
+  }
+
+  private func tapKeyboardDismissControl(app: XCUIApplication) -> Bool {
+#if os(tvOS)
+    return false
+#else
+    guard let keyboardFrame = visibleKeyboardFrame(app: app) else {
+      return false
+    }
+    for label in ["Hide keyboard", "Dismiss keyboard", "Done"] {
+      let candidates = [
+        app.keyboards.buttons[label],
+        app.keyboards.keys[label],
+        app.keyboards.toolbars.buttons[label],
+      ]
+      if let hittable = candidates.first(where: { $0.exists && $0.isHittable }) {
+        hittable.tap()
+        return true
+      }
+
+      let toolbarButtonPredicate = NSPredicate(
+        format: "label == %@ OR identifier == %@",
+        label,
+        label
+      )
+      let toolbarButtons = app.descendants(matching: .button)
+        .matching(toolbarButtonPredicate)
+        .allElementsBoundByIndex
+      if let hittable = toolbarButtons.first(where: {
+        $0.exists && $0.isHittable && isKeyboardAccessoryControl($0, keyboardFrame: keyboardFrame)
+      }) {
+        hittable.tap()
+        return true
+      }
+    }
+    return false
+#endif
+  }
+
+  private func tapKeyboardReturnControl(app: XCUIApplication) -> Bool {
+#if os(iOS)
+    for label in ["return", "Return", "Enter", "Go", "Search", "Next", "Done", "Send", "Join"] {
+      let candidates = [
+        app.keyboards.buttons[label],
+        app.keyboards.keys[label],
+      ]
+      if let hittable = candidates.first(where: { $0.exists && $0.isHittable }) {
+        hittable.tap()
+        return true
+      }
+    }
+#endif
+    return false
+  }
+
+  private func isKeyboardAccessoryControl(_ element: XCUIElement, keyboardFrame: CGRect) -> Bool {
+    let frame = element.frame
+    guard !frame.isEmpty && !keyboardFrame.isEmpty else {
+      return false
+    }
+    return frame.intersects(keyboardFrame) || abs(frame.maxY - keyboardFrame.minY) <= 80
+  }
+}
+
+/// True once the `requiredConsecutiveMatches` most recent samples are all present
+/// and byte-identical — i.e. the screen held still across that whole run of
+/// polls, not just the last two. A spring-driven content-offset correction can
+/// pass through a near-zero-velocity inflection that two adjacent samples alone
+/// cannot distinguish from true rest; requiring a longer run of matches demands
+/// real elapsed stillness before stopping early. `nil` entries (a screenshot
+/// capture that failed) never count toward a match, so a flaky capture cannot
+/// look like stability; the caller's bounded loop still terminates on its
+/// deadline regardless.
+func runnerScreenshotStabilitySettled(
+  _ samples: [Data?],
+  requiredConsecutiveMatches: Int
+) -> Bool {
+  guard requiredConsecutiveMatches >= 2, samples.count >= requiredConsecutiveMatches else {
+    return false
+  }
+  let window = samples.suffix(requiredConsecutiveMatches)
+  guard let first = window.first, let firstData = first else { return false }
+  return window.allSatisfy { $0 == firstData }
+}
+