Skip to content

Commit 181935c

Browse files
strzhaoclaude
andcommitted
refactor(contracts): take the gesture duration from its last canonical offset
The separate durationMs argument could disagree with the samples and the guard guarding that could not fire from the only caller. The last offset IS the duration: the parameter, its guard, its reason and its test are gone, and a path of fewer than two timed samples refuses with GESTURE_PATH_TOO_SHORT. Evidence adds the live Android pan and scroll through the densified helper path. Co-Authored-By: Claude Code <[email protected]>
1 parent d41e77e commit 181935c

4 files changed

Lines changed: 73 additions & 28 deletions

File tree

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Android densified lowering through the shared densifyGesturePath, 2026-11-13
2+
3+
Evidence for #4239's Android side: the reshaped lowering
4+
(`lowerAndroidTouchPlan` calling the shared `densifyGesturePath`) ran on
5+
hardware — one pan and one scroll — and both strokes executed through the
6+
densified Android helper path.
7+
8+
## Device and build
9+
10+
- Redmi K60 (Android), adb serial `5p4hqglvpzxshiuw`, Settings app foreground
11+
- agent-device head at this commit, built in the contribution worktree, daemon
12+
restarted clean; the Android automation helper (0.32.0 build, packaged under
13+
this tree's version name) was installed with `adb install -t` before the run
14+
15+
## The runs
16+
17+
```json
18+
{
19+
"kind": "pan",
20+
"backend": "android-helper",
21+
"executionProfile": "timed-pan",
22+
"message": "Panned (500, 1400) by (0, -600)"
23+
}
24+
```
25+
26+
```json
27+
{
28+
"message": "Scrolled down",
29+
"success": true
30+
}
31+
```
32+
33+
`gesture pan --json` names `backend: android-helper` and
34+
`executionProfile: timed-pan` — the timed densified dispatch the lowering
35+
produces — and `scroll down` succeeded through the same plan builder. The
36+
screen visibly scrolled in both runs.
37+
38+
## What this evidences
39+
40+
The shared `densifyGesturePath` rewiring is behavior-preserving on the Android
41+
transport: the sampled-path rule it owns still produces the timed interior
42+
samples the helper's recognizer consumes, at the same cadence the Android
43+
lowering produced before the rewiring. CI covers the pure function and the
44+
lowering; this run covers the live dispatch path on hardware.

‎packages/contracts/src/gesture-plan.test.ts‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ test('densifyGesturePath merges the profile grid into the canonical path and kee
9090
{ offsetMs: 100, point: { x: 100, y: 0 } },
9191
{ offsetMs: 200, point: { x: 100, y: 100 } },
9292
];
93-
const dense = densifyGesturePath(canonical, 200, 'default');
93+
const dense = densifyGesturePath(canonical, 'default');
9494

9595
// The 16 ms grid and the canonical offsets merge into one ascending timeline.
9696
const offsets = dense.map(({ offsetMs }) => offsetMs);
@@ -113,7 +113,7 @@ test('densifyGesturePath hands within-segment pacing to the progress hook and ke
113113
{ offsetMs: 100, point: { x: 100, y: 0 } },
114114
];
115115
const seen: Array<[number, number]> = [];
116-
const dense = densifyGesturePath(canonical, 100, 'default', (progress, segmentDurationMs) => {
116+
const dense = densifyGesturePath(canonical, 'default', (progress, segmentDurationMs) => {
117117
seen.push([progress, segmentDurationMs]);
118118
return progress * progress;
119119
});
@@ -133,13 +133,20 @@ test('densifyGesturePath hands within-segment pacing to the progress hook and ke
133133
assert.deepEqual(dense.at(-1)?.point, { x: 100, y: 0 });
134134
});
135135

136-
test('densifyGesturePath refuses a duration that disagrees with the last canonical offset', () => {
137-
const canonical = [
138-
{ offsetMs: 0, point: { x: 0, y: 0 } },
139-
{ offsetMs: 100, point: { x: 100, y: 0 } },
140-
];
136+
test('densifyGesturePath refuses a path of fewer than two timed samples', () => {
141137
assert.throws(
142-
() => densifyGesturePath(canonical, 150, 'default'),
143-
/must equal the last canonical sample offset/,
138+
() => densifyGesturePath([{ offsetMs: 0, point: { x: 0, y: 0 } }], 'default'),
139+
/at least two timed samples/,
140+
);
141+
assert.throws(
142+
() =>
143+
densifyGesturePath(
144+
[
145+
{ offsetMs: 0, point: { x: 0, y: 0 } },
146+
{ offsetMs: 0, point: { x: 1, y: 0 } },
147+
],
148+
'default',
149+
),
150+
/at least two timed samples/,
144151
);
145152
});

‎packages/contracts/src/gesture-plan.ts‎

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -471,26 +471,24 @@ export function sampleGestureOffsets(
471471
/**
472472
* Densifies a plan's own timed path onto one merged sampling grid: the profile grid and the
473473
* canonical offsets merge, every merged offset interpolates inside its canonical segment, and the
474-
* endpoints and duration stay the plan's. This is the one owner of the sampled-path rule; every
474+
* endpoints and duration stay the plan's — the duration IS the last canonical offset, so a
475+
* disagreeing duration cannot be written. This is the one owner of the sampled-path rule; every
475476
* transport lowering calls it instead of keeping its own merge-and-interpolate loop. The optional
476477
* progress hook lets a transport reshape within-segment pacing (Android's controlled scroll) while
477478
* the segment walk and the endpoint rule stay shared.
478479
*/
479480
export function densifyGesturePath(
480481
canonical: readonly PointerTrajectorySample[],
481-
durationMs: number,
482482
profile: GestureSamplingProfile,
483483
progress: (baseProgress: number, segmentDurationMs: number) => number = (p) => p,
484484
): PointerTrajectorySample[] {
485-
// The plan's last offset is its duration; a disagreement between the two
486-
// arguments would extrapolate past the final sample or drop its endpoint.
487-
const last = canonical.at(-1);
488-
if (!last || last.offsetMs !== durationMs) {
489-
throw new AppError(
490-
'INVALID_ARGS',
491-
'gesture sample duration must equal the last canonical sample offset',
492-
{ reason: 'GESTURE_SAMPLE_DURATION_MISMATCH', durationMs },
493-
);
485+
// The walk reads each segment's end, so a path of fewer than two timed samples has no
486+
// interpolable segment; the last offset is the duration the sampling grid builds on.
487+
const durationMs = canonical.at(-1)?.offsetMs ?? 0;
488+
if (canonical.length < 2 || !Number.isFinite(durationMs) || durationMs <= 0) {
489+
throw new AppError('INVALID_ARGS', 'gesture path needs at least two timed samples', {
490+
reason: 'GESTURE_PATH_TOO_SHORT',
491+
});
494492
}
495493
const offsets = [
496494
...new Set([

‎packages/platform-android/src/touch-plan-lowering.ts‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -62,14 +62,10 @@ export function lowerAndroidTouchPlan(plan: AndroidTouchPlan): AndroidLoweredTou
6262

6363
const { releaseBehavior, ...gesturePlan } = plan;
6464
const [{ pointerId, samples: canonicalSamples }] = gesturePlan.pointers;
65-
const dense = densifyGesturePath(
66-
canonicalSamples,
67-
plan.durationMs,
68-
'android',
69-
(progress, segmentDurationMs) =>
70-
releaseBehavior === 'controlled'
71-
? controlledScrollProgress(progress, segmentDurationMs)
72-
: progress,
65+
const dense = densifyGesturePath(canonicalSamples, 'android', (progress, segmentDurationMs) =>
66+
releaseBehavior === 'controlled'
67+
? controlledScrollProgress(progress, segmentDurationMs)
68+
: progress,
7369
);
7470
// The sampler floors the frame count at three, so `dense` always holds at least four samples.
7571
const samples: AndroidTransportSamples = [dense[0]!, dense[1]!, dense[2]!, ...dense.slice(3)];

0 commit comments

Comments
 (0)