refactor: tighten unified gesture boundaries

Author: thymikee

android-multitouch-helper/README.md

@@ -21,7 +21,6 @@ sh ./scripts/build-android-multitouch-helper.sh "$VERSION" .tmp/android-multitou
 PAYLOAD_JSON='{
   "protocol":"android-multitouch-helper-v1",
   "kind":"transform",
-  "intent":"transform",
   "durationMs":32,
   "pointers":[
     {"pointerId":0,"samples":[{"offsetMs":0,"x":120,"y":180},{"offsetMs":16,"x":130,"y":175},{"offsetMs":32,"x":140,"y":170}]},

docs/adr/0013-unified-gesture-plans.md

@@ -61,17 +61,23 @@ Platform adapters consume the canonical plan:
   instrumentation because Android permits only one instrumentation owner of `UiAutomation`.
 - iOS converts every planned point to native orientation and feeds the exact arrays to the existing
   private XCTest event bridge. macOS lowers a one-contact plan to its drag executor and tvOS lowers
-  it to remote direction; multi-touch remains capability-gated to iOS simulators.
+  it to remote direction. Core admission and the Apple adapter both consume the same shared
+  multi-touch support policy; multi-touch remains capability-gated to iOS simulators.
 - WebDriver lowers a supported plan to synchronized W3C pointer action sources. Multi-touch remains
   capability-gated until a provider proves it.
 
 The `Interactor` and backend expose one compositional `performGesture(plan)` primitive instead of a
 method per semantic alias. The old scalar Apple and Android multi-touch executors and the
 public-command alias-to-positionals-to-reparse route are deleted. `.ad` keeps its established
-positional syntax through one named daemon-edge compatibility adapter; CLI, Node.js, and MCP send
+positional syntax through one named replay compatibility codec; CLI, Node.js, and MCP send
 structured input. Providers should compose transport/device bindings with the shared platform
 adapter rather than reimplement the interaction runtime.
 
+Repeated coordinate swipes are bounded at the public command contract and daemon trust boundary.
+Individual count and pause limits prevent pathological fields, while the combined planned gesture
+and pause schedule must fit within 60 seconds so valid fields cannot compose into an unbounded
+session lock.
+
 Public two-finger pan is additive: `pointerCount?: 1 | 2` on pan and CLI
 `--pointer-count 2`; omission remains one contact. Responses share the canonical
 `kind`, `durationMs`, `pointerCount`, `from`, and `to` fields, followed by backend evidence.

src/cli/parser/cli-help.ts

@@ -287,7 +287,7 @@ Navigation and gestures:
   For raw coordinate gestures, run snapshot -i first and choose a point near the center of the intended app-owned target. Avoid screen edges, tab bars, navigation bars, and home indicators because those areas can trigger system or app navigation instead of the gesture under test.
   If app-owned back is ambiguous or has just misrouted, prefer a visible nav/back button ref, tab-bar ref, or deep link over repeated back/system back.
   App-owned action sheets, menus, and camera/scan screens are normal UI. After opening one, run snapshot -i or wait for the option, press by label/ref, handle visible permission sheets through UI or platform-supported native alerts, then wait for a concrete result before returning to chat/form state.
-  Keep count/pause/pattern on one swipe; flags are --count, --pause-ms, --pattern ping-pong.
+  Keep count/pause/pattern on one swipe; flags are --count, --pause-ms, --pattern ping-pong. Count is capped at 200, pause at 10000ms, and the combined swipe/pause schedule at 60000ms.
   For repeated iOS gesture smoke checks, use press <x> <y> --count <n> --jitter-px <n> for tap series and swipe <x1> <y1> <x2> <y2> --count <n> for drag series.
   longpress accepts coordinates, @refs, or selectors. Prefer @ref/selector from snapshot -i; use coordinates only as a fallback when accessibility refs miss the exact target. Duration and gesture scale/center are positional:
     agent-device longpress 300 500 800

src/commands/interaction/metadata.ts

@@ -24,8 +24,10 @@ import { CLICK_BUTTONS } from '../../core/click-button.ts';
 import { SCROLL_DURATION_MAX_MS } from '../../contracts/scroll-command.ts';
 import {
   SCROLL_DIRECTIONS,
+  SWIPE_PAUSE_MAX_MS,
   SWIPE_PATTERNS,
   SWIPE_PRESETS,
+  SWIPE_REPETITION_MAX,
 } from '../../contracts/scroll-gesture.ts';
 import { SCROLL_INPUT_DIRECTIONS } from './runtime/gestures.ts';
 import { FIND_LOCATORS } from '../../selectors/find.ts';
@@ -137,9 +139,12 @@ const longPressFields = {
 const swipeFields = {
   from: requiredField(pointField('Swipe start point.')),
   to: requiredField(pointField('Swipe end point.')),
-  durationMs: integerField('Deprecated: timed movement is a pan; omit for swipe.', { min: 0 }),
-  count: integerField('Number of swipe repetitions.', { min: 1 }),
-  pauseMs: integerField('Pause between repeated swipes.', { min: 0 }),
+  durationMs: integerField('Deprecated: timed movement is a pan; omit for swipe.', {
+    min: 16,
+    max: 10_000,
+  }),
+  count: integerField('Number of swipe repetitions.', { min: 1, max: SWIPE_REPETITION_MAX }),
+  pauseMs: integerField('Pause between repeated swipes.', { min: 0, max: SWIPE_PAUSE_MAX_MS }),
   pattern: enumField(SWIPE_PATTERNS),
 };
 

src/contracts/apple-multitouch-support.ts

@@ -0,0 +1,58 @@
+import {
+  isApplePlatform,
+  resolveDeviceAppleOs,
+  type AppleOS,
+  type DeviceInfo,
+} from '../kernel/device.ts';
+import { AppError } from '../kernel/errors.ts';
+import type { GesturePlan } from './gesture-plan-types.ts';
+
+const APPLE_OS_DISPLAY_NAMES: Record<AppleOS, string> = {
+  ios: 'iOS',
+  ipados: 'iPadOS',
+  tvos: 'tvOS',
+  watchos: 'watchOS',
+  visionos: 'visionOS',
+  macos: 'macOS',
+};
+
+const APPLE_MULTI_TOUCH_UNSUPPORTED_HINTS: Partial<Record<AppleOS, string>> = {
+  visionos: 'visionOS uses spatial input and does not support two-finger touch synthesis.',
+  tvos: 'tvOS has no touch input — this gesture is supported on Android and the iOS simulator only.',
+  macos:
+    'macOS automation has no multi-touch input — this gesture is supported on Android and the iOS simulator only.',
+};
+
+/** One policy shared by command admission and the defensive Apple adapter check. */
+export function assertAppleMultiTouchSupported(
+  device: DeviceInfo,
+  intent: GesturePlan['intent'],
+): void {
+  if (!isApplePlatform(device.platform)) {
+    throw unsupported(intent, device.platform);
+  }
+  const appleOs = resolveDeviceAppleOs(device);
+  if ((appleOs === 'ios' || appleOs === 'ipados') && device.kind === 'simulator') return;
+  if (appleOs === 'ios' || appleOs === 'ipados') {
+    throw new AppError(
+      'UNSUPPORTED_OPERATION',
+      `gesture ${intent} is not supported on physical iOS devices`,
+      {
+        hint: 'Two-finger gesture synthesis is iOS-simulator only — not available on physical iOS devices.',
+      },
+    );
+  }
+  throw unsupported(
+    intent,
+    APPLE_OS_DISPLAY_NAMES[appleOs],
+    APPLE_MULTI_TOUCH_UNSUPPORTED_HINTS[appleOs],
+  );
+}
+
+function unsupported(intent: GesturePlan['intent'], platform: string, hint?: string): AppError {
+  return new AppError(
+    'UNSUPPORTED_OPERATION',
+    `gesture ${intent} is not supported on ${platform}`,
+    hint === undefined ? undefined : { hint },
+  );
+}

src/contracts/gesture-input.ts

@@ -10,7 +10,6 @@ import {
 import type { GesturePointerCount } from './gesture-plan-types.ts';
 
 export const GESTURE_KINDS = ['pan', 'fling', 'swipe', 'pinch', 'rotate', 'transform'] as const;
-export type GestureKind = (typeof GESTURE_KINDS)[number];
 
 export type PanGesturePayload = {
   kind: 'pan';

src/contracts/gesture-plan.ts

@@ -21,7 +21,7 @@ const GESTURE_HORIZONTAL_ANGLE_DEGREES = 0;
 const GESTURE_MINIMUM_RELIABLE_SPAN_PX = 48;
 const GESTURE_VIEWPORT_INSET_PX = 1;
 const DEFAULT_PAN_DURATION_MS = 500;
-const FLING_DURATION_MS = 100;
+export const GESTURE_FLING_DURATION_MS = 100;
 const DEFAULT_MULTI_TOUCH_DURATION_MS = 300;
 const MAX_ROTATION_DEGREES_PER_SAMPLE = 3;
 const MAX_ROTATION_DEFAULT_DURATION_MS = 2_400;
@@ -110,7 +110,7 @@ function buildFlingPlan(
       'fling',
       input.from,
       input.to,
-      FLING_DURATION_MS,
+      GESTURE_FLING_DURATION_MS,
       viewport,
       platform,
     );
@@ -121,7 +121,7 @@ function buildFlingPlan(
     'fling',
     start,
     offsetPointByDirection(start, input.direction, distance),
-    FLING_DURATION_MS,
+    GESTURE_FLING_DURATION_MS,
     viewport,
     platform,
   );

src/contracts/scroll-gesture.ts

@@ -8,6 +8,9 @@ export const SWIPE_PRESETS = ['left', 'right', 'left-edge', 'right-edge'] as con
 export type SwipePreset = (typeof SWIPE_PRESETS)[number];
 export const SWIPE_PATTERNS = ['one-way', 'ping-pong'] as const;
 export type SwipePattern = (typeof SWIPE_PATTERNS)[number];
+export const SWIPE_REPETITION_MAX = 200;
+export const SWIPE_PAUSE_MAX_MS = 10_000;
+export const SWIPE_SERIES_MAX_SCHEDULED_DURATION_MS = 60_000;
 const SCROLL_DIRECTION_ENUM = defineStringEnum(SCROLL_DIRECTIONS, {
   message: (direction) => `Unknown direction: ${direction}`,
 });
@@ -27,7 +30,7 @@ export type GestureReferenceFrame = {
   referenceHeight: number;
 };
 
-export type GesturePoint = {
+type GesturePoint = {
   x: number;
   y: number;
 };

src/core/capabilities.ts

@@ -2,9 +2,10 @@ import { deriveCapabilityMatrix } from './command-descriptor/derive.ts';
 import { commandDescriptors } from './command-descriptor/registry.ts';
 import { tryGetPlugin } from './platform-plugin/plugin.ts';
 import { registerBuiltinPlatformPlugins } from './interactors/register-builtins.ts';
-import { isIosFamily, type AppleOS, type DeviceInfo } from '../kernel/device.ts';
+import type { DeviceInfo } from '../kernel/device.ts';
 import { AppError } from '../kernel/errors.ts';
 import type { NormalizedGestureInput } from '../contracts/gesture-normalization.ts';
+import { assertAppleMultiTouchSupported } from '../contracts/apple-multitouch-support.ts';
 
 // Populate the PlatformPlugin registry once at module load (idempotent; registers
 // only lazy closures, so no leaf code is imported and CLI cold-start is unaffected
@@ -175,54 +176,7 @@ function requireMultiTouchGestureSupported(
   if (device.platform !== 'apple') {
     throw unsupportedGesture(input, gesturePlatformMessage(input, device));
   }
-  const appleOs = resolveGestureAppleOs(device);
-  if (appleOs === 'ios' || appleOs === 'ipados') {
-    if (device.kind === 'simulator') return;
-    if (isIosFamily(device) && device.kind === 'device') {
-      throw unsupportedGesture(
-        input,
-        `gesture ${input.intent} is not supported on physical iOS devices`,
-        'Two-finger gesture synthesis is iOS-simulator only — not available on physical iOS devices.',
-      );
-    }
-  }
-  throw unsupportedGesture(
-    input,
-    `gesture ${input.intent} is not supported on ${appleOsDisplayName(appleOs)}`,
-    multiTouchUnsupportedHint(appleOs),
-  );
-}
-
-function resolveGestureAppleOs(device: DeviceInfo): AppleOS {
-  if (device.appleOs) return device.appleOs;
-  if (device.target === 'tv') return 'tvos';
-  if (device.target === 'desktop') return 'macos';
-  return 'ios';
-}
-
-function appleOsDisplayName(appleOs: AppleOS): string {
-  const names: Record<AppleOS, string> = {
-    ios: 'iOS',
-    ipados: 'iPadOS',
-    tvos: 'tvOS',
-    watchos: 'watchOS',
-    visionos: 'visionOS',
-    macos: 'macOS',
-  };
-  return names[appleOs];
-}
-
-function multiTouchUnsupportedHint(appleOs: AppleOS): string | undefined {
-  if (appleOs === 'visionos') {
-    return 'visionOS uses spatial input and does not support two-finger touch synthesis.';
-  }
-  if (appleOs === 'tvos') {
-    return 'tvOS has no touch input — this gesture is supported on Android and the iOS simulator only.';
-  }
-  if (appleOs === 'macos') {
-    return 'macOS automation has no multi-touch input — this gesture is supported on Android and the iOS simulator only.';
-  }
-  return undefined;
+  assertAppleMultiTouchSupported(device, input.intent);
 }
 
 function gesturePlatformMessage(input: NormalizedGestureInput, device: DeviceInfo): string {

src/core/platform-plugin/__tests__/apple-os-capability-table-parity.test.ts

@@ -4,6 +4,7 @@ import { isAudioProbeSupportedDevice } from '../../../kernel/audio-probe-support
 import {
   isIosFamily,
   isMacOs,
+  resolveDeviceAppleOs,
   DEVICE_TARGETS,
   PLATFORMS,
   type AppleOS,
@@ -23,10 +24,7 @@ import {
   VISIONOS_SIMULATOR,
   WEB_DESKTOP_DEVICE,
 } from '../../../__tests__/test-utils/index.ts';
-import {
-  APPLE_OS_CAPABILITIES,
-  resolveDeviceAppleOs,
-} from '../../../platforms/apple/capabilities.ts';
+import { APPLE_OS_CAPABILITIES } from '../../../platforms/apple/capabilities.ts';
 import { getPlugin } from '../plugin.ts';
 import { registerBuiltinPlatformPlugins } from '../../interactors/register-builtins.ts';
 
@@ -145,16 +143,13 @@ const SAMPLE_DEVICES: DeviceInfo[] = [
   ...buildSyntheticMatrix(),
 ];
 
-test('the per-AppleOS table row keys are exhaustive and visionOS refuses touch synthesis', () => {
+test('the per-AppleOS capability table row keys are exhaustive', () => {
   const rows: AppleOS[] = ['ios', 'ipados', 'tvos', 'watchos', 'visionos', 'macos'];
   for (const os of rows) {
     assert.ok(APPLE_OS_CAPABILITIES[os], `capability row present for ${os}`);
   }
-  // iOS/iPadOS share touch synthesis; visionOS keeps the lifecycle surface but uses
-  // spatial input and therefore has its own explicit unsupported row.
+  // iOS/iPadOS share the same platform capability profile.
   assert.equal(APPLE_OS_CAPABILITIES.ios, APPLE_OS_CAPABILITIES.ipados);
-  assert.equal(APPLE_OS_CAPABILITIES.visionos.multiTouchSynthesis, false);
-  assert.match(APPLE_OS_CAPABILITIES.visionos.multiTouchUnsupportedHint ?? '', /spatial input/i);
 });
 
 test('resolveDeviceAppleOs prefers the stored discriminant, else infers from target', () => {