agent-device 0.21.6 → 0.21.8

package/android/ime-helper/dist/agent-device-android-ime-helper-0.21.8.apk.sha256

@@ -0,0 +1 @@
+d2661c9b0183854af3266f08aa084c1e6f5171be78c468333a8166b068482327  agent-device-android-ime-helper-0.21.8.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.21.6.manifest.json → agent-device-android-ime-helper-0.21.8.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.21.6",
-  "assetName": "agent-device-android-ime-helper-0.21.6.apk",
-  "sha256": "c705e3732af1307e0bf9f9ec058c898839ff695ffa9f3b9fcffe08ba63458487",
+  "version": "0.21.8",
+  "assetName": "agent-device-android-ime-helper-0.21.8.apk",
+  "sha256": "d2661c9b0183854af3266f08aa084c1e6f5171be78c468333a8166b068482327",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 21006,
+  "versionCode": 21008,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.21.8.apk.sha256

@@ -0,0 +1 @@
+4a7a293f798f3c0349e23170d886b7defcd8eaad3f47b98c431185f033d7f800  agent-device-android-snapshot-helper-0.21.8.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.21.6.manifest.json → agent-device-android-snapshot-helper-0.21.8.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.21.6",
-  "releaseTag": "v0.21.6",
-  "assetName": "agent-device-android-snapshot-helper-0.21.6.apk",
+  "version": "0.21.8",
+  "releaseTag": "v0.21.8",
+  "assetName": "agent-device-android-snapshot-helper-0.21.8.apk",
   "apkUrl": null,
-  "sha256": "a4c52106edd24230c2d7a89e955bd43be8115d39b5d0994f674cb4e93fe049e6",
-  "checksumName": "agent-device-android-snapshot-helper-0.21.6.apk.sha256",
+  "sha256": "4a7a293f798f3c0349e23170d886b7defcd8eaad3f47b98c431185f033d7f800",
+  "checksumName": "agent-device-android-snapshot-helper-0.21.8.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 21006,
+  "versionCode": 21008,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

package/apple/macos-helper/Package.swift

@@ -11,8 +11,23 @@ let package = Package(
     ),
   ],
   targets: [
+    .target(
+      name: "AgentDeviceMacOSInput"
+    ),
+    .target(
+      name: "AgentDeviceMacOSDeviceHub"
+    ),
     .executableTarget(
-      name: "AgentDeviceMacOSHelper"
+      name: "AgentDeviceMacOSHelper",
+      dependencies: ["AgentDeviceMacOSInput", "AgentDeviceMacOSDeviceHub"]
+    ),
+    .testTarget(
+      name: "AgentDeviceMacOSInputTests",
+      dependencies: ["AgentDeviceMacOSInput"]
+    ),
+    .testTarget(
+      name: "AgentDeviceMacOSDeviceHubTests",
+      dependencies: ["AgentDeviceMacOSDeviceHub"]
     ),
   ]
 )

package/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubPose.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+/// The decisions the Device Hub pose press makes without a window server: which control a pose
+/// names, which window belongs to a device, and which sidebar row identifies it. They live apart
+/// from the helper executable so the tests can exercise them without an accessibility session.
+
+/// Device Hub's three pose presets for a foldable simulator, named as the helper's `--pose`
+/// argument spells them. Each maps to the accessibility description of its action-bar button.
+public enum DeviceHubPose: String, CaseIterable, Sendable {
+  case closed
+  case book
+  case open
+
+  public init?(argument: String) {
+    self.init(rawValue: argument.lowercased())
+  }
+
+  /// The `AXDescription` Device Hub gives the button for this pose.
+  public var controlDescription: String {
+    switch self {
+    case .closed: return "Closed"
+    case .book: return "Book"
+    case .open: return "Open"
+    }
+  }
+}
+
+/// Device Hub is launched through a trampoline, so LaunchServices registers it with no process
+/// identifier; the process table is matched on the executable path instead.
+public let deviceHubExecutableSuffix = "/DeviceHub.app/Contents/MacOS/DeviceHub"
+
+/// The separator Device Hub puts between the device name and the OS in a window title.
+public let deviceHubWindowTitleSeparator = " – "
+
+/// Device Hub titles a device window `<device name> – <OS> <version>`, so a window shows the
+/// device when its title is the name or the name followed by that exact separator. A bare
+/// space would also match a simulator whose name merely extends this one ("iPhone Duo Lab").
+public func deviceHubWindowShows(deviceName: String, title: String?) -> Bool {
+  guard let title else { return false }
+  return title == deviceName || title.hasPrefix(deviceName + deviceHubWindowTitleSeparator)
+}
+
+/// The accessibility identifier of the sidebar row for one simulator. The UDID is the one device
+/// identity Device Hub exposes that two simulators sharing a name cannot confuse.
+public func deviceHubDeviceRowIdentifier(udid: String) -> String {
+  return "TableRow.Device.\(udid)"
+}

