|
| 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 | +} |
0 commit comments