refactor: normalize click alias to press path

Author: thymikee

README.md

@@ -39,10 +39,10 @@ Use `press` as the canonical tap command; `click` is an equivalent alias.
 ```bash
 agent-device open Contacts --platform ios # creates session on iOS Simulator
 agent-device snapshot
-agent-device click @e5
+agent-device press @e5
 agent-device fill @e6 "John"
 agent-device fill @e7 "Doe"
-agent-device click @e3
+agent-device press @e3
 agent-device close
 ```
 
@@ -82,7 +82,7 @@ Gesture series examples:
 ```bash
 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 @e5 --count 5 --interval-ms 1 --double-tap
+agent-device press @e5 --count 5 --double-tap
 agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-pong
 ```
 

skills/agent-device/SKILL.md

@@ -12,7 +12,7 @@ For agent-driven exploration: use refs. For deterministic replay scripts: use se
 ```bash
 agent-device open Settings --platform ios
 agent-device snapshot -i
-agent-device click @e3
+agent-device press @e3
 agent-device wait text "Camera"
 agent-device alert wait 10000
 agent-device fill @e5 "test"

src/cli.ts

@@ -146,12 +146,12 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
         if (logTailStopper) logTailStopper();
         return;
       }
-      if (command === 'click') {
+      if (command === 'click' || command === 'press') {
         const ref = (response.data as any)?.ref ?? '';
         const x = (response.data as any)?.x;
         const y = (response.data as any)?.y;
         if (ref && typeof x === 'number' && typeof y === 'number') {
-          process.stdout.write(`Clicked @${ref} (${x}, ${y})\n`);
+          process.stdout.write(`Tapped @${ref} (${x}, ${y})\n`);
         }
         if (logTailStopper) logTailStopper();
         return;

src/core/__tests__/dispatch-press.test.ts

@@ -25,7 +25,6 @@ test('shouldUseIosTapSeries enables fast path for repeated plain iOS taps', () =
 
 test('shouldUseIosTapSeries disables fast path for single press or modified gestures', () => {
   assert.equal(shouldUseIosTapSeries(iosDevice, 1, 0, 0), false);
-  assert.equal(shouldUseIosTapSeries(iosDevice, 1, 0, 0, true), true);
   assert.equal(shouldUseIosTapSeries(iosDevice, 5, 100, 0), false);
   assert.equal(shouldUseIosTapSeries(iosDevice, 5, 0, 1), false);
 });

src/core/dispatch.ts

@@ -141,7 +141,7 @@ export async function dispatchCommand(
         throw new AppError('INVALID_ARGS', 'double-tap cannot be combined with jitter-px');
       }
 
-      if (shouldUseIosTapSeries(device, count, holdMs, jitterPx, doubleTap)) {
+      if (shouldUseIosTapSeries(device, count, holdMs, jitterPx)) {
         await runIosRunnerCommand(
           device,
           {
@@ -421,9 +421,8 @@ export function shouldUseIosTapSeries(
   count: number,
   holdMs: number,
   jitterPx: number,
-  doubleTap = false,
 ): boolean {
-  return device.platform === 'ios' && (count > 1 || doubleTap) && holdMs === 0 && jitterPx === 0;
+  return device.platform === 'ios' && count > 1 && holdMs === 0 && jitterPx === 0;
 }
 
 export function shouldUseIosDragSeries(device: DeviceInfo, count: number): boolean {

src/daemon.ts

@@ -55,15 +55,16 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
     return { ok: false, error: { code: 'UNAUTHORIZED', message: 'Invalid token' } };
   }
 
-  const command = req.command;
-  const sessionName = resolveEffectiveSessionName(req, sessionStore);
+  const normalizedReq = normalizeAliasedCommands(req);
+  const command = normalizedReq.command;
+  const sessionName = resolveEffectiveSessionName(normalizedReq, sessionStore);
   const existingSession = sessionStore.get(sessionName);
   if (existingSession && !selectorValidationExemptCommands.has(command)) {
-    assertSessionSelectorMatches(existingSession, req.flags);
+    assertSessionSelectorMatches(existingSession, normalizedReq.flags);
   }
 
   const sessionResponse = await handleSessionCommands({
-    req,
+    req: normalizedReq,
     sessionName,
     logPath,
     sessionStore,
@@ -72,22 +73,22 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
   if (sessionResponse) return sessionResponse;
 
   const snapshotResponse = await handleSnapshotCommands({
-    req,
+    req: normalizedReq,
     sessionName,
     logPath,
     sessionStore,
   });
   if (snapshotResponse) return snapshotResponse;
 
   const recordTraceResponse = await handleRecordTraceCommands({
-    req,
+    req: normalizedReq,
     sessionName,
     sessionStore,
   });
   if (recordTraceResponse) return recordTraceResponse;
 
   const findResponse = await handleFindCommands({
-    req,
+    req: normalizedReq,
     sessionName,
     logPath,
     sessionStore,
@@ -96,7 +97,7 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
   if (findResponse) return findResponse;
 
   const interactionResponse = await handleInteractionCommands({
-    req,
+    req: normalizedReq,
     sessionName,
     sessionStore,
     contextFromFlags,
@@ -119,18 +120,23 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
     };
   }
 
-  const data = await dispatchCommand(session.device, command, req.positionals ?? [], req.flags?.out, {
-    ...contextFromFlags(req.flags, session.appBundleId, session.trace?.outPath),
+  const data = await dispatchCommand(session.device, command, normalizedReq.positionals ?? [], normalizedReq.flags?.out, {
+    ...contextFromFlags(normalizedReq.flags, session.appBundleId, session.trace?.outPath),
   });
   sessionStore.recordAction(session, {
     command,
-    positionals: req.positionals ?? [],
-    flags: req.flags ?? {},
+    positionals: normalizedReq.positionals ?? [],
+    flags: normalizedReq.flags ?? {},
     result: data ?? {},
   });
   return { ok: true, data: data ?? {} };
 }
 
+function normalizeAliasedCommands(req: DaemonRequest): DaemonRequest {
+  if (req.command !== 'click') return req;
+  return { ...req, command: 'press' };
+}
+
 function writeInfo(port: number): void {
   if (!fs.existsSync(baseDir)) fs.mkdirSync(baseDir, { recursive: true });
   fs.writeFileSync(logPath, '');

src/daemon/handlers/__tests__/interaction.test.ts

@@ -56,7 +56,7 @@ test('unsupportedRefSnapshotFlags returns empty when no ref-unsupported flags ar
   assert.deepEqual(unsupported, []);
 });
 
-test('click coordinates dispatches press and records as click', async () => {
+test('press coordinates dispatches press and records as press', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'default';
   sessionStore.set(sessionName, makeSession(sessionName));
@@ -67,7 +67,7 @@ test('click coordinates dispatches press and records as click', async () => {
     req: {
       token: 't',
       session: sessionName,
-      command: 'click',
+      command: 'press',
       positionals: ['100', '200'],
       flags: { count: 3, intervalMs: 1, doubleTap: true },
     },
@@ -92,7 +92,7 @@ test('click coordinates dispatches press and records as click', async () => {
   const session = sessionStore.get(sessionName);
   assert.ok(session);
   assert.equal(session?.actions.length, 1);
-  assert.equal(session?.actions[0]?.command, 'click');
+  assert.equal(session?.actions[0]?.command, 'press');
   assert.deepEqual(session?.actions[0]?.positionals, ['100', '200']);
 });
 
@@ -155,30 +155,33 @@ test('press @ref resolves snapshot node and records press action', async () => {
   assert.ok(Array.isArray(result.selectorChain));
 });
 
-test('press coordinates returns null to allow daemon passthrough', async () => {
+test('press coordinates does not treat extra trailing args as selector', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'default';
   sessionStore.set(sessionName, makeSession(sessionName));
 
-  let dispatchCalls = 0;
+  const dispatchCalls: Array<{ command: string; positionals: string[] }> = [];
   const response = await handleInteractionCommands({
     req: {
       token: 't',
       session: sessionName,
       command: 'press',
-      positionals: ['100', '200'],
+      positionals: ['100', '200', 'extra'],
       flags: { count: 2 },
     },
     sessionName,
     sessionStore,
     contextFromFlags,
-    dispatch: async () => {
-      dispatchCalls += 1;
-      return {};
+    dispatch: async (_device, command, positionals) => {
+      dispatchCalls.push({ command, positionals });
+      return { ok: true };
     },
   });
 
-  assert.equal(response, null);
-  assert.equal(dispatchCalls, 0);
-  assert.equal(sessionStore.get(sessionName)?.actions.length, 0);
+  assert.ok(response);
+  assert.equal(response.ok, true);
+  assert.equal(dispatchCalls.length, 1);
+  assert.equal(dispatchCalls[0]?.command, 'press');
+  assert.deepEqual(dispatchCalls[0]?.positionals, ['100', '200']);
+  assert.equal(sessionStore.get(sessionName)?.actions.length, 1);
 });

src/daemon/handlers/interaction.ts

@@ -6,7 +6,6 @@ import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
 import { SessionStore } from '../session-store.ts';
 import { evaluateIsPredicate, isSupportedPredicate } from '../is-predicates.ts';
 import { extractNodeText, findNodeByLabel, isFillableType, pruneGroupNodes, resolveRefLabel } from '../snapshot-processing.ts';
-import { isClickLikeCommand } from '../script-utils.ts';
 import {
   buildSelectorChainForNode,
   findSelectorChainMatch,
@@ -34,7 +33,7 @@ export async function handleInteractionCommands(params: {
   const dispatch = params.dispatch ?? dispatchCommand;
   const command = req.command;
 
-  if (isClickLikeCommand(command)) {
+  if (command === 'press') {
     const session = sessionStore.get(sessionName);
     if (!session) {
       return {
@@ -44,8 +43,6 @@ export async function handleInteractionCommands(params: {
     }
     const directCoordinates = parseCoordinateTarget(req.positionals ?? []);
     if (directCoordinates) {
-      // Coordinate-only press is handled by daemon fallback to preserve legacy passthrough semantics.
-      if (command === 'press') return null;
       const data = await dispatch(
         session.device,
         'press',
@@ -67,7 +64,7 @@ export async function handleInteractionCommands(params: {
     const selectorAction = 'click';
     const refInput = req.positionals?.[0] ?? '';
     if (refInput.startsWith('@')) {
-      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse(command, req.flags);
+      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('press', req.flags);
       if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
       if (!session.snapshot) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
@@ -575,7 +572,7 @@ const REF_UNSUPPORTED_FLAG_MAP: ReadonlyArray<[keyof CommandFlags, string]> = [
 ];
 
 function refSnapshotFlagGuardResponse(
-  command: 'click' | 'press' | 'fill' | 'get',
+  command: 'press' | 'fill' | 'get',
   flags: CommandFlags | undefined,
 ): DaemonResponse | null {
   const unsupported = unsupportedRefSnapshotFlags(flags);
@@ -591,7 +588,6 @@ function refSnapshotFlagGuardResponse(
 
 function parseCoordinateTarget(positionals: string[]): { x: number; y: number } | null {
   if (positionals.length < 2) return null;
-  // Keep legacy "first two numeric tokens win" behavior for coordinate targets.
   const x = Number(positionals[0]);
   const y = Number(positionals[1]);
   if (!Number.isFinite(x) || !Number.isFinite(y)) return null;