Skip to content

Commit 9af006d

Browse files
committed
feat(ios): decide the presented surface from a captured tree (#3565)
Add the TypeScript rule that answers whether an iOS capture read a modal presentation over the app's own content, the golden table that pins it, and the publication that carries its answer, so the rule has a production consumer the moment it lands. `absent` is the strong answer and never the default, because a consumer arms a dismissal confirmation on it. It requires that the producer stated the capture was not capped, that every node carries the UIKit class name the rule reads, that each node is numbered once so the parent links the walk follows name the node they mean, and that the one content window under the app root holds exactly one presentation container. Positive evidence — the dimming view a presentation owns, an alert's own root class, or an element type that names a presentation — answers `presented` from a single node, so a capped capture still reports what it did read. Producers that publish no class names, which is every XCTest runner tier, answer `presented` or `unknown` and never `absent`. The rule reads a dimming view without its enablement, unlike the occlusion cut that shares the same container class: a sheet resting at an undimmed detent keeps a dimming view that takes no touches and is still presented. Two placements come from the repository's own gates rather than preference. The rule lives in `engine.ts` rather than its own module: ADR 0027 holds every entry's eager closure to the merge-base's module count, and a new module the engine imports is a new eager edge no split explains — thirteen carried entries would have grown by one module and seventy eager statements. And the publication is here rather than one layer up, because `check:production-exports` refuses an exported rule with no production consumer, so a layer that ships a decision nobody can read is not a layer that passes. The Apple runner's Swift twin, its parity test, and its own consumer land in the next layer, where the runner acquires trees; both languages read the one fixture.
1 parent 29aaf3b commit 9af006d

8 files changed

Lines changed: 870 additions & 2 deletions

File tree

‎contracts/fixtures/ios-presented-surface.json‎

Lines changed: 308 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
import fs from 'node:fs';
2+
import path from 'node:path';
3+
import { expect, test } from 'vitest';
4+
import type { PresentedSurface, RawSnapshotNode } from '@agent-device/kernel/snapshot';
5+
import {
6+
ALERT_ROOT_CLASS_PREFIX,
7+
PRESENTATION_CONTAINER_CLASS,
8+
PRESENTATION_DIMMING_VIEW_CLASS,
9+
PRESENTING_ELEMENT_TYPES,
10+
SYSTEM_WINDOW_CLASSES,
11+
collectPresentedSurface,
12+
type PresentedSurfaceCompleteness,
13+
} from './engine.ts';
14+
15+
const FIXTURE_PATH = path.resolve(
16+
import.meta.dirname,
17+
'..',
18+
'..',
19+
'..',
20+
'..',
21+
'contracts',
22+
'fixtures',
23+
'ios-presented-surface.json',
24+
);
25+
26+
type FixtureNode = {
27+
index: number;
28+
parentIndex?: number;
29+
type: string;
30+
role?: string;
31+
label?: string;
32+
userInteractionEnabled?: boolean;
33+
};
34+
35+
type FixtureCase = {
36+
name: string;
37+
truncated: boolean | null;
38+
expected: PresentedSurface;
39+
classBlindExpected: PresentedSurface;
40+
nodes: FixtureNode[];
41+
};
42+
43+
type Fixture = {
44+
vocabulary: {
45+
presentationContainerClass: string;
46+
dimmingViewClass: string;
47+
alertRootClassPrefix: string;
48+
systemWindowClasses: string[];
49+
presentingElementTypes: Array<{ name: string; elementType: number }>;
50+
};
51+
cases: FixtureCase[];
52+
};
53+
54+
function readFixture(): Fixture {
55+
return JSON.parse(fs.readFileSync(FIXTURE_PATH, 'utf8')) as Fixture;
56+
}
57+
58+
// Cross-language parity: the classifier must mirror the canonical table the Swift
59+
// SnapshotPresentedSurface also reads, and the vocabulary it mirrors by hand. A drift on either side
60+
// fails here or in the Swift test.
61+
test('the classifier mirrors the canonical vocabulary exactly', () => {
62+
const vocabulary = readFixture().vocabulary;
63+
expect(vocabulary.presentationContainerClass).toBe(PRESENTATION_CONTAINER_CLASS);
64+
expect(vocabulary.dimmingViewClass).toBe(PRESENTATION_DIMMING_VIEW_CLASS);
65+
expect(vocabulary.alertRootClassPrefix).toBe(ALERT_ROOT_CLASS_PREFIX);
66+
expect(new Set(vocabulary.systemWindowClasses)).toEqual(SYSTEM_WINDOW_CLASSES);
67+
expect(Object.fromEntries(PRESENTING_ELEMENT_TYPES)).toEqual(
68+
Object.fromEntries(
69+
vocabulary.presentingElementTypes.map((entry) => [entry.name, entry.elementType]),
70+
),
71+
);
72+
});
73+
74+
// Every case runs twice: once with the UIKit class names the table spells, once with every class name
75+
// stripped, which is what a capture from a producer that reports none — every XCTest runner tier —
76+
// actually looks like. That reading is what `classBlindExpected` states, and it is why the table can
77+
// hold a case a bridge capture answers `presented` and a runner capture answers `unknown`.
78+
test('every golden case classifies as the table states', () => {
79+
for (const testCase of readFixture().cases) {
80+
const completeness = completenessOf(testCase);
81+
expect(collectPresentedSurface(nodesOf(testCase), completeness)).toBe(testCase.expected);
82+
expect(collectPresentedSurface(classBlindNodesOf(testCase), completeness)).toBe(
83+
testCase.classBlindExpected,
84+
);
85+
}
86+
});
87+
88+
/**
89+
* The producer's own completeness claim, which the table states as `truncated`: a null is a producer
90+
* that observes nothing about truncation, and cannot be read as complete.
91+
*/
92+
function completenessOf(testCase: FixtureCase): PresentedSurfaceCompleteness {
93+
if (testCase.truncated === null) return 'unstated';
94+
return testCase.truncated ? 'capped' : 'complete';
95+
}
96+
97+
function nodesOf(testCase: FixtureCase): RawSnapshotNode[] {
98+
return testCase.nodes.map((node) => ({ ...node }));
99+
}
100+
101+
function classBlindNodesOf(testCase: FixtureCase): RawSnapshotNode[] {
102+
return testCase.nodes.map(({ role: _role, ...node }) => ({ ...node }));
103+
}

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,63 @@ function acquisition(
397397
};
398398
}
399399

400+
test("the published presented-surface fact is the acquisition's, for every projection", () => {
401+
const requests = [
402+
createIosSnapshotRequest(),
403+
createIosSnapshotRequest({ interactiveOnly: true }),
404+
createIosSnapshotRequest({ raw: true, depth: 1 }),
405+
createIosSnapshotRequest({ scope: 'Automation lab' }),
406+
];
407+
const answers = requests.map(
408+
(request) =>
409+
publishIosSnapshot(acquiredInput(request, presentedTreeNodes()), request).presentedSurface,
410+
);
411+
412+
// One screen answers one value: the fact is read on the acquired tree, so a projection that dropped
413+
// the presentation from what it shows still reports the presentation the producer saw.
414+
assert.deepEqual(answers, ['presented', 'presented', 'presented', 'presented']);
415+
});
416+
417+
test('an acquisition that states no completeness cannot be read as un-presented', () => {
418+
const request = createIosSnapshotRequest();
419+
const unstated: IosSnapshotAcquisition = {
420+
...acquisition(request, ordinaryTreeNodes()),
421+
truncated: undefined,
422+
};
423+
424+
assert.equal(
425+
publishIosSnapshot({ stage: 'acquired', acquisition: unstated }, request).presentedSurface,
426+
'unknown',
427+
);
428+
assert.equal(
429+
publishIosSnapshot(acquiredInput(request, ordinaryTreeNodes()), request).presentedSurface,
430+
'absent',
431+
);
432+
});
433+
434+
test('a runner-declared publication states no presented-surface fact of its own', () => {
435+
const request = createIosSnapshotRequest();
436+
const input: IosSnapshotInput = {
437+
stage: 'presented',
438+
presentation: {
439+
producer: 'apple-runner',
440+
intent: 'full',
441+
payload: { nodes: presentedTreeNodes(), truncated: false },
442+
},
443+
validation: validationFacts(request),
444+
};
445+
446+
// The runner classifies its own pre-presentation acquisition and publishes the reading beside the
447+
// payload; re-deriving one from the presented tree here would be a second, weaker answer. The same tree
448+
// answers at the acquired stage, so this pins the stage gate and not a classifier that reads neither:
449+
// a publication path that stopped classifying at all would fail the second assertion, not this one.
450+
assert.equal(publishIosSnapshot(input, request).presentedSurface, undefined);
451+
assert.equal(
452+
publishIosSnapshot(acquiredInput(request, presentedTreeNodes()), request).presentedSurface,
453+
'presented',
454+
);
455+
});
456+
400457
function acquiredInput(request: IosSnapshotRequest, nodes: RawSnapshotNode[]): IosSnapshotInput {
401458
return { stage: 'acquired', acquisition: acquisition(request, nodes) };
402459
}
@@ -421,6 +478,49 @@ function nestedNodes(): RawSnapshotNode[] {
421478
];
422479
}
423480

481+
/** A UIKit-shaped tree over which a presentation is up: a second container carrying a dimming view. */
482+
function presentedTreeNodes(): RawSnapshotNode[] {
483+
return [
484+
appNode(0, 'UIApplication', 'Application', viewport, undefined),
485+
appNode(1, 'UIWindow', 'Window', viewport, 0),
486+
appNode(2, 'UITransitionView', 'Other', viewport, 1),
487+
node(3, 'StaticText', 'Automation lab', { x: 10, y: 20, width: 200, height: 20 }, 2, 3),
488+
appNode(4, 'UITransitionView', 'Other', viewport, 1),
489+
{ ...appNode(5, 'UIDimmingView', 'Other', viewport, 4), userInteractionEnabled: true },
490+
node(6, 'StaticText', 'Automation sheet', { x: 10, y: 120, width: 200, height: 20 }, 4, 4),
491+
];
492+
}
493+
494+
/** A UIKit-shaped tree with nothing presenting: one window, its own single container. */
495+
function ordinaryTreeNodes(): RawSnapshotNode[] {
496+
return [
497+
appNode(0, 'UIApplication', 'Application', viewport, undefined),
498+
appNode(1, 'UIWindow', 'Window', viewport, 0),
499+
appNode(2, 'UITransitionView', 'Other', viewport, 1),
500+
appNode(
501+
3,
502+
'RCTParagraphComponentView',
503+
'StaticText',
504+
{ x: 10, y: 20, width: 200, height: 20 },
505+
2,
506+
),
507+
];
508+
}
509+
510+
/** A node shaped like the simulator AX bridge reports one: UIKit class name in `role`. */
511+
function appNode(
512+
index: number,
513+
role: string,
514+
type: string,
515+
rect: Rect,
516+
parentIndex: number | undefined,
517+
): RawSnapshotNode {
518+
return {
519+
...node(index, type, undefined, rect, parentIndex, parentIndex === undefined ? 0 : 1),
520+
role,
521+
};
522+
}
523+
424524
function scopedNodes(): RawSnapshotNode[] {
425525
return [
426526
node(0, 'Application', 'App', viewport),

0 commit comments

Comments
 (0)