Skip to content

Commit 6d99914

Browse files
feat!: remove deprecated gesture duration and rotate velocity inputs (#1218, #1216) (#1315)
* feat!: remove deprecated gesture duration and rotate velocity inputs (#1218, #1216) Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fix: address CI failures - remove dead export, dedupe positional validation, migrate linux-desktop swipe test to pan Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fixup! preserve Maestro swipe endpoint-hold execution profile via internal seam Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * docs(adr): describe Maestro endpoint-hold internal seam in ADR 0013/0015 Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * feat: surface Maestro swipe executionProfile in replay trace and assert endpoint-hold in differential Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --------- Co-authored-by: Michał Pierzchała <[email protected]> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
1 parent 3fed8ac commit 6d99914

41 files changed

Lines changed: 494 additions & 370 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
## Unreleased
44

5+
- Breaking: removed deprecated gesture duration and rotate velocity inputs (#1218).
6+
- `swipe x1 y1 x2 y2` no longer accepts a trailing `durationMs` positional; use `gesture pan x1 y1 (x2-x1) (y2-y1) durationMs` for deliberate timed drags.
7+
- Maestro `swipe` operations with a duration continue to normalize to `gesture pan` with the `endpoint-hold` execution profile, preserving the Maestro-compatible fast-swipe-then-hold behavior on iOS.
8+
- `gesture fling direction x y` no longer accepts a trailing `durationMs` positional; use `gesture pan` for timed movement.
9+
- `gesture swipe preset` no longer accepts a trailing `durationMs` positional; use `gesture pan` for timed movement.
10+
- `gesture rotate degrees [x] [y]` no longer accepts a trailing `velocity` positional; rotation pacing is derived from `degrees`.
11+
- MCP/Node schemas no longer advertise `velocity` or `durationMs` on `swipe`/`fling`/`gesture swipe`; `durationMs` remains on `gesture pan` and `gesture transform`.
512
- Breaking: the deprecated `rotate` CLI command alias has been removed. Use `orientation` instead; invoking `rotate` now fails with `rotate was renamed to orientation; for the two-finger gesture use: gesture rotate`.
613
- Breaking (ADR 0014, session ref-frame lifetime): a mutation through an `@ref` now expires the session's ref frame, so a later ref mutation without a fresh observation fails closed with a typed `details.reason` (`ref_frame_expired`, `ref_generation_mismatch`, `plain_ref_requires_complete_frame`, or `ref_not_issued`) instead of acting on a possibly-navigated screen. A ref-oriented sequence that performs several mutations must re-`snapshot` between them, consume an honestly issued `--settle` ref in pinned `@eN~s<gen>` form, or use selectors. Enforcement applies on every platform, not just iOS. Legacy hand-written `.ad` scripts that reuse several bare refs from one snapshot must capture between mutations or use selectors.
714
- Ref reads resolve against the authorized ref frame's source tree, so an internal read-only capture (including Android freshness) can no longer retarget an admitted `@ref` by positional coincidence. Read-only ref consumers keep the structured staleness warning while the frame retains the ref's evidence.

‎docs/adr/0013-unified-gesture-plans.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,22 +22,31 @@ the Android planned-touch executor.
2222
## Decision
2323

2424
Public gesture inputs normalize once in `src/contracts/gesture-normalization.ts`. This is the
25-
explicit compatibility boundary: convenience APIs and deprecated arguments become canonical
26-
semantic intent before entering the runtime. The private daemon wire is free to evolve with that
27-
model; compatibility is owed at CLI, Node.js, and MCP.
25+
explicit public compatibility boundary: canonical semantic intent is produced before entering the
26+
runtime. Deprecated arguments that have been removed (timed `swipe`, timed `gesture fling`,
27+
`gesture rotate` `velocity`) are rejected with actionable `INVALID_ARGS` messages rather than
28+
silently reinterpreted. The private daemon wire remains free to carry compatibility-only hints
29+
that do not appear on public surfaces; Maestro timed swipes use
30+
`internal.gestureExecutionProfile: 'endpoint-hold'` to preserve iOS fast-swipe-then-hold behavior
31+
while still routing through the canonical `pan` input.
2832

2933
The runtime plans canonical intent in `src/contracts/gesture-plan.ts`. Contact topology is separate
3034
from motion:
3135

3236
- one contact: pan or fling with a complete pointer trajectory and an explicit execution profile;
3337
- two contacts: pan, pinch, rotate, or transform with two complete, synchronized trajectories.
3438

35-
`swipe` without a duration is public sugar for a fixed-duration fling. Its historical optional
36-
duration normalizes to pan intent with an endpoint-hold execution profile and reports a deprecation
37-
toward explicit pan. Maestro-authored swipes follow the same normalization and materialize
38-
Maestro's 400 ms default when duration is omitted. A genuine pan uses the timed-pan profile, so
39-
compatibility aliases retain their release behavior without becoming a new semantic intent. The
40-
same deprecation-to-pan rule applies to the historical fling duration. Pinch fixes translation and rotation at zero; rotate fixes
39+
`swipe` without a duration remains public sugar for a fixed-duration fling. Timed public forms
40+
(`swipe x1 y1 x2 y2 durationMs`, `gesture fling direction x y distance durationMs`,
41+
`gesture swipe preset durationMs`, and `gesture rotate degrees x y velocity`) are rejected; callers
42+
must use `gesture pan` for deliberate timed translation and `gesture rotate` without `velocity`.
43+
Maestro-authored swipes normalize to the canonical `pan` input (origin, delta, durationMs) and carry
44+
the `endpoint-hold` execution profile through a daemon-internal compatibility seam
45+
(`internal.gestureExecutionProfile`). This preserves the iOS fast-swipe-then-hold behavior that
46+
matches Maestro's XCTest driver, without exposing the profile on the public command surface. Maestro
47+
materializes its 400 ms default when duration is omitted. A genuine public `pan` uses the `timed-pan`
48+
profile, so compatibility-only paths retain their release behavior without becoming a new semantic
49+
intent. Pinch fixes translation and rotation at zero; rotate fixes
4150
translation at zero and scale at one; two-finger pan fixes scale at one and rotation at zero;
4251
transform can apply all three
4352
components atomically. Intent remains on the plan even when aliases share an executor.

‎docs/adr/0015-direct-maestro-engine.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,11 @@ Android compatibility is materially faster than native Maestro in the pager and
2121
that advantage is a product constraint, not expendable migration headroom.
2222

2323
ADR 0013 separately owns public gesture normalization, contact topology, trajectory planning, and
24-
native injection. Maestro's supported gesture surface is single-pointer swipe only.
24+
native injection. Maestro's supported gesture surface is single-pointer swipe only. Maestro swipes
25+
normalize to ADR 0013's canonical `pan` input (origin, delta, durationMs) and carry the
26+
`endpoint-hold` execution profile through a daemon-internal compatibility seam
27+
(`internal.gestureExecutionProfile`), preserving iOS fast-swipe-then-hold behavior without exposing
28+
the profile on the public command surface.
2529

2630
## Decision
2731

@@ -55,13 +59,17 @@ The engine does not implement platform input. Absolute and percentage swipes pre
5559
endpoints without a hierarchy capture. Directional horizontal swipes reuse ADR 0013's shared in-page
5660
preset geometry so an iOS right swipe does not become an interactive-back gesture; vertical presets
5761
retain Maestro's platform geometry. All viewport-relative swipes resolve the cheapest fresh interaction
58-
viewport available so ADR 0013 can validate every planned sample.
62+
viewport available so ADR 0013 can validate every planned sample. Maestro swipes pair that resolved
63+
viewport with `internal.gestureExecutionProfile: 'endpoint-hold'` on the nested public `gesture` request
64+
so ADR 0013 produces the iOS fast-swipe-then-hold profile without a public `executionProfile` field.
5965
When normalization already resolves a viewport, the adapter pairs it with the nested public gesture
6066
request as daemon-internal metadata. ADR 0013 planning consumes that exact frame instead of probing
6167
the platform a second time.
68+
6269
Target-relative swipes reuse the target-resolution observation. The resulting typed single-pointer
63-
motion enters ADR 0013 after public compatibility normalization. Maestro code cannot construct or
64-
execute two-pointer pan, pinch, rotate, transform, or physical pointer trajectories.
70+
motion enters ADR 0013 as the canonical `pan` input, with the `endpoint-hold` execution profile carried
71+
as daemon-internal metadata. Maestro code cannot construct or execute two-pointer pan, pinch, rotate,
72+
transform, or physical pointer trajectories.
6573

6674
Simple successful target queries return their match, visibility decision, candidate count, and
6775
observation generation in one response. The daemon may retain the provider snapshot behind that

‎scripts/maestro-conformance/differential/invariants.test.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,3 +152,48 @@ test('no device scenario claims to prove percent truncation (bug class 1)', () =
152152
'a 1px truncation delta is not app-observable; keep bug class 1 in runtime-port-geometry.test.ts',
153153
);
154154
});
155+
156+
// --- gestureExecutionProfile: proves the iOS endpoint-hold delivery path ---
157+
158+
const PROFILE_INVARIANT: Invariant = {
159+
kind: 'gestureExecutionProfile',
160+
command: 'swipe',
161+
profile: 'endpoint-hold',
162+
because: 'test',
163+
};
164+
165+
const stopWithProfile = (command: string, executionProfile: string) => ({
166+
type: 'replay_action_stop',
167+
step: 1,
168+
command,
169+
ok: true,
170+
durationMs: 300,
171+
resultTiming: { executionProfile },
172+
});
173+
174+
test('a swipe with endpoint-hold in resultTiming holds the gesture execution profile invariant', () => {
175+
const result = evaluateInvariant([stopWithProfile('swipe', 'endpoint-hold')], PROFILE_INVARIANT);
176+
assert.equal(result.status, 'held');
177+
});
178+
179+
test('a swipe with timed-pan violates the endpoint-hold invariant', () => {
180+
const result = evaluateInvariant([stopWithProfile('swipe', 'timed-pan')], PROFILE_INVARIANT);
181+
assert.equal(result.status, 'violated');
182+
assert.match(result.detail, /timed-pan/);
183+
});
184+
185+
test('a trace with no executionProfile reports no-data', () => {
186+
const result = evaluateInvariant([stop('swipe', 300)], PROFILE_INVARIANT);
187+
assert.equal(result.status, 'no-data');
188+
});
189+
190+
test('percent-swipe asserts the endpoint-hold execution profile in its engine-side invariant', () => {
191+
const scenario = DIFFERENTIAL_SCENARIOS.find((s) => s.id === 'percent-swipe');
192+
const invariant = scenario?.engineInvariants?.[0];
193+
assert.ok(invariant, 'percent-swipe must carry an engine-side invariant');
194+
assert.equal(invariant?.kind, 'gestureExecutionProfile');
195+
assert.equal(
196+
invariant?.kind === 'gestureExecutionProfile' ? invariant.profile : undefined,
197+
'endpoint-hold',
198+
);
199+
});

‎scripts/maestro-conformance/differential/invariants.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ export type Invariant =
4141
metric: 'tapRetries' | 'hierarchyCaptures' | 'screenshotCaptures';
4242
min: number;
4343
because: string;
44+
}
45+
| {
46+
kind: 'gestureExecutionProfile';
47+
command: string;
48+
profile: 'endpoint-hold' | 'timed-pan';
49+
because: string;
4450
};
4551

