@devicelab/maestro-runner-darwin-arm64 1.1.25 → 1.1.28

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerAXSnapshotBridge.m

@@ -0,0 +1,439 @@
+#import "RunnerAXSnapshotBridge.h"
+
+#import <CoreGraphics/CoreGraphics.h>
+#import <objc/message.h>
+
+// A childless serialized node remembered with its depth. 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 (one BELOW the requested maxDepth — the server
+// counts node levels, not edges).
+@interface RunnerAXFrontier : NSObject
+@property(nonatomic, strong, nullable) id snapshot;
+@property(nonatomic, strong, nullable) NSMutableDictionary *node;
+@property(nonatomic, assign) NSInteger depth;
+@end
+
+@implementation RunnerAXFrontier
+@end
+
+typedef id (*RunnerAXObjMsgSend)(id, SEL);
+typedef id (*RunnerAXSnapMsgSend)(id, SEL, id, id, id, NSError **);
+
+@implementation RunnerAXSnapshotBridge
+
++ (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
+                                                    maxDepth:(NSInteger)maxDepth
+                                                    maxNodes:(NSInteger)maxNodes
+                                      deepExtensionCallLimit:(NSInteger)deepExtensionCallLimit
+                                                     timeout:(NSTimeInterval)timeout {
+  @try {
+    id axClient = [self accessibilityClient];
+    if (nil == axClient) {
+      return [self failure:@"XCUIDevice accessibilityInterface is unavailable"];
+    }
+    id target = [self accessibilityApplicationForApplication:application axClient:axClient];
+    if (nil == target) {
+      return [self failure:@"Could not match active AX application for XCTest application"];
+    }
+
+    NSDate *deadline = timeout > 0 ? [NSDate dateWithTimeIntervalSinceNow:timeout] : nil;
+    NSArray *attributes = [self snapshotAttributes];
+    NSError *error = nil;
+    id root = [self requestSnapshotFromClient:axClient
+                                       target:target
+                                   attributes:attributes
+                                     maxDepth:maxDepth
+                                     maxNodes:maxNodes
+                                        error:&error];
+    if (nil == root) {
+      return [self failure:error.localizedDescription ?: @"AX snapshot request returned nil"];
+    }
+
+    BOOL truncated = NO;
+    NSInteger nodeCount = 0;
+    NSMutableArray<RunnerAXFrontier *> *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"];
+    }
+
+    NSMutableArray<RunnerAXFrontier *> *frontiers =
+        [self cappedFrontiersFromCandidates:candidates ?: @[] maxDepth:maxDepth];
+    [self extendFrontiers:frontiers
+                 axClient:axClient
+               attributes:attributes
+                 maxDepth:maxDepth
+                 maxNodes:maxNodes
+                nodeCount:&nodeCount
+                truncated:&truncated
+             callsAllowed:deepExtensionCallLimit
+                 deadline:deadline];
+
+    return @{ @"ok": @YES, @"root": rootNode, @"truncated": @(truncated) };
+  } @catch (NSException *exception) {
+    return [self failure:exception.reason ?: exception.name ?: @"AX snapshot bridge exception"];
+  }
+}
+
+// Chains element-rooted snapshot requests from depth-capped frontier nodes.
++ (void)extendFrontiers:(NSMutableArray<RunnerAXFrontier *> *)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;
+  }
+  NSInteger callsUsed = 0;
+  while (frontiers.count > 0) {
+    if (callsUsed >= callsAllowed || *nodeCount >= maxNodes ||
+        (nil != deadline && deadline.timeIntervalSinceNow <= 0)) {
+      *truncated = YES;
+      break;
+    }
+    RunnerAXFrontier *frontier = frontiers.firstObject;
+    [frontiers removeObjectAtIndex:0];
+    id element = [self accessibilityElementForSnapshot:frontier.snapshot];
+    if (nil == element) {
+      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) {
+      continue;
+    }
+    // The re-rooted snapshot's root IS the frontier element captured again;
+    // splice only its children so the frontier node is not duplicated.
+    NSMutableArray<RunnerAXFrontier *> *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;
+    [frontiers addObjectsFromArray:[self cappedFrontiersFromCandidates:subCandidates
+                                                              maxDepth:maxDepth]];
+  }
+}
+
+// Keeps only candidates at the deepest observed level, and only when that level
+// sits at the request's cap (server emits maxDepth node LEVELS, deepest is
+// maxDepth - 1). A tree that ended naturally above the cap costs nothing.
++ (NSMutableArray<RunnerAXFrontier *> *)cappedFrontiersFromCandidates:
+                                            (NSArray<RunnerAXFrontier *> *)candidates
+                                                            maxDepth:(NSInteger)maxDepth {
+  NSMutableArray<RunnerAXFrontier *> *frontiers = [NSMutableArray array];
+  NSInteger deepest = -1;
+  for (RunnerAXFrontier *candidate in candidates) {
+    deepest = MAX(deepest, candidate.depth);
+  }
+  if (deepest < maxDepth - 1) {
+    return frontiers;
+  }
+  for (RunnerAXFrontier *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:@"devicelab.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;
+
+  RunnerAXSnapMsgSend send = (RunnerAXSnapMsgSend)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 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 on large RN trees. Keep only what we 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 NSMutableDictionary *)dictionaryForSnapshot:(id)snapshot
+                                                  depth:(NSInteger)depth
+                                               maxDepth:(NSInteger)maxDepth
+                                               maxNodes:(NSInteger)maxNodes
+                                              nodeCount:(NSInteger *)nodeCount
+                                              truncated:(BOOL *)truncated
+                                              frontiers:
+                                                  (nullable NSMutableArray<RunnerAXFrontier *> *)
+                                                      frontiers {
+  if (nil == snapshot || *nodeCount >= maxNodes) {
+    *truncated = YES;
+    return nil;
+  }
+  *nodeCount += 1;
+  NSMutableDictionary *result = [NSMutableDictionary dictionary];
+  result[@"type"] = [self numberValueForKey:@"elementType" snapshot:snapshot] ?: @0;
+  result[@"identifier"] = [self stringValueForKey:@"identifier" snapshot:snapshot] ?: @"";
+  result[@"label"] = [self stringValueForKey:@"label" snapshot:snapshot] ?: @"";
+  result[@"value"] = [self stringValueForKey:@"value" snapshot:snapshot] ?: @"";
+  result[@"frame"] = [self frameValueForSnapshot:snapshot];
+  result[@"enabled"] = [self boolNumberForKey:@"enabled" snapshot:snapshot defaultValue:YES];
+  result[@"selected"] = [self boolNumberForKey:@"selected" snapshot:snapshot defaultValue:NO];
+  result[@"focused"] = [self boolNumberForKey:@"hasFocus" snapshot:snapshot defaultValue:NO];
+
+  NSMutableArray *children = [NSMutableArray array];
+  if (depth < maxDepth) {
+    for (id child in [self childrenForSnapshot:snapshot]) {
+      NSMutableDictionary *childNode = [self dictionaryForSnapshot:child
+                                                             depth:depth + 1
+                                                          maxDepth:maxDepth
+                                                          maxNodes:maxNodes
+                                                         nodeCount:nodeCount
+                                                         truncated:truncated
+                                                         frontiers:frontiers];
+      if (nil != childNode) {
+        [children addObject:childNode];
+      }
+      if (*nodeCount >= maxNodes) {
+        *truncated = YES;
+        break;
+      }
+    }
+  }
+  if (children.count == 0 && nil != frontiers && depth >= maxDepth - 1) {
+    // Childless node at the cap boundary: real leaf or a branch whose children
+    // the AX server withheld. Indistinguishable here, so boundary childless
+    // nodes become candidates; the caller keeps only the deepest observed level.
+    RunnerAXFrontier *frontier = [[RunnerAXFrontier alloc] init];
+    frontier.snapshot = snapshot;
+    frontier.node = result;
+    frontier.depth = depth;
+    [frontiers addObject:frontier];
+  }
+  result[@"children"] = children;
+  return result;
+}
+
++ (NSArray *)childrenForSnapshot:(id)snapshot {
+  id children = nil;
+  @try {
+    children = [snapshot valueForKey:@"children"];
+  } @catch (NSException *exception) {
+    children = nil;
+  }
+  return [children isKindOfClass:NSArray.class] ? children : @[];
+}
+
++ (nullable id)accessibilityClient {
+  return [self objectFrom:XCUIDevice.sharedDevice selectorName:@"accessibilityInterface"];
+}
+
++ (nullable id)accessibilityElementForSnapshot:(id)snapshot {
+  id element = nil;
+  @try {
+    element = [snapshot valueForKey:@"accessibilityElement"];
+  } @catch (NSException *exception) {
+    element = nil;
+  }
+  return element;
+}
+
++ (id)accessibilityApplicationForApplication:(XCUIApplication *)application axClient:(id)axClient {
+  NSInteger targetProcessID = [self integerFrom:application selectorName:@"processID"];
+  id activeApplications = [self objectFrom:axClient selectorName:@"activeApplications"];
+  if (![activeApplications isKindOfClass:NSArray.class]) {
+    return nil;
+  }
+  for (id candidate in (NSArray *)activeApplications) {
+    NSInteger candidateProcessID =
+        [self integerFrom:candidate selectorName:@"processIdentifier"];
+    if (targetProcessID > 0 && candidateProcessID == targetProcessID) {
+      return candidate;
+    }
+  }
+  return nil;
+}
+
++ (NSDictionary<NSString *, id> *)failure:(NSString *)message {
+  return @{ @"ok": @NO, @"error": message ?: @"unknown error" };
+}
+
++ (nullable id)objectFrom:(id)target selectorName:(NSString *)selectorName {
+  SEL selector = NSSelectorFromString(selectorName);
+  if (![target respondsToSelector:selector]) {
+    return nil;
+  }
+  RunnerAXObjMsgSend send = (RunnerAXObjMsgSend)objc_msgSend;
+  return send(target, selector);
+}
+
++ (NSInteger)integerFrom:(id)target selectorName:(NSString *)selectorName {
+  SEL selector = NSSelectorFromString(selectorName);
+  if (![target respondsToSelector:selector]) {
+    return 0;
+  }
+  // processID/processIdentifier return pid_t (int32); reading through an
+  // NSInteger cast is not upper-32-bit safe on arm64. Pick by return type.
+  NSMethodSignature *signature = [target methodSignatureForSelector:selector];
+  const char *returnType = signature.methodReturnType;
+  if (returnType != NULL && strcmp(returnType, @encode(int)) == 0) {
+    typedef int (*RunnerAXIntMsgSend)(id, SEL);
+    RunnerAXIntMsgSend send = (RunnerAXIntMsgSend)objc_msgSend;
+    return (NSInteger)send(target, selector);
+  }
+  typedef NSInteger (*RunnerAXNSIntMsgSend)(id, SEL);
+  RunnerAXNSIntMsgSend send = (RunnerAXNSIntMsgSend)objc_msgSend;
+  return send(target, selector);
+}
+
++ (nullable NSNumber *)numberValueForKey:(NSString *)key snapshot:(id)snapshot {
+  id value = nil;
+  @try {
+    value = [snapshot valueForKey:key];
+  } @catch (NSException *exception) {
+    return nil;
+  }
+  return [value isKindOfClass:NSNumber.class] ? value : nil;
+}
+
++ (nullable NSString *)stringValueForKey:(NSString *)key snapshot:(id)snapshot {
+  id value = nil;
+  @try {
+    value = [snapshot valueForKey:key];
+  } @catch (NSException *exception) {
+    return nil;
+  }
+  if (nil == value || value == NSNull.null) {
+    return nil;
+  }
+  if ([value isKindOfClass:NSString.class]) {
+    return [(NSString *)value
+        stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet];
+  }
+  return [[value description]
+      stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet];
+}
+
++ (NSNumber *)boolNumberForKey:(NSString *)key snapshot:(id)snapshot defaultValue:(BOOL)defaultValue {
+  NSNumber *value = [self numberValueForKey:key snapshot:snapshot];
+  return nil == value ? @(defaultValue) : @([value boolValue]);
+}
+
++ (NSDictionary *)frameValueForSnapshot:(id)snapshot {
+  CGRect frame = CGRectZero;
+  @try {
+    id value = [snapshot valueForKey:@"frame"];
+    if ([value isKindOfClass:NSValue.class] &&
+        strcmp([(NSValue *)value objCType], @encode(CGRect)) == 0) {
+      [(NSValue *)value getValue:&frame];
+    }
+  } @catch (NSException *exception) {
+    frame = CGRectZero;
+  }
+  if (CGRectIsNull(frame) || CGRectIsInfinite(frame)) {
+    frame = CGRectZero;
+  }
+  return @{
+    @"x": @(CGRectGetMinX(frame)),
+    @"y": @(CGRectGetMinY(frame)),
+    @"width": @(CGRectGetWidth(frame)),
+    @"height": @(CGRectGetHeight(frame)),
+  };
+}
+
+@end

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerDefaults.h

@@ -0,0 +1,12 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Applies WDA's runner-process defaults once, before any test runs:
+/// XCTest screenshots and diagnostic screen recordings off, local query
+/// evaluation, keyboard autocorrect/prediction off with intros dismissed,
+/// and XCTest's UI-interruption handling off. Set DL_KEEP_XCTEST_DEFAULTS=1
+/// in the runner environment to skip it.
+void DLApplyRunnerDefaults(void);
+
+NS_ASSUME_NONNULL_END

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerDefaults.m

@@ -0,0 +1,59 @@
+#import "RunnerDefaults.h"
+#import <XCTest/XCTest.h>
+#import <dlfcn.h>
+#import <objc/runtime.h>
+
+// Keyboard preferences live in the private TextInput framework, reached the
+// way WDA does (FBConfiguration configureDefaultKeyboardPreferences).
+static void DLConfigureKeyboardPreferences(void)
+{
+  void *handle = dlopen("/System/Library/PrivateFrameworks/TextInput.framework/TextInput", RTLD_LAZY);
+  Class controllerClass = NSClassFromString(@"TIPreferencesController");
+  SEL shared = NSSelectorFromString(@"sharedPreferencesController");
+  id controller = [controllerClass respondsToSelector:shared]
+    ? ((id (*)(id, SEL))[controllerClass methodForSelector:shared])(controllerClass, shared)
+    : nil;
+  SEL setPref = NSSelectorFromString(@"setValue:forPreferenceKey:");
+  if (controller != nil && [controller respondsToSelector:setPref]) {
+    void (*set)(id, SEL, id, NSString *) = (void (*)(id, SEL, id, NSString *))[controller methodForSelector:setPref];
+    set(controller, setPref, @NO, @"KeyboardAutocorrection");
+    set(controller, setPref, @NO, @"KeyboardPrediction");
+    set(controller, setPref, @YES, @"DidShowGestureKeyboardIntroduction");
+    set(controller, setPref, @YES, @"DidShowContinuousPathIntroduction");
+    SEL sync = NSSelectorFromString(@"synchronizePreferences");
+    if ([controller respondsToSelector:sync]) {
+      ((void (*)(id, SEL))[controller methodForSelector:sync])(controller, sync);
+    }
+  }
+  if (handle != NULL) {
+    dlclose(handle);
+  }
+}
+
+// XCTest's own interruption handling taps "Allow"/"OK" on system alerts at
+// moments of its choosing; the runner handles alerts itself (WDA does the
+// same: XCUIApplication+FBUIInterruptions).
+static void DLDisableUIInterruptionsHandling(void)
+{
+  Method m = class_getInstanceMethod(XCUIApplication.class, NSSelectorFromString(@"doesNotHandleUIInterruptions"));
+  if (m != NULL) {
+    method_setImplementation(m, imp_implementationWithBlock(^BOOL(__unused id app) { return YES; }));
+  }
+}
+
+void DLApplyRunnerDefaults(void)
+{
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    if (NSProcessInfo.processInfo.environment[@"DL_KEEP_XCTEST_DEFAULTS"] != nil) {
+      return;
+    }
+    NSUserDefaults *defaults = NSUserDefaults.standardUserDefaults;
+    [defaults setBool:YES forKey:@"DisableScreenshots"];
+    [defaults setBool:YES forKey:@"DisableDiagnosticScreenRecordings"];
+    [defaults setBool:YES forKey:@"XCTDisableRemoteQueryEvaluation"];
+    DLConfigureKeyboardPreferences();
+    DLDisableUIInterruptionsHandling();
+    NSLog(@"DL_RUNNER_DEFAULTS applied");
+  });
+}

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerTests+AXSnapshotFallback.swift

