serve-sim 0.1.45 → 0.1.46

package/Package.swift

@@ -30,9 +30,13 @@ let package = Package(
         .package(path: "node_modules/node-swift"),
     ],
     targets: [
+        .target(
+            name: "SimNativeSupport"
+        ),
         .target(
             name: "SimNative",
             dependencies: [
+                "SimNativeSupport",
                 .product(name: "NodeAPI", package: "node-swift"),
                 .product(name: "NodeModuleSupport", package: "node-swift"),
             ],
@@ -46,6 +50,10 @@ let package = Package(
                 ])
             ]
         ),
+        .testTarget(
+            name: "SimNativeSupportTests",
+            dependencies: ["SimNativeSupport"]
+        ),
     ],
     // The reused SimStreamHelper logic was written against the standalone helper
     // (plain swiftc, which defaults to Swift 5 mode). Build in Swift 5 mode so its

package/README.md

@@ -36,6 +36,8 @@ Requires macOS with Xcode command line tools (`xcrun simctl`) and a [maintained
 
 > **Note:** Apple Silicon (arm64) only. The bundled `serve-sim-bin` helper ships as an arm64 binary and does not run on Intel (x86_64) Macs.
 
+> **Xcode 27 keyboard input:** Device Hub must be running with the target simulator window visible and frontmost. macOS may also require the app that launched `serve-sim` (for example Terminal) to be enabled in **System Settings → Privacy & Security → Accessibility**. Xcode 26 and older keep using the legacy simulator HID path. Set `SERVE_SIM_DISABLE_DEVICE_HUB_KEYBOARD=1` to opt out of the Xcode 27 bridge.
+
 ## CLI
 
 ```

package/Sources/SimNative/CaptureEngine.swift

@@ -48,7 +48,7 @@ actor CaptureConsumer<E: FrameEncoder>: CaptureConsuming {
                     let encoded = try await encoder.encode(frame)
                     await onFrame(encoded)
                 } catch {
-                    print("error encoding frame: \(error)")
+                    print("error encoding \(E.self) frame: \(error)")
                     continue
                 }
             }
@@ -94,8 +94,25 @@ actor CaptureEngine {
             // drop old frames if there's backpressure
             bufferingPolicy: .bufferingNewest(1)
         )
-        try await frameCapture.start(deviceUDID: deviceUDID) { pixelBuffer, _ in
-            frameContinuation.yield(Frame(pixelBuffer: pixelBuffer))
+        do {
+            try await frameCapture.start(deviceUDID: deviceUDID) { pixelBuffer, _ in
+                frameContinuation.yield(Frame(pixelBuffer: pixelBuffer))
+            }
+        } catch {
+            // Preserve retryability after an ordinary start failure, but never
+            // overwrite a concurrent stop() that moved the actor to .stopped.
+            frameContinuation.finish()
+            await frameCapture.stop()
+            if phase == .starting { phase = .unstarted }
+            throw error
+        }
+        // Actor methods are reentrant across the await above. A simulator can
+        // be shut down while FrameCapture is starting; do not resurrect a
+        // session that stop() already marked stopped.
+        guard phase == .starting else {
+            frameContinuation.finish()
+            await frameCapture.stop()
+            throw CancellationError()
         }
         Task {
             for await frame in frames {
@@ -148,7 +165,7 @@ actor CaptureEngine {
             let flagDescription: Int32 = 1 << 0
             let flagKeyframe: Int32 = 1 << 1
 
-            guard let self else { return }
+            guard let self, let encoded else { return }
             if let description = encoded.description {
                 await onFrame(
                     screenSize,
@@ -203,13 +220,13 @@ actor AVCCEncoder: FrameEncoder {
 
     init() {}
 
-    func encode(_ frame: Frame) async throws -> H264Encoder.Encoded {
+    func encode(_ frame: Frame) async throws -> H264Encoder.Encoded? {
         // TODO: cancel after timeout using TaskGroup
         let result = try await h264Encoder.encode(
             frame.pixelBuffer,
             forceKeyframe: forceKeyframe,
         )
-        forceKeyframe = false
+        if result != nil { forceKeyframe = false }
         return result
     }
 

package/Sources/SimNative/DeviceHubKeyboardBridge.swift

@@ -0,0 +1,300 @@
+import ApplicationServices
+import AppKit
+import CoreGraphics
+import Foundation
+import SimNativeSupport
+
+/// Keyboard transport used by Xcode 27's Device Hub.
+///
+/// CoreSimulator still accepts legacy Indigo keyboard messages on Xcode 27,
+/// but the iOS 27 guest no longer consumes them. Device Hub owns the new input
+/// route, so this bridge posts ordinary macOS key events to its process and lets
+/// the selected simulator window forward them. Xcode 26 and older never create
+/// the bridge and continue using Indigo unchanged.
+///
+/// CGEvent can target an application, not one of its windows. To avoid typing
+/// into a different simulator, the first key-down is accepted only when the
+/// target device name identifies one visible, focused Device Hub window through
+/// Accessibility. Accessibility titles remain available when CGWindow titles
+/// are redacted without Screen Recording permission. The route remains latched
+/// until every posted key is released, so one chord never splits between Device
+/// Hub and the legacy Indigo fallback.
+final class DeviceHubKeyboardBridge {
+    private static let bundleIdentifier = "com.apple.dt.Devices"
+    private static let minimumXcodeMajorVersion = 27
+
+    private struct ActiveTarget {
+        let processIdentifier: pid_t
+    }
+
+    private let expectedBundleURL: URL
+    private let deviceUDID: String
+    private let deviceName: String
+    private let targetWindowTitle: String
+
+    private var activeTarget: ActiveTarget?
+    private var pressedUsages = Set<UInt32>()
+    private var lastUnavailableReason: String?
+
+    private init(
+        expectedBundleURL: URL,
+        deviceUDID: String,
+        deviceName: String,
+        runtimeName: String
+    ) {
+        self.expectedBundleURL = expectedBundleURL.resolvingSymlinksInPath().standardizedFileURL
+        self.deviceUDID = deviceUDID
+        self.deviceName = deviceName
+        self.targetWindowTitle = "\(deviceName) – \(runtimeName)"
+    }
+
+    static func makeIfSupported(
+        deviceUDID: String,
+        deviceName: String,
+        runtimeName: String?
+    ) -> DeviceHubKeyboardBridge? {
+        let environment = ProcessInfo.processInfo.environment
+        guard !DeviceHubKeyboardConfiguration.isDisabled(
+            environmentValue: environment["SERVE_SIM_DISABLE_DEVICE_HUB_KEYBOARD"]
+        ) else {
+            return nil
+        }
+
+        let developerURL = URL(fileURLWithPath: Xcode.developerDir(), isDirectory: true)
+        let xcodeURL = developerURL
+            .deletingLastPathComponent() // Contents
+            .deletingLastPathComponent() // Xcode.app
+
+        guard let bundle = Bundle(url: xcodeURL), xcodeMajorVersion(in: bundle) >= minimumXcodeMajorVersion else {
+            return nil
+        }
+
+        let deviceHubURL = xcodeURL
+            .appendingPathComponent("Contents", isDirectory: true)
+            .appendingPathComponent("Applications", isDirectory: true)
+            .appendingPathComponent("DeviceHub.app", isDirectory: true)
+        guard FileManager.default.fileExists(atPath: deviceHubURL.path) else { return nil }
+
+        guard let runtimeName, !runtimeName.isEmpty else { return nil }
+        return DeviceHubKeyboardBridge(
+            expectedBundleURL: deviceHubURL,
+            deviceUDID: deviceUDID,
+            deviceName: deviceName,
+            runtimeName: runtimeName
+        )
+    }
+
+    /// Returns true only when this event was posted through the guarded Device
+    /// Hub route. False lets HIDInjector use Indigo for backward compatibility
+    /// and for usages Device Hub cannot safely route.
+    func send(type: String, usage: UInt32) -> Bool {
+        let keyDown: Bool
+        switch type {
+        case "down": keyDown = true
+        case "up": keyDown = false
+        default: return false
+        }
+
+        guard let rawKeyCode = HIDKeyboardMapping.macVirtualKeyCode(for: usage) else { return false }
+        guard CGPreflightPostEventAccess() else {
+            return unavailable(
+                "macOS Accessibility permission is not granted "
+                + "(System Settings > Privacy & Security > Accessibility)"
+            )
+        }
+        let keyCode = CGKeyCode(rawKeyCode)
+
+        let target: ActiveTarget
+        if keyDown {
+            if let activeTarget {
+                guard isExpectedDeviceHubRunning(processIdentifier: activeTarget.processIdentifier) else {
+                    resetSequence()
+                    return unavailable("Device Hub exited during a key sequence")
+                }
+                target = activeTarget
+            } else {
+                guard let resolved = resolveTarget() else { return false }
+                activeTarget = resolved
+                target = resolved
+            }
+        } else {
+            // An up event whose down used Indigo must stay on Indigo too.
+            guard pressedUsages.contains(usage), let activeTarget else { return false }
+            guard isExpectedDeviceHubRunning(processIdentifier: activeTarget.processIdentifier) else {
+                resetSequence()
+                return unavailable("Device Hub exited during a key sequence")
+            }
+            target = activeTarget
+        }
+
+        var nextPressedUsages = pressedUsages
+        if keyDown {
+            nextPressedUsages.insert(usage)
+        } else {
+            nextPressedUsages.remove(usage)
+        }
+
+        guard
+            let source = CGEventSource(stateID: .hidSystemState),
+            let event = CGEvent(keyboardEventSource: source, virtualKey: keyCode, keyDown: keyDown)
+        else {
+            if pressedUsages.isEmpty { resetSequence() }
+            return unavailable("CoreGraphics could not create a keyboard event")
+        }
+
+        event.flags = Self.eventFlags(for: nextPressedUsages)
+        event.postToPid(target.processIdentifier)
+
+        pressedUsages = nextPressedUsages
+        lastUnavailableReason = nil
+        if pressedUsages.isEmpty { resetSequence() }
+        return true
+    }
+
+    private func resolveTarget() -> ActiveTarget? {
+        let applications = runningDeviceHubs()
+        guard applications.count == 1, let application = applications.first else {
+            let reason = applications.isEmpty
+                ? "Device Hub from the selected Xcode is not running"
+                : "multiple matching Device Hub processes are running"
+            _ = unavailable(reason)
+            return nil
+        }
+
+        let processIdentifier = application.processIdentifier
+        let route = DeviceHubWindowRouter.route(
+            windows: Self.visibleWindows(processIdentifier: processIdentifier),
+            processIdentifier: processIdentifier,
+            targetWindowTitle: targetWindowTitle
+        )
+        switch route {
+        case .success:
+            return ActiveTarget(processIdentifier: processIdentifier)
+        case .failure(let failure):
+            _ = unavailable(failure.description)
+            return nil
+        }
+    }
+
+    private func runningDeviceHubs() -> [NSRunningApplication] {
+        NSRunningApplication
+            .runningApplications(withBundleIdentifier: Self.bundleIdentifier)
+            .filter { application in
+                guard !application.isTerminated, let bundleURL = application.bundleURL else { return false }
+                return bundleURL.resolvingSymlinksInPath().standardizedFileURL == expectedBundleURL
+            }
+    }
+
+    private func isExpectedDeviceHubRunning(processIdentifier: pid_t) -> Bool {
+        runningDeviceHubs().contains { $0.processIdentifier == processIdentifier }
+    }
+
+    /// Return visible standard Device Hub windows with its key window first.
+    /// AX is already covered by the event-posting Accessibility permission and,
+    /// unlike CGWindowList, does not require Screen Recording to expose titles.
+    private static func visibleWindows(processIdentifier: pid_t) -> [DeviceHubWindow] {
+        let application = AXUIElementCreateApplication(processIdentifier)
+        guard
+            let windows: [AXUIElement] = accessibilityValue(
+                kAXWindowsAttribute,
+                from: application
+            ),
+            let focusedWindow: AXUIElement = accessibilityValue(
+                kAXFocusedWindowAttribute,
+                from: application
+            ),
+            windows.contains(where: { CFEqual($0, focusedWindow) }),
+            isVisibleStandardWindow(focusedWindow) == true
+        else {
+            return []
+        }
+
+        let orderedWindows = [focusedWindow] + windows.filter { !CFEqual($0, focusedWindow) }
+        var snapshot = [DeviceHubWindow]()
+        for (index, window) in orderedWindows.enumerated() {
+            // A partial AX snapshot is unsafe: dropping an unreadable focused
+            // window would make a different window appear to own keyboard focus.
+            guard
+                let isVisible = isVisibleStandardWindow(window),
+                let title: String = accessibilityValue(kAXTitleAttribute, from: window)
+            else { return [] }
+            guard isVisible else { continue }
+            snapshot.append(DeviceHubWindow(
+                processIdentifier: processIdentifier,
+                // The router only needs stable identity within this snapshot.
+                windowNumber: UInt32(index + 1),
+                name: title
+            ))
+        }
+        return snapshot
+    }
+
+    private static func isVisibleStandardWindow(_ window: AXUIElement) -> Bool? {
+        guard
+            let role: String = accessibilityValue(kAXRoleAttribute, from: window),
+            let subrole: String = accessibilityValue(kAXSubroleAttribute, from: window),
+            let minimized: Bool = accessibilityValue(kAXMinimizedAttribute, from: window)
+        else { return nil }
+        return role == kAXWindowRole && subrole == kAXStandardWindowSubrole && !minimized
+    }
+
+    private static func accessibilityValue<T>(
+        _ attribute: String,
+        from element: AXUIElement
+    ) -> T? {
+        var value: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(element, attribute as CFString, &value) == .success else {
+            return nil
+        }
+        return value as? T
+    }
+
+    private func unavailable(_ reason: String) -> Bool {
+        if lastUnavailableReason != reason {
+            let shortUDID = String(deviceUDID.prefix(8))
+            print(
+                "[hid] Device Hub keyboard unavailable for \(deviceName) (\(shortUDID)): "
+                + "\(reason); using legacy HID"
+            )
+            lastUnavailableReason = reason
+        }
+        return false
+    }
+
+    private func resetSequence() {
+        activeTarget = nil
+        pressedUsages.removeAll()
+    }
+
+    private static func eventFlags(for usages: Set<UInt32>) -> CGEventFlags {
+        var flags: CGEventFlags = []
+        for usage in usages {
+            switch HIDKeyboardMapping.modifier(for: usage) {
+            case .control: flags.insert(.maskControl)
+            case .shift: flags.insert(.maskShift)
+            case .option: flags.insert(.maskAlternate)
+            case .command: flags.insert(.maskCommand)
+            case nil: break
+            }
+        }
+        return flags
+    }
+
+    private static func xcodeMajorVersion(in bundle: Bundle) -> Int {
+        if
+            let version = bundle.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String,
+            let major = Int(version.split(separator: ".").first ?? "")
+        {
+            return major
+        }
+
+        if let dtxcode = bundle.object(forInfoDictionaryKey: "DTXcode") as? String,
+           let value = Int(dtxcode) {
+            return value / 100
+        }
+        if let dtxcode = bundle.object(forInfoDictionaryKey: "DTXcode") as? NSNumber {
+            return dtxcode.intValue / 100
+        }
+        return 0
+    }
+}

package/Sources/SimNative/FrameCapture.swift

@@ -4,6 +4,7 @@ import CoreMedia
 import CoreGraphics
 import IOSurface
 import ObjectiveC
+import SimNativeSupport
 
 /// Headless simulator frame capture via direct IOSurface access.
 ///
@@ -40,6 +41,9 @@ actor FrameCapture {
     private var descriptors: [NSObject] = []
     private var callbackUUIDs: [ObjectIdentifier: UUID] = [:]
     private var ioClient: NSObject?
+    private var expectedScreenSize: FramebufferSurfaceSize?
+    private var didLogRejectedPresentationSurface = false
+    private var didLogMissingExpectedSurface = false
 
     func start(deviceUDID: String, onFrame: @escaping @Sendable (CVPixelBuffer, CMTime) -> Void) throws {
         self.onFrame = onFrame
@@ -53,6 +57,7 @@ actor FrameCapture {
         guard state == "Booted" else {
             throw makeError(2, "Device not booted (state: \(state))")
         }
+        self.expectedScreenSize = Self.nativeScreenSize(for: device)
 
         guard let io = device.perform(NSSelectorFromString("io"))?.takeUnretainedValue() as? NSObject else {
             throw makeError(3, "Failed to get device IO")
@@ -139,22 +144,56 @@ actor FrameCapture {
         return candidates
     }
 
-    /// Return the descriptor whose live surface has the largest area.
-    /// Secondary planes/overlays are typically smaller than the main screen.
+    /// Return the descriptor matching the device type's native screen size.
+    /// Xcode 27 can expose an additional 7680x4320 presentation surface while
+    /// Device Hub is resizing; selecting the historical largest surface then
+    /// feeds a non-device frame to VideoToolbox and produces `encodingFailed`.
+    /// If screen metadata is unavailable, retain the old largest-live fallback.
     private func pickBestDescriptor() -> NSObject? {
         let surfSel = NSSelectorFromString("framebufferSurface")
-        var best: NSObject?
-        var bestArea: Int = 0
-        for desc in descriptors {
-            guard let surfObj = desc.perform(surfSel)?.takeUnretainedValue() else { continue }
+        let sizes = descriptors.map { desc -> FramebufferSurfaceSize in
+            guard let surfObj = desc.perform(surfSel)?.takeUnretainedValue() else {
+                return FramebufferSurfaceSize(width: 0, height: 0)
+            }
             let surf = unsafeBitCast(surfObj, to: IOSurface.self)
-            let area = IOSurfaceGetWidth(surf) * IOSurfaceGetHeight(surf)
-            if area > bestArea {
-                best = desc
-                bestArea = area
+            return FramebufferSurfaceSize(
+                width: IOSurfaceGetWidth(surf),
+                height: IOSurfaceGetHeight(surf)
+            )
+        }
+        guard let selection = FramebufferSurfaceSelector.select(
+            from: sizes,
+            expectedSize: expectedScreenSize
+        ) else {
+            return nil
+        }
+
+        if selection.matchedExpectedSize, !didLogRejectedPresentationSurface {
+            let selected = sizes[selection.index]
+            let selectedArea = Int64(selected.width) * Int64(selected.height)
+            if let larger = sizes.filter(\.isLive).max(by: {
+                Int64($0.width) * Int64($0.height) < Int64($1.width) * Int64($1.height)
+            }), Int64(larger.width) * Int64(larger.height) > selectedArea {
+                print(
+                    "[capture] Ignoring non-device framebuffer \(larger.width)x\(larger.height); "
+                    + "native screen is \(selected.width)x\(selected.height)"
+                )
+                didLogRejectedPresentationSurface = true
             }
+        } else if
+            !selection.matchedExpectedSize,
+            let expectedScreenSize,
+            !didLogMissingExpectedSurface
+        {
+            let selected = sizes[selection.index]
+            print(
+                "[capture] No framebuffer matches native screen "
+                + "\(expectedScreenSize.width)x\(expectedScreenSize.height); "
+                + "falling back to \(selected.width)x\(selected.height)"
+            )
+            didLogMissingExpectedSurface = true
         }
-        return best
+        return descriptors[selection.index]
     }
 
     // MARK: - Frame callbacks via objc_msgSend
@@ -270,7 +309,16 @@ actor FrameCapture {
         callbackUUIDs.removeAll()
         descriptors.removeAll()
         lastSeeds.removeAll()
+        onFrame = nil
+        frameCount = 0
+        capturedWidth = 0
+        capturedHeight = 0
+        rewireTickCount = 0
+        lastCaptureTime = .now
         ioClient = nil
+        expectedScreenSize = nil
+        didLogRejectedPresentationSurface = false
+        didLogMissingExpectedSurface = false
     }
 
     // MARK: - Helpers
@@ -280,6 +328,34 @@ actor FrameCapture {
                 userInfo: [NSLocalizedDescriptionKey: msg])
     }
 
+    /// SimDeviceType.mainScreenSize is private but stable across the same
+    /// SimulatorKit versions already used by this file. Runtime validation on
+    /// Xcode 27 confirms that it reports native pixels, not logical points, and
+    /// matches the primary IOSurface exactly. The `@convention(c)` IMP type is
+    /// intentional: it preserves the platform CGSize return ABI (registers on
+    /// arm64 and the appropriate struct-return convention on x86_64).
+    private static func nativeScreenSize(for device: NSObject) -> FramebufferSurfaceSize? {
+        let deviceTypeSelector = NSSelectorFromString("deviceType")
+        guard
+            device.responds(to: deviceTypeSelector),
+            let deviceType = device.perform(deviceTypeSelector)?.takeUnretainedValue() as? NSObject
+        else {
+            return nil
+        }
+        let selector = NSSelectorFromString("mainScreenSize")
+        guard deviceType.responds(to: selector) else { return nil }
+
+        typealias GetSize = @convention(c) (AnyObject, Selector) -> CGSize
+        let getSize = unsafeBitCast(deviceType.method(for: selector), to: GetSize.self)
+        let size = getSize(deviceType, selector)
+        guard size.width.isFinite, size.height.isFinite else { return nil }
+
+        let width = Int(size.width.rounded())
+        let height = Int(size.height.rounded())
+        guard width > 0, height > 0 else { return nil }
+        return FramebufferSurfaceSize(width: width, height: height)
+    }
+
     static func findSimDevice(udid: String) -> NSObject? {
         guard let contextClass = NSClassFromString("SimServiceContext") as? NSObject.Type else { return nil }
         let developerDir = Xcode.developerDir()

package/Sources/SimNative/H264Encoder.swift

@@ -41,8 +41,9 @@ actor H264Encoder {
         if let session { VTCompressionSessionInvalidate(session) }
     }
 
-    /// Submit a frame. Returns immediately; `onEncoded` fires on VT's queue.
-    func encode(_ source: CVPixelBuffer, forceKeyframe: Bool = false) async throws -> Encoded {
+    /// Encode one frame. Real-time VideoToolbox sessions may deliberately drop
+    /// a frame under pressure; that is reported as `nil`, not as an error.
+    func encode(_ source: CVPixelBuffer, forceKeyframe: Bool = false) async throws -> Encoded? {
         let w = Int32(CVPixelBufferGetWidth(source))
         let h = Int32(CVPixelBufferGetHeight(source))
         if session == nil || w != width || h != height {
@@ -60,7 +61,7 @@ actor H264Encoder {
             ? [kVTEncodeFrameOptionKey_ForceKeyFrame: kCFBooleanTrue!] as NSDictionary
             : nil
 
-        let buffer: CMSampleBuffer? = await withCheckedContinuation { continuation in
+        let result: (buffer: CMSampleBuffer?, status: OSStatus, flags: VTEncodeInfoFlags) = await withCheckedContinuation { continuation in
             let status = VTCompressionSessionEncodeFrame(
                 session,
                 imageBuffer: source,
@@ -68,18 +69,20 @@ actor H264Encoder {
                 duration: .invalid,
                 frameProperties: frameProps,
                 infoFlagsOut: nil
-            ) { @Sendable status, _, sampleBuffer in
-                guard status == noErr, let sb = sampleBuffer else {
-                    continuation.resume(returning: nil)
+            ) { @Sendable status, flags, sampleBuffer in
+                guard status == noErr, let sampleBuffer else {
+                    continuation.resume(returning: (nil, status, flags))
                     return
                 }
-                continuation.resume(returning: sb)
+                continuation.resume(returning: (sampleBuffer, status, flags))
             }
             if status != noErr {
-                continuation.resume(returning: nil)
+                continuation.resume(returning: (nil, status, []))
             }
         }
-        guard let buffer else { throw Errors.encodingFailed }
+        if result.status == noErr, result.flags.contains(.frameDropped) { return nil }
+        guard result.status == noErr else { throw Errors.encodingFailed(result.status) }
+        guard let buffer = result.buffer else { throw Errors.missingSampleBuffer }
         return try extract(from: buffer)
     }
 
@@ -219,7 +222,8 @@ actor H264Encoder {
 
     enum Errors: Error {
         case couldNotCreateSession
-        case encodingFailed
+        case encodingFailed(OSStatus)
+        case missingSampleBuffer
         case invalidSampleBuffer
     }
 }

package/Sources/SimNative/HIDInjector.swift

@@ -39,6 +39,7 @@ actor HIDInjector {
     private var hidClient: NSObject?
     private var sendSel: Selector?
     private var simDevice: NSObject?
+    private var deviceHubKeyboardBridge: DeviceHubKeyboardBridge?
 
     // IndigoHIDMessageForMouseNSEvent(CGPoint*, CGPoint*, IndigoHIDTarget, NSEventType, NSSize, IndigoHIDEdge)
     // arm64 ABI: pointer/int params → x0-x4, float params → d0-d1 (independent numbering).
@@ -140,6 +141,14 @@ actor HIDInjector {
 
         self.hidClient = clientObj
         self.sendSel = NSSelectorFromString("sendWithMessage:freeWhenDone:completionQueue:completion:")
+        let deviceName = device.value(forKey: "name") as? String ?? deviceUDID
+        let runtimeName = (device.value(forKey: "runtime") as? NSObject)?
+            .value(forKey: "name") as? String
+        self.deviceHubKeyboardBridge = DeviceHubKeyboardBridge.makeIfSupported(
+            deviceUDID: deviceUDID,
+            deviceName: deviceName,
+            runtimeName: runtimeName
+        )
         hidLog("[hid] SimDeviceLegacyHIDClient created")
         hidLog("[hid] IndigoHIDMessageForMouseNSEvent loaded (with edge gesture support)")
     }
@@ -253,11 +262,6 @@ actor HIDInjector {
     ///   - type: "down" or "up"
     ///   - usage: HID usage code (e.g. 0x04 = 'A', 0x28 = Enter, 0xE1 = LeftShift)
     func sendKey(type: String, usage: UInt32) {
-        guard let keyboardFunc = keyboardFunc else {
-            print("[hid] Keyboard injection unavailable")
-            return
-        }
-
         let direction: UInt32
         switch type {
         case "down": direction = 1
@@ -265,6 +269,16 @@ actor HIDInjector {
         default: return
         }
 
+        if deviceHubKeyboardBridge?.send(type: type, usage: usage) == true {
+            hidLog("[hid] Posted Device Hub key \(type) usage=0x\(String(usage, radix: 16))")
+            return
+        }
+
+        guard let keyboardFunc = keyboardFunc else {
+            print("[hid] Keyboard injection unavailable")
+            return
+        }
+
         guard let msg = keyboardFunc(usage, direction) else {
             print("[hid] IndigoHIDMessageForKeyboardArbitrary returned nil (usage=0x\(String(usage, radix: 16)))")
             return