feat(ios): add pinch gesture for zoom on iOS simulators (#11)

- Add 'pinch' CLI command: pinch <scale> [x y] (scale > 1 zoom in, < 1 zoom out)
- Implement in dispatch, runner-client (RunnerCommand + scale param), Swift runner
- Use double-tap + drag workaround for map zoom (tap center, drag up/down)
  instead of XCUITest pinch(withScale:velocity:) which pans on map views
- Update commands.md and agent-device skill with pinch usage and best practices
- Fix skill reference: recording.md -> video-recording.md

Co-authored-by: Jano Detzel <jano.detzel@ewe-go.de>

Author: janodetzel

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -305,6 +305,12 @@ final class RunnerTests: XCTestCase {
       }
       let buttonLabels = alert.buttons.allElementsBoundByIndex.map { $0.label }
       return Response(ok: true, data: DataPayload(message: alert.label, items: buttonLabels))
+    case .pinch:
+      guard let scale = command.scale, scale > 0 else {
+        return Response(ok: false, error: ErrorPayload(message: "pinch requires scale > 0"))
+      }
+      pinch(app: activeApp, scale: scale, x: command.x, y: command.y)
+      return Response(ok: true, data: DataPayload(message: "pinched"))
     }
   }
 
@@ -372,6 +378,39 @@ final class RunnerTests: XCTestCase {
     }
   }
 
+  private func pinch(app: XCUIApplication, scale: Double, x: Double?, y: Double?) {
+    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)
+  }
+
   private func aggregatedLabel(for element: XCUIElement, depth: Int = 0) -> String? {
     if depth > 2 { return nil }
     let text = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -718,6 +757,7 @@ enum CommandType: String, Codable {
   case home
   case appSwitcher
   case alert
+  case pinch
   case shutdown
 }
 
@@ -736,6 +776,7 @@ struct Command: Codable {
   let x: Double?
   let y: Double?
   let direction: SwipeDirection?
+  let scale: Double?
   let interactiveOnly: Bool?
   let compact: Bool?
   let depth: Int?

skills/agent-device/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-device
-description: Automates mobile and simulator interactions for iOS and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info on mobile devices or simulators.
+description: Automates mobile and simulator interactions for iOS and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, pinching, or extracting UI info on mobile devices or simulators.
 ---
 
 # Mobile Automation with agent-device
@@ -102,6 +102,8 @@ agent-device type "text"               # Type into focused field
 agent-device press 300 500             # Tap by coordinates
 agent-device long-press 300 500 800    # Long press (where supported)
 agent-device scroll down 0.5
+agent-device pinch 2.0              # Zoom in 2x (iOS simulator)
+agent-device pinch 0.5 200 400     # Zoom out at coordinates (iOS simulator)
 agent-device back
 agent-device home
 agent-device app-switcher
@@ -139,6 +141,7 @@ agent-device apps --platform android --user-installed
 
 ## Best practices
 
+- Pinch (`pinch <scale> [x y]`) is supported on iOS simulators only; scale > 1 zooms in, < 1 zooms out.
 - Always snapshot right before interactions; refs invalidate on UI changes.
 - Prefer `snapshot -i` to reduce output size.
 - On iOS, `xctest` is the default and does not require Accessibility permission.
@@ -153,7 +156,7 @@ agent-device apps --platform android --user-installed
 - [references/snapshot-refs.md](references/snapshot-refs.md)
 - [references/session-management.md](references/session-management.md)
 - [references/permissions.md](references/permissions.md)
-- [references/recording.md](references/recording.md)
+- [references/video-recording.md](references/video-recording.md)
 - [references/coordinate-system.md](references/coordinate-system.md)
 
 ## Missing features roadmap (high level)

src/core/dispatch.ts

@@ -224,6 +224,24 @@ export async function dispatchCommand(
       await interactor.scrollIntoView(text);
       return { text };
     }
+    case 'pinch': {
+      const scale = Number(positionals[0]);
+      const x = positionals[1] ? Number(positionals[1]) : undefined;
+      const y = positionals[2] ? Number(positionals[2]) : undefined;
+      if (Number.isNaN(scale) || scale <= 0) {
+        throw new AppError('INVALID_ARGS', 'pinch requires scale > 0');
+      }
+      if (device.platform === 'ios' && device.kind === 'simulator') {
+        await runIosRunnerCommand(
+          device,
+          { command: 'pinch', scale, x, y, appBundleId: context?.appBundleId },
+          { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
+        );
+      } else {
+        throw new AppError('UNSUPPORTED_OPERATION', 'pinch is only supported on iOS simulators');
+      }
+      return { scale, x, y };
+    }
     case 'screenshot': {
       const path = outPath ?? `./screenshot-${Date.now()}.png`;
       await interactor.screenshot(path);

src/platforms/ios/runner-client.ts

@@ -20,13 +20,15 @@ export type RunnerCommand = {
     | 'home'
     | 'appSwitcher'
     | 'alert'
+    | 'pinch'
     | 'shutdown';
   appBundleId?: string;
   text?: string;
   action?: 'get' | 'accept' | 'dismiss';
   x?: number;
   y?: number;
   direction?: 'up' | 'down' | 'left' | 'right';
+  scale?: number;
   interactiveOnly?: boolean;
   compact?: boolean;
   depth?: number;

website/docs/docs/commands.md

@@ -34,6 +34,8 @@ agent-device type "text"
 agent-device press 300 500
 agent-device long-press 300 500 800
 agent-device scroll down 0.5
+agent-device pinch 2.0          # zoom in 2x
+agent-device pinch 0.5 200 400 # zoom out at coordinates
 ```
 
 ## Find (semantic)