Skip to content

Commit 746e9b3

Browse files
authored
fix(web): refuse the press shapes a browser click cannot drive (#2806)
An admitted `tapPoint` cell promised the whole point-press series, so `press --double` and `press --hold` on a web session resolved the shared interactor's bare denials. The browser backend drives one immediate pointer press per call: it repeats single taps for `--count`, and carries no click count to fuse a double-click and no hold duration. A hold is a capability an owner states, so `press --hold` is now refused by the same `longPressPoint` cell that already refuses `longpress`, carrying the owner's reason and hint. A fused double-click is a mechanic an interactor either has or leaves undefined, so it joins the other optional owner mechanics and the shared series refuses the shape with `details.reason: "owner-capability-missing"` before pressing anything.
1 parent 19cb1fd commit 746e9b3

15 files changed

Lines changed: 341 additions & 15 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,19 @@
1515
is reported. Because it stamps the raw source rather than the fold, `snapshot --raw` matches too, and
1616
the residue owner stays the fact owner (#2199). Closes the hittable-absence half of the AX-bridge
1717
capture divergence (#2638).
18+
- Fixed (web): `press --double` and `press --hold` on a web session now answer with a typed reason
19+
instead of an unclassified `UNSUPPORTED_OPERATION` naming an interactor member. The browser owner's
20+
`tapPoint` cell admitted the whole press series, but the web click affordance is one immediate
21+
pointer press per call: `--count` repeats it, and this owner composes neither a fused double-click
22+
nor a timed hold. A hold is refused by the `longPressPoint` cell that already refuses `longpress`,
23+
so both commands now carry the hint "A web click is one immediate pointer press; the browser backend
24+
has no timed hold." and `press --hold` adds `details.reason: "unsupported-platform-leaf"`. A
25+
double-click is refused by the fused mechanic the web interactor no longer carries, reporting
26+
`details.reason: "owner-capability-missing"`; both refusals arrive when the press runs, after any
27+
target selector was resolved. A repeated single-tap press (`--count 3`) keeps working on the same
28+
session, and every owner that double-tapped or held before this change still does: Android, iOS,
29+
Linux, HarmonyOS, Cloud WebDriver and Limrun keep their own mechanics, and an owner with a fused
30+
point press keeps answering `--double` through it.
1831
- Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again carries the
1932
accessibility `selected` state, so `is selected`, a `selected=true` selector, and a Maestro
2033
`selected:` qualifier match the active control. When 0.21.0 made the AX bridge the Simulator's

‎packages/contracts/src/interactor-types.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -295,7 +295,13 @@ export type Interactor = {
295295
/** Owner-native ref routes; currently the managed web runtime is their only local owner. */
296296
tapRef?(ref: string): Promise<Record<string, unknown> | void>;
297297
tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
298-
doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
298+
/**
299+
* Fused double-click for owners that have one. The shared `--count` series cannot stand in for it —
300+
* it spaces and jitters independent presses rather than firing one pair the target reads as a
301+
* double — so an owner with no such mechanic leaves this undefined and `press --double` reports the
302+
* gap instead of resolving a denial.
303+
*/
304+
doubleTap?(x: number, y: number): Promise<Record<string, unknown> | void>;
299305
longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
300306
/**
301307
* Move the pointer to a point without pressing. Only pointer-driven

‎packages/contracts/src/touch-runtime.test.ts‎

Lines changed: 189 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { expect, test, vi } from 'vitest';
2-
import type { Interactor } from './interactor-types.ts';
2+
import { AppError } from '@agent-device/kernel/errors';
3+
import type { Interactor, PressPointOptions } from './interactor-types.ts';
34
import {
45
bindLocalTouchInteractor,
56
HOVER_UNAVAILABLE_HINT,
@@ -143,3 +144,190 @@ test('the shared primary series preserves jitter, interval, and every press', as
143144
]);
144145
expect(pause.mock.calls).toEqual([[40], [40]]);
145146
});
147+
148+
// A point press is one operation whose options carry several shapes, and two of them ask for more
149+
// than the shared series can compose. A timed hold is a capability an owner states with its
150+
// `longPressPoint` cell; a fused double-click is a mechanic its interactor either has or leaves
151+
// undefined. Either way the shape is refused with a typed reason instead of resolving a member that
152+
// only knows how to throw.
153+
const holdRefused = (hint?: string) =>
154+
touchRuntimeOperationFacts({
155+
unsupported: unavailable,
156+
tap: available,
157+
longPress:
158+
hint === undefined
159+
? unavailable
160+
: { available: false, reason: 'unsupported-platform-leaf', hint },
161+
fill: available,
162+
});
163+
164+
const pressOptions = {
165+
button: 'primary',
166+
count: 1,
167+
intervalMs: 0,
168+
holdMs: 0,
169+
jitterPx: 0,
170+
doubleTap: false,
171+
} as const;
172+
173+
function bindSharedSeries(
174+
seriesFacts: ReturnType<typeof touchRuntimeOperationFacts>,
175+
mechanics: Partial<
176+
Record<'tap' | 'doubleTap' | 'longPress' | 'pressPoint', ReturnType<typeof vi.fn>>
177+
>,
178+
) {
179+
return bindLocalTouchInteractor({
180+
device,
181+
signal: new AbortController().signal,
182+
resolveInteractor: async () => mechanics as unknown as Interactor,
183+
facts: seriesFacts,
184+
pause: async () => {},
185+
});
186+
}
187+
188+
const refusedBy =
189+
(reason: string) =>
190+
(error: unknown): boolean =>
191+
error instanceof AppError &&
192+
error.code === 'UNSUPPORTED_OPERATION' &&
193+
error.details?.['reason'] === reason;
194+
195+
const press = (
196+
operations: ReturnType<typeof bindSharedSeries>,
197+
options: Partial<PressPointOptions> = {},
198+
) =>
199+
operations.tapPoint!({
200+
point: { x: 20, y: 30 },
201+
options: { ...pressOptions, ...options },
202+
});
203+
204+
test('a hold the owner refuses is refused by its fact, over an interactor that can hold', async () => {
205+
const longPress = vi.fn(async () => undefined);
206+
const operations = bindSharedSeries(holdRefused('Use a native gesture instead.'), {
207+
tap: vi.fn(async () => undefined),
208+
longPress,
209+
});
210+
211+
await expect(press(operations, { holdMs: 600 })).rejects.toSatisfy(
212+
refusedBy('unsupported-platform-leaf'),
213+
);
214+
await expect(press(operations, { holdMs: 600 })).rejects.toMatchObject({
215+
details: { reason: 'unsupported-platform-leaf', hint: 'Use a native gesture instead.' },
216+
});
217+
218+
expect(longPress).not.toHaveBeenCalled();
219+
});
220+
221+
test('an owner with no double-click mechanic refuses --double before pressing anything', async () => {
222+
const tap = vi.fn(async () => undefined);
223+
const operations = bindSharedSeries(holdRefused(), { tap });
224+
225+
await expect(press(operations, { doubleTap: true })).rejects.toSatisfy(
226+
refusedBy('owner-capability-missing'),
227+
);
228+
229+
expect(tap).not.toHaveBeenCalled();
230+
});
231+
232+
test('the same hold refusal wording carries whatever reason the owner states', async () => {
233+
const refusals = await Promise.all(
234+
[
235+
touchRuntimeOperationFacts({
236+
unsupported: unavailable,
237+
tap: available,
238+
longPress: unavailable,
239+
fill: available,
240+
}),
241+
touchRuntimeOperationFacts({
242+
unsupported: unavailable,
243+
tap: available,
244+
longPress: { available: false, reason: 'unsupported-device-kind' },
245+
fill: available,
246+
}),
247+
].map(
248+
async (seriesFacts) =>
249+
await bindSharedSeries(seriesFacts, { longPress: vi.fn() }).tapPoint!({
250+
point: { x: 1, y: 1 },
251+
options: { ...pressOptions, holdMs: 600 },
252+
})
253+
.then(() => undefined)
254+
.catch((error: unknown) => error),
255+
),
256+
);
257+
258+
const [leaf, deviceKind] = refusals as [AppError, AppError];
259+
// Identical wording and code, so nothing reading the message can tell the two owners apart…
260+
expect(deviceKind.message).toEqual(leaf.message);
261+
expect(deviceKind.code).toEqual(leaf.code);
262+
// …and the typed reason is the only thing that can.
263+
expect(leaf).toSatisfy(refusedBy('unsupported-platform-leaf'));
264+
expect(deviceKind).toSatisfy(refusedBy('unsupported-device-kind'));
265+
});
266+
267+
// The three tests below pin behavior this change must not disturb, so they are green before it too.
268+
test('an owner that states each shape reaches its own mechanic', async () => {
269+
const mechanics = {
270+
tap: vi.fn(async () => undefined),
271+
doubleTap: vi.fn(async () => ({ double: true })),
272+
longPress: vi.fn(async () => ({ held: true })),
273+
};
274+
const operations = bindSharedSeries(facts, mechanics);
275+
276+
await expect(press(operations, { doubleTap: true })).resolves.toEqual({ double: true });
277+
await expect(press(operations, { holdMs: 600 })).resolves.toEqual({ held: true });
278+
279+
expect(mechanics.doubleTap).toHaveBeenCalledWith(20, 30);
280+
expect(mechanics.longPress).toHaveBeenCalledWith(20, 30, 600);
281+
});
282+
283+
test('an owner with a fused point press keeps its own --double route without a double-click member', async () => {
284+
const pressPoint = vi.fn(async () => ({ fused: true }));
285+
const operations = bindSharedSeries(facts, { pressPoint });
286+
287+
await expect(
288+
operations.tapPoint!({
289+
point: { x: 20, y: 30 },
290+
options: { ...pressOptions, doubleTap: true },
291+
}),
292+
).resolves.toEqual({ fused: true });
293+
294+
expect(pressPoint).toHaveBeenCalledWith(
295+
{ x: 20, y: 30 },
296+
expect.objectContaining({ doubleTap: true }),
297+
);
298+
});
299+
300+
test('a repeated single tap keeps running where the owner refuses a hold and has no double-click', async () => {
301+
const tap = vi.fn(async () => undefined);
302+
const operations = bindSharedSeries(holdRefused(), { tap });
303+
304+
await expect(press(operations, { count: 2, jitterPx: 1 })).resolves.toBeUndefined();
305+
306+
expect(tap.mock.calls).toEqual([
307+
[20, 30],
308+
[21, 30],
309+
]);
310+
});
311+
312+
// The mechanic is read off the interactor, so an owner written as a class has to keep its own
313+
// receiver: both provider interactors are classes that reach their session through `this`.
314+
test('the fused double-click keeps the interactor as its receiver', async () => {
315+
class PointerOwner {
316+
readonly pressed: Array<[number, number]> = [];
317+
async doubleTap(x: number, y: number): Promise<void> {
318+
this.pressed.push([x, y]);
319+
}
320+
}
321+
const owner = new PointerOwner();
322+
const operations = bindLocalTouchInteractor({
323+
device,
324+
signal: new AbortController().signal,
325+
resolveInteractor: async () => owner as unknown as Interactor,
326+
facts,
327+
pause: async () => {},
328+
});
329+
330+
await press(operations, { doubleTap: true });
331+
332+
expect(owner.pressed).toEqual([[20, 30]]);
333+
});

‎packages/contracts/src/touch-runtime.ts‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,8 @@ function bindTouch(
136136
return await resolveInteractor(runnerContext(input, signal));
137137
};
138138
const tapPoint = async (input: TapPointInput) => {
139+
signal.throwIfAborted();
140+
requireAdmittedHold(input.options, facts.longPressPoint);
139141
const interactor = await interactorFor(input);
140142
if (input.options.button !== 'primary' && interactor.alternateClick) {
141143
return await interactor.alternateClick(input.point, input.options.button);
@@ -221,6 +223,33 @@ function missingAdvertisedOperation(name: string): never {
221223
);
222224
}
223225

226+
/**
227+
* Two shapes of a point press ask for more than the shared series can compose. A hold is a capability
228+
* an owner states with its `longPressPoint` cell, so `press --hold` is refused by the same fact that
229+
* refuses `longpress`, carrying the owner's reason and hint.
230+
*/
231+
function requireAdmittedHold(options: PressPointOptions, fact: RuntimeOperationFact): void {
232+
if (options.holdMs <= 0 || fact.available) return;
233+
throw new AppError('UNSUPPORTED_OPERATION', 'press-and-hold is not supported by this runtime.', {
234+
reason: fact.reason,
235+
...(fact.hint === undefined ? {} : { hint: fact.hint }),
236+
});
237+
}
238+
239+
/**
240+
* A fused double-click is the one press shape no fact can state: facts speak per operation, and no
241+
* command names a double-tap operation. The interactor member is the owner's only claim, so an absent
242+
* one is a capability it declines — where an absent alert member is an ownership bug, because the
243+
* alert leg's operation was admitted and this shape never was.
244+
*/
245+
function requireDoubleTapMechanic(interactor: Interactor): NonNullable<Interactor['doubleTap']> {
246+
if (interactor.doubleTap) return interactor.doubleTap;
247+
throw new AppError('UNSUPPORTED_OPERATION', 'double-tap is not supported by this runtime.', {
248+
reason: 'owner-capability-missing',
249+
hint: 'This runtime drives single presses; use --count to repeat them.',
250+
});
251+
}
252+
224253
async function executeGenericPress(
225254
interactor: Interactor,
226255
point: Point,
@@ -233,11 +262,12 @@ async function executeGenericPress(
233262
`Bound runtime does not implement ${options.button} click.`,
234263
);
235264
}
265+
const doubleTap = options.doubleTap ? requireDoubleTapMechanic(interactor) : undefined;
236266
let first: Record<string, unknown> | void = undefined;
237267
for (let index = 0; index < options.count; index += 1) {
238268
const [dx, dy] = pressJitter(index, options.jitterPx);
239-
const result = options.doubleTap
240-
? await interactor.doubleTap(point.x + dx, point.y + dy)
269+
const result = doubleTap
270+
? await doubleTap.call(interactor, point.x + dx, point.y + dy)
241271
: options.holdMs > 0
242272
? await interactor.longPress(point.x + dx, point.y + dy, options.holdMs)
243273
: await interactor.tap(point.x + dx, point.y + dy);

‎packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ const RUNNER_TRANSPORT_METHODS: Record<
5151
invoke: (i) => i.tapElementSelector!({ key: 'label', value: 'Go' }),
5252
runnerCommand: 'tap',
5353
},
54-
doubleTap: { invoke: (i) => i.doubleTap(10, 20), runnerCommand: 'sequence' },
54+
doubleTap: { invoke: (i) => i.doubleTap!(10, 20), runnerCommand: 'sequence' },
5555
longPress: { invoke: (i) => i.longPress(10, 20, 600), runnerCommand: 'longPress' },
5656
focus: { invoke: (i) => i.focus(10, 20), runnerCommand: 'tap' },
5757
type: { invoke: (i) => i.type('hi'), runnerCommand: 'type' },

‎packages/platform-vega/src/__tests__/interactor.test.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,6 @@ test('required unproven Vega operations share typed unsupported behavior', async
121121
const interactor = createVegaInteractor(VEGA_VVD, {});
122122
const unsupportedCalls: ReadonlyArray<readonly [string, () => Promise<unknown>]> = [
123123
['tap', () => interactor.tap(10, 20)],
124-
['doubleTap', () => interactor.doubleTap(10, 20)],
125124
['longPress', () => interactor.longPress(10, 20, 500)],
126125
['focus', () => interactor.focus(10, 20)],
127126
['type', () => interactor.type('text')],

‎packages/platform-vega/src/__tests__/unsupported-interactor.test.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ const OPERATIONS = [
88
'openDevice',
99
'close',
1010
'tap',
11-
'doubleTap',
1211
'longPress',
1312
'focus',
1413
'type',

‎packages/platform-vega/src/unsupported-interactor.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ export function createUnsupportedInteractor(platformLabel: string): Interactor {
1515
openDevice: () => unsupported('openDevice'),
1616
close: () => unsupported('close'),
1717
tap: () => unsupported('tap'),
18-
doubleTap: () => unsupported('doubleTap'),
1918
longPress: () => unsupported('longPress'),
2019
focus: () => unsupported('focus'),
2120
type: () => unsupported('type'),

0 commit comments

Comments
 (0)