refactor: add interactor doubleTap and alias docs

Author: thymikee

README.md

@@ -34,6 +34,7 @@ npx agent-device open SampleApp
 ## Quick Start
 
 Use refs for agent-driven exploration and normal automation flows.
+Use `press` as the canonical tap command; `click` is an equivalent alias.
 
 ```bash
 agent-device open Contacts --platform ios # creates session on iOS Simulator
@@ -56,7 +57,7 @@ Basic flow:
 ```bash
 agent-device open SampleApp
 agent-device snapshot
-agent-device click @e7
+agent-device press @e7
 agent-device fill @e8 "hello"
 agent-device close SampleApp
 ```
@@ -73,7 +74,8 @@ agent-device trace stop ./trace.log
 Coordinates:
 - All coordinate-based commands (`press`, `long-press`, `swipe`, `focus`, `fill`) use device coordinates with origin at top-left.
 - X increases to the right, Y increases downward.
-- `click` and `press` both accept `x y`, `@ref`, and selector targets.
+- `press` is the canonical tap command.
+- `click` is an equivalent alias and accepts the same targets (`x y`, `@ref`, selector) and flags.
 
 Gesture series examples:
 
@@ -87,7 +89,7 @@ agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-p
 ## Command Index
 - `boot`, `open`, `close`, `reinstall`, `home`, `back`, `app-switcher`
 - `snapshot`, `find`, `get`
-- `click`, `focus`, `type`, `fill`, `press`, `long-press`, `swipe`, `scroll`, `scrollintoview`, `pinch`, `is`
+- `press` (alias: `click`), `focus`, `type`, `fill`, `long-press`, `swipe`, `scroll`, `scrollintoview`, `pinch`, `is`
 - `alert`, `wait`, `screenshot`
 - `trace start`, `trace stop`
 - `settings wifi|airplane|location on|off`

skills/agent-device/SKILL.md

@@ -29,7 +29,7 @@ npx -y agent-device
 
 1. Open app or deep link: `open [app|url] [url]` (`open` handles target selection + boot/activation in the normal flow)
 2. Snapshot: `snapshot` to get refs from accessibility tree
-3. Interact using refs (`click @ref`, `fill @ref "text"`)
+3. Interact using refs (`press @ref`, `fill @ref "text"`; `click` is an alias of `press`)
 4. Re-snapshot after navigation/UI changes
 5. Close session when done
 
@@ -109,14 +109,15 @@ agent-device appstate
 ### Interactions (use @refs from snapshot)
 
 ```bash
-agent-device click @e1
+agent-device press @e1                # Canonical tap command (`click` is an alias)
 agent-device focus @e2
 agent-device fill @e2 "text"           # Clear then type (Android: verifies value and retries once on mismatch)
 agent-device type "text"               # Type into focused field without clearing
 agent-device press 300 500             # Tap by coordinates
 agent-device press 300 500 --count 12 --interval-ms 45
 agent-device press 300 500 --count 6 --hold-ms 120 --interval-ms 30 --jitter-px 2
-agent-device click @e1 --count 5 --interval-ms 1 --double-tap
+agent-device press @e1 --count 5             # Repeat taps on the same target
+agent-device press @e1 --count 5 --double-tap # Use double-tap gesture per iteration
 agent-device swipe 540 1500 540 500 120
 agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-pong
 agent-device long-press 300 500 800    # Long press (where supported)
@@ -179,7 +180,8 @@ agent-device apps --platform android --user-installed
 
 ## Best practices
 
-- `click` and `press` both accept `x y`, `@ref`, and selector targets.
+- `press` is the canonical tap command; `click` is an alias with the same behavior.
+- `press` (and `click`) accepts `x y`, `@ref`, and selector targets.
 - `press`/`click` support gesture series controls: `--count`, `--interval-ms`, `--hold-ms`, `--jitter-px`, `--double-tap`.
 - `--double-tap` cannot be combined with `--hold-ms` or `--jitter-px`.
 - `swipe` supports coordinate + timing controls and repeat patterns: `swipe x1 y1 x2 y2 [durationMs] --count --pause-ms --pattern`.

skills/agent-device/references/snapshot-refs.md

@@ -3,6 +3,7 @@
 ## Purpose
 
 Refs are useful for discovery/debugging. For deterministic scripts, use selectors.
+For tap interactions, `press` is canonical; `click` is an equivalent alias.
 
 ## Snapshot
 
@@ -24,14 +25,14 @@ App: com.apple.Preferences
 ## Using refs (discovery/debug)
 
 ```bash
-agent-device click @e2
+agent-device press @e2
 agent-device fill @e5 "test"
 ```
 
 ## Using selectors (deterministic)
 
 ```bash
-agent-device click 'id="camera_row" || label="Camera" role=button'
+agent-device press 'id="camera_row" || label="Camera" role=button'
 agent-device fill 'id="search_input" editable=true' "test"
 agent-device is visible 'id="camera_settings_anchor"'
 ```

src/core/dispatch.ts

@@ -163,8 +163,7 @@ export async function dispatchCommand(
         const targetX = x + dx;
         const targetY = y + dy;
         if (doubleTap) {
-          await interactor.tap(targetX, targetY);
-          await interactor.tap(targetX, targetY);
+          await interactor.doubleTap(targetX, targetY);
           return;
         }
         if (holdMs > 0) await interactor.longPress(targetX, targetY, holdMs);

src/utils/interactors.ts

@@ -34,6 +34,7 @@ export type Interactor = {
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
   tap(x: number, y: number): Promise<void>;
+  doubleTap(x: number, y: number): Promise<void>;
   swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
   longPress(x: number, y: number, durationMs?: number): Promise<void>;
   focus(x: number, y: number): Promise<void>;
@@ -52,6 +53,10 @@ export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext):
         openDevice: () => openAndroidDevice(device),
         close: (app) => closeAndroidApp(device, app),
         tap: (x, y) => pressAndroid(device, x, y),
+        doubleTap: async (x, y) => {
+          await pressAndroid(device, x, y);
+          await pressAndroid(device, x, y);
+        },
         swipe: (x1, y1, x2, y2, durationMs) => swipeAndroid(device, x1, y1, x2, y2, durationMs),
         longPress: (x, y, durationMs) => longPressAndroid(device, x, y, durationMs),
         focus: (x, y) => focusAndroid(device, x, y),
@@ -74,7 +79,10 @@ export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext):
   }
 }
 
-type IoRunnerOverrides = Pick<Interactor, 'tap' | 'swipe' | 'longPress' | 'focus' | 'type' | 'fill' | 'scroll' | 'scrollIntoView'>;
+type IoRunnerOverrides = Pick<
+  Interactor,
+  'tap' | 'doubleTap' | 'swipe' | 'longPress' | 'focus' | 'type' | 'fill' | 'scroll' | 'scrollIntoView'
+>;
 
 function iosRunnerOverrides(device: DeviceInfo, ctx: RunnerContext): IoRunnerOverrides {
   const runnerOpts = { verbose: ctx.verbose, logPath: ctx.logPath, traceLogPath: ctx.traceLogPath };
@@ -87,6 +95,13 @@ function iosRunnerOverrides(device: DeviceInfo, ctx: RunnerContext): IoRunnerOve
         runnerOpts,
       );
     },
+    doubleTap: async (x, y) => {
+      await runIosRunnerCommand(
+        device,
+        { command: 'tapSeries', x, y, count: 1, intervalMs: 0, doubleTap: true, appBundleId: ctx.appBundleId },
+        runnerOpts,
+      );
+    },
     swipe: async (x1, y1, x2, y2, durationMs) => {
       await runIosRunnerCommand(
         device,