fix: clarify Android gesture transform behavior

[thymikee]

Summary

Clarify Android combined gesture behavior and stabilize Android multi-touch transform injection.

Android gesture transform remains documented as a geometric two-finger path whose app-level recognizer results may be non-exact. The helper now keeps boundary events synchronous, injects only move frames asynchronously, preserves helper failure messages through explicit parser error codes, and uses a shorter 45s command timeout for slow am instrument returns. The GestureLab fixture also latches simultaneous transform baselines more consistently and uses averaged Android pan touches.

Validation

Verified with pnpm format, pnpm exec vitest run src/utils/__tests__/args.test.ts, pnpm exec vitest run src/platforms/android/__tests__/multitouch-helper.test.ts, pnpm check:quick, pnpm build, pnpm test-app:typecheck, and sh scripts/package-android-multitouch-helper.sh 0.15.2 android-multitouch-helper/dist. Earlier manual Android verification ran Metro on port 8083 with adb reverse tcp:8083 tcp:8083 and verified five gesture transform variations completed through agent-device with clean input state afterward.

Known gap: the emulator/Expo run stayed system-unstable after reboot, with Android framework ANR dialogs and UIAutomator snapshot timeouts, so I could not complete reliable app-text assertions inside Gesture Lab in that pass. Direct helper instrumentation and command-level transforms completed without stale pointers.

Touched 9 files. Scope stays within Android gesture behavior, the GestureLab fixture, CLI/docs guidance, and command-planning assertions.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstackincubator.github.io/agent-device/pr-preview/pr-584/
Built to branch gh-pages at 2026-05-26 06:51 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[thymikee]

Reviewed the Android multi-touch helper changes. The qualitative-state guidance, the helper-failure message preservation, and the GestureLab handler-tag tracking all look like solid improvements.

Main concerns:

1. WAIT_FOR_INPUT_DISPATCH = false is a meaningful semantics change that isn't fully discussed in the description; async injection plus a 32 ms sleep at the tail is the only thing guarding against stuck-pointer state after the final ACTION_UP. Worth either keeping sync mode for the boundary events (DOWN, POINTER_UP, UP, CANCEL) and using async only for intermediate MOVE frames, or at minimum documenting the trade-off and adding a "failure mid-gesture leaves clean state" test.
2. ANDROID_MULTITOUCH_HELPER_GESTURE_TIMEOUT_MS = 90_000 is very generous — 90 s of waiting on a flaky failure mode is a notable UX regression. If 45 s would cover the slow am instrument case, that seems strictly better.
3. The .nojekyll addition to build-docs/action.yml is unrelated to the stated PR scope and should probably be split out.
4. Minor nits: redundant !has(handlerTag) clause in beginTransformGesture; string-match on parser error message in runAndroidMultiTouchHelperGesture should ideally switch to an error code so refactors don't silently break it.

Nothing here is a hard block — happy to re-look once the WAIT_FOR_INPUT_DISPATCH reasoning is clearer.

---

Generated by Claude Code