agent-device 0.20.4 → 0.20.6

package/README.md

@@ -61,6 +61,8 @@ agent-device close
 
 Use refs only from the latest output. Do not assume an earlier `@eN` still identifies the same element. After a command with `--settle`, use the refs in its diff. Take another snapshot only if the diff omits what you need.
 
+`--settle` works the same way on `scroll` and `back`, so scroll-then-observe and back-then-observe are one call too.
+
 Snapshots use the app's accessibility tree. Clear labels, roles, and test IDs make agent runs more reliable. Use screenshots and videos as evidence or when accessibility data is poor. Use refs and selectors for actions and assertions when you can.
 
 ![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](./website/docs/public/agent-device-contacts.gif)

package/android/ime-helper/dist/agent-device-android-ime-helper-0.20.6.apk.sha256

@@ -0,0 +1 @@
+7f719c5e1698e827948a9de22bf31aab065d7f2cb7d17731793b586fd3f88f4f  agent-device-android-ime-helper-0.20.6.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.4.manifest.json → agent-device-android-ime-helper-0.20.6.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.20.4",
-  "assetName": "agent-device-android-ime-helper-0.20.4.apk",
-  "sha256": "019ebbda52976df5cff05f9e5a764c8d6e280be3640e8dea0a2d7cca6c25021f",
+  "version": "0.20.6",
+  "assetName": "agent-device-android-ime-helper-0.20.6.apk",
+  "sha256": "7f719c5e1698e827948a9de22bf31aab065d7f2cb7d17731793b586fd3f88f4f",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20004,
+  "versionCode": 20006,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.20.6.apk.sha256

@@ -0,0 +1 @@
+696f8e518bbc2ad66225cb80f2e9e70d2b19b75d382918edd8fce3009200e434  agent-device-android-snapshot-helper-0.20.6.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.4.manifest.json → agent-device-android-snapshot-helper-0.20.6.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.20.4",
-  "releaseTag": "v0.20.4",
-  "assetName": "agent-device-android-snapshot-helper-0.20.4.apk",
+  "version": "0.20.6",
+  "releaseTag": "v0.20.6",
+  "assetName": "agent-device-android-snapshot-helper-0.20.6.apk",
   "apkUrl": null,
-  "sha256": "e3799afe5549776e047744efe46939a9146a4742a5328bb2e22f0b9d6abd2b52",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.4.apk.sha256",
+  "sha256": "696f8e518bbc2ad66225cb80f2e9e70d2b19b75d382918edd8fce3009200e434",
+  "checksumName": "agent-device-android-snapshot-helper-0.20.6.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20004,
+  "versionCode": 20006,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m

@@ -62,6 +62,13 @@ int main(int argc, const char *argv[]) {
 
 @implementation AgentDeviceRunnerViewController
 
+- (void)agentDeviceTextEntryDidChange:(UITextField *)textField {
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-disappear-after-input"] &&
+      textField.text.length > 0) {
+    [textField removeFromSuperview];
+  }
+}
+
 - (void)viewDidLoad {
   [super viewDidLoad];
 
@@ -78,6 +85,27 @@ int main(int argc, const char *argv[]) {
     [label.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
     [label.centerYAnchor constraintEqualToAnchor:self.view.centerYAnchor],
   ]];
+
+  // Keep the fixture behind a launch argument so normal runner snapshots remain unchanged.
+#if TARGET_OS_IOS
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-regression"]) {
+    UITextField *textField = [[UITextField alloc] init];
+    textField.accessibilityIdentifier = @"agent-device-hardware-keyboard-input";
+    textField.borderStyle = UITextBorderStyleRoundedRect;
+    textField.inputView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 1, 1)];
+    [textField addTarget:self
+                  action:@selector(agentDeviceTextEntryDidChange:)
+        forControlEvents:UIControlEventEditingChanged];
+    textField.translatesAutoresizingMaskIntoConstraints = NO;
+    [self.view addSubview:textField];
+    [NSLayoutConstraint activateConstraints:@[
+      [textField.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
+      [textField.topAnchor constraintEqualToAnchor:label.bottomAnchor constant:24],
+      [textField.widthAnchor constraintEqualToConstant:240],
+      [textField.heightAnchor constraintEqualToConstant:44],
+    ]];
+  }
+#endif
 }
 
 @end

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/AgentDeviceRunnerUITests-Bridging-Header.h

