@stim-cli/server 1.13.0 → 1.15.0

package/dist/stim-frames/ScrcpyProtocol.swift

@@ -0,0 +1,167 @@
+import Foundation
+
+/// The scrcpy server (Apache-2.0) that streams a physical Android device's screen as H.264 over an adb
+/// socket and injects input from a control socket. Its client and server must be the same version: the
+/// server refuses any other `version` argument, and the wire format changes between releases.
+enum Scrcpy {
+  static let version = "4.1"
+  /// The sha256 of `scrcpy-server-v4.1` in the release's SHA256SUMS.txt.
+  static let serverSha256 = "deacb991ed2509715160ffdc7907e47b4160eb30d1566217e9047fd5b8850cae"
+  static let maxSize = 2048
+
+  /// `app_process` arguments after the class name. `cleanup=true` forks a process that deletes the pushed
+  /// jar as soon as the server starts; `power_on=false` and the absent `show_touches`/`stay_awake` keep the
+  /// device's settings and screen state untouched.
+  static func serverArguments(scid: String) -> [String] {
+    [
+      version, "scid=\(scid)", "log_level=warn", "tunnel_forward=true", "audio=false", "control=true",
+      "video_codec=h264", "max_size=\(maxSize)", "max_fps=60", "clipboard_autosync=false", "power_on=false",
+      "cleanup=true", "send_device_meta=false",
+    ]
+  }
+
+  enum KeyAction: UInt8 {
+    case down = 0
+    case up = 1
+  }
+
+  enum TouchAction: UInt8 {
+    case down = 0
+    case up = 1
+    case move = 2
+  }
+
+  /// Android `KeyEvent` codes for the buttons and the control characters `input.text` takes.
+  static let keycodes: [String: Int32] = [
+    "home": 3, "back": 4, "lock": 26, "app-switch": 187, "\n": 66, "\t": 61, "\u{8}": 67,
+  ]
+
+  /// `POINTER_ID_GENERIC_FINGER` in scrcpy's Controller: a finger touch, not a mouse.
+  static let fingerPointer: Int64 = -2
+
+  static func keycode(_ action: KeyAction, _ keycode: Int32) -> Data {
+    var data = Data([0, action.rawValue])
+    append(UInt32(bitPattern: keycode), to: &data)
+    append(UInt32(0), to: &data)
+    append(UInt32(0), to: &data)
+    return data
+  }
+
+  static func text(_ text: String) -> Data {
+    let bytes = Data(text.utf8)
+    var data = Data([1])
+    append(UInt32(bytes.count), to: &data)
+    return data + bytes
+  }
+
+  /// `x` and `y` are pixels in the video frame of size `width` by `height`; the server ignores a touch
+  /// whose frame size is not its current one, such as one sent across a rotation.
+  static func touch(
+    _ action: TouchAction, pointer: Int64 = fingerPointer, x: Int32, y: Int32, width: UInt16, height: UInt16
+  ) -> Data {
+    var data = Data([2, action.rawValue])
+    append(UInt64(bitPattern: pointer), to: &data)
+    append(UInt32(bitPattern: x), to: &data)
+    append(UInt32(bitPattern: y), to: &data)
+    append(width, to: &data)
+    append(height, to: &data)
+    append(action == .up ? UInt16(0) : UInt16(0xffff), to: &data)
+    append(UInt32(0), to: &data)
+    append(UInt32(0), to: &data)
+    return data
+  }
+
+  private static func append<T: FixedWidthInteger>(_ value: T, to data: inout Data) {
+    withUnsafeBytes(of: value.bigEndian) { data.append(contentsOf: $0) }
+  }
+}
+
+/// One item of the video socket after the dummy byte: the codec, a capture session with the frame size
+/// (a new one after each rotation), or a packet of Annex-B H.264. A config packet carries the SPS and PPS.
+enum ScrcpyVideoEvent: Equatable {
+  case codec(UInt32)
+  case session(width: Int, height: Int)
+  case packet(config: Bool, keyframe: Bool, data: Data)
+}
+
+/// Splits the bytes of the video socket into events, whatever the chunking of the reads.
+struct ScrcpyVideoDemuxer {
+  static let h264: UInt32 = 0x6832_3634
+  private var buffer = Data()
+  private var codecRead = false
+
+  mutating func push(_ chunk: Data) throws -> [ScrcpyVideoEvent] {
+    buffer += chunk
+    var events: [ScrcpyVideoEvent] = []
+    while true {
+      let start = buffer.startIndex
+      if !codecRead {
+        guard buffer.count >= 4 else { break }
+        events.append(.codec(read32(start)))
+        buffer.removeFirst(4)
+        codecRead = true
+        continue
+      }
+      guard buffer.count >= 12 else { break }
+      if buffer[start] & 0x80 != 0 {
+        events.append(.session(width: Int(read32(start + 4)), height: Int(read32(start + 8))))
+        buffer.removeFirst(12)
+        continue
+      }
+      let length = Int(read32(start + 8))
+      guard length <= 16 * 1024 * 1024 else { throw ScrcpyError.malformed("a \(length)-byte video packet") }
+      guard buffer.count >= 12 + length else { break }
+      let flags = buffer[start]
+      let payload = Data(buffer[(start + 12)..<(start + 12 + length)])
+      events.append(.packet(config: flags & 0x40 != 0, keyframe: flags & 0x20 != 0, data: payload))
+      buffer.removeFirst(12 + length)
+    }
+    return events
+  }
+
+  private func read32(_ at: Int) -> UInt32 {
+    buffer[at..<(at + 4)].reduce(0) { $0 << 8 | UInt32($1) }
+  }
+}
+
+enum ScrcpyError: Error, CustomStringConvertible {
+  case malformed(String)
+
+  var description: String {
+    switch self {
+    case .malformed(let what): return "The scrcpy server sent \(what)."
+    }
+  }
+}
+
+enum AnnexB {
+  /// The NAL units of an Annex-B byte stream, without their start codes.
+  static func units(_ data: Data) -> [Data] {
+    let bytes = [UInt8](data)
+    var starts: [(code: Int, payload: Int)] = []
+    var index = 0
+    while index + 2 < bytes.count {
+      if bytes[index] == 0, bytes[index + 1] == 0, bytes[index + 2] == 1 {
+        let code = index > 0 && bytes[index - 1] == 0 ? index - 1 : index
+        starts.append((code, index + 3))
+        index += 3
+      } else {
+        index += 1
+      }
+    }
+    return starts.indices.map { position in
+      let end = position + 1 < starts.count ? starts[position + 1].code : bytes.count
+      return Data(bytes[starts[position].payload..<end])
+    }
+  }
+
+  /// The same units with 4-byte big-endian lengths, as a `CMSampleBuffer` of `avc1` takes them.
+  static func lengthPrefixed(_ units: [Data]) -> Data {
+    var out = Data()
+    for unit in units {
+      withUnsafeBytes(of: UInt32(unit.count).bigEndian) { out.append(contentsOf: $0) }
+      out += unit
+    }
+    return out
+  }
+}

