fix(ios): fail-fast macOS pinch + align capability/docs with synthesis-only

Follow-through for removing the macOS coordinate pinch path (the runner now returns
UNSUPPORTED_OPERATION for macOS pinch): reject it at admission instead of round-tripping.

- capabilities.ts: pinch now matches rotate-gesture/transform-gesture (Android + iOS
  simulator only); macOS dropped. Removes the now-unused isMacOsOrMobileAppleSimulator helper.
- capabilities.test.ts: pinch expected unsupported on macOS and tvOS.
- website/docs/docs/commands.md: pinch listed for Android + iOS simulators only (removed from
  the macOS app-session list); documents that iOS rotate ignores the optional velocity arg
  (synthesis uses a fixed duration; direction comes from the sign of degrees).

Addresses PR #645 review HIGH #2 and MEDIUM #3.

Author: thymikee

src/core/__tests__/capabilities.test.ts

@@ -74,7 +74,8 @@ test('device capability matrix stays consistent across shared command groups', (
         { device: iosSimulator, expected: true, label: 'on iOS sim' },
         { device: iosDevice, expected: false, label: 'on iOS device' },
         { device: androidDevice, expected: true, label: 'on Android' },
-        { device: macOsDevice, expected: true, label: 'on macOS' },
+        { device: macOsDevice, expected: false, label: 'on macOS' },
+        { device: tvOsSimulator, expected: false, label: 'on tvOS simulator' },
       ],
     },
     {
@@ -233,7 +234,6 @@ test('macOS supports the Apple runner interaction core but excludes mobile-only
       'logs',
       'network',
       'open',
-      'pinch',
       'perf',
       'press',
       'record',
@@ -255,6 +255,7 @@ test('macOS supports the Apple runner interaction core but excludes mobile-only
       'home',
       'install',
       'install-from-source',
+      'pinch',
       'push',
       'reinstall',
       'rotate',

src/core/capabilities.ts

@@ -17,8 +17,6 @@ export type CommandCapability = {
 const isNotMacOs = (device: DeviceInfo): boolean => device.platform !== 'macos';
 const isMacOsOrAppleSimulator = (device: DeviceInfo): boolean =>
   device.platform === 'macos' || device.kind === 'simulator';
-const isMacOsOrMobileAppleSimulator = (device: DeviceInfo): boolean =>
-  device.platform === 'macos' || (device.kind === 'simulator' && device.target !== 'tv');
 const isIosMobileSimulator = (device: DeviceInfo): boolean =>
   device.platform === 'ios' && device.kind === 'simulator' && device.target !== 'tv';
 
@@ -55,12 +53,14 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     supports: (device) => device.platform === 'android' || isMacOsOrAppleSimulator(device),
   },
   pinch: {
-    // macOS desktop targets report kind=device, so this stays enabled here and the
-    // supports() guard excludes iOS physical devices.
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_NONE,
-    supports: (device) => device.platform === 'android' || isMacOsOrMobileAppleSimulator(device),
+    // iOS-simulator-only (plus Android): pinch is driven by the two-finger XCTest synthesis
+    // path (RunnerSynthesizedGesture), which is iOS-only. macOS has no multi-touch synthesis, so
+    // it is excluded and fails fast at admission rather than round-tripping to an unsupported
+    // runner. Matches rotate-gesture / transform-gesture.
+    supports: (device) => device.platform === 'android' || isIosMobileSimulator(device),
   },
   'rotate-gesture': {
     apple: { simulator: true, device: true },

website/docs/docs/commands.md

@@ -158,7 +158,7 @@ agent-device snapshot -i --platform apple --target desktop
 - Status-item apps often expose little or no useful UI through the default macOS `app` surface. Prefer `--surface menubar` for discovery when the app lives in the top menu bar.
 - Use `frontmost-app`, `desktop`, and `menubar` mainly for `snapshot`, `get`, `is`, and `wait`.
 - If you inspect with `desktop` or `menubar` and then need to click or fill inside one app, open that app in a normal `app` session.
-- macOS also supports `clipboard read|write`, `trigger-app-event`, `logs`, `network dump`, `alert`, `gesture pinch` in app sessions, `settings appearance`, and `settings permission <grant|reset> <accessibility|screen-recording|input-monitoring>`.
+- macOS also supports `clipboard read|write`, `trigger-app-event`, `logs`, `network dump`, `alert`, `settings appearance`, and `settings permission <grant|reset> <accessibility|screen-recording|input-monitoring>`.
 - In macOS app sessions, `screenshot` captures the target app window bounds rather than the full desktop.
 - Prefer selector or `@ref`-driven interactions on macOS. Window position can shift between runs, so raw x/y point commands are less stable than snapshot-derived targets.
 - Use `click --button secondary` for context menus on macOS, then run `snapshot -i` again.
@@ -302,8 +302,8 @@ done
 ```
 
 `longpress` is supported on iOS and Android.
-`gesture pinch` is supported on Android, Apple simulators, and macOS app sessions.
-`gesture rotate` is supported on Android and iOS simulator app sessions. Use `rotate` for device orientation.
+`gesture pinch` is supported on Android and iOS simulator app sessions.
+`gesture rotate` is supported on Android and iOS simulator app sessions. Use `rotate` for device orientation. On iOS the optional `velocity` argument is ignored — rotation is synthesized over a fixed duration and direction is taken from the sign of `degrees`.
 `gesture transform` is supported on Android and iOS simulator app sessions.
 
 ## Find (semantic)