refactor: tighten Maestro replay compatibility boundary

thymikee · thymikee · commit d7a7ce47fa5b · 2026-05-27T16:20:46.000+02:00
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -256,7 +256,7 @@ extension RunnerTests {
           app: activeApp,
           selectorKey: selectorKey,
           selectorValue: selectorValue,
-          allowNonHittableFallback: command.allowNonHittableSelectorTap == true
+          allowNonHittableFallback: command.allowNonHittableCoordinateFallback == true
         )
         if match.isAmbiguous {
           return Response(ok: false, error: ErrorPayload(code: "AMBIGUOUS_MATCH", message: "selector matched multiple elements"))
@@ -877,7 +877,7 @@ extension RunnerTests {
         app: activeApp,
         selectorKey: selectorKey,
         selectorValue: selectorValue,
-        allowNonHittableFallback: command.allowNonHittableSelectorTap == true
+        allowNonHittableFallback: command.allowNonHittableCoordinateFallback == true
       )
       if match.isAmbiguous {
         return Response(ok: false, error: ErrorPayload(code: "AMBIGUOUS_MATCH", message: "selector matched multiple elements"))
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -40,7 +40,7 @@ struct Command: Codable {
   let text: String?
   let selectorKey: String?
   let selectorValue: String?
-  let allowNonHittableSelectorTap: Bool?
+  let allowNonHittableCoordinateFallback: Bool?
   let delayMs: Int?
   let textEntryMode: String?
   let clearFirst: Bool?
diff --git a/src/compat/maestro/__tests__/replay-flow.test.ts b/src/compat/maestro/__tests__/replay-flow.test.ts
@@ -80,8 +80,8 @@ env:
   assert.equal(parsed.actions[3]?.flags.doubleTap, true);
   assert.equal(parsed.actions[3]?.flags.intervalMs, 150);
   assert.equal(parsed.actions[4]?.flags.holdMs, 3000);
-  assert.equal(parsed.actions[1]?.flags.maestro?.allowNonHittableSelectorTap, true);
-  assert.equal(parsed.actions[6]?.flags?.maestro?.allowNonHittableSelectorTap, undefined);
+  assert.equal(parsed.actions[1]?.flags.maestro?.allowNonHittableCoordinateFallback, true);
+  assert.equal(parsed.actions[6]?.flags?.maestro?.allowNonHittableCoordinateFallback, undefined);
 });
 
 test('parseMaestroReplayFlow maps iOS openLink through the app id when available', () => {
@@ -200,7 +200,7 @@ test('parseMaestroReplayFlow marks tapOn before inputText for snapshot tap focus
       ['type', ['Muted Users']],
     ],
   );
-  assert.equal(parsed.actions[0]?.flags?.maestro?.allowNonHittableSelectorTap, undefined);
+  assert.equal(parsed.actions[0]?.flags?.maestro?.allowNonHittableCoordinateFallback, undefined);
 });
 
 test('parseMaestroReplayFlow coalesces tapOn inputText while preserving pressKey Enter submit', () => {
@@ -221,7 +221,7 @@ test('parseMaestroReplayFlow coalesces tapOn inputText while preserving pressKey
     ],
   );
   assert.deepEqual(parsed.actionLines, [3, 3, 6]);
-  assert.equal(parsed.actions[1]?.flags?.maestro?.allowNonHittableSelectorTap, true);
+  assert.equal(parsed.actions[1]?.flags?.maestro?.allowNonHittableCoordinateFallback, true);
 });
 
 test('parseMaestroReplayFlow rejects relative runScript paths without source path', () => {
@@ -430,7 +430,7 @@ test('parseMaestroReplayFlow keeps visible-gated runFlow commands for runtime ev
     {
       command: '__maestroTapOn',
       positionals: ['label="Continue" || text="Continue" || id="Continue"'],
-      flags: { maestro: { allowNonHittableSelectorTap: true } },
+      flags: { maestro: { allowNonHittableCoordinateFallback: true } },
     },
   ]);
 });