package/dist/stim-frames/SimulatorDevelopmentOptions.swift

@@ -0,0 +1,81 @@
+import Foundation
+import ObjectiveC
+
+/// Guest development controls on a selected iOS simulator. CoreSimulator calls can block; use off the main thread.
+public enum SimulatorDevelopmentOptions {
+  public struct Settings: Sendable {
+    public let slowAnimations: Bool?
+    public let canShake: Bool
+  }
+
+  // UIKit consumes the state of this Darwin notification when it is posted, as
+  // Siniulator's Input.swift does (e181521a32595c2e537e1ee6c359aae254dbfed3).
+  private static let slowAnimationNotification = "com.apple.UIKit.SimulatorSlowMotionAnimationState"
+  private static let readSelector = NSSelectorFromString("darwinNotificationGetState:name:error:")
+  private static let setSelector = NSSelectorFromString("darwinNotificationSetState:name:error:")
+  private static let postSelector = NSSelectorFromString("postDarwinNotification:error:")
+
+  public static func read(udid: String) throws -> Settings {
+    let device = try selectedDevice(udid)
+    let canPost = device.responds(to: postSelector)
+    let canSetSlow = canPost && device.responds(to: readSelector) && device.responds(to: setSelector)
+    return Settings(slowAnimations: canSetSlow ? try state(device) != 0 : nil, canShake: canPost)
+  }
+
+  public static func setSlowAnimations(_ enabled: Bool, udid: String) throws -> Settings {
+    let device = try selectedDevice(udid)
+    guard device.responds(to: setSelector), device.responds(to: readSelector), device.responds(to: postSelector) else {
+      throw Failure.unavailable
+    }
+    typealias Set = @convention(c) (AnyObject, Selector, UInt64, NSString, UnsafeMutablePointer<NSError?>?) -> Bool
+    let set = unsafeBitCast(device.method(for: setSelector), to: Set.self)
+    var error: NSError?
+    guard set(device, setSelector, enabled ? 1 : 0, slowAnimationNotification as NSString, &error) else {
+      throw error ?? Failure.unavailable
+    }
+    try post(slowAnimationNotification, device: device)
+    let settings = try read(udid: udid)
+    guard settings.slowAnimations == enabled else { throw Failure.unconfirmed }
+    return settings
+  }
+
+  public static func shake(udid: String) throws {
+    try post("com.apple.UIKit.SimulatorShake", device: selectedDevice(udid))
+  }
+
+  private static func selectedDevice(_ udid: String) throws -> NSObject {
+    guard let device = CoreSimulator.device(udid: udid) else { throw Failure.unavailable }
+    return device
+  }
+
+  private static func state(_ device: NSObject) throws -> UInt64 {
+    typealias Read =
+      @convention(c) (AnyObject, Selector, UnsafeMutablePointer<UInt64>, NSString, UnsafeMutablePointer<NSError?>?) -> Bool
+    let read = unsafeBitCast(device.method(for: readSelector), to: Read.self)
+    var value: UInt64 = 0
+    var error: NSError?
+    guard read(device, readSelector, &value, slowAnimationNotification as NSString, &error) else {
+      throw error ?? Failure.unavailable
+    }
+    return value
+  }
+
+  private static func post(_ name: String, device: NSObject) throws {
+    guard device.responds(to: postSelector) else { throw Failure.unavailable }
+    typealias Post = @convention(c) (AnyObject, Selector, NSString, UnsafeMutablePointer<NSError?>?) -> Bool
+    let post = unsafeBitCast(device.method(for: postSelector), to: Post.self)
+    var error: NSError?
+    guard post(device, postSelector, name as NSString, &error) else { throw error ?? Failure.unavailable }
+  }
+
+  private enum Failure: LocalizedError {
+    case unavailable, unconfirmed
+
+    var errorDescription: String? {
+      switch self {
+      case .unavailable: return "Development controls are unavailable for this simulator."
+      case .unconfirmed: return "The simulator did not confirm the animation setting."
+      }
+    }
+  }
+}

