fix: clarify Android gesture transform behavior

Author: thymikee

examples/test-app/README.md

@@ -91,7 +91,9 @@ These run the `.ad` replay suite in `examples/test-app/replays`.
 `gesture-lab.ad` verifies `gesture pan`, `gesture fling`, `gesture pinch`, and
 `gesture rotate` against the gesture metrics rendered by the Home screen on iOS
 and Android. Android and iOS simulator sessions also support `gesture transform`
-for a combined pan/zoom/rotate gesture.
+for a combined pan/zoom/rotate gesture. On Android, treat combined transform
+assertions as qualitative because recognizers can report non-exact centroid,
+scale, and rotation values for one simultaneous two-finger gesture.
 
 To target a specific iOS simulator or an installed Expo development build, run the
 underlying command directly so global flags stay before replay inputs:

examples/test-app/src/screens/GestureLab.tsx

@@ -60,6 +60,7 @@ export function GestureLab() {
   const pinchRef = useRef(null);
   const rotationRef = useRef(null);
   const flingRefs = [flingLeftRef, flingRightRef, flingUpRef, flingDownRef];
+  const activeTransformHandlersRef = useRef(0);
 
   function updateTransform(nextTransform: TransformState) {
     transformRef.current = nextTransform;
@@ -70,6 +71,10 @@ export function GestureLab() {
     gestureStartRef.current = transformRef.current;
   }
 
+  function endTransformGesture() {
+    activeTransformHandlersRef.current = Math.max(activeTransformHandlersRef.current - 1, 0);
+  }
+
   function handlePan(event: PanGestureHandlerGestureEvent) {
     const start = gestureStartRef.current;
     updateTransform({
@@ -102,7 +107,19 @@ export function GestureLab() {
       | RotationGestureHandlerStateChangeEvent,
   ) {
     if (event.nativeEvent.state === State.BEGAN) {
-      beginTransformGesture();
+      if (activeTransformHandlersRef.current === 0) {
+        beginTransformGesture();
+      }
+      activeTransformHandlersRef.current += 1;
+      return;
+    }
+
+    if (
+      event.nativeEvent.state === State.END ||
+      event.nativeEvent.state === State.FAILED ||
+      event.nativeEvent.state === State.CANCELLED
+    ) {
+      endTransformGesture();
     }
   }
 
@@ -163,6 +180,7 @@ export function GestureLab() {
                   simultaneousHandlers={[panRef, rotationRef, ...flingRefs]}
                 >
                   <PanGestureHandler
+                    avgTouches
                     minDist={4}
                     onGestureEvent={handlePan}
                     onHandlerStateChange={handleTransformStateChange}

src/utils/__tests__/args.test.ts

@@ -948,6 +948,9 @@ test('usageForCommand resolves workflow help topic', () => {
   assert.match(help, /wait for a concrete result before returning to chat\/form state/);
   assert.match(help, /choose a point near the center of the intended app-owned target/);
   assert.match(help, /Avoid screen edges, tab bars, navigation bars, and home indicators/);
+  assert.match(help, /Android transform injects a geometric two-finger path/);
+  assert.match(help, /verify qualitative state such as "pan changed yes"/);
+  assert.match(help, /prefer isolated gesture pan, gesture pinch, or gesture rotate/);
   assert.match(help, /longpress accepts coordinates, @refs, or selectors/);
   assert.match(help, /use help react-native for Metro\/Fast Refresh/);
   assert.match(help, /iOS Allow Paste prompt cannot be exercised under XCUITest/);

src/utils/command-schema.ts

@@ -324,6 +324,8 @@ Navigation and gestures:
     agent-device gesture rotate 35 200 420
     agent-device gesture transform 200 420 80 -40 2 35 700
   iOS simulator transform uses XCTest gesture primitives; verify app metrics instead of assuming requested degrees map exactly to recognizer output.
+  Android transform injects a geometric two-finger path; app recognizers may report non-exact pan/scale/rotation. For Android combined transforms, verify qualitative state such as "pan changed yes" / "pinch changed yes" / "rotate changed yes" unless the app explicitly promises exact centroid metrics.
+  If Android needs exact app-state values, prefer isolated gesture pan, gesture pinch, or gesture rotate commands over one combined transform.
 
 Validation and evidence:
   Nearby mutation diff: agent-device diff snapshot -i.

test/skillgym/suites/agent-device-smoke-suite.ts

@@ -1530,14 +1530,25 @@ const SKILL_GUIDANCE_CASES: Case[] = [
       'Zoom scale is 2',
       'Rotation is 35 degrees',
       'Duration is 700ms',
+      'After the command, verify Android changed qualitatively instead of asserting exact x, y, scale, or rotate values',
+    ],
+    task: 'Plan the direct agent-device command for the combined pan, zoom, and rotate gesture, then verify qualitative state.',
+    outputs: [
+      plannedCommand('gesture transform'),
+      /200\s+420\s+80\s+-40\s+2\s+35\s+700/i,
+      plannedCommand('wait'),
+      /pan changed yes/i,
+      /pinch changed yes/i,
+      /rotate changed yes/i,
     ],
-    task: 'Plan the direct agent-device command for the combined pan, zoom, and rotate gesture.',
-    outputs: [plannedCommand('gesture transform'), /200\s+420\s+80\s+-40\s+2\s+35\s+700/i],
     forbiddenOutputs: [
       plannedCommand('gesture pan'),
       plannedCommand('gesture pinch'),
       plannedCommand('gesture rotate'),
       plannedCommand('compose-gestures'),
+      /wait\s+["']?x\s/i,
+      /wait\s+["']?scale\s/i,
+      /wait\s+["']?rotate\s+\d/i,
     ],
   }),
   makeCase({

website/docs/docs/commands.md

@@ -281,6 +281,7 @@ On iOS, swipe duration is clamped to a safe range (`16..60ms`) to avoid longpres
 `gesture rotate` accepts `degrees [x] [y] [velocity]`; the degree sign controls direction and velocity controls speed.
 `gesture transform` accepts `x y dx dy scale degrees [durationMs]` for one combined pan/zoom/rotate gesture on Android and iOS simulators.
 On iOS simulators it is implemented with XCTest gesture primitives, so verify app-level metrics instead of assuming the requested degrees map exactly to recognizer output.
+On Android, `gesture transform` injects a geometric two-finger path. App recognizers may report non-exact pan, scale, and rotation values, so verify qualitative state such as `pan changed yes`, `pinch changed yes`, and `rotate changed yes` unless the app explicitly promises exact centroid metrics. If exact app-state values matter, prefer isolated `gesture pan`, `gesture pinch`, or `gesture rotate` commands.
 `scroll` accepts either a relative amount (`0.5` means roughly half of the viewport on that axis) or `--pixels <n>` for a fixed-distance gesture. Large distances are clamped to the usable drag band so the gesture stays reliable across Android, iOS, and macOS.
 Default snapshot text output is visible-first, so off-screen interactive content is summarized instead of shown as tappable refs.
 When a target only appears in an off-screen summary, use `scroll <direction>` and then take a fresh `snapshot -i`. For repeated checks, a small shell loop is enough: