Skip to content

Commit 9981b13

Browse files
thymikeeopencode
andcommitted
test(ios): enforce scroll-eligibility parity and settle ScrollArea for macOS (#2754 step 4)
`REGULAR_ELIGIBLE_TYPES` (projection.ts) and `eligibleInteractiveTypes` (SnapshotPresentationProjection.swift) are one fact in two languages: they keep a scroll host alive through regular projection so the parent-edge ownership rule can find it. No test referenced either list, so they could silently drift. `eligibility-parity.test.ts` reads both literals from source, normalizes them with the runtime's `normalizeType`, and fails on drift (verified by planting an extra member). A production export was rejected in favor of source parsing so the sets stay module-private. The `scrollarea` asymmetry is settled for the macOS surface with a case rather than by editing a set for iOS's sake: the desktop path (snapshot-desktop-surface -> ios-snapshot-runtime -> publishIosSnapshot) reaches these rules and its helper emits `ScrollArea`. A content-bearing `ScrollArea` survives eligibility and owns its band under parent-edge ownership; a label-less one is dropped and its indicator resolves no owner, which under-clips (safe) instead of mis-clipping the enclosing list — strictly safer than the retired ancestor walk. So the type stays out of both eligible sets, and the guard pins that exclusion. Co-authored-by: opencode <[email protected]>
1 parent 6141e35 commit 9981b13

3 files changed

Lines changed: 220 additions & 0 deletions

File tree

‎apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationProjection.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
import Foundation
22

33
extension SnapshotPresentation {
4+
// Kept in step with `REGULAR_ELIGIBLE_TYPES` in ios-snapshot-engine/projection.ts by
5+
// eligibility-parity.test.ts. Excludes `scrollarea` (ADR 0026): the iOS runner never emits it.
46
static let eligibleInteractiveTypes: Set<String> = [
57
"Button",
68
"Cell",
Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
import assert from 'node:assert/strict';
2+
import fs from 'node:fs';
3+
import path from 'node:path';
4+
import { test } from 'vitest';
5+
import { normalizeType } from '@agent-device/contracts/snapshot';
6+
import type {
7+
IosSnapshotAcquisition,
8+
IosSnapshotInput,
9+
} from '@agent-device/contracts/ios-snapshot';
10+
import {
11+
createIosSnapshotRequest,
12+
deriveIosCaptureHint,
13+
} from '@agent-device/capture-kit/ios-snapshot-planning';
14+
import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
15+
import { presentIosSnapshot } from './index.ts';
16+
17+
// ADR 0026: `REGULAR_ELIGIBLE_TYPES` (TypeScript) and `eligibleInteractiveTypes` (Swift) are one
18+
// fact in two languages — the set that lets a scroll host survive regular projection so the
19+
// parent-edge ownership rule can find it. No runtime shares the two lists, so this guard reads both
20+
// literals from source and fails if they drift. Parsing source (rather than a production export)
21+
// keeps the sets private to their modules while still enforcing parity.
22+
23+
const TYPESCRIPT_PROJECTION = path.join(import.meta.dirname, 'projection.ts');
24+
const SWIFT_PROJECTION = path.join(
25+
import.meta.dirname,
26+
'..',
27+
'..',
28+
'..',
29+
'..',
30+
'apple',
31+
'snapshot-presentation',
32+
'Sources',
33+
'AgentDeviceSnapshotPresentation',
34+
'SnapshotPresentationProjection.swift',
35+
);
36+
37+
const SHARED_MEMBERS = [
38+
'button',
39+
'cell',
40+
'collectionview',
41+
'scrollview',
42+
'table',
43+
'textview',
44+
'webview',
45+
] as const;
46+
47+
const TYPESCRIPT_LITERAL = /const REGULAR_ELIGIBLE_TYPES = new Set\(\[([\s\S]*?)\]\)/;
48+
const SWIFT_LITERAL = /eligibleInteractiveTypes: Set<String> = \[([\s\S]*?)\]/;
49+
50+
test('the two regular-eligibility lists are one fact in two languages', () => {
51+
const typescript = normalizedEligible(readSource(TYPESCRIPT_PROJECTION), TYPESCRIPT_LITERAL);
52+
const swift = normalizedEligible(readSource(SWIFT_PROJECTION), SWIFT_LITERAL);
53+
54+
// A regex that stopped matching would yield an empty set and pass by accident; pin non-emptiness
55+
// and the scroll-host members that carry the ownership rule.
56+
assert.ok(typescript.size >= SHARED_MEMBERS.length, 'TypeScript eligibility list parsed empty');
57+
assert.ok(swift.size >= SHARED_MEMBERS.length, 'Swift eligibility list parsed empty');
58+
for (const member of SHARED_MEMBERS) {
59+
assert.ok(typescript.has(member), `TypeScript list missing ${member}`);
60+
assert.ok(swift.has(member), `Swift list missing ${member}`);
61+
}
62+
assert.deepEqual(
63+
[...typescript].sort(),
64+
[...swift].sort(),
65+
'REGULAR_ELIGIBLE_TYPES and eligibleInteractiveTypes diverged',
66+
);
67+
68+
// Spelling discipline. Normalized equality alone hides a casing flip that breaks only one runtime,
69+
// because each matches `node.type` differently: TypeScript normalizes before lookup
70+
// (`projection.ts` `.has(normalizeType(node.type))`), so its members must already be normalized;
71+
// Swift matches the raw producer spelling (`contains(node.type)`), so its members must stay in the
72+
// un-normalized PascalCase the Apple producer emits. Without this, lowercasing the Swift literals
73+
// would keep the normalized parity check green while silently dropping every macOS row.
74+
for (const raw of rawEligible(readSource(TYPESCRIPT_PROJECTION), TYPESCRIPT_LITERAL)) {
75+
assert.equal(raw, normalizeType(raw), `TypeScript literal "${raw}" is not in normalized form`);
76+
}
77+
for (const raw of rawEligible(readSource(SWIFT_PROJECTION), SWIFT_LITERAL)) {
78+
assert.notEqual(
79+
raw,
80+
normalizeType(raw),
81+
`Swift literal "${raw}" was normalized; Swift matches raw node.type`,
82+
);
83+
}
84+
});
85+
86+
// `scrollarea` is accepted by `isScrollableSnapshotType` yet excluded from both eligible sets: the
87+
// iOS runner never emits it, and macOS desktop capture reaches these rules through the same engine.
88+
// The macOS surface is answered with a case below rather than by admitting the type for iOS's sake.
89+
test('the eligible sets deliberately exclude the macOS-only scrollarea type', () => {
90+
const typescript = normalizedEligible(readSource(TYPESCRIPT_PROJECTION), TYPESCRIPT_LITERAL);
91+
const swift = normalizedEligible(readSource(SWIFT_PROJECTION), SWIFT_LITERAL);
92+
assert.equal(typescript.has('scrollarea'), false);
93+
assert.equal(swift.has('scrollarea'), false);
94+
});
95+
96+
// macOS desktop capture (snapshot-desktop-surface → ios-snapshot-runtime → publishIosSnapshot) uses
97+
// these rules and its helper emits `ScrollArea` from AXScrollArea. The decision: keep the type out
98+
// of the eligible sets. A `ScrollArea` that carries content survives eligibility and owns its band
99+
// under the parent-edge rule; a label-less one is dropped and its indicator resolves no owner, which
100+
// under-clips (safe) rather than mis-clipping the enclosing list — strictly safer than the retired
101+
// ancestor walk, which could re-attribute the re-parented indicator to an unrelated scroll host.
102+
test('a content-bearing ScrollArea scroll host owns its band on the shared engine', () => {
103+
const viewport: Rect = { x: 0, y: 0, width: 320, height: 240 };
104+
const result = presentInteractive([
105+
node(0, 'Application', 'Finder', viewport),
106+
node(1, 'ScrollArea', 'Documents', { x: 0, y: 40, width: 320, height: 200 }, 0),
107+
node(
108+
2,
109+
'Other',
110+
'Vertical scroll bar, 3 pages',
111+
{ x: 306, y: 40, width: 10, height: 150 },
112+
1,
113+
'0%',
114+
),
115+
node(3, 'Button', 'Row above', { x: 16, y: -40, width: 288, height: 28 }, 1),
116+
node(4, 'Button', 'Row visible', { x: 16, y: 60, width: 288, height: 28 }, 1),
117+
node(5, 'Button', 'Row below', { x: 16, y: 200, width: 288, height: 28 }, 1),
118+
]);
119+
const scrollArea = result.nodes.find((entry) => entry.type === 'ScrollArea');
120+
const labels = result.nodes.map((entry) => entry.label);
121+
122+
assert.ok(scrollArea, 'a content-bearing ScrollArea must survive regular projection');
123+
assert.deepEqual(scrollArea?.rect, { x: 0, y: 40, width: 320, height: 150 });
124+
assert.equal(scrollArea?.hiddenContentBelow, true);
125+
assert.deepEqual(
126+
labels.filter((label) => label?.startsWith('Row ')),
127+
['Row visible'],
128+
);
129+
});
130+
131+
// Decision pin from the other side of the same rule. Because `scrollarea` is excluded from both
132+
// eligible sets, a label-less ScrollArea carries no semantic content to survive on and is dropped
133+
// from regular projection — the type simply does not appear, whichever producer reaches the engine.
134+
// Admitting `scrollarea` would make it survive as a node, failing the absence assertion below. (The
135+
// dropped host's own indicator still bands the tree it leaves behind; that band is a separate concern
136+
// from eligibility, so this case only pins the survival decision.)
137+
test('a label-less ScrollArea does not survive regular projection', () => {
138+
const viewport: Rect = { x: 0, y: 0, width: 320, height: 240 };
139+
const result = presentInteractive([
140+
node(0, 'Application', 'Finder', viewport),
141+
node(1, 'ScrollArea', undefined, { x: 0, y: 40, width: 320, height: 200 }, 0),
142+
node(
143+
2,
144+
'Other',
145+
'Vertical scroll bar, 3 pages',
146+
{ x: 306, y: 40, width: 10, height: 150 },
147+
1,
148+
'0%',
149+
),
150+
node(3, 'Button', 'Row above', { x: 16, y: -40, width: 288, height: 28 }, 1),
151+
node(4, 'Button', 'Row visible', { x: 16, y: 60, width: 288, height: 28 }, 1),
152+
node(5, 'Button', 'Row below', { x: 16, y: 200, width: 288, height: 28 }, 1),
153+
]);
154+
155+
assert.equal(
156+
result.nodes.find((entry) => entry.type === 'ScrollArea'),
157+
undefined,
158+
'a label-less ScrollArea must not survive regular projection',
159+
);
160+
});
161+
162+
function readSource(file: string): string {
163+
return fs.readFileSync(file, 'utf8');
164+
}
165+
166+
function normalizedEligible(source: string, literal: RegExp): Set<string> {
167+
return new Set(rawEligible(source, literal).map((member) => normalizeType(member)));
168+
}
169+
170+
function rawEligible(source: string, literal: RegExp): string[] {
171+
const body = source.match(literal)?.[1];
172+
assert.ok(body, 'eligibility list literal not found — did it get renamed?');
173+
return [...body.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]!);
174+
}
175+
176+
function presentInteractive(nodes: RawSnapshotNode[]) {
177+
const request = createIosSnapshotRequest({
178+
projection: 'regular',
179+
interactiveOnly: true,
180+
acquisitionIntent: 'full',
181+
});
182+
const acquisition: IosSnapshotAcquisition = {
183+
producer: 'simulator-ax-bridge',
184+
intent: 'full',
185+
hint: { ...deriveIosCaptureHint(request), acquisitionIntent: 'full' },
186+
nodes,
187+
truncated: false,
188+
viewport: { kind: 'reported', rect: { x: 0, y: 0, width: 320, height: 240 } },
189+
lineage: { targetId: 'parity-target', generation: 'parity-generation' },
190+
residue: [],
191+
};
192+
const input: IosSnapshotInput = { stage: 'acquired', acquisition };
193+
return presentIosSnapshot(input, request);
194+
}
195+
196+
function node(
197+
index: number,
198+
type: string,
199+
label: string | undefined,
200+
rect: Rect,
201+
parentIndex?: number,
202+
value?: string,
203+
): RawSnapshotNode {
204+
return {
205+
index,
206+
type,
207+
...(label ? { label } : {}),
208+
...(value ? { value } : {}),
209+
rect,
210+
enabled: true,
211+
hittable: true,
212+
depth: parentIndex === undefined ? 0 : 1,
213+
...(parentIndex === undefined ? {} : { parentIndex }),
214+
};
215+
}

‎packages/capture-kit/src/ios-snapshot-engine/projection.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@ import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
22
import { normalizeType } from '@agent-device/contracts/snapshot';
33
import type { IosSnapshotFoldPolicy, IosSnapshotPresentationNode } from './types.ts';
44

5+
// Kept in step with `eligibleInteractiveTypes` in SnapshotPresentationProjection.swift by
6+
// ios-snapshot-engine/eligibility-parity.test.ts. Excludes `scrollarea`, which `isScrollableSnapshotType`
7+
// accepts but the iOS runner never emits (ADR 0026; macOS decision recorded in that test).
58
const REGULAR_ELIGIBLE_TYPES = new Set([
69
'button',
710
'cell',

0 commit comments

Comments
 (0)