package/dist/stim-frames/SimulatorFrameArtwork.swift

@@ -0,0 +1,118 @@
+// Copyright (c) 2026 Siniulator contributors. Adapted under the MIT license in Support/Siniulator-LICENSE.txt.
+import AppKit
+
+#if canImport(StimKit)
+  import StimKit
+#endif
+
+@MainActor
+enum SimulatorFrameArtwork {
+  static func load(udid: String) -> DeviceFrameArtwork? {
+    guard let resources = resources(udid: udid) else { return nil }
+    let profile = plist(resources.appendingPathComponent("profile.plist"))
+    let capabilities = plist(resources.appendingPathComponent("capabilities.plist"))["capabilities"] as? [String: Any]
+    guard let displays = capabilities?["displays"] as? [[String: Any]] else { return nil }
+    let integrated = displays.filter { $0["displayType"] as? String == "integrated" }
+    guard integrated.count == 1, let display = integrated.first,
+      (number(display, "nativeRotation") ?? 0) == 0,
+      let chromeID = profile["chromeIdentifier"] as? String,
+      let name = chromeID.split(separator: ".").last,
+      let width = number(display, "width"), let height = number(display, "height"),
+      let scale = number(display, "scale"), width > 0, height > 0, scale > 0
+    else { return nil }
+    let chrome = URL(fileURLWithPath: "/Library/Developer/DeviceKit/Chrome/\(name).devicechrome/Contents/Resources")
+    guard let data = try? Data(contentsOf: chrome.appendingPathComponent("chrome.json")),
+      let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+      let images = json["images"] as? [String: Any],
+      let sizing = images["sizing"] as? [String: Any],
+      let left = number(sizing, "leftWidth"), let right = number(sizing, "rightWidth"),
+      let top = number(sizing, "topHeight"), let bottom = number(sizing, "bottomHeight")
+    else { return nil }
+    let padding = images["devicePadding"] as? [String: Any] ?? [:]
+    let padLeft = number(padding, "left") ?? 0
+    let padRight = number(padding, "right") ?? 0
+    let padTop = number(padding, "top") ?? 0
+    let padBottom = number(padding, "bottom") ?? 0
+    let screen = CGSize(width: width / scale, height: height / scale)
+    let body = CGRect(x: padLeft, y: padTop, width: screen.width + left + right, height: screen.height + top + bottom)
+    let aperture = CGRect(x: body.minX + left, y: body.minY + top, width: screen.width, height: screen.height)
+    let geometry = DeviceFrameGeometry(
+      size: CGSize(width: body.maxX + padRight, height: body.maxY + padBottom), aperture: aperture)
+    let names = ["topLeft", "top", "topRight", "left", "right", "bottomLeft", "bottom", "bottomRight"]
+    let pieces = names.compactMap { key -> NSImage? in
+      guard let name = images[key] as? String else { return nil }
+      return NSImage(contentsOf: chrome.appendingPathComponent(name).appendingPathExtension("pdf"))
+    }
+    guard pieces.count == names.count else { return nil }
+    let paths = json["paths"] as? [String: Any]
+    let outer = paths?["simpleOutsideBorder"] as? [String: Any] ?? [:]
+    let outerRadius = number(outer, "cornerRadiusX") ?? 0
+    let buttons = (json["inputs"] as? [[String: Any]] ?? []).compactMap { input -> (NSImage, CGRect)? in
+      guard let name = input["image"] as? String,
+        let image = NSImage(contentsOf: chrome.appendingPathComponent(name).appendingPathExtension("pdf")),
+        let offsets = input["offsets"] as? [String: Any], let normal = offsets["normal"] as? [String: Any],
+        let x = number(normal, "x"), let y = number(normal, "y")
+      else { return nil }
+      let position = input["anchor"] as? String == "right" ? body.maxX + x : body.minX + x - image.size.width
+      return (image, CGRect(x: position, y: body.minY + y, width: image.size.width, height: image.size.height))
+    }
+    return DeviceFrameArtwork(
+      geometry: geometry, cornerRadius: number(display, "cornerRadiusUL") ?? 0,
+      background: { _ in
+        NSColor.black.setFill()
+        NSBezierPath(roundedRect: body, xRadius: outerRadius, yRadius: outerRadius).fill()
+        for (image, rect) in buttons { draw(image, in: rect) }
+        drawEdges(pieces, in: body)
+      })
+  }
+
+  static func resources(udid: String) -> URL? {
+    guard let device = CoreSimulator.device(udid: udid),
+      let type = property("deviceType", on: device) as? NSObject,
+      let identifier = property("identifier", on: type) as? String
+    else { return nil }
+    let root = URL(fileURLWithPath: "/Library/Developer/CoreSimulator/Profiles/DeviceTypes")
+    guard let types = try? FileManager.default.contentsOfDirectory(at: root, includingPropertiesForKeys: nil),
+      let bundle = types.first(where: { Bundle(url: $0)?.bundleIdentifier == identifier })
+    else { return nil }
+    return bundle.appendingPathComponent("Contents/Resources")
+  }
+
+  private static func property(_ name: String, on object: NSObject) -> Any? {
+    let selector = NSSelectorFromString(name)
+    return object.responds(to: selector) ? object.perform(selector)?.takeUnretainedValue() : nil
+  }
+
+  private static func plist(_ url: URL) -> [String: Any] {
+    guard let data = try? Data(contentsOf: url) else { return [:] }
+    return (try? PropertyListSerialization.propertyList(from: data, format: nil)) as? [String: Any] ?? [:]
+  }
+
+  private static func number(_ object: [String: Any], _ key: String) -> CGFloat? {
+    (object[key] as? NSNumber).map { CGFloat(truncating: $0) }
+  }
+
+  private static func draw(_ image: NSImage, in rect: CGRect) {
+    image.draw(in: rect, from: .zero, operation: .sourceOver, fraction: 1, respectFlipped: true, hints: nil)
+  }
+
+  private static func drawEdges(_ pieces: [NSImage], in body: CGRect) {
+    let left = pieces[0].size.width
+    let right = pieces[2].size.width
+    let top = pieces[0].size.height
+    let bottom = pieces[5].size.height
+    let width = max(0, body.width - left - right)
+    let height = max(0, body.height - top - bottom)
+    let rects = [
+      CGRect(x: body.minX, y: body.minY, width: left, height: top),
+      CGRect(x: body.minX + left, y: body.minY, width: width, height: top),
+      CGRect(x: body.maxX - right, y: body.minY, width: right, height: top),
+      CGRect(x: body.minX, y: body.minY + top, width: left, height: height),
+      CGRect(x: body.maxX - right, y: body.minY + top, width: right, height: height),
+      CGRect(x: body.minX, y: body.maxY - bottom, width: left, height: bottom),
+      CGRect(x: body.minX + left, y: body.maxY - bottom, width: width, height: bottom),
+      CGRect(x: body.maxX - right, y: body.maxY - bottom, width: right, height: bottom),
+    ]
+    for (image, rect) in zip(pieces, rects) { draw(image, in: rect) }
+  }
+}

