Skip to content

Commit f168edd

Browse files
strzhaoclaude
andcommitted
fix(interaction): batch-press review absorption — recording refusal, refusal details, first-key identity, per-key rest check
Absorb the independent review of the multi-ref press sequence: - Daemon admission refuses a multi-ref press plan while script recording is armed, and refuses a plan step that still carries a replay target guard: both shapes replay through the single-ref path, so the step would press only the first key and report the rest as sent — the ADR 0014 false-success class. - sequence_ref_unmatched now carries details.executed and details.pending beside details.ref, and the message names the keys already pressed, as the shared reason contract and command help promise. - sequence_option_conflict registers in INTERACTION_ERROR_REASONS instead of a one-off reason string. - The response's target identity is the first key, the member the command's target positional named; sequence.points still carries where every key landed, in plan order. - Each later key passes a rest check anchored on the previous key's dispatch — the session baseline is retired at the first key's side-effect seam and the frame a gate re-resolution would spend is expired — so a key the window cannot settle refuses with the shared target_still_moving reason, the same outcome a standalone press meets, instead of dispatching mid-animation. - Parse layer: a space-separated second ref on press/click refuses with the comma-sequence hint instead of becoming a fallback label, and a plan refuses a trailing positional instead of dropping it silently. - Help sync: the click facet documents the sequence form, the intervalMs schema description covers key-to-key delay, and the press cliDetail names details.executed/details.pending and the recording refusal. Co-Authored-By: Claude Code <[email protected]>
1 parent 02fc744 commit f168edd

13 files changed

Lines changed: 615 additions & 42 deletions

File tree

‎packages/command-runtime/src/commands/interaction/runtime/moving-target-gate.ts‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,24 @@ export const MOVING_TARGET_GATE_WINDOW_MS = 500;
8282
const ANDROID_MOVING_TARGET_WINDOW_MS = 1_500;
8383
const ANDROID_TARGET_QUIET_MS = 100;
8484

