fix: stabilize maestro post-gesture snapshots

Author: thymikee

src/compat/maestro/__tests__/runtime-interactions.test.ts

@@ -11,13 +11,14 @@ test('invokeMaestroTapOn resolves mutating taps from the current snapshot', asyn
   const selector =
     'label="Article by Gandalf" || text="Article by Gandalf" || id="Article by Gandalf"';
 
-  const { response, clicks, snapshots } = await runTapOn(selector, () =>
+  const { response, clicks, clickFlags, snapshots } = await runTapOn(selector, () =>
     currentBreadcrumbSnapshot(),
   );
 
   expect(response.ok).toBe(true);
   expect(snapshots).toBe(1);
   expect(clicks).toEqual([['86', '89']]);
+  expect(clickFlags[0]?.postGestureStabilization).toBe(true);
 });
 
 test('invokeMaestroTapOn uses optimized interactive snapshots by default', async () => {
@@ -125,6 +126,7 @@ test('invokeMaestroTapOn clicks explicit React Native overlay controls directly'
 
 test('invokeMaestroSwipeScreen maps horizontal directional swipes to native gesture presets', async () => {
   const gestures: string[][] = [];
+  const gestureFlags: Array<DaemonRequest['flags']> = [];
   const response = await invokeMaestroSwipeScreen({
     baseReq: {
       token: 'test',
@@ -135,6 +137,7 @@ test('invokeMaestroSwipeScreen maps horizontal directional swipes to native gest
     invoke: async (req: DaemonRequest): Promise<DaemonResponse> => {
       if (req.command === 'gesture') {
         gestures.push(req.positionals ?? []);
+        gestureFlags.push(req.flags);
         return { ok: true, data: {} };
       }
       return { ok: false, error: { code: 'UNEXPECTED_COMMAND', message: req.command } };
@@ -143,6 +146,7 @@ test('invokeMaestroSwipeScreen maps horizontal directional swipes to native gest
 
   expect(response.ok).toBe(true);
   expect(gestures).toEqual([['swipe', 'left', '300']]);
+  expect(gestureFlags[0]?.postGestureStabilization).toBeUndefined();
 });
 
 test('invokeMaestroSwipeScreen mirrors horizontal directional swipe presets', async () => {
@@ -169,6 +173,7 @@ test('invokeMaestroSwipeScreen mirrors horizontal directional swipe presets', as
 
 test('invokeMaestroSwipeScreen preserves vertical percentage endpoints', async () => {
   const swipes: string[][] = [];
+  const swipeFlags: Array<DaemonRequest['flags']> = [];
   const response = await invokeMaestroSwipeScreen({
     baseReq: {
       token: 'test',
@@ -182,6 +187,7 @@ test('invokeMaestroSwipeScreen preserves vertical percentage endpoints', async (
       }
       if (req.command === 'swipe') {
         swipes.push(req.positionals ?? []);
+        swipeFlags.push(req.flags);
         return { ok: true, data: {} };
       }
       return { ok: false, error: { code: 'UNEXPECTED_COMMAND', message: req.command } };
@@ -190,6 +196,7 @@ test('invokeMaestroSwipeScreen preserves vertical percentage endpoints', async (
 
   expect(response.ok).toBe(true);
   expect(swipes).toEqual([['200', '600', '200', '280', '300']]);
+  expect(swipeFlags[0]?.postGestureStabilization).toBe(true);
 });
 
 test('invokeMaestroSwipeScreen keeps Android horizontal percentage swipes on the content lane', async () => {
@@ -219,6 +226,7 @@ test('invokeMaestroSwipeScreen keeps Android horizontal percentage swipes on the
 
 test('invokeMaestroTapPointPercent shares percentage point geometry without clamping', async () => {
   const clicks: string[][] = [];
+  const clickFlags: Array<DaemonRequest['flags']> = [];
   const response = await invokeMaestroTapPointPercent({
     baseReq: {
       token: 'test',
@@ -232,6 +240,7 @@ test('invokeMaestroTapPointPercent shares percentage point geometry without clam
       }
       if (req.command === 'click') {
         clicks.push(req.positionals ?? []);
+        clickFlags.push(req.flags);
         return { ok: true, data: {} };
       }
       return { ok: false, error: { code: 'UNEXPECTED_COMMAND', message: req.command } };
@@ -240,6 +249,7 @@ test('invokeMaestroTapPointPercent shares percentage point geometry without clam
 
   expect(response.ok).toBe(true);
   expect(clicks).toEqual([['500', '-80']]);
+  expect(clickFlags[0]?.postGestureStabilization).toBe(true);
 });
 
 function currentBreadcrumbSnapshot(): SnapshotState {
@@ -277,10 +287,12 @@ async function runTapOn(
   response: DaemonResponse;
   commands: string[];
   clicks: string[][];
+  clickFlags: Array<DaemonRequest['flags']>;
   snapshots: number;
 }> {
   const commands: string[] = [];
   const clicks: string[][] = [];
+  const clickFlags: Array<DaemonRequest['flags']> = [];
   let snapshots = 0;
   const response = await invokeMaestroTapOn({
     baseReq: {
@@ -297,12 +309,13 @@ async function runTapOn(
       }
       if (req.command === 'click') {
         clicks.push(req.positionals ?? []);
+        clickFlags.push(req.flags);
         return { ok: true, data: {} };
       }
       return { ok: false, error: { code: 'UNEXPECTED_COMMAND', message: req.command } };
     },
   });
-  return { response, commands, clicks, snapshots };
+  return { response, commands, clicks, clickFlags, snapshots };
 }
 
 function fullScreenSnapshot(width: number, height: number): SnapshotState {

src/compat/maestro/runtime-interactions.ts

@@ -147,6 +147,10 @@ export async function invokeMaestroTapPointPercent(params: {
     ...params.baseReq,
     command: 'click',
     positionals: [String(point.x), String(point.y)],
+    flags: {
+      ...params.baseReq.flags,
+      postGestureStabilization: true,
+    },
   });
 }
 
@@ -235,6 +239,10 @@ async function invokeSwipeGesture(
       String(swipe.end.y),
       ...(durationMs ? [durationMs] : []),
     ],
+    flags: {
+      ...params.baseReq.flags,
+      postGestureStabilization: true,
+    },
   });
 }
 
@@ -479,6 +487,7 @@ async function clickMaestroSnapshotTarget(
     flags: {
       ...params.baseReq.flags,
       interactionOutcome: { retryOnNoChange: true },
+      postGestureStabilization: true,
     },
   });
   if (response.ok) clearMaestroVisibleContext(params.scope);
@@ -502,6 +511,7 @@ async function invokeMaestroFuzzyTapOn(
       ...params.baseReq.flags,
       findFirst: true,
       interactionOutcome: { retryOnNoChange: true },
+      postGestureStabilization: true,
     },
   });
   emitDiagnostic({

src/core/dispatch-context.ts

@@ -20,6 +20,7 @@ export type CommandFlags = Omit<CliFlags, DaemonExcludedCliFlag> & {
   };
   launchArgs?: string[];
   maestro?: MaestroRuntimeFlags;
+  postGestureStabilization?: boolean;
   replayBackend?: string;
 };
 

src/daemon/__tests__/interaction-outcome-policy.test.ts

@@ -84,11 +84,12 @@ test('markPendingInteractionOutcome stores retry state only for explicit retry f
   assert.equal(longPressSession.pendingInteractionOutcome, undefined);
 });
 
-test('stripInternalInteractionOutcomeFlags removes internal retry controls', () => {
+test('stripInternalInteractionOutcomeFlags removes internal interaction controls', () => {
   assert.deepEqual(
     stripInternalInteractionOutcomeFlags({
       platform: 'ios',
       interactionOutcome: { retryOnNoChange: true },
+      postGestureStabilization: true,
     }),
     { platform: 'ios' },
   );

src/daemon/__tests__/post-gesture-stabilization.test.ts

@@ -28,6 +28,22 @@ test('markPostGestureStabilization marks Android swipe sessions', () => {
   assert.equal(session.postGestureStabilization?.action, 'swipe');
 });
 
+test('markPostGestureStabilization marks gesture swipe sessions', () => {
+  const session = makeSession('android');
+
+  markPostGestureStabilization(session, 'gesture', ['swipe', 'left']);
+
+  assert.equal(session.postGestureStabilization?.action, 'gesture');
+});
+
+test('markPostGestureStabilization ignores non-swipe gesture sessions', () => {
+  const session = makeSession('android');
+
+  markPostGestureStabilization(session, 'gesture', ['pinch', 'in']);
+
+  assert.equal(session.postGestureStabilization, undefined);
+});
+
 test('capturePostGestureStabilizedSnapshot retries until rects stop moving', async () => {
   vi.useFakeTimers();
   const session = makeSession();

src/daemon/handlers/__tests__/session-replay-vars.test.ts

@@ -1889,9 +1889,17 @@ test('runReplayScriptFile runs Maestro runFlow.when.visible commands when presen
   assert.deepEqual(calls.find((call) => call.command === 'click')?.flags?.interactionOutcome, {
     retryOnNoChange: true,
   });
+  assert.equal(
+    calls.find((call) => call.command === 'click')?.flags?.postGestureStabilization,
+    true,
+  );
   assert.deepEqual(calls.find((call) => call.command === 'find')?.flags?.interactionOutcome, {
     retryOnNoChange: true,
   });
+  assert.equal(
+    calls.find((call) => call.command === 'find')?.flags?.postGestureStabilization,
+    true,
+  );
 });
 
 test('runReplayScriptFile runs nested Maestro runtime commands inside runFlow.when', async () => {

src/daemon/handlers/interaction-common.ts

@@ -13,6 +13,7 @@ import {
   markPendingInteractionOutcome,
   stripInternalInteractionOutcomeFlags,
 } from '../interaction-outcome-policy.ts';
+import { markPostGestureStabilization } from '../post-gesture-stabilization.ts';
 
 export type ContextFromFlags = (
   flags: CommandFlags | undefined,
@@ -115,6 +116,7 @@ export function finalizeTouchInteraction(params: {
   if (isNavigationSensitiveAction(command)) {
     markAndroidSnapshotFreshness(session, command, androidFreshnessBaseline ?? session.snapshot);
   }
+  markPostGestureStabilization(session, command, retryPositionals ?? positionals, flags);
   recordTouchVisualizationEvent(
     session,
     command,

src/daemon/interaction-outcome-policy.ts

@@ -137,8 +137,12 @@ export function emitInteractionSettleTimeout(params: {
 export function stripInternalInteractionOutcomeFlags(
   flags: CommandFlags | undefined,
 ): CommandFlags | undefined {
-  if (!flags?.interactionOutcome) return flags;
-  const { interactionOutcome: _interactionOutcome, ...publicFlags } = flags;
+  if (!flags?.interactionOutcome && !flags?.postGestureStabilization) return flags;
+  const {
+    interactionOutcome: _interactionOutcome,
+    postGestureStabilization: _postGestureStabilization,
+    ...publicFlags
+  } = flags;
   return publicFlags;
 }
 

src/daemon/post-gesture-stabilization.ts

@@ -1,4 +1,5 @@
 import { emitDiagnostic } from '../utils/diagnostics.ts';
+import type { CommandFlags } from '../core/dispatch.ts';
 import type { SnapshotState } from '../utils/snapshot.ts';
 import { sleep } from '../utils/timeouts.ts';
 import {
@@ -10,9 +11,14 @@ import type { SessionState } from './types.ts';
 const STABILIZATION_DEADLINE_MS = 1_500;
 const STABILIZATION_INTERVAL_MS = 200;
 
-export function markPostGestureStabilization(session: SessionState, action: string): void {
+export function markPostGestureStabilization(
+  session: SessionState,
+  action: string,
+  positionals: string[] = [],
+  flags?: CommandFlags,
+): void {
   if (!supportsPostGestureStabilization(session.device.platform)) return;
-  if (!isPostGestureStabilizingAction(action)) return;
+  if (!isPostGestureStabilizingAction(action, positionals, flags)) return;
   session.postGestureStabilization = {
     action,
     markedAt: Date.now(),
@@ -74,8 +80,14 @@ export async function capturePostGestureStabilizedSnapshot(params: {
   return previous;
 }
 
-function isPostGestureStabilizingAction(action: string): boolean {
-  return action === 'swipe' || action === 'scroll';
+function isPostGestureStabilizingAction(
+  action: string,
+  positionals: string[],
+  flags: CommandFlags | undefined,
+): boolean {
+  if (flags?.postGestureStabilization === true) return true;
+  if (action === 'swipe' || action === 'scroll') return true;
+  return action === 'gesture' && positionals[0] === 'swipe';
 }
 
 function supportsPostGestureStabilization(platform: SessionState['device']['platform']): boolean {

src/daemon/request-generic-dispatch.ts

@@ -120,7 +120,7 @@ export async function dispatchGenericCommand(params: {
   if (isNavigationSensitiveAction(platformCommand)) {
     markAndroidSnapshotFreshness(session, platformCommand);
   }
-  markPostGestureStabilization(session, platformCommand);
+  markPostGestureStabilization(session, platformCommand, resolvedPositionals, req.flags);
 
   return { ok: true, data: data ?? {} };
 }