agent-device 0.20.9 → 0.21.0

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

@@ -7,6 +7,7 @@ extension RunnerTests {
   enum TextEntryFailure: String {
     case notFocused = "TEXT_INPUT_NOT_FOCUSED"
     case synthesisUnavailable = "TEXT_INPUT_SYNTHESIS_UNAVAILABLE"
+    case commitNotObserved = "TEXT_INPUT_COMMIT_NOT_OBSERVED"
 
     var message: String {
       switch self {
@@ -14,6 +15,8 @@ extension RunnerTests {
         return "No focused text input was available for typing."
       case .synthesisUnavailable:
         return "Reliable text synthesis is unavailable while the software keyboard is hidden."
+      case .commitNotObserved:
+        return "The runner could not confirm the typed text reached the field."
       }
     }
 
@@ -23,6 +26,8 @@ extension RunnerTests {
         return "Focus a visible text input, then retry type or fill. If the input is not exposed by accessibility, use a coordinate focus command before typing."
       case .synthesisUnavailable:
         return "Show the software keyboard, then retry type or fill."
+      case .commitNotObserved:
+        return "The field may hold none, part, or all of the text. Run snapshot -i and inspect the field: if it already matches, continue; otherwise retry fill with the full text quoted and --delay-ms 80. Do not use type, which appends to whatever committed."
       }
     }
   }
@@ -40,7 +45,15 @@ extension RunnerTests {
     static let pollInterval: TimeInterval = 0.02
     static let warmupValueTimeout: TimeInterval = 0.4
     static let verificationStabilityWindow: TimeInterval = 0.2
-    static let synthesizedCommitTimeout: TimeInterval = 3.0
+    /// How long the commit wait tolerates seeing NO further progress toward the expected value.
+    /// Numerically the flat deadline this replaced, so a pipeline that delivers nothing is
+    /// condemned at exactly the same instant it always was (see `SynthesizedCommitDeadline`).
+    static let synthesizedCommitStallTimeout: TimeInterval = 3.0
+    /// The commit wait's absolute bound, however long characters keep arriving. Sits well inside
+    /// the daemon's per-command budget (`RUNNER_COMMAND_TIMEOUT_MS`, 45s), which also has to cover
+    /// focus, clear and verification around this wait.
+    static let synthesizedCommitCeiling: TimeInterval = 10.0
+    static let synthesizedCommitPollInterval: TimeInterval = 0.2
   }
 
   struct TextEntryResult {
@@ -121,211 +134,6 @@ extension RunnerTests {
     element.typeText(deletes)
   }
 
-  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
-    return safely("FOCUSED_INPUT_QUERY") {
-      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:
-          return candidate
-        default:
-          continue
-        }
-      }
-      return nil
-    }
-#endif
-  }
-
-  func rememberTextEntryTap(_ element: XCUIElement?) {
-    guard let element, isTextEntryElement(element) else {
-      clearRememberedTextEntryTap()
-      return
-    }
-    textEntryTapWitness = TextEntryTapWitness(
-      element: element,
-      bundleId: currentBundleId,
-      processIdentifier: currentAppProcessIdentifier
-    )
-  }
-
-  func clearRememberedTextEntryTap() {
-    textEntryTapWitness = nil
-  }
-
-  private func rememberedTextEntryTarget() -> TextEntryTarget? {
-    guard let witness = textEntryTapWitness else {
-      return nil
-    }
-    // The tap is proof for one immediately-following bare type only. Consume it before checking
-    // the element so a failed or interrupted type cannot reuse stale focus evidence.
-    clearRememberedTextEntryTap()
-    guard witness.matches(
-      bundleId: currentBundleId,
-      processIdentifier: currentAppProcessIdentifier
-    ) else {
-      return nil
-    }
-    let element = witness.element
-    // XCUIElement is query-backed rather than a stable node identity. A same-identifier field
-    // introduced by app-side navigation between tap and this immediate type can therefore
-    // re-resolve here; keep the witness one-shot and fail closed on every observable identity
-    // boundary instead of using frame equality, which would reject legitimate layout changes.
-    guard safely("LAST_TAPPED_TEXT_INPUT_EXISTS", false, { element.exists }) else {
-      return nil
-    }
-    // Keep the target scoped to the element that the preceding tap actually selected. Do not
-    // attach a refresh point: if that element disappeared, bare type must fail closed rather
-    // than rediscovering a different field or dispatching unscoped app.typeText.
-    return TextEntryTarget(
-      element: element,
-      refreshPoint: nil,
-      prefersFocusedElement: false,
-      fromTapWitness: true
-    )
-  }
-
-  func stabilizeTextInputBeforeTyping(
-    app: XCUIApplication,
-    target: XCUIElement?,
-    keyboardVisibleBeforeTap: Bool? = nil
-  ) -> TextEntryStabilization {
-#if os(tvOS)
-    return TextEntryStabilization(element: target, focusConfirmed: true)
-#else
-    let latest = target
-    let keyboardVisibleAtEntry = keyboardVisibleBeforeTap ?? isKeyboardVisible(app: app)
-    let deadline = Date().addingTimeInterval(TextEntryTiming.focusTimeout)
-    while Date() < deadline {
-      if let focused = focusedTextInput(app: app) {
-        return TextEntryStabilization(element: focused, focusConfirmed: true)
-      }
-      // focusedTextInput is intentionally nil on iOS; treat the keyboard transitioning to
-      // visible after our tap as the focus-moved signal. Don't fast-path when it was already up.
-      if keyboardBecameVisible(app: app, wasVisibleAtEntry: keyboardVisibleAtEntry) {
-        return TextEntryStabilization(element: latest, focusConfirmed: true)
-      }
-      sleepFor(TextEntryTiming.pollInterval)
-    }
-    return TextEntryStabilization(element: latest, focusConfirmed: false)
-#endif
-  }
-
-  func focusTextInputForTextEntry(app: XCUIApplication, x: Double?, y: Double?) -> TextEntryTarget {
-    guard let x, let y else {
-      let softwareKeyboardVisible = isKeyboardVisible(app: app)
-      if !softwareKeyboardVisible, let rememberedTarget = rememberedTextEntryTarget() {
-        return rememberedTarget
-      }
-      // Bare `type` targets the current first responder. On iOS we intentionally do not trust
-      // `hasKeyboardFocus`, but an already-visible software keyboard is sufficient evidence that
-      // app.typeText has a receiver; waiting the full readiness timeout cannot prove a stronger
-      // target because there is no selector/coordinate focus move to validate.
-      if softwareKeyboardVisible {
-        return TextEntryTarget(
-          element: focusedTextInput(app: app),
-          refreshPoint: nil,
-          prefersFocusedElement: true
-        )
-      }
-      let focused = waitForTextEntryReadiness(
-        app: app,
-        target: TextEntryTarget(
-          element: focusedTextInput(app: app),
-          refreshPoint: nil,
-          prefersFocusedElement: true
-        )
-      )
-      return TextEntryTarget(element: focused, refreshPoint: nil, prefersFocusedElement: true)
-    }
-
-    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
-    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)
-    }
-    // A visible keyboard is not enough evidence for app.typeText, because focus may still
-    // belong to a previous field. With a concrete target we type through XCUIElement.typeText,
-    // so after tapping it the iOS readiness timeout cannot prove anything stronger.
-    if keyboardVisibleBeforeTap, let target {
-      return TextEntryTarget(
-        element: target,
-        refreshPoint: textEntryRefreshPoint(for: target) ?? requestedPoint,
-        prefersFocusedElement: false
-      )
-    }
-    let stabilized = stabilizeTextInputBeforeTyping(
-      app: app,
-      target: target,
-      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
-    )
-    let readyTarget = TextEntryTarget(
-      element: stabilized.element ?? target,
-      refreshPoint: requestedPoint,
-      prefersFocusedElement: false
-    )
-    let concreteTargetReady = keyboardVisibleBeforeTap && readyTarget.element != nil
-    let element = stabilized.focusConfirmed || concreteTargetReady
-      ? (stabilized.element ?? target)
-      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? target)
-    return TextEntryTarget(
-      element: element,
-      refreshPoint: textEntryRefreshPoint(for: element) ?? requestedPoint,
-      prefersFocusedElement: false
-    )
-  }
-
-  func focusTextInputForTextEntry(app: XCUIApplication, element: XCUIElement) -> TextEntryTarget {
-    let point = textEntryRefreshPoint(for: element)
-    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
-    if let point {
-      _ = tapAt(app: app, x: point.x, y: point.y)
-    }
-    // See the coordinate-target path above: direct element typing keeps this scoped to the
-    // tapped target, while the first-character warmup and final verify still catch dropped input.
-    if keyboardVisibleBeforeTap {
-      return TextEntryTarget(
-        element: element,
-        refreshPoint: textEntryRefreshPoint(for: element) ?? point,
-        prefersFocusedElement: false
-      )
-    }
-    let stabilized = stabilizeTextInputBeforeTyping(
-      app: app,
-      target: element,
-      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
-    )
-    let readyTarget = TextEntryTarget(
-      element: stabilized.element ?? element,
-      refreshPoint: point,
-      prefersFocusedElement: false
-    )
-    let resolved = stabilized.focusConfirmed
-      ? (stabilized.element ?? element)
-      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? 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:
@@ -369,103 +177,6 @@ extension RunnerTests {
     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 keyboardVisibleAtEntry = isKeyboardVisible(app: app)
-    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
-        }
-      }
-      // Fast-path on a keyboard hidden->visible transition: our tapped field gained focus, so
-      // return immediately instead of burning the full readinessTimeout (warmup-first-char echo
-      // + post-type verify/repair remain as drop safety nets). When the keyboard was ALREADY up
-      // (back-to-back fills), this isn't a focus signal — fall through to the settle/timeout so
-      // text isn't sent to the previously-focused field.
-      if keyboardBecameVisible(app: app, wasVisibleAtEntry: keyboardVisibleAtEntry) {
-        return latest
-      }
-      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)
-  }
-
-  /// A focus-moved signal for iOS text entry, where `focusedTextInput` is intentionally nil.
-  /// The software keyboard TRANSITIONING from hidden (at entry) to visible means the field we
-  /// just tapped gained first-responder. If the keyboard was ALREADY up (e.g. back-to-back
-  /// fills into different fields), its visibility is not evidence focus moved to the new field,
-  /// so callers must keep waiting rather than typing into the previously-focused field.
-  private func keyboardBecameVisible(app: XCUIApplication, wasVisibleAtEntry: Bool) -> Bool {
-    return !wasVisibleAtEntry && isKeyboardVisible(app: app)
-  }
-
-  private func keyboardElementExists(app: XCUIApplication) -> Bool {
-#if os(iOS)
-    return safely("KEYBOARD_EXISTS", false) { app.keyboards.firstMatch.exists }
-#else
-    return false
-#endif
-  }
-
   private func moveCaretToEnd(element: XCUIElement) {
 #if os(tvOS)
     return
@@ -516,14 +227,13 @@ extension RunnerTests {
   }
 
   private func isPlaceholderValue(_ value: String, for element: XCUIElement) -> Bool {
+    if Self.textMatchesPlaceholder(value, placeholder: element.placeholderValue) {
+      return true
+    }
     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
     }
@@ -531,6 +241,13 @@ extension RunnerTests {
     return normalizedLabel == normalizedValue && isGenericTextInputLabel(normalizedLabel)
   }
 
+  static func textMatchesPlaceholder(_ text: String, placeholder: String?) -> Bool {
+    let normalizedText = text.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !normalizedText.isEmpty else { return false }
+    let normalizedPlaceholder = placeholder?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    return !normalizedPlaceholder.isEmpty && normalizedText == normalizedPlaceholder
+  }
+
   private func isGenericTextInputLabel(_ value: String) -> Bool {
     switch value {
     case "Text input field":

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

@@ -0,0 +1,206 @@
+import XCTest
+
+// Text-entry target acquisition: choosing the element a `type`/`fill` will address and getting
+// focus onto it — the one-shot tap witness, the post-tap stabilization, and the two
+// `focusTextInputForTextEntry` entry points the command layer calls. Whether that target is ready
+// is RunnerTests+TextEntryReadiness.swift's question, and this file asks it rather than answering
+// it.
+extension RunnerTests {
+  func rememberTextEntryTap(_ element: XCUIElement?) {
+    guard let element, isTextEntryElement(element) else {
+      clearRememberedTextEntryTap()
+      return
+    }
+    textEntryTapWitness = TextEntryTapWitness(
+      element: element,
+      bundleId: currentBundleId,
+      processIdentifier: currentAppProcessIdentifier
+    )
+  }
+
+  func clearRememberedTextEntryTap() {
+    textEntryTapWitness = nil
+  }
+
+  private func rememberedTextEntryTarget() -> TextEntryTarget? {
+    guard let witness = textEntryTapWitness else {
+      return nil
+    }
+    // The tap is proof for one immediately-following bare type only. Consume it before checking
+    // the element so a failed or interrupted type cannot reuse stale focus evidence.
+    clearRememberedTextEntryTap()
+    guard witness.matches(
+      bundleId: currentBundleId,
+      processIdentifier: currentAppProcessIdentifier
+    ) else {
+      return nil
+    }
+    let element = witness.element
+    // XCUIElement is query-backed rather than a stable node identity. A same-identifier field
+    // introduced by app-side navigation between tap and this immediate type can therefore
+    // re-resolve here; keep the witness one-shot and fail closed on every observable identity
+    // boundary instead of using frame equality, which would reject legitimate layout changes.
+    guard safely("LAST_TAPPED_TEXT_INPUT_EXISTS", false, { element.exists }) else {
+      return nil
+    }
+    // Keep the target scoped to the element that the preceding tap actually selected. Do not
+    // attach a refresh point: if that element disappeared, bare type must fail closed rather
+    // than rediscovering a different field or dispatching unscoped app.typeText.
+    return TextEntryTarget(
+      element: element,
+      refreshPoint: nil,
+      prefersFocusedElement: false,
+      fromTapWitness: true
+    )
+  }
+
+  func stabilizeTextInputBeforeTyping(
+    app: XCUIApplication,
+    target: XCUIElement?,
+    keyboardVisibleBeforeTap: Bool? = nil
+  ) -> TextEntryStabilization {
+#if os(tvOS)
+    return TextEntryStabilization(element: target, focusConfirmed: true)
+#else
+    let latest = target
+    let keyboardVisibleAtEntry = keyboardVisibleBeforeTap ?? isKeyboardVisible(app: app)
+    let deadline = Date().addingTimeInterval(TextEntryTiming.focusTimeout)
+    while Date() < deadline {
+      if let focused = focusedTextInput(app: app) {
+        return TextEntryStabilization(element: focused, focusConfirmed: true)
+      }
+      // focusedTextInput is intentionally nil on iOS; treat the keyboard transitioning to
+      // visible after our tap as the focus-moved signal. Don't fast-path when it was already up.
+      if keyboardBecameVisible(app: app, wasVisibleAtEntry: keyboardVisibleAtEntry) {
+        return TextEntryStabilization(element: latest, focusConfirmed: true)
+      }
+      sleepFor(TextEntryTiming.pollInterval)
+    }
+    return TextEntryStabilization(element: latest, focusConfirmed: false)
+#endif
+  }
+
+  func focusTextInputForTextEntry(app: XCUIApplication, x: Double?, y: Double?) -> TextEntryTarget {
+    guard let x, let y else {
+      let softwareKeyboardVisible = isKeyboardVisible(app: app)
+      if !softwareKeyboardVisible, let rememberedTarget = rememberedTextEntryTarget() {
+        return rememberedTarget
+      }
+      // Bare `type` targets the current first responder. On iOS we intentionally do not trust
+      // `hasKeyboardFocus`, but an already-visible software keyboard is sufficient evidence that
+      // app.typeText has a receiver; waiting the full readiness timeout cannot prove a stronger
+      // target because there is no selector/coordinate focus move to validate.
+      if softwareKeyboardVisible {
+        return TextEntryTarget(
+          element: focusedTextInput(app: app),
+          refreshPoint: nil,
+          prefersFocusedElement: true
+        )
+      }
+      let focused = waitForTextEntryReadiness(
+        app: app,
+        target: TextEntryTarget(
+          element: focusedTextInput(app: app),
+          refreshPoint: nil,
+          prefersFocusedElement: true
+        )
+      )
+      return TextEntryTarget(element: focused, refreshPoint: nil, prefersFocusedElement: true)
+    }
+
+    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
+    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)
+    }
+    // A visible keyboard is not enough evidence for app.typeText, because focus may still
+    // belong to a previous field. With a concrete target we type through XCUIElement.typeText,
+    // so after tapping it the iOS readiness timeout cannot prove anything stronger.
+    if keyboardVisibleBeforeTap, let target {
+      return TextEntryTarget(
+        element: target,
+        refreshPoint: textEntryRefreshPoint(for: target) ?? requestedPoint,
+        prefersFocusedElement: false
+      )
+    }
+    let stabilized = stabilizeTextInputBeforeTyping(
+      app: app,
+      target: target,
+      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
+    )
+    let readyTarget = TextEntryTarget(
+      element: stabilized.element ?? target,
+      refreshPoint: requestedPoint,
+      prefersFocusedElement: false
+    )
+    let concreteTargetReady = keyboardVisibleBeforeTap && readyTarget.element != nil
+    let element = stabilized.focusConfirmed || concreteTargetReady
+      ? (stabilized.element ?? target)
+      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? target)
+    return TextEntryTarget(
+      element: element,
+      refreshPoint: textEntryRefreshPoint(for: element) ?? requestedPoint,
+      prefersFocusedElement: false
+    )
+  }
+
+  func focusTextInputForTextEntry(app: XCUIApplication, element: XCUIElement) -> TextEntryTarget {
+    let point = textEntryRefreshPoint(for: element)
+    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
+    if let point {
+      _ = tapAt(app: app, x: point.x, y: point.y)
+    }
+    // See the coordinate-target path above: direct element typing keeps this scoped to the
+    // tapped target, while the first-character warmup and final verify still catch dropped input.
+    if keyboardVisibleBeforeTap {
+      return TextEntryTarget(
+        element: element,
+        refreshPoint: textEntryRefreshPoint(for: element) ?? point,
+        prefersFocusedElement: false
+      )
+    }
+    let stabilized = stabilizeTextInputBeforeTyping(
+      app: app,
+      target: element,
+      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
+    )
+    let readyTarget = TextEntryTarget(
+      element: stabilized.element ?? element,
+      refreshPoint: point,
+      prefersFocusedElement: false
+    )
+    let resolved = stabilized.focusConfirmed
+      ? (stabilized.element ?? element)
+      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? element)
+    return TextEntryTarget(
+      element: resolved,
+      refreshPoint: textEntryRefreshPoint(for: resolved) ?? point,
+      prefersFocusedElement: false
+    )
+  }
+
+  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)
+  }
+
+  /// A focus-moved signal for iOS text entry, where `focusedTextInput` is intentionally nil.
+  /// The software keyboard TRANSITIONING from hidden (at entry) to visible means the field we
+  /// just tapped gained first-responder. If the keyboard was ALREADY up (e.g. back-to-back
+  /// fills into different fields), its visibility is not evidence focus moved to the new field,
+  /// so callers must keep waiting rather than typing into the previously-focused field.
+}