Skip to content

Commit 84f170e

Browse files
committed
fix(settle): resolve the default quiet window from the capture that pays it
`--settle` asked every capture the same 500 ms quiet window. The iOS simulator snapshot bridge answers well inside it, so the loop spends a whole extra capture holding a window the tree has already satisfied — and the window is paid twice per settled command: once as the settle's final window, then again as the next command's baseline capture. The loop now prices the window from the capture it performs rather than the one the action was performed against: an unrequested `--settle` resolves 300 ms when that read came from the simulator snapshot bridge, and 500 ms for the Apple runner's own tree read, the Android helper, and any capture that declares no provenance — only the bridge carries the measurement. It re-prices on every capture, so a mid-run fallback to a more expensive read widens the remaining wait, and it reports the window it ran on (`settle.quietMs`) so the response states which default it applied. Keying on the baseline's producer was the first cut and is wrong: the window governs the loop's own reads, and a stored ref frame or session tree can be several commands stale or served by another producer. Keying on the channel would be wrong too — the bridge and the Apple runner share `xctest` and read at different costs. `--settle-quiet` still outranks both, and `wait stable` keeps the general default of its own. Cadence follows the window in force, so the shorter default also samples on a grid that can measure it. The loop's window, quiet clock, and recovery budget moved to one owner each in the same pass, which is what makes the re-pricing a single line rather than a fourth piece of loop state. The trap this layer owes the layer under it is pinned by name: a 300 ms default sits under the 1.5 s confirmation floor, so the arming rule that layer removed must not come back. Mutation check: with `requestedQuietMs >= DEFAULT_STABLE_QUIET_MS` restored in the arming path, that case is the only one in the file that fails — i.e. the shorter default would have silently switched the #1831 guard off for every default settle the bridge answers.
1 parent 4952ad4 commit 84f170e

8 files changed

Lines changed: 622 additions & 143 deletions

File tree

