Skip to content

Commit 3099f3d

Browse files
committed
feat(daemon): let a finishing mutation record the tree it acted through (#3471)
The history the gate reads. The session's deferred surface becomes a two-variant claim — `stabilize` (the capture side still owes a quiet-window loop) or `recheck` (a mutation dispatched through a captured tree whose own effect may still be animating) — and a mutation that resolved a target records that tree at the instant it finished, so the next press can ask whether its own coordinates are still in play. ADR 0014's device side-effect seam retires the record, and a press never erases a stabilization the capture side still owes. The `targetStability` matrix cells, their Layer-3 scenarios on both runtime paths, and the caller-facing help/docs land with it: the refusal is observable from here. Closes #3471.
1 parent db4540a commit 3099f3d

27 files changed

Lines changed: 785 additions & 75 deletions

‎packages/contracts/src/interaction-guarantees.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,15 @@ export const INTERACTION_GUARANTEES = [
8383
// a settled diff). Distinct from the opt-in verifyEvidence/settleObservation features; this is the
8484
// path's baseline, always-on claim.
8585
'outcomeObservation',
86+
// The position the path dispatches at is one the target is confirmed to be at REST in (#3471).
87+
// Distinct from every guard above: those judge a tree, this judges the tree against the previous
88+
// action's tree. A capture is one instant's photograph of a surface that may still be
89+
// rearranging itself, and the ADB-backed Android helper is measured reporting frames in flight,
90+
// so a press issued right after an action that animated the UI can resolve a point the target has
91+
// already vacated and report success on the vacancy. The gate is backend-neutral: it re-observes
92+
// past the window and refuses rather than dispatching at a position two observations disagree
93+
// about.
94+
'targetStability',
8695
] as const;
8796

8897
export type InteractionGuarantee = (typeof INTERACTION_GUARANTEES)[number];
@@ -151,6 +160,21 @@ export type InteractionPathContract = {
151160
const GAPS_UMBRELLA_ISSUE = 'https://github.com/callstack/agent-device/issues/1081';
152161
const TAP_OUTCOME_NOT_OBSERVED_GAP_ISSUE = 'https://github.com/callstack/agent-device/issues/3335';
153162

163+
/**
164+
* The moving-target gate's shared cell (#3471). Scoped to the two commands that dispatch a tap the
165+
* daemon aimed at a rect it captured: `fill` aims at a field it expects to be found wherever it
166+
* is, and its own staleness failure mode is a wrong focus rather than a silent miss, which the
167+
* guard's re-resolve would not fix. `longpress` aims the same way and is deliberately left out for
168+
* now: a hold that begins one frame early is a gesture the recognizer still owns, the measured
169+
* failure and the caller-visible recovery are both tap-shaped, and widening this list is one
170+
* declaration plus one scenario per added command.
171+
*/
172+
const RUNTIME_TREE_TARGET_STABILITY: GuaranteeEnforcement = {
173+
kind: 'runtime',
174+
via: 'src/commands/interaction/runtime/moving-target-gate.ts#guardResolvedTargetAgainstMotion',
175+
appliesTo: ['press', 'click'],
176+
};
177+
154178
// Every path shares the SAME cell by construction: response payloads have one
155179
// construction site (ADR 0011 Layer 2), and the hand-rolled-literal guard test
156180
// (interaction-response-construction-guard.test.ts) keeps new branches on it.
@@ -193,6 +217,16 @@ const DIRECT_IOS_OUTCOME_NOT_OBSERVED_GAP: GuaranteeEnforcement = {
193217
trackingIssue: TAP_OUTCOME_NOT_OBSERVED_GAP_ISSUE,
194218
};
195219

220+
/**
221+
* Shares the SAME reasoning as DIRECT_IOS_SINGLE_QUERY_READINESS: the fused request is one XCTest
222+
* round trip, so it also cannot carry a stale daemon-captured position into the tap.
223+
*/
224+
const DIRECT_IOS_TARGET_STABILITY: GuaranteeEnforcement = {
225+
kind: 'waived',
226+
reason:
227+
"Intentional: the fused runner request queries the element and taps it inside one XCTest request, so the runner aims at the element's own live frame at tap time rather than at a rect the daemon captured earlier and carried across a round trip — the capture-to-dispatch distance #3471 closes does not exist on this route. Its hittability semantics stay the runner's, as the offscreen cell above already records.",
228+
};
229+
196230
// The two runtime tree paths (selector and ref resolution) run the SAME shared
197231
// guard/observation implementations; only how the target is found
198232
// (disambiguation) and how failures are described (errorTaxonomy) differ.
@@ -260,6 +294,7 @@ const RUNTIME_TREE_SHARED_GUARANTEES = {
260294
kind: 'runtime',
261295
via: 'src/commands/interaction/runtime/settle.ts#settleAfterInteraction',
262296
},
297+
targetStability: RUNTIME_TREE_TARGET_STABILITY,
263298
} satisfies Partial<Record<InteractionGuarantee, GuaranteeEnforcement>>;
264299

265300
export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPathContract> = {
@@ -390,6 +425,11 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
390425
'gap: target-authored drag has no --settle/--verify observation of the destination; the tap-shaped runtime paths are the only ones with an opt-in evidence route today.',
391426
trackingIssue: GAPS_UMBRELLA_ISSUE,
392427
},
428+
targetStability: {
429+
kind: 'inapplicable',
430+
reason:
431+
"Drag endpoints name contact coordinates for one uninterrupted pointer plan (ADR 0013); re-pointing an endpoint after resolution would split the plan the gesture's integrity depends on, and a drag whose surface moved mid-gesture is the surface behavior, not a misaimed tap. #3471 guards the tap-shaped paths, where one captured point is the whole action.",
432+
},
393433
},
394434
},
395435
'native-ref': {
@@ -475,6 +515,11 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
475515
'gap: the fast path observes no post-action outcome by default; --settle/--verify disable it and delegate to runtime-ref instead of running here.',
476516
trackingIssue: GAPS_UMBRELLA_ISSUE,
477517
},
518+
targetStability: {
519+
kind: 'inapplicable',
520+
reason:
521+
'The fast path activates a provider-owned semantic handle rather than a point the daemon aimed from a capture, so there is no daemon-captured position that could have gone stale — the exposure #3471 guards is created by capture-to-dispatch distance and this path has none. Where the daemon does read a rect on this path, its preflight reads the same stored node the other guards judge.',
522+
},
478523
},
479524
},
480525
coordinate: {
@@ -538,6 +583,11 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
538583
'Coordinates name a point, not an element; there is no target existence to wait for.',
539584
},
540585
outcomeObservation: TAP_OUTCOME_NOT_OBSERVED_GAP,
586+
targetStability: {
587+
kind: 'inapplicable',
588+
reason:
589+
'Coordinates are the escape hatch that dispatches the point it was given; there is no resolved element whose position could be confirmed, and re-resolving a caller-authored coordinate would replace the instruction rather than verify it.',
590+
},
541591
},
542592
},
543593
'maestro-direct-selector': {
@@ -601,6 +651,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
601651
},
602652
targetReadiness: DIRECT_IOS_SINGLE_QUERY_READINESS,
603653
outcomeObservation: DIRECT_IOS_OUTCOME_NOT_OBSERVED_GAP,
654+
targetStability: DIRECT_IOS_TARGET_STABILITY,
604655
},
605656
},
606657
'maestro-non-hittable-fallback': {
@@ -664,6 +715,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
664715
},
665716
targetReadiness: DIRECT_IOS_SINGLE_QUERY_READINESS,
666717
outcomeObservation: DIRECT_IOS_OUTCOME_NOT_OBSERVED_GAP,
718+
targetStability: DIRECT_IOS_TARGET_STABILITY,
667719
},
668720
},
669721
};

