Skip to content

Commit 3ea91a3

Browse files
faresrafat3faresrafat3
authored andcommitted
fix(interaction): refuse a target with no usable centre
A selector that resolves to a target with no usable centre was dispatched at the node's origin, and the command reported success. The touch-point layer now uses the kernel's `isPositiveFiniteRect` guard, so a target with no extent, or one carrying the failed-read `CGRectInfinite` sentinel, refuses with the existing typed reason `target_bounds_invalid` and no tap is dispatched. The layer had no area rule of its own: `normalizeRect` refuses only a negative width or height, so a zero-area rect passed through it, and so did the sentinel. The kernel's `isPositiveFiniteRect` refuses both. The new fixtures publish the capture the issue describes: a zero-area node is `hittable: false`. ADR 0011 records the guard's rule and names the shapes the suite keeps, and the runtime-selector and runtime-ref contract suites prove the refusal in the in-process runtime harness, under the errorTaxonomy cell, before any dispatch. Fixes callstack#3841
1 parent 507ef23 commit 3ea91a3

9 files changed

Lines changed: 281 additions & 5 deletions

File tree

‎docs/adr/0011-interaction-guarantee-contract.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,14 +252,17 @@ The fixture trees are the real shapes that found this week's bugs, and the suite
252252

253253
- Closed drawer (all candidates off-screen) → `offscreen_selector`/`offscreen_ref`.
254254
- Stale or unknown `@ref` (errorTaxonomy) → `ref_not_found` beside the stale-ref hint.
255-
- A listed `@ref` whose node has no usable centre (missing, non-finite, or negative bounds), or a selector target without one → `target_bounds_invalid`.
255+
- A listed `@ref` or a selector target whose node carries a zero extent (errorTaxonomy) → `target_bounds_invalid`.
256256
- A listed `@ref` with no label to wait on or to scope by → `ref_unlabeled`.
257257
- Drawer item + visible twin (ambiguous on/off-screen) → the visible candidate wins.
258258
- Edge-grazing container (0.07 px viewport overlap, center off-screen) → still refused.
259259
- Covered node → occlusion refusal.
260260
- Non-hittable target ± `--verify` → hint present / suppressed by evidence.
261261
- Stripped-root tree (no Application/Window) → safe-default visibility.
262262

263+
The `target_bounds_invalid` refusal is the kernel's bounds guard, `isPositiveFiniteRect`: a node with no rect, a non-finite component, a box whose own right or bottom edge overflows, a zero or negative extent, and the `CGRectInfinite` sentinel all refuse.
264+
That is the guard's rule rather than this list's inventory: the contract suite keeps the zero extent, and the selectors unit suite and the command-level suite prove the sentinel beside it.
265+
263266
Path forcing is explicit and test-only: `AGENT_DEVICE_FORCE_INTERACTION_PATH=runtime|direct|native-ref`.
264267
Thus, cases stay stable when path-selection heuristics change.
265268

@@ -380,6 +383,15 @@ Also, the structural rule never reached the read door.
380383
Verification names the collapsed control too.
381384
That control is the node that dispatch acted on, and the node that the recorded identity carries.
382385

386+
### 2026-10-20 amendment: a target with no usable bounds is refused before dispatch
387+
388+
The touch-point layer had no area rule of its own.
389+
`normalizeRect` refuses a negative width or height, so a zero-area rect passed through it — and so did the `CGRectInfinite` sentinel a failed read carries.
390+
Both resolved to a point, the sentinel to the origin, so the layer dispatched a tap there and the command reported success.
391+
The layer now calls the kernel's `isPositiveFiniteRect`, and a target the guard refuses gets the typed reason `target_bounds_invalid` with no tap dispatched.
392+
The reason a value guard is the rule: a failed read that crossed the wire leaves every component and every extent finite, so only a value guard refuses it (#2891).
393+
The guard is value-exact, so a huge but finite box whose centre is the origin still resolves; the Swift twin refuses the same values, and a wider rule belongs to the kernel.
394+
383395
### Synthesized iOS gesture policy
384396

385397
The element dispatch-path matrix above intentionally does not include synthesized iOS gestures:

‎packages/selectors/src/interaction-touch-point.test.ts‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,79 @@ test('keeps the exact center when there are no competing interactive descendants
115115
});
116116
});
117117