@@ -0,0 +1,128 @@
+import XCTest
+
+extension RunnerTests {
+  // Per-request depth cap. Kept moderate on purpose: the AX server rejects a
+  // bulk request outright (kAXErrorIllegalArgument) once depth crosses a
+  // tree-size-dependent limit, and frontier re-rooting reaches deeper content
+  // without ever passing a larger depth. 20 clears every React Navigation
+  // screen measured; deeper subtrees arrive through re-rooting.
+  private static let privateAXMaxDepth = 20
+  // Whole-capture node budget. Higher than the public path's fastSnapshotLimit
+  // because the point of this path is completeness on a screen the public
+  // serializer could not deliver at all.
+  private static let privateAXMaxNodes = 4000
+  // Re-root requests per capture. A depth-capped RN tree resolves in 1-3 chained
+  // requests; the bound stops a pathological tree from stacking requests.
+  private static let privateAXDeepExtensionCallLimit = 12
+  // Whole-capture wall-clock bound, seconds. A responsive capture is ~100-400ms;
+  // this only contains an unresponsive app.
+  private static let privateAXTimeout: TimeInterval = 4.0
+
+  /// Snapshot via the private AX client, used when the public
+  /// `XCUIElement.snapshot()` path threw or returned a childless root on a deep
+  /// React Native tree. Returns nil when the bridge is unavailable or the
+  /// capture failed, so the caller keeps its existing (empty) result.
+  func privateAXFallbackPayload(app: XCUIApplication, options: SnapshotOptions) -> DataPayload? {
+    // The bridge's timeout only stops it starting new requests. Each request
+    // also gets a bound here, or one sent to an app that leaves the screen
+    // mid-capture waits out XCTest's 60s AX timeout.
+    var response: [String: Any] = [:]
+    RunnerXCTestTimeouts.withAXTimeout(RunnerTests.privateAXTimeout) {
+      response = RunnerAXSnapshotBridge.snapshotTree(
+        for: app,
+        maxDepth: RunnerTests.privateAXMaxDepth,
+        maxNodes: RunnerTests.privateAXMaxNodes,
+        deepExtensionCallLimit: RunnerTests.privateAXDeepExtensionCallLimit,
+        timeout: RunnerTests.privateAXTimeout
+      )
+    }
+    guard (response["ok"] as? Bool) == true,
+          let rootDict = response["root"] as? [String: Any] else {
+      if let error = response["error"] as? String {
+        NSLog("DL_PRIVATE_AX_FALLBACK: unavailable (%@)", error)
+      }
+      return nil
+    }
+
+    let viewport = axFrame(from: rootDict["frame"])
+    var nodes: [SnapshotNode] = []
+    let depthLimit = options.depth ?? Int.max
+    appendAXNode(rootDict, depth: 0, parentIndex: nil, viewport: viewport,
+                 depthLimit: depthLimit, into: &nodes)
+    let truncated = (response["truncated"] as? Bool) ?? false
+    NSLog("DL_PRIVATE_AX_FALLBACK: recovered %ld nodes (truncated=%d)",
+          nodes.count, truncated ? 1 : 0)
+    guard !nodes.isEmpty else { return nil }
+    return DataPayload(
+      nodes: nodes,
+      truncated: truncated,
+      appState: appStateString(app),
+      source: SnapshotSource.privateAX
+    )
+  }
+
+  /// Flattens the bridge's nested node dict into the flat, parent-indexed
+  /// SnapshotNode list the rest of the runner and the Go host expect.
+  private func appendAXNode(_ node: [String: Any], depth: Int, parentIndex: Int?,
+                            viewport: CGRect, depthLimit: Int, into nodes: inout [SnapshotNode]) {
+    if nodes.count >= RunnerTests.privateAXMaxNodes { return }
+    if depth > depthLimit { return }
+
+    let index = nodes.count
+    let typeRaw = (node["type"] as? NSNumber)?.uintValue ?? XCUIElement.ElementType.other.rawValue
+    let type = elementTypeName(XCUIElement.ElementType(rawValue: typeRaw) ?? .other)
+    let frame = axFrame(from: node["frame"])
+    let enabled = (node["enabled"] as? NSNumber)?.boolValue ?? true
+    // No occlusion pass here (a re-rooted tree has no reliable sibling order);
+    // hittable is the honest geometric answer: a real, enabled rect on screen.
+    let onScreen = !frame.isNull && !frame.isEmpty && frame.intersects(viewport)
+    let hittable = enabled && onScreen
+    let label = axString(node["label"])
+    let identifier = axString(node["identifier"])
+    let value = axString(node["value"])
+    let selected = (node["selected"] as? NSNumber)?.boolValue ?? false
+    let focused = (node["focused"] as? NSNumber)?.boolValue ?? false
+
+    nodes.append(
+      SnapshotNode(
+        index: index,
+        type: type,
+        label: label,
+        identifier: identifier,
+        value: value,
+        placeholderValue: nil,
+        rect: SnapshotRect(x: Double(frame.origin.x), y: Double(frame.origin.y),
+                           width: Double(frame.size.width), height: Double(frame.size.height)),
+        enabled: enabled,
+        focused: focused ? true : nil,
+        selected: selected ? true : nil,
+        hittable: hittable,
+        depth: depth,
+        parentIndex: parentIndex,
+        hiddenContentAbove: nil,
+        hiddenContentBelow: nil
+      )
+    )
+
+    guard let children = node["children"] as? [[String: Any]] else { return }
+    for child in children {
+      appendAXNode(child, depth: depth + 1, parentIndex: index, viewport: viewport,
+                   depthLimit: depthLimit, into: &nodes)
+      if nodes.count >= RunnerTests.privateAXMaxNodes { break }
+    }
+  }
+
+  private func axFrame(from value: Any?) -> CGRect {
+    guard let dict = value as? [String: Any] else { return .zero }
+    let x = (dict["x"] as? NSNumber)?.doubleValue ?? 0
+    let y = (dict["y"] as? NSNumber)?.doubleValue ?? 0
+    let w = (dict["width"] as? NSNumber)?.doubleValue ?? 0
+    let h = (dict["height"] as? NSNumber)?.doubleValue ?? 0
+    return CGRect(x: x, y: y, width: w, height: h)
+  }
+
+  private func axString(_ value: Any?) -> String? {
+    guard let s = value as? String, !s.isEmpty else { return nil }
+    return s
+  }
+}