Repository navigation
Expand file tree
/
Copy pathsnapshot-model.ts
More file actions
421 lines (396 loc) · 16.3 KB
/
Copy pathsnapshot-model.ts
File metadata and controls
421 lines (396 loc) · 16.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
import type {
IosTargetActivation,
PresentedSurface,
SnapshotKeyboardBandFact,
SnapshotNode,
SnapshotPresentation,
SnapshotQualityNote,
SnapshotQualityVerdict,
SnapshotRefMinting,
SnapshotViewportSize,
} from '@agent-device/kernel/snapshot';
/**
* Every acquisition that can produce a snapshot tree, named for the source and never for the
* platform: one platform channel can be fed by several producers with different guarantees, and
* one producer can feed more than one channel (`appium-source` answers for WebDriver iOS and
* Android). Sharing a parser does not make two sources one producer.
*/
export type SnapshotProducer =
| 'apple-runner'
| 'simulator-ax-bridge'
| 'appium-source'
| 'revyl-ios-tree'
| 'revyl-android-tree'
| 'android-uiautomator'
| 'cdp-dom'
| 'harmonyos-uitest'
| 'macos-helper'
| 'linux-atspi'
| 'agent-browser';
export type SnapshotProducerFacts = Readonly<{
/** The platform channels this producer's trees arrive on: the `backend` of its provenance pairs. */
channels: readonly [string, ...string[]];
/**
* Whether the producer observes truncation at all. On the iOS channel a capture that reported
* nothing about truncation is only "not truncated" when its producer would have noticed (#2188
* invariant 5).
*/
truncation: 'available' | 'unavailable';
/**
* `source-measured`: the source builds its own residue. `provider-derived`: a provider hands over a
* bare tree and nothing else, so capture-kit derives what it leaves unproven. On the iOS channel
* only a provider-derived producer may build an acquisition through capture-kit; a source-measured
* one there would be a claim nothing consults (#2199).
*/
residue: 'source-measured' | 'provider-derived';
/**
* The default stable-capture quiet window a capture from this producer earns. The Simulator AX
* bridge answers well inside the general default, so holding the general window on that read spends
* a whole extra capture on a window its tree had already satisfied (PR #3522 holds the measurement).
* Every producer states its price, so a new one cannot inherit an unmeasured window by omission.
*/
quietMs: number;
/**
* `backend-issued`: the producer resolves actions against refs it minted itself, and so owns the
* ref namespace of every tree it publishes (#2283). A producer that mints nothing keeps dense
* positional numbering.
*/
refs: SnapshotRefMinting;
/**
* What an iOS interactive snapshot that exposed only the application root says about this producer:
* an XCTest query that failed to enumerate the tree, an Appium page source that lacked the
* descendants, or nothing.
*/
sparseRootWarning: 'xctest-query' | 'appium-page-source' | 'none';
}>;
const GENERAL_QUIET_MS = 500;
/**
* The one table of producer facts. Every other producer-keyed fact derives from it: the provenance
* pairs below, the iOS producer subsets (`ios-snapshot.ts`), truncation, residue,
* quiet time, ref minting, and producer warning dispatch. A new producer adds a row here and stamps
* its served identity through {@link stampSnapshotIdentity}.
*/
export const SNAPSHOT_PRODUCERS = {
'apple-runner': {
channels: ['xctest'],
truncation: 'available',
residue: 'source-measured',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'xctest-query',
},
'simulator-ax-bridge': {
channels: ['xctest'],
truncation: 'available',
residue: 'source-measured',
quietMs: 300,
refs: 'dense',
sparseRootWarning: 'none',
},
'appium-source': {
channels: ['xctest', 'android'],
truncation: 'unavailable',
residue: 'provider-derived',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'appium-page-source',
},
'revyl-ios-tree': {
channels: ['xctest'],
truncation: 'unavailable',
residue: 'provider-derived',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'none',
},
'revyl-android-tree': {
channels: ['android'],
truncation: 'unavailable',
residue: 'provider-derived',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'none',
},
'android-uiautomator': {
channels: ['android'],
truncation: 'available',
residue: 'source-measured',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'none',
},
'cdp-dom': {
channels: ['android'],
truncation: 'available',
residue: 'source-measured',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'none',
},
'harmonyos-uitest': {
channels: ['harmonyos-arkui'],
truncation: 'available',
residue: 'source-measured',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'none',
},
'macos-helper': {
channels: ['macos-helper'],
truncation: 'available',
residue: 'source-measured',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'none',
},
'linux-atspi': {
channels: ['linux-atspi'],
truncation: 'available',
residue: 'source-measured',
quietMs: GENERAL_QUIET_MS,
refs: 'dense',
sparseRootWarning: 'none',
},
'agent-browser': {
channels: ['web'],
truncation: 'available',
residue: 'source-measured',
quietMs: GENERAL_QUIET_MS,
refs: 'backend-issued',
sparseRootWarning: 'none',
},
} as const satisfies Record<SnapshotProducer, SnapshotProducerFacts>;
/**
* The registry row of a producer read from a capture. A store plugin built against another release
* can name a producer this host does not list; that capture gets no producer facts.
*/
export function snapshotProducerFacts(
producer: SnapshotProducer,
): SnapshotProducerFacts | undefined {
return Object.hasOwn(SNAPSHOT_PRODUCERS, producer) ? SNAPSHOT_PRODUCERS[producer] : undefined;
}
type ProducerChannel<Producer extends SnapshotProducer> =
(typeof SNAPSHOT_PRODUCERS)[Producer]['channels'][number];
export type SnapshotBackend = ProducerChannel<SnapshotProducer>;
type ProducerOnChannel<Backend extends SnapshotBackend> = {
[Producer in SnapshotProducer]: Backend extends ProducerChannel<Producer> ? Producer : never;
}[SnapshotProducer];
/**
* The channel↔producer pairs that can actually occur, derived from {@link SNAPSHOT_PRODUCERS}.
* `xctest` trees come from the local Apple runner, the Simulator AX bridge, Appium page-source XML,
* or a cloud provider's AX element tree (Revyl), and only the runner's output has been through its
* presentation (clip fold, effective geometry, scope). Logic that assumes those guarantees must key
* on the producer, never on the channel alone.
*
* Every carrier embeds the pair atomically, so a cross-channel pair does not compile.
*/
export type SnapshotProvenance = {
[Backend in SnapshotBackend]: { backend: Backend; producer: ProducerOnChannel<Backend> };
}[SnapshotBackend];
/**
* Stamps the served identity of a capture onto its result: the producer that read the tree and the
* channel it arrived on. Every one-source owner stamps through here (ADR 0038); an owner with more
* than one source routes through the snapshot router instead. It lives beside the registry, in a
* module every capture path already evaluates, so stamping adds no module to a capture's import
* closure. The identity must be a registry pair: a producer without a {@link SNAPSHOT_PRODUCERS} row,
* or a channel its row does not list, does not compile.
*/
export function stampSnapshotIdentity<
Result extends object,
const Identity extends SnapshotProvenance,
>(result: Result, identity: Identity): Omit<Result, 'backend' | 'producer'> & Identity {
return { ...result, ...identity };
}
type OptionalProducerProvenance<Pair> = Pair extends {
backend: infer Backend;
producer: infer Producer;
}
? { backend: Backend; producer?: Producer }
: never;
/**
* The provenance carrier for {@link SnapshotState}: the producer may be absent (a client-side
* fallback that rebuilds a state from a bare backend result knows the channel and nothing more),
* but a present pair still has to come from the {@link SnapshotProvenance} table — the channel
* may not carry a foreign producer.
*/
export type SnapshotStateProvenance =
| OptionalProducerProvenance<SnapshotProvenance>
| { backend?: undefined; producer?: undefined };
/**
* The provenance a capture hands to the daemon snapshot assembly: either nothing is known about
* the origin, or the WHOLE pair is. A channel that arrived without its producer would leave the
* assembly guessing who presented the tree, which is exactly the backend-name presentation
* policy #2199 deleted — so it does not compile. Every production capture satisfies this: the
* interactor boundary (`SnapshotResult`) already carries {@link SnapshotProvenance}.
*/
export type SnapshotCaptureProvenance =
| SnapshotProvenance
| { backend?: undefined; producer?: undefined };
/**
* Narrows a provenance-carrying value to just its pair without decorrelating the two fields
* (reading `backend` and `producer` separately would lose the pairing for the type system).
*/
export function snapshotStateProvenance(
value: SnapshotStateProvenance | undefined,
): SnapshotStateProvenance {
if (value === undefined || value.backend === undefined) return {};
switch (value.backend) {
case 'xctest':
return { backend: value.backend, producer: value.producer };
case 'android':
return { backend: value.backend, producer: value.producer };
case 'harmonyos-arkui':
return { backend: value.backend, producer: value.producer };
case 'macos-helper':
return { backend: value.backend, producer: value.producer };
case 'linux-atspi':
return { backend: value.backend, producer: value.producer };
case 'web':
return { backend: value.backend, producer: value.producer };
}
}
const SNAPSHOT_BACKENDS: ReadonlySet<string> = new Set(
Object.values(SNAPSHOT_PRODUCERS).flatMap((facts) => facts.channels),
);
export function isSnapshotBackend(value: unknown): value is SnapshotBackend {
return typeof value === 'string' && SNAPSHOT_BACKENDS.has(value);
}
export function usesMobileSnapshotPresentation(backend: SnapshotBackend | undefined): boolean {
return (
backend === undefined ||
backend === 'xctest' ||
backend === 'android' ||
backend === 'harmonyos-arkui'
);
}
export type SnapshotState = {
nodes: SnapshotNode[];
createdAt: number;
truncated?: boolean;
snapshotQuality?: SnapshotQualityVerdict;
snapshotQualityNotes?: SnapshotQualityNote[];
comparisonSafe?: boolean;
presentationKey?: string;
/** The presentation this capture was taken with; absent means the default full tree. */
presentation?: SnapshotPresentation;
/** Opaque equality key for iOS acquisition and presentation lineage. */
comparisonKey?: string;
/**
* Android: the capture is an occluding system surface (notification shade, quick settings)
* rather than app content. Consumers that surface this tree to the agent must disclose the
* occlusion (see `@agent-device/contracts/android-system-surface-disclosure`).
*/
systemSurfaceOnly?: boolean;
/**
* iOS: the bundle id of the in-place system surface this capture describes (a web sign-in sheet
* presented over the app, #2438). Two captures that disagree here describe different surfaces and
* must never be compared as the same presentation; consumers that surface the tree disclose it.
*/
iosSystemSurfaceBundleId?: string;
/**
* iOS: whether this capture read a modal presentation over the app's own content (#3565), decided
* on the acquired tree before interactive filtering, compaction, depth, or scope, so every view of
* one screen carries one value. `'absent'` is read, never defaulted; an unreadable or unexplained
* capture answers `'unknown'`. Settle's presented-surface confirmation arms on this fact.
*/
presentedSurface?: PresentedSurface;
/**
* iOS and Android: keyboard observations made during acquisition. Measured and derived frames
* take precedence over reconstruction from the presented tree. Visibility-only and unknown facts
* carry no band; missing nodes or an omitted fact never establish absence.
*/
keyboard?: SnapshotKeyboardBandFact;
/**
* The box these rects are measured in, as the producer measured it (#3182). The state is the carrier
* the response reads, so the stored tree and the published `viewport` are one fact rather than two:
* a consumer of a stored capture — a later diff, a re-read of the session's tree — gets the box the
* producer measured instead of inferring one from the largest rect still on screen.
*/
viewport?: SnapshotViewportSize;
/**
* iOS: this capture's own command found the session app out of foreground and the runner
* activated it before answering, so an earlier observation in the session described whatever held
* the foreground instead (#2682). Consumers that surface this tree disclose the repair.
*/
targetActivation?: IosTargetActivation;
/** What post-gesture stabilization proved about the gesture before this capture. */
postGestureOutcome?: PostGestureOutcome;
} & SnapshotStateProvenance;
/** The gesture a post-gesture outcome fact names: the command and its positionals. */
export type PostGestureAction = { action: string; positionals: string[] };
/**
* `unsettled`: the surface was still changing when the stabilization deadline expired.
* `no-effect`: the settled surface still matches the pre-gesture tree (#1600).
*/
export type PostGestureOutcome = {
kind: 'unsettled' | 'no-effect';
gesture: PostGestureAction;
};
/**
* A capture taken at once to recover or widen `previous` reads the same moment after the same
* gesture, so it carries that capture's outcome.
*/
export function inheritPostGestureOutcome<T extends SnapshotState>(
previous: SnapshotState,
recapture: T,
): T {
recapture.postGestureOutcome ??= previous.postGestureOutcome;
return recapture;
}
/**
* The ref-minting mode of a capture, from the pair that produced it. The projection that publishes a
* tree and the projection that later re-attaches refs to it both read it here, so they cannot
* disagree about which producers own their ref namespace.
*
* It reads the producer and not the platform channel, per the rule the provenance table states:
* several producers can feed one channel with different guarantees, and a second web adapter
* (webdriver-backed, or anything else that lands on this channel) mints no refs of its own — it
* needs dense numbering, which a channel-keyed check would silently take away from it. The
* parameter is the whole pair or nothing, so a caller cannot present a channel and leave this to
* guess who acquired the tree.
*/
export function snapshotRefMinting(
provenance: SnapshotCaptureProvenance | undefined,
): SnapshotRefMinting {
const producer = provenance?.producer;
return producer === undefined ? 'dense' : (snapshotProducerFacts(producer)?.refs ?? 'dense');
}
export function buildSnapshotNodeMap<T extends { index: number }>(
nodes: readonly T[],
): Map<number, T> {
return new Map(nodes.map((node) => [node.index, node]));
}
/**
* Walks from the given node through its parent chain and returns the first
* non-null value produced by `resolve`. Returning null from `resolve` skips
* that ancestor and continues walking toward the root. Parents are resolved
* by snapshot index (not array position) with an array-offset fallback, and
* a visited set guards against parent-linkage cycles.
*/
export function findSnapshotAncestor<T>(
nodes: SnapshotNode[],
node: SnapshotNode,
nodeByIndex: ReadonlyMap<number, SnapshotNode>,
resolve: (ancestor: SnapshotNode) => T | null,
): T | null {
let current: SnapshotNode | undefined = node;
const visited = new Set<number>();
while (typeof current.parentIndex === 'number' && !visited.has(current.index)) {
visited.add(current.index);
current = nodeByIndex.get(current.parentIndex) ?? nodes[current.parentIndex];
if (!current) return null;
const result = resolve(current);
if (result !== null) return result;
}
return null;
}
/** Returns the nearest ancestor matching `predicate`; false means keep walking. */
export function findNearestAncestor(
nodes: SnapshotNode[],
node: SnapshotNode,
predicate: (ancestor: SnapshotNode) => boolean,
): SnapshotNode | null {
return findSnapshotAncestor(nodes, node, buildSnapshotNodeMap(nodes), (ancestor) =>
predicate(ancestor) ? ancestor : null,
);
}