118+
test('refuses a target with no touchable area', () => {
119+
const areaLessTargets: Rect[] = [
120+
{ x: 0, y: 0, width: 0, height: 0 },
121+
{ x: 12, y: 40, width: 0, height: 30 },
122+
{ x: 12, y: 40, width: 30, height: 0 },
123+
];
124+
125+
for (const rect of areaLessTargets) {
126+
const nodes = makeSnapshotState([
127+
{
128+
index: 0,
129+
depth: 0,
130+
type: 'Button',
131+
label: 'Clock',
132+
rect,
133+
hittable: false,
134+
},
135+
]).nodes;
136+
137+
assert.deepEqual(
138+
resolveInteractionTouchPoint(nodes, nodes[0]!),
139+
{ kind: 'invalid' },
140+
`a target with no area has no point to touch, so ${JSON.stringify(rect)} must not resolve`,
141+
);
142+
}
143+
});
144+
145+
test('refuses the CGRectInfinite sentinel, whose centre is the origin', () => {
146+
// `CGRectInfinite` spelled in the four doubles Apple spells it with: every component and every
147+
// extent of it is finite, so only the kernel's value guard refuses it.
148+
const sentinel: Rect = {
149+
x: -Number.MAX_VALUE / 2,
150+
y: -Number.MAX_VALUE / 2,
151+
width: Number.MAX_VALUE,
152+
height: Number.MAX_VALUE,
153+
};
154+
const nodes = makeSnapshotState([
155+
{
156+
index: 0,
157+
depth: 0,
158+
type: 'Button',
159+
label: 'Clock',
160+
rect: sentinel,
161+
hittable: false,
162+
},
163+
]).nodes;
164+
165+
assert.deepEqual(
166+
resolveInteractionTouchPoint(nodes, nodes[0]!),
167+
{ kind: 'invalid' },
168+
'the failed-read sentinel centres on the origin, so it must not resolve to a point to touch',
169+
);
170+
});
171+
172+
test('keeps a one-pixel target resolvable to its center', () => {
173+
const nodes = makeSnapshotState([
174+
{
175+
index: 0,
176+
depth: 0,
177+
type: 'Button',
178+
label: 'Clock',
179+
rect: { x: 20, y: 30, width: 1, height: 1 },
180+
hittable: true,
181+
},
182+
]).nodes;
183+
184+
assert.deepEqual(resolveInteractionTouchPoint(nodes, nodes[0]!), {
185+
kind: 'resolved',
186+
point: { x: 21, y: 31 },
187+
strategy: 'center',
188+
});
189+
});
190+
118191
test('keeps a parent-owned center in a thin row when a child is safely off to the side', () => {
119192
const nodes = makeSnapshotState([
120193
{

‎packages/selectors/src/interaction-touch-point.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import {
44
type Rect,
55
type SnapshotNode,
66
} from '@agent-device/kernel/snapshot';
7-
import { containsPoint } from '@agent-device/kernel/rect';
7+
import { containsPoint, isPositiveFiniteRect } from '@agent-device/kernel/rect';
88
import {
99
areRectsApproximatelyEqual,
1010
normalizeRect,
@@ -34,8 +34,12 @@ export function resolveInteractionTouchPoint(
3434
options: { bounds?: readonly Rect[] } = {},
3535
): InteractionTouchPointResolution {
3636
const targetRect = normalizeRect(node.rect);
37-
const center = resolveRectCenter(targetRect ?? undefined);
38-
if (!targetRect || !center) return { kind: 'invalid' };
37+
// The kernel's guard names the boxes that cannot be measured or landed on: a component that is
38+
// not a finite number, a box whose own right or bottom edge overflows the number range, a zero
39+
// or negative extent, and the `CGRectInfinite` sentinel a failed read carries.
40+
if (!targetRect || !isPositiveFiniteRect(targetRect)) return { kind: 'invalid' };
41+
const center = resolveRectCenter(targetRect);
42+
if (!center) return { kind: 'invalid' };
3943

4044
const competitors = collectInteractiveDescendantRects(nodes, node, targetRect);
4145
if (competitors.length === 0) {

‎src/commands/interaction/runtime/resolution-touch-point.test.ts‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,107 @@ function postSnapshot() {
5353
]);
5454
}
5555

56+
test('runtime press refuses a zero-area selector target and dispatches no tap', async () => {
57+
const calls: Point[] = [];
58+
const device = createInteractionDevice(
59+
makeSnapshotState([
60+
{
61+
index: 0,
62+
depth: 0,
63+
type: 'Application',
64+
rect: { x: 0, y: 0, width: 402, height: 874 },
65+
hittable: true,
66+
},
67+
{
68+
index: 1,
69+
depth: 1,
70+
parentIndex: 0,
71+
type: 'Button',
72+
label: 'Clock',
73+
rect: { x: 0, y: 0, width: 0, height: 0 },
74+
hittable: false,
75+
},
76+
]),
77+
{
78+
tap: async (_context, point) => {
79+
calls.push(point);
80+
return { ok: true };
81+
},
82+
},
83+
);
84+
85+
await assert.rejects(
86+
() => device.interactions.press(selector('label="Clock"'), { session: 'default' }),
87+
(error: unknown) => {
88+
assert.deepEqual(
89+
(error as { details?: Record<string, unknown> }).details,
90+
{
91+
reason: 'target_bounds_invalid',
92+
selector: 'label="Clock"',
93+
dispatched: 'no',
94+
},
95+
'the refusal names the typed reason, and discloses that no tap was dispatched',
96+
);
97+
return true;
98+
},
99+
);
100+
assert.deepEqual(calls, [], 'a target with no area must not be tapped at its origin');
101+
});
102+
103+
test('runtime press refuses a sentinel-bounds selector target and dispatches no tap', async () => {
104+
const calls: Point[] = [];
105+
const device = createInteractionDevice(
106+
makeSnapshotState([
107+
{
108+
index: 0,
109+
depth: 0,
110+
type: 'Application',
111+
rect: { x: 0, y: 0, width: 402, height: 874 },
112+
hittable: true,
113+
},
114+
{
115+
index: 1,
116+
depth: 1,
117+
parentIndex: 0,
118+
type: 'Button',
119+
label: 'Clock',
120+
// `CGRectInfinite` spelled in the four doubles Apple spells it with: a failed read that
121+
// crossed a wire, whose centre is the origin.
122+
rect: {
123+
x: -Number.MAX_VALUE / 2,
124+
y: -Number.MAX_VALUE / 2,
125+
width: Number.MAX_VALUE,
126+
height: Number.MAX_VALUE,
127+
},
128+
hittable: false,
129+
},
130+
]),
131+
{
132+
tap: async (_context, point) => {
133+
calls.push(point);
134+
return { ok: true };
135+
},
136+
},
137+
);
138+
139+
await assert.rejects(
140+
() => device.interactions.press(selector('label="Clock"'), { session: 'default' }),
141+
(error: unknown) => {
142+
assert.deepEqual(
143+
(error as { details?: Record<string, unknown> }).details,
144+
{
145+
reason: 'target_bounds_invalid',
146+
selector: 'label="Clock"',
147+
dispatched: 'no',
148+
},
149+
'the refusal names the typed reason, and discloses that no tap was dispatched',
150+
);
151+
return true;
152+
},
153+
);
154+
assert.deepEqual(calls, [], 'a target with no usable centre must not be tapped at the origin');
155+
});
156+
56157
test('runtime ref and selector paths dispatch the same parent-owned post point', async () => {
57158
const refCalls: Point[] = [];
58159
const selectorCalls: Point[] = [];

‎test/integration/interaction-contract/fixtures.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,31 @@ export function fullyTiledParentSnapshot(): SnapshotState {
202202
]);
203203
}
204204

205+
// A node the capture reports with no extent: the page-1 icons iOS leaves in
206+
// the tree carry a 0x0 rect and are not hittable. A target with no usable
207+
// centre must be refused before any dispatch, not tapped at its origin.
208+
export function zeroAreaTargetSnapshot(): SnapshotState {
209+
return makeSnapshotState([
210+
{
211+
index: 0,
212+
depth: 0,
213+
type: 'Application',
214+
label: 'Example',
215+
rect: { x: 0, y: 0, width: 400, height: 800 },
216+
hittable: true,
217+
},
218+
{
219+
index: 1,
220+
depth: 1,
221+
parentIndex: 0,
222+
type: 'Button',
223+
label: 'Clock',
224+
rect: { x: 0, y: 0, width: 0, height: 0 },
225+
hittable: false,
226+
},
227+
]);
228+
}
229+
205230
// A visible list cell that iOS reports as non-hittable (#1037 shape): the
206231
// interaction must proceed but be annotated.
207232
export function nonHittableCellSnapshot(): SnapshotState {

‎test/integration/interaction-contract/runtime-ref.contract.test.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
22
import { test } from 'vitest';
33
import type { InteractionGuarantee } from '@agent-device/contracts/interaction-guarantees';
44
import type { Point } from '@agent-device/kernel/snapshot';
5+
import { INTERACTION_ERROR_REASONS } from '@agent-device/selectors/interaction-error';
56
import { ref } from '../../../src/commands/interaction/runtime/selector-read-utils.ts';
67
import { assertRpcOk } from '../provider-scenarios/assertions.ts';
78
import { PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS } from '../provider-scenarios/test-timeouts.ts';
@@ -18,6 +19,7 @@ import {
1819
RUNNER_CONTINUE_NODES,
1920
settledWelcomeSnapshot,
2021
viewportOnlySnapshot,
22+
zeroAreaTargetSnapshot,
2123
} from './fixtures.ts';
2224
import { createContractClock, createContractDevice } from './runtime-harness.ts';
2325
import { runnerSnapshotEntry, runnerTapEntry, withIosContractDaemon } from './daemon-harness.ts';
@@ -67,6 +69,33 @@ test(scenario('parentOwnedTouchPoint'), async () => {
6769
assert.deepEqual(taps, []);
6870
});
6971

72+
// The zero-area target refuses through the shared error taxonomy: the code, the message and the
73+
// reason all come from the shared vocabulary, and the refusal dispatches no tap. The fixture has no
74+
// descendants, so this is not a parent-owned case.
75+
test(scenarioNames(RUNTIME_REF_COVERAGE, 'errorTaxonomy')[1]!, async () => {
76+
const taps: Point[] = [];
77+
const device = createContractDevice(zeroAreaTargetSnapshot(), {
78+
tap: async (_context, point) => {
79+
taps.push(point);
80+
},
81+
});
82+
83+
await assert.rejects(
84+
() => device.interactions.press(ref('@e2'), { session: 'default' }),
85+
(error: unknown) => {
86+
assert.ok(error instanceof Error);
87+
assert.equal((error as { code?: string }).code, 'COMMAND_FAILED');
88+
assert.match(error.message, /has no usable bounds/);
89+
const details = (error as { details?: Record<string, unknown> }).details;
90+
assert.equal(details?.reason, INTERACTION_ERROR_REASONS.targetBoundsInvalid);
91+
assert.equal(details?.ref, 'e2');
92+
assert.equal(details?.dispatched, 'no');
93+
return true;
94+
},
95+
);
96+
assert.deepEqual(taps, [], 'a ref target with no usable bounds must not be tapped at its origin');
97+
});
98+
7099
test(scenario('keyboardOcclusion'), async () => {
71100
const taps: Point[] = [];
72101
const device = createContractDevice(keyboardCoveredTabBarSnapshot(), {

‎test/integration/interaction-contract/runtime-ref.coverage.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ export const RUNTIME_REF_COVERAGE = definePathCoverage('runtime-ref', {
1515
'runtime-ref verifyEvidence: click @ref --verify returns a digest with change detection',
1616
settleObservation:
1717
'runtime-ref settleObservation: press @ref --settle diffs the settled tree against the stored baseline',
18-
errorTaxonomy: 'runtime-ref errorTaxonomy: unknown ref fails with the stale-ref hint',
18+
errorTaxonomy: [
19+
'runtime-ref errorTaxonomy: unknown ref fails with the stale-ref hint',
20+
'runtime-ref errorTaxonomy: a ref target with no usable bounds refuses with target_bounds_invalid before dispatch',
21+
],
1922
resolutionDisclosure: [
2023
'runtime-ref resolutionDisclosure: an @ref discloses the exact ref-provenance shape',
2124
'runtime-ref resolutionDisclosure: trailing-label recovery discloses label-fallback, never exact',

‎test/integration/interaction-contract/runtime-selector.contract.test.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import {
2222
RUNNER_CONTINUE_NODES,
2323
settledWelcomeSnapshot,
2424
viewportOnlySnapshot,
25+
zeroAreaTargetSnapshot,
2526
} from './fixtures.ts';
2627
import { createContractClock, createContractDevice } from './runtime-harness.ts';
2728
import { runnerSnapshotEntry, runnerTapEntry, withIosContractDaemon } from './daemon-harness.ts';
@@ -189,6 +190,33 @@ test(scenario('parentOwnedTouchPoint'), async () => {
189190
assert.deepEqual(taps, []);
190191
});
191192

193+
// The zero-area target refuses through the shared error taxonomy: the code, the message and the
194+
// reason all come from the shared vocabulary, and the refusal dispatches no tap. The fixture has no
195+
// descendants, so this is not a parent-owned case.
196+
test(scenarioNames(RUNTIME_SELECTOR_COVERAGE, 'errorTaxonomy')[2]!, async () => {
197+
const taps: Point[] = [];
198+
const device = createContractDevice(zeroAreaTargetSnapshot(), {
199+
tap: async (_context, point) => {
200+
taps.push(point);
201+
},
202+
});
203+
204+
await assert.rejects(
205+
() => device.interactions.press(selector('label=Clock'), { session: 'default' }),
206+
(error: unknown) => {
207+
assert.ok(error instanceof Error);
208+
assert.equal((error as { code?: string }).code, 'COMMAND_FAILED');
209+
assert.match(error.message, /resolved to invalid bounds/);
210+
const details = (error as { details?: Record<string, unknown> }).details;
211+
assert.equal(details?.reason, INTERACTION_ERROR_REASONS.targetBoundsInvalid);
212+
assert.equal(details?.selector, 'label=Clock');
213+
assert.equal(details?.dispatched, 'no');
214+
return true;
215+
},
216+
);
217+
assert.deepEqual(taps, [], 'a target with no usable centre must not be tapped at its origin');
218+
});
219+
192220
test(scenario('nonHittable'), async () => {
193221
const taps: Point[] = [];
194222
const device = createContractDevice(nonHittableButtonSnapshot(), {

‎test/integration/interaction-contract/runtime-selector.coverage.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ export const RUNTIME_SELECTOR_COVERAGE = definePathCoverage('runtime-selector',
2626
errorTaxonomy: [
2727
'runtime-selector errorTaxonomy: no-match failure carries the shared code and hint',
2828
'runtime-selector errorTaxonomy: a daemon selector miss discloses dispatched no',
29+
'runtime-selector errorTaxonomy: a selector target with no usable centre refuses with target_bounds_invalid before dispatch',
2930
],
3031
resolutionDisclosure: [
3132
'runtime-selector resolutionDisclosure: a unique match discloses the unique runtime shape',

0 commit comments

Comments
 (0)