fix(ios): unify multi-touch gestures on two-finger synthesis + hinted unsupported errors

Make RunnerSynthesizedGesture the single iOS multi-touch engine and drop the older
incompatible models:

- rotateGesture now drives the two-finger XCTest synthesis path (dx=dy=0, scale=1,
  degrees), mirroring the pinch migration in #634. The native XCUIElement.rotate(withVelocity:)
  injected a single synthetic rotation that React Native's rotation recognizer did not read
  reliably; synthesis fixes it. velocity is ignored on iOS (kept in the wire contract for
  compatibility; rotation direction comes from the sign of degrees).
- pinch is now synthesis on iOS and a clear UNSUPPORTED_OPERATION on tvOS/macOS. The macOS
  coordinate double-tap+drag heuristic (performCoordinatePinch) is removed: synthesis is
  iOS-only, so macOS multi-touch is reported honestly as unsupported rather than approximated.
- RunnerInteractionOutcome.unsupported now carries an actionable hint, mapped to ErrorPayload.hint
  (#639). Every unsupported gesture/tvOS path returns a concise message plus a next-step hint
  (existing messages kept verbatim).

Net: on iOS, pinch/rotate/transform all flow through one synthesis primitive. swipe/scroll/pan/
fling remain single-finger drags (correct, unchanged).

Coverage: examples/test-app/replays/gesture-lab.ad exercises pinch + rotate against the gesture
lab and asserts "pinch changed yes" / "rotate changed yes".

Author: thymikee

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -17,10 +17,10 @@ extension RunnerTests {
     switch outcome {
     case .performed:
       return nil
-    case .unsupported(let message):
+    case .unsupported(let message, let hint):
       return Response(
         ok: false,
-        error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message)
+        error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message, hint: hint)
       )
     }
   }

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -1604,13 +1604,51 @@ extension RunnerTests {
       degrees: 0,
       durationMs: 300
     )
+#elseif os(tvOS)
+    return .unsupported(
+      message: "pinch is not supported on tvOS",
+      hint: "tvOS has no touch input; pinch requires a touchscreen (run on iOS)."
+    )
 #else
-    return performCoordinatePinch(app: app, scale: scale, x: x, y: y)
+    return .unsupported(
+      message: "pinch is not supported on macOS",
+      hint: "macOS automation has no multi-touch input; pinch requires a touchscreen (run on iOS)."
+    )
 #endif
   }
 
   func rotateGesture(app: XCUIApplication, degrees: Double, x: Double?, y: Double?, velocity: Double) -> RunnerInteractionOutcome {
-    return performCoordinateRotateGesture(app: app, degrees: degrees, x: x, y: y, velocity: velocity)
+#if os(iOS)
+    // Drive the two-finger XCTest synthesis path (the same one pinch/transformGesture use, #634)
+    // with zero translation/scale so React Native's rotation recognizer actually fires. The native
+    // XCUIElement.rotate(withVelocity:) injects a single synthetic rotation that RN's gesture
+    // handler does not read reliably — the same class of problem #629/#634 fixed for pinch.
+    // velocity is unused on iOS (synthesis speed is governed by durationMs); the wire contract
+    // keeps it for compatibility and direction is carried entirely by the sign of `degrees`.
+    let frame = interactionRoot(app: app).frame
+    let centerX = x ?? Double(frame.midX)
+    let centerY = y ?? Double(frame.midY)
+    return transformGesture(
+      app: app,
+      x: centerX,
+      y: centerY,
+      dx: 0,
+      dy: 0,
+      scale: 1,
+      degrees: degrees,
+      durationMs: 300
+    )
+#elseif os(tvOS)
+    return .unsupported(
+      message: "rotate-gesture is not supported on tvOS",
+      hint: "tvOS has no touch input; rotation gestures require a touchscreen (run on iOS)."
+    )
+#else
+    return .unsupported(
+      message: "rotate-gesture is not supported on macOS",
+      hint: "macOS automation has no multi-touch input; rotation gestures require a touchscreen (run on iOS)."
+    )
+#endif
   }
 
   func transformGesture(
@@ -1636,13 +1674,22 @@ extension RunnerTests {
       radius: transformGestureRadius(frame: target.frame, scale: scale),
       durationMs: durationMs
     ) {
-      return .unsupported(message)
+      return .unsupported(
+        message: message,
+        hint: "This gesture uses private XCTest event-synthesis APIs; rebuild the runner with a supported Xcode (these APIs can change across Xcode versions)."
+      )
     }
     return .performed
 #elseif os(tvOS)
-    return .unsupported("transformGesture is not supported on tvOS")
+    return .unsupported(
+      message: "transformGesture is not supported on tvOS",
+      hint: "tvOS has no touch input; transform gestures require a touchscreen (run on iOS)."
+    )
 #else
-    return .unsupported("transformGesture is not supported on macOS")
+    return .unsupported(
+      message: "transformGesture is not supported on macOS",
+      hint: "macOS automation has no multi-touch input; transform gestures require a touchscreen (run on iOS)."
+    )
 #endif
   }
 