package/dist/stim-frames/SimulatorHID.swift

@@ -3,15 +3,18 @@ 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?
+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?
@@ -32,7 +35,7 @@ enum SimulatorKit {
 // Indigo event sources for IndigoHIDMessageForButton, and the HID consumer
 // usages CoreDevice takes for the same buttons; SimulatorKit exports no names
 // for them.
-enum SimulatorButton {
+public enum SimulatorButton: Sendable {
   case home, lock
 
   var indigoSource: UInt32 {
@@ -66,7 +69,9 @@ enum TouchPhase {
 /// 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.
+/// that was not up yet is tried again. The legacy client stays ready while its
+/// replacement connects.
+/// Construction performs synchronous CoreSimulator XPC lookups and must run off the main thread.
 final class SimulatorHID {
   private let transport: Transport
   private let legacyUntil = Date().addingTimeInterval(10)
@@ -78,7 +83,7 @@ final class SimulatorHID {
 
   init?(udid: String) {
     guard let device = CoreSimulator.device(udid: udid) else { return nil }
-    if let coreDevice = CoreDeviceHID(device: device) {
+    if let coreDevice = CoreDeviceHID(device: device, feature: CoreDeviceHID.digitizer) {
       transport = .coreDevice(coreDevice)
     } else if let legacy = LegacyHID(device: device) {
       transport = .legacy(legacy)
@@ -92,11 +97,16 @@ final class SimulatorHID {
     return Date() < legacyUntil
   }
 
+  var isReady: Bool {
+    if case .coreDevice(let coreDevice) = transport { return coreDevice.isReady }
+    return true
+  }
+
   /// `point` is a fraction of the screen in its native orientation, origin top-left.
-  func touch(_ phase: TouchPhase, at point: CGPoint, screenID: UInt32 = 1) {
+  func touch(_ phase: TouchPhase, at point: CGPoint, second: CGPoint? = nil, 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)
+    case .coreDevice(let coreDevice): coreDevice.touch(phase, at: point, second: second, screenID: screenID)
+    case .legacy(let legacy): legacy.touch(phase, at: point, second: second, screenID: screenID)
     }
   }
 
@@ -122,29 +132,33 @@ final class SimulatorHID {
 // 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"
+final class CoreDeviceHID {
+  static let digitizer = "com.apple.coredevice.feature.remote.hid.digitizer"
+  static let vendorDefined = "com.apple.coredevice.feature.remote.hid.vendordefined"
   private static let lookupSelector = NSSelectorFromString("lookup:error:")
 
-  private typealias LookupFn = @convention(c) (
-    AnyObject, Selector, NSString, UnsafeMutablePointer<Unmanaged<NSError>?>?
-  ) -> mach_port_t
+  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 feature: String
   private let connection: xpc_connection_t
   private let lock = NSLock()
   private var closed = false
   private var pending: [xpc_object_t]? = []
 
-  init?(device: NSObject) {
+  init?(device: NSObject, feature: String) {
+    self.feature = feature
     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)
+    let port = lookup(device, Self.lookupSelector, 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)
@@ -190,8 +204,14 @@ private final class CoreDeviceHID {
     return !closed
   }
 
+  var isReady: Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return !closed && pending == nil
+  }
+
   // 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) {
+  func touch(_ phase: TouchPhase, at point: CGPoint, second: 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)
@@ -199,6 +219,12 @@ private final class CoreDeviceHID {
       "eventType": phase == .down ? 0 : phase == .move ? 1 : 2, "edge": 0, "target": UInt64(screenID == 1 ? 0 : screenID),
     ])
     xpc_dictionary_set_value(payload, "pointOne", contact)
+    if let second {
+      let contact = xpc_dictionary_create(nil, nil, 0)
+      xpc_dictionary_set_double(contact, "x", second.x)
+      xpc_dictionary_set_double(contact, "y", second.y)
+      xpc_dictionary_set_value(payload, "pointTwo", contact)
+    }
     send("IndigoDigitizerEvent", payload)
   }
 
@@ -210,6 +236,14 @@ private final class CoreDeviceHID {
     send("IndigoButtonEvent", ["usagePage": 0x0c, "usageCode": usage, "state": down ? 1 : 2])
   }
 
+  /// Sends a vendor-defined HID report on usage page 0xff61, usage 0x5b, which
+  /// is where the simulator's Virtualization provider takes hinge input.
+  func vendorDefined(_ data: Data) {
+    let payload = dictionary(["usagePage": 0xff61, "usage": 0x5b, "version": 0])
+    data.withUnsafeBytes { xpc_dictionary_set_data(payload, "data", $0.baseAddress!, $0.count) }
+    send("IndigoVendorDefinedEvent", payload)
+  }
+
   private func send(_ type: String, _ values: [String: UInt64]) {
     send(type, dictionary(values))
   }
@@ -230,7 +264,7 @@ private final class CoreDeviceHID {
     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_string(message, "featureIdentifier", feature)
     xpc_dictionary_set_value(message, "payload", payload)
     return message
   }
@@ -279,18 +313,25 @@ private final class LegacyHID {
   // 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) {
+  func touch(_ phase: TouchPhase, at point: CGPoint, second: 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 }
+    let message: UnsafeMutableRawPointer?
+    if var other = second {
+      message = SimulatorKit.mouseMessage?(
+        &point, &other, target, UInt(phase.eventType.rawValue), CGSize(width: 1, height: 1), 0)
+    } else {
+      message = SimulatorKit.mouseMessage?(
+        &point, nil, target, UInt(phase.eventType.rawValue), CGSize(width: 1, height: 1), 0)
+    }
+    guard let message 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)
+    guard
+      let message = SimulatorKit.hidMessage?(Self.mainScreenTarget, Self.keyboardPage, usage, down ? Self.keyDown : Self.keyUp)
     else { return }
     deliver(message)
   }

package/dist/stim-frames/SimulatorHingeAngle.swift

@@ -0,0 +1,56 @@
+import Foundation
+
+#if canImport(StimKit)
+  import StimKit
+#endif
+
+/// Reads live Duo hinge angles in degrees. Cancelling iteration interrupts
+/// only this stream's monitor process; the global timeout bounds its lifetime.
+public enum SimulatorHingeAngle {
+  public static func angles(udid: String) -> AsyncStream<Double> {
+    AsyncStream(bufferingPolicy: .bufferingNewest(1)) { continuation in
+      var environment = ProcessInfo.processInfo.environment
+      environment["DEVELOPER_DIR"] = CoreSimulator.developerDir
+      environment["LC_ALL"] = "en_US.UTF-8"
+      do {
+        let process = try ProcessStream.start(
+          executable: "/usr/bin/xcrun",
+          arguments: [
+            "devicectl", "device", "motion", "hinge-angle", "--device", udid,
+            "--session-timeout", "55", "--timeout", "60", "--change-threshold", "1", "--update-interval", "0.5",
+          ],
+          cwd: "/", environment: environment,
+          onLine: { line in
+            guard line.channel == .stdout, let angle = parse(line.text) else { return }
+            continuation.yield(angle)
+          },
+          onExit: { _ in continuation.finish() }
+        )
+        continuation.onTermination = { _ in
+          guard process.isRunning else { return }
+          process.interrupt()
+          DispatchQueue.global().asyncAfter(deadline: .now() + 1) {
+            if process.isRunning { process.terminate() }
+          }
+        }
+      } catch {
+        continuation.finish()
+      }
+    }
+  }
+
+  // devicectl 651.13.4 streams samples only in human output; its JSON snapshot
+  // is lost when this beta hangs after the session timeout or is interrupted.
+  // Human output is not a stable contract, so unfamiliar or invalid lines are ignored.
+  static func parse(_ line: String) -> Double? {
+    let fields = line.strippingANSI.replacingOccurrences(of: "Angle:", with: "Angle: ").split(whereSeparator: \.isWhitespace)
+    guard fields.contains("AngleValid:Y"), let marker = fields.firstIndex(of: "Angle:"),
+      fields.indices.contains(marker + 1)
+    else { return nil }
+    let value = fields[marker + 1]
+    guard value.hasSuffix("\u{00B0}"), let angle = Double(value.dropLast()), angle.isFinite,
+      (0...180).contains(angle)
+    else { return nil }
+    return angle
+  }
+}