agent-device 0.16.7 → 0.16.9

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -30,48 +30,6 @@ extension RunnerTests {
     let usedNonHittableFallback: Bool
   }
 
-  enum TextTypingRepairMode {
-    case none
-    case append
-    case replacement
-  }
-
-  enum TextEntryTiming {
-    static let focusTimeout: TimeInterval = 0.4
-    static let repairReadinessTimeout: TimeInterval = 1.0
-    static let readinessTimeout: TimeInterval = 2.0
-    static let hardwareKeyboardFallbackTimeout: TimeInterval = 0.35
-    static let pollInterval: TimeInterval = 0.02
-    static let warmupValueTimeout: TimeInterval = 0.4
-    static let verificationStabilityWindow: TimeInterval = 0.2
-  }
-
-  struct TextEntryResult {
-    let verified: Bool?
-    let repaired: Bool
-    let expectedText: String?
-    let observedText: String?
-  }
-
-  struct TextEntryTarget {
-    let element: XCUIElement?
-    let refreshPoint: CGPoint?
-    let prefersFocusedElement: Bool
-
-    func withElement(_ nextElement: XCUIElement?) -> TextEntryTarget {
-      guard let nextElement else {
-        return self
-      }
-      let frame = nextElement.frame
-      let point = frame.isEmpty ? refreshPoint : CGPoint(x: frame.midX, y: frame.midY)
-      return TextEntryTarget(
-        element: nextElement,
-        refreshPoint: point,
-        prefersFocusedElement: prefersFocusedElement
-      )
-    }
-  }
-
   // MARK: - Navigation Gestures
 
   func tapInAppBackControl(app: XCUIApplication) -> Bool {
@@ -283,6 +241,13 @@ extension RunnerTests {
 
   func readTextAt(app: XCUIApplication, x: Double, y: Double) -> String? {
     let point = CGPoint(x: x, y: y)
+    let textInputCandidates = textInputCandidatesAt(app: app, point: point)
+    for element in textInputCandidates where prefersExpandedTextRead(element) {
+      if let text = readableText(for: element) {
+        return text
+      }
+    }
+
     let candidates = app.descendants(matching: .any).allElementsBoundByIndex
       .filter { element in
         element.exists && !element.frame.isEmpty && element.frame.contains(point)
@@ -315,30 +280,29 @@ extension RunnerTests {
     return nil
   }
 
-  func clearTextInput(_ element: XCUIElement) {
-#if !os(tvOS)
-    moveCaretToEnd(element: element)
-#endif
-    let count = estimatedDeleteCount(for: element)
-    let deletes = String(repeating: XCUIKeyboardKey.delete.rawValue, count: count)
-    element.typeText(deletes)
+  func textInputAt(app: XCUIApplication, x: Double, y: Double) -> XCUIElement? {
+    return textInputCandidatesAt(app: app, point: CGPoint(x: x, y: y)).first
   }
 
-  func textInputAt(app: XCUIApplication, x: Double, y: Double) -> XCUIElement? {
-    let point = CGPoint(x: x, y: y)
-    var matched: XCUIElement?
+  private func textInputCandidatesAt(app: XCUIApplication, point: CGPoint) -> [XCUIElement] {
+    var candidates: [XCUIElement] = []
     let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      // Query the text-input element types directly instead of enumerating the entire tree
+      // (app.descendants(.any).allElementsBoundByIndex snapshots every element and is ~10x
+      // slower — it dominated fill latency because resolveTextEntryElement re-runs this on
+      // each verify/repair poll once the focused field reference goes stale).
       // Prefer the smallest matching field so nested editable controls win over large containers.
-      let candidates = app.descendants(matching: .any).allElementsBoundByIndex
+      candidates = [
+        app.textFields,
+        app.secureTextFields,
+        app.searchFields,
+        app.textViews,
+      ]
+        .flatMap { $0.allElementsBoundByIndex }
         .filter { element in
           guard element.exists else { return false }
-          switch element.elementType {
-          case .textField, .secureTextField, .searchField, .textView:
-            let frame = element.frame
-            return !frame.isEmpty && frameContainsPoint(frame, point, tolerance: 2)
-          default:
-            return false
-          }
+          let frame = element.frame
+          return !frame.isEmpty && frameContainsPoint(frame, point, tolerance: 2)
         }
         .sorted { left, right in
           let leftArea = max(1, left.frame.width * left.frame.height)
@@ -354,16 +318,15 @@ extension RunnerTests {
           }
           return left.elementType.rawValue < right.elementType.rawValue
         }
-      matched = candidates.first
     })
     if let exceptionMessage {
       NSLog(
         "AGENT_DEVICE_RUNNER_TEXT_INPUT_AT_POINT_IGNORED_EXCEPTION=%@",
         exceptionMessage
       )
-      return nil
+      return []
     }
-    return matched
+    return candidates
   }
 
   private func frameContainsPoint(_ frame: CGRect, _ point: CGPoint, tolerance: CGFloat) -> Bool {
@@ -373,586 +336,10 @@ extension RunnerTests {
       && point.y <= frame.maxY + tolerance
   }
 
-  func focusedTextInput(app: XCUIApplication) -> XCUIElement? {
-#if os(iOS)
-    // iOS focus predicates can return stale or misleading text-input matches
-    // under XCUITest, so text entry readiness is driven by tap/keyboard state.
-    return nil
-#else
-    var focused: XCUIElement?
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      let candidates = app
-        .descendants(matching: .any)
-        .matching(NSPredicate(format: "hasKeyboardFocus == 1"))
-        .allElementsBoundByIndex
-      for candidate in candidates where candidate.exists {
-        switch candidate.elementType {
-        case .textField, .secureTextField, .searchField, .textView:
-          focused = candidate
-          return
-        default:
-          continue
-        }
-      }
-    })
-    if let exceptionMessage {
-      NSLog(
-        "AGENT_DEVICE_RUNNER_FOCUSED_INPUT_QUERY_IGNORED_EXCEPTION=%@",
-        exceptionMessage
-      )
-      return nil
-    }
-    return focused
-#endif
-  }
-
-  func stabilizeTextInputBeforeTyping(app: XCUIApplication, target: XCUIElement?) -> XCUIElement? {
-#if os(tvOS)
-    return target
-#else
-    let latest = target
-    let deadline = Date().addingTimeInterval(TextEntryTiming.focusTimeout)
-    while Date() < deadline {
-      if let focused = focusedTextInput(app: app) {
-        return focused
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    }
-    return latest
-#endif
-  }
-
-  func focusTextInputForTextEntry(app: XCUIApplication, x: Double?, y: Double?) -> TextEntryTarget {
-    guard let x, let y else {
-      let focused = waitForTextEntryReadiness(
-        app: app,
-        target: TextEntryTarget(
-          element: focusedTextInput(app: app),
-          refreshPoint: nil,
-          prefersFocusedElement: true
-        )
-      )
-      return TextEntryTarget(element: focused, refreshPoint: nil, prefersFocusedElement: true)
-    }
-
-    let target = textInputAt(app: app, x: x, y: y)
-    let requestedPoint = CGPoint(x: x, y: y)
-    if let target {
-      let frame = target.frame
-      if !frame.isEmpty {
-        _ = tapAt(app: app, x: frame.midX, y: frame.midY)
-      } else {
-        _ = tapAt(app: app, x: x, y: y)
-      }
-    } else {
-      _ = tapAt(app: app, x: x, y: y)
-    }
-    let stabilized = stabilizeTextInputBeforeTyping(app: app, target: target)
-    let element = waitForTextEntryReadiness(
-      app: app,
-      target: TextEntryTarget(
-        element: stabilized ?? target,
-        refreshPoint: requestedPoint,
-        prefersFocusedElement: false
-      )
-    ) ?? stabilized ?? target
-    return TextEntryTarget(
-      element: element,
-      refreshPoint: textEntryRefreshPoint(for: element) ?? requestedPoint,
-      prefersFocusedElement: false
-    )
-  }
-
-  func focusTextInputForTextEntry(app: XCUIApplication, element: XCUIElement) -> TextEntryTarget {
-    let point = textEntryRefreshPoint(for: element)
-    if let point {
-      _ = tapAt(app: app, x: point.x, y: point.y)
-    }
-    let stabilized = stabilizeTextInputBeforeTyping(app: app, target: element)
-    let resolved = waitForTextEntryReadiness(
-      app: app,
-      target: TextEntryTarget(
-        element: stabilized ?? element,
-        refreshPoint: point,
-        prefersFocusedElement: false
-      )
-    ) ?? stabilized ?? element
-    return TextEntryTarget(
-      element: resolved,
-      refreshPoint: textEntryRefreshPoint(for: resolved) ?? point,
-      prefersFocusedElement: false
-    )
-  }
-
-  func isTextEntryElement(_ element: XCUIElement) -> Bool {
-    switch element.elementType {
-    case .textField, .secureTextField, .searchField, .textView:
-      return true
-    default:
-      return false
-    }
-  }
-
-  func resolveTextEntryMode(_ command: Command) -> TextTypingRepairMode {
-    switch command.textEntryMode {
-    case "append":
-      return .append
-    case "replace":
-      return .replacement
-    default:
-      return command.clearFirst == true ? .replacement : .none
-    }
-  }
-
-  func typeTextReliably(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    text: String,
-    delaySeconds: Double,
-    repairMode: TextTypingRepairMode = .none
-  ) -> TextEntryResult {
-    guard !text.isEmpty else {
-      return TextEntryResult(verified: true, repaired: false, expectedText: "", observedText: "")
-    }
-    var activeTarget = target
-    let initialTarget = resolveTextEntryElement(app: app, target: activeTarget)
-    activeTarget = activeTarget.withElement(initialTarget)
-    let currentText = editableTextValue(for: initialTarget, treatingPlaceholderAsEmpty: true)
-    let initialText = repairMode == .append ? currentText : nil
-    let expectedText = expectedTextEntryValue(typedText: text, mode: repairMode, initialText: initialText)
-
-    if repairMode == .replacement {
-      guard let replacementTarget = initialTarget else {
-        return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
-      }
-      if currentText == nil || currentText?.isEmpty == false {
-        clearTextInput(replacementTarget)
-        activeTarget = activeTarget.withElement(replacementTarget)
-      }
-    }
-
-    func typeIntoCurrentTarget(_ value: String) -> XCUIElement? {
-      if let currentTarget = resolveTextEntryElement(app: app, target: activeTarget) {
-        app.typeText(value)
-        return currentTarget
-      } else {
-        app.typeText(value)
-        return resolveTextEntryElement(app: app, target: activeTarget)
-      }
-    }
-
-    func waitForWarmupValue(_ expectedValue: String?, target: TextEntryTarget) {
-      guard let expectedValue else {
-        sleepFor(TextEntryTiming.pollInterval)
-        return
-      }
-      let deadline = Date().addingTimeInterval(TextEntryTiming.warmupValueTimeout)
-      while Date() < deadline {
-        if editableTextValue(for: resolveTextEntryElement(app: app, target: target)) == expectedValue {
-          return
-        }
-        sleepFor(TextEntryTiming.pollInterval)
-      }
-    }
-
-    let characters = Array(text)
-    if delaySeconds > 0 && characters.count > 1 {
-      var typedTarget: XCUIElement?
-      for (index, character) in characters.enumerated() {
-        typedTarget = typeIntoCurrentTarget(String(character)) ?? typedTarget
-        if index + 1 < characters.count {
-          sleepFor(delaySeconds)
-        }
-      }
-      if repairMode == .none {
-        return TextEntryResult(verified: nil, repaired: false, expectedText: nil, observedText: nil)
-      }
-      let repairResult = repairTextEntryIfNeeded(
-        app: app,
-        target: activeTarget.withElement(typedTarget),
-        expectedText: expectedText,
-        repairMode: repairMode
-      )
-      return verifyTextEntry(
-        app: app,
-        target: activeTarget.withElement(typedTarget),
-        expectedText: expectedText,
-        repaired: repairResult.repaired
-      )
-    }
-
-    let typedTarget: XCUIElement?
-    if repairMode != .none && characters.count > 1 {
-      let firstCharacter = String(characters[0])
-      var firstTypedTarget = typeIntoCurrentTarget(firstCharacter)
-      activeTarget = activeTarget.withElement(firstTypedTarget)
-      let warmupExpectedText = expectedTextEntryValue(
-        typedText: firstCharacter,
-        mode: repairMode,
-        initialText: initialText
-      )
-      waitForWarmupValue(warmupExpectedText, target: activeTarget)
-      let remainingText = String(characters.dropFirst())
-      firstTypedTarget = typeIntoCurrentTarget(remainingText) ?? firstTypedTarget
-      typedTarget = firstTypedTarget
-    } else {
-      typedTarget = typeIntoCurrentTarget(text)
-    }
-    if repairMode == .none {
-      return TextEntryResult(verified: nil, repaired: false, expectedText: nil, observedText: nil)
-    }
-    let repairResult = repairTextEntryIfNeeded(
-      app: app,
-      target: activeTarget.withElement(typedTarget),
-      expectedText: expectedText,
-      repairMode: repairMode
-    )
-    return verifyTextEntry(
-      app: app,
-      target: activeTarget.withElement(typedTarget),
-      expectedText: expectedText,
-      repaired: repairResult.repaired
-    )
-  }
-
-  private func repairTextEntryIfNeeded(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    expectedText: String?,
-    repairMode: TextTypingRepairMode
-  ) -> TextEntryResult {
-#if os(iOS)
-    guard let targetElement = resolveTextEntryElement(app: app, target: target) else {
-      return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
-    }
-    guard let expectedText else {
-      let observedText = editableTextValue(for: targetElement)
-      return TextEntryResult(verified: nil, repaired: false, expectedText: nil, observedText: observedText)
-    }
-    guard shouldRepairTextEntry(
-      app: app,
-      target: target,
-      expectedText: expectedText,
-      repairMode: repairMode
-    ) else {
-      return verifyTextEntry(app: app, target: target, expectedText: expectedText, repaired: false)
-    }
-
-    guard let repairTarget = resolveTextEntryElement(app: app, target: target) else {
-      return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
-    }
-    let observedText = editableTextValue(for: repairTarget) ?? ""
-    NSLog(
-      "AGENT_DEVICE_RUNNER_REPAIR_TEXT_ENTRY expectedLength=%d observedLength=%d",
-      expectedText.count,
-      observedText.count
-    )
-    clearTextInput(repairTarget)
-    app.typeText(expectedText)
-    return verifyTextEntry(app: app, target: target, expectedText: expectedText, repaired: true)
-#else
-    return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
-#endif
-  }
-
-  private func verifyTextEntry(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    expectedText: String?,
-    repaired: Bool
-  ) -> TextEntryResult {
-    let targetElement = resolveTextEntryElement(app: app, target: target)
-    guard let expectedText else {
-      return TextEntryResult(
-        verified: nil,
-        repaired: repaired,
-        expectedText: nil,
-        observedText: editableTextValue(for: targetElement)
-      )
-    }
-    guard let observedText = editableTextValue(for: targetElement) else {
-      return TextEntryResult(verified: nil, repaired: repaired, expectedText: expectedText, observedText: nil)
-    }
-    guard textEntryValueMatchesExpected(targetElement, observedText: observedText, expectedText: expectedText) else {
-      return TextEntryResult(
-        verified: false,
-        repaired: repaired,
-        expectedText: expectedText,
-        observedText: observedText
-      )
-    }
-    let stableDeadline = Date().addingTimeInterval(TextEntryTiming.verificationStabilityWindow)
-    var latestObservedText = observedText
-    while Date() < stableDeadline {
-      sleepFor(TextEntryTiming.pollInterval)
-      guard let nextObservedText = editableTextValue(for: resolveTextEntryElement(app: app, target: target)) else {
-        return TextEntryResult(verified: nil, repaired: repaired, expectedText: expectedText, observedText: nil)
-      }
-      latestObservedText = nextObservedText
-      guard textEntryValueMatchesExpected(
-        resolveTextEntryElement(app: app, target: target),
-        observedText: nextObservedText,
-        expectedText: expectedText
-      ) else {
-        return TextEntryResult(
-          verified: false,
-          repaired: repaired,
-          expectedText: expectedText,
-          observedText: nextObservedText
-        )
-      }
-    }
-    return TextEntryResult(
-      verified: true,
-      repaired: repaired,
-      expectedText: expectedText,
-      observedText: latestObservedText
-    )
-  }
-
-  private func textEntryValueMatchesExpected(
-    _ element: XCUIElement?,
-    observedText: String,
-    expectedText: String
-  ) -> Bool {
-    if observedText == expectedText {
-      return true
-    }
-    guard hasTextEntrySubmitSuffix(expectedText), element?.elementType != .textView else {
-      return false
-    }
-    var submittedText = expectedText
-    while hasTextEntrySubmitSuffix(submittedText) {
-      submittedText.removeLast()
-    }
-    return observedText == submittedText
-  }
-
-  private func hasTextEntrySubmitSuffix(_ text: String) -> Bool {
-    text.hasSuffix("\n") || text.hasSuffix("\r")
-  }
-
-  private func expectedTextEntryValue(
-    typedText: String,
-    mode: TextTypingRepairMode,
-    initialText: String?
-  ) -> String? {
-    switch mode {
-    case .none:
-      return nil
-    case .append:
-      guard let initialText else {
-        return nil
-      }
-      return initialText + typedText
-    case .replacement:
-      return typedText
-    }
-  }
-
-  private func shouldRepairTextEntry(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    expectedText: String,
-    repairMode: TextTypingRepairMode
-  ) -> Bool {
-#if os(iOS)
-    var latestObservedText: String?
-    let deadline = Date().addingTimeInterval(TextEntryTiming.verificationStabilityWindow)
-    repeat {
-      guard let observedText = editableTextValue(for: resolveTextEntryElement(app: app, target: target)) else {
-        return false
-      }
-      if textEntryValueMatchesExpected(
-        resolveTextEntryElement(app: app, target: target),
-        observedText: observedText,
-        expectedText: expectedText
-      ) {
-        return false
-      }
-      latestObservedText = observedText
-      if !isRepairableTextEntryMismatch(
-        observedText: observedText,
-        expectedText: expectedText,
-        repairMode: repairMode
-      ) {
-        return false
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    } while Date() < deadline
-
-    guard let latestObservedText else {
-      return false
-    }
-    guard !textEntryValueMatchesExpected(
-      resolveTextEntryElement(app: app, target: target),
-      observedText: latestObservedText,
-      expectedText: expectedText
-    ) else {
-      return false
-    }
-    return isRepairableTextEntryMismatch(
-      observedText: latestObservedText,
-      expectedText: expectedText,
-      repairMode: repairMode
-    )
-#else
-    return false
-#endif
-  }
-
-  private func isRepairableTextEntryMismatch(
-    observedText: String,
-    expectedText: String,
-    repairMode: TextTypingRepairMode
-  ) -> Bool {
-    guard observedText != expectedText else {
-      return false
-    }
-    if repairMode == .replacement {
-      return true
-    }
-    return observedText.isEmpty || isLikelyDroppedCharacterTextEntryMismatch(
-      observedText: observedText,
-      expectedText: expectedText
-    )
-  }
-
-  private func isLikelyDroppedCharacterTextEntryMismatch(observedText: String, expectedText: String) -> Bool {
-    guard observedText.count < expectedText.count else {
-      return false
-    }
-    let missingCharacterCount = expectedText.count - observedText.count
-    guard missingCharacterCount <= max(2, expectedText.count / 4) else {
-      return false
-    }
-    var expectedIndex = expectedText.startIndex
-    for character in observedText {
-      guard let matchIndex = expectedText[expectedIndex...].firstIndex(of: character) else {
-        return false
-      }
-      expectedIndex = expectedText.index(after: matchIndex)
-    }
-    return true
-  }
-
-  private func resolveTextEntryElement(app: XCUIApplication, target: TextEntryTarget) -> XCUIElement? {
-    if target.prefersFocusedElement {
-      if let focused = focusedTextInput(app: app) {
-        return focused
-      }
-      if let element = target.element, element.exists {
-        return element
-      }
-    } else {
-      if let element = target.element, element.exists {
-        return element
-      }
-    }
-    if let refreshPoint = target.refreshPoint,
-       let refreshed = textInputAt(app: app, x: refreshPoint.x, y: refreshPoint.y) {
-      return refreshed
-    }
-    if let focused = focusedTextInput(app: app) {
-      return focused
-    }
-    return nil
-  }
-
-  private func waitForTextEntryReadiness(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    timeout: TimeInterval = TextEntryTiming.readinessTimeout
-  ) -> XCUIElement? {
-#if os(iOS)
-    var latest = resolveTextEntryElement(app: app, target: target)
-    let deadline = Date().addingTimeInterval(timeout)
-    let hardwareKeyboardFallback = Date().addingTimeInterval(
-      min(TextEntryTiming.hardwareKeyboardFallbackTimeout, timeout)
-    )
-    var sawSoftwareKeyboard = false
-    while Date() < deadline {
-      if let focused = focusedTextInput(app: app) {
-        latest = focused
-        if isKeyboardVisible(app: app) {
-          return focused
-        }
-      }
-      sawSoftwareKeyboard = sawSoftwareKeyboard || keyboardElementExists(app: app)
-      if !sawSoftwareKeyboard && Date() >= hardwareKeyboardFallback && latest != nil {
-        return latest
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    }
-    return focusedTextInput(app: app) ?? latest
-#else
-    return resolveTextEntryElement(app: app, target: target)
-#endif
-  }
-
-  func waitForTextEntryReadinessAfterTap(app: XCUIApplication, element: XCUIElement) {
-#if os(iOS)
-    switch element.elementType {
-    case .textField, .secureTextField, .searchField, .textView:
-      if waitForFocusedTextInput(app: app, timeout: TextEntryTiming.readinessTimeout) != nil {
-        return
-      }
-      let frame = element.frame
-      if !frame.isEmpty {
-        _ = tapAt(app: app, x: frame.midX, y: frame.midY)
-        _ = waitForFocusedTextInput(app: app, timeout: TextEntryTiming.readinessTimeout)
-      }
-    default:
-      return
-    }
-#endif
-  }
-
-  private func waitForFocusedTextInput(app: XCUIApplication, timeout: TimeInterval) -> XCUIElement? {
-    let deadline = Date().addingTimeInterval(timeout)
-    while Date() < deadline {
-      if let focused = focusedTextInput(app: app) {
-        return focused
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    }
-    return focusedTextInput(app: app)
-  }
-
-  private func textEntryRefreshPoint(for element: XCUIElement?) -> CGPoint? {
-    guard let element else {
-      return nil
-    }
-    let frame = element.frame
-    guard !frame.isEmpty else {
-      return nil
-    }
-    return CGPoint(x: frame.midX, y: frame.midY)
-  }
-
   func isKeyboardVisible(app: XCUIApplication) -> Bool {
     return visibleKeyboardFrame(app: app) != nil
   }
 
-  private func keyboardElementExists(app: XCUIApplication) -> Bool {
-#if os(iOS)
-    var exists = false
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      exists = app.keyboards.firstMatch.exists
-    })
-    if let exceptionMessage {
-      NSLog(
-        "AGENT_DEVICE_RUNNER_KEYBOARD_EXISTS_IGNORED_EXCEPTION=%@",
-        exceptionMessage
-      )
-      return false
-    }
-    return exists
-#else
-    return false
-#endif
-  }
-
   func dismissKeyboard(app: XCUIApplication) -> (wasVisible: Bool, dismissed: Bool, visible: Bool) {
     let wasVisible = isKeyboardVisible(app: app)
     guard wasVisible else {
@@ -978,6 +365,14 @@ extension RunnerTests {
       return (wasVisible: true, dismissed: !visible, visible: visible)
     }
 
+    if tapKeyboardReturnControl(app: app, allowCoordinateFallback: true) {
+      sleepFor(0.2)
+      let visible = isKeyboardVisible(app: app)
+      if !visible {
+        return (wasVisible: true, dismissed: true, visible: false)
+      }
+    }
+
     return (wasVisible: true, dismissed: false, visible: isKeyboardVisible(app: app))
 #endif
   }
@@ -1098,7 +493,10 @@ extension RunnerTests {
 #endif
   }
 
-  private func tapKeyboardReturnControl(app: XCUIApplication) -> Bool {
+  private func tapKeyboardReturnControl(
+    app: XCUIApplication,
+    allowCoordinateFallback: Bool = false
+  ) -> Bool {
 #if os(iOS)
     for label in ["return", "Return", "Enter", "Go", "Search", "Next", "Done", "Send", "Join"] {
       let candidates = [
@@ -1109,6 +507,21 @@ extension RunnerTests {
         hittable.tap()
         return true
       }
+      if allowCoordinateFallback,
+         let keyboardFrame = visibleKeyboardFrame(app: app),
+         let framed = candidates.first(where: {
+           guard $0.exists else { return false }
+           let frame = $0.frame
+           return !frame.isEmpty && keyboardFrame.contains(CGPoint(x: frame.midX, y: frame.midY))
+         }) {
+        let frame = framed.frame
+        switch tapAt(app: app, x: frame.midX, y: frame.midY) {
+        case .performed:
+          return true
+        case .unsupported:
+          return false
+        }
+      }
     }
 #endif
     return false
@@ -1122,80 +535,6 @@ extension RunnerTests {
     return frame.intersects(keyboardFrame) || abs(frame.maxY - keyboardFrame.minY) <= 80
   }
 
-  private func moveCaretToEnd(element: XCUIElement) {
-#if os(tvOS)
-    return
-#else
-    let frame = element.frame
-    guard !frame.isEmpty else {
-      element.tap()
-      return
-    }
-    let origin = element.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
-    let target = origin.withOffset(
-      CGVector(dx: max(2, frame.width - 4), dy: max(2, frame.height / 2))
-    )
-    target.tap()
-#endif
-  }
-
-  private func estimatedDeleteCount(for element: XCUIElement) -> Int {
-    let valueText = normalizedElementText(element.value)
-    let base = valueText.isEmpty ? 24 : (valueText.count + 8)
-    return max(24, min(120, base))
-  }
-
-  private func normalizedElementText(_ value: Any?) -> String {
-    String(describing: value ?? "")
-      .trimmingCharacters(in: .whitespacesAndNewlines)
-  }
-
-  private func editableTextValue(
-    for element: XCUIElement?,
-    treatingPlaceholderAsEmpty: Bool = false
-  ) -> String? {
-    guard let element else {
-      return nil
-    }
-    switch element.elementType {
-    case .textField, .searchField, .textView:
-      let value = String(describing: element.value ?? "")
-      if treatingPlaceholderAsEmpty && isPlaceholderValue(value, for: element) {
-        return ""
-      }
-      return value
-    case .secureTextField:
-      return nil
-    default:
-      return nil
-    }
-  }
-
-  private func isPlaceholderValue(_ value: String, for element: XCUIElement) -> Bool {
-    let normalizedValue = value.trimmingCharacters(in: .whitespacesAndNewlines)
-    guard !normalizedValue.isEmpty else {
-      return false
-    }
-    let placeholder = element.placeholderValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-    if !placeholder.isEmpty && normalizedValue == placeholder {
-      return true
-    }
-    if isGenericTextInputLabel(normalizedValue) {
-      return true
-    }
-    let normalizedLabel = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-    return normalizedLabel == normalizedValue && isGenericTextInputLabel(normalizedLabel)
-  }
-
-  private func isGenericTextInputLabel(_ value: String) -> Bool {
-    switch value {
-    case "Text input field":
-      return true
-    default:
-      return false
-    }
-  }
-
   private func readableText(for element: XCUIElement) -> String? {
     let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
     let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -1510,11 +849,69 @@ extension RunnerTests {
   }
 
   func pinch(app: XCUIApplication, scale: Double, x: Double?, y: Double?) -> RunnerInteractionOutcome {
-    return performCoordinatePinch(app: app, scale: scale, x: x, y: y)
+#if os(iOS)
+    // A coordinate tap+drag is a single-finger gesture: React Native reads it as a pan
+    // and the pinch scale never changes (#629). Drive the two-finger XCTest synthesis
+    // path (the same one transformGesture uses) with zero translation/rotation so RN's
+    // pinch recognizer actually fires.
+    let frame = interactionRoot(app: app).frame
+    let centerX = x ?? Double(frame.midX)
+    let centerY = y ?? Double(frame.midY)
+    return transformGesture(
+      app: app,
+      x: centerX,
+      y: centerY,
+      dx: 0,
+      dy: 0,
+      scale: scale,
+      degrees: 0,
+      durationMs: 300
+    )
+#elseif os(tvOS)
+    return .unsupported(
+      message: "pinch is not supported on tvOS",
+      hint: "tvOS has no touch input; pinch requires a touchscreen (run on iOS)."
+    )
+#else
+    return .unsupported(
+      message: "pinch is not supported on macOS",
+      hint: "macOS automation has no multi-touch input; pinch requires a touchscreen (run on iOS)."
+    )
+#endif
   }
 
   func rotateGesture(app: XCUIApplication, degrees: Double, x: Double?, y: Double?, velocity: Double) -> RunnerInteractionOutcome {
-    return performCoordinateRotateGesture(app: app, degrees: degrees, x: x, y: y, velocity: velocity)
+#if os(iOS)
+    // Drive the two-finger XCTest synthesis path (the same one pinch/transformGesture use, #634)
+    // with zero translation/scale so React Native's rotation recognizer actually fires. The native
+    // XCUIElement.rotate(withVelocity:) injects a single synthetic rotation that RN's gesture
+    // handler does not read reliably — the same class of problem #629/#634 fixed for pinch.
+    // velocity is unused on iOS (synthesis speed is governed by durationMs); the wire contract
+    // keeps it for compatibility and direction is carried entirely by the sign of `degrees`.
+    let frame = interactionRoot(app: app).frame
+    let centerX = x ?? Double(frame.midX)
+    let centerY = y ?? Double(frame.midY)
+    return transformGesture(
+      app: app,
+      x: centerX,
+      y: centerY,
+      dx: 0,
+      dy: 0,
+      scale: 1,
+      degrees: degrees,
+      durationMs: 300
+    )
+#elseif os(tvOS)
+    return .unsupported(
+      message: "rotate-gesture is not supported on tvOS",
+      hint: "tvOS has no touch input; rotation gestures require a touchscreen (run on iOS)."
+    )
+#else
+    return .unsupported(
+      message: "rotate-gesture is not supported on macOS",
+      hint: "macOS automation has no multi-touch input; rotation gestures require a touchscreen (run on iOS)."
+    )
+#endif
   }
 
   func transformGesture(
@@ -1540,13 +937,22 @@ extension RunnerTests {
       radius: transformGestureRadius(frame: target.frame, scale: scale),
       durationMs: durationMs
     ) {
-      return .unsupported(message)
+      return .unsupported(
+        message: message,
+        hint: "This gesture uses private XCTest event-synthesis APIs; rebuild the runner with a supported Xcode (these APIs can change across Xcode versions)."
+      )
     }
     return .performed
 #elseif os(tvOS)
-    return .unsupported("transformGesture is not supported on tvOS")
+    return .unsupported(
+      message: "transformGesture is not supported on tvOS",
+      hint: "tvOS has no touch input; transform gestures require a touchscreen (run on iOS)."
+    )
 #else
-    return .unsupported("transformGesture is not supported on macOS")
+    return .unsupported(
+      message: "transformGesture is not supported on macOS",
+      hint: "macOS automation has no multi-touch input; transform gestures require a touchscreen (run on iOS)."
+    )
 #endif
   }
 
@@ -1558,57 +964,6 @@ extension RunnerTests {
     return min(max(scaleAdjustedRadius, 48.0), shorterSide * 0.35)
   }
 
-  private func performCoordinatePinch(app: XCUIApplication, scale: Double, x: Double?, y: Double?) -> RunnerInteractionOutcome {
-#if os(tvOS)
-    return .unsupported("pinch is not supported on tvOS")
-#else
-    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
-
-    // Use double-tap + drag gesture for reliable map zoom
-    // Zoom in (scale > 1): tap then drag UP
-    // Zoom out (scale < 1): tap then drag DOWN
-
-    // Determine center point (use provided x/y or screen center)
-    let centerX = x.map { $0 / target.frame.width } ?? 0.5
-    let centerY = y.map { $0 / target.frame.height } ?? 0.5
-    let center = target.coordinate(withNormalizedOffset: CGVector(dx: centerX, dy: centerY))
-
-    // Calculate drag distance based on scale (clamped to reasonable range)
-    // Larger scale = more drag distance
-    let dragAmount: CGFloat
-    if scale > 1.0 {
-      // Zoom in: drag up (negative Y direction in normalized coords)
-      dragAmount = min(0.4, CGFloat(scale - 1.0) * 0.2)
-    } else {
-      // Zoom out: drag down (positive Y direction)
-      dragAmount = min(0.4, CGFloat(1.0 - scale) * 0.4)
-    }
-
-    let endY = scale > 1.0 ? (centerY - Double(dragAmount)) : (centerY + Double(dragAmount))
-    let endPoint = target.coordinate(withNormalizedOffset: CGVector(dx: centerX, dy: max(0.1, min(0.9, endY))))
-
-    // Tap first (first tap of double-tap)
-    center.tap()
-
-    // Immediately press and drag (second tap + drag)
-    center.press(forDuration: 0.05, thenDragTo: endPoint)
-    return .performed
-#endif
-  }
-
-  private func performCoordinateRotateGesture(app: XCUIApplication, degrees: Double, x: Double?, y: Double?, velocity: Double) -> RunnerInteractionOutcome {
-#if os(iOS)
-    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
-    let radians = CGFloat(degrees * .pi / 180.0)
-    target.rotate(radians, withVelocity: CGFloat(velocity))
-    return .performed
-#elseif os(tvOS)
-    return .unsupported("rotate-gesture is not supported on tvOS")
-#else
-    return .unsupported("rotate-gesture is not supported on macOS")
-#endif
-  }
-
   private func interactionRoot(app: XCUIApplication) -> XCUIElement {
     let windows = app.windows.allElementsBoundByIndex
     if let window = windows.first(where: { $0.exists && !$0.frame.isEmpty }) {
@@ -1619,7 +974,10 @@ extension RunnerTests {
 
   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")
+    return .unsupported(
+      message: "coordinate tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then select it."
+    )
 #else
     interactionCoordinate(app: app, x: x, y: y).tap()
     return .performed
@@ -1628,7 +986,10 @@ extension RunnerTests {
 
   private func performCoordinateDoubleTap(app: XCUIApplication, x: Double, y: Double) -> RunnerInteractionOutcome {
 #if os(tvOS)
-    return .unsupported("coordinate double tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element")
+    return .unsupported(
+      message: "coordinate double tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then select it."
+    )
 #else
     interactionCoordinate(app: app, x: x, y: y).doubleTap()
     return .performed
@@ -1637,7 +998,10 @@ extension RunnerTests {
 
   private func performCoordinateLongPress(app: XCUIApplication, x: Double, y: Double, duration: TimeInterval) -> RunnerInteractionOutcome {
 #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")
+    return .unsupported(
+      message: "coordinate long press is not supported on tvOS; move focus with swipe or scroll, then long-select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then long-select it."
+    )
 #else
     interactionCoordinate(app: app, x: x, y: y).press(forDuration: duration)
     return .performed
@@ -1653,7 +1017,10 @@ extension RunnerTests {
     holdDuration: TimeInterval
   ) -> RunnerInteractionOutcome {
 #if os(tvOS)
-    return .unsupported("coordinate drag is not supported on tvOS")
+    return .unsupported(
+      message: "coordinate drag is not supported on tvOS",
+      hint: "tvOS has no coordinate input; use remote-driven swipe/scroll to move focus instead."
+    )
 #else
     let start = interactionCoordinate(app: app, x: x, y: y)
     let end = interactionCoordinate(app: app, x: x2, y: y2)