@@ -454,7 +454,7 @@ test('parseMaestroReplayFlow accepts launchApp reset options', () => {
         'open',
         ['com.callstack.agentdevicelab'],
         {
-          maestro: { clearState: true },
+          clearAppState: true,
           launchArgs: ['-EXDevMenuIsOnboardingFinished', 'true', '-Example', 'ignored'],
         },
       ],
diff --git a/src/compat/maestro/device-actions.ts b/src/compat/maestro/device-actions.ts
@@ -42,7 +42,7 @@ export function convertLaunchApp(
   const shouldRelaunch = !shouldClearState && (value.stopApp === true || launchArgs.length > 0);
   return action('open', [appId], {
     ...(shouldRelaunch ? { relaunch: true } : {}),
-    ...(shouldClearState ? { maestro: { clearState: true } } : {}),
+    ...(shouldClearState ? { clearAppState: true } : {}),
     ...(launchArgs.length > 0 ? { launchArgs } : {}),
   });
 }
diff --git a/src/compat/maestro/interactions.ts b/src/compat/maestro/interactions.ts
@@ -357,7 +357,7 @@ function maestroTapOnFlags(value: unknown): SessionAction['flags'] {
     ...flags,
     maestro: {
       ...(flags.maestro ?? {}),
-      allowNonHittableSelectorTap: true,
+      allowNonHittableCoordinateFallback: true,
     },
   };
 }