4652
export type InvariantResult = {
@@ -107,6 +113,32 @@ export function evaluateInvariant(events: TraceEvent[], invariant: Invariant): I
107113
};
108114
}
109115

116+
if (invariant.kind === 'gestureExecutionProfile') {
117+
const profiles = steps
118+
.map((step) => step.resultTiming?.executionProfile)
119+
.filter((value): value is string => typeof value === 'string');
120+
if (profiles.length === 0) {
121+
return {
122+
invariant,
123+
status: 'no-data',
124+
detail: `no ${invariant.command} step recorded an executionProfile`,
125+
};
126+
}
127+
const firstMismatch = profiles.find((profile) => profile !== invariant.profile);
128+
if (firstMismatch !== undefined) {
129+
return {
130+
invariant,
131+
status: 'violated',
132+
detail: `${invariant.command} executionProfile was ${firstMismatch} (expected ${invariant.profile}): ${invariant.because}`,
133+
};
134+
}
135+
return {
136+
invariant,
137+
status: 'held',
138+
detail: `${invariant.command} executionProfile is ${invariant.profile} on ${profiles.length} step(s)`,
139+
};
140+
}
141+
110142
const timed = steps.filter((step) => typeof step.durationMs === 'number');
111143
if (timed.length === 0) {
112144
return {

‎scripts/maestro-conformance/differential/scenarios.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,15 @@ export const DIFFERENTIAL_SCENARIOS: DifferentialScenario[] = [
137137
comparesAcrossEngines:
138138
'A percentage-endpoint swipe completes on both engines. It does NOT compare resolved pixel endpoints — no metric records them and a 1px delta is not app-observable.',
139139
expect: 'pass',
140+
engineInvariants: [
141+
{
142+
kind: 'gestureExecutionProfile',
143+
command: 'swipe',
144+
profile: 'endpoint-hold',
145+
because:
146+
'Maestro timed swipes are normalized to pan with the endpoint-hold execution profile, which the iOS runner delivers as a fast 100ms move followed by a hold.',
147+
},
148+
],
140149
divergenceMeans: 'The swipe behaves differently enough on one engine to fail the flow.',
141150
},
142151
// PARKED: tap-retry-if-no-change (flow kept at differential/flows/, invariant

‎src/cli/parser/__tests__/cli-help-command-usage.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -263,7 +263,7 @@ test('command usage shows command flags without global flags', async () => {
263263
const help = await usageForCommand('swipe');
264264
if (help === null) throw new Error('Expected command help text');
265265
assert.match(help, /Quick coordinate fling with optional repeat pattern/);
266-
assert.match(help, /duration positional is accepted as a deprecated alias to pan/);
266+
assert.doesNotMatch(help, /duration positional is accepted as a deprecated alias to pan/);
267267
assert.match(help, /Command flags:/);
268268
assert.match(help, /--pattern one-way\|ping-pong/);
269269
assert.doesNotMatch(help, /Global flags:/);

‎src/cli/parser/cli-help.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,7 @@ Read-only and waits:
282282
Ambiguous find: add --first or --last. If info is not visible/exposed, report that gap instead of typing/searching/navigating to reveal it.
283283
284284
Navigation and gestures:
285-
Use scroll for lists; swipe for quick coordinate gestures/carousels; gesture pan for deliberate timed drags; gesture fling for fast directional throws. Historical swipe/fling duration arguments remain compatibility aliases to pan and are deprecated.
285+
Use scroll for lists; swipe for quick coordinate gestures/carousels; gesture pan for deliberate timed drags; gesture fling for fast directional throws.
286286
For fast macOS desktop list traversal, prefer fixed pixel wheel steps and batch them when no snapshot is needed between passes:
287287
agent-device scroll down --pixels 200 --duration-ms 50 --platform macos
288288
agent-device batch --steps '[{"command":"scroll","input":{"direction":"down","pixels":200,"durationMs":50}},{"command":"scroll","input":{"direction":"down","pixels":200,"durationMs":50}}]' --platform macos

‎src/client/client-types.ts‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -752,8 +752,6 @@ export type LongPressOptions = DeviceCommandBaseOptions &
752752
export type SwipeOptions = DeviceCommandBaseOptions & {
753753
from: { x: number; y: number };
754754
to: { x: number; y: number };
755-
/** @deprecated Timed movement is a pan. Omit this field for swipe/fling semantics. */
756-
durationMs?: number;
757755
count?: number;
758756
pauseMs?: number;
759757
pattern?: SwipePattern;
@@ -773,14 +771,10 @@ export type FlingOptions = DeviceCommandBaseOptions & {
773771
x: number;
774772
y: number;
775773
distance?: number;
776-
/** @deprecated Timed movement is a pan. Omit this field for fling semantics. */
777-
durationMs?: number;
778774
};
779775

780776
export type SwipeGestureOptions = DeviceCommandBaseOptions & {
781777
preset: SwipePreset;
782-
/** @deprecated Timed movement is a pan. Omit this field for swipe/fling semantics. */
783-
durationMs?: number;
784778
};
785779

786780
export type FocusOptions = DeviceCommandBaseOptions & {
@@ -819,8 +813,6 @@ export type RotateGestureOptions = DeviceCommandBaseOptions & {
819813
degrees: number;
820814
x?: number;
821815
y?: number;
822-
/** @deprecated Rotation pacing is derived from degrees. */
823-
velocity?: number;
824816
};
825817

826818
export type TransformGestureOptions = DeviceCommandBaseOptions & TransformGestureParams;

‎src/commands/cli-grammar/types.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,6 @@ export type CommandInput = Omit<InternalRequestOptions, 'batchSteps' | 'target'>
6969
update?: boolean;
7070
url?: string;
7171
value?: string;
72-
velocity?: number;
7372
x?: number;
7473
y?: number;
7574
} & Record<string, unknown>;

0 commit comments

Comments
 (0)