fix(ios): surface a hinted unsupported error for synthesis gestures at admission

Removing macOS pinch from the capability matrix makes macOS pinch (and the already-excluded
rotate-gesture/transform-gesture on macOS/tvOS/physical iOS) fail fast in ensureGenericCommandReady
before reaching the runner. That left the runner's macOS-specific hint unreachable on the daemon
path, so callers only saw the generic "<cmd> is not supported on this device".

Add an optional unsupportedHint to the capability matrix and surface it at admission, so the
synthesis-only gestures fail fast (no runner round-trip) AND return an actionable hint pointing to
where they work (Android + iOS simulator). Applied to pinch / rotate-gesture / transform-gesture.

Addresses PR #645 review (P2: route macOS pinch to the hinted failure).

Author: thymikee

src/core/__tests__/capabilities.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { isCommandSupportedOnDevice } from '../capabilities.ts';
+import { isCommandSupportedOnDevice, unsupportedHintForDevice } from '../capabilities.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 
 const iosSimulator: DeviceInfo = {
@@ -360,3 +360,33 @@ test('unknown commands default to supported', () => {
   assert.equal(isCommandSupportedOnDevice('some-future-cmd', androidDevice), true);
   assert.equal(isCommandSupportedOnDevice('some-future-cmd', linuxDevice), true);
 });
+
+test('synthesis gestures carry an actionable unsupported hint at admission', () => {
+  // macOS / tvOS / physical iOS are rejected at admission; the hint redirects to where the
+  // two-finger synthesis path actually works, so callers do not just see a bare "not supported".
+  for (const command of ['pinch', 'rotate-gesture', 'transform-gesture']) {
+    assert.match(
+      unsupportedHintForDevice(command, macOsDevice) ?? '',
+      /multi-touch/i,
+      `${command} macOS hint`,
+    );
+    assert.match(
+      unsupportedHintForDevice(command, tvOsSimulator) ?? '',
+      /touch/i,
+      `${command} tvOS hint`,
+    );
+    assert.match(
+      unsupportedHintForDevice(command, iosDevice) ?? '',
+      /simulator/i,
+      `${command} iOS device hint`,
+    );
+    // Where the gesture IS supported there is nothing to hint.
+    assert.equal(
+      unsupportedHintForDevice(command, iosSimulator),
+      undefined,
+      `${command} iOS sim (supported) hint`,
+    );
+  }
+  // Commands without a hint hook return undefined (admission keeps its generic message).
+  assert.equal(unsupportedHintForDevice('tap', macOsDevice), undefined);
+});

src/core/capabilities.ts

@@ -12,6 +12,8 @@ export type CommandCapability = {
   android?: KindMatrix;
   linux?: KindMatrix;
   supports?: (device: DeviceInfo) => boolean;
+  /** Optional actionable hint surfaced when this command is rejected at admission for `device`. */
+  unsupportedHint?: (device: DeviceInfo) => string | undefined;
 };
 
 const isNotMacOs = (device: DeviceInfo): boolean => device.platform !== 'macos';
@@ -20,6 +22,19 @@ const isMacOsOrAppleSimulator = (device: DeviceInfo): boolean =>
 const isIosMobileSimulator = (device: DeviceInfo): boolean =>
   device.platform === 'ios' && device.kind === 'simulator' && device.target !== 'tv';
 
+// Two-finger gesture synthesis (RunnerSynthesizedGesture) is iOS-simulator-only (plus Android).
+// When such a gesture is rejected at admission, explain where it IS available so an agent can
+// redirect instead of getting a bare "not supported on this device".
+const synthesisGestureUnsupportedHint = (device: DeviceInfo): string | undefined => {
+  if (device.platform === 'macos')
+    return 'macOS automation has no multi-touch input — this gesture is supported on Android and the iOS simulator only.';
+  if (device.platform === 'ios' && device.target === 'tv')
+    return 'tvOS has no touch input — this gesture is supported on Android and the iOS simulator only.';
+  if (device.platform === 'ios' && device.kind === 'device')
+    return 'Two-finger gesture synthesis is iOS-simulator only — not available on physical iOS devices.';
+  return undefined;
+};
+
 // Linux desktop supports these commands via xdotool/ydotool + AT-SPI2.
 // Linux device kind is always 'device' (local desktop).
 const LINUX_DEVICE: KindMatrix = { device: true };
@@ -61,18 +76,21 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     // 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),
+    unsupportedHint: synthesisGestureUnsupportedHint,
   },
   'rotate-gesture': {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_NONE,
     supports: (device) => device.platform === 'android' || isIosMobileSimulator(device),
+    unsupportedHint: synthesisGestureUnsupportedHint,
   },
   'transform-gesture': {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_NONE,
     supports: (device) => device.platform === 'android' || isIosMobileSimulator(device),
+    unsupportedHint: synthesisGestureUnsupportedHint,
   },
   'app-switcher': {
     apple: { simulator: true, device: true },
@@ -240,6 +258,10 @@ export function isCommandSupportedOnDevice(command: string, device: DeviceInfo):
   return byPlatform[kind] === true;
 }
 
+export function unsupportedHintForDevice(command: string, device: DeviceInfo): string | undefined {
+  return COMMAND_CAPABILITY_MATRIX[command]?.unsupportedHint?.(device);
+}
+
 export function listCapabilityCommands(): string[] {
   return Object.keys(COMMAND_CAPABILITY_MATRIX).sort();
 }

src/daemon/request-generic-dispatch.ts

@@ -1,6 +1,6 @@
 import { dispatchCommand, type CommandFlags } from '../core/dispatch.ts';
 import { DAEMON_COMMAND_GROUPS, GESTURE_SUBCOMMAND_ERROR } from '../command-catalog.ts';
-import { isCommandSupportedOnDevice } from '../core/capabilities.ts';
+import { isCommandSupportedOnDevice, unsupportedHintForDevice } from '../core/capabilities.ts';
 import { SessionStore } from './session-store.ts';
 import type { DaemonCommandContext } from './context.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from './types.ts';
@@ -154,11 +154,13 @@ async function ensureGenericCommandReady(
   platformCommand: string,
 ): Promise<DaemonResponse | null> {
   if (!isCommandSupportedOnDevice(platformCommand, session.device)) {
+    const hint = unsupportedHintForDevice(platformCommand, session.device);
     return {
       ok: false,
       error: {
         code: 'UNSUPPORTED_OPERATION',
         message: `${platformCommand} is not supported on this device`,
+        ...(hint ? { hint } : {}),
       },
     };
   }