@@ -1,3 +1,4 @@
 #import "RunnerObjCExceptionCatcher.h"
 #import "RunnerAXSnapshotBridge.h"
 #import "RunnerSynthesizedGesture.h"
+#import "RunnerSynthesizedTextEntry.h"

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.h

@@ -3,14 +3,54 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/// Keys of the `deepExtension` dictionary in the snapshot response, shared
+/// with the Swift consumer so the response shape has one spelling.
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionCallsKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionNodesAddedKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionPendingKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionMissedKey;
+
+/// A depth-capped childless node awaiting an element-rooted follow-up request.
+/// Public so the runner unit bundle can drive the extension's miss paths with
+/// fabricated snapshots — the executed contract that missed frontiers are
+/// counted, never silently dropped.
+@interface RunnerAXSnapshotFrontier : NSObject
+@property(nonatomic, strong, nullable) id snapshot;
+@property(nonatomic, strong, nullable) NSMutableDictionary *node;
+@property(nonatomic, assign) NSInteger depth;
+@end
+
 @interface RunnerAXSnapshotBridge : NSObject
 
+/// Captures the app's accessibility tree, then chains element-rooted follow-up
+/// requests from depth-capped frontier nodes (the AX depth limit is
+/// per-request, so re-rooting reaches content the app-rooted request could
+/// not). The response gains a `deepExtension` {calls, nodesAdded,
+/// pendingFrontiers, missedFrontiers} dictionary when any frontier existed and
+/// the call limit allowed extension. Pass 0 to disable extension entirely.
 + (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
                                                     maxDepth:(NSInteger)maxDepth
-                                                    maxNodes:(NSInteger)maxNodes;
+                                                    maxNodes:(NSInteger)maxNodes
+                                      deepExtensionCallLimit:(NSInteger)deepExtensionCallLimit
+                                                    deadline:(nullable NSDate *)deadline;
 
 + (NSInteger)processIdentifierForApplication:(XCUIApplication *)application;
 
+/// The frontier-extension loop, exposed for the runner unit bundle: a frontier
+/// whose element vanished or whose re-rooted request fails must count as
+/// missed (see the deepExtension keys above) — an all-miss extension reporting
+/// itself drained would present a capped capture as complete.
++ (nullable NSDictionary *)extendSnapshotFrontiers:(NSMutableArray<RunnerAXSnapshotFrontier *> *)frontiers
+                                          axClient:(id)axClient
+                                        attributes:(NSArray *)attributes
+                                          maxDepth:(NSInteger)maxDepth
+                                          maxNodes:(NSInteger)maxNodes
+                                         nodeCount:(NSInteger *)nodeCount
+                                         truncated:(BOOL *)truncated
+                                      callsAllowed:(NSInteger)callsAllowed
+                                          deadline:(nullable NSDate *)deadline;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.m

@@ -8,15 +8,32 @@ static NSString *const RunnerAXSnapshotErrorKey = @"error";
 static NSString *const RunnerAXSnapshotRootKey = @"root";
 static NSString *const RunnerAXSnapshotTruncatedKey = @"truncated";
 
+NSString *const RunnerAXSnapshotDeepExtensionKey = @"deepExtension";
+NSString *const RunnerAXSnapshotDeepExtensionCallsKey = @"calls";
+NSString *const RunnerAXSnapshotDeepExtensionNodesAddedKey = @"nodesAdded";
+NSString *const RunnerAXSnapshotDeepExtensionPendingKey = @"pendingFrontiers";
+NSString *const RunnerAXSnapshotDeepExtensionMissedKey = @"missedFrontiers";
+
 typedef id (*RunnerAXObjectMsgSend)(id, SEL);
 typedef NSInteger (*RunnerAXIntegerMsgSend)(id, SEL);
 typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
 
+// A childless serialized node remembered with its depth (interface in the
+// header for the unit bundle). Nodes at the deepest observed level of a
+// depth-capped capture are the truncation frontier: the AX server withholds
+// children uniformly at its per-request cap, so every capped branch ends at
+// the same level (observed one BELOW the requested maxDepth — the server
+// counts node levels, not edges).
+@implementation RunnerAXSnapshotFrontier
+@end
+
 @implementation RunnerAXSnapshotBridge
 
 + (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
                                                     maxDepth:(NSInteger)maxDepth
                                                     maxNodes:(NSInteger)maxNodes
+                                      deepExtensionCallLimit:(NSInteger)deepExtensionCallLimit
+                                                    deadline:(nullable NSDate *)deadline
 {
   @try {
     id axClient = [self objectFrom:XCUIDevice.sharedDevice selectorName:@"accessibilityInterface"];
@@ -29,103 +46,277 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
       return [self failure:@"Could not match active AX application for XCTest application"];
     }
 
-    NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
-    id defaults = [self objectFrom:axClient selectorName:@"defaultParameters"];
-    if ([defaults isKindOfClass:NSDictionary.class]) {
-      [parameters addEntriesFromDictionary:(NSDictionary *)defaults];
-    }
-    parameters[@"maxDepth"] = @(MAX(0, maxDepth));
-    parameters[@"maxChildren"] = @(MAX(1, maxNodes));
-    parameters[@"maxArrayCount"] = @(MAX(1, maxNodes));
-    parameters[@"traverseFromParentsToChildren"] = @YES;
-
-    SEL requestSelector = NSSelectorFromString(@"requestSnapshotForElement:attributes:parameters:error:");
-    if (![axClient respondsToSelector:requestSelector]) {
-      return [self failure:@"AX client does not support requestSnapshotForElement"];
-    }
-
+    NSArray *attributes = [self snapshotAttributes];
     NSError *error = nil;
-    NSArray<NSString *> *keyPaths = @[
-      @"elementType",
-      @"identifier",
-      @"label",
-      @"value",
-      @"frame",
-      @"enabled",
-      @"selected",
-      @"hasFocus",
-      @"children",
-    ];
-    // The AX server expects real accessibility attribute identifiers, not snapshot keypath
-    // strings; passing raw keypaths silently drops attributes it does not recognize (frame
-    // came back zeroed). XCElementSnapshot owns the keypath -> AX attribute mapping.
-    NSArray *attributes = keyPaths;
-    Class snapshotClass = NSClassFromString(@"XCElementSnapshot");
-    SEL mapSelector = NSSelectorFromString(@"axAttributesForElementSnapshotKeyPaths:isMacOS:");
-    if ([snapshotClass respondsToSelector:mapSelector]) {
-      typedef id (*RunnerAXMapMsgSend)(id, SEL, id, BOOL);
-      RunnerAXMapMsgSend mapSend = (RunnerAXMapMsgSend)objc_msgSend;
-      id mapped = mapSend(snapshotClass, mapSelector, keyPaths, NO);
-      if ([mapped isKindOfClass:NSSet.class]) {
-        mapped = [(NSSet *)mapped allObjects];
-      }
-      if ([mapped isKindOfClass:NSArray.class] && [(NSArray *)mapped count] > 0) {
-        // The mapper expands keypaths with extra attributes (automation type, window display
-        // id, base type) that are disproportionately expensive for the AX server to compute
-        // on large React Native trees. Keep only the attributes we actually consume.
-        NSArray *needed = @[ @"ElementType", @"Identifier", @"Label", @"Value", @"Frame",
-                             @"Enabled", @"Selected", @"Focus" ];
-        NSMutableArray *filtered = [NSMutableArray array];
-        for (id attribute in (NSArray *)mapped) {
-          NSString *name = [attribute description];
-          for (NSString *suffix in needed) {
-            if ([name hasSuffix:suffix]) {
-              [filtered addObject:attribute];
-              break;
-            }
-          }
-        }
-        attributes = filtered.count > 0 ? filtered : mapped;
-      }
-    }
-    RunnerAXSnapshotMsgSend send = (RunnerAXSnapshotMsgSend)objc_msgSend;
-    id result = send(axClient, requestSelector, target, attributes, parameters.copy, &error);
-    if (nil == result) {
-      return [self failure:error.localizedDescription ?: @"AX snapshot request returned nil"];
-    }
-
-    id root = nil;
-    @try {
-      root = [result valueForKey:@"_rootElementSnapshot"];
-    } @catch (NSException *exception) {
-      root = nil;
-    }
+    id root = [self requestSnapshotFromClient:axClient
+                                      target:target
+                                  attributes:attributes
+                                    maxDepth:maxDepth
+                                    maxNodes:maxNodes
+                                       error:&error];
     if (nil == root) {
-      root = result;
+      return [self failure:error.localizedDescription ?: @"AX snapshot request returned nil"];
     }
 
     BOOL truncated = NO;
     NSInteger nodeCount = 0;
-    NSDictionary *rootNode = [self dictionaryForSnapshot:root
-                                                   depth:0
-                                                maxDepth:maxDepth
-                                                maxNodes:maxNodes
-                                               nodeCount:&nodeCount
-                                               truncated:&truncated];
+    // nil disables candidate collection entirely — exact --depth captures pay
+    // zero extension bookkeeping.
+    NSMutableArray<RunnerAXSnapshotFrontier *> *candidates =
+        deepExtensionCallLimit > 0 ? [NSMutableArray array] : nil;
+    NSMutableDictionary *rootNode = [self dictionaryForSnapshot:root
+                                                          depth:0
+                                                       maxDepth:maxDepth
+                                                       maxNodes:maxNodes
+                                                      nodeCount:&nodeCount
+                                                      truncated:&truncated
+                                                      frontiers:candidates];
     if (nil == rootNode) {
       return [self failure:@"AX snapshot root could not be serialized"];
     }
 
-    return @{
+    NSMutableArray<RunnerAXSnapshotFrontier *> *frontiers =
+        [self cappedFrontiersFromCandidates:candidates ?: @[] maxDepth:maxDepth];
+    NSDictionary *deepExtension = [self extendSnapshotFrontiers:frontiers
+                                                       axClient:axClient
+                                                     attributes:attributes
+                                                       maxDepth:maxDepth
+                                                       maxNodes:maxNodes
+                                                      nodeCount:&nodeCount
+                                                      truncated:&truncated
+                                                   callsAllowed:deepExtensionCallLimit
+                                                       deadline:deadline];
+
+    NSMutableDictionary *response = [NSMutableDictionary dictionaryWithDictionary:@{
       RunnerAXSnapshotOkKey: @YES,
       RunnerAXSnapshotRootKey: rootNode,
       RunnerAXSnapshotTruncatedKey: @(truncated),
-    };
+    }];
+    if (nil != deepExtension) {
+      response[RunnerAXSnapshotDeepExtensionKey] = deepExtension;
+    }
+    return response.copy;
   } @catch (NSException *exception) {
     return [self failure:exception.reason ?: exception.name ?: @"AX snapshot bridge exception"];
   }
 }
 
+/// Chains element-rooted snapshot requests from depth-capped frontier nodes.
+/// The AX server's depth limit is per-request (kAXErrorIllegalArgument above a
+/// tree-size-dependent value), so re-rooting the SAME request at a frontier
+/// node's live accessibility element reaches content the app-rooted request
+/// could not, without ever passing a larger depth parameter. Bounded by call
+/// count, the shared node budget, and the capture-plan deadline.
++ (nullable NSDictionary *)extendSnapshotFrontiers:(NSMutableArray<RunnerAXSnapshotFrontier *> *)frontiers
+                                          axClient:(id)axClient
+                                        attributes:(NSArray *)attributes
+                                          maxDepth:(NSInteger)maxDepth
+                                          maxNodes:(NSInteger)maxNodes
+                                         nodeCount:(NSInteger *)nodeCount
+                                         truncated:(BOOL *)truncated
+                                      callsAllowed:(NSInteger)callsAllowed
+                                          deadline:(nullable NSDate *)deadline
+{
+  if (callsAllowed <= 0 || frontiers.count == 0) {
+    return nil;
+  }
+  NSInteger callsUsed = 0;
+  NSInteger nodesAdded = 0;
+  // A frontier whose live element vanished (list churn between serialization
+  // and extension) or whose re-rooted request failed leaves its subtree
+  // unresolved — it must count as missed, never as drained, or an all-miss
+  // extension would present a capped capture as complete.
+  NSInteger missedFrontiers = 0;
+  while (frontiers.count > 0) {
+    if (callsUsed >= callsAllowed || *nodeCount >= maxNodes
+        || (nil != deadline && deadline.timeIntervalSinceNow <= 0)) {
+      *truncated = YES;
+      break;
+    }
+    RunnerAXSnapshotFrontier *frontier = frontiers.firstObject;
+    [frontiers removeObjectAtIndex:0];
+    id element = [self accessibilityElementForSnapshot:frontier.snapshot];
+    if (nil == element) {
+      missedFrontiers += 1;
+      NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_DEEP_EXTENSION_MISS=element unavailable");
+      continue;
+    }
+    callsUsed += 1;
+    NSError *error = nil;
+    id subRoot = [self requestSnapshotFromClient:axClient
+                                          target:element
+                                      attributes:attributes
+                                        maxDepth:maxDepth
+                                        maxNodes:maxNodes - *nodeCount
+                                           error:&error];
+    if (nil == subRoot) {
+      missedFrontiers += 1;
+      NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_DEEP_EXTENSION_MISS=%@",
+            error.localizedDescription ?: @"nil subtree");
+      continue;
+    }
+    // The re-rooted snapshot's root IS the frontier element captured again;
+    // splice only its children so the frontier node is not duplicated.
+    NSInteger before = *nodeCount;
+    NSMutableArray<RunnerAXSnapshotFrontier *> *subCandidates = [NSMutableArray array];
+    NSMutableArray *children = [NSMutableArray array];
+    for (id child in [self childrenForSnapshot:subRoot]) {
+      NSMutableDictionary *childNode = [self dictionaryForSnapshot:child
+                                                             depth:1
+                                                          maxDepth:maxDepth
+                                                          maxNodes:maxNodes
+                                                         nodeCount:nodeCount
+                                                         truncated:truncated
+                                                         frontiers:subCandidates];
+      if (nil != childNode) {
+        [children addObject:childNode];
+      }
+      if (*nodeCount >= maxNodes) {
+        *truncated = YES;
+        break;
+      }
+    }
+    frontier.node[@"children"] = children;
+    nodesAdded += *nodeCount - before;
+    [frontiers addObjectsFromArray:[self cappedFrontiersFromCandidates:subCandidates
+                                                              maxDepth:maxDepth]];
+  }
+  NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_DEEP_EXTENSION calls=%ld nodes=%ld pending=%ld missed=%ld",
+        (long)callsUsed, (long)nodesAdded, (long)frontiers.count, (long)missedFrontiers);
+  return @{
+    RunnerAXSnapshotDeepExtensionCallsKey: @(callsUsed),
+    RunnerAXSnapshotDeepExtensionNodesAddedKey: @(nodesAdded),
+    RunnerAXSnapshotDeepExtensionPendingKey: @(frontiers.count),
+    RunnerAXSnapshotDeepExtensionMissedKey: @(missedFrontiers),
+  };
+}
+
+/// Keeps only candidates at the deepest observed level, and only when that
+/// level sits at the request's cap (the server emits maxDepth node LEVELS, so
+/// the deepest possible level is maxDepth - 1). A tree that ended naturally
+/// above the cap yields no frontiers and costs nothing.
++ (NSMutableArray<RunnerAXSnapshotFrontier *> *)cappedFrontiersFromCandidates:
+    (NSArray<RunnerAXSnapshotFrontier *> *)candidates
+                                                                      maxDepth:(NSInteger)maxDepth
+{
+  NSMutableArray<RunnerAXSnapshotFrontier *> *frontiers = [NSMutableArray array];
+  NSInteger deepest = -1;
+  for (RunnerAXSnapshotFrontier *candidate in candidates) {
+    deepest = MAX(deepest, candidate.depth);
+  }
+  if (deepest < maxDepth - 1) {
+    return frontiers;
+  }
+  for (RunnerAXSnapshotFrontier *candidate in candidates) {
+    if (candidate.depth == deepest) {
+      [frontiers addObject:candidate];
+    }
+  }
+  return frontiers;
+}
+
++ (nullable id)requestSnapshotFromClient:(id)axClient
+                                  target:(id)target
+                              attributes:(NSArray *)attributes
+                                maxDepth:(NSInteger)maxDepth
+                                maxNodes:(NSInteger)maxNodes
+                                   error:(NSError **)error
+{
+  SEL requestSelector = NSSelectorFromString(@"requestSnapshotForElement:attributes:parameters:error:");
+  if (![axClient respondsToSelector:requestSelector]) {
+    if (NULL != error) {
+      *error = [NSError errorWithDomain:@"agent-device.runner"
+                                   code:1
+                               userInfo:@{
+                                 NSLocalizedDescriptionKey:
+                                     @"AX client does not support requestSnapshotForElement"
+                               }];
+    }
+    return nil;
+  }
+  NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
+  id defaults = [self objectFrom:axClient selectorName:@"defaultParameters"];
+  if ([defaults isKindOfClass:NSDictionary.class]) {
+    [parameters addEntriesFromDictionary:(NSDictionary *)defaults];
+  }
+  parameters[@"maxDepth"] = @(MAX(0, maxDepth));
+  parameters[@"maxChildren"] = @(MAX(1, maxNodes));
+  parameters[@"maxArrayCount"] = @(MAX(1, maxNodes));
+  parameters[@"traverseFromParentsToChildren"] = @YES;
+
+  RunnerAXSnapshotMsgSend send = (RunnerAXSnapshotMsgSend)objc_msgSend;
+  id result = send(axClient, requestSelector, target, attributes, parameters.copy, error);
+  if (nil == result) {
+    return nil;
+  }
+  id root = nil;
+  @try {
+    root = [result valueForKey:@"_rootElementSnapshot"];
+  } @catch (NSException *exception) {
+    root = nil;
+  }
+  return root ?: result;
+}
+
++ (NSArray *)snapshotAttributes
+{
+  NSArray<NSString *> *keyPaths = @[
+    @"elementType",
+    @"identifier",
+    @"label",
+    @"value",
+    @"frame",
+    @"enabled",
+    @"selected",
+    @"hasFocus",
+    @"children",
+  ];
+  // The AX server expects real accessibility attribute identifiers, not snapshot keypath
+  // strings; passing raw keypaths silently drops attributes it does not recognize (frame
+  // came back zeroed). XCElementSnapshot owns the keypath -> AX attribute mapping.
+  NSArray *attributes = keyPaths;
+  Class snapshotClass = NSClassFromString(@"XCElementSnapshot");
+  SEL mapSelector = NSSelectorFromString(@"axAttributesForElementSnapshotKeyPaths:isMacOS:");
+  if ([snapshotClass respondsToSelector:mapSelector]) {
+    typedef id (*RunnerAXMapMsgSend)(id, SEL, id, BOOL);
+    RunnerAXMapMsgSend mapSend = (RunnerAXMapMsgSend)objc_msgSend;
+    id mapped = mapSend(snapshotClass, mapSelector, keyPaths, NO);
+    if ([mapped isKindOfClass:NSSet.class]) {
+      mapped = [(NSSet *)mapped allObjects];
+    }
+    if ([mapped isKindOfClass:NSArray.class] && [(NSArray *)mapped count] > 0) {
+      // The mapper expands keypaths with extra attributes (automation type, window display
+      // id, base type) that are disproportionately expensive for the AX server to compute
+      // on large React Native trees. Keep only the attributes we actually consume.
+      NSArray *needed = @[ @"ElementType", @"Identifier", @"Label", @"Value", @"Frame",
+                           @"Enabled", @"Selected", @"Focus" ];
+      NSMutableArray *filtered = [NSMutableArray array];
+      for (id attribute in (NSArray *)mapped) {
+        NSString *name = [attribute description];
+        for (NSString *suffix in needed) {
+          if ([name hasSuffix:suffix]) {
+            [filtered addObject:attribute];
+            break;
+          }
+        }
+      }
+      attributes = filtered.count > 0 ? filtered : mapped;
+    }
+  }
+  return attributes;
+}
+
++ (nullable id)accessibilityElementForSnapshot:(id)snapshot
+{
+  id element = nil;
+  @try {
+    element = [snapshot valueForKey:@"accessibilityElement"];
+  } @catch (NSException *exception) {
+    element = nil;
+  }
+  return element;
+}
+
 + (NSDictionary<NSString *, id> *)failure:(NSString *)message
 {
   return @{
@@ -186,12 +377,13 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
   return nil;
 }
 
-+ (nullable NSDictionary *)dictionaryForSnapshot:(id)snapshot
-                                           depth:(NSInteger)depth
-                                        maxDepth:(NSInteger)maxDepth
-                                        maxNodes:(NSInteger)maxNodes
-                                       nodeCount:(NSInteger *)nodeCount
-                                       truncated:(BOOL *)truncated
++ (nullable NSMutableDictionary *)dictionaryForSnapshot:(id)snapshot
+                                                  depth:(NSInteger)depth
+                                               maxDepth:(NSInteger)maxDepth
+                                               maxNodes:(NSInteger)maxNodes
+                                              nodeCount:(NSInteger *)nodeCount
+                                              truncated:(BOOL *)truncated
+                                              frontiers:(NSMutableArray<RunnerAXSnapshotFrontier *> *)frontiers
 {
   if (nil == snapshot || *nodeCount >= maxNodes) {
     *truncated = YES;
@@ -212,12 +404,13 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
   NSMutableArray *children = [NSMutableArray array];
   if (depth < maxDepth) {
     for (id child in [self childrenForSnapshot:snapshot]) {
-      NSDictionary *childNode = [self dictionaryForSnapshot:child
-                                                      depth:depth + 1
-                                                   maxDepth:maxDepth
-                                                   maxNodes:maxNodes
-                                                  nodeCount:nodeCount
-                                                  truncated:truncated];
+      NSMutableDictionary *childNode = [self dictionaryForSnapshot:child
+                                                             depth:depth + 1
+                                                          maxDepth:maxDepth
+                                                          maxNodes:maxNodes
+                                                         nodeCount:nodeCount
+                                                         truncated:truncated
+                                                         frontiers:frontiers];
       if (nil != childNode) {
         [children addObject:childNode];
       }
@@ -227,8 +420,21 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
       }
     }
   }
+  if (children.count == 0 && nil != frontiers && depth >= maxDepth - 1) {
+    // Childless node at the cap boundary: either a real leaf or a branch whose
+    // children the AX server withheld. The two are indistinguishable here, so
+    // boundary childless nodes become candidates; the caller keeps only the
+    // deepest observed level, where every capped branch necessarily ends.
+    // Shallower childless nodes are provably real leaves and are never
+    // collected.
+    RunnerAXSnapshotFrontier *frontier = [[RunnerAXSnapshotFrontier alloc] init];
+    frontier.snapshot = snapshot;
+    frontier.node = result;
+    frontier.depth = depth;
+    [frontiers addObject:frontier];
+  }
   result[@"children"] = children;
-  return result.copy;
+  return result;
 }
 
 + (NSArray *)childrenForSnapshot:(id)snapshot