@@ -1654,57 +1701,6 @@ extension RunnerTests {
     return min(max(scaleAdjustedRadius, 48.0), shorterSide * 0.35)
   }
 
-  private func performCoordinatePinch(app: XCUIApplication, scale: Double, x: Double?, y: Double?) -> RunnerInteractionOutcome {
-#if os(tvOS)
-    return .unsupported("pinch is not supported on tvOS")
-#else
-    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
-
-    // Use double-tap + drag gesture for reliable map zoom
-    // Zoom in (scale > 1): tap then drag UP
-    // Zoom out (scale < 1): tap then drag DOWN
-
-    // Determine center point (use provided x/y or screen center)
-    let centerX = x.map { $0 / target.frame.width } ?? 0.5
-    let centerY = y.map { $0 / target.frame.height } ?? 0.5
-    let center = target.coordinate(withNormalizedOffset: CGVector(dx: centerX, dy: centerY))
-
-    // Calculate drag distance based on scale (clamped to reasonable range)
-    // Larger scale = more drag distance
-    let dragAmount: CGFloat
-    if scale > 1.0 {
-      // Zoom in: drag up (negative Y direction in normalized coords)
-      dragAmount = min(0.4, CGFloat(scale - 1.0) * 0.2)
-    } else {
-      // Zoom out: drag down (positive Y direction)
-      dragAmount = min(0.4, CGFloat(1.0 - scale) * 0.4)
-    }
-
-    let endY = scale > 1.0 ? (centerY - Double(dragAmount)) : (centerY + Double(dragAmount))
-    let endPoint = target.coordinate(withNormalizedOffset: CGVector(dx: centerX, dy: max(0.1, min(0.9, endY))))
-
-    // Tap first (first tap of double-tap)
-    center.tap()
-
-    // Immediately press and drag (second tap + drag)
-    center.press(forDuration: 0.05, thenDragTo: endPoint)
-    return .performed
-#endif
-  }
-
-  private func performCoordinateRotateGesture(app: XCUIApplication, degrees: Double, x: Double?, y: Double?, velocity: Double) -> RunnerInteractionOutcome {
-#if os(iOS)
-    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
-    let radians = CGFloat(degrees * .pi / 180.0)
-    target.rotate(radians, withVelocity: CGFloat(velocity))
-    return .performed
-#elseif os(tvOS)
-    return .unsupported("rotate-gesture is not supported on tvOS")
-#else
-    return .unsupported("rotate-gesture is not supported on macOS")
-#endif
-  }
-
   private func interactionRoot(app: XCUIApplication) -> XCUIElement {
     let windows = app.windows.allElementsBoundByIndex
     if let window = windows.first(where: { $0.exists && !$0.frame.isEmpty }) {
@@ -1715,7 +1711,10 @@ extension RunnerTests {
 
   private func performCoordinateTap(app: XCUIApplication, x: Double, y: Double) -> RunnerInteractionOutcome {
 #if os(tvOS)
-    return .unsupported("coordinate tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element")
+    return .unsupported(
+      message: "coordinate tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then select it."
+    )
 #else
     interactionCoordinate(app: app, x: x, y: y).tap()
     return .performed
@@ -1724,7 +1723,10 @@ extension RunnerTests {
 
   private func performCoordinateDoubleTap(app: XCUIApplication, x: Double, y: Double) -> RunnerInteractionOutcome {
 #if os(tvOS)
-    return .unsupported("coordinate double tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element")
+    return .unsupported(
+      message: "coordinate double tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then select it."
+    )
 #else
     interactionCoordinate(app: app, x: x, y: y).doubleTap()
     return .performed
@@ -1733,7 +1735,10 @@ extension RunnerTests {
 
   private func performCoordinateLongPress(app: XCUIApplication, x: Double, y: Double, duration: TimeInterval) -> RunnerInteractionOutcome {
 #if os(tvOS)
-    return .unsupported("coordinate long press is not supported on tvOS; move focus with swipe or scroll, then long-select the focused element")
+    return .unsupported(
+      message: "coordinate long press is not supported on tvOS; move focus with swipe or scroll, then long-select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then long-select it."
+    )
 #else
     interactionCoordinate(app: app, x: x, y: y).press(forDuration: duration)
     return .performed
@@ -1749,7 +1754,10 @@ extension RunnerTests {
     holdDuration: TimeInterval
   ) -> RunnerInteractionOutcome {
 #if os(tvOS)
-    return .unsupported("coordinate drag is not supported on tvOS")
+    return .unsupported(
+      message: "coordinate drag is not supported on tvOS",
+      hint: "tvOS has no coordinate input; use remote-driven swipe/scroll to move focus instead."
+    )
 #else
     let start = interactionCoordinate(app: app, x: x, y: y)
     let end = interactionCoordinate(app: app, x: x2, y: y2)

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TvRemote.swift

@@ -2,7 +2,9 @@ import XCTest
 
 enum RunnerInteractionOutcome {
   case performed
-  case unsupported(String)
+  /// A capability/state gap, surfaced to the caller as an UNSUPPORTED_OPERATION error.
+  /// `hint` is an optional actionable next step (mapped to ErrorPayload.hint).
+  case unsupported(message: String, hint: String?)
 }
 
 enum TvRemoteButton {
@@ -85,7 +87,10 @@ extension RunnerTests {
   func selectFocusedTvElement(app: XCUIApplication, point: CGPoint, action: String) -> RunnerInteractionOutcome? {
 #if os(tvOS)
     guard let focused = focusedTvElement(app: app), !focused.frame.isEmpty, focused.frame.contains(point) else {
-      return .unsupported("\(action) is supported on tvOS only when the requested point is inside the focused element")
+      return .unsupported(
+        message: "\(action) is supported on tvOS only when the requested point is inside the focused element",
+        hint: "Move focus with swipe or scroll until the target is focused, then retry."
+      )
     }
     _ = pressTvRemote(.select)
     return .performed
@@ -97,7 +102,10 @@ extension RunnerTests {
   func longSelectFocusedTvElement(app: XCUIApplication, point: CGPoint, duration: TimeInterval) -> RunnerInteractionOutcome? {
 #if os(tvOS)
     guard let focused = focusedTvElement(app: app), !focused.frame.isEmpty, focused.frame.contains(point) else {
-      return .unsupported("long press is supported on tvOS only when the requested point is inside the focused element")
+      return .unsupported(
+        message: "long press is supported on tvOS only when the requested point is inside the focused element",
+        hint: "Move focus with swipe or scroll until the target is focused, then retry."
+      )
     }
     _ = pressTvRemote(.select, duration: duration)
     return .performed
@@ -108,7 +116,10 @@ extension RunnerTests {
 
   private func performElementTap(_ element: XCUIElement) -> RunnerInteractionOutcome {
 #if os(tvOS)
-    return .unsupported("element tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element")
+    return .unsupported(
+      message: "element tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
+      hint: "Use swipe/scroll to move focus to the target, then select it; tvOS has no coordinate tap."
+    )
 #else
     let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
       element.tap()
@@ -118,7 +129,7 @@ extension RunnerTests {
       if isPostTapElementDisappearance(exceptionMessage) {
         return .performed
       }
-      return .unsupported("element tap failed: \(exceptionMessage)")
+      return .unsupported(message: "element tap failed: \(exceptionMessage)", hint: nil)
     }
     return .performed
 #endif
@@ -132,7 +143,10 @@ extension RunnerTests {
   private func selectFocusedTvElement(app: XCUIApplication, element: XCUIElement, action: String) -> RunnerInteractionOutcome? {
 #if os(tvOS)
     guard tvFocusedElementMatches(app: app, target: element) else {
-      return .unsupported("\(action) is supported on tvOS only when the requested element is focused")
+      return .unsupported(
+        message: "\(action) is supported on tvOS only when the requested element is focused",
+        hint: "Move focus to the target element first, then retry."
+      )
     }
     _ = pressTvRemote(.select)
     return .performed