agent-device 0.20.5 → 0.20.7

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

@@ -136,8 +136,9 @@ struct Command: Codable {
   let gesturePlan: RunnerGesturePlan?
   let outPath: String?
   let fps: Int?
-  let maxSize: Int?
   let interactiveOnly: Bool?
+  let preferredBackend: String?
+  let customActions: Bool?
   let depth: Int?
   let scope: String?
   let raw: Bool?
@@ -257,11 +258,13 @@ struct DataPayload: Codable {
   let visible: Bool?
   let wasVisible: Bool?
   let dismissed: Bool?
+  let keyboardDismissMechanism: String?
   let orientation: String?
   let gestureFallback: String?
   let gestureFallbackMessage: String?
   let gestureFallbackHint: String?
   let maestroNonHittableCoordinateFallbackUsed: Bool?
+  let textEntryRoute: String?
   let runnerFatal: Bool?
   let runnerFatalReason: String?
   let completedSteps: Int?
@@ -297,11 +300,13 @@ struct DataPayload: Codable {
     visible: Bool? = nil,
     wasVisible: Bool? = nil,
     dismissed: Bool? = nil,
+    keyboardDismissMechanism: String? = nil,
     orientation: String? = nil,
     gestureFallback: String? = nil,
     gestureFallbackMessage: String? = nil,
     gestureFallbackHint: String? = nil,
     maestroNonHittableCoordinateFallbackUsed: Bool? = nil,
+    textEntryRoute: String? = nil,
     runnerFatal: Bool? = nil,
     runnerFatalReason: String? = nil,
     completedSteps: Int? = nil,
@@ -336,11 +341,13 @@ struct DataPayload: Codable {
     self.visible = visible
     self.wasVisible = wasVisible
     self.dismissed = dismissed
+    self.keyboardDismissMechanism = keyboardDismissMechanism
     self.orientation = orientation
     self.gestureFallback = gestureFallback
     self.gestureFallbackMessage = gestureFallbackMessage
     self.gestureFallbackHint = gestureFallbackHint
     self.maestroNonHittableCoordinateFallbackUsed = maestroNonHittableCoordinateFallbackUsed
+    self.textEntryRoute = textEntryRoute
     self.runnerFatal = runnerFatal
     self.runnerFatalReason = runnerFatalReason
     self.completedSteps = completedSteps
@@ -383,6 +390,9 @@ struct SnapshotNode: Codable {
   let parentIndex: Int?
   let hiddenContentAbove: Bool?
   let hiddenContentBelow: Bool?
+  /// Names of the element's UIAccessibilityCustomActions, present only when the
+  /// capture asked for them and the element carries some.
+  var actions: [String]? = nil
 }
 
 struct SnapshotOptions {
@@ -390,4 +400,11 @@ struct SnapshotOptions {
   let depth: Int?
   let scope: String?
   let raw: Bool
+  /// Internal daemon ask: capture with this backend first regardless of channel
+  /// health ("private-ax"). Same-backend evidence probes (tap-outcome
+  /// corroboration) must be captured the way their baseline was.
+  var preferredBackend: String? = nil
+  /// Read UIAccessibilityCustomActions for merged leaves. Opt-in: each element
+  /// costs its own AX round trip (see RunnerAXSnapshotBridge).
+  var customActions: Bool = false
 }

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

@@ -7,7 +7,6 @@ extension RunnerTests {
   final class ScreenRecorder {
     private let outputPath: String
     private let fps: Int32?
-    private let maxSize: Int?
     private var effectiveFps: Int32 {
       max(1, fps ?? RunnerTests.defaultRecordingFps)
     }
@@ -26,10 +25,9 @@ extension RunnerTests {
     private var startedSession = false
     private var startError: Error?
 
-    init(outputPath: String, fps: Int32?, maxSize: Int?) {
+    init(outputPath: String, fps: Int32?) {
       self.outputPath = outputPath
       self.fps = fps
-      self.maxSize = maxSize
     }
 
     func start(captureFrame: @escaping () -> RunnerImage?) throws {
@@ -50,7 +48,7 @@ extension RunnerTests {
       while Date() < bootstrapDeadline {
         if let image = captureFrame(), let cgImage = runnerCGImage(from: image) {
           bootstrapImage = image
-          dimensions = scaledDimensions(width: cgImage.width, height: cgImage.height)
+          dimensions = CGSize(width: cgImage.width, height: cgImage.height)
           break
         }
         Thread.sleep(forTimeInterval: 0.05)
@@ -261,23 +259,5 @@ extension RunnerTests {
       return pixelBuffer
     }
 
-    private func scaledDimensions(width: Int, height: Int) -> CGSize {
-      guard let maxSize, maxSize > 0 else {
-        return CGSize(width: width, height: height)
-      }
-      let longest = max(width, height)
-      guard longest > maxSize else {
-        return CGSize(width: width, height: height)
-      }
-      let scale = Double(maxSize) / Double(longest)
-      return CGSize(
-        width: scaledEvenDimension(width, scale: scale),
-        height: scaledEvenDimension(height, scale: scale)
-      )
-    }
-
-    private func scaledEvenDimension(_ value: Int, scale: Double) -> Int {
-      max(2, Int((Double(value) * scale / 2.0).rounded()) * 2)
-    }
   }
 }

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

@@ -0,0 +1,4 @@
+import XCTest
+
+extension RunnerTests {
+}

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

@@ -493,7 +493,8 @@ extension RunnerTests {
         reason: failure.message,
         reasonCode: "ax-rejected",
         effectiveDepth: nil,
-        collapsedLeafIndexes: nil
+        collapsedLeafIndexes: nil,
+        customActions: nil
       ),
       runnerFatal: true,
       runnerFatalReason: Self.axSnapshotUnavailableReason

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

@@ -22,6 +22,23 @@ struct SnapshotQuality: Codable {
   let effectiveDepth: Int?
   /// Leaves that merge many labels — a container marked accessible hides its descendants.
   let collapsedLeafIndexes: [Int]?
+  /// Coverage of the bounded custom-action pass, when the capture asked for one.
+  let customActions: SnapshotCustomActionCoverage?
+}
+
+/// How much of the merged-element set the custom-action pass actually read. An
+/// unread element renders exactly like one with no actions, so a partial pass
+/// has to say so — otherwise absence reads as proof of absence.
+struct SnapshotCustomActionCoverage: Codable {
+  let read: Int
+  let candidates: Int
+  /// Elements whose action list was clipped by the per-element output caps. A
+  /// clipped list looks complete, so it is disclosed on the same principle as
+  /// an unread element.
+  let truncated: Int
+  /// The pass stopped early because an earlier read is still hung. Distinct from
+  /// a budget stop: the remedy is waiting, not scrolling.
+  let blocked: Bool
 }
 
 enum SnapshotBackendKind: String, CaseIterable {
@@ -78,6 +95,8 @@ struct SnapshotBackendCapture {
   let payload: DataPayload
   /// Set by the private AX backend when the ladder accepted a shallower depth than requested.
   let effectiveDepth: Int?
+  /// Set by the private AX backend when the capture asked for custom actions.
+  var customActions: SnapshotCustomActionCoverage? = nil
 }
 
 extension RunnerTests {
@@ -144,6 +163,53 @@ extension RunnerTests {
     return pending
   }
 
+  /// The pre-seeded first-failure a penalized plan stamps into its verdict. The deferred case
+  /// uses the dedicated 'deferred' code: the breaker pre-selected the backend, nothing new
+  /// degraded on this capture, and the daemon keys warning suppression and the settle budget
+  /// reset off exactly that distinction. The bounded probe keeps 'budget': its short XCTest
+  /// slice genuinely constrains what this capture could read.
+  ///
+  /// `requestPinnedBackend` separates the two ways the plan can arrive at the same
+  /// deferred shape. A capture that ASKED for a private-AX-only reading (custom
+  /// actions) degraded nothing, so reporting slow accessibility work would name a
+  /// cause that does not exist.
+  static func xcTestChannelStateFirstFailure(
+    _ state: SnapshotXCTestChannelPlanState,
+    requestPinnedBackend: Bool = false
+  ) -> (reason: String, code: String)? {
+    switch state {
+    case .normal:
+      return nil
+    case .deferredToIndependentBackend:
+      if requestPinnedBackend {
+        return (
+          "the private AX backend was selected because this capture asked for accessibility custom actions",
+          "requested-backend"
+        )
+      }
+      return (
+        "XCTest-backed snapshot tiers were deferred after recent slow accessibility work on this screen",
+        "deferred"
+      )
+    case .boundedXCTestProbe:
+      return (
+        "XCTest-backed snapshot tiers are running with a short recovery probe after recent slow accessibility work on this screen",
+        "budget"
+      )
+    }
+  }
+
+  /// Pure gate: a capture is planned as penalized when the channel penalty is
+  /// active OR the daemon pinned the private-AX backend (same-backend evidence
+  /// probe) — both mean "do not enter XCTest tree work first, and stamp the
+  /// pre-selection as 'deferred' rather than a degradation".
+  static func snapshotXCTestChannelTreatedAsPenalized(
+    penalized: Bool,
+    preferredBackend: String?
+  ) -> Bool {
+    penalized || preferredBackend == SnapshotBackendKind.privateAX.rawValue
+  }
+
   /// Pure plan-reorder rule: a penalized XCTest accessibility channel uses independent backends
   /// when the platform has one, otherwise it keeps XCTest work on a short probe. The raw
   /// diagnostic plan keeps tree-first errors, and unknown plans are left untouched.
@@ -198,9 +264,17 @@ extension RunnerTests {
     // Reorder is iOS-only because hostile screens can make XCTest tree/query work grind while
     // the app remains visually responsive. Simulators can avoid that channel through private AX;
     // physical devices have no independent semantic backend yet, so they use a bounded probe.
+    // A daemon-preferred private-AX capture (same-backend evidence probe) takes the exact
+    // penalized route: privateAX-first plan, 'deferred' verdict — the backend was pre-selected
+    // deliberately, so no degradation warning should render for it.
     var xCTestChannelPenalized = false
+    var xCTestChannelPenalizedByBreaker = false
 #if os(iOS)
-    xCTestChannelPenalized = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
+    xCTestChannelPenalizedByBreaker = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
+    xCTestChannelPenalized = Self.snapshotXCTestChannelTreatedAsPenalized(
+      penalized: xCTestChannelPenalizedByBreaker,
+      preferredBackend: options.preferredBackend
+    )
 #endif
     let effective = Self.effectiveSnapshotCapturePlan(
       plan,
@@ -208,20 +282,18 @@ extension RunnerTests {
       availableBackends: Set(SnapshotBackendKind.allCases.filter(\.isAvailableOnCurrentPlatform))
     )
     let effectivePlan = effective.plan
+    // Only a customActions-implied pin is request-pinned; the daemon's
+    // same-backend evidence probe pins for its own reasons and keeps 'deferred'.
+    firstFailure = Self.xcTestChannelStateFirstFailure(
+      effective.xCTestChannelState,
+      requestPinnedBackend: options.customActions && !xCTestChannelPenalizedByBreaker
+    )
     switch effective.xCTestChannelState {
     case .normal:
       break
     case .deferredToIndependentBackend:
-      firstFailure = (
-        "XCTest-backed snapshot tiers were deferred after recent slow accessibility work on this screen",
-        "budget"
-      )
       NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_DEFERRED bundle=%@", currentBundleId ?? "")
     case .boundedXCTestProbe:
-      firstFailure = (
-        "XCTest-backed snapshot tiers are running with a short recovery probe after recent slow accessibility work on this screen",
-        "budget"
-      )
       NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_PROBE_BOUNDED bundle=%@", currentBundleId ?? "")
     }
 
@@ -428,7 +500,7 @@ extension RunnerTests {
       return ("snapshot returned no nodes", "no-nodes")
     }
     if isSparseApplicationWindowTree(nodes) {
-      return ("snapshot returned only structural application/window nodes", "sparse-tree")
+      return ("snapshot returned no semantic controls or content", "sparse-tree")
     }
     if payload.truncated == true && nodes.count <= sparseRecoveryTruncatedNodeThreshold {
       return ("snapshot was cut off by its budget with almost nothing collected", "budget")
@@ -459,19 +531,36 @@ extension RunnerTests {
 
   static func isSparseApplicationWindowTree(_ nodes: [SnapshotNode]) -> Bool {
     guard !nodes.isEmpty else { return false }
+    let rootRects = nodes.compactMap { node in
+      node.type == "Application" || node.type == "Window" ? node.rect : nil
+    }
     return nodes.allSatisfy { node in
       // Application/Window labels are just the app/window name, and full-screen roots
       // compute as hittable; neither says anything about tree health.
       let isRootContainer = node.type == "Application" || node.type == "Window"
-      let hasContent = (!isRootContainer && node.label?.isEmpty == false)
-        || node.identifier?.isEmpty == false
-        || node.value?.isEmpty == false
-      return !hasContent
-        && (isRootContainer || !node.hittable)
-        && Self.structuralOnlyNodeTypes.contains(node.type)
+      guard Self.structuralOnlyNodeTypes.contains(node.type) else { return false }
+      guard !isRootContainer else { return true }
+
+      let isFullScreenContainer = !node.hittable && rootRects.contains { rootRect in
+        rootRect.x == node.rect.x && rootRect.y == node.rect.y
+          && rootRect.width == node.rect.width && rootRect.height == node.rect.height
+      }
+      let hasAddressableIdentifier = node.identifier?.isEmpty == false && !isFullScreenContainer
+      return !Self.isSemanticSnapshotText(node.label)
+        && !Self.isSemanticSnapshotText(node.value)
+        && !hasAddressableIdentifier
     }
   }
 
+  /// Private AX can stringify an unserializable accessibility label as the JavaScript object
+  /// placeholder. It is transport residue, not UI content, and must not make a shell-only tree
+  /// look healthy.
+  static func isSemanticSnapshotText(_ text: String?) -> Bool {
+    guard let text else { return false }
+    let normalized = text.trimmingCharacters(in: .whitespacesAndNewlines)
+    return !normalized.isEmpty && normalized.lowercased() != "[object object]"
+  }
+
   /// A leaf whose label joins many short segments is a container marked as an accessibility
   /// element: the platform folds every descendant into one merged node. Nothing below it can
   /// be addressed — by automation or by assistive tech. This is app-side; no backend recovers it.
@@ -502,7 +591,8 @@ extension RunnerTests {
       reason: reason?.reason,
       reasonCode: reason?.code,
       effectiveDepth: capture.effectiveDepth,
-      collapsedLeafIndexes: Self.collapsedLeafIndexes(payload.nodes ?? [])
+      collapsedLeafIndexes: Self.collapsedLeafIndexes(payload.nodes ?? []),
+      customActions: capture.customActions
     )
     return DataPayload(
       // Legacy human text for older daemons that read message instead of snapshotQuality.
@@ -515,11 +605,42 @@ extension RunnerTests {
     )
   }
 
+  /// Response level, one line per incompleteness. An unread merged element is
+  /// byte-identical to one with no actions, and a clipped list looks complete,
+  /// so both have to name themselves.
+  static func customActionCoverageWarnings(_ coverage: SnapshotCustomActionCoverage) -> [String] {
+    var lines: [String] = []
+    if coverage.blocked {
+      // Scrolling is the remedy for a budget stop, not for this one — saying it
+      // here would send the reader off doing something that cannot help.
+      lines.append(
+        "Custom actions were not read: an earlier accessibility read is still hung, so this "
+          + "capture skipped the read pass instead of queueing behind it. No element's actions "
+          + "list is authoritative here. Reads resume once that call returns.")
+    } else if coverage.read < coverage.candidates {
+      lines.append(
+        "Custom actions were read for \(coverage.read) of \(coverage.candidates) merged elements, "
+          + "on-screen ones first; the remaining \(coverage.candidates - coverage.read) were not read, "
+          + "so an absent actions list on those is not evidence that they have none. "
+          + "Scroll them into view and re-run to read them.")
+    }
+    if coverage.truncated > 0 {
+      lines.append(
+        "\(coverage.truncated) element(s) published more custom actions than are shown; those "
+          + "lists are clipped to the first 8 names, and long names are shortened.")
+    }
+    return lines
+  }
+
   static func legacyQualityMessage(_ quality: SnapshotQuality) -> String? {
-    guard quality.state != "healthy" || quality.collapsedLeafIndexes != nil else { return nil }
+    let customActionWarnings =
+      quality.customActions.map { Self.customActionCoverageWarnings($0) } ?? []
+    guard quality.state != "healthy" || quality.collapsedLeafIndexes != nil
+      || !customActionWarnings.isEmpty
+    else { return nil }
     var parts: [String] = []
     if quality.state == "recovered" {
-      let meaning = quality.reasonCode == "budget"
+      let meaning = quality.reasonCode == "budget" || quality.reasonCode == "deferred"
         ? " The primary capture ran out of its time budget (busy app or simulator); the recovered tree is authoritative for this screen."
         : " This usually means the app publishes an unhealthy accessibility tree — fixing the app's accessibility is the real cure. Treat screenshot as visual truth when this warning appears."
       parts.append(
@@ -535,9 +656,13 @@ extension RunnerTests {
           + ". Use screenshot as visual truth and coordinate taps."
       )
     }
+    parts.append(contentsOf: customActionWarnings)
     if let depth = quality.effectiveDepth {
+      // No --depth remedy here: an explicit --depth capture disables the
+      // frontier extension, so following it would return strictly less than
+      // this capture did. A plain re-run retries with a fresh extension budget.
       parts.append(
-        "The accessibility server rejected deeper requests; this tree is capped at depth \(depth) — re-run with --depth \(depth) --scope <container> for deeper content."
+        "The accessibility server rejected deeper requests; content below depth \(depth) may be missing — re-run snapshot to retry deeper content."
       )
     }
     return parts.isEmpty ? nil : parts.joined(separator: " ")

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

@@ -1,24 +1,4 @@
 import XCTest
 
 extension RunnerTests {
-  func testSnapshotTraversalIdentityPreservesSameOriginNodesWithDifferentBounds() {
-    let wrapper = Self.snapshotTraversalIdentity(
-      elementType: .other,
-      label: "Article",
-      identifier: "",
-      frame: CGRect(x: 0, y: 97, width: 393, height: 48)
-    )
-    let leaf = Self.snapshotTraversalIdentity(
-      elementType: .other,
-      label: "Article",
-      identifier: "",
-      frame: CGRect(x: 0, y: 97, width: 131, height: 48)
-    )
-
-    #if os(iOS)
-    XCTAssertNotEqual(wrapper, leaf)
-    #else
-    XCTAssertEqual(wrapper, leaf)
-    #endif
-  }
 }

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

@@ -101,6 +101,10 @@ func synthesizedGesturePolicy(_ kind: SynthesizedGesturePolicyKind) -> Synthesiz
   }
 }
 
+func shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: Bool) -> Bool {
+  !xCTestChannelPenalized
+}
+
 func sequenceHasSynthesizedCoordinateStep(_ steps: [SequenceStep]) -> Bool {
   steps.contains { step in
     step.synthesized == true && step.kind == "tap"

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

@@ -0,0 +1,234 @@
+import XCTest
+
+// AX-independent text synthesis: private-XCTest boundary, pacing plan, and route policy.
+// The verified XCUIElement path remains in TextEntry/TextTyping.
+extension RunnerTests {
+  enum SynthesizedReplacementRouteOutcome {
+    case notApplicable
+    case completed(TextEntryResult)
+    case fallback(TextEntryTarget)
+  }
+
+  struct SynthesizedReplacementRequest {
+    let app: XCUIApplication
+    let target: TextEntryTarget
+    let text: String
+    let delaySeconds: Double
+    let synthesizer: any TextEntrySynthesizing
+    let commandId: String?
+    let startedAt: Date
+  }
+
+  enum SynthesizedTextEntryAction: Equatable {
+    case continueTyping
+    case fallback
+    case raise(String?)
+  }
+
+  protocol TextEntrySynthesizing {
+    func enterText(
+      app: XCUIApplication,
+      text: String,
+      replacingExistingText: Bool
+    ) -> SynthesizedTextEntryAction
+  }
+
+  struct PrivateXCTestTextEntrySynthesizer: TextEntrySynthesizing {
+    func enterText(
+      app: XCUIApplication,
+      text: String,
+      replacingExistingText: Bool
+    ) -> SynthesizedTextEntryAction {
+#if os(iOS)
+      let result = replacingExistingText
+        ? RunnerSynthesizedTextEntry.replaceText(withApplication: app, text: text)
+        : RunnerSynthesizedTextEntry.synthesizeText(withApplication: app, text: text)
+      return Self.action(status: result.status, message: result.message)
+#else
+      return .fallback
+#endif
+    }
+
+#if os(iOS)
+    static func action(
+      status: RunnerSynthesizedTextEntryStatus,
+      message: String?
+    ) -> SynthesizedTextEntryAction {
+      switch status {
+      case .succeeded:
+        return .continueTyping
+      case .unavailable:
+        return .fallback
+      case .failed:
+        return .raise(message)
+      @unknown default:
+        return .raise(message)
+      }
+    }
+#endif
+  }
+
+  struct SynthesizedReplacementStep: Equatable {
+    let text: String
+    let replacesExistingText: Bool
+  }
+
+  static func synthesizedReplacementSteps(
+    text: String,
+    delaySeconds: Double
+  ) -> [SynthesizedReplacementStep] {
+    let characters = Array(text)
+    guard delaySeconds > 0, characters.count > 1 else {
+      return [SynthesizedReplacementStep(text: text, replacesExistingText: true)]
+    }
+    return characters.enumerated().map { index, character in
+      SynthesizedReplacementStep(
+        text: String(character),
+        replacesExistingText: index == 0
+      )
+    }
+  }
+
+  func runSynthesizedReplacementRoute(
+    _ request: SynthesizedReplacementRequest
+  ) -> SynthesizedReplacementRouteOutcome {
+#if os(iOS)
+    NSLog("AGENT_DEVICE_RUNNER_TEXT_ENTRY_ROUTE route=synthesized-first-responder-replacement")
+    let steps = Self.synthesizedReplacementSteps(
+      text: request.text,
+      delaySeconds: request.delaySeconds
+    )
+    for (index, step) in steps.enumerated() {
+      switch request.synthesizer.enterText(
+        app: request.app,
+        text: step.text,
+        replacingExistingText: step.replacesExistingText
+      ) {
+      case .fallback:
+        NSLog("AGENT_DEVICE_RUNNER_TEXT_ENTRY_ROUTE route=verified-fallback reason=synthesis-unavailable")
+        guard let point = request.target.refreshPoint else { return .notApplicable }
+        return .fallback(
+          focusTextInputForTextEntry(app: request.app, x: point.x, y: point.y)
+        )
+      case .raise(let message):
+        NSException(
+          name: NSExceptionName.internalInconsistencyException,
+          reason: message ?? "private XCTest text synthesis failed"
+        ).raise()
+      case .continueTyping:
+        break
+      }
+      if index + 1 < steps.count {
+        sleepFor(request.delaySeconds)
+      }
+    }
+    logTextEntryPhase(
+      commandId: request.commandId,
+      phase: "total",
+      startedAt: request.startedAt,
+      chars: request.text.count,
+      mode: .replacement
+    )
+    return .completed(
+      TextEntryResult(
+        verified: nil,
+        repaired: false,
+        expectedText: request.text,
+        observedText: nil,
+        textEntryRoute: "synthesized-first-responder-replacement"
+      )
+    )
+#else
+    return .notApplicable
+#endif
+  }
+
+  static func shouldUseSynthesizedFirstResponderReplacement(
+    hasResolvedElement: Bool,
+    hasRefreshPoint: Bool,
+    xCTestChannelPenalized: Bool
+  ) -> Bool {
+    !hasResolvedElement && hasRefreshPoint && xCTestChannelPenalized
+  }
+
+  static func shouldUseSynthesizedFirstResponderType(
+    repairMode: TextTypingRepairMode,
+    fromTapWitness: Bool,
+    softwareKeyboardVisible: Bool
+  ) -> Bool {
+    repairMode == .none && fromTapWitness && !softwareKeyboardVisible
+  }
+
+  enum SynthesizedTextCommitProgress: Equatable {
+    case committed
+    case pending
+    case diverged
+  }
+
+  // The private synthesize call returns once the event record is posted, not once the target
+  // app has committed the characters, so intermediate reads walk prefix-by-prefix toward the
+  // expected value. Anything off that prefix path means the app transformed the input
+  // (formatter, mid-text caret, autocomplete) and the runner must not second-guess it. An
+  // unreadable value — secure field, or the element stopped resolving — ends the wait the
+  // same way.
+  static func synthesizedTextCommitProgress(
+    observedText: String?,
+    expectedText: String
+  ) -> SynthesizedTextCommitProgress {
+    guard let observedText else {
+      return .diverged
+    }
+    if observedText == expectedText {
+      return .committed
+    }
+    return expectedText.hasPrefix(observedText) ? .pending : .diverged
+  }
+
+  /// Blocks until the synthesized bare-type text is observable in the target field, so `type`
+  /// cannot report ok while trailing characters are still uncommitted on a slow simulator.
+  ///
+  /// Observation only. A stalled prefix cannot be told apart from a suffix still queued in the
+  /// event stream, so re-synthesizing the difference risks committing it twice after the command
+  /// already reported success. Text carrying a submit key is skipped outright: the app may clear
+  /// or rewrite the field on submit, so `textBefore + typedText` is not the value to wait for.
+  func awaitSynthesizedFirstResponderCommit(
+    app: XCUIApplication,
+    target: TextEntryTarget,
+    textBefore: String?,
+    typedText: String
+  ) {
+    guard let textBefore, !typedText.contains("\n"), !typedText.contains("\r") else {
+      return
+    }
+    let expectedText = textBefore + typedText
+    let deadline = Date().addingTimeInterval(TextEntryTiming.synthesizedCommitTimeout)
+    while Date() < deadline {
+      let observedText = editableTextValue(
+        for: resolveTextEntryElement(app: app, target: target),
+        treatingPlaceholderAsEmpty: true
+      )
+      switch Self.synthesizedTextCommitProgress(observedText: observedText, expectedText: expectedText) {
+      case .committed, .diverged:
+        return
+      case .pending:
+        sleepFor(TextEntryTiming.pollInterval)
+      }
+    }
+  }
+
+  static func shouldUseResolvedCoordinateTextEntryRoute(
+    repairMode: TextTypingRepairMode,
+    hasX: Bool,
+    hasY: Bool,
+    xCTestChannelPenalized: Bool
+  ) -> Bool {
+    repairMode == .replacement && hasX && hasY && xCTestChannelPenalized
+  }
+
+  static func shouldFallbackFromSynthesizedTextEntryFocus(
+    _ outcome: RunnerInteractionOutcome
+  ) -> Bool {
+    if case .unsupported = outcome { return true }
+    return false
+  }
+}