mcp-baepsae 5.1.0 → 6.2.0

package/native/Sources/Commands/UICommands.swift

@@ -9,13 +9,15 @@ func handleDescribeUI(_ parsed: ParsedOptions) throws -> Int32 {
 
     let appRoot = try accessibilityRootElement(for: target)
     var targetRoot = appRoot
+    var usedSimulatorContentScope = false
 
     switch target {
-    case .simulator:
+    case .simulator(let udid):
         // Default behavior: Focus on in-app content group unless --all is specified
         if !parsed.flags.contains("--all") {
-            if let contentGroup = simulatorContentRootElement(from: appRoot) {
+            if let contentGroup = simulatorContentRootElement(from: appRoot, udid: udid) {
                 targetRoot = contentGroup
+                usedSimulatorContentScope = true
             }
         }
     case .macApp:
@@ -32,6 +34,7 @@ func handleDescribeUI(_ parsed: ParsedOptions) throws -> Int32 {
     if let focusId = parsed.options["--focus-id"] {
         if let found = findAccessibilityElement(in: appRoot, identifier: focusId, label: nil) {
             targetRoot = found
+            usedSimulatorContentScope = false
         } else {
             throw NativeError.commandFailed("Could not find element with id: \(focusId)")
         }
@@ -41,6 +44,7 @@ func handleDescribeUI(_ parsed: ParsedOptions) throws -> Int32 {
     if let rootElementId = parsed.options["--root-element-id"] {
         if let found = findAccessibilityElement(in: appRoot, identifier: rootElementId, label: nil) {
             targetRoot = found
+            usedSimulatorContentScope = false
         } else {
             throw NativeError.commandFailed("Could not find element with id: \(rootElementId)")
         }
@@ -68,10 +72,17 @@ func handleDescribeUI(_ parsed: ParsedOptions) throws -> Int32 {
         }
     }
 
-    let lines = describeAccessibilityTree(from: targetRoot, options: descOpts)
+    var lines = describeAccessibilityTree(from: targetRoot, options: descOpts)
     if lines.isEmpty {
         throw NativeError.commandFailed("No accessibility elements found.")
     }
+    if usedSimulatorContentScope {
+        let targetUdid = simulatorUdid(from: target)
+        let auxiliaryLabels = simulatorAuxiliaryContainerLabels(from: appRoot, excluding: targetRoot, udid: targetUdid)
+        if let hint = formatSimulatorAuxiliaryContainerHint(auxiliaryLabels) {
+            lines.append(hint)
+        }
+    }
     let report = lines.joined(separator: "\n")
 
     if let output = parsed.options["--output"] {
@@ -95,8 +106,10 @@ func handleSearchUI(_ parsed: ParsedOptions) throws -> Int32 {
 
     let appRoot = try accessibilityRootElement(for: target)
     var searchRoot = appRoot
-    if case .simulator = target {
-        if let contentGroup = simulatorContentRootElement(from: appRoot) {
+    var simulatorContentRoot: UIElement? = nil
+    if case .simulator(let udid) = target {
+        if let contentGroup = simulatorContentRootElement(from: appRoot, udid: udid) {
+            simulatorContentRoot = contentGroup
             searchRoot = contentGroup
         }
     }
@@ -117,7 +130,24 @@ func handleSearchUI(_ parsed: ParsedOptions) throws -> Int32 {
     }
 
     let results = searchAccessibilityElements(in: searchRoot, query: query, options: searchOpts)
-    if results.isEmpty {
+    if results.isEmpty, case .simulator = target, let simulatorContentRoot {
+        let targetUdid = simulatorUdid(from: target)
+        let auxiliaryCandidates = simulatorAuxiliaryContainerCandidates(from: appRoot, excluding: simulatorContentRoot, udid: targetUdid)
+        let auxiliaryResults = searchAccessibilityElements(
+            in: auxiliaryCandidates.map(\.element),
+            query: query,
+            options: searchOpts
+        )
+        if auxiliaryResults.isEmpty {
+            print("No elements found matching query: \(query) in simulator app content or auxiliary containers.")
+            if let hint = formatSimulatorAuxiliaryContainerHint(auxiliaryCandidates.map(\.label)) {
+                print(hint)
+            }
+        } else {
+            print("[Fallback] No matches in simulator content scope; searched auxiliary containers outside iOSContentGroup.")
+            print(auxiliaryResults.joined(separator: "\n"))
+        }
+    } else if results.isEmpty {
         print("No elements found matching query: \(query)")
     } else {
         print(results.joined(separator: "\n"))
@@ -142,15 +172,22 @@ func handleTap(_ parsed: ParsedOptions) throws -> Int32 {
         }
 
         let root = try accessibilityRootElement(for: target)
-        let searchRoot: UIElement
+        let targetUdid = simulatorUdid(from: target)
+        let simulatorContentRoot = simulatorContentRootElement(from: root, udid: targetUdid)
+        let searchRoots: [UIElement]
         if case .simulator = target, !includeAll {
-            searchRoot = simulatorContentRootElement(from: root) ?? root
+            if let contentRoot = simulatorContentRoot {
+                let auxiliaryRoots = simulatorAuxiliaryContainerCandidates(from: root, excluding: contentRoot, udid: targetUdid).map(\.element)
+                searchRoots = [contentRoot] + auxiliaryRoots
+            } else {
+                searchRoots = [root]
+            }
         } else {
-            searchRoot = root
+            searchRoots = [root]
         }
 
         guard let matchedElement = findAccessibilityElement(
-            in: searchRoot,
+            in: searchRoots,
             identifier: accessibilityId,
             label: accessibilityLabel
         ) else {
@@ -163,7 +200,10 @@ func handleTap(_ parsed: ParsedOptions) throws -> Int32 {
             }
             let selectorText = selectors.joined(separator: " and ")
             if case .simulator = target, !includeAll {
-                throw NativeError.commandFailed("No accessibility element matched \(selectorText) in simulator app content. Try --all to include Simulator chrome UI.")
+                let auxiliaryLabels = simulatorContentRoot.map {
+                    simulatorAuxiliaryContainerLabels(from: root, excluding: $0, udid: targetUdid)
+                } ?? []
+                throw NativeError.commandFailed(simulatorSelectorNotFoundMessage(selectorText: selectorText, auxiliaryLabels: auxiliaryLabels))
             }
             throw NativeError.commandFailed("No accessibility element matched \(selectorText).")
         }
@@ -174,18 +214,7 @@ func handleTap(_ parsed: ParsedOptions) throws -> Int32 {
             }
             sendDoubleClick(at: CGPoint(x: frame.midX, y: frame.midY))
         } else {
-            let actions = ActionNames(matchedElement)
-            if actions.contains(kAXPressAction as String) {
-                let status = AXUIElementPerformAction(matchedElement, kAXPressAction as CFString)
-                if status != .success {
-                    throw NativeError.commandFailed("Matched accessibility element but AXPress failed with status \(status.rawValue).")
-                }
-            } else if let frame = FrameAttribute(matchedElement) {
-                let point = CGPoint(x: frame.midX, y: frame.midY)
-                sendClick(at: point)
-            } else {
-                throw NativeError.commandFailed("Matched accessibility element has no AXPress action or frame for fallback click.")
-            }
+            try performPrimaryAction(on: matchedElement)
         }
 
         if postDelay > 0 {
@@ -206,12 +235,114 @@ func handleTap(_ parsed: ParsedOptions) throws -> Int32 {
     if preDelay > 0 {
         Thread.sleep(forTimeInterval: preDelay)
     }
-    let point = try pointInWindow(x: x, y: y, for: target)
-    if isDouble {
-        sendDoubleClick(at: point)
+    let backend = resolveInputBackend(for: target)
+    switch backend {
+    case .indigoHID(let client):
+        if isDouble {
+            _ = client.tap(x: x, y: y)
+            Thread.sleep(forTimeInterval: 0.1)
+            _ = client.tap(x: x, y: y)
+        } else {
+            _ = client.tap(x: x, y: y)
+        }
+    case .cgevent:
+        let point = try pointInWindow(x: x, y: y, for: target)
+        if isDouble {
+            sendDoubleClick(at: point)
+        } else {
+            sendClick(at: point)
+        }
+    }
+    if postDelay > 0 {
+        Thread.sleep(forTimeInterval: postDelay)
+    }
+    return 0
+}
+
+func handleTapTab(_ parsed: ParsedOptions) throws -> Int32 {
+    let target = try resolveTarget(from: parsed)
+    guard let indexStr = parsed.options["--index"], let index = Int(indexStr) else {
+        throw NativeError.invalidArguments("tap-tab requires --index <N>.")
+    }
+
+    let preDelay = try optionalDoubleOption("--pre-delay", from: parsed) ?? 0
+    let postDelay = try optionalDoubleOption("--post-delay", from: parsed) ?? 0
+
+    try ensureAccessibilityTrusted()
+    try activateTarget(target)
+
+    let appRoot = try accessibilityRootElement(for: target)
+    let targetUdid = simulatorUdid(from: target)
+    let searchRoot: UIElement = appRoot
+
+    guard let tabBar = findTabBarElement(in: searchRoot, simulatorUdid: targetUdid) else {
+        throw NativeError.commandFailed("No tab bar found in the application UI. Ensure the app has a visible tab bar.")
+    }
+
+    guard let frame = FrameAttribute(tabBar) else {
+        throw NativeError.commandFailed("Tab bar element has no frame attribute.")
+    }
+
+    let tabCount: Int
+    if let tabCountStr = parsed.options["--tab-count"], let tc = Int(tabCountStr) {
+        tabCount = tc
     } else {
-        sendClick(at: point)
+        let children = Children(tabBar)
+        tabCount = children.count
+    }
+
+    guard tabCount > 0 else {
+        throw NativeError.commandFailed("Tab bar has no children and --tab-count was not specified.")
+    }
+
+    guard index >= 0 && index < tabCount else {
+        throw NativeError.invalidArguments("Tab index \(index) is out of range. Valid range: 0..\(tabCount - 1)")
+    }
+
+    if preDelay > 0 {
+        Thread.sleep(forTimeInterval: preDelay)
     }
+
+    let actionableItems = actionableTabBarItems(in: tabBar)
+    if actionableItems.count == tabCount {
+        try performPrimaryAction(on: actionableItems[index])
+        if postDelay > 0 {
+            Thread.sleep(forTimeInterval: postDelay)
+        }
+        return 0
+    }
+
+    if case .simulator = target,
+       let contentRoot = simulatorContentRootElement(from: appRoot, udid: targetUdid) {
+        let proxyItems = semanticProxyTabButtons(in: contentRoot, excluding: tabBar, expectedCount: tabCount)
+        if proxyItems.count == tabCount {
+            try performPrimaryAction(on: proxyItems[index])
+            if postDelay > 0 {
+                Thread.sleep(forTimeInterval: postDelay)
+            }
+            return 0
+        }
+    }
+
+    let tabWidth = frame.width / CGFloat(tabCount)
+    let tapX = frame.origin.x + tabWidth * CGFloat(index) + tabWidth / 2.0
+    let tapY = frame.origin.y + frame.height / 2.0
+
+    let backend = resolveInputBackend(for: target)
+    switch backend {
+    case .indigoHID(let client):
+        guard let contentBounds = simulatorContentBounds(udid: targetUdid) else {
+            throw NativeError.commandFailed("Cannot determine simulator content bounds for IndigoHID coordinate conversion. Ensure Simulator is running.")
+        }
+        let relX = Double(tapX) - Double(contentBounds.origin.x)
+        let relY = Double(tapY) - Double(contentBounds.origin.y)
+        if !client.tap(x: relX, y: relY) {
+            throw NativeError.commandFailed("IndigoHID tap failed. The simulator may not be responding.")
+        }
+    case .cgevent:
+        sendClick(at: CGPoint(x: tapX, y: tapY))
+    }
+
     if postDelay > 0 {
         Thread.sleep(forTimeInterval: postDelay)
     }
@@ -233,10 +364,69 @@ func handleType(_ parsed: ParsedOptions) throws -> Int32 {
     if text.isEmpty {
         throw NativeError.invalidArguments("type requires text input.")
     }
-    sendText(text)
+
+    let methodStr = parsed.options["--method"] ?? "auto"
+    let usePaste: Bool
+    switch methodStr {
+    case "paste":
+        usePaste = true
+    case "keyboard":
+        usePaste = false
+    default: // auto
+        if case .simulator = target {
+            usePaste = true
+        } else {
+            usePaste = false
+        }
+    }
+
+    if usePaste {
+        try pasteText(text, target: target)
+    } else {
+        let backend = resolveInputBackend(for: target)
+        switch backend {
+        case .indigoHID(let client):
+            _ = client.typeText(text)
+        case .cgevent:
+            sendText(text)
+        }
+    }
     return 0
 }
 
+func pasteText(_ text: String, target: TargetApp) throws {
+    switch target {
+    case .simulator(let udid):
+        try setSimulatorPasteboard(text, udid: udid)
+        // Cmd+V: Command keycode=55, V keycode=9
+        sendKeyCombo(modifiers: [55], key: 9)
+        Thread.sleep(forTimeInterval: 0.2)
+    case .macApp:
+        let pasteboard = NSPasteboard.general
+        let original = pasteboard.string(forType: .string)
+
+        pasteboard.clearContents()
+        pasteboard.setString(text, forType: .string)
+
+        // Cmd+V: Command keycode=55, V keycode=9
+        sendKeyCombo(modifiers: [55], key: 9)
+        Thread.sleep(forTimeInterval: 0.15)
+
+        // Restore original clipboard content
+        pasteboard.clearContents()
+        if let original = original {
+            pasteboard.setString(original, forType: .string)
+        }
+    }
+}
+
+func setSimulatorPasteboard(_ text: String, udid: String) throws {
+    let status = try runProcess("/usr/bin/xcrun", ["simctl", "pbcopy", udid], stdinText: text)
+    if status != 0 {
+        throw NativeError.commandFailed("Failed to set simulator pasteboard (exit code \(status)).")
+    }
+}
+
 func handleSwipe(_ parsed: ParsedOptions) throws -> Int32 {
     let target = try resolveTarget(from: parsed)
     let startX = try requiredOption("--start-x", from: parsed)
@@ -257,9 +447,15 @@ func handleSwipe(_ parsed: ParsedOptions) throws -> Int32 {
     if preDelay > 0 {
         Thread.sleep(forTimeInterval: preDelay)
     }
-    let start = try pointInWindow(x: startXValue, y: startYValue, for: target)
-    let end = try pointInWindow(x: endXValue, y: endYValue, for: target)
-    sendSwipe(from: start, to: end, duration: duration)
+    let backend = resolveInputBackend(for: target)
+    switch backend {
+    case .indigoHID(let client):
+        _ = client.swipe(fromX: startXValue, fromY: startYValue, toX: endXValue, toY: endYValue, duration: duration)
+    case .cgevent:
+        let start = try pointForInput(x: startXValue, y: startYValue, for: target)
+        let end = try pointForInput(x: endXValue, y: endYValue, for: target)
+        sendSwipe(from: start, to: end, duration: duration)
+    }
     if postDelay > 0 {
         Thread.sleep(forTimeInterval: postDelay)
     }
@@ -275,12 +471,35 @@ func handleScroll(_ parsed: ParsedOptions) throws -> Int32 {
     if deltaX == 0 && deltaY == 0 {
         throw NativeError.invalidArguments("scroll requires --delta-x and/or --delta-y.")
     }
-    var scrollPoint: CGPoint? = nil
+
     let xRaw = parsed.options["-x"]
     let yRaw = parsed.options["-y"]
-    if let xRaw, let yRaw, let x = Double(xRaw), let y = Double(yRaw) {
-        scrollPoint = try pointInWindow(x: x, y: y, for: target)
+    let xValue = xRaw.flatMap(Double.init)
+    let yValue = yRaw.flatMap(Double.init)
+
+    switch target {
+    case .simulator:
+        let scrollPoint = try simulatorScrollAnchorPoint(x: xValue, y: yValue)
+        let scrollDistance = simulatorScrollDistance(deltaX: deltaX, deltaY: deltaY)
+        let start = CGPoint(x: scrollPoint.x - scrollDistance.width / 2, y: scrollPoint.y - scrollDistance.height / 2)
+        let end = CGPoint(x: scrollPoint.x + scrollDistance.width / 2, y: scrollPoint.y + scrollDistance.height / 2)
+
+        let backend = resolveInputBackend(for: target)
+        switch backend {
+        case .indigoHID(let client):
+            _ = client.swipe(fromX: Double(start.x), fromY: Double(start.y), toX: Double(end.x), toY: Double(end.y), duration: 0.45, steps: 18)
+        case .cgevent:
+            let targetUdid = simulatorUdid(from: target)
+            let startPoint = try pointInSimulatorContent(x: Double(start.x), y: Double(start.y), udid: targetUdid)
+            let endPoint = try pointInSimulatorContent(x: Double(end.x), y: Double(end.y), udid: targetUdid)
+            sendSwipe(from: startPoint, to: endPoint, duration: 0.45)
+        }
+    case .macApp:
+        var scrollPoint: CGPoint? = nil
+        if let xValue, let yValue {
+            scrollPoint = try pointForInput(x: xValue, y: yValue, for: target)
+        }
+        sendScrollWheel(at: scrollPoint, deltaX: Int32(deltaX), deltaY: Int32(deltaY))
     }
-    sendScrollWheel(at: scrollPoint, deltaX: Int32(deltaX), deltaY: Int32(deltaY))
     return 0
 }

package/native/Sources/Commands/WindowCommands.swift

@@ -18,7 +18,7 @@ func handleRightClick(_ parsed: ParsedOptions) throws -> Int32 {
         let root = try accessibilityRootElement(for: target)
         let searchRoot: UIElement
         if case .simulator = target, !includeAll {
-            searchRoot = simulatorContentRootElement(from: root) ?? root
+            searchRoot = simulatorContentRootElement(from: root, udid: simulatorUdid(from: target)) ?? root
         } else {
             searchRoot = root
         }
@@ -71,14 +71,21 @@ func handleDragDrop(_ parsed: ParsedOptions) throws -> Int32 {
         throw NativeError.invalidArguments("drag-drop requires numeric start/end coordinates.")
     }
     let duration = try optionalDoubleOption("--duration", from: parsed) ?? 0.5
+    let holdDuration = try optionalDoubleOption("--hold-duration", from: parsed) ?? 0.7
     let preDelay = try optionalDoubleOption("--pre-delay", from: parsed) ?? 0
     let postDelay = try optionalDoubleOption("--post-delay", from: parsed) ?? 0
     if preDelay > 0 {
         Thread.sleep(forTimeInterval: preDelay)
     }
-    let start = try pointInWindow(x: startXVal, y: startYVal, for: target)
-    let end = try pointInWindow(x: endXVal, y: endYVal, for: target)
-    sendSwipe(from: start, to: end, duration: duration)
+    let backend = resolveInputBackend(for: target)
+    switch backend {
+    case .indigoHID(let client):
+        _ = client.drag(fromX: startXVal, fromY: startYVal, toX: endXVal, toY: endYVal, holdDuration: holdDuration, moveDuration: duration)
+    case .cgevent:
+        let start = try pointForInput(x: startXVal, y: startYVal, for: target)
+        let end = try pointForInput(x: endXVal, y: endYVal, for: target)
+        sendDrag(from: start, to: end, holdDuration: holdDuration, moveDuration: duration)
+    }
     if postDelay > 0 {
         Thread.sleep(forTimeInterval: postDelay)
     }

package/native/Sources/IndigoHID/IndigoHIDClient.swift

@@ -0,0 +1,222 @@
+import Foundation
+
+// MARK: - IndigoHID Client
+
+/// High-level API for sending HID events to an iOS Simulator via IndigoHID.
+final class IndigoHIDClient {
+    let udid: String
+    let port: mach_port_t
+    let loader: IndigoHIDLoader
+    let coords: IndigoHIDCoordinates
+
+    /// Initialize with a simulator UDID.
+    /// Returns nil if IndigoHID is not available or the Mach port cannot be resolved.
+    init?(udid: String) {
+        let loader = IndigoHIDLoader.shared
+        guard loader.isAvailable else { return nil }
+        guard let port = resolveIndigoHIDPort(udid: udid) else { return nil }
+
+        self.udid = udid
+        self.port = port
+        self.loader = loader
+
+        let screenSize = resolveSimulatorScreenSize(udid: udid)
+        self.coords = IndigoHIDCoordinates(screenWidth: screenSize.width, screenHeight: screenSize.height)
+    }
+
+    // MARK: - Touch
+
+    /// Send a single tap at the given pixel coordinates.
+    func tap(x: Double, y: Double) -> Bool {
+        let (nx, ny) = coords.normalize(x: x, y: y)
+
+        // Touch began
+        guard let beginMsg = loader.createTouchMessage(phase: .began, x: nx, y: ny) else { return false }
+        guard sendIndigoHIDMessage(beginMsg, to: port) else { return false }
+
+        Thread.sleep(forTimeInterval: 0.05)
+
+        // Touch ended
+        guard let endMsg = loader.createTouchMessage(phase: .ended, x: nx, y: ny) else { return false }
+        return sendIndigoHIDMessage(endMsg, to: port)
+    }
+
+    /// Send a swipe gesture from start to end coordinates (in pixels).
+    func swipe(fromX: Double, fromY: Double, toX: Double, toY: Double, duration: Double? = nil, steps: Int = 10) -> Bool {
+        let (sx, sy) = coords.normalize(x: fromX, y: fromY)
+        let (ex, ey) = coords.normalize(x: toX, y: toY)
+
+        // Touch began
+        guard let beginMsg = loader.createTouchMessage(phase: .began, x: sx, y: sy) else { return false }
+        guard sendIndigoHIDMessage(beginMsg, to: port) else { return false }
+
+        let stepDuration = (duration ?? 0.3) / Double(steps)
+
+        // Touch moved sequence
+        for step in 1...steps {
+            let progress = Double(step) / Double(steps)
+            let cx = sx + (ex - sx) * progress
+            let cy = sy + (ey - sy) * progress
+            guard let moveMsg = loader.createTouchMessage(phase: .moved, x: cx, y: cy) else { return false }
+            guard sendIndigoHIDMessage(moveMsg, to: port) else { return false }
+            Thread.sleep(forTimeInterval: stepDuration)
+        }
+
+        // Touch ended
+        guard let endMsg = loader.createTouchMessage(phase: .ended, x: ex, y: ey) else { return false }
+        return sendIndigoHIDMessage(endMsg, to: port)
+    }
+
+    /// Send a drag gesture (long press + move + release).
+    func drag(fromX: Double, fromY: Double, toX: Double, toY: Double, holdDuration: Double = 0.5, moveDuration: Double? = nil) -> Bool {
+        let (sx, sy) = coords.normalize(x: fromX, y: fromY)
+        let (ex, ey) = coords.normalize(x: toX, y: toY)
+
+        // Touch began (long press)
+        guard let beginMsg = loader.createTouchMessage(phase: .began, x: sx, y: sy) else { return false }
+        guard sendIndigoHIDMessage(beginMsg, to: port) else { return false }
+
+        if holdDuration > 0 {
+            Thread.sleep(forTimeInterval: holdDuration)
+        }
+
+        // A small warmup move helps SwiftUI DragGesture transition into
+        // an active drag before the long move sequence begins.
+        let warmupProgress = 0.02
+        let warmupX = sx + (ex - sx) * warmupProgress
+        let warmupY = sy + (ey - sy) * warmupProgress
+        guard let warmupMsg = loader.createTouchMessage(phase: .moved, x: warmupX, y: warmupY) else { return false }
+        guard sendIndigoHIDMessage(warmupMsg, to: port) else { return false }
+        Thread.sleep(forTimeInterval: 0.05)
+
+        // Move sequence
+        let steps = 18
+        let stepDuration = max((moveDuration ?? 0.6) / Double(steps), 0.02)
+        for step in 1...steps {
+            let progress = Double(step) / Double(steps)
+            let cx = sx + (ex - sx) * progress
+            let cy = sy + (ey - sy) * progress
+            guard let moveMsg = loader.createTouchMessage(phase: .moved, x: cx, y: cy) else { return false }
+            guard sendIndigoHIDMessage(moveMsg, to: port) else { return false }
+            Thread.sleep(forTimeInterval: stepDuration)
+        }
+
+        Thread.sleep(forTimeInterval: 0.08)
+
+        // Touch ended
+        guard let endMsg = loader.createTouchMessage(phase: .ended, x: ex, y: ey) else { return false }
+        return sendIndigoHIDMessage(endMsg, to: port)
+    }
+
+    /// Type text using HID keyboard events.
+    /// This bypasses iOS autocomplete by sending raw HID keycodes.
+    func typeText(_ text: String) -> Bool {
+        let usagePage: UInt32 = 0x07  // Keyboard/Keypad page
+
+        for char in text {
+            guard let usage = hidUsageForCharacter(char) else { continue }
+
+            let needsShift = characterNeedsShift(char)
+
+            if needsShift {
+                // Shift down (usage 0xE1 = Left Shift)
+                if let shiftDown = loader.createKeyboardMessage(usagePage: usagePage, usage: 0xE1, operation: .keyDown) {
+                    _ = sendIndigoHIDMessage(shiftDown, to: port)
+                }
+            }
+
+            // Key down
+            if let keyDown = loader.createKeyboardMessage(usagePage: usagePage, usage: usage, operation: .keyDown) {
+                _ = sendIndigoHIDMessage(keyDown, to: port)
+            }
+            Thread.sleep(forTimeInterval: 0.02)
+
+            // Key up
+            if let keyUp = loader.createKeyboardMessage(usagePage: usagePage, usage: usage, operation: .keyUp) {
+                _ = sendIndigoHIDMessage(keyUp, to: port)
+            }
+
+            if needsShift {
+                // Shift up
+                if let shiftUp = loader.createKeyboardMessage(usagePage: usagePage, usage: 0xE1, operation: .keyUp) {
+                    _ = sendIndigoHIDMessage(shiftUp, to: port)
+                }
+            }
+
+            Thread.sleep(forTimeInterval: 0.02)
+        }
+
+        return true
+    }
+}
+
+// MARK: - HID Usage Mapping
+
+/// Map a character to its USB HID Usage ID (usage page 0x07).
+private func hidUsageForCharacter(_ char: Character) -> UInt32? {
+    let lower = char.lowercased().first ?? char
+    switch lower {
+    case "a": return 0x04
+    case "b": return 0x05
+    case "c": return 0x06
+    case "d": return 0x07
+    case "e": return 0x08
+    case "f": return 0x09
+    case "g": return 0x0A
+    case "h": return 0x0B
+    case "i": return 0x0C
+    case "j": return 0x0D
+    case "k": return 0x0E
+    case "l": return 0x0F
+    case "m": return 0x10
+    case "n": return 0x11
+    case "o": return 0x12
+    case "p": return 0x13
+    case "q": return 0x14
+    case "r": return 0x15
+    case "s": return 0x16
+    case "t": return 0x17
+    case "u": return 0x18
+    case "v": return 0x19
+    case "w": return 0x1A
+    case "x": return 0x1B
+    case "y": return 0x1C
+    case "z": return 0x1D
+    case "1", "!": return 0x1E
+    case "2", "@": return 0x1F
+    case "3", "#": return 0x20
+    case "4", "$": return 0x21
+    case "5", "%": return 0x22
+    case "6", "^": return 0x23
+    case "7", "&": return 0x24
+    case "8", "*": return 0x25
+    case "9", "(": return 0x26
+    case "0", ")": return 0x27
+    case "\n": return 0x28  // Return
+    case "\t": return 0x2B  // Tab
+    case " ": return 0x2C   // Space
+    case "-", "_": return 0x2D
+    case "=", "+": return 0x2E
+    case "[", "{": return 0x2F
+    case "]", "}": return 0x30
+    case "\\", "|": return 0x31
+    case ";", ":": return 0x33
+    case "'", "\"": return 0x34
+    case "`", "~": return 0x35
+    case ",", "<": return 0x36
+    case ".", ">": return 0x37
+    case "/", "?": return 0x38
+    default: return nil
+    }
+}
+
+/// Check if a character requires the Shift modifier.
+private func characterNeedsShift(_ char: Character) -> Bool {
+    let shiftChars: Set<Character> = [
+        "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M",
+        "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z",
+        "!", "@", "#", "$", "%", "^", "&", "*", "(", ")",
+        "_", "+", "{", "}", "|", ":", "\"", "~", "<", ">", "?"
+    ]
+    return shiftChars.contains(char)
+}