package/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift

@@ -0,0 +1,320 @@
+import AgentDeviceMacOSDeviceHub
+import AppKit
+import ApplicationServices
+import Darwin
+import Foundation
+
+/// The Xcode Device Hub application. Its device windows carry an action bar whose pose controls
+/// are the only public seam onto the private channel that folds a simulator.
+private let deviceHubBundleId = "com.apple.dt.Devices"
+
+/// How long a reopen gets to restore a window, and a sidebar selection to switch the window's
+/// device, before the press is refused.
+private let deviceHubSettleDeadline: TimeInterval = 8
+private let deviceHubPoll: TimeInterval = 0.25
+
+struct DeviceHubPoseResponse: Encodable {
+  let pose: String
+  let control: String
+  let windowTitle: String
+  /** Whether Device Hub had to be asked to reopen a window before the device could be selected. */
+  let reopened: Bool
+  /** Whether the window was switched to the device through its sidebar row. */
+  let selected: Bool
+}
+
+func handleDeviceHub(arguments: [String]) throws -> any Encodable {
+  guard arguments.first == "pose" else {
+    throw HelperError.invalidArgs("device-hub requires pose")
+  }
+  let rest = Array(arguments.dropFirst())
+  guard let udid = helperOptionValue(arguments: rest, name: "--udid")?
+    .trimmingCharacters(in: .whitespacesAndNewlines),
+    !udid.isEmpty
+  else {
+    throw HelperError.invalidArgs("device-hub pose requires --udid <udid>")
+  }
+  guard let deviceName = helperOptionValue(arguments: rest, name: "--device-name")?
+    .trimmingCharacters(in: .whitespacesAndNewlines),
+    !deviceName.isEmpty
+  else {
+    throw HelperError.invalidArgs("device-hub pose requires --device-name <name>")
+  }
+  guard let pose = helperOptionValue(arguments: rest, name: "--pose").flatMap(DeviceHubPose.init(argument:))
+  else {
+    throw HelperError.invalidArgs("device-hub pose requires --pose <closed|book|open>")
+  }
+  let control = pose.controlDescription
+  guard AXIsProcessTrusted() else {
+    throw HelperError.commandFailed(
+      "fold needs Accessibility permission to press the Device Hub pose control",
+      details: ["reason": "accessibility-permission", "permission": "accessibility"]
+    )
+  }
+  guard let pid = deviceHubProcessIdentifier() else {
+    throw HelperError.commandFailed(
+      "Xcode Device Hub is not running",
+      details: ["reason": "device-hub-not-running", "bundleId": deviceHubBundleId]
+    )
+  }
+
+  let appElement = AXUIElementCreateApplication(pid)
+  let (window, reopened) = try deviceHubWindow(in: appElement, pid: pid, deviceName: deviceName)
+  let selected = try selectDevice(udid: udid, deviceName: deviceName, in: window, appElement: appElement)
+  let windowTitle = stringAttribute(window, attribute: kAXTitleAttribute as String) ?? ""
+  guard let button = awaitPoseButton(in: window, description: control) else {
+    throw HelperError.commandFailed(
+      "Device Hub shows no \(control) pose control for \(deviceName)",
+      details: [
+        "reason": "device-hub-pose-control-missing",
+        "windowTitle": windowTitle,
+        "control": control,
+      ]
+    )
+  }
+  let status = AXUIElementPerformAction(button, kAXPressAction as CFString)
+  guard status == .success else {
+    throw HelperError.commandFailed(
+      "Device Hub refused the \(control) pose press",
+      details: ["reason": "device-hub-press-failed", "status": "\(status.rawValue)"]
+    )
+  }
+  return SuccessEnvelope(
+    data: DeviceHubPoseResponse(
+      pose: pose.rawValue,
+      control: control,
+      windowTitle: windowTitle,
+      reopened: reopened,
+      selected: selected
+    )
+  )
+}
+
+/// Device Hub is launched through a trampoline, so LaunchServices registers it with no process
+/// identifier (`NSRunningApplication.processIdentifier` is -1) and an accessibility element built
+/// from that identifier is invalid. The process table is the only place its real pid appears.
+private func deviceHubProcessIdentifier() -> pid_t? {
+  let executableSuffix = deviceHubExecutableSuffix
+  let byteCount = proc_listpids(UInt32(PROC_ALL_PIDS), 0, nil, 0)
+  guard byteCount > 0 else { return nil }
+  var pids = [pid_t](repeating: 0, count: Int(byteCount) / MemoryLayout<pid_t>.size + 64)
+  let filled = proc_listpids(
+    UInt32(PROC_ALL_PIDS), 0, &pids, Int32(pids.count * MemoryLayout<pid_t>.size)
+  )
+  guard filled > 0 else { return nil }
+  var path = [CChar](repeating: 0, count: 4096)
+  for pid in pids.prefix(Int(filled) / MemoryLayout<pid_t>.size) where pid > 0 {
+    guard proc_pidpath(pid, &path, UInt32(path.count)) > 0 else { continue }
+    if String(cString: path).hasSuffix(executableSuffix) {
+      return pid
+    }
+  }
+  return nil
+}
+
+/// A device window to drive: the one already showing this device when there is one, otherwise
+/// any device window, since its sidebar can switch it to the device. A Device Hub with no window
+/// at all — a simulator booted headlessly leaves it that way — is asked to reopen one.
+private func deviceHubWindow(
+  in appElement: AXUIElement,
+  pid: pid_t,
+  deviceName: String
+) throws -> (window: AXUIElement, reopened: Bool) {
+  if let window = preferredWindow(in: appElement, deviceName: deviceName) {
+    return (window, false)
+  }
+  try sendReopenEvent(to: pid)
+  let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
+  while Date() < deadline {
+    Thread.sleep(forTimeInterval: deviceHubPoll)
+    if let window = preferredWindow(in: appElement, deviceName: deviceName) {
+      return (window, true)
+    }
+  }
+  throw HelperError.commandFailed(
+    "Device Hub shows no device window to drive",
+    details: ["reason": "device-hub-window-missing", "deviceName": deviceName]
+  )
+}
+
+private func preferredWindow(in appElement: AXUIElement, deviceName: String) -> AXUIElement? {
+  let candidates = windows(of: appElement)
+  return candidates.first { windowShows(deviceName: deviceName, $0) } ?? candidates.first
+}
+
+private func windowShows(deviceName: String, _ window: AXUIElement) -> Bool {
+  return deviceHubWindowShows(
+    deviceName: deviceName,
+    title: stringAttribute(window, attribute: kAXTitleAttribute as String)
+  )
+}
+
+/// `kAEReopenApplication` is what the Dock sends when an app with no open windows is clicked, and
+/// it is the one event Device Hub answers by restoring the device window. Sent to the process
+/// directly, because LaunchServices cannot address a trampolined app by bundle identifier.
+private func sendReopenEvent(to pid: pid_t) throws {
+  let target = NSAppleEventDescriptor(processIdentifier: pid)
+  let event = NSAppleEventDescriptor(
+    eventClass: AEEventClass(kCoreEventClass),
+    eventID: AEEventID(kAEReopenApplication),
+    targetDescriptor: target,
+    returnID: AEReturnID(kAutoGenerateReturnID),
+    transactionID: AETransactionID(kAnyTransactionID)
+  )
+  do {
+    _ = try event.sendEvent(options: [.noReply], timeout: 5)
+  } catch {
+    let code = (error as NSError).code
+    throw HelperError.commandFailed(
+      "fold could not ask Device Hub to reopen its device window",
+      details: [
+        "reason": code == -1743 ? "automation-permission" : "device-hub-reopen-failed",
+        "error": String(describing: error),
+      ]
+    )
+  }
+}
+
+/// Switches the window to the device through its sidebar row, whose accessibility identifier is
+/// `TableRow.Device.<udid>` — the one place Device Hub exposes a device identity that two
+/// simulators sharing a name cannot confuse. A window already titled with the device still gets
+/// the selection when the row is visible, because the title alone cannot tell such twins apart.
+private func selectDevice(
+  udid: String,
+  deviceName: String,
+  in window: AXUIElement,
+  appElement: AXUIElement
+) throws -> Bool {
+  var shownSidebar = false
+  var row = deviceRow(udid: udid, in: window)
+  if row == nil, showSidebar(appElement: appElement) {
+    shownSidebar = true
+    let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
+    while row == nil, Date() < deadline {
+      Thread.sleep(forTimeInterval: deviceHubPoll)
+      row = deviceRow(udid: udid, in: window)
+    }
+  }
+  defer {
+    if shownSidebar { _ = pressMenuItem(appElement: appElement, menu: "View", item: "Hide Sidebar") }
+  }
+  guard let row else {
+    if windowShows(deviceName: deviceName, window) {
+      return false
+    }
+    throw HelperError.commandFailed(
+      "Device Hub lists no device \(udid) in its sidebar",
+      details: ["reason": "device-hub-device-missing", "udid": udid, "deviceName": deviceName]
+    )
+  }
+  let status = AXUIElementSetAttributeValue(row, kAXSelectedAttribute as CFString, kCFBooleanTrue)
+  guard status == .success else {
+    throw HelperError.commandFailed(
+      "Device Hub refused to select \(deviceName) in its sidebar",
+      details: ["reason": "device-hub-select-failed", "status": "\(status.rawValue)"]
+    )
+  }
+  let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
+  while !windowShows(deviceName: deviceName, window), Date() < deadline {
+    Thread.sleep(forTimeInterval: deviceHubPoll)
+  }
+  guard windowShows(deviceName: deviceName, window) else {
+    throw HelperError.commandFailed(
+      "Device Hub did not switch its window to \(deviceName)",
+      details: [
+        "reason": "device-hub-select-unconfirmed",
+        "windowTitle": stringAttribute(window, attribute: kAXTitleAttribute as String) ?? "",
+      ]
+    )
+  }
+  return true
+}
+
+private func deviceRow(udid: String, in window: AXUIElement) -> AXUIElement? {
+  guard let label = findElement(root: window, depth: 0, where: {
+    stringAttribute($0, attribute: "AXIdentifier") == deviceHubDeviceRowIdentifier(udid: udid)
+  }) else {
+    return nil
+  }
+  var current: AXUIElement? = label
+  while let element = current {
+    if stringAttribute(element, attribute: kAXRoleAttribute as String) == "AXRow" {
+      return element
+    }
+    current = elementAttribute(element, attribute: kAXParentAttribute as String)
+  }
+  return nil
+}
+
+private func showSidebar(appElement: AXUIElement) -> Bool {
+  return pressMenuItem(appElement: appElement, menu: "View", item: "Show Sidebar")
+}
+
+private func pressMenuItem(appElement: AXUIElement, menu: String, item: String) -> Bool {
+  guard let menuBar = elementAttribute(appElement, attribute: kAXMenuBarAttribute as String) else {
+    return false
+  }
+  for menuBarItem in children(of: menuBar)
+  where stringAttribute(menuBarItem, attribute: kAXTitleAttribute as String) == menu {
+    for submenu in children(of: menuBarItem) {
+      for menuItem in children(of: submenu)
+      where stringAttribute(menuItem, attribute: kAXTitleAttribute as String) == item {
+        return AXUIElementPerformAction(menuItem, kAXPressAction as CFString) == .success
+      }
+    }
+  }
+  return false
+}
+
+/// The action bar is rebuilt for the device the window shows, so right after a sidebar selection
+/// the window already carries the new title while the pose controls are still being laid out.
+/// The controls are therefore awaited, not looked up once.
+private func awaitPoseButton(in window: AXUIElement, description: String) -> AXUIElement? {
+  let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
+  while true {
+    if let button = poseButton(in: window, description: description) {
+      return button
+    }
+    guard Date() < deadline else { return nil }
+    Thread.sleep(forTimeInterval: deviceHubPoll)
+  }
+}
+
+/// The pose controls sit in the window's action bar as `AXButton`s described by their preset
+/// name; the simulated screen inside the same window is an iOS content group whose own buttons
+/// carry app labels, never these three.
+private func poseButton(in window: AXUIElement, description: String) -> AXUIElement? {
+  return findElement(root: window, depth: 0) {
+    stringAttribute($0, attribute: kAXRoleAttribute as String) == "AXButton"
+      && stringAttribute($0, attribute: kAXDescriptionAttribute as String) == description
+  }
+}
+
+private func findElement(
+  root: AXUIElement,
+  depth: Int,
+  where matches: (AXUIElement) -> Bool
+) -> AXUIElement? {
+  if depth > 14 {
+    return nil
+  }
+  for child in children(of: root) {
+    if matches(child) {
+      return child
+    }
+    if stringAttribute(child, attribute: kAXSubroleAttribute as String) == "iOSContentGroup" {
+      continue
+    }
+    if let nested = findElement(root: child, depth: depth + 1, where: matches) {
+      return nested
+    }
+  }
+  return nil
+}
+
+func helperOptionValue(arguments: [String], name: String) -> String? {
+  guard let index = arguments.firstIndex(of: name), arguments.indices.contains(index + 1) else {
+    return nil
+  }
+  return arguments[index + 1]
+}