‎src/__tests__/daemon-composition/handlers/snapshot-handler-freshness.test.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,12 @@ test('snapshot annotations survive a deferred post-gesture capture into CLI JSON
166166
];
167167
const snapshotQuality = { state: 'healthy', backend: 'tree' };
168168
session.snapshot = { nodes: baselineNodes, createdAt: Date.now(), backend: 'android' };
169-
session.postGestureStabilization = { action: 'swipe', positionals: [], markedAt: Date.now() };
169+
session.deferredSurface = {
170+
kind: 'stabilize',
171+
action: 'swipe',
172+
positionals: [],
173+
markedAt: Date.now(),
174+
};
170175
sessionStore.publish(sessionName, session);
171176

172177
legacyDispatchCapture.mockResolvedValue({

‎src/commands/interaction/metadata.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ const FIND_ACTION_VALUES = [
5757

5858
const interactionCommandDescriptions = {
5959
click:
60-
'Activate a UI target by snapshot ref, selector, or coordinates. Prefer a ref or selector after a snapshot; use coordinates only when semantic targeting is unavailable. This can change app state. Success means the click was dispatched, not that it landed: use settle or verify to confirm the result without a follow-up snapshot, or wait for the expected screen.',
60+
"Activate a UI target by snapshot ref, selector, or coordinates. Prefer a ref or selector after a snapshot; use coordinates only when semantic targeting is unavailable. This can change app state. Success means the click was dispatched, not that it landed: use settle or verify to confirm the result without a follow-up snapshot, or wait for the expected screen. A target still moving shortly after the session's previous action is re-observed and tapped at its resting position; one that has not stopped refuses with target_still_moving rather than tapping where it was.",
6161
press:
62-
'Short-press a UI target by snapshot ref, selector, or coordinates. Use longpress instead when the target requires a context-menu or hold gesture. Success means the press was dispatched, not that it landed: use settle or verify to confirm the result, or wait for the expected screen.',
62+
"Short-press a UI target by snapshot ref, selector, or coordinates. Use longpress instead when the target requires a context-menu or hold gesture. Success means the press was dispatched, not that it landed: use settle or verify to confirm the result, or wait for the expected screen. A target still moving shortly after the session's previous action is re-observed and tapped at its resting position; one that has not stopped refuses with target_still_moving rather than tapping where it was.",
6363
fill: 'Replace text in a UI input selected by snapshot ref, selector, or coordinates. Pass an empty text to clear the field. Inspect unconfirmed evidence and assert the expected value or resulting screen before continuing. Prefer refs or selectors after snapshot; use recordAs to keep sensitive text out of a recorded replay while sending it to the live app.',
6464
longpress:
6565
'Hold a UI target by snapshot ref, selector, or coordinates to open a context menu or perform another hold gesture. Set durationMs when the default hold duration is unsuitable.',

‎src/daemon/__tests__/deferred-interaction-outcome.test.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { afterEach, test, vi } from 'vitest';
33
import {
44
isPostGestureStabilizationPending,
55
markDeferredInteractionOutcome,
6+
pendingSurfaceStabilization,
67
markPostOpenStabilization,
78
resolveDeferredInteractionOutcome,
89
stripInternalInteractionFlags,
@@ -105,8 +106,8 @@ test('an Apple open that could not observe its app marks stabilization without a
105106
markPostOpenStabilization(session, 'unobservable');
106107

107108
assert.equal(isPostGestureStabilizationPending(session), true);
108-
assert.equal(session.postGestureStabilization?.action, 'open');
109-
assert.equal(session.postGestureStabilization?.baselineSignature, undefined);
109+
assert.equal(pendingSurfaceStabilization(session)?.action, 'open');
110+
assert.equal(pendingSurfaceStabilization(session)?.baselineSignature, undefined);
110111
});
111112

112113
test('every open verdict other than observable marks stabilization', () => {

‎src/daemon/__tests__/direct-ios-selector.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ test('isLocalIosRunnerSession: iOS local sessions are eligible, Android and unde
119119

120120
test('isLocalIosRunnerSession: skipPendingPostGestureStabilization:true excludes a pending session (the tap fast path)', () => {
121121
const pending = makeSession('ios', {
122-
postGestureStabilization: { action: 'scroll', positionals: [], markedAt: Date.now() },
122+
deferredSurface: { kind: 'stabilize', action: 'scroll', positionals: [], markedAt: Date.now() },
123123
});
124124
assert.equal(
125125
isLocalIosRunnerSession(pending, { skipPendingPostGestureStabilization: true }),
@@ -129,7 +129,7 @@ test('isLocalIosRunnerSession: skipPendingPostGestureStabilization:true excludes
129129

130130
test('isLocalIosRunnerSession: skipPendingPostGestureStabilization:false keeps a pending session eligible (the offscreen double-check)', () => {
131131
const pending = makeSession('ios', {
132-
postGestureStabilization: { action: 'scroll', positionals: [], markedAt: Date.now() },
132+
deferredSurface: { kind: 'stabilize', action: 'scroll', positionals: [], markedAt: Date.now() },
133133
});
134134
assert.equal(
135135
isLocalIosRunnerSession(pending, { skipPendingPostGestureStabilization: false }),

‎src/daemon/__tests__/generic-settle.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ vi.mock('../interaction/index.ts', async (importOriginal) => {
3939

4040
import { captureSnapshotForSession } from '../interaction/index.ts';
4141
import { dispatchGenericCommand } from '../request-generic-dispatch.ts';
42+
import { pendingSurfaceStabilization } from '../deferred-interaction-outcome.ts';
4243

4344
const mockCaptureSnapshotForSession = vi.mocked(captureSnapshotForSession);
4445

@@ -94,7 +95,7 @@ async function emulateCaptureSnapshotForSession(
9495
) {
9596
captureObservations.push({
9697
postGestureStabilizationPending:
97-
sessionStore.requireCurrent(ref).postGestureStabilization !== undefined,
98+
pendingSurfaceStabilization(sessionStore.requireCurrent(ref)) !== undefined,
9899
});
99100
const effectiveFlags = { ...(flags ?? {}), snapshotInteractiveOnly: options.interactiveOnly };
100101
const snapshotData = (await mockDispatch('snapshot')) as Parameters<typeof buildSnapshotState>[0];

0 commit comments

Comments
 (0)