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/__tests__/session.test.ts

@@ -2135,6 +2135,7 @@ test('prepare ios-runner starts the XCTest runner on an explicit iOS selector',
     expect.objectContaining({ platform: 'ios', id: 'sim-1' }),
     { command: 'uptime' },
     expect.objectContaining({
+      cleanStaleBundles: true,
       logPath: expect.stringMatching(/daemon\.log$/),
       requestId: 'prepare-request',
     }),

src/daemon/handlers/__tests__/snapshot-handler.test.ts

@@ -802,6 +802,82 @@ test('captureSnapshot lazily retries pending no-change touch before returning fr
   expect(session.pendingInteractionOutcome).toBeUndefined();
 });
 
+test('captureSnapshot prioritizes pending tap outcome retry over post-gesture stabilization', async () => {
+  const sessionName = 'android-maestro-tap-outcome-before-stabilization';
+  const session = makeSession(sessionName, androidDevice);
+  const baselineNodes = [
+    {
+      ref: 'e1',
+      index: 0,
+      depth: 0,
+      type: 'android.widget.Button',
+      label: 'Navigate to Third',
+      hittable: true,
+      rect: { x: 302, y: 1301, width: 476, height: 110 },
+    },
+  ];
+  session.snapshot = {
+    nodes: baselineNodes,
+    createdAt: Date.now(),
+    backend: 'android',
+  };
+  session.pendingInteractionOutcome = {
+    action: 'click',
+    command: 'press',
+    positionals: ['540', '1356'],
+    flags: { platform: 'android' },
+    markedAt: Date.now(),
+    attemptsRemaining: 2,
+    preSignature: [
+      {
+        key: '|Navigate to Third||android.widget.Button||enabled|unselected|hittable|#0',
+        x: 302,
+        y: 1301,
+        width: 476,
+        height: 110,
+      },
+    ],
+  };
+  session.postGestureStabilization = {
+    action: 'click',
+    markedAt: Date.now(),
+  };
+
+  mockDispatch
+    .mockResolvedValueOnce({
+      nodes: baselineNodes,
+      backend: 'android',
+    })
+    .mockResolvedValueOnce({ clicked: true })
+    .mockResolvedValueOnce({
+      nodes: [
+        {
+          index: 0,
+          depth: 0,
+          type: 'android.widget.TextView',
+          label: 'Tab Third (3)',
+          rect: { x: 390, y: 884, width: 300, height: 55 },
+        },
+      ],
+      backend: 'android',
+    });
+
+  const result = await captureSnapshot({
+    device: androidDevice,
+    session,
+    flags: { snapshotInteractiveOnly: true },
+    logPath: '/tmp/daemon.log',
+  });
+
+  expect(result.snapshot.nodes).toEqual(
+    expect.arrayContaining([expect.objectContaining({ label: 'Tab Third (3)' })]),
+  );
+  expect(mockDispatch.mock.calls.map((call) => call[1])).toEqual(['snapshot', 'press', 'snapshot']);
+  expect(mockDispatch.mock.calls[1]?.[2]).toEqual(['540', '1356']);
+  expect(session.pendingInteractionOutcome).toBeUndefined();
+  expect(session.postGestureStabilization).toBeUndefined();
+});
+
 test('captureSnapshot composes pending outcome retry with Android freshness capture', async () => {
   const sessionName = 'android-lazy-outcome-freshness';
   const session = makeSession(sessionName, androidDevice);

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/handlers/session.ts

@@ -110,6 +110,7 @@ function buildPrepareIosRunnerOptions(
     verbose: req.flags?.verbose,
     logPath,
     traceLogPath: session?.trace?.outPath,
+    cleanStaleBundles: true,
     requestId: req.meta?.requestId,
   };
 }