85+
/**
86+
* The motion window one platform judges a freshly resolved rect against, or
87+
* `undefined` for the default window. Shared by the ordinary press gate and the
88+
* multi-ref sequence's per-key guard, so a sequence key asks the same question
89+
* a standalone press asks after the same previous action.
90+
*/
91+
function movingTargetGateWindowMs(platform: string): number | undefined {
92+
return platform === 'android' ? ANDROID_MOVING_TARGET_WINDOW_MS : undefined;
93+
}
94+
95+
/** The platform's window as the `movingTargetGateDecision` parameter, absent for the default. */
96+
export function windowParamForPlatform(
97+
platform: string,
98+
): { windowMs: number } | Record<string, never> {
99+
const windowMs = movingTargetGateWindowMs(platform);
100+
return windowMs === undefined ? {} : { windowMs };
101+
}
102+
85103
/**
86104
* How far apart the two observations must be for agreeing to mean "at rest". Below one capture
87105
* round trip, two observations of a still-moving target agree by timing rather than by the target
@@ -144,9 +162,7 @@ async function readMovingTargetGate(
144162
baselineFinishedAtMs: baseline.finishedAt,
145163
targetShownAtRest: baselineShowsTargetAtRest(baseline, resolvedNode, resolvedSurface),
146164
nowMs: now(runtime),
147-
...(runtime.backend.platform === 'android'
148-
? { windowMs: ANDROID_MOVING_TARGET_WINDOW_MS }
149-
: {}),
165+
...windowParamForPlatform(runtime.backend.platform),
150166
});
151167
return decision.kind === 'recheck' ? decision : undefined;
152168
}
@@ -385,8 +401,13 @@ function targetStillMovingHint(params: { selector: string | undefined }): string
385401
* `movedToRect` is the one optional member: a re-observation that measured nothing (the ref kept its
386402
* authorized frame node) has no position to name, and an absent value is the honest report rather
387403
* than a stale one.
404+
*
405+
* Exported because the multi-ref sequence's per-key guard raises the same refusal for a later key:
406+
* the sequence cannot re-run this module's recheck (it re-resolves the `@ref` through the frame,
407+
* which the sequence's first dispatch already expired), so it re-finds the key by identity and
408+
* raises this refusal when its two looks disagree.
388409
*/
389-
function motionRefusal(
410+
export function motionRefusal(
390411
resolved: Exclude<ResolvedInteractionTarget, { kind: 'point' }>,
391412
movedToRect: Rect | undefined,
392413
waitedMs: number,

‎packages/command-runtime/src/commands/interaction/runtime/press-sequence.test.ts‎

Lines changed: 147 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ import { createInteractionDevice } from './__tests__/test-utils/index.ts';
77
/**
88
* The multi-ref press sequence (`press @e1,@e2,...`): the plan is minted once
99
* against the frame, the first key dispatches at its mint point, and each later
10-
* key is re-found by identity on a fresh capture and dispatched at its fresh
11-
* point.
10+
* key is re-found by identity on a fresh capture, passed through the per-key
11+
* rest check, and dispatched at the point that check leaves standing.
1212
*/
1313

1414
function keyNode(label: string, rect: { x: number; y: number }): RawSnapshotNode {
@@ -49,24 +49,64 @@ function padAfterPressSnapshot(dotCount: number): SnapshotState {
4949
]);
5050
}
5151

52-
function sequenceDevice(captures: SnapshotState[]) {
52+
/** The pad with key "2" at an arbitrary row: two of these animate one in-flight key. */
53+
function padWithKey2At(y: number): SnapshotState {
54+
return makeSnapshotState([
55+
keyNode('1', { x: 10, y: 100 }),
56+
keyNode('2', { x: 70, y }),
57+
keyNode('3', { x: 130, y: 100 }),
58+
]);
59+
}
60+
61+
/**
62+
* A clock whose reads step far past the moving-target window, so each later key
63+
* is judged `not-recent` and dispatches at its first identity look. The window's
64+
* own behavior is pinned by the dedicated rest-check tests below.
65+
*/
66+
function clockPastMotionWindow() {
67+
let reading = 0;
68+
return {
69+
now: () => (reading += 10_000),
70+
sleep: async () => {},
71+
};
72+
}
73+
74+
/** A clock frozen at t0, so every later key lands inside the motion window. */
75+
function clockFrozenInMotionWindow(waits: number[] = []) {
76+
return {
77+
now: () => 0,
78+
sleep: async (ms: number) => {
79+
waits.push(ms);
80+
},
81+
};
82+
}
83+
84+
function sequenceDevice(
85+
captures: SnapshotState[],
86+
clock?: { now: () => number; sleep: (ms: number) => Promise<void> },
87+
) {
5388
const taps: Array<{ point: Point }> = [];
89+
const queue = [...captures];
5490
const device = createInteractionDevice(keyPadSnapshot(), {
5591
captureSnapshot: async () => {
56-
const snapshot = captures.shift();
92+
const snapshot = queue.shift();
5793
if (!snapshot) throw new Error('unexpected capture');
5894
return { snapshot };
5995
},
6096
tap: async (_context, point) => {
6197
taps.push({ point });
6298
return { ok: true };
6399
},
100+
...(clock ? { clock } : {}),
64101
});
65102
return { device, taps };
66103
}
67104

68105
test('sequence presses each key in order at its fresh position and reports the plan', async () => {
69-
const { device, taps } = sequenceDevice([padAfterPressSnapshot(1), padAfterPressSnapshot(2)]);
106+
const { device, taps } = sequenceDevice(
107+
[padAfterPressSnapshot(1), padAfterPressSnapshot(2)],
108+
clockPastMotionWindow(),
109+
);
70110

71111
const result = await device.interactions.press(
72112
{ kind: 'ref', ref: '@e1' },
@@ -92,6 +132,32 @@ test('sequence presses each key in order at its fresh position and reports the p
92132
});
93133
});
94134

135+
test('the response identity is the first key; sequence.points carries every landing', async () => {
136+
const { device, taps } = sequenceDevice(
137+
[padAfterPressSnapshot(1), padAfterPressSnapshot(2)],
138+
clockPastMotionWindow(),
139+
);
140+
141+
const result = await device.interactions.press(
142+
{ kind: 'ref', ref: '@e1' },
143+
{ session: 'default', refs: ['e1', 'e2', 'e3'] },
144+
);
145+
146+
// The response names the member the command's target positional named, at
147+
// the point that key was dispatched at; the later keys live in the summary.
148+
if (result.kind !== 'ref' || result.target?.kind !== 'ref') {
149+
throw new Error(`expected a ref result, got ${JSON.stringify(result)}`);
150+
}
151+
assert.equal(result.target.ref, '@e1');
152+
assert.deepEqual(result.point, { x: 35, y: 125 });
153+
assert.deepEqual(result.sequence?.points, [
154+
{ x: 35, y: 125 },
155+
{ x: 95, y: 165 },
156+
{ x: 155, y: 125 },
157+
]);
158+
assert.deepEqual(taps[1], { point: { x: 95, y: 165 } });
159+
});
160+
95161
test('sequence refuses whole when one member is not on the frame, before any dispatch', async () => {
96162
const { device, taps } = sequenceDevice([]);
97163

@@ -130,6 +196,28 @@ test('sequence refuses a remaining key whose identity left the screen', async ()
130196
assert.deepEqual(taps, [{ point: { x: 35, y: 125 } }]);
131197
});
132198

199+
test('the unmatched-key refusal names the keys already pressed and the keys still pending', async () => {
200+
const { device, taps } = sequenceDevice([
201+
makeSnapshotState([keyNode('1', { x: 10, y: 100 }), keyNode('3', { x: 130, y: 100 })]),
202+
]);
203+
204+
await assert.rejects(
205+
device.interactions.press(
206+
{ kind: 'ref', ref: '@e1' },
207+
{ session: 'default', refs: ['e1', 'e2', 'e3'] },
208+
),
209+
(error: Error & { details?: Record<string, unknown> }) => {
210+
// The recovery reads the remaining plan out of the refusal instead of
211+
// guessing how far the command got.
212+
assert.equal(error.details?.executed, 1);
213+
assert.deepEqual(error.details?.pending, ['@e3']);
214+
assert.match(error.message, /Keys already pressed: @e1/);
215+
return true;
216+
},
217+
);
218+
assert.deepEqual(taps, [{ point: { x: 35, y: 125 } }]);
219+
});
220+
133221
test('sequence refuses a remaining key whose identity names two nodes', async () => {
134222
// After key 2, the surface carries the "3" identity twice, so the plan
135223
// cannot tell which control the key names.
@@ -160,6 +248,7 @@ test('sequence refuses same-point repetition options', async () => {
160248
),
161249
(error: AppErrorShape) => {
162250
assert.equal(error.code, 'INVALID_ARGS');
251+
assert.equal(error.details?.reason, 'sequence_option_conflict');
163252
assert.equal(error.details?.option, 'count');
164253
return true;
165254
},
@@ -169,13 +258,65 @@ test('sequence refuses same-point repetition options', async () => {
169258

170259
type AppErrorShape = Error & { code?: string; details?: Record<string, unknown> };
171260

261+
test('a later key found inside the motion window agrees on a second look and dispatches at rest', async () => {
262+
// The frozen clock keeps key 2 inside the window, and key 2 sits at the same
263+
// fresh position on both looks: rest is proven by agreement, after paying
264+
// the window's remainder. Key 3 sits where the previous key's acting tree
265+
// already showed it, so it dispatches without a second look.
266+
const waits: number[] = [];
267+
const { device, taps } = sequenceDevice(
268+
[padAfterPressSnapshot(1), padAfterPressSnapshot(1), padAfterPressSnapshot(2)],
269+
clockFrozenInMotionWindow(waits),
270+
);
271+
272+
const result = await device.interactions.press(
273+
{ kind: 'ref', ref: '@e1' },
274+
{ session: 'default', refs: ['e1', 'e2', 'e3'] },
275+
);
276+
277+
assert.deepEqual(taps, [
278+
{ point: { x: 35, y: 125 } },
279+
{ point: { x: 95, y: 165 } },
280+
{ point: { x: 155, y: 125 } },
281+
]);
282+
assert.deepEqual(waits, [500]);
283+
assert.deepEqual(result.sequence?.pressed, 3);
284+
});
285+
286+
test('a later key the window cannot settle refuses with target_still_moving', async () => {
287+
const { device, taps } = sequenceDevice(
288+
[padWithKey2At(140), padWithKey2At(260)],
289+
clockFrozenInMotionWindow(),
290+
);
291+
292+
await assert.rejects(
293+
device.interactions.press(
294+
{ kind: 'ref', ref: '@e1' },
295+
{ session: 'default', refs: ['e1', 'e2'] },
296+
),
297+
(error: Error & { details?: Record<string, unknown> }) => {
298+
// The same refusal, reason, and details a standalone press meets.
299+
assert.equal(error.details?.reason, 'target_still_moving');
300+
assert.equal(error.details?.ref, '@e2');
301+
assert.match(error.message, /Ref @e2 had no confirmed resting position/);
302+
return true;
303+
},
304+
);
305+
// Key 1 dispatched; key 2 never did.
306+
assert.deepEqual(taps, [{ point: { x: 35, y: 125 } }]);
307+
});
308+
172309
test('sequence sleeps --interval-ms between keys', async () => {
173310
const sleeps: number[] = [];
174311
const device = createInteractionDevice(keyPadSnapshot(), {
175312
captureSnapshot: async () => ({ snapshot: padAfterPressSnapshot(1) }),
176313
tap: async () => ({ ok: true }),
314+
// Reads step past the motion window so only the interval itself sleeps.
177315
clock: {
178-
now: () => 0,
316+
now: (() => {
317+
let reading = 0;
318+
return () => (reading += 10_000);
319+
})(),
179320
sleep: async (ms) => {
180321
sleeps.push(ms);
181322
},

0 commit comments

Comments
 (0)