fix: preserve gesture compatibility contracts

Author: thymikee

apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h

@@ -4,6 +4,13 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface RunnerSynthesizedGesture : NSObject
 
++ (NSString * _Nullable)synthesizeSwipeWithApplication:(id)application
+                                                    x:(double)x
+                                                    y:(double)y
+                                                   x2:(double)x2
+                                                   y2:(double)y2
+                                            durationMs:(double)durationMs;
+
 + (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
                                                              x:(double)x
                                                              y:(double)y

apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m

@@ -40,6 +40,12 @@ typedef id (*RunnerDragPointerPathFactory)(
 static NSString * _Nullable RunnerRequireClass(Class cls, NSString *className);
 static NSString * _Nullable RunnerRequireSelector(Class cls, SEL selector, NSString *selectorName);
 static NSString * _Nullable RunnerRequireApplicationSelector(id application, SEL selector, NSString *selectorName);
+static id RunnerSwipePointerPath(
+  const RunnerXCTestEventBridge *bridge,
+  CGPoint start,
+  CGPoint end,
+  double durationMs
+);
 static id RunnerContinuousDragPointerPath(
   const RunnerXCTestEventBridge *bridge,
   CGPoint start,
@@ -54,13 +60,38 @@ static id RunnerContinuousDragPointerPath(
   NSString *recordName,
   RunnerDragPointerPathFactory pathFactory
 );
+// XCTest's proven swipe profile reaches the endpoint in 100 ms, then holds for the planned
+// fling duration. Fast movement is what lets UIKit distinguish a fling from a timed pan.
+static const NSTimeInterval RunnerSwipeMovementDurationSeconds = 0.1;
 static id RunnerTapPointerPath(
   const RunnerXCTestEventBridge *bridge,
   CGPoint point
 );
 
 @implementation RunnerSynthesizedGesture
 
++ (NSString * _Nullable)synthesizeSwipeWithApplication:(id)application
+                                                    x:(double)x
+                                                    y:(double)y
+                                                   x2:(double)x2
+                                                   y2:(double)y2
+                                            durationMs:(double)durationMs {
+  @try {
+    return RunnerTrySynthesizeDrag(
+      application,
+      CGPointMake(x, y),
+      CGPointMake(x2, y2),
+      durationMs,
+      @"agent-device-swipe",
+      RunnerSwipePointerPath
+    );
+  } @catch (NSException *exception) {
+    NSString *name = exception.name ?: @"NSException";
+    NSString *reason = exception.reason ?: @"private XCTest event synthesis failed";
+    return [NSString stringWithFormat:@"%@: %@", name, reason];
+  }
+}
+
 + (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
                                                              x:(double)x
                                                              y:(double)y
@@ -352,6 +383,33 @@ + (NSString * _Nullable)trySynthesizeTapWithApplication:(id)application
 }
 
 
+static id RunnerSwipePointerPath(
+  const RunnerXCTestEventBridge *bridge,
+  CGPoint start,
+  CGPoint end,
+  double durationMs
+) {
+  id path =
+    ((RunnerMsgSendInitPath)objc_msgSend)([bridge->pathClass alloc], bridge->initPathSelector, start, 0.0);
+  if (path == nil) {
+    return nil;
+  }
+
+  NSTimeInterval durationSeconds = durationMs / 1000.0;
+  ((RunnerMsgSendPathMove)objc_msgSend)(
+    path,
+    bridge->moveSelector,
+    end,
+    RunnerSwipeMovementDurationSeconds
+  );
+  ((RunnerMsgSendPathOffset)objc_msgSend)(
+    path,
+    bridge->liftSelector,
+    RunnerSwipeMovementDurationSeconds + durationSeconds
+  );
+  return path;
+}
+
 static id RunnerContinuousDragPointerPath(
   const RunnerXCTestEventBridge *bridge,
   CGPoint start,

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

@@ -133,6 +133,24 @@ extension RunnerTests {
     return Response(ok: true, data: data)
   }
 
+  /// Gesture plans already return canonical centroid endpoints from the portable runtime.
+  /// Keep runner timing/fallback diagnostics, but do not leak the coordinate-drag adapter's
+  /// visualization frame into only the fast-fling response shape.
+  private func canonicalPlannedGestureResponse(_ response: Response) -> Response {
+    guard response.ok, let data = response.data else { return response }
+    return Response(
+      ok: true,
+      data: DataPayload(
+        message: data.message,
+        gestureStartUptimeMs: data.gestureStartUptimeMs,
+        gestureEndUptimeMs: data.gestureEndUptimeMs,
+        gestureFallback: data.gestureFallback,
+        gestureFallbackMessage: data.gestureFallbackMessage,
+        gestureFallbackHint: data.gestureFallbackHint
+      )
+    )
+  }
+
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
   func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
     let response = gestureResponse(
@@ -165,6 +183,42 @@ extension RunnerTests {
     XCTAssertEqual(response.data?.maestroNonHittableCoordinateFallbackUsed, true)
   }
 
+  func testCanonicalPlannedGestureResponseOmitsDragFrameAndPreservesDiagnostics() {
+    let response = gestureResponse(
+      message: "fling",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      frame: .drag(
+        DragVisualizationFrame(
+          x: 160,
+          y: 150,
+          x2: 40,
+          y2: 150,
+          referenceWidth: 200,
+          referenceHeight: 300
+        )
+      ),
+      fallback: GestureFallback(
+        strategy: "xctest-coordinate-drag",
+        message: "Private synthesis unavailable",
+        hint: "Using XCTest coordinate fallback."
+      )
+    )
+
+    let canonical = canonicalPlannedGestureResponse(response)
+
+    XCTAssertEqual(canonical.data?.gestureStartUptimeMs, 1)
+    XCTAssertEqual(canonical.data?.gestureEndUptimeMs, 2)
+    XCTAssertEqual(canonical.data?.gestureFallback, "xctest-coordinate-drag")
+    XCTAssertEqual(canonical.data?.gestureFallbackMessage, "Private synthesis unavailable")
+    XCTAssertEqual(canonical.data?.gestureFallbackHint, "Using XCTest coordinate fallback.")
+    XCTAssertNil(canonical.data?.x)
+    XCTAssertNil(canonical.data?.y)
+    XCTAssertNil(canonical.data?.x2)
+    XCTAssertNil(canonical.data?.y2)
+    XCTAssertNil(canonical.data?.referenceWidth)
+    XCTAssertNil(canonical.data?.referenceHeight)
+  }
+
   func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
     let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
     let response = Response(ok: true, data: DataPayload(message: "tapped"))
@@ -1482,8 +1536,27 @@ extension RunnerTests {
           error: ErrorPayload(code: "INVALID_ARGS", message: validationError)
         )
       }
+      if plannedGestureExecution(for: plan) == .fastSwipe {
+        // Validation above guarantees a non-empty, single-pointer path for this execution kind.
+        let first = plan.pointers[0].samples.first!.point
+        let last = plan.pointers[0].samples.last!.point
+        return canonicalPlannedGestureResponse(
+          executeDragGesture(
+            activeApp: activeApp,
+            x: first.x,
+            y: first.y,
+            x2: last.x,
+            y2: last.y,
+            durationMs: plan.durationMs,
+            synthesized: true,
+            message: plan.intent,
+            synthesizedPolicyKind: .synthesizedDrag,
+            synthesizedProfile: .fastSwipe
+          )
+        )
+      }
       let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-        plannedGesture(app: activeApp, plan: plan)
+        sampledPlannedGesture(app: activeApp, plan: plan)
       }
       if let response = unsupportedResponse(for: outcome) {
         return response
@@ -1513,7 +1586,8 @@ extension RunnerTests {
     synthesized: Bool,
     message: String,
     synthesizedContext: SynthesizedCoordinateContext? = nil,
-    synthesizedPolicyKind: SynthesizedGesturePolicyKind
+    synthesizedPolicyKind: SynthesizedGesturePolicyKind,
+    synthesizedProfile: SynthesizedDragProfile = .continuous
   ) -> Response {
     let commandName = dragCommandName(message: message)
     guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
@@ -1531,7 +1605,8 @@ extension RunnerTests {
       durationMs: durationMs,
       message: message,
       context: synthesizedContext,
-      policyKind: synthesizedPolicyKind
+      policyKind: synthesizedPolicyKind,
+      profile: synthesizedProfile
     ) {
       return synthesizedResponse
     }
@@ -1555,6 +1630,7 @@ extension RunnerTests {
           x2: dragPoints.x2,
           y2: dragPoints.y2,
           durationMs: durationMs,
+          profile: synthesizedProfile,
           context: context
         )
       }
@@ -1596,7 +1672,8 @@ extension RunnerTests {
     durationMs: Double?,
     message: String,
     context: SynthesizedCoordinateContext?,
-    policyKind: SynthesizedGesturePolicyKind
+    policyKind: SynthesizedGesturePolicyKind,
+    profile: SynthesizedDragProfile
   ) -> Response? {
 #if os(iOS)
     let policy = synthesizedGesturePolicy(policyKind)
@@ -1648,6 +1725,7 @@ extension RunnerTests {
         x2: plan.points.x2,
         y2: plan.points.y2,
         durationMs: durationMs,
+        profile: profile,
         context: plan.context
       )
     }

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

@@ -13,6 +13,16 @@ private enum RunnerInterfaceOrientation {
 }
 
 extension RunnerTests {
+  enum PlannedGestureExecution: Equatable {
+    case fastSwipe
+    case sampled
+  }
+
+  enum SynthesizedDragProfile {
+    case continuous
+    case fastSwipe
+  }
+
   struct TouchVisualizationFrame {
     let x: Double
     let y: Double
@@ -775,6 +785,7 @@ extension RunnerTests {
     x2: Double,
     y2: Double,
     durationMs: Double,
+    profile: SynthesizedDragProfile = .continuous,
     context: SynthesizedCoordinateContext? = nil
   ) -> RunnerInteractionOutcome {
 #if os(iOS)
@@ -794,14 +805,26 @@ extension RunnerTests {
     let frame = context.referenceFrame
     let start = nativeSynthesizedPoint(orientedX: x, orientedY: y, in: frame, interfaceOrientation: orientation)
     let end = nativeSynthesizedPoint(orientedX: x2, orientedY: y2, in: frame, interfaceOrientation: orientation)
-    let message = RunnerSynthesizedGesture.synthesizeContinuousDrag(
-      withApplication: app,
-      x: Double(start.x),
-      y: Double(start.y),
-      x2: Double(end.x),
-      y2: Double(end.y),
-      durationMs: durationMs
-    )
+    let message = switch profile {
+    case .continuous:
+      RunnerSynthesizedGesture.synthesizeContinuousDrag(
+        withApplication: app,
+        x: Double(start.x),
+        y: Double(start.y),
+        x2: Double(end.x),
+        y2: Double(end.y),
+        durationMs: durationMs
+      )
+    case .fastSwipe:
+      RunnerSynthesizedGesture.synthesizeSwipe(
+        withApplication: app,
+        x: Double(start.x),
+        y: Double(start.y),
+        x2: Double(end.x),
+        y2: Double(end.y),
+        durationMs: durationMs
+      )
+    }
     if let message {
       return .unsupported(
         message: message,
@@ -1221,7 +1244,11 @@ extension RunnerTests {
     return nil
   }
 
-  func plannedGesture(
+  func plannedGestureExecution(for plan: RunnerGesturePlan) -> PlannedGestureExecution {
+    plan.topology == "single" && plan.intent == "fling" ? .fastSwipe : .sampled
+  }
+
+  func sampledPlannedGesture(
     app: XCUIApplication,
     plan: RunnerGesturePlan
   ) -> RunnerInteractionOutcome {
@@ -1448,6 +1475,28 @@ extension RunnerTests {
     )
   }
 
+  func testSinglePointerFlingUsesFastSwipeExecution() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"fling","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertEqual(plannedGestureExecution(for: plan), .fastSwipe)
+  }
+
+  func testSinglePointerTimedPanUsesSampledExecution() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":250,"point":{"x":100,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertEqual(plannedGestureExecution(for: plan), .sampled)
+  }
+
   func testDesktopScrollWheelDeltasMapDirections() throws {
     XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "up", pixels: 120)).vertical, 120)
     XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "down", pixels: 120)).vertical, -120)

src/commands/interaction/metadata.ts

@@ -204,10 +204,10 @@ const gestureFields = {
   distance: integerField('Fling distance.', { min: 0 }),
   scale: numberField('Pinch or transform scale.'),
   degrees: numberField('Rotation in degrees.'),
-  velocity: integerField('Deprecated: rotation pacing is derived from degrees.', { min: 0 }),
+  velocity: numberField('Deprecated: rotation pacing is derived from degrees; must be non-zero.'),
   durationMs: integerField(
     'Pan/transform duration. Deprecated on swipe/fling; timed movement is a pan.',
-    { min: 0 },
+    { min: 16, max: 10_000 },
   ),
   pointerCount: integerField('Pan touch pointer count (1 or 2).', { min: 1, max: 2 }),
 };

src/contracts/gesture-input.test.ts

@@ -42,3 +42,20 @@ test('structured gesture input rejects durations outside the planner range', ()
     );
   }
 });
+
+test('deprecated rotate velocity accepts finite non-zero compatibility values', () => {
+  for (const velocity of [-2.5, -1, 0.25, 3]) {
+    assert.deepEqual(readGesturePayload({ kind: 'rotate', degrees: 45, velocity }), {
+      kind: 'rotate',
+      degrees: 45,
+      origin: undefined,
+      velocity,
+    });
+  }
+
+  for (const velocity of [0, Number.NaN, Number.POSITIVE_INFINITY]) {
+    assert.throws(() => readGesturePayload({ kind: 'rotate', degrees: 45, velocity }), {
+      code: 'INVALID_ARGS',
+    });
+  }
+});