mcp-baepsae 5.1.0 → 6.2.0

package/native/Sources/Utils.swift

@@ -15,6 +15,7 @@ let supportedCommands: Set<String> = [
     "describe-ui",
     "search-ui",
     "tap",
+    "tap-tab",
     "type",
     "swipe",
     "button",
@@ -25,6 +26,7 @@ let supportedCommands: Set<String> = [
     "gesture",
     "stream-video",
     "list-apps",
+    "doctor",
     "list-windows",
     "activate-app",
     "screenshot-app",
@@ -52,6 +54,11 @@ func parse(arguments: [String]) throws -> ParsedOptions {
     var flags: Set<String> = []
     var positionals: [String] = []
 
+    func looksLikeNegativeNumber(_ value: String) -> Bool {
+        let pattern = #"^-\d+(\.\d+)?$"#
+        return value.range(of: pattern, options: .regularExpression) != nil
+    }
+
     var index = 1
     while index < arguments.count {
         let item = arguments[index]
@@ -60,14 +67,14 @@ func parse(arguments: [String]) throws -> ParsedOptions {
                 let key = String(item[..<separator])
                 let value = String(item[item.index(after: separator)...])
                 options[key] = value
-            } else if index + 1 < arguments.count, !arguments[index + 1].hasPrefix("-") {
+            } else if index + 1 < arguments.count, (!arguments[index + 1].hasPrefix("-") || looksLikeNegativeNumber(arguments[index + 1])) {
                 options[item] = arguments[index + 1]
                 index += 1
             } else {
                 flags.insert(item)
             }
         } else if item.hasPrefix("-") {
-            if index + 1 < arguments.count, !arguments[index + 1].hasPrefix("-") {
+            if index + 1 < arguments.count, (!arguments[index + 1].hasPrefix("-") || looksLikeNegativeNumber(arguments[index + 1])) {
                 options[item] = arguments[index + 1]
                 index += 1
             } else {
@@ -132,10 +139,27 @@ func readFileText(_ path: String) throws -> String {
 // MARK: - Process Execution
 
 @discardableResult
-func runProcess(_ command: String, _ arguments: [String]) throws -> Int32 {
+func runProcess(_ command: String, _ arguments: [String], stdinText: String? = nil) throws -> Int32 {
     let process = Process()
     process.executableURL = URL(fileURLWithPath: command)
     process.arguments = arguments
+    if let stdinText {
+        let pipe = Pipe()
+        process.standardInput = pipe
+        process.standardOutput = FileHandle.standardOutput
+        process.standardError = FileHandle.standardError
+        do {
+            try process.run()
+        } catch {
+            throw NativeError.commandFailed("Failed to launch process: \(command) \(arguments.joined(separator: " "))")
+        }
+        if let data = stdinText.data(using: .utf8) {
+            pipe.fileHandleForWriting.write(data)
+        }
+        pipe.fileHandleForWriting.closeFile()
+        process.waitUntilExit()
+        return process.terminationStatus
+    }
     process.standardInput = FileHandle.standardInput
     process.standardOutput = FileHandle.standardOutput
     process.standardError = FileHandle.standardError
@@ -235,6 +259,11 @@ func requireSimulatorUdid(_ target: TargetApp) throws -> String {
     return udid
 }
 
+func simulatorUdid(from target: TargetApp) -> String? {
+    guard case .simulator(let udid) = target else { return nil }
+    return udid
+}
+
 // MARK: - Accessibility Helpers
 
 func ensureAccessibilityTrusted() throws {
@@ -276,6 +305,24 @@ func simulatorAccessibilityRootElement() throws -> UIElement {
     return appElement
 }
 
+func shellCaptureCommand(_ command: String, _ arguments: [String]) -> String? {
+    let process = Process()
+    process.executableURL = URL(fileURLWithPath: command)
+    process.arguments = arguments
+    let pipe = Pipe()
+    process.standardOutput = pipe
+    process.standardError = FileHandle.nullDevice
+    do {
+        try process.run()
+        process.waitUntilExit()
+        guard process.terminationStatus == 0 else { return nil }
+        let data = pipe.fileHandleForReading.readDataToEndOfFile()
+        return String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines)
+    } catch {
+        return nil
+    }
+}
+
 func CopyAttributeValue(_ element: UIElement, _ attribute: CFString) -> CFTypeRef? {
     var value: CFTypeRef?
     let status = AXUIElementCopyAttributeValue(element, attribute, &value)
@@ -410,6 +457,24 @@ func IdentifierAttribute(_ element: UIElement) -> String? {
     return StringAttribute(element, "AXIdentifier" as CFString)
 }
 
+func performPrimaryAction(on element: UIElement) throws {
+    let actions = ActionNames(element)
+    if actions.contains(kAXPressAction as String) {
+        let status = AXUIElementPerformAction(element, kAXPressAction as CFString)
+        if status != .success {
+            throw NativeError.commandFailed("Matched accessibility element but AXPress failed with status \(status.rawValue).")
+        }
+        return
+    }
+
+    if let frame = FrameAttribute(element) {
+        sendClick(at: CGPoint(x: frame.midX, y: frame.midY))
+        return
+    }
+
+    throw NativeError.commandFailed("Matched accessibility element has no AXPress action or frame for fallback click.")
+}
+
 // MARK: - Text Helpers
 
 func normalizeText(_ value: String) -> String {
@@ -516,6 +581,98 @@ func describeAccessibilityElement(_ element: UIElement, includeEmpty: Bool = tru
     return parts.joined(separator: " ")
 }
 
+func actionableTabBarItems(in tabBar: UIElement, maxDepth: Int = 2) -> [UIElement] {
+    var stack: [(element: UIElement, depth: Int)] = Children(tabBar).map { ($0, 1) }.reversed()
+    var matches: [UIElement] = []
+
+    while let current = stack.popLast() {
+        let role = StringAttribute(current.element, kAXRoleAttribute as CFString) ?? ""
+        let actions = ActionNames(current.element)
+        let hasFrame = FrameAttribute(current.element) != nil
+        let isLikelyTabItem =
+            role == "AXButton" ||
+            role == "AXRadioButton" ||
+            role == "AXCheckBox" ||
+            actions.contains(kAXPressAction as String)
+
+        if isLikelyTabItem && hasFrame {
+            if !matches.contains(where: { elementsAreEqual($0, current.element) }) {
+                matches.append(current.element)
+            }
+        }
+
+        if current.depth < maxDepth {
+            for child in Children(current.element).reversed() {
+                stack.append((child, current.depth + 1))
+            }
+        }
+    }
+
+    return matches.sorted {
+        (FrameAttribute($0)?.midX ?? 0) < (FrameAttribute($1)?.midX ?? 0)
+    }
+}
+
+func semanticProxyTabButtons(in contentRoot: UIElement, excluding excludedElement: UIElement? = nil, expectedCount: Int) -> [UIElement] {
+    guard expectedCount > 0 else { return [] }
+    guard let contentFrame = FrameAttribute(contentRoot) else { return [] }
+    let excludedFrame = excludedElement.flatMap(FrameAttribute)
+
+    let directChildren = Children(contentRoot)
+    let candidates = directChildren.filter { child in
+        let role = StringAttribute(child, kAXRoleAttribute as CFString) ?? ""
+        let actions = ActionNames(child)
+        guard let frame = FrameAttribute(child) else { return false }
+        if let excludedFrame, excludedFrame.contains(frame) {
+            return false
+        }
+        guard frame.midY < contentFrame.origin.y + contentFrame.height * 0.55 else {
+            return false
+        }
+        guard frame.width < contentFrame.width * 0.8 else {
+            return false
+        }
+        return role == "AXButton" || actions.contains(kAXPressAction as String)
+    }
+
+    guard !candidates.isEmpty else { return [] }
+
+    struct RowGroup {
+        var meanY: CGFloat
+        var elements: [UIElement]
+    }
+
+    var rows: [RowGroup] = []
+    let tolerance: CGFloat = 24
+    for element in candidates.sorted(by: { (FrameAttribute($0)?.midY ?? 0) < (FrameAttribute($1)?.midY ?? 0) }) {
+        let midY = FrameAttribute(element)?.midY ?? 0
+        if let rowIndex = rows.firstIndex(where: { abs($0.meanY - midY) <= tolerance }) {
+            rows[rowIndex].elements.append(element)
+            let count = CGFloat(rows[rowIndex].elements.count)
+            rows[rowIndex].meanY = ((rows[rowIndex].meanY * (count - 1)) + midY) / count
+        } else {
+            rows.append(RowGroup(meanY: midY, elements: [element]))
+        }
+    }
+
+    guard let bestRow = rows.sorted(by: {
+        if $0.elements.count == $1.elements.count {
+            return $0.meanY < $1.meanY
+        }
+        return $0.elements.count > $1.elements.count
+    }).first else {
+        return []
+    }
+
+    guard bestRow.elements.count == expectedCount else {
+        return []
+    }
+
+    return bestRow.elements.sorted {
+        (FrameAttribute($0)?.midX ?? 0) < (FrameAttribute($1)?.midX ?? 0)
+    }
+}
+
 func describeAccessibilityTree(from root: UIElement, options: DescribeOptions = DescribeOptions()) -> [String] {
     var lines: [String] = []
     var stack: [(element: UIElement, depth: Int)] = [(root, 0)]
@@ -590,6 +747,20 @@ func describeAccessibilityTree(from root: UIElement, options: DescribeOptions =
                     lines.append("\(prefix)- [hidden: no accessible content]")
                 }
                 emitted += 1
+                // Add hint for tab bar elements with unlabeled children
+                let attrs2 = copyMultipleAttributes(element, [kAXRoleAttribute as String])
+                if let roleRef = attrs2[kAXRoleAttribute as String], let role = stringFromCFTypeRef(roleRef),
+                   role == "AXTabGroup" || role == "AXRadioGroup" {
+                    let tabChildren = Children(element)
+                    let unlabeledCount = tabChildren.filter { child in
+                        let childTexts = getElementTextValues(child)
+                        return childTexts.isEmpty
+                    }.count
+                    if unlabeledCount > 0 && unlabeledCount == tabChildren.count {
+                        let hint = "\(prefix)  [Tab bar with \(tabChildren.count) unlabeled items - use tap_tab with index 0..\(tabChildren.count - 1)]"
+                        lines.append(hint)
+                    }
+                }
             }
         }
 
@@ -701,6 +872,21 @@ func findAccessibilityElement(
     return nil
 }
 
+func findAccessibilityElement(
+    in roots: [UIElement],
+    identifier: String?,
+    label: String?,
+    maxDepth: Int = Int.max,
+    maxNodes: Int = Int.max
+) -> UIElement? {
+    for root in roots {
+        if let match = findAccessibilityElement(in: root, identifier: identifier, label: label, maxDepth: maxDepth, maxNodes: maxNodes) {
+            return match
+        }
+    }
+    return nil
+}
+
 func searchAccessibilityElements(in root: UIElement, query: String, options: SearchOptions = SearchOptions()) -> [String] {
     var results: [String] = []
     var stack: [(element: UIElement, depth: Int)] = [(root, 0)]
@@ -789,6 +975,14 @@ func searchAccessibilityElements(in root: UIElement, query: String, options: Sea
     return results
 }
 
+func searchAccessibilityElements(in roots: [UIElement], query: String, options: SearchOptions = SearchOptions()) -> [String] {
+    var results: [String] = []
+    for root in roots {
+        results.append(contentsOf: searchAccessibilityElements(in: root, query: query, options: options))
+    }
+    return results
+}
+
 func findElementBySubrole(from root: UIElement, subrole: String) -> UIElement? {
     var stack: [UIElement] = [root]
     var visited = 0
@@ -808,16 +1002,328 @@ func findElementBySubrole(from root: UIElement, subrole: String) -> UIElement? {
     return nil
 }
 
-func simulatorContentRootElement(from appRoot: UIElement) -> UIElement? {
+func simulatorDeviceName(for udid: String?) -> String? {
+    guard let udid, !udid.isEmpty else { return nil }
+    return shellCaptureCommand("/usr/bin/xcrun", ["simctl", "getenv", udid, "SIMULATOR_DEVICE_NAME"])
+}
+
+func simulatorWindowTitle(_ element: UIElement) -> String? {
+    return StringAttribute(element, kAXTitleAttribute as CFString)
+        ?? StringAttribute(element, kAXDescriptionAttribute as CFString)
+        ?? StringAttribute(element, kAXValueAttribute as CFString)
+}
+
+func simulatorWindowElement(from appRoot: UIElement, udid: String? = nil) -> UIElement? {
+    let windows = Children(appRoot).filter { element in
+        let attrs = copyMultipleAttributes(element, [kAXRoleAttribute as String])
+        if let ref = attrs[kAXRoleAttribute as String], let role = stringFromCFTypeRef(ref) {
+            return role == "AXWindow"
+        }
+        return false
+    }
+
+    guard !windows.isEmpty else { return nil }
+
+    let normalizedDeviceName = simulatorDeviceName(for: udid).map(normalizeText)
+    let preferredWindows: [UIElement]
+    if let normalizedDeviceName {
+        let matched = windows.filter { window in
+            guard let title = simulatorWindowTitle(window) else { return false }
+            return normalizeText(title).contains(normalizedDeviceName)
+        }
+        preferredWindows = matched.isEmpty ? windows : matched
+    } else {
+        preferredWindows = windows
+    }
+
+    var bestWindow: UIElement?
+    var bestArea: CGFloat = 0
+    for window in preferredWindows {
+        let area = FrameAttribute(window).map { $0.width * $0.height } ?? 0
+        if bestWindow == nil || area > bestArea {
+            bestWindow = window
+            bestArea = area
+        }
+    }
+    return bestWindow
+}
+
+func simulatorContentRootElement(from appRoot: UIElement, udid: String? = nil) -> UIElement? {
+    if let scopedWindow = simulatorWindowElement(from: appRoot, udid: udid),
+       let scopedContentRoot = findElementBySubrole(from: scopedWindow, subrole: "iOSContentGroup") {
+        return scopedContentRoot
+    }
     return findElementBySubrole(from: appRoot, subrole: "iOSContentGroup")
 }
 
+struct SimulatorAuxiliaryContainerCandidate {
+    let element: UIElement
+    let label: String
+}
+
+func elementsAreEqual(_ lhs: UIElement, _ rhs: UIElement) -> Bool {
+    CFEqual(lhs, rhs)
+}
+
+func collectElements(
+    in root: UIElement,
+    matching predicate: (UIElement, Int) -> Bool,
+    maxVisited: Int = 500,
+    maxMatches: Int = 8
+) -> [UIElement] {
+    var stack: [(element: UIElement, depth: Int)] = [(root, 0)]
+    var visited = 0
+    var matches: [UIElement] = []
+
+    while let current = stack.popLast() {
+        if visited >= maxVisited || matches.count >= maxMatches {
+            break
+        }
+        visited += 1
+
+        if predicate(current.element, current.depth) {
+            matches.append(current.element)
+        }
+
+        for child in Children(current.element).reversed() {
+            stack.append((child, current.depth + 1))
+        }
+    }
+
+    return matches
+}
+
+func collectElementsByRole(in root: UIElement, role: String, maxMatches: Int = 4) -> [UIElement] {
+    collectElements(
+        in: root,
+        matching: { element, _ in
+            let attrs = copyMultipleAttributes(element, [kAXRoleAttribute as String])
+            if let ref = attrs[kAXRoleAttribute as String], let value = stringFromCFTypeRef(ref) {
+                return value == role
+            }
+            return false
+        },
+        maxMatches: maxMatches
+    )
+}
+
+func collectWideAuxiliaryGroups(in root: UIElement, contentRootFrame: CGRect? = nil, maxMatches: Int = 4) -> [UIElement] {
+    guard let mainScreen = NSScreen.main else { return [] }
+    let screenWidth = mainScreen.frame.width
+    let screenHeight = mainScreen.frame.height
+    let topThreshold = screenHeight * 0.20
+    let bottomThreshold = screenHeight * 0.20
+
+    return collectElements(
+        in: root,
+        matching: { element, _ in
+            let attrs = copyMultipleAttributes(element, [kAXRoleAttribute as String, "AXFrame"])
+            guard let ref = attrs[kAXRoleAttribute as String], let role = stringFromCFTypeRef(ref), role == "AXGroup" else {
+                return false
+            }
+            guard let frameRef = attrs["AXFrame"], let frame = frameFromCFTypeRef(frameRef) else {
+                return false
+            }
+            guard frame.width > screenWidth * 0.6 else {
+                return false
+            }
+            guard frame.origin.y < topThreshold || frame.origin.y > screenHeight - bottomThreshold else {
+                return false
+            }
+            if let contentRootFrame, contentRootFrame.contains(frame) {
+                return false
+            }
+            return Children(element).count >= 2
+        },
+        maxMatches: maxMatches
+    )
+}
+
+func simulatorAuxiliaryContainerCandidates(from appRoot: UIElement, excluding contentRoot: UIElement? = nil, udid: String? = nil) -> [SimulatorAuxiliaryContainerCandidate] {
+    let scopeRoot = simulatorWindowElement(from: appRoot, udid: udid) ?? appRoot
+    let contentRootFrame = contentRoot.flatMap(FrameAttribute)
+    let roleCandidates: [(role: String, label: String)] = [
+        ("AXTabGroup", "tab bar"),
+        ("AXRadioGroup", "radio group"),
+        ("AXSegmentedControl", "segmented control"),
+        ("AXToolbar", "toolbar"),
+    ]
+
+    var candidates: [SimulatorAuxiliaryContainerCandidate] = []
+
+    func appendCandidate(_ element: UIElement, label: String) {
+        if let contentRoot, elementsAreEqual(element, contentRoot) {
+            return
+        }
+        if let candidateFrame = FrameAttribute(element), let contentRootFrame, contentRootFrame.contains(candidateFrame) {
+            return
+        }
+        if candidates.contains(where: { elementsAreEqual($0.element, element) }) {
+            return
+        }
+        candidates.append(SimulatorAuxiliaryContainerCandidate(element: element, label: label))
+    }
+
+    for roleCandidate in roleCandidates {
+        for element in collectElementsByRole(in: scopeRoot, role: roleCandidate.role) {
+            appendCandidate(element, label: roleCandidate.label)
+        }
+    }
+
+    for element in collectWideAuxiliaryGroups(in: scopeRoot, contentRootFrame: contentRootFrame) {
+        appendCandidate(element, label: "auxiliary group")
+    }
+
+    return candidates
+}
+
+func simulatorAuxiliaryContainerLabels(from appRoot: UIElement, excluding contentRoot: UIElement? = nil, udid: String? = nil) -> [String] {
+    simulatorAuxiliaryContainerCandidates(from: appRoot, excluding: contentRoot, udid: udid).map(\.label)
+}
+
+func formatSimulatorAuxiliaryContainerHint(_ labels: [String]) -> String? {
+    var seen: Set<String> = []
+    let uniqueLabels = labels.filter { label in
+        let normalized = label.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalized.isEmpty else { return false }
+        return seen.insert(normalized).inserted
+    }
+    guard !uniqueLabels.isEmpty else {
+        return nil
+    }
+    let containerList = uniqueLabels.joined(separator: ", ")
+    return "[Hint] Simulator auxiliary containers outside iOSContentGroup: \(containerList). Use --all to inspect Simulator chrome UI."
+}
+
+func simulatorSelectorNotFoundMessage(selectorText: String, auxiliaryLabels: [String]) -> String {
+    if let hint = formatSimulatorAuxiliaryContainerHint(auxiliaryLabels) {
+        return "No accessibility element matched \(selectorText) in simulator app content or auxiliary containers. \(hint)"
+    }
+    return "No accessibility element matched \(selectorText) in simulator app content. Try --all to include Simulator chrome UI."
+}
+
+func findTabBarElement(in root: UIElement, simulatorUdid: String? = nil) -> UIElement? {
+    // 1st pass: Look for AXTabGroup
+    var stack: [UIElement] = [root]
+    var visited = 0
+    while let current = stack.popLast() {
+        if visited > 500 { break }
+        visited += 1
+
+        let attrs = copyMultipleAttributes(current, [kAXRoleAttribute as String])
+        if let ref = attrs[kAXRoleAttribute as String], let role = stringFromCFTypeRef(ref), role == "AXTabGroup" {
+            return current
+        }
+        for child in Children(current).reversed() {
+            stack.append(child)
+        }
+    }
+
+    // 2nd pass: Look for AXRadioGroup
+    stack = [root]
+    visited = 0
+    while let current = stack.popLast() {
+        if visited > 500 { break }
+        visited += 1
+
+        let attrs = copyMultipleAttributes(current, [kAXRoleAttribute as String])
+        if let ref = attrs[kAXRoleAttribute as String], let role = stringFromCFTypeRef(ref), role == "AXRadioGroup" {
+            return current
+        }
+        for child in Children(current).reversed() {
+            stack.append(child)
+        }
+    }
+
+    // 3rd pass: Simulator-specific heuristic — look for a wide bottom group
+    // inside iOSContentGroup. SwiftUI TabView on Simulator frequently exposes
+    // the tab bar as AXGroup text="Tab Bar" rather than AXTabGroup.
+    if let contentRoot = simulatorContentRootElement(from: root, udid: simulatorUdid),
+       let contentFrame = FrameAttribute(contentRoot) {
+        let bottomThresholdY = contentFrame.origin.y + contentFrame.height * 0.65
+        stack = [contentRoot]
+        visited = 0
+        while let current = stack.popLast() {
+            if visited > 800 { break }
+            visited += 1
+
+            let attrs = copyMultipleAttributes(current, [
+                kAXRoleAttribute as String,
+                "AXFrame",
+                "AXLabel",
+                kAXTitleAttribute as String,
+                kAXDescriptionAttribute as String,
+                kAXValueAttribute as String,
+            ])
+
+            if let ref = attrs[kAXRoleAttribute as String],
+               let role = stringFromCFTypeRef(ref),
+               role == "AXGroup",
+               let frameRef = attrs["AXFrame"],
+               let frame = frameFromCFTypeRef(frameRef) {
+                let textCandidates = [
+                    attrs["AXLabel"],
+                    attrs[kAXTitleAttribute as String],
+                    attrs[kAXDescriptionAttribute as String],
+                    attrs[kAXValueAttribute as String],
+                ].compactMap { $0 }.compactMap(stringFromCFTypeRef)
+
+                let hasExplicitTabBarText = textCandidates.contains { candidate in
+                    normalizeText(candidate).contains("tab bar")
+                }
+
+                let isWide = frame.width >= contentFrame.width * 0.60
+                let isNearBottom = frame.origin.y >= bottomThresholdY && frame.maxY <= contentFrame.maxY + 8
+                let plausibleBarHeight = frame.height >= 32 && frame.height <= 140
+
+                if hasExplicitTabBarText || (isWide && isNearBottom && plausibleBarHeight) {
+                    return current
+                }
+            }
+
+            for child in Children(current).reversed() {
+                stack.append(child)
+            }
+        }
+    }
+
+    // 4th pass: Generic heuristic — wide AXGroup in bottom 15% of screen
+    guard let mainScreen = NSScreen.main else { return nil }
+    let screenHeight = mainScreen.frame.height
+    let bottomThreshold = screenHeight * 0.15
+
+    stack = [root]
+    visited = 0
+    while let current = stack.popLast() {
+        if visited > 500 { break }
+        visited += 1
+
+        let attrs = copyMultipleAttributes(current, [kAXRoleAttribute as String, "AXFrame"])
+        if let ref = attrs[kAXRoleAttribute as String], let role = stringFromCFTypeRef(ref), role == "AXGroup" {
+            if let frameRef = attrs["AXFrame"], let frame = frameFromCFTypeRef(frameRef) {
+                // AXFrame uses screen coordinates with origin at top-left.
+                // A tab bar near the bottom of the screen has a high y value.
+                // We check if the element is wide (>60% of screen width) and in the bottom 15%.
+                let screenWidth = mainScreen.frame.width
+                if frame.width > screenWidth * 0.6 && frame.origin.y > screenHeight - bottomThreshold {
+                    return current
+                }
+            }
+        }
+        for child in Children(current).reversed() {
+            stack.append(child)
+        }
+    }
+
+    return nil
+}
+
 // MARK: - Window / Coordinate Helpers
 
 func windowBounds(for target: TargetApp) -> CGRect? {
     switch target {
-    case .simulator:
-        return simulatorWindowBounds()
+    case .simulator(let udid):
+        return simulatorWindowBounds(udid: udid)
     case .macApp(let pid, _, _):
         guard let windowInfo = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID)
             as? [[String: Any]] else {
@@ -849,7 +1355,7 @@ func windowBounds(for target: TargetApp) -> CGRect? {
     }
 }
 
-func simulatorWindowBounds() -> CGRect? {
+func simulatorWindowBounds(udid: String? = nil) -> CGRect? {
     guard let windowInfo = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID)
         as? [[String: Any]] else {
         return nil
@@ -861,9 +1367,21 @@ func simulatorWindowBounds() -> CGRect? {
         return owner == "Simulator" && (layer ?? 0) == 0
     }
 
+    let normalizedDeviceName = simulatorDeviceName(for: udid).map(normalizeText)
+    let preferredWindows: [[String: Any]]
+    if let normalizedDeviceName {
+        let matched = windows.filter { info in
+            let title = (info[kCGWindowName as String] as? String) ?? ""
+            return normalizeText(title).contains(normalizedDeviceName)
+        }
+        preferredWindows = matched.isEmpty ? windows : matched
+    } else {
+        preferredWindows = windows
+    }
+
     var best: CGRect?
     var bestArea: CGFloat = 0
-    for info in windows {
+    for info in preferredWindows {
         guard let boundsDict = info[kCGWindowBounds as String] as? [String: Any],
               let x = boundsDict["X"] as? CGFloat,
               let y = boundsDict["Y"] as? CGFloat,
@@ -883,8 +1401,8 @@ func simulatorWindowBounds() -> CGRect? {
 
 func pointInWindow(x: Double, y: Double, for target: TargetApp) throws -> CGPoint {
     switch target {
-    case .simulator:
-        return try pointInSimulatorWindow(x: x, y: y)
+    case .simulator(let udid):
+        return try pointInSimulatorWindow(x: x, y: y, udid: udid)
     case .macApp:
         guard let bounds = windowBounds(for: target) else {
             throw NativeError.commandFailed("Application window not found. Ensure the app is running and visible.")
@@ -895,15 +1413,67 @@ func pointInWindow(x: Double, y: Double, for target: TargetApp) throws -> CGPoin
     }
 }
 
-func pointInSimulatorWindow(x: Double, y: Double) throws -> CGPoint {
-    guard let bounds = simulatorWindowBounds() else {
+func pointInSimulatorWindow(x: Double, y: Double, udid: String? = nil) throws -> CGPoint {
+    guard let bounds = simulatorWindowBounds(udid: udid) else {
         throw NativeError.commandFailed("Simulator window not found. Ensure Simulator is running and visible.")
     }
     let targetX = bounds.origin.x + CGFloat(x)
-    let targetY = bounds.origin.y + bounds.size.height - CGFloat(y)
+    let targetY = bounds.origin.y + CGFloat(y)
     return CGPoint(x: targetX, y: targetY)
 }
 
+// MARK: - Simulator Content Bounds
+
+func simulatorContentBounds(udid: String? = nil) -> CGRect? {
+    guard let appRoot = try? simulatorAccessibilityRootElement() else {
+        return simulatorWindowBounds(udid: udid)
+    }
+    if let contentGroup = simulatorContentRootElement(from: appRoot, udid: udid),
+       let frame = FrameAttribute(contentGroup) {
+        return frame
+    }
+    return simulatorWindowBounds(udid: udid)
+}
+
+func pointInSimulatorContent(x: Double, y: Double, udid: String? = nil) throws -> CGPoint {
+    guard let bounds = simulatorContentBounds(udid: udid) else {
+        throw NativeError.commandFailed("Simulator content area not found. Ensure Simulator is running and visible.")
+    }
+    let targetX = bounds.origin.x + CGFloat(x)
+    let targetY = bounds.origin.y + CGFloat(y)
+    return CGPoint(x: targetX, y: targetY)
+}
+
+func pointForInput(x: Double, y: Double, for target: TargetApp) throws -> CGPoint {
+    switch target {
+    case .simulator(let udid):
+        return try pointInSimulatorContent(x: x, y: y, udid: udid)
+    case .macApp:
+        return try pointInWindow(x: x, y: y, for: target)
+    }
+}
+
+func simulatorScrollAnchorPoint(x: Double?, y: Double?, udid: String? = nil) throws -> CGPoint {
+    if let x, let y {
+        return CGPoint(x: x, y: y)
+    }
+    guard let bounds = simulatorContentBounds(udid: udid) else {
+        throw NativeError.commandFailed("Simulator content area not found. Ensure Simulator is running and visible.")
+    }
+    return CGPoint(x: bounds.width * 0.5, y: bounds.height * 0.5)
+}
+
+func simulatorScrollDistance(deltaX: Double, deltaY: Double) -> CGSize {
+    func component(for delta: Double) -> CGFloat {
+        guard delta != 0 else { return 0 }
+        let magnitude = min(max(abs(delta) * 18.0, 90.0), 320.0)
+        let sign: CGFloat = delta < 0 ? -1 : 1
+        return CGFloat(magnitude) * sign
+    }
+
+    return CGSize(width: component(for: deltaX), height: component(for: deltaY))
+}
+
 // MARK: - App Activation
 
 func activateTarget(_ target: TargetApp) throws {
@@ -1000,6 +1570,43 @@ func sendSwipe(from start: CGPoint, to end: CGPoint, duration: Double?) {
     postMouseEvent(type: .leftMouseUp, point: end)
 }
 
+func sendDrag(from start: CGPoint, to end: CGPoint, holdDuration: Double, moveDuration: Double?) {
+    postMouseEvent(type: .leftMouseDown, point: start)
+    if holdDuration > 0 {
+        Thread.sleep(forTimeInterval: holdDuration)
+    }
+
+    // iOS drag & drop is often sensitive to the exact event sequence.
+    // Use a slightly larger warmup move so SwiftUI DragGesture reliably
+    // leaves the initial long-press state and enters an active drag.
+    let warmupOffset: CGFloat = 4.0
+    let warmupPoint = CGPoint(
+        x: start.x + (end.x >= start.x ? warmupOffset : -warmupOffset),
+        y: start.y + (end.y >= start.y ? warmupOffset : -warmupOffset)
+    )
+    postMouseEvent(type: .leftMouseDragged, point: warmupPoint)
+    if let moveDuration {
+        Thread.sleep(forTimeInterval: min(max(moveDuration / 24.0, 0.02), 0.06))
+    } else {
+        Thread.sleep(forTimeInterval: 0.05)
+    }
+
+    let steps = 18
+    for step in 1...steps {
+        let progress = CGFloat(step) / CGFloat(steps)
+        let x = start.x + (end.x - start.x) * progress
+        let y = start.y + (end.y - start.y) * progress
+        postMouseEvent(type: .leftMouseDragged, point: CGPoint(x: x, y: y))
+        if let moveDuration {
+            Thread.sleep(forTimeInterval: moveDuration / Double(steps))
+        } else {
+            Thread.sleep(forTimeInterval: 0.02)
+        }
+    }
+    Thread.sleep(forTimeInterval: 0.08)
+    postMouseEvent(type: .leftMouseUp, point: end)
+}
+
 // MARK: - Keyboard Events
 
 func sendKeyPress(keyCode: Int, duration: Double?) {
@@ -1046,6 +1653,39 @@ func sendText(_ text: String) {
     }
 }
 
+// MARK: - Input Backend
+
+enum InputBackend {
+    case cgevent
+    case indigoHID(IndigoHIDClient)
+}
+
+/// Resolve the input backend for the given target.
+/// For simulators: try IndigoHID first, fall back to CGEvent.
+/// For macOS apps: always use CGEvent.
+/// Override with BAEPSAE_INPUT_BACKEND=indigo|cgevent|auto
+func resolveInputBackend(for target: TargetApp) -> InputBackend {
+    let envOverride = ProcessInfo.processInfo.environment["BAEPSAE_INPUT_BACKEND"]?.lowercased()
+
+    switch target {
+    case .macApp:
+        return .cgevent
+    case .simulator(let udid):
+        if envOverride == "cgevent" {
+            return .cgevent
+        }
+
+        if let client = IndigoHIDClient(udid: udid) {
+            return .indigoHID(client)
+        }
+
+        if envOverride == "indigo" {
+            fputs("Warning: IndigoHID requested but not available, falling back to CGEvent\n", stderr)
+        }
+        return .cgevent
+    }
+}
+
 // MARK: - Misc Helpers
 
 func defaultOutputPath(prefix: String, ext: String) -> String {