diff --git a/src/compat/maestro/replay-flow.ts b/src/compat/maestro/replay-flow.ts
@@ -126,7 +126,7 @@ function optimizeInputTextActions(
 
 function clearMaestroNonHittableTap(action: SessionAction): SessionAction {
   const maestro = { ...(action.flags?.maestro ?? {}) };
-  delete maestro.allowNonHittableSelectorTap;
+  delete maestro.allowNonHittableCoordinateFallback;
   return {
     ...action,
     flags: {
diff --git a/src/core/dispatch-context.ts b/src/core/dispatch-context.ts
@@ -11,14 +11,14 @@ export type BatchStep = {
 };
 
 export type MaestroRuntimeFlags = {
-  allowNonHittableSelectorTap?: boolean;
-  clearState?: boolean;
+  allowNonHittableCoordinateFallback?: boolean;
   optional?: boolean;
   runScriptEnv?: Record<string, string>;
 };
 
 export type CommandFlags = Omit<CliFlags, DaemonExcludedCliFlag> & {
   batchSteps?: BatchStep[];
+  clearAppState?: boolean;
   launchArgs?: string[];
   maestro?: MaestroRuntimeFlags;
   replayBackend?: string;
@@ -55,6 +55,6 @@ export type DispatchContext = ScreenshotDispatchFlags & {
     key: 'id' | 'label' | 'text' | 'value';
     value: string;
     raw: string;
-    allowNonHittableTap?: boolean;
+    allowNonHittableCoordinateFallback?: boolean;
   };
 };
diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
@@ -236,13 +236,13 @@ async function handleOpenCommand(
     if (isDeepLinkTarget(app)) {
       throw new AppError(
         'INVALID_ARGS',
-        'Maestro launchApp.clearState requires an app target, not a deep link.',
+        'Clearing app state requires an app target, not a deep link.',
       );
     }
     if (device.platform !== 'ios' || device.kind !== 'simulator') {
       throw new AppError(
         'UNSUPPORTED_OPERATION',
-        'Maestro launchApp.clearState is currently supported only on iOS simulators.',
+        'Clearing app state is currently supported only on iOS simulators.',
       );
     }
     await clearIosSimulatorAppState(device, app);
diff --git a/src/core/interactor-types.ts b/src/core/interactor-types.ts
@@ -29,7 +29,7 @@ export type ScreenshotOptions = {
 export type ElementSelectorTapOptions = {
   key: 'id' | 'label' | 'text' | 'value';
   value: string;
-  allowNonHittableTap?: boolean;
+  allowNonHittableCoordinateFallback?: boolean;
 };
 
 export type SnapshotOptions = BaseSnapshotOptions & {
diff --git a/src/daemon/__tests__/context.test.ts b/src/daemon/__tests__/context.test.ts
@@ -14,8 +14,8 @@ test('contextFromFlags forwards scroll pixels from CLI flags', () => {
   assert.equal(context.pixels, 240);
 });
 
-test('contextFromFlags maps Maestro clearState to generic app-state clearing', () => {
-  const flags: CommandFlags = { maestro: { clearState: true } };
+test('contextFromFlags forwards generic app-state clearing', () => {
+  const flags: CommandFlags = { clearAppState: true };
   const context = contextFromFlags('/tmp/agent-device.log', flags);
   assert.equal(context.clearAppState, true);
 });
diff --git a/src/daemon/context.ts b/src/daemon/context.ts
@@ -25,7 +25,7 @@ export function contextFromFlags(
     activity: flags?.activity,
     launchConsole: flags?.launchConsole,
     launchArgs: flags?.launchArgs,
-    clearAppState: flags?.maestro?.clearState,
+    clearAppState: flags?.clearAppState,
     verbose: flags?.verbose,
     logPath,
     traceLogPath,
diff --git a/src/daemon/direct-ios-selector.ts b/src/daemon/direct-ios-selector.ts
@@ -6,7 +6,7 @@ export type DirectIosSelectorTarget = {
   key: 'id' | 'label' | 'text' | 'value';
   value: string;
   raw: string;
-  allowNonHittableTap?: boolean;
+  allowNonHittableCoordinateFallback?: boolean;
 };
 
 export function readSimpleIosSelectorTarget(params: {
diff --git a/src/daemon/handlers/__tests__/interaction.test.ts b/src/daemon/handlers/__tests__/interaction.test.ts
@@ -460,7 +460,7 @@ test('fill simple iOS id selector uses direct runner selector fill without snaps
   }
 });
 
-test('click simple iOS selector forwards Maestro non-hittable tap backdoor', async () => {
+test('click simple iOS selector forwards Maestro non-hittable coordinate fallback', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-maestro-selector-fallback';
   sessionStore.set(sessionName, makeIosSession(sessionName, { appBundleId: 'com.example.app' }));
@@ -479,7 +479,7 @@ test('click simple iOS selector forwards Maestro non-hittable tap backdoor', asy
       session: sessionName,
       command: 'click',
       positionals: ['id="e2eSignInAlice"'],
-      flags: { maestro: { allowNonHittableSelectorTap: true } },
+      flags: { maestro: { allowNonHittableCoordinateFallback: true } },
     },
     sessionName,
     sessionStore,
@@ -493,7 +493,7 @@ test('click simple iOS selector forwards Maestro non-hittable tap backdoor', asy
     key: 'id',
     value: 'e2eSignInAlice',
     raw: 'id="e2eSignInAlice"',
-    allowNonHittableTap: true,
+    allowNonHittableCoordinateFallback: true,
   });
 });
 
diff --git a/src/daemon/handlers/interaction-touch.ts b/src/daemon/handlers/interaction-touch.ts
@@ -262,7 +262,9 @@ function readDirectIosSelectorTapTarget(params: {
   if (!selector) return null;
   return {
     ...selector,
-    ...(flags?.maestro?.allowNonHittableSelectorTap ? { allowNonHittableTap: true } : {}),
+    ...(flags?.maestro?.allowNonHittableCoordinateFallback
+      ? { allowNonHittableCoordinateFallback: true }
+      : {}),
   };
 }
 
@@ -438,7 +440,9 @@ function readDirectIosSelectorFillTarget(params: {
   if (!selector) return null;
   return {
     ...selector,
-    ...(flags?.maestro?.allowNonHittableSelectorTap ? { allowNonHittableTap: true } : {}),
+    ...(flags?.maestro?.allowNonHittableCoordinateFallback
+      ? { allowNonHittableCoordinateFallback: true }
+      : {}),
   };
 }
 
diff --git a/src/daemon/handlers/session-replay-maestro-runtime.ts b/src/daemon/handlers/session-replay-maestro-runtime.ts
@@ -12,11 +12,27 @@ import { getSnapshotReferenceFrame, type TouchReferenceFrame } from '../touch-re
 import type { DaemonRequest, DaemonResponse, SessionAction } from '../types.ts';
 import { errorResponse } from './response.ts';
 
-const MAESTRO_SCROLL_UNTIL_VISIBLE_PROBE_MS = 500;
-const MAESTRO_TAP_ON_TIMEOUT_MS = 30000;
-const MAESTRO_OPTIONAL_TAP_ON_TIMEOUT_MS = 3000;
-const MAESTRO_TAP_ON_RETRY_MS = 250;
-const MAESTRO_ANIMATION_POLL_MS = 250;
+// Keep Maestro timing and target-selection heuristics behind one policy so
+// generic Agent Device command behavior does not inherit compatibility rules.
+const MAESTRO_REPLAY_POLICY = {
+  animationPollMs: 250,
+  scrollUntilVisibleProbeMs: 500,
+  tapOnRetryMs: 250,
+  tapOnTimeoutMs: 30000,
+  optionalTapOnTimeoutMs: 3000,
+  swipe: {
+    screenRatio: 0.35,
+    minDistancePx: 120,
+    maxDistancePx: 360,
+    marginPx: 8,
+  },
+  largeTextContainerBias: {
+    minWidth: 120,
+    minHeight: 70,
+    width: 168,
+    height: 48,
+  },
+} as const;
 
 type ReplayBaseRequest = Omit<DaemonRequest, 'command' | 'positionals'>;
 
@@ -160,7 +176,7 @@ async function invokeMaestroWaitForAnimationToEnd(params: {
     });
     if (!response.ok) {
       lastResponse = response;
-      await sleep(MAESTRO_ANIMATION_POLL_MS);
+      await sleep(MAESTRO_REPLAY_POLICY.animationPollMs);
       continue;
     }
     const snapshot = readSnapshotState(response.data);
@@ -171,7 +187,7 @@ async function invokeMaestroWaitForAnimationToEnd(params: {
     }
     previousSignature = signature;
     lastResponse = response;
-    await sleep(MAESTRO_ANIMATION_POLL_MS);
+    await sleep(MAESTRO_REPLAY_POLICY.animationPollMs);
   }
 
   return lastResponse?.ok === false
@@ -191,7 +207,10 @@ async function invokeMaestroScrollUntilVisible(
     return errorResponse('INVALID_ARGS', 'scrollUntilVisible timeout must be a positive number.');
   }
   const fuzzyTextQuery = extractMaestroVisibleTextQuery(selector);
-  const attempts = Math.max(1, Math.ceil(timeoutMs / MAESTRO_SCROLL_UNTIL_VISIBLE_PROBE_MS));
+  const attempts = Math.max(
+    1,
+    Math.ceil(timeoutMs / MAESTRO_REPLAY_POLICY.scrollUntilVisibleProbeMs),
+  );
   let lastWaitResponse: FailedDaemonResponse | null = null;
 
   for (let index = 0; index < attempts; index += 1) {
@@ -240,8 +259,8 @@ async function probeMaestroScrollVisibility(
 
 function scrollProbeMs(timeoutMs: number, index: number): number {
   return Math.min(
-    MAESTRO_SCROLL_UNTIL_VISIBLE_PROBE_MS,
-    Math.max(1, timeoutMs - index * MAESTRO_SCROLL_UNTIL_VISIBLE_PROBE_MS),
+    MAESTRO_REPLAY_POLICY.scrollUntilVisibleProbeMs,
+    Math.max(1, timeoutMs - index * MAESTRO_REPLAY_POLICY.scrollUntilVisibleProbeMs),
   );
 }
 
@@ -339,8 +358,8 @@ async function invokeMaestroTapOn(params: MaestroTapOnParams): Promise<DaemonRes
   const fuzzyTextQuery = extractMaestroVisibleTextQuery(selector);
   const timeoutMs =
     params.baseReq.flags?.maestro?.optional === true
-      ? MAESTRO_OPTIONAL_TAP_ON_TIMEOUT_MS
-      : MAESTRO_TAP_ON_TIMEOUT_MS;
+      ? MAESTRO_REPLAY_POLICY.optionalTapOnTimeoutMs
+      : MAESTRO_REPLAY_POLICY.tapOnTimeoutMs;
   let lastResponse: DaemonResponse | undefined;
   while (Date.now() - startedAt < timeoutMs) {
     const attempt = await invokeMaestroSnapshotTapOn(params, selector, options.value ?? {});
@@ -351,7 +370,7 @@ async function invokeMaestroTapOn(params: MaestroTapOnParams): Promise<DaemonRes
       if (!fuzzyAttempt.retry) return fuzzyAttempt.response;
       lastResponse = fuzzyAttempt.response;
     }
-    await sleep(MAESTRO_TAP_ON_RETRY_MS);
+    await sleep(MAESTRO_REPLAY_POLICY.tapOnRetryMs);
   }
 
   if (params.baseReq.flags?.maestro?.optional === true) {
@@ -644,10 +663,11 @@ function swipeCoordinatesFromTarget(
   const frame = target.frame;
   const horizontalDistance = swipeDistance(frame?.referenceWidth, target.rect.width);
   const verticalDistance = swipeDistance(frame?.referenceHeight, target.rect.height);
-  const minX = 8;
-  const minY = 8;
-  const maxX = frame ? frame.referenceWidth - 8 : center.x + horizontalDistance;
-  const maxY = frame ? frame.referenceHeight - 8 : center.y + verticalDistance;
+  const margin = MAESTRO_REPLAY_POLICY.swipe.marginPx;
+  const minX = margin;
+  const minY = margin;
+  const maxX = frame ? frame.referenceWidth - margin : center.x + horizontalDistance;
+  const maxY = frame ? frame.referenceHeight - margin : center.y + verticalDistance;
   switch (direction.toLowerCase()) {
     case 'up':
       return {
@@ -685,8 +705,14 @@ function swipeCoordinatesFromTarget(
 }
 
 function swipeDistance(frameSize: number | undefined, rectSize: number): number {
-  const screenRelative = typeof frameSize === 'number' ? frameSize * 0.35 : 0;
-  return Math.round(Math.min(360, Math.max(120, screenRelative, rectSize * 1.5)));
+  const screenRelative =
+    typeof frameSize === 'number' ? frameSize * MAESTRO_REPLAY_POLICY.swipe.screenRatio : 0;
+  return Math.round(
+    Math.min(
+      MAESTRO_REPLAY_POLICY.swipe.maxDistancePx,
+      Math.max(MAESTRO_REPLAY_POLICY.swipe.minDistancePx, screenRelative, rectSize * 1.5),
+    ),
+  );
 }
 
 function clampCoordinate(value: number, min: number, max: number): number {
@@ -708,8 +734,14 @@ function pointForMaestroTapOnTarget(
     return pointInsideRect(target.rect);
   }
   return {
-    x: interiorCoordinate(target.rect.x, Math.min(target.rect.width, 168)),
-    y: interiorCoordinate(target.rect.y, Math.min(target.rect.height, 48)),
+    x: interiorCoordinate(
+      target.rect.x,
+      Math.min(target.rect.width, MAESTRO_REPLAY_POLICY.largeTextContainerBias.width),
+    ),
+    y: interiorCoordinate(
+      target.rect.y,
+      Math.min(target.rect.height, MAESTRO_REPLAY_POLICY.largeTextContainerBias.height),
+    ),
   };
 }
 
@@ -719,7 +751,12 @@ function shouldBiasMaestroVisibleTextTap(
   rect: Rect,
 ): boolean {
   if (!extractMaestroVisibleTextQuery(selector)) return false;
-  if (rect.height < 70 || rect.width < 120) return false;
+  if (
+    rect.height < MAESTRO_REPLAY_POLICY.largeTextContainerBias.minHeight ||
+    rect.width < MAESTRO_REPLAY_POLICY.largeTextContainerBias.minWidth
+  ) {
+    return false;
+  }
   const type = node.type?.toLowerCase();
   return type === 'cell' || type === 'other' || type === 'scrollview';
 }
diff --git a/src/platforms/ios/apps.ts b/src/platforms/ios/apps.ts
@@ -245,7 +245,7 @@ export async function clearIosSimulatorAppState(
   if (device.platform !== 'ios' || device.kind !== 'simulator') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      'Maestro launchApp.clearState is currently supported only on iOS simulators.',
+      'Clearing app state is currently supported only on iOS simulators.',
     );
   }
 
diff --git a/src/platforms/ios/interactions.ts b/src/platforms/ios/interactions.ts
diff --git a/src/platforms/ios/runner-contract.ts b/src/platforms/ios/runner-contract.ts

Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ export function convertLaunchApp(`
`42`	`42`	`const shouldRelaunch = !shouldClearState && (value.stopApp === true \|\| launchArgs.length > 0);`
`43`	`43`	`return action('open', [appId], {`
`44`	`44`	`...(shouldRelaunch ? { relaunch: true } : {}),`
`45`		`- ...(shouldClearState ? { maestro: { clearState: true } } : {}),`
	`45`	`+ ...(shouldClearState ? { clearAppState: true } : {}),`
`46`	`46`	`...(launchArgs.length > 0 ? { launchArgs } : {}),`
`47`	`47`	`});`
`48`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -357,7 +357,7 @@ function maestroTapOnFlags(value: unknown): SessionAction['flags'] {`
`357`	`357`	`...flags,`
`358`	`358`	`maestro: {`
`359`	`359`	`...(flags.maestro ?? {}),`
`360`		`- allowNonHittableSelectorTap: true,`
	`360`	`+ allowNonHittableCoordinateFallback: true,`
`361`	`361`	`},`
`362`	`362`	`};`
`363`	`363`	`}`