agent-device 0.20.10 → 0.21.1

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift

@@ -1,4 +1,5 @@
 import XCTest
+import AgentDeviceSnapshotPresentation
 
 extension RunnerTests {
   private static let axSnapshotErrorCode = "IOS_AX_SNAPSHOT_FAILED"
@@ -15,78 +16,76 @@ extension RunnerTests {
     let queryRoot: XCUIElement
     let rootSnapshot: XCUIElementSnapshot
     let viewport: CGRect
-    let flatSnapshots: [XCUIElementSnapshot]
-    let snapshotRanges: [ObjectIdentifier: (Int, Int)]
-    let maxDepth: Int
   }
 
   private struct SnapshotEvaluation {
     let label: String
     let identifier: String
     let valueText: String?
-    let hittable: Bool
     let focused: Bool
     let selected: Bool
-    let visible: Bool
   }
 
   private struct SnapshotTraversalEntry {
     let snapshot: XCUIElementSnapshot
     let depth: Int
-    let visibleDepth: Int
     let parentIndex: Int?
-    let nearestScrollAnchor: (index: Int, rect: CGRect)?
-    let projectionCursor: FlatSnapshotProjectionCursor
+    let parentPresentedDepth: Int
+    let parentTraversal: SnapshotVisibilityFold.TraversalState
   }
 
   struct SnapshotCaptureFailure: Error {
     let code: String
     let message: String
     let hint: String
+    let qualityReasonCode: String?
+
+    init(code: String, message: String, hint: String, qualityReasonCode: String? = nil) {
+      self.code = code
+      self.message = message
+      self.hint = hint
+      self.qualityReasonCode = qualityReasonCode
+    }
   }
 
-  // MARK: - Snapshot Entry
+
+
+
+  static let elementTypeNamesByRawValue = [
+    XCUIElement.ElementType.application.rawValue: "Application",
+    XCUIElement.ElementType.window.rawValue: "Window",
+    XCUIElement.ElementType.button.rawValue: "Button",
+    XCUIElement.ElementType.cell.rawValue: "Cell",
+    XCUIElement.ElementType.staticText.rawValue: "StaticText",
+    XCUIElement.ElementType.textField.rawValue: "TextField",
+    XCUIElement.ElementType.textView.rawValue: "TextView",
+    XCUIElement.ElementType.secureTextField.rawValue: "SecureTextField",
+    XCUIElement.ElementType.switch.rawValue: "Switch",
+    XCUIElement.ElementType.slider.rawValue: "Slider",
+    XCUIElement.ElementType.link.rawValue: "Link",
+    XCUIElement.ElementType.image.rawValue: "Image",
+    XCUIElement.ElementType.navigationBar.rawValue: "NavigationBar",
+    XCUIElement.ElementType.tabBar.rawValue: "TabBar",
+    XCUIElement.ElementType.collectionView.rawValue: "CollectionView",
+    XCUIElement.ElementType.table.rawValue: "Table",
+    XCUIElement.ElementType.scrollView.rawValue: "ScrollView",
+    XCUIElement.ElementType.toolbar.rawValue: "Toolbar",
+    XCUIElement.ElementType.searchField.rawValue: "SearchField",
+    XCUIElement.ElementType.segmentedControl.rawValue: "SegmentedControl",
+    XCUIElement.ElementType.stepper.rawValue: "Stepper",
+    XCUIElement.ElementType.picker.rawValue: "Picker",
+    XCUIElement.ElementType.activityIndicator.rawValue: "ActivityIndicator",
+    XCUIElement.ElementType.progressIndicator.rawValue: "ProgressIndicator",
+    XCUIElement.ElementType.checkBox.rawValue: "CheckBox",
+    XCUIElement.ElementType.menuItem.rawValue: "MenuItem",
+    XCUIElement.ElementType.webView.rawValue: "WebView",
+    XCUIElement.ElementType.other.rawValue: "Other",
+    19: "Keyboard",
+    20: "Key"
+  ]
 
   func elementTypeName(_ type: XCUIElement.ElementType) -> String {
-    switch type {
-    case .application: return "Application"
-    case .window: return "Window"
-    case .button: return "Button"
-    case .cell: return "Cell"
-    case .staticText: return "StaticText"
-    case .textField: return "TextField"
-    case .textView: return "TextView"
-    case .secureTextField: return "SecureTextField"
-    case .switch: return "Switch"
-    case .slider: return "Slider"
-    case .link: return "Link"
-    case .image: return "Image"
-    case .navigationBar: return "NavigationBar"
-    case .tabBar: return "TabBar"
-    case .collectionView: return "CollectionView"
-    case .table: return "Table"
-    case .scrollView: return "ScrollView"
-    case .toolbar: return "Toolbar"
-    case .searchField: return "SearchField"
-    case .segmentedControl: return "SegmentedControl"
-    case .stepper: return "Stepper"
-    case .picker: return "Picker"
-    case .activityIndicator: return "ActivityIndicator"
-    case .progressIndicator: return "ProgressIndicator"
-    case .checkBox: return "CheckBox"
-    case .menuItem: return "MenuItem"
-    case .webView: return "WebView"
-    case .other: return "Other"
-    default:
-      switch type.rawValue {
-      case 19:
-        return "Keyboard"
-      case 20:
-        return "Key"
-      default:
-        return "Element(\(type.rawValue))"
-      }
-    }
+    Self.elementTypeNamesByRawValue[type.rawValue] ?? "Element(\(type.rawValue))"
   }
 
   static let structuralOnlyNodeTypes: Set<String> = [
@@ -112,11 +111,11 @@ extension RunnerTests {
 
   static let flatInteractiveFallbackBudget: TimeInterval = 1.0
 
-  // The single production entry point -- always compiled, no unit-test overload. A unit test
-  // exercises this exact function; the only injectable seam lives inside
-  // `boundedBlockingSystemAlertSnapshot`'s probe closure (see `systemModalProbeOverrideForTesting`
-  // in RunnerTests.swift), so reverting this entry point to bypass the bounded probe fails the
-  // regression test.
+
+
+
+
+
   func snapshotFast(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
     if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
@@ -133,7 +132,7 @@ extension RunnerTests {
 
   func recursiveTreeSnapshotAcquisition(
     context: SnapshotTraversalContext,
-    options: PresentationOptions
+    hint: CaptureHint
   ) -> SnapshotAcquisition {
     var cachedDescendantElements: [XCUIElement]?
     func collapsedTabDescendants() -> [XCUIElement] {
@@ -147,110 +146,68 @@ extension RunnerTests {
       return result.elements
     }
 
+
+
+
+
+
     var nodes: [RawAXNode] = []
-    var hiddenContentHintsByNodeIndex: [Int: (above: Bool, below: Bool)] = [:]
-    let rootEvaluation = evaluateSnapshot(context.rootSnapshot, in: context)
+    let rootEvaluation = evaluateSnapshot(context.rootSnapshot)
     nodes.append(
       makeSnapshotNode(
         snapshot: context.rootSnapshot,
         evaluation: rootEvaluation,
         depth: 0,
         index: 0,
-        parentIndex: nil
+        parentIndex: nil,
+        viewport: context.viewport
       )
     )
-    if context.maxDepth > 0 {
+    let shouldVisitRootChildren = SnapshotPresentation.shouldAcquireChildren(
+      for: hint,
+      rawDepth: 0,
+      regularPresentedDepth: 0
+    )
+    if shouldVisitRootChildren {
       appendCollapsedTabFallbackNodes(
         to: &nodes,
         containerSnapshot: context.rootSnapshot,
         resolveElements: collapsedTabDescendants,
         depth: 1,
-        parentIndex: 0
+        parentIndex: 0,
+        viewport: context.viewport
       )
     }
 
     var seen = Set<String>()
-    let rootScrollAnchor = scrollContainerAnchor(
-      for: context.rootSnapshot,
-      visible: rootEvaluation.visible,
-      nodeIndex: 0
-    )
-    #if os(iOS)
-      let rootProjection = flatSnapshotProjectionTransition(
-        frame: context.rootSnapshot.frame,
-        intersectsViewportAndScrollClip: rootEvaluation.visible,
-        elementType: context.rootSnapshot.elementType,
-        hasChildren: !context.rootSnapshot.children.isEmpty,
-        cursor: .root
-      )
-      let rootDescendantProjectionCursor = rootProjection.decision.descendants
-    #else
-      let rootDescendantProjectionCursor = FlatSnapshotProjectionCursor.root
-    #endif
-    var stack: [SnapshotTraversalEntry] = context.rootSnapshot.children.map {
-      SnapshotTraversalEntry(
-        snapshot: $0,
-        depth: 1,
-        visibleDepth: 1,
-        parentIndex: 0,
-        nearestScrollAnchor: rootScrollAnchor,
-        projectionCursor: rootDescendantProjectionCursor
-      )
+    var stack: [SnapshotTraversalEntry] = []
+    if shouldVisitRootChildren {
+      stack = context.rootSnapshot.children.map {
+        SnapshotTraversalEntry(
+          snapshot: $0,
+          depth: 1,
+          parentIndex: 0,
+          parentPresentedDepth: 0,
+          parentTraversal: .root
+        )
+      }
     }
 
     while let entry = stack.popLast() {
       let snapshot = entry.snapshot
       let depth = entry.depth
-      let visibleDepth = entry.visibleDepth
       let parentIndex = entry.parentIndex
-      let nearestScrollAnchor = entry.nearestScrollAnchor
-      let projectionCursor = entry.projectionCursor
-      if let limit = options.depth, depth > limit { continue }
+      if let limit = hint.rawTraversalDepth, depth > limit { continue }
 
-      let evaluation = evaluateSnapshot(snapshot, in: context)
-      let intersectsViewportAndScrollClip = isVisibleInRegularSnapshot(
-        snapshot.frame,
-        viewport: context.viewport,
-        scrollContainerAnchor: nearestScrollAnchor
-      )
-      #if os(iOS)
-        let projectionTransition = flatSnapshotProjectionTransition(
-          frame: snapshot.frame,
-          intersectsViewportAndScrollClip: intersectsViewportAndScrollClip,
-          elementType: snapshot.elementType,
-          hasChildren: !snapshot.children.isEmpty,
-          cursor: projectionCursor
-        )
-        let projection = projectionTransition.decision
-      #else
-        let projectionTransition = FlatSnapshotProjectionTransition(
-          decision: FlatSnapshotProjectionDecision(
-            presentationVisible: intersectsViewportAndScrollClip,
-            descendants: .root
-          ),
-          hiddenContentFrame: !intersectsViewportAndScrollClip ? snapshot.frame : nil
-        )
-        let projection = projectionTransition.decision
-      #endif
-      if let hiddenFrame = projectionTransition.hiddenContentFrame, let nearestScrollAnchor
-      {
-        rememberHiddenContentHint(
-          for: hiddenFrame,
-          relativeTo: nearestScrollAnchor,
-          hints: &hiddenContentHintsByNodeIndex
-        )
-      }
-      let include = shouldAcquireSnapshotNode(
+      let evaluation = evaluateSnapshot(snapshot)
+      let node = makeSnapshotNode(
         snapshot: snapshot,
-        label: evaluation.label,
-        identifier: evaluation.identifier,
-        valueText: evaluation.valueText,
-        options: options,
-        hittable: evaluation.hittable,
-        visible: projection.presentationVisible,
-        regularSnapshot: true
+        evaluation: evaluation,
+        depth: depth,
+        index: nodes.count,
+        parentIndex: parentIndex,
+        viewport: context.viewport
       )
-
       let key = Self.snapshotTraversalIdentity(
         elementType: snapshot.elementType,
         label: evaluation.label,
@@ -262,67 +219,57 @@ extension RunnerTests {
         seen.insert(key)
       }
 
-      let currentIndex = include && !isDuplicate ? nodes.count : parentIndex
-      if depth < context.maxDepth {
-        let nextVisibleDepth = include && !isDuplicate ? visibleDepth + 1 : visibleDepth
-        let nextScrollContainerAnchor: (index: Int, rect: CGRect)?
-        if include && !isDuplicate {
-          nextScrollContainerAnchor =
-            scrollContainerAnchor(
-              for: snapshot,
-              visible: intersectsViewportAndScrollClip,
-              nodeIndex: currentIndex
-            )
-            ?? nearestScrollAnchor
-        } else {
-          nextScrollContainerAnchor = nearestScrollAnchor
-        }
+      let currentIndex = !isDuplicate ? nodes.count : parentIndex
+      let transition = SnapshotPresentation.regularTraversalTransition(
+        for: node,
+        parentPresentedDepth: entry.parentPresentedDepth,
+        parentTraversal: entry.parentTraversal,
+        hint: hint,
+        rawDepth: depth,
+        viewport: context.viewport,
+        hasChildren: !snapshot.children.isEmpty,
+        isDuplicate: isDuplicate,
+        policy: .platformDefault
+      )
+      if transition.shouldVisitChildren {
         for child in snapshot.children.reversed() {
           stack.append(
             SnapshotTraversalEntry(
               snapshot: child,
               depth: depth + 1,
-              visibleDepth: nextVisibleDepth,
               parentIndex: currentIndex,
-              nearestScrollAnchor: nextScrollContainerAnchor,
-              projectionCursor: projection.descendants
+              parentPresentedDepth: transition.presentedDepth,
+              parentTraversal: transition.traversal
             )
           )
         }
       }
 
-      if !include || isDuplicate { continue }
+      if isDuplicate { continue }
 
-      let index = nodes.count
-      nodes.append(
-        makeSnapshotNode(
-          snapshot: snapshot,
-          evaluation: evaluation,
-          depth: min(context.maxDepth, visibleDepth),
-          index: index,
-          parentIndex: parentIndex
-        )
-      )
-      if visibleDepth < context.maxDepth {
+      nodes.append(node)
+      if transition.shouldVisitChildren {
         appendCollapsedTabFallbackNodes(
           to: &nodes,
           containerSnapshot: snapshot,
           resolveElements: collapsedTabDescendants,
-          depth: visibleDepth + 1,
-          parentIndex: index
+          depth: depth + 1,
+          parentIndex: node.index,
+          viewport: context.viewport
         )
       }
-
     }
 
     return SnapshotAcquisition(
-      nodes: applyHiddenContentHints(hiddenContentHintsByNodeIndex, to: nodes),
+      hint: hint,
+      nodes: nodes,
       truncated: false,
-      effectiveDepth: nil
+      effectiveDepth: nil,
+      viewport: context.viewport
     )
   }
 
-  // See `snapshotFast` above: the single production entry point, no unit-test overload.
+
   func snapshotRaw(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
     if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
@@ -337,19 +284,24 @@ extension RunnerTests {
     )
   }
 
-  /// Runs the pre-plan SpringBoard system-modal probe as a bounded capture tier sharing the plan
-  /// deadline, so a slow alert enumeration cannot bypass the snapshot timeout and stall (#1244).
+
+
   func boundedBlockingSystemAlertSnapshot(deadline: Date) -> DataPayload? {
     boundedBlockingSystemAlertSnapshotBody(deadline: deadline) { probeDeadline in
+
+
+
+
+
       return self.blockingSystemAlertSnapshot(deadline: probeDeadline)
     }
   }
 
-  /// The real bounding/hook machinery used by `boundedBlockingSystemAlertSnapshot` above: the
-  /// probe closure it's given always calls `self.blockingSystemAlertSnapshot` in production, and
-  /// in unit-test builds may first consult `systemModalProbeOverrideForTesting`. Keeping this in
-  /// one place means the `runMainThreadWork` wrap and the `onAbandoned`/`onDrained` hooks can
-  /// never drift between what production runs and what the unit tests exercise.
+
+
+
+
+
   private func boundedBlockingSystemAlertSnapshotBody(
     deadline: Date,
     probe: @escaping (Date) -> DataPayload?
@@ -369,7 +321,6 @@ extension RunnerTests {
     let startedAt = Date()
     do {
       return try runMainThreadWork(
-        command: nil,
         timeout: slice,
         timeoutError: {
           SnapshotCaptureFailure(
@@ -404,8 +355,8 @@ extension RunnerTests {
     #endif
   }
 
-  /// The probe gets its own budget, clamped by whatever remains of the shared plan deadline, and
-  /// 0 (skip entirely) once that deadline is already spent.
+
+
   static func systemModalProbeSlice(
     budget: TimeInterval,
     deadlineRemaining: TimeInterval
@@ -416,38 +367,28 @@ extension RunnerTests {
 
   func rawTreeSnapshotAcquisition(
     context: SnapshotTraversalContext,
-    options: PresentationOptions
+    hint: CaptureHint
   ) throws -> SnapshotAcquisition {
     var nodes: [RawAXNode] = []
 
     func walk(_ snapshot: XCUIElementSnapshot, depth: Int, parentIndex: Int?) throws {
-      if let limit = options.depth, depth > limit { return }
+      if let limit = hint.rawTraversalDepth, depth > limit { return }
 
-      let evaluation = evaluateSnapshot(snapshot, in: context)
-      let include = shouldAcquireSnapshotNode(
-        snapshot: snapshot,
-        label: evaluation.label,
-        identifier: evaluation.identifier,
-        valueText: evaluation.valueText,
-        options: options,
-        hittable: evaluation.hittable,
-        visible: evaluation.visible
-      )
-      let currentIndex = include ? nodes.count : parentIndex
-      if include {
-        if nodes.count >= Self.rawSnapshotMaxNodes {
-          throw rawSnapshotTooLargeFailure(nodeCount: nodes.count + 1)
-        }
-        nodes.append(
-          makeSnapshotNode(
-            snapshot: snapshot,
-            evaluation: evaluation,
-            depth: depth,
-            index: nodes.count,
-            parentIndex: parentIndex
-          )
-        )
+      let evaluation = evaluateSnapshot(snapshot)
+      if nodes.count >= Self.rawSnapshotMaxNodes {
+        throw rawSnapshotTooLargeFailure(nodeCount: nodes.count + 1)
       }
+      let currentIndex = nodes.count
+      nodes.append(
+        makeSnapshotNode(
+          snapshot: snapshot,
+          evaluation: evaluation,
+          depth: depth,
+          index: currentIndex,
+          parentIndex: parentIndex,
+          viewport: context.viewport
+        )
+      )
 
       let children = snapshot.children
       for child in children {
@@ -456,24 +397,36 @@ extension RunnerTests {
     }
 
     try walk(context.rootSnapshot, depth: 0, parentIndex: nil)
-    return SnapshotAcquisition(nodes: nodes, truncated: false, effectiveDepth: nil)
+    return SnapshotAcquisition(
+      hint: hint,
+      nodes: nodes,
+      truncated: false,
+      effectiveDepth: nil,
+      viewport: context.viewport
+    )
   }
 
   func querySweepSnapshotAcquisition(
     app: XCUIApplication,
-    options: PresentationOptions,
+    hint: CaptureHint,
     planDeadline: Date = .distantFuture
   ) -> SnapshotAcquisition {
     var nodes: [RawAXNode] = [
       interactiveRootNode(rect: .zero)
     ]
-    if options.depth == 0 {
-      return SnapshotAcquisition(nodes: nodes, truncated: false, effectiveDepth: nil)
+    if hint.rawTraversalDepth == 0 || hint.regularPresentedDepth == 0 {
+      return SnapshotAcquisition(
+        hint: hint,
+        nodes: nodes,
+        truncated: false,
+        effectiveDepth: nil,
+        viewport: .infinite
+      )
     }
 
-    // Bounded by both its own sweep budget and the umbrella capture-plan deadline, so a
-    // chained recovery tier can never push the plan past the main-thread watchdog (#1105).
-    let sweepDeadline = options.interactiveOnly
+
+
+    let sweepDeadline = hint.interactiveOnly
       ? Date().addingTimeInterval(Self.flatInteractiveFallbackBudget)
       : Date.distantFuture
     let deadline = min(sweepDeadline, planDeadline)
@@ -492,8 +445,7 @@ extension RunnerTests {
         element: element,
         index: 0,
         parentIndex: 0,
-        viewport: viewport,
-        options: options
+        viewport: viewport
       ) else {
         continue
       }
@@ -512,9 +464,9 @@ extension RunnerTests {
       return left.type < right.type
     }
 
-    // The synthetic root doubles as the daemon's viewport (find.ts prefers on-screen matches
-    // inside nodes[0].rect): use the real screen viewport when capture produced a finite one,
-    // so off-screen candidates can never inflate the root and masquerade as on-screen.
+
+
+
     let rootRect = viewport.isInfinite || viewport.isNull || viewport.isEmpty
       ? interactiveRootFrame(for: candidates)
       : viewport
@@ -539,15 +491,21 @@ extension RunnerTests {
         )
       )
     }
-    return SnapshotAcquisition(nodes: nodes, truncated: truncated, effectiveDepth: nil)
+    return SnapshotAcquisition(
+      hint: hint,
+      nodes: nodes,
+      truncated: truncated,
+      effectiveDepth: nil,
+      viewport: viewport
+    )
   }
 
   func snapshotAccessibilityUnavailable(failure: SnapshotCaptureFailure) -> DataPayload {
     NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_AX_UNAVAILABLE=%@", failure.message)
     runnerAccessibilityHealth = .unavailable
     invalidateCachedTarget(reason: Self.axSnapshotUnavailableReason)
-    // This is a planned terminal result, so it carries the structured verdict like every other
-    // planned snapshot — downstream sparse handling keys off the verdict, not node shapes.
+
+
     return sparseTruncatedSnapshotPayload(
       message: recoveredSnapshotMessage(failure),
       snapshotQuality: SnapshotQuality(
@@ -593,6 +551,248 @@ extension RunnerTests {
   }
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
   private func interactiveRootNode(rect: CGRect) -> RawAXNode {
     RawAXNode(
       index: 0,
@@ -630,96 +830,31 @@ extension RunnerTests {
     )
   }
 
-  // MARK: - Snapshot Filtering
-
-  /// Conservative acquisition gate. Regular capture keeps every node its visibility policy can
-  /// supply; `SnapshotPresentation` alone decides eligibility after the backend returns.
-  private func shouldAcquireSnapshotNode(
-    snapshot: XCUIElementSnapshot,
-    label: String,
-    identifier: String,
-    valueText: String?,
-    options: PresentationOptions,
-    hittable: Bool,
-    visible: Bool,
-    regularSnapshot: Bool = false
-  ) -> Bool {
-    let type = snapshot.elementType
-    let hasContent = !label.isEmpty || !identifier.isEmpty || (valueText != nil)
-    #if os(iOS)
-      if regularSnapshot && !visible && type != .application && type != .window {
-        return false
-      }
-    #endif
-    if regularSnapshot {
-      #if os(macOS)
-        if options.interactiveOnly && !visible && type != .application {
-          return false
-        }
-      #endif
-      if type == .application || type == .window { return true }
-      return visible
-    }
-    if options.interactiveOnly {
-      if isScrollableContainer(snapshot, visible: visible) { return true }
-      if interactiveTypes.contains(type) { return true }
-      if hittable && type != .other { return true }
-      if hasContent { return true }
-      return false
-    }
-    return true
-  }
 
-  private func computedSnapshotHittable(
-    _ snapshot: XCUIElementSnapshot,
-    viewport: CGRect,
-    laterNodes: ArraySlice<XCUIElementSnapshot>
-  ) -> Bool {
-    guard snapshot.isEnabled else { return false }
-    let frame = snapshot.frame
-    if frame.isNull || frame.isEmpty { return false }
-    let center = CGPoint(x: frame.midX, y: frame.midY)
-    if !viewport.contains(center) { return false }
-    for node in laterNodes {
-      if !isOccludingType(node.elementType) { continue }
-      let nodeFrame = node.frame
-      if nodeFrame.isNull || nodeFrame.isEmpty { continue }
-      if nodeFrame.contains(center) { return false }
-    }
-    return true
-  }
 
   func makeSnapshotTraversalContext(
     app: XCUIApplication,
-    options: PresentationOptions,
+    hint: CaptureHint,
     captureDeadline: Date = .distantFuture,
     treeCaptureSliceBudgetOverride: TimeInterval? = nil
   ) throws -> SnapshotTraversalContext? {
-    let (viewport, queryRoot) = try runMainThreadWork(
-      command: nil,
+    let viewport = try runMainThreadWork(
       timeout: min(1.0, max(0.1, captureDeadline.timeIntervalSinceNow)),
       timeoutError: snapshotMainThreadTimeoutError("preparing tree snapshot")
     ) {
-      (
-        self.safeSnapshotViewport(app: app),
-        options.scope.flatMap { self.findScopeElement(app: app, scope: $0) } ?? app
-      )
+      self.safeSnapshotViewport(app: app)
     }
 
     let treeSliceBudget = treeCaptureSliceBudgetOverride ?? treeCaptureSliceBudget
     let slice = min(treeSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
-    guard let rootSnapshot = try captureSnapshotRootBounded(queryRoot, sliceSeconds: slice) else {
+    guard let rootSnapshot = try captureSnapshotRootBounded(app, sliceSeconds: slice) else {
       return nil
     }
 
-    let (flatSnapshots, snapshotRanges) = flattenedSnapshots(rootSnapshot)
     return SnapshotTraversalContext(
-      queryRoot: queryRoot,
+      queryRoot: app,
       rootSnapshot: rootSnapshot,
-      viewport: viewport,
-      flatSnapshots: flatSnapshots,
-      snapshotRanges: snapshotRanges,
-      maxDepth: options.depth ?? Int.max
+      viewport: viewport
     )
   }
 
@@ -731,8 +866,8 @@ extension RunnerTests {
     return abandonedTreeCaptureCount > 0
   }
 
-  /// The watchdog abandoned one unit of XCTest main-thread capture work that is still draining on
-  /// main; XCTest-backed snapshot tiers skip (`hasAbandonedTreeCapture`) until a matching release.
+
+
   func retainAbandonedXCTestChannelWork() {
     treeCaptureLock.lock()
     abandonedTreeCaptureCount += 1
@@ -745,11 +880,11 @@ extension RunnerTests {
     treeCaptureLock.unlock()
   }
 
-  /// Runs the blocking tree-snapshot XPC on the main thread bounded by `sliceSeconds`. On
-  /// timeout the XPC keeps running on main (it cannot be cancelled); the capture is marked
-  /// abandoned so plans avoid XCTest-backed tiers until it drains, the tree backend is penalized
-  /// for this bundle, and the plan moves to the platform's independent recovery tier when one
-  /// exists (#1105/#1122).
+
+
+
+
+
   private func captureSnapshotRootBounded(
     _ element: XCUIElement,
     sliceSeconds: TimeInterval
@@ -758,7 +893,6 @@ extension RunnerTests {
       return try captureSnapshotRoot(element)
     }
     return try runMainThreadWork(
-      command: nil,
       timeout: sliceSeconds,
       timeoutError: treeCaptureTimeoutError(sliceSeconds: sliceSeconds),
       onAbandoned: {
@@ -856,26 +990,16 @@ extension RunnerTests {
     failure.code == Self.axSnapshotErrorCode || isAxIllegalArgument(failure.message)
   }
 
-  private func evaluateSnapshot(
-    _ snapshot: XCUIElementSnapshot,
-    in context: SnapshotTraversalContext
-  ) -> SnapshotEvaluation {
+  private func evaluateSnapshot(_ snapshot: XCUIElementSnapshot) -> SnapshotEvaluation {
     let label = aggregatedLabel(for: snapshot) ?? snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
     let identifier = snapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
     let valueText = snapshotValueText(snapshot)
-    let laterNodes = laterSnapshots(
-      for: snapshot,
-      in: context.flatSnapshots,
-      ranges: context.snapshotRanges
-    )
     return SnapshotEvaluation(
       label: label,
       identifier: identifier,
       valueText: valueText,
-      hittable: computedSnapshotHittable(snapshot, viewport: context.viewport, laterNodes: laterNodes),
       focused: snapshotHasFocus(snapshot),
-      selected: snapshotIsSelected(snapshot),
-      visible: isVisibleInViewport(snapshot.frame, context.viewport)
+      selected: snapshotIsSelected(snapshot)
     )
   }
 
@@ -884,7 +1008,8 @@ extension RunnerTests {
     evaluation: SnapshotEvaluation,
     depth: Int,
     index: Int,
-    parentIndex: Int?
+    parentIndex: Int?,
+    viewport: CGRect
   ) -> RawAXNode {
     return RawAXNode(
       index: index,
@@ -896,7 +1021,11 @@ extension RunnerTests {
       enabled: snapshot.isEnabled,
       focused: evaluation.focused ? true : nil,
       selected: evaluation.selected ? true : nil,
-      hittable: evaluation.hittable,
+      hittable: parentIndex != nil && SnapshotGeometry.isGeometricallyActionable(
+        enabled: snapshot.isEnabled,
+        frame: snapshot.frame,
+        viewport: viewport
+      ),
       depth: depth,
       parentIndex: parentIndex,
       hiddenContentAbove: nil,
@@ -904,52 +1033,6 @@ extension RunnerTests {
     )
   }
 
-  private func isOccludingType(_ type: XCUIElement.ElementType) -> Bool {
-    switch type {
-    case .application, .window:
-      return false
-    default:
-      return true
-    }
-  }
-
-  private func flattenedSnapshots(
-    _ root: XCUIElementSnapshot
-  ) -> ([XCUIElementSnapshot], [ObjectIdentifier: (Int, Int)]) {
-    var ordered: [XCUIElementSnapshot] = []
-    var ranges: [ObjectIdentifier: (Int, Int)] = [:]
-
-    @discardableResult
-    func visit(_ snapshot: XCUIElementSnapshot) -> Int {
-      let start = ordered.count
-      ordered.append(snapshot)
-      var end = start
-      for child in snapshot.children {
-        end = max(end, visit(child))
-      }
-      ranges[ObjectIdentifier(snapshot)] = (start, end)
-      return end
-    }
-
-    _ = visit(root)
-    return (ordered, ranges)
-  }
-
-  private func laterSnapshots(
-    for snapshot: XCUIElementSnapshot,
-    in ordered: [XCUIElementSnapshot],
-    ranges: [ObjectIdentifier: (Int, Int)]
-  ) -> ArraySlice<XCUIElementSnapshot> {
-    guard let (_, subtreeEnd) = ranges[ObjectIdentifier(snapshot)] else {
-      return ordered.suffix(from: ordered.count)
-    }
-    let nextIndex = subtreeEnd + 1
-    if nextIndex >= ordered.count {
-      return ordered.suffix(from: ordered.count)
-    }
-    return ordered.suffix(from: nextIndex)
-  }
-
   private func snapshotValueText(_ snapshot: XCUIElementSnapshot) -> String? {
     guard let value = snapshot.value else { return nil }
     let text = String(describing: value).trimmingCharacters(in: .whitespacesAndNewlines)
@@ -990,134 +1073,47 @@ extension RunnerTests {
     return nil
   }
 
-  func isVisibleInViewport(_ rect: CGRect, _ viewport: CGRect) -> Bool {
-    if rect.isNull || rect.isEmpty { return false }
-    return rect.intersects(viewport)
-  }
-
-  func isVisibleInRegularSnapshot(
-    _ rect: CGRect,
-    viewport: CGRect,
-    scrollContainerAnchor: (index: Int, rect: CGRect)?
-  ) -> Bool {
-    if !isVisibleInViewport(rect, viewport) { return false }
-    guard let scrollContainerAnchor else { return true }
-    return isVisibleInViewport(rect, scrollContainerAnchor.rect)
-  }
-
   private func appendCollapsedTabFallbackNodes(
     to nodes: inout [RawAXNode],
     containerSnapshot: XCUIElementSnapshot,
     resolveElements: () -> [XCUIElement],
     depth: Int,
-    parentIndex: Int
+    parentIndex: Int,
+    viewport: CGRect
   ) {
     let fallbackNodes = collapsedTabFallbackNodes(
       for: containerSnapshot,
       resolveElements: resolveElements,
       startingIndex: nodes.count,
       depth: depth,
-      parentIndex: parentIndex
+      parentIndex: parentIndex,
+      viewport: viewport
     )
     nodes.append(contentsOf: fallbackNodes)
   }
 
-  private func scrollContainerAnchor(
-    for snapshot: XCUIElementSnapshot,
-    visible: Bool,
-    nodeIndex: Int?
-  ) -> (index: Int, rect: CGRect)? {
-    return scrollContainerAnchor(
-      for: snapshot.elementType,
-      hasChildren: !snapshot.children.isEmpty,
-      visible: visible,
-      frame: snapshot.frame,
-      nodeIndex: nodeIndex
-    )
-  }
-
-  func scrollContainerAnchor(
-    for elementType: XCUIElement.ElementType,
-    hasChildren: Bool,
-    visible: Bool,
-    frame: CGRect,
-    nodeIndex: Int?
-  ) -> (index: Int, rect: CGRect)? {
-    guard let nodeIndex else { return nil }
-    if !isScrollableContainer(
-      elementType: elementType,
-      hasChildren: hasChildren,
-      visible: visible
-    ) { return nil }
-    return (nodeIndex, frame)
-  }
-
-  func rememberHiddenContentHint(
-    for frame: CGRect,
-    relativeTo scrollContainerAnchor: (index: Int, rect: CGRect),
-    hints: inout [Int: (above: Bool, below: Bool)]
-  ) {
-    if frame.isNull || frame.isEmpty { return }
-    var hint = hints[scrollContainerAnchor.index] ?? (above: false, below: false)
-    if frame.maxY <= scrollContainerAnchor.rect.minY {
-      hint.above = true
-    } else if frame.minY >= scrollContainerAnchor.rect.maxY {
-      hint.below = true
-    } else {
-      return
-    }
-    hints[scrollContainerAnchor.index] = hint
-  }
-
-  func applyHiddenContentHints(
-    _ hints: [Int: (above: Bool, below: Bool)],
-    to nodes: [RawAXNode]
-  ) -> [RawAXNode] {
-    if hints.isEmpty { return nodes }
-    return nodes.map { node in
-      guard let hint = hints[node.index] else { return node }
-      let hiddenContentAbove: Bool? = (node.hiddenContentAbove == true || hint.above) ? true : nil
-      let hiddenContentBelow: Bool? = (node.hiddenContentBelow == true || hint.below) ? true : nil
-      return RawAXNode(
-        index: node.index,
-        type: node.type,
-        label: node.label,
-        identifier: node.identifier,
-        value: node.value,
-        rect: node.rect,
-        enabled: node.enabled,
-        focused: node.focused,
-        selected: node.selected,
-        hittable: node.hittable,
-        depth: node.depth,
-        parentIndex: node.parentIndex,
-        hiddenContentAbove: hiddenContentAbove,
-        hiddenContentBelow: hiddenContentBelow,
-        actions: node.actions
-      )
-    }
-  }
-
   private func collapsedTabFallbackNodes(
     for containerSnapshot: XCUIElementSnapshot,
     resolveElements: () -> [XCUIElement],
     startingIndex: Int,
     depth: Int,
-    parentIndex: Int
+    parentIndex: Int,
+    viewport: CGRect
   ) -> [RawAXNode] {
     if !containerSnapshot.children.isEmpty { return [] }
     guard shouldExpandCollapsedTabContainer(containerSnapshot) else { return [] }
     let containerFrame = containerSnapshot.frame
     if containerFrame.isNull || containerFrame.isEmpty { return [] }
 
-    // Collapsed tab containers should be rare, so a full descendant scan is acceptable once per
-    // snapshot as a fallback for XCTest omitting the tab children from the snapshot tree.
+
+
     let elements = resolveElements()
     let candidates = elements.compactMap { element in
       collapsedTabCandidateNode(
         element: element,
         containerSnapshot: containerSnapshot,
-        containerFrame: containerFrame
+        containerFrame: containerFrame,
+        viewport: viewport
       )
     }
     .sorted { left, right in
@@ -1130,7 +1126,7 @@ extension RunnerTests {
     if candidates.count < 2 { return [] }
     let rowMidpoints = candidates.map { $0.rect.y + ($0.rect.height / 2) }
     let rowSpread = (rowMidpoints.max() ?? 0) - (rowMidpoints.min() ?? 0)
-    // Allow modest vertical jitter and short two-row wraps while still rejecting unrelated controls.
+
     if rowSpread > max(24.0, Double(containerFrame.height) * 0.6) { return [] }
 
     var seen = Set<String>()
@@ -1165,7 +1161,8 @@ extension RunnerTests {
   private func collapsedTabCandidateNode(
     element: XCUIElement,
     containerSnapshot: XCUIElementSnapshot,
-    containerFrame: CGRect
+    containerFrame: CGRect,
+    viewport: CGRect
   ) -> RawAXNode? {
     var node: RawAXNode?
     let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
@@ -1205,7 +1202,11 @@ extension RunnerTests {
         enabled: element.isEnabled,
         focused: elementHasFocus(element) ? true : nil,
         selected: element.isSelected ? true : nil,
-        hittable: element.isHittable,
+        hittable: SnapshotGeometry.isGeometricallyActionable(
+          enabled: element.isEnabled,
+          frame: frame,
+          viewport: viewport
+        ),
         depth: 0,
         parentIndex: nil,
         hiddenContentAbove: nil,
@@ -1331,40 +1332,25 @@ extension RunnerTests {
     element: XCUIElement,
     index: Int,
     parentIndex: Int?,
-    viewport: CGRect,
-    options: PresentationOptions
+    viewport: CGRect
   ) -> RawAXNode? {
     var node: RawAXNode?
     let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
       if !element.exists { return }
+
+
       let frame = element.frame
       if frame.isNull || frame.isEmpty { return }
-      let visible = isVisibleInViewport(frame, viewport)
-      if options.interactiveOnly && !visible { return }
-      #if os(macOS)
-        if !visible { return }
-      #endif
       let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
       let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
       let valueText = snapshotValueText(element)
       let elementType = element.elementType
       let enabled = element.isEnabled
-      let hittable = visible && enabled && element.isHittable
-      let filterNode = FlatSnapshotFilterNode(
-        isRoot: false,
-        label: label,
-        identifier: identifier,
-        valueText: valueText,
-        visible: visible
+      let hittable = SnapshotGeometry.isGeometricallyActionable(
+        enabled: enabled,
+        frame: frame,
+        viewport: viewport
       )
-      if !flatSnapshotFilterDecision(
-        filterNode,
-        options: options,
-        visibilityPolicy: .interactiveOnly,
-        insideMatchedScope: false
-      ).include {
-        return
-      }
 
       node = RawAXNode(
         index: index,
@@ -1390,19 +1376,4 @@ extension RunnerTests {
     return node
   }
 
-  private func isScrollableContainer(_ snapshot: XCUIElementSnapshot, visible: Bool) -> Bool {
-    return isScrollableContainer(
-      elementType: snapshot.elementType,
-      hasChildren: !snapshot.children.isEmpty,
-      visible: visible
-    )
-  }
-
-  private func isScrollableContainer(
-    elementType: XCUIElement.ElementType,
-    hasChildren: Bool,
-    visible: Bool
-  ) -> Bool {
-    return visible && hasChildren && Self.scrollContainerTypes.contains(elementType)
-  }
 }