package/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift

@@ -1,3 +1,4 @@
+import AgentDeviceMacOSInput
 import AppKit
 import ApplicationServices
 import CoreGraphics
@@ -63,6 +64,10 @@ struct ReadResponse: Encodable {
 struct PressResponse: Encodable {
   let x: Double
   let y: Double
+  /// Hold actually posted; a short request is raised to the deliverable floor.
+  let holdMs: Int
+  let clicks: Int
+  let doubleClick: Bool
   let bundleId: String?
   let surface: String?
 }
@@ -122,6 +127,8 @@ struct AgentDeviceMacOSHelper {
       return try handleScreenshot(arguments: Array(arguments.dropFirst()))
     case "audio-probe":
       return try handleAudioProbe(arguments: Array(arguments.dropFirst()))
+    case "device-hub":
+      return try handleDeviceHub(arguments: Array(arguments.dropFirst()))
     default:
       throw HelperError.invalidArgs("unknown command: \(command)")
     }
@@ -378,10 +385,48 @@ struct AgentDeviceMacOSHelper {
       throw HelperError.invalidArgs("press requires --x <number> --y <number>")
     }
 
+    let holdMs = try validatedPressInt(
+      optionValue(arguments: arguments, name: "--hold-ms"),
+      name: "--hold-ms",
+      minimum: 0,
+      default: 0
+    )
+    let clicks = try validatedPressInt(
+      optionValue(arguments: arguments, name: "--clicks"),
+      name: "--clicks",
+      minimum: 1,
+      default: 1
+    )
+    let intervalMs = try validatedPressInt(
+      optionValue(arguments: arguments, name: "--interval-ms"),
+      name: "--interval-ms",
+      minimum: 0,
+      default: 120
+    )
+
+    let doubleClick = arguments.contains("--double-click")
     let bundleId = try optionValue(arguments: arguments, name: "--bundle-id").map(validatedBundleId)
     let surface = optionValue(arguments: arguments, name: "--surface")
-    try pressAtPosition(bundleId: bundleId, surface: surface, x: x, y: y)
-    return SuccessEnvelope(data: PressResponse(x: x, y: y, bundleId: bundleId, surface: surface))
+    let request = MouseClickRequest(
+      x: x,
+      y: y,
+      holdMs: holdMs,
+      clicks: clicks,
+      doubleClick: doubleClick,
+      intervalMs: intervalMs
+    )
+    try pressAtPosition(request)
+    return SuccessEnvelope(
+      data: PressResponse(
+        x: x,
+        y: y,
+        holdMs: mouseClickHoldMs(requestedMs: holdMs),
+        clicks: clicks,
+        doubleClick: doubleClick,
+        bundleId: bundleId,
+        surface: surface
+      )
+    )
   }
 
   static func handleScreenshot(arguments: [String]) throws -> any Encodable {
@@ -434,6 +479,21 @@ private func intOption(arguments: [String], name: String) -> Int? {
   return Int(value)
 }
 
+private func validatedPressInt(
+  _ raw: String?,
+  name: String,
+  minimum: Int,
+  default fallback: Int
+) throws -> Int {
+  guard let raw else {
+    return fallback
+  }
+  guard let value = Int(raw), value >= minimum else {
+    throw HelperError.invalidArgs("press \(name) must be an integer of at least \(minimum)")
+  }
+  return value
+}
+
 private func readTextAtPosition(bundleId: String?, surface: String?, x: Double, y: Double) throws -> String {
   let targetApp: NSRunningApplication?
   if surface == "frontmost-app" || (surface == nil && bundleId != nil) {
@@ -481,19 +541,12 @@ private func readTextAtPosition(bundleId: String?, surface: String?, x: Double,
   throw HelperError.commandFailed("read did not resolve text")
 }
 
-private func pressAtPosition(bundleId: String?, surface: String?, x: Double, y: Double) throws {
-  _ = bundleId
-  _ = surface
-  let point = CGPoint(x: x, y: y)
-  guard let move = CGEvent(mouseEventSource: nil, mouseType: .mouseMoved, mouseCursorPosition: point, mouseButton: .left),
-        let down = CGEvent(mouseEventSource: nil, mouseType: .leftMouseDown, mouseCursorPosition: point, mouseButton: .left),
-        let up = CGEvent(mouseEventSource: nil, mouseType: .leftMouseUp, mouseCursorPosition: point, mouseButton: .left)
-  else {
+private func pressAtPosition(_ request: MouseClickRequest) throws {
+  do {
+    try postMouseClick(request)
+  } catch MouseClickDeliveryError.eventCreationFailed {
     throw HelperError.commandFailed("press action failed", details: ["reason": "event_creation_failed"])
   }
-  move.post(tap: .cghidEventTap)
-  down.post(tap: .cghidEventTap)
-  up.post(tap: .cghidEventTap)
 }
 
 private func captureSurfaceScreenshot(surface: String?, outPath: String, fullscreen: Bool) throws {

package/apple/macos-helper/Sources/AgentDeviceMacOSInput/MouseClickDelivery.swift

@@ -0,0 +1,116 @@
+import CoreGraphics
+import Foundation
+
+public struct MouseClickRequest: Equatable, Sendable {
+  public let x: Double
+  public let y: Double
+  /// How long the button stays down. Zero asks for the default hold.
+  public let holdMs: Int
+  /// Independent presses, each at click state 1.
+  public let clicks: Int
+  /// Post every press as a double-click pair with a rising click state.
+  public let doubleClick: Bool
+  public let intervalMs: Int
+
+  public init(
+    x: Double,
+    y: Double,
+    holdMs: Int = 0,
+    clicks: Int = 1,
+    doubleClick: Bool = false,
+    intervalMs: Int = 120
+  ) {
+    self.x = x
+    self.y = y
+    self.holdMs = holdMs
+    self.clicks = clicks
+    self.doubleClick = doubleClick
+    self.intervalMs = intervalMs
+  }
+}
+
+public enum MouseClickDeliveryError: Error, Equatable {
+  case eventCreationFailed
+}
+
+/// The button the helper currently holds down, kept where a signal handler can reach it.
+/// A helper killed between a mouse-down and its mouse-up would otherwise leave the system's
+/// primary button stuck down for whatever the user touches next. The host stops the helper
+/// with SIGTERM before SIGKILL (`runMacOsHelper` in `helper.ts`) so that this handler runs
+/// on a deadline and on a cancelled request, not only on a signal sent by hand.
+nonisolated(unsafe) private var heldMouseButton: (point: CGPoint, clickState: Int)?
+
+private func releaseHeldMouseButton() {
+  guard let held = heldMouseButton else { return }
+  heldMouseButton = nil
+  let up = CGEvent(
+    mouseEventSource: nil,
+    mouseType: .leftMouseUp,
+    mouseCursorPosition: held.point,
+    mouseButton: .left
+  )
+  up?.setIntegerValueField(.mouseEventClickState, value: Int64(held.clickState))
+  up?.post(tap: .cghidEventTap)
+}
+
+private func installMouseReleaseOnTermination() {
+  for terminationSignal in [SIGTERM, SIGINT, SIGHUP] {
+    signal(terminationSignal) { received in
+      releaseHeldMouseButton()
+      _exit(128 + received)
+    }
+  }
+}
+
+/// Posts a click the way a trackpad would: one motion to the point, then each press held
+/// long enough for the app to accept the release. A termination signal that lands inside a
+/// hold releases the button before the process exits.
+public func postMouseClick(_ request: MouseClickRequest) throws {
+  installMouseReleaseOnTermination()
+  let point = CGPoint(x: request.x, y: request.y)
+  let hold = mouseClickHoldMs(requestedMs: request.holdMs)
+  let presses = mouseClickPresses(
+    clicks: request.clicks,
+    doubleClick: request.doubleClick,
+    intervalMs: request.intervalMs
+  )
+
+  guard let move = CGEvent(
+    mouseEventSource: nil,
+    mouseType: .mouseMoved,
+    mouseCursorPosition: point,
+    mouseButton: .left
+  ) else {
+    throw MouseClickDeliveryError.eventCreationFailed
+  }
+  move.post(tap: .cghidEventTap)
+
+  for press in presses {
+    if press.delayBeforeMs > 0 {
+      usleep(UInt32(press.delayBeforeMs) * 1000)
+    }
+    guard let down = CGEvent(
+      mouseEventSource: nil,
+      mouseType: .leftMouseDown,
+      mouseCursorPosition: point,
+      mouseButton: .left
+    ), let up = CGEvent(
+      mouseEventSource: nil,
+      mouseType: .leftMouseUp,
+      mouseCursorPosition: point,
+      mouseButton: .left
+    ) else {
+      throw MouseClickDeliveryError.eventCreationFailed
+    }
+    down.setIntegerValueField(.mouseEventClickState, value: Int64(press.clickState))
+    up.setIntegerValueField(.mouseEventClickState, value: Int64(press.clickState))
+    heldMouseButton = (point, press.clickState)
+    down.post(tap: .cghidEventTap)
+    usleep(UInt32(hold) * 1000)
+    // The record clears only after the up is posted: a signal that lands between the two
+    // would otherwise find nothing to release and exit with the button still down. A signal
+    // that lands after the post releases a button already up, which is harmless.
+    up.post(tap: .cghidEventTap)
+    heldMouseButton = nil
+  }
+}