‎packages/command-registry/src/flag-definitions-action.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,7 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
211211
min: 0,
212212
usageLabel: '--settle-quiet <ms>',
213213
usageDescription:
214-
'Settle: quiet window the UI must hold to count as settled (default 500ms). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the --timeout settle deadline',
214+
'Settle: quiet window the UI must hold to count as settled (default 500ms; 300ms when the settled tree comes from the iOS simulator snapshot bridge). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the --timeout settle deadline',
215215
projectConfig: true,
216216
recorded: false,
217217
},

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ export type RepeatedPressOptions = {
2525
* Opt-in (#1101): after the action, wait for the UI to go quiet and return the
2626
* settled diff vs the pre-action tree (`settle` on the result) in the same
2727
* response. Best-effort — never fails the action. `settleQuietMs` tunes the
28-
* quiet window (default 500ms); `timeoutMs` bounds the settle wait (default
28+
* quiet window (default 500ms, or 300ms when the settled tree comes from the iOS
29+
* simulator snapshot bridge); `timeoutMs` bounds the settle wait (default
2930
* 10s) when `settle` is true. A bare `timeoutMs` without `settle` is ignored
3031
* for compatibility; `settleQuietMs` still requires `settle`.
3132
*/
Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import type { SnapshotProvenance, SnapshotState } from '@agent-device/kernel/snapshot';
4+
import { ref } from './selector-read-utils.ts';
5+
import {
6+
buttonSnapshot,
7+
createSettleDevice,
8+
welcomeSnapshot,
9+
} from './__tests__/settle-device-fixtures.ts';
10+
11+
// The `--settle` DEFAULT quiet window keys on the capture the settle loop PERFORMS (#3470
12+
// follow-up), because that read is the one the window prices: the loop holds its quiet window open
13+
// across captures of its own. The pre-action baseline cannot answer this — on the ref route it is
14+
// the stored ref frame, on the generic route the session's stored tree, and either can be several
15+
// commands stale and served by a producer other than the one settle then reads through. A caller
16+
// that asks for a window with `--settle-quiet` always outranks the default.
17+
//
18+
// Budgets are injected (fake clock) — no real waiting.
19+
20+
function withProvenance<P extends SnapshotProvenance>(state: SnapshotState, provenance: P) {
21+
return { ...state, ...provenance };
22+
}
23+
24+
const BRIDGE = { backend: 'xctest', producer: 'simulator-ax-bridge' } as const;
25+
const RUNNER = { backend: 'xctest', producer: 'apple-runner' } as const;
26+
27+
/**
28+
* A press whose baseline and whose loop captures come from declared capture paths, so the two can
29+
* be made to agree or to disagree.
30+
*/
31+
function pressWithCapturePaths(params: {
32+
baseline?: SnapshotProvenance;
33+
loop?: SnapshotProvenance;
34+
settle?: { quietMs?: number; timeoutMs?: number };
35+
}) {
36+
const baseline = params.baseline
37+
? withProvenance(buttonSnapshot(), params.baseline)
38+
: buttonSnapshot();
39+
let captures = 0;
40+
const device = createSettleDevice({
41+
stored: baseline,
42+
captureSnapshot: () => {
43+
captures += 1;
44+
// A ref press captures nothing before the action, so every call is the loop's own sample.
45+
const settled = welcomeSnapshot();
46+
return {
47+
snapshot:
48+
captures === 1 ? baseline : params.loop ? withProvenance(settled, params.loop) : settled,
49+
};
50+
},
51+
});
52+
return device.interactions.press(ref('@e1'), { session: 'default', settle: params.settle ?? {} });
53+
}
54+
55+
test('a settle the simulator snapshot bridge performs uses the shorter default window', async () => {
56+
const result = await pressWithCapturePaths({ loop: BRIDGE });
57+
58+
const settle = result.settle;
59+
assert.ok(settle);
60+
assert.equal(settle.settled, true);
61+
assert.equal(settle.quietMs, 300);
62+
});
63+
64+
test('an explicit --settle-quiet outranks the per-capture default window', async () => {
65+
const result = await pressWithCapturePaths({ loop: BRIDGE, settle: { quietMs: 700 } });
66+
67+
const settle = result.settle;
68+
assert.ok(settle);
69+
assert.equal(settle.quietMs, 700);
70+
});
71+
72+
// Each of these is a read the 300 ms default was NOT measured on, so shortening its window would be
73+
// an unmeasured change of behaviour rather than the measured one. The Apple runner shares the
74+
// `xctest` CHANNEL with the bridge, which is why the rule keys on the producer.
75+
const UNMEASURED_CAPTURES: Array<[string, SnapshotProvenance?]> = [
76+
['the Apple runner tree read (same channel, different producer)', RUNNER],
77+
['an Appium-sourced tree on the same channel', { backend: 'xctest', producer: 'appium-source' }],
78+
['the Android helper', { backend: 'android', producer: 'android-uiautomator' }],
79+
['a capture that declares no provenance at all', undefined],
80+
];
81+
82+
for (const [label, provenance] of UNMEASURED_CAPTURES) {
83+
test(`${label} keeps the 500ms default window`, async () => {
84+
const result = await pressWithCapturePaths({ loop: provenance });
85+
86+
const settle = result.settle;
87+
assert.ok(settle);
88+
assert.equal(settle.quietMs, 500);
89+
});
90+
}
91+
92+
test('a bridge read during settle earns the shorter window even from a runner-issued ref frame', async () => {
93+
// The ref frame the action was authorized against came from the runner, so keying the window on
94+
// the baseline would hold the unmeasured 500 ms against captures the bridge answered.
95+
const result = await pressWithCapturePaths({ baseline: RUNNER, loop: BRIDGE });
96+
97+
const settle = result.settle;
98+
assert.ok(settle);
99+
assert.equal(settle.quietMs, 300);
100+
});
101+
102+
test('a runner read during settle keeps the 500ms window despite a bridge-issued baseline', async () => {
103+
// The unsafe direction of the same mismatch: holding 300 ms for a read priced at 500 ms would
104+
// settle on a window the measurement never covered.
105+
const result = await pressWithCapturePaths({ baseline: BRIDGE, loop: RUNNER });
106+
107+
const settle = result.settle;
108+
assert.ok(settle);
109+
assert.equal(settle.quietMs, 500);
110+
});
111+
112+
test('the shorter default window never shortens a broad-transition confirmation', async () => {
113+
// The trap this layer owes layer 1: a 300 ms default sits under the 1.5 s floor, so a rule that
114+
// armed on `requestedQuietMs >= DEFAULT_STABLE_QUIET_MS` would silently switch the #1831
115+
// confirmation off for every default settle the bridge answers. Here the pre-action tree is the
116+
// tiny-baseline shape, so the confirmation owns the wait and the 300 ms default still holds its
117+
// 1.5 s floor (#3470).
118+
const sparseBaseline = withProvenance(buttonSnapshot(), BRIDGE);
119+
let captures = 0;
120+
const device = createSettleDevice({
121+
stored: sparseBaseline,
122+
captureSnapshot: () => {
123+
captures += 1;
124+
return {
125+
snapshot: captures === 1 ? sparseBaseline : withProvenance(welcomeSnapshot(), BRIDGE),
126+
};
127+
},
128+
});
129+
130+
const result = await device.interactions.press(ref('@e1'), {
131+
session: 'default',
132+
settle: { timeoutMs: 5_000 },
133+
});
134+
135+
const settle = result.settle;
136+
assert.ok(settle);
137+
assert.equal(settle.settled, true);
138+
assert.equal(settle.quietMs, 300);
139+
assert.ok(
140+
settle.waitedMs >= 1_500,
141+
`confirmation did not outlast the shorter default: waitedMs=${settle.waitedMs}`,
142+
);
143+
});

‎src/commands/interaction/runtime/settle.ts‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -126,12 +126,20 @@ async function settleAfterAction(
126126
options: CommandContext,
127127
params: SettleParams & { baseline: SurfaceScopedNodes; actionPoint?: Point },
128128
): Promise<SettleOutcome> {
129-
const quietMs = params.quietMs ?? DEFAULT_STABLE_QUIET_MS;
129+
// The loop resolves an unrequested window from the capture that pays it, so the window is only
130+
// known once one is taken. `base` carries the general default for the pre-capture shape the
131+
// observation still has to report; `readSettledOutcome` replaces it with the window the loop ran.
130132
const timeoutMs = params.timeoutMs ?? DEFAULT_STABLE_TIMEOUT_MS;
131-
const base: SettleObservation = { settled: false, waitedMs: 0, captures: 0, quietMs, timeoutMs };
133+
const base: SettleObservation = {
134+
settled: false,
135+
waitedMs: 0,
136+
captures: 0,
137+
quietMs: params.quietMs ?? DEFAULT_STABLE_QUIET_MS,
138+
timeoutMs,
139+
};
132140
try {
133141
const outcome = await runStableCaptureLoop(runtime, options, {
134-
quietMs,
142+
...(params.quietMs === undefined ? {} : { quietMs: params.quietMs }),
135143
timeoutMs,
136144
resetBudgetOnPrivateAxRecovery: true,
137145
broadTransitionBaselineNodes: params.baseline.nodes,
@@ -162,6 +170,9 @@ async function readSettledOutcome(
162170
settled: outcome.settled,
163171
waitedMs: outcome.waitedMs,
164172
captures: outcome.captures,
173+
// The window the loop actually ran. For an unrequested settle that is the one its own captures
174+
// priced, which `base` cannot know because it is built before the first read.
175+
quietMs: outcome.quietMs,
165176
};
166177
if (!outcome.lastCapture) {
167178
return {

‎src/commands/interaction/runtime/stable-capture.test.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,37 @@ test('settle confirms a tiny modal replacement through a partial post-action pro
326326
);
327327
});
328328

329+
test('a dismissal confirmation is not dropped by a later empty projection', async () => {
330+
// The confirmation is a fact about the transition, so it survives a capture that stops qualifying.
331+
// The comparison refuses a node-less side, so re-deciding it per capture hands the loop its short
332+
// window again mid-confirmation — and the next empty read matches it, settling on two empty
333+
// projections 302ms after a dismissal that owed 1.5s (#3470).
334+
const { runtime } = transitionRuntime({
335+
settledAtMs: 0,
336+
emptyProjectionAtCaptures: [2, 3],
337+
});
338+
339+
const outcome = await runStableCaptureLoop(
340+
runtime,
341+
{ session: 'default' },
342+
{
343+
quietMs: 150,
344+
timeoutMs: 5_000,
345+
broadTransitionBaselineNodes: elementThreadsNoticeSnapshot.nodes,
346+
},
347+
);
348+
349+
assert.equal(outcome.settled, true);
350+
assert.ok(
351+
outcome.waitedMs >= 1_500,
352+
`empty projection disarmed the confirmation: settled after ${outcome.waitedMs}ms`,
353+
);
354+
assert.ok(
355+
outcome.lastCapture!.snapshot.nodes.length > 0,
356+
'settled on an empty projection instead of the dismissed screen',
357+
);
358+
});
359+
329360
test('settle keeps the default quiet window for a larger partial projection', async () => {
330361
const { runtime } = transitionRuntime({ omitViewportRoot: true, settledAtMs: 1_200 });
331362

@@ -458,6 +489,8 @@ function transitionRuntime(
458489
omitViewportRoot?: boolean;
459490
settledAtMs?: number;
460491
sessionSnapshot?: SnapshotState;
492+
/** 1-based capture indices that answer with an empty projection (mid-animation read). */
493+
emptyProjectionAtCaptures?: number[];
461494
} = {},
462495
) {
463496
const captureBackend = options.captureBackend ?? 'tree';
@@ -476,6 +509,14 @@ function transitionRuntime(
476509
captureSnapshot: async () => {
477510
const keepsBaseline = options.firstCaptureKeepsBaseline === true && captures === 0;
478511
captures += 1;
512+
if (options.emptyProjectionAtCaptures?.includes(captures)) {
513+
return {
514+
snapshot: withCaptureBackend(
515+
{ ...elementSettledRoomSnapshot, nodes: [] },
516+
captureBackend,
517+
),
518+
};
519+
}
479520
const snapshot = keepsBaseline
480521
? elementThreadsNoticeSnapshot
481522
: withCaptureBackend(

0 commit comments

Comments
 (0)