@stim-cli/server 1.10.1 → 1.12.0

package/dist/stim-frames/ScreenshotStream.swift

@@ -0,0 +1,130 @@
+import Foundation
+import Network
+
+/// A single `streamScreenshot` call over cleartext HTTP/2 to the emulator's
+/// localhost gRPC port. URLSession speaks HTTP/2 only over TLS, and the
+/// emulator's endpoint is h2c, so this writes the frames itself. It never
+/// decodes response header blocks: the call ends on END_STREAM, RST_STREAM,
+/// GOAWAY, or a closed connection.
+final class ScreenshotStream {
+  private static let window: UInt32 = 1 << 30
+
+  private let connection: NWConnection
+  private let queue = DispatchQueue(label: "stim.emulator-frames")
+  private let request: [UInt8]
+  private let onFrame: (EmulatorFrame) -> Void
+  private let onEnd: () -> Void
+  private var inbox: [UInt8] = []
+  private var messages: [UInt8] = []
+  private var unacknowledged: UInt32 = 0
+  private var ended = false
+
+  init(
+    endpoint: EmulatorEndpoint, width: Int, height: Int,
+    onFrame: @escaping (EmulatorFrame) -> Void, onEnd: @escaping () -> Void
+  ) {
+    connection = NWConnection(
+      host: "127.0.0.1", port: NWEndpoint.Port(integerLiteral: UInt16(endpoint.grpcPort)), using: .tcp)
+    request = Self.requestBytes(endpoint: endpoint, width: width, height: height)
+    self.onFrame = onFrame
+    self.onEnd = onEnd
+  }
+
+  func start() {
+    connection.stateUpdateHandler = { [weak self] state in
+      switch state {
+      case .ready:
+        guard let self else { return }
+        self.send(self.request)
+        self.receive()
+      case .failed, .cancelled:
+        self?.finish()
+      default:
+        break
+      }
+    }
+    connection.start(queue: queue)
+  }
+
+  func cancel() {
+    queue.async {
+      self.ended = true
+      self.connection.cancel()
+    }
+  }
+
+  static func requestBytes(endpoint: EmulatorEndpoint, width: Int, height: Int) -> [UInt8] {
+    GrpcFraming.preface(window: window)
+      + GrpcFraming.request(
+        method: "streamScreenshot", message: ScreenshotMessages.imageFormat(width: width, height: height),
+        endpoint: endpoint, stream: 1)
+  }
+
+  private func receive() {
+    connection.receive(minimumIncompleteLength: 1, maximumLength: 1 << 20) { [weak self] data, _, complete, error in
+      guard let self else { return }
+      if let data { self.inbox += data }
+      self.drainFrames()
+      if complete || error != nil { self.finish() } else if !self.ended { self.receive() }
+    }
+  }
+
+  private func drainFrames() {
+    GrpcFraming.drain(&inbox) { type, flags, _, payload in
+      if !ended { handle(type: type, flags: flags, payload: payload) }
+    }
+  }
+
+  private func handle(type: UInt8, flags: UInt8, payload: ArraySlice<UInt8>) {
+    switch type {
+    case 0:
+      var body = payload
+      if flags & 0x8 != 0, let pad = body.first {
+        body = body.dropFirst().dropLast(Int(pad))
+      }
+      messages += body
+      acknowledge(UInt32(payload.count))
+      drainMessages()
+      if flags & 0x1 != 0 { finish() }
+    case 1:
+      if flags & 0x1 != 0 { finish() }
+    case 3, 7:
+      finish()
+    default:
+      if let reply = GrpcFraming.acknowledgement(type: type, flags: flags, payload: payload) { send(reply) }
+    }
+  }
+
+  private func drainMessages() {
+    var offset = 0
+    while messages.count - offset >= 5 {
+      let length = messages[(offset + 1)..<(offset + 5)].reduce(0) { $0 << 8 | Int($1) }
+      guard messages.count - offset >= 5 + length else { break }
+      let bytes = Data(messages[(offset + 5)..<(offset + 5 + length)])
+      offset += 5 + length
+      if let frame = ScreenshotMessages.frame(fromImage: bytes) { onFrame(frame) }
+    }
+    messages.removeFirst(offset)
+  }
+
+  private func acknowledge(_ count: UInt32) {
+    unacknowledged += count
+    guard unacknowledged >= 1 << 24 else { return }
+    let increment = GrpcFraming.bigEndian(unacknowledged)
+    send(
+      GrpcFraming.frame(type: 8, flags: 0, stream: 0, payload: increment)
+        + GrpcFraming.frame(type: 8, flags: 0, stream: 1, payload: increment))
+    unacknowledged = 0
+  }
+
+  private func send(_ bytes: [UInt8]) {
+    connection.send(content: Data(bytes), completion: .idempotent)
+  }
+
+  private func finish() {
+    guard !ended else { return }
+    ended = true
+    connection.cancel()
+    onEnd()
+  }
+}

package/dist/stim-frames/SimulatorDisplay.swift

@@ -0,0 +1,116 @@
+import Foundation
+import IOSurface
+import ObjectiveC
+
+// CoreSimulator and SimulatorKit are private Apple frameworks. These selectors
+// match the SimDisplayIOSurfaceRenderable, SimDisplayRenderable, SimScreen and
+// SimScreenProperties protocols that Xcode 27 ships; Apple can change them in
+// any Xcode release.
+@objc protocol SimDisplayIOSurfaceRenderable {
+  var framebufferSurface: IOSurface? { get }
+  @objc(registerCallbackWithUUID:ioSurfacesChangeCallback:)
+  func registerSurfacesCallback(_ uuid: NSUUID, _ callback: @escaping (AnyObject?) -> Void)
+  @objc(unregisterIOSurfacesChangeCallbackWithUUID:)
+  func unregisterSurfacesCallback(_ uuid: NSUUID)
+}
+
+@objc protocol SimDisplayRenderable {
+  @objc(registerCallbackWithUUID:damageRectanglesCallback:)
+  func registerDamageCallback(_ uuid: NSUUID, _ callback: @escaping (AnyObject?) -> Void)
+  @objc(unregisterDamageRectanglesCallbackWithUUID:)
+  func unregisterDamageCallback(_ uuid: NSUUID)
+  @objc(registerCallbackWithUUID:displayPropertiesChanged:)
+  func registerPropertiesCallback(_ uuid: NSUUID, _ callback: @escaping (AnyObject?) -> Void)
+  @objc(unregisterDisplayPropertiesChangedCallbackWithUUID:)
+  func unregisterPropertiesCallback(_ uuid: NSUUID)
+}
+
+@objc protocol SimScreen {
+  var screenProperties: SimScreenProperties? { get }
+}
+
+// uiOrientation is a UIInterfaceOrientation; the framebuffer stays in the
+// display's native portrait orientation when the device rotates. screenType 0
+// is a built-in display with a digitizer; TV out, CarPlay and resizable
+// displays have other types.
+@objc protocol SimScreenProperties {
+  var uiOrientation: UInt32 { get }
+  var screenID: UInt32 { get }
+  var screenType: UInt { get }
+}
+
+typealias SimDisplay = SimDisplayIOSurfaceRenderable & SimDisplayRenderable & SimScreen
+
+public enum CoreSimulator {
+  /// The Xcode developer directory CoreSimulator loads SimulatorKit from.
+  /// Set it once at launch, before any view shows simulator frames.
+  public static var developerDir = defaultDeveloperDir
+
+  private static var defaultDeveloperDir: String {
+    ProcessInfo.processInfo.environment["DEVELOPER_DIR"] ?? "/Applications/Xcode.app/Contents/Developer"
+  }
+
+  /// The developer directory `xcode-select -p` reports, or `DEVELOPER_DIR`,
+  /// or `/Applications/Xcode.app`, when the selected one has no SimulatorKit.
+  public static func selectedDeveloperDir() -> String {
+    let process = Process()
+    process.executableURL = URL(fileURLWithPath: "/usr/bin/xcode-select")
+    process.arguments = ["-p"]
+    let out = Pipe()
+    process.standardOutput = out
+    process.standardError = FileHandle.nullDevice
+    guard (try? process.run()) != nil else { return defaultDeveloperDir }
+    let path = String(decoding: out.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    return FileManager.default.fileExists(atPath: simulatorKitPath(path)) ? path : defaultDeveloperDir
+  }
+
+  static func simulatorKitPath(_ developerDir: String) -> String {
+    "\(developerDir)/../SharedFrameworks/SimulatorKit.framework/SimulatorKit"
+  }
+
+  static let deviceSet: NSObject? = {
+    guard dlopen("/Library/Developer/PrivateFrameworks/CoreSimulator.framework/CoreSimulator", RTLD_NOW) != nil
+    else { return nil }
+    dlopen(simulatorKitPath(developerDir), RTLD_NOW)
+    guard let contextClass = NSClassFromString("SimServiceContext") as? NSObject.Type,
+      let context = contextClass.perform(
+        NSSelectorFromString("sharedServiceContextForDeveloperDir:error:"), with: developerDir, with: nil
+      )?.takeUnretainedValue() as? NSObject
+    else { return nil }
+    return context.perform(NSSelectorFromString("defaultDeviceSetWithError:"), with: nil)?
+      .takeUnretainedValue() as? NSObject
+  }()
+
+  static func device(udid: String) -> NSObject? {
+    guard let devices = deviceSet?.value(forKey: "devices") as? [NSObject] else { return nil }
+    return devices.first { ($0.value(forKey: "UDID") as? NSUUID)?.uuidString == udid }
+  }
+
+  /// The screen IDs of the device's built-in displays that have a
+  /// framebuffer, main display first. An iPhone Duo has two; it is empty until
+  /// the device boots.
+  public static func screenIDs(udid: String) -> [UInt32] {
+    displays(udid: udid).compactMap { display in
+      display.screenProperties.flatMap { $0.screenType == 0 ? $0.screenID : nil }
+    }
+  }
+
+  static func displays(udid: String) -> [SimDisplay] {
+    guard let device = device(udid: udid),
+      let io = device.perform(NSSelectorFromString("io"))?.takeUnretainedValue() as? NSObject,
+      let ports = io.perform(NSSelectorFromString("ioPorts"))?.takeUnretainedValue() as? [NSObject],
+      let surfaceRenderable = objc_getProtocol("SimDisplayIOSurfaceRenderable"),
+      let renderable = objc_getProtocol("SimDisplayRenderable"),
+      let screen = objc_getProtocol("SimScreen")
+    else { return [] }
+    let displays = ports.compactMap { port -> SimDisplay? in
+      guard let descriptor = port.perform(NSSelectorFromString("descriptor"))?.takeUnretainedValue() as? NSObject,
+        descriptor.conforms(to: surfaceRenderable), descriptor.conforms(to: renderable), descriptor.conforms(to: screen)
+      else { return nil }
+      let display = unsafeBitCast(descriptor, to: SimDisplay.self)
+      return display.framebufferSurface == nil ? nil : display
+    }
+    return displays.sorted { ($0.screenProperties?.screenID ?? .max) < ($1.screenProperties?.screenID ?? .max) }
+  }
+}

package/dist/stim-frames/SimulatorHID.swift

@@ -0,0 +1,336 @@
+import AppKit
+import ObjectiveC
+import XPC
+
+private typealias AllocFn = @convention(c) (AnyClass, Selector) -> Unmanaged<AnyObject>
+private typealias InitFn = @convention(c) (
+  Unmanaged<AnyObject>, Selector, AnyObject, UnsafeMutablePointer<Unmanaged<NSError>?>?
+) -> Unmanaged<AnyObject>?
+private typealias SendFn = @convention(c) (
+  AnyObject, Selector, UnsafeMutableRawPointer, Bool, DispatchQueue?, (@convention(block) (NSError?) -> Void)?
+) -> Void
+typealias MouseMessageFn = @convention(c) (
+  UnsafePointer<CGPoint>, UnsafePointer<CGPoint>?, UInt32, UInt, CGSize, UInt32
+) -> UnsafeMutableRawPointer?
+typealias UsageForKeyCodeFn = @convention(c) (UInt32) -> UInt32
+typealias ButtonMessageFn = @convention(c) (UInt32, UInt32, UInt32) -> UnsafeMutableRawPointer?
+typealias HIDMessageFn = @convention(c) (UInt32, UInt32, UInt32, UInt32) -> UnsafeMutableRawPointer?
+
+enum SimulatorKit {
+  static let handle = dlopen(CoreSimulator.simulatorKitPath(CoreSimulator.developerDir), RTLD_NOW)
+  static let mouseMessage = symbol("IndigoHIDMessageForMouseNSEvent", MouseMessageFn.self)
+  static let usageForKeyCode = symbol("hidUsageForCGKeyCode", UsageForKeyCodeFn.self)
+  static let buttonMessage = symbol("IndigoHIDMessageForButton", ButtonMessageFn.self)
+  static let hidMessage = symbol("IndigoHIDMessageForHIDArbitrary", HIDMessageFn.self)
+
+  static func symbol<T>(_ name: String, _ type: T.Type) -> T? {
+    guard let handle, let pointer = dlsym(handle, name) else { return nil }
+    return unsafeBitCast(pointer, to: type)
+  }
+}
+
+// Indigo event sources for IndigoHIDMessageForButton, and the HID consumer
+// usages CoreDevice takes for the same buttons; SimulatorKit exports no names
+// for them.
+enum SimulatorButton {
+  case home, lock
+
+  var indigoSource: UInt32 {
+    switch self {
+    case .home: return 0x0
+    case .lock: return 0xbb8
+    }
+  }
+
+  var consumerUsage: UInt64 {
+    switch self {
+    case .home: return 0x40
+    case .lock: return 0x30
+    }
+  }
+}
+
+enum TouchPhase {
+  case down, move, up
+
+  var eventType: NSEvent.EventType {
+    switch self {
+    case .down: return .leftMouseDown
+    case .move: return .leftMouseDragged
+    case .up: return .leftMouseUp
+    }
+  }
+}
+
+/// Input for one booted simulator. It uses the simulator's CoreDevice HID
+/// service when the runtime has one, and SimulatorKit's legacy HID client
+/// otherwise. `isConnected` turns false once the CoreDevice connection closes,
+/// and a few seconds after falling back to the legacy client, so a service
+/// that was not up yet is tried again; make a new instance then.
+final class SimulatorHID {
+  private let transport: Transport
+  private let legacyUntil = Date().addingTimeInterval(10)
+
+  private enum Transport {
+    case coreDevice(CoreDeviceHID)
+    case legacy(LegacyHID)
+  }
+
+  init?(udid: String) {
+    guard let device = CoreSimulator.device(udid: udid) else { return nil }
+    if let coreDevice = CoreDeviceHID(device: device) {
+      transport = .coreDevice(coreDevice)
+    } else if let legacy = LegacyHID(device: device) {
+      transport = .legacy(legacy)
+    } else {
+      return nil
+    }
+  }
+
+  var isConnected: Bool {
+    if case .coreDevice(let coreDevice) = transport { return coreDevice.isConnected }
+    return Date() < legacyUntil
+  }
+
+  /// `point` is a fraction of the screen in its native orientation, origin top-left.
+  func touch(_ phase: TouchPhase, at point: CGPoint, screenID: UInt32 = 1) {
+    switch transport {
+    case .coreDevice(let coreDevice): coreDevice.touch(phase, at: point, screenID: screenID)
+    case .legacy(let legacy): legacy.touch(phase, at: point, screenID: screenID)
+    }
+  }
+
+  /// Presses or releases a key, named by its macOS virtual key code.
+  func hardwareKey(code: UInt16, down: Bool) {
+    guard let usage = SimulatorKit.usageForKeyCode?(UInt32(code)), usage != 0 else { return }
+    switch transport {
+    case .coreDevice(let coreDevice): coreDevice.key(usage: UInt64(usage), down: down)
+    case .legacy(let legacy): legacy.key(usage: usage, down: down)
+    }
+  }
+
+  func button(_ button: SimulatorButton, down: Bool) {
+    switch transport {
+    case .coreDevice(let coreDevice): coreDevice.button(usage: button.consumerUsage, down: down)
+    case .legacy(let legacy): legacy.button(source: button.indigoSource, down: down)
+    }
+  }
+}
+
+// Once a CoreDevice client such as Device Hub starts dtuhidd in the simulator,
+// the guest ignores SimulatorKit's legacy HID client until it reboots; dtuhidd's
+// own service takes input in both states. The message shapes follow dtuhidd's
+// IndigoHIDServer as Siniulator uses it
+// (github.com/kmagiera/Siniulator, Sources/Siniulator/Input.swift).
+private final class CoreDeviceHID {
+  private static let feature = "com.apple.coredevice.feature.remote.hid.digitizer"
+  private static let lookupSelector = NSSelectorFromString("lookup:error:")
+
+  private typealias LookupFn = @convention(c) (
+    AnyObject, Selector, NSString, UnsafeMutablePointer<Unmanaged<NSError>?>?
+  ) -> mach_port_t
+  private typealias EndpointFn = @convention(c) (mach_port_t, UInt64, UInt64) -> xpc_object_t?
+  private typealias EnableFn = @convention(c) (xpc_connection_t) -> Void
+
+  private let connection: xpc_connection_t
+  private let lock = NSLock()
+  private var closed = false
+  private var pending: [xpc_object_t]? = []
+
+  init?(device: NSObject) {
+    let process = dlopen(nil, RTLD_NOW)
+    guard device.responds(to: Self.lookupSelector),
+      let createEndpoint = dlsym(process, "xpc_endpoint_create_mach_port_4sim"),
+      let enableSimToHost = dlsym(process, "xpc_connection_enable_sim2host_4sim")
+    else { return nil }
+    let lookup = unsafeBitCast(device.method(for: Self.lookupSelector), to: LookupFn.self)
+    let port = lookup(device, Self.lookupSelector, Self.feature as NSString, nil)
+    guard port != 0, let endpoint = unsafeBitCast(createEndpoint, to: EndpointFn.self)(port, 0, 0) else { return nil }
+    connection = xpc_connection_create_from_endpoint(endpoint)
+    unsafeBitCast(enableSimToHost, to: EnableFn.self)(connection)
+    let queue = DispatchQueue(label: "stim.simulator-hid")
+    xpc_connection_set_target_queue(connection, queue)
+    xpc_connection_set_event_handler(connection) { [weak self] event in
+      guard xpc_get_type(event) == XPC_TYPE_ERROR, let self else { return }
+      self.lock.lock()
+      self.closed = true
+      self.pending = nil
+      self.lock.unlock()
+    }
+    xpc_connection_resume(connection)
+    // dtuhidd drops events that arrive before it has answered the activating
+    // barrier; a barrier left unanswered fails the connection.
+    let activation = message("IndigoKeyboardButtonEvent", dictionary(["usageCode": 0, "state": 2]), barrier: true)
+    xpc_connection_send_message_with_reply(connection, activation, queue) { [weak self] reply in
+      guard xpc_get_type(reply) != XPC_TYPE_ERROR, let self else { return }
+      self.lock.lock()
+      let queued = self.pending ?? []
+      self.pending = nil
+      for message in queued { xpc_connection_send_message(self.connection, message) }
+      self.lock.unlock()
+    }
+    queue.asyncAfter(deadline: .now() + 5) { [weak self] in
+      guard let self else { return }
+      self.lock.lock()
+      if self.pending != nil {
+        self.closed = true
+        self.pending = nil
+      }
+      self.lock.unlock()
+    }
+  }
+
+  deinit {
+    xpc_connection_cancel(connection)
+  }
+
+  var isConnected: Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return !closed
+  }
+
+  // dtuhidd's DigitizerTarget is 0 for the main screen and the screen ID for any other display.
+  func touch(_ phase: TouchPhase, at point: CGPoint, screenID: UInt32) {
+    let contact = xpc_dictionary_create(nil, nil, 0)
+    xpc_dictionary_set_double(contact, "x", point.x)
+    xpc_dictionary_set_double(contact, "y", point.y)
+    let payload = dictionary([
+      "eventType": phase == .down ? 0 : phase == .move ? 1 : 2, "edge": 0, "target": UInt64(screenID == 1 ? 0 : screenID),
+    ])
+    xpc_dictionary_set_value(payload, "pointOne", contact)
+    send("IndigoDigitizerEvent", payload)
+  }
+
+  func key(usage: UInt64, down: Bool) {
+    send("IndigoKeyboardButtonEvent", ["usageCode": usage, "state": down ? 1 : 2])
+  }
+
+  func button(usage: UInt64, down: Bool) {
+    send("IndigoButtonEvent", ["usagePage": 0x0c, "usageCode": usage, "state": down ? 1 : 2])
+  }
+
+  private func send(_ type: String, _ values: [String: UInt64]) {
+    send(type, dictionary(values))
+  }
+
+  private func send(_ type: String, _ payload: xpc_object_t) {
+    let message = message(type, payload, barrier: false)
+    lock.lock()
+    defer { lock.unlock() }
+    guard !closed else { return }
+    if pending != nil {
+      pending?.append(message)
+    } else {
+      xpc_connection_send_message(connection, message)
+    }
+  }
+
+  private func message(_ type: String, _ payload: xpc_object_t, barrier: Bool) -> xpc_object_t {
+    let message = xpc_dictionary_create(nil, nil, 0)
+    xpc_dictionary_set_string(message, "messageType", type)
+    xpc_dictionary_set_bool(message, "isBarrier", barrier)
+    xpc_dictionary_set_string(message, "featureIdentifier", Self.feature)
+    xpc_dictionary_set_value(message, "payload", payload)
+    return message
+  }
+
+  private func dictionary(_ values: [String: UInt64]) -> xpc_object_t {
+    let object = xpc_dictionary_create(nil, nil, 0)
+    for (key, value) in values { xpc_dictionary_set_uint64(object, key, value) }
+    return object
+  }
+}
+
+// SimulatorKit's HID client and Indigo message builders are private. These
+// signatures match the assertion strings and ObjC type encodings that Xcode 27
+// ships. Touch points are fractions of the screen when the size is 1x1, and
+// 0x32 is the Indigo target of the main screen's digitizer. Keys and buttons
+// also go to 0x32: the keyboard (0x64) and button (0x33) targets stop working
+// once the guest suppresses those services.
+private final class LegacyHID {
+  private static let mainScreenTarget: UInt32 = 0x32
+  private static let keyboardPage: UInt32 = 0x07
+  private static let keyDown: UInt32 = 1
+  private static let keyUp: UInt32 = 2
+  private static let sendSelector = NSSelectorFromString("sendWithMessage:freeWhenDone:completionQueue:completion:")
+
+  private let client: AnyObject
+  private let send: SendFn
+
+  init?(device: NSObject) {
+    let allocSelector = NSSelectorFromString("alloc")
+    let initSelector = NSSelectorFromString("initWithDevice:error:")
+    guard SimulatorKit.handle != nil,
+      let cls = NSClassFromString("_TtC12SimulatorKit24SimDeviceLegacyHIDClient"),
+      let metaclass = object_getClass(cls),
+      class_respondsToSelector(metaclass, allocSelector),
+      class_respondsToSelector(cls, initSelector),
+      class_respondsToSelector(cls, Self.sendSelector)
+    else { return nil }
+    let alloc = unsafeBitCast(class_getMethodImplementation(metaclass, allocSelector), to: AllocFn.self)
+    let initialize = unsafeBitCast(class_getMethodImplementation(cls, initSelector), to: InitFn.self)
+    guard let client = initialize(alloc(cls, allocSelector), initSelector, device, nil)?.takeRetainedValue()
+    else { return nil }
+    self.client = client
+    send = unsafeBitCast(class_getMethodImplementation(cls, Self.sendSelector), to: SendFn.self)
+  }
+
+  // The simulator's SimulatorHID addresses a display's digitizer by its screen
+  // ID with bit 30 set, and backboardd aborts on a target it has no service
+  // for. The main display keeps its legacy target.
+  func touch(_ phase: TouchPhase, at point: CGPoint, screenID: UInt32) {
+    let target = screenID == 1 ? Self.mainScreenTarget : 0x4000_0000 | screenID
+    var point = point
+    // The builder returns nil for a drag that arrives within 16 ms of the previous message.
+    guard let message = SimulatorKit.mouseMessage?(
+      &point, nil, target, UInt(phase.eventType.rawValue), CGSize(width: 1, height: 1), 0)
+    else { return }
+    deliver(message)
+  }
+
+  func key(usage: UInt32, down: Bool) {
+    guard let message = SimulatorKit.hidMessage?(Self.mainScreenTarget, Self.keyboardPage, usage, down ? Self.keyDown : Self.keyUp)
+    else { return }
+    deliver(message)
+  }
+
+  func button(source: UInt32, down: Bool) {
+    guard let message = SimulatorKit.buttonMessage?(source, down ? Self.keyDown : Self.keyUp, Self.mainScreenTarget)
+    else { return }
+    deliver(message)
+  }
+
+  private func deliver(_ message: UnsafeMutableRawPointer) {
+    send(client, Self.sendSelector, message, true, nil, nil)
+  }
+}
+
+/// Maps a fraction of the upright screen, origin top-left, to a fraction of
+/// the framebuffer in its native portrait orientation, which is what the
+/// simulator's digitizer expects. `orientation` is a UIInterfaceOrientation.
+func nativeScreenPoint(_ point: CGPoint, orientation: UInt32) -> CGPoint {
+  switch orientation {
+  case 2: return CGPoint(x: 1 - point.x, y: 1 - point.y)
+  case 3: return CGPoint(x: point.y, y: 1 - point.x)
+  case 4: return CGPoint(x: 1 - point.y, y: point.x)
+  default: return point
+  }
+}
+
+/// Whether a grid of samples across a BGRA framebuffer is all black. A lit
+/// screen shows at least a status bar, so a dark app still has non-black pixels.
+func isBlack(_ surface: IOSurface) -> Bool {
+  surface.lock(options: .readOnly, seed: nil)
+  defer { surface.unlock(options: .readOnly, seed: nil) }
+  let bytes = surface.baseAddress.assumingMemoryBound(to: UInt8.self)
+  let rowStep = max(surface.height / 64, 1)
+  let columnStep = max(surface.width / 48, 1)
+  for y in stride(from: 0, to: surface.height, by: rowStep) {
+    for x in stride(from: 0, to: surface.width, by: columnStep) {
+      let offset = y * surface.bytesPerRow + x * 4
+      if bytes[offset] | bytes[offset + 1] | bytes[offset + 2] != 0 { return false }
+    }
+  }
+  return true
+}

package/dist/stim-frames/SimulatorRotation.swift

@@ -0,0 +1,64 @@
+import Darwin
+import Foundation
+
+/// Turns a booted simulator a quarter turn, as Simulator.app's Rotate Left and
+/// Rotate Right do. Returns false when the simulator cannot be reached.
+public enum SimulatorRotation {
+  private static var sent: [String: UInt32] = [:]
+
+  public static func rotate(udid: String, clockwise: Bool) -> Bool {
+    guard let device = CoreSimulator.device(udid: udid) else { return false }
+    let current = sent[udid] ?? deviceOrientation(interface: CoreSimulator.displays(udid: udid).first?
+      .screenProperties?.uiOrientation ?? 1)
+    let next = quarterTurn(from: current, clockwise: clockwise)
+    guard send(orientation: next, to: device) else { return false }
+    sent[udid] = next
+    return true
+  }
+
+  // GraphicsServices' GSEvent wire format for PurpleWorkspacePort, as Simulator.app
+  // sends it: a 108-byte mach message with id 0x7B carrying event type 50
+  // (device orientation changed) with the host flag 0x20000, a 4-byte record at
+  // 0x48 and the UIDeviceOrientation at 0x4C. facebook/idb documents the layout
+  // in PrivateHeaders/SimulatorApp/GSEvent.h.
+  private static func send(orientation: UInt32, to device: NSObject) -> Bool {
+    typealias Lookup = @convention(c) (AnyObject, Selector, NSString, UnsafeMutablePointer<NSError?>?) -> mach_port_t
+    let selector = NSSelectorFromString("lookup:error:")
+    guard device.responds(to: selector) else { return false }
+    let lookup = unsafeBitCast(device.method(for: selector), to: Lookup.self)
+    let port = lookup(device, selector, "PurpleWorkspacePort", nil)
+    guard port != 0 else { return false }
+    var message = [UInt8](repeating: 0, count: 112)
+    func write(_ value: UInt32, at offset: Int) {
+      withUnsafeBytes(of: value.littleEndian) { message.replaceSubrange(offset..<offset + 4, with: $0) }
+    }
+    write(0x13, at: 0x00)
+    write(108, at: 0x04)
+    write(port, at: 0x08)
+    write(0x7B, at: 0x14)
+    write(50 | 0x20000, at: 0x18)
+    write(4, at: 0x48)
+    write(orientation, at: 0x4C)
+    return message.withUnsafeMutableBytes { bytes in
+      let header = bytes.baseAddress!.assumingMemoryBound(to: mach_msg_header_t.self)
+      return mach_msg(header, MACH_SEND_MSG | MACH_SEND_TIMEOUT, header.pointee.msgh_size, 0, 0, 2000, 0)
+    } == KERN_SUCCESS
+  }
+}
+
+/// The UIDeviceOrientation that shows a UIInterfaceOrientation upright.
+func deviceOrientation(interface: UInt32) -> UInt32 {
+  switch interface {
+  case 3: return 4
+  case 4: return 3
+  case 2: return 2
+  default: return 1
+  }
+}
+
+/// The UIDeviceOrientation a quarter turn from `orientation`.
+func quarterTurn(from orientation: UInt32, clockwise: Bool) -> UInt32 {
+  let counterclockwise: [UInt32] = [1, 3, 2, 4]
+  let index = counterclockwise.firstIndex(of: orientation) ?? 0
+  return counterclockwise[(index + (clockwise ? 3 : 1)) % 4]
+}