Skip to content

Commit c56942e

Browse files
thymikeeclaude
andcommitted
fix(apple): give a tree that changed during a bridge read capture scope
The bridge reader re-reads a node whose children the first read withheld. When a scrolling list recycles its cells between the two reads, the re-read returns fewer children, and the runtime reported every such reader error as snapshot-tree-malformed. The route then retired the app generation, so one scroll moved every later capture of the app to XCTest (seen on Bluesky's feed). The reader errors are now a typed enum, and the runtime maps each one to its refusal: a changed tree is snapshot-tree-changed with capture scope, and a foreground change during a continuation is foreground-owner-changed. Co-Authored-By: Claude <[email protected]>
1 parent 3a4eb6d commit c56942e

11 files changed

Lines changed: 119 additions & 21 deletions

‎apple/snapshot-bridge/SnapshotBridgeCapture.h‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,26 @@ extern const NSUInteger kMaximumRequestLevels;
77
/// Requests one acquisition may issue before it fails as continuation-budget-exhausted.
88
extern const NSUInteger kMaximumRequestsPerCapture;
99

10+
/// The domain of every error the tree reader reports.
11+
extern NSErrorDomain const SnapshotCaptureErrorDomain;
12+
13+
/// Why the reader stopped. The runtime maps each one to its wire refusal code.
14+
typedef NS_ERROR_ENUM(SnapshotCaptureErrorDomain, SnapshotCaptureError) {
15+
/// The acquisition used every request it may issue.
16+
SnapshotCaptureErrorBudgetExhausted = 1,
17+
/// A native read returned a node that is not a snapshot dictionary.
18+
SnapshotCaptureErrorMalformedContinuation = 2,
19+
/// A node withheld children but carried no element to continue from.
20+
SnapshotCaptureErrorContinuationElementUnavailable = 3,
21+
/// A continuation re-read returned fewer children than the first read reported: the tree changed
22+
/// between the two reads, as a scrolling list does when it recycles its cells.
23+
SnapshotCaptureErrorTreeChanged = 4,
24+
/// The foreground process changed while a continuation was read.
25+
SnapshotCaptureErrorForegroundOwnerChanged = 5,
26+
/// A node below the first level reported no child count, so its children cannot be bounded.
27+
SnapshotCaptureErrorBoundaryChildCountUnavailable = 6,
28+
};
29+
1030
typedef id _Nullable (^SnapshotElementReader)(id element, NSUInteger depth, NSUInteger nodes, NSError **error);
1131

1232
/// Native request accounting for one acquisition: requests issued, requests the accessibility

‎apple/snapshot-bridge/SnapshotBridgeCapture.m‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
#import "SnapshotBridgeCapture.h"
22

3+
NSErrorDomain const SnapshotCaptureErrorDomain = @"agent-device.snapshot";
4+
35
static NSString *const attributesKey = @"UIAccessibilitySnapshotKeyAttributes";
46
static NSString *const childrenKey = @"UIAccessibilitySnapshotKeyChildren";
57
static NSString *const childCountKey = @"UIAccessibilitySnapshotKeyChildrenCount";
@@ -32,7 +34,7 @@ - (nullable NSDictionary *)read:(id)element depth:(NSUInteger)depth error:(NSErr
3234
NSUInteger attemptDepth = MIN(depth, self.acceptedDepth);
3335
for (NSUInteger retries = 0;; retries++) {
3436
if (self.requests >= kMaximumRequestsPerCapture) {
35-
if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:1
37+
if (error) *error = [NSError errorWithDomain:SnapshotCaptureErrorDomain code:SnapshotCaptureErrorBudgetExhausted
3638
userInfo:@{NSLocalizedDescriptionKey: @"snapshot continuation request budget exhausted"}];
3739
return nil;
3840
}
@@ -58,7 +60,7 @@ - (nullable NSDictionary *)materialize:(NSDictionary *)tree depth:(NSUInteger)de
5860
if (![tree isKindOfClass:NSDictionary.class] ||
5961
![tree[attributesKey] isKindOfClass:NSDictionary.class] ||
6062
![tree[childrenKey] isKindOfClass:NSArray.class]) {
61-
if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:2
63+
if (error) *error = [NSError errorWithDomain:SnapshotCaptureErrorDomain code:SnapshotCaptureErrorMalformedContinuation
6264
userInfo:@{NSLocalizedDescriptionKey: @"malformed snapshot continuation"}];
6365
return nil;
6466
}
@@ -73,7 +75,7 @@ - (nullable NSDictionary *)materialize:(NSDictionary *)tree depth:(NSUInteger)de
7375
childCount.doubleValue == (double)childCount.unsignedIntegerValue;
7476
if (nativeLevels <= 1 && !knownChildCount && depth <= 1) self.truncated = YES;
7577
if (depth > 1 && nativeLevels <= 1 && !knownChildCount) {
76-
if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:6
78+
if (error) *error = [NSError errorWithDomain:SnapshotCaptureErrorDomain code:SnapshotCaptureErrorBoundaryChildCountUnavailable
7779
userInfo:@{NSLocalizedDescriptionKey: @"snapshot boundary child count unavailable"}];
7880
return nil;
7981
}
@@ -88,7 +90,7 @@ - (nullable NSDictionary *)materialize:(NSDictionary *)tree depth:(NSUInteger)de
8890
if (withheld && children.count < self.remainingNodes) {
8991
id element = tree[elementKey];
9092
if (!element) {
91-
if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:3
93+
if (error) *error = [NSError errorWithDomain:SnapshotCaptureErrorDomain code:SnapshotCaptureErrorContinuationElementUnavailable
9294
userInfo:@{NSLocalizedDescriptionKey: @"snapshot continuation element unavailable"}];
9395
return nil;
9496
}
@@ -97,7 +99,7 @@ - (nullable NSDictionary *)materialize:(NSDictionary *)tree depth:(NSUInteger)de
9799
nativeLevels = MIN(depth, self.acceptedDepth);
98100
children = continuation[childrenKey];
99101
if (![children isKindOfClass:NSArray.class] || children.count < MIN(childCount.unsignedIntegerValue, self.remainingNodes)) {
100-
if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:4
102+
if (error) *error = [NSError errorWithDomain:SnapshotCaptureErrorDomain code:SnapshotCaptureErrorTreeChanged
101103
userInfo:@{NSLocalizedDescriptionKey: @"snapshot continuation children unavailable"}];
102104
return nil;
103105
}

‎apple/snapshot-bridge/SnapshotBridgeRuntime.m‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,25 @@
3838
static NSString *const kAttributeIsUserInteractionEnabled = @"XC_kAXXCAttributeIsUserInteractionEnabled";
3939
static NSString *const kPresentationDimmingViewClass = @"UIDimmingView";
4040
static NSString *const kSnapshotAttributes = @"UIAccessibilitySnapshotKeyAttributes";
41+
42+
/// The wire refusal for a reader error. A tree that changed between two reads and a foreground that
43+
/// changed during a continuation describe the screen at that moment, so their codes are capture-scoped;
44+
/// the other reader errors describe what this reader can read.
45+
static NSDictionary *captureFailureResponse(NSString *requestId, SnapshotCaptureError code, NSString *message) {
46+
switch (code) {
47+
case SnapshotCaptureErrorBudgetExhausted:
48+
return failureResponse(requestId, @"reader_unavailable", @"continuation-budget-exhausted", message);
49+
case SnapshotCaptureErrorTreeChanged:
50+
return failureResponse(requestId, @"malformed_tree", @"snapshot-tree-changed", message);
51+
case SnapshotCaptureErrorForegroundOwnerChanged:
52+
return failureResponse(requestId, @"unsupported", @"foreground-owner-changed", message);
53+
case SnapshotCaptureErrorMalformedContinuation:
54+
case SnapshotCaptureErrorContinuationElementUnavailable:
55+
case SnapshotCaptureErrorBoundaryChildCountUnavailable:
56+
return failureResponse(requestId, @"malformed_tree", @"snapshot-tree-malformed", message);
57+
}
58+
return failureResponse(requestId, @"malformed_tree", @"snapshot-tree-malformed", message);
59+
}
4160
static NSString *const kSnapshotChildren = @"UIAccessibilitySnapshotKeyChildren";
4261
static NSString *const kSnapshotElement = @"UIAccessibilitySnapshotKeyElement";
4362
static NSString *const kXctAutomationSupportPath =
@@ -422,7 +441,7 @@ - (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
422441
snapshot = captureSnapshotTree((__bridge id)raw, maxDepth, maxNodes, nativeLevelsHint,
423442
^id(id element, NSUInteger depth, NSUInteger nodes, NSError **captureError) {
424443
if (![self isPrimaryForegroundProcess:pid]) {
425-
if (captureError) *captureError = [NSError errorWithDomain:@"agent-device.snapshot" code:5
444+
if (captureError) *captureError = [NSError errorWithDomain:SnapshotCaptureErrorDomain code:SnapshotCaptureErrorForegroundOwnerChanged
426445
userInfo:@{NSLocalizedDescriptionKey: @"foreground owner changed during continuation"}];
427446
return nil;
428447
}
@@ -442,10 +461,8 @@ - (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
442461
finishRequestWatchdog(watchdog, watchdogState);
443462
return nil;
444463
}
445-
if (!snapshot && [runtimeError.domain isEqualToString:@"agent-device.snapshot"]) {
446-
BOOL exhausted = runtimeError.code == 1;
447-
if (error) *error = failureResponse(requestId, exhausted ? @"reader_unavailable" : @"malformed_tree",
448-
exhausted ? @"continuation-budget-exhausted" : @"snapshot-tree-malformed", runtimeError.localizedDescription);
464+
if (!snapshot && [runtimeError.domain isEqualToString:SnapshotCaptureErrorDomain]) {
465+
if (error) *error = captureFailureResponse(requestId, (SnapshotCaptureError)runtimeError.code, runtimeError.localizedDescription);
449466
finishRequestWatchdog(watchdog, watchdogState);
450467
return nil;
451468
}

‎contracts/fixtures/ios-ax-recovery-conformance.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,35 @@
359359
}
360360
}
361361
},
362+
{
363+
"name": "children-shrink-during-continuation",
364+
"request": {
365+
"traversalDepth": 64,
366+
"explicitDepth": false,
367+
"nodeBudget": 1500
368+
},
369+
"native": {
370+
"tree": {
371+
"chain": 45
372+
},
373+
"rejectLevelsAbove": 48,
374+
"frontierEvidence": "counted",
375+
"shrinkOnContinuation": true
376+
},
377+
"expected": {
378+
"host-bridge": {
379+
"outcome": "failed",
380+
"failure": "tree-changed",
381+
"requests": 3,
382+
"rejected": 1,
383+
"continuations": 1
384+
},
385+
"runner": {
386+
"outcome": "not-applicable",
387+
"reason": "the runner's XCTest plan reads no continuation; the tree-changed refusal belongs to the bridge reader"
388+
}
389+
}
390+
},
362391
{
363392
"name": "host-request-budget",
364393
"request": {

‎contracts/fixtures/ios-snapshot-bridge-refusals.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@
2424
{
2525
"code": "bridge-preparation-pending",
2626
"consequence": "bridge-preparation"
27+
},
28+
{
29+
"code": "snapshot-tree-changed",
30+
"consequence": "tree-changed"
2731
}
2832
],
2933
"generationScoped": [

‎docs/adr/0004-ios-snapshot-backend-strategy.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,12 @@ A bridge request on each capture would instead add a refused bridge round trip t
9090
The circuit limits that cost to one capture per generation.
9191
A refusal that provides evidence about the screen instead of the app has capture scope.
9292
The coordinate-space amendment below decides that case.
93+
A tree that changed between two reads also has capture scope (`snapshot-tree-changed`).
94+
The reader re-reads a node whose children the first read withheld.
95+
If the re-read returns fewer children than the first read counted, the screen moved between the reads, as a scrolling list does when it recycles its cells.
96+
That refusal costs one capture, and the next capture of the same app uses the bridge again.
97+
A foreground owner that changes during a continuation is `foreground-owner-changed`, with the same scope.
98+
`contracts/fixtures/ios-snapshot-bridge-refusals.json` lists the scope of every refusal code.
9399

94100
Keep the two public snapshot strategies explicit:
95101

‎packages/platform-apple/src/snapshot-route-failure-policy.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import type { SnapshotSourceFailure } from './snapshot-source-facade.ts';
22

33
/**
44
* What the screen showed when a capture-scoped bridge refusal fired: a preparation still running
5-
* (#2491), a runner-served read still running, an unresolved coordinate space (#2612), a foreground
5+
* (#2491), a runner-served read still running, a tree that changed between two reads, an unresolved coordinate space (#2612), a foreground
66
* another surface owns (#3874), or a window that does not fill the screen (#3844). The route consumes one disposition for both
77
* decisions that must agree: whether the generation's bridge circuit opens, and which sentence the
88
* fallback warning carries (#3874, #3895).
@@ -12,6 +12,7 @@ export type CaptureScopedConsequence =
1212
| 'bridge-read-busy'
1313
| 'coordinate-space-unresolved'
1414
| 'foreground-ownership'
15+
| 'tree-changed'
1516
| 'window-not-full-screen';
1617

1718
/**
@@ -39,6 +40,9 @@ const CAPTURE_SCOPED_REFUSALS: ReadonlyMap<string, CaptureScopedConsequence> = n
3940
// The runner-served reader runs one read at a time: the refusal says only that another read, such
4041
// as one a cancelled capture left running, has not returned yet.
4142
['bridge-read-in-flight', 'bridge-read-busy'],
43+
// A continuation re-read found fewer children than the first read reported: the tree changed
44+
// between the two reads, as a list does while it scrolls and recycles its cells.
45+
['snapshot-tree-changed', 'tree-changed'],
4246
]);
4347

4448
/**

‎packages/platform-apple/src/snapshot-route.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -405,6 +405,7 @@ test.for([
405405
],
406406
['foreground-owner-unverified', 'while another surface owned the foreground'],
407407
['foreground-owner-changed', 'while another surface owned the foreground'],
408+
['snapshot-tree-changed', 'while the screen changed during the bridge read'],
408409
[
409410
'app-window-not-full-screen',
410411
'while the app window did not fill the screen; the runner republishes a windowed capture in screen space',

‎packages/platform-apple/src/snapshot-route.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -630,6 +630,8 @@ function captureScopedFallbackWarning(code: string, consequence: CaptureScopedCo
630630
return `${thisCapture} while an earlier bridge read was still running.`;
631631
case 'foreground-ownership':
632632
return `${thisCapture}, while another surface owned the foreground.`;
633+
case 'tree-changed':
634+
return `${thisCapture}, while the screen changed during the bridge read.`;
633635
case 'window-not-full-screen':
634636
return `${thisCapture}, while the app window did not fill the screen; the runner republishes a windowed capture in screen space.`;
635637
case 'coordinate-space-unresolved':

‎packages/platform-apple/src/snapshot-source/fixtures/foreground-owner.m‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,8 @@ int main(int argc, const char *argv[])
203203
if ([@[@"depth-missing-element", @"depth-incomplete", @"depth-missing-count", @"depth-invalid-count", @"depth-continuation-count", @"depth-fractional-count", @"depth-nan-count", @"depth-negative-count"] containsObject:scenario]) {
204204
expectedCode = @"snapshot-tree-malformed";
205205
if (![scenario isEqual:@"depth-incomplete"] && ![scenario isEqual:@"depth-continuation-count"]) expectedCaptures = 2;
206+
// The continuation found fewer children than the first read counted: the tree changed.
207+
if ([scenario isEqual:@"depth-incomplete"]) expectedCode = @"snapshot-tree-changed";
206208
}
207209
if ([scenario isEqual:@"depth-owner-change"]) {
208210
replacementApplication = system;
@@ -240,7 +242,7 @@ int main(int argc, const char *argv[])
240242
nativeLevelsHint:0 requestId:@"capture-1" generation:@"generation-1" maxDurationMs:4000 error:&error];
241243
if (expectedCode) {
242244
require(result == nil, @"refused capture must not publish the app tree");
243-
require([error[@"error_kind"] isEqual:([expectedCode isEqual:@"application-server-unavailable"] ? @"application_unavailable" : [expectedCode isEqual:@"snapshot-tree-malformed"] ? @"malformed_tree" : [expectedCode isEqual:@"continuation-budget-exhausted"] ? @"reader_unavailable" : @"unsupported")], @"refusal must preserve the typed failure kind");
245+
require([error[@"error_kind"] isEqual:([expectedCode isEqual:@"application-server-unavailable"] ? @"application_unavailable" : ([expectedCode isEqual:@"snapshot-tree-malformed"] || [expectedCode isEqual:@"snapshot-tree-changed"]) ? @"malformed_tree" : [expectedCode isEqual:@"continuation-budget-exhausted"] ? @"reader_unavailable" : @"unsupported")], @"refusal must preserve the typed failure kind");
244246
require([error[@"error_code"] isEqual:expectedCode], @"refusal must name the ownership phase");
245247
require([error[@"requestId"] isEqual:@"capture-1"], @"refusal must preserve request identity");
246248
} else {

0 commit comments

Comments
 (0)