Skip to content

Commit 4a67a37

Browse files
committed
fix(android): cap the controlled-release tail at the gesture duration ceiling
The release tail was appended after buildGesturePlan's own duration validation, so a maximum-duration (10000ms) scroll silently produced a 10160ms plan beyond GESTURE_DURATION_MAX_MS. Cap the tail so the dispatched plan never exceeds that shared ceiling, shrinking (and, at the exact maximum, dropping) the tail near the boundary instead of truncating the requested move. Add regression coverage for the exact maximum and near-maximum cases. Also fix the stale android-lifecycle provider-integration expectation: a plain scroll resolves to 'controlled' release by default, so its dispatched plan is now 510ms (350ms move + 160ms tail), not 350ms.
1 parent fce45a3 commit 4a67a37

3 files changed

Lines changed: 81 additions & 5 deletions

File tree

‎packages/platform-android/src/__tests__/input-actions.test.ts‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { test, vi } from 'vitest';
22
import assert from 'node:assert/strict';
33
import { GESTURE_SAMPLE_INTERVAL_MS } from '@agent-device/contracts/gesture-plan';
4+
import { GESTURE_DURATION_MAX_MS } from '@agent-device/contracts/gesture-plan-types';
45
import {
56
backAndroid,
67
homeAndroid,
@@ -157,6 +158,64 @@ test('scrollAndroid composes the duration floor with the default controlled-rele
157158
assert.equal(touchCalls[0]!.durationMs, GESTURE_SAMPLE_INTERVAL_MS + 160);
158159
});
159160

161+
test('scrollAndroid caps the controlled-release tail at the maximum gesture duration without shortening the move', async () => {
162+
const touchCalls: Parameters<AndroidTouchInjector>[0][] = [];
163+
const result = await withAndroidAdbProvider(
164+
{
165+
exec: async () => {
166+
throw new Error('adb must not run');
167+
},
168+
gestureViewport: async () => ({ x: 0, y: 0, width: 1080, height: 1920 }),
169+
touch: async (request) => {
170+
touchCalls.push(request);
171+
},
172+
},
173+
{ serial: ANDROID_EMULATOR.id },
174+
async () =>
175+
await scrollAndroid(ANDROID_EMULATOR, 'down', {
176+
pixels: 1800,
177+
durationMs: GESTURE_DURATION_MAX_MS,
178+
}),
179+
);
180+
181+
// The requested move is honored in full — never truncated to make room for the tail.
182+
assert.equal(result.durationMs, GESTURE_DURATION_MAX_MS);
183+
const [touch] = touchCalls;
184+
// At the exact ceiling there is no headroom left for a tail; the dispatched plan still never
185+
// exceeds GESTURE_DURATION_MAX_MS, the same boundary every gesture plan is built under.
186+
assert.equal(touch!.durationMs, GESTURE_DURATION_MAX_MS);
187+
assert.equal(touch!.pointers[0]!.samples.at(-1)!.offsetMs, GESTURE_DURATION_MAX_MS);
188+
});
189+
190+
test('scrollAndroid shrinks (but keeps) the controlled-release tail just under the maximum gesture duration', async () => {
191+
const touchCalls: Parameters<AndroidTouchInjector>[0][] = [];
192+
const nearMaxDurationMs = GESTURE_DURATION_MAX_MS - 50;
193+
const result = await withAndroidAdbProvider(
194+
{
195+
exec: async () => {
196+
throw new Error('adb must not run');
197+
},
198+
gestureViewport: async () => ({ x: 0, y: 0, width: 1080, height: 1920 }),
199+
touch: async (request) => {
200+
touchCalls.push(request);
201+
},
202+
},
203+
{ serial: ANDROID_EMULATOR.id },
204+
async () =>
205+
await scrollAndroid(ANDROID_EMULATOR, 'down', {
206+
pixels: 1800,
207+
durationMs: nearMaxDurationMs,
208+
}),
209+
);
210+
211+
assert.equal(result.durationMs, nearMaxDurationMs);
212+
const [touch] = touchCalls;
213+
// Only 50ms of headroom below the ceiling: the tail shrinks to 3 whole 16ms steps (48ms)
214+
// rather than pushing the plan past GESTURE_DURATION_MAX_MS.
215+
assert.equal(touch!.durationMs, nearMaxDurationMs + 48);
216+
assert.ok(touch!.durationMs <= GESTURE_DURATION_MAX_MS);
217+
});
218+
160219
test('scrollAndroid jitters the axis orthogonal to a horizontal scroll, holding the scroll axis fixed', async () => {
161220
const touchCalls: Parameters<AndroidTouchInjector>[0][] = [];
162221
await withAndroidAdbProvider(

‎packages/platform-android/src/input-actions.ts‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@
44
*/
55
import { DEVICE_ROTATION_SURFACE_INDEX, type DeviceRotation } from '@agent-device/contracts/device';
66
import { GESTURE_SAMPLE_INTERVAL_MS, buildGesturePlan } from '@agent-device/contracts/gesture-plan';
7-
import { GESTURE_DURATION_MIN_MS } from '@agent-device/contracts/gesture-plan-types';
7+
import {
8+
GESTURE_DURATION_MAX_MS,
9+
GESTURE_DURATION_MIN_MS,
10+
} from '@agent-device/contracts/gesture-plan-types';
811
import type {
912
GesturePlan,
1013
PointerTrajectorySample,
@@ -240,7 +243,7 @@ export async function scrollAndroid(
240243
const CONTROLLED_RELEASE_TAIL_MS = 160;
241244

242245
/**
243-
* A short, quivering tail appended after a 'controlled' scroll's endpoint, adding
246+
* A short, quivering tail appended after a 'controlled' scroll's endpoint, adding up to
244247
* `CONTROLLED_RELEASE_TAIL_MS` of real time to the gesture. AOSP's `InputConsumer::rewriteMessage`
245248
* collapses a MOVE that repeats the previous coordinates into a "resampled" sample, and
246249
* `VelocityTracker` skips resampled samples — so a truly stationary tail never reaches the
@@ -251,21 +254,30 @@ const CONTROLLED_RELEASE_TAIL_MS = 160;
251254
* vertical scrolls on a `RecyclerView` and an RN `ScrollView` (issue #2371); not independently
252255
* verified against every OEM skin or a Compose `LazyColumn`. An 'inertial' release (the
253256
* `scroll top`/`scroll bottom` edge passes) lifts at the pan's endpoint unchanged.
257+
*
258+
* The dispatched plan never exceeds `GESTURE_DURATION_MAX_MS` — the same ceiling every gesture
259+
* plan is built under — so the tail shrinks (and, at the exact maximum, disappears) for a move
260+
* already at or near that limit; the requested move itself is never shortened to make room.
254261
*/
255262
function withControlledReleaseTail(
256263
plan: GesturePlan,
257264
viewport: Rect,
258265
direction: ScrollDirection,
259266
): GesturePlan {
260267
if (plan.topology !== 'single') return plan;
268+
const tailMs = Math.max(
269+
0,
270+
Math.min(CONTROLLED_RELEASE_TAIL_MS, GESTURE_DURATION_MAX_MS - plan.durationMs),
271+
);
272+
const steps = Math.floor(tailMs / GESTURE_SAMPLE_INTERVAL_MS);
273+
if (steps === 0) return plan;
261274
const [pointer] = plan.pointers;
262275
const end = pointer.samples.at(-1)!;
263276
const horizontal = direction === 'left' || direction === 'right';
264277
const jitterBase = horizontal ? end.point.y : end.point.x;
265278
const jitterMin = (horizontal ? viewport.y : viewport.x) + 1;
266279
const jitterMax = (horizontal ? viewport.y + viewport.height : viewport.x + viewport.width) - 1;
267280
const nudged = jitterBase + 1 <= jitterMax ? jitterBase + 1 : Math.max(jitterMin, jitterBase - 1);
268-
const steps = CONTROLLED_RELEASE_TAIL_MS / GESTURE_SAMPLE_INTERVAL_MS;
269281
const tail: PointerTrajectorySample[] = Array.from({ length: steps }, (_, index) => {
270282
const jitter = index % 2 === 0 ? nudged : jitterBase;
271283
return {
@@ -281,7 +293,7 @@ function withControlledReleaseTail(
281293
];
282294
return {
283295
...plan,
284-
durationMs: plan.durationMs + CONTROLLED_RELEASE_TAIL_MS,
296+
durationMs: plan.durationMs + steps * GESTURE_SAMPLE_INTERVAL_MS,
285297
pointers: [{ ...pointer, samples }],
286298
};
287299
}

‎test/integration/provider-scenarios/android-lifecycle.test.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,12 @@ test(ANDROID_TOUCH_CONTRACT_EVIDENCE.testName, async () => {
226226
}));
227227
assert.deepEqual(touchCalls, [
228228
{ topology: 'single', intent: 'longPress', pointerCount: 1, durationMs: 750 },
229-
{ topology: 'single', intent: 'pan', pointerCount: 1, durationMs: 350 },
229+
// `scroll down` has no edge, so it resolves to the default 'controlled' release: the
230+
// requested 350ms move plus the 160ms release tail that defeats Android's fling (#2371).
231+
// 'inertial' (the `scroll top`/`scroll bottom` edge passes, which lift at the pan's
232+
// endpoint unchanged) is covered at the unit level in
233+
// packages/platform-android/src/__tests__/input-actions.test.ts.
234+
{ topology: 'single', intent: 'pan', pointerCount: 1, durationMs: 510 },
230235
{ topology: 'single', intent: 'pan', pointerCount: 1, durationMs: 300 },
231236
{ topology: 'single', intent: 'pan', pointerCount: 1, durationMs: 500 },
232237
{ topology: 'two', intent: 'pan', pointerCount: 2, durationMs: 500 },

0 commit comments

Comments
 (0)