agent-device 0.20.9 → 0.21.0

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,69 +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 parentIndex: Int?
+    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
 
+  /// One raw-value table covers public XCTest cases and the SDK-hidden Keyboard/Key values.
+  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> = [
@@ -108,7 +116,7 @@ extension RunnerTests {
   // `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: SnapshotOptions) throws -> DataPayload {
+  func snapshotFast(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
     if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
       return blocking
@@ -122,10 +130,10 @@ extension RunnerTests {
     )
   }
 
-  func recursiveTreeSnapshotPayload(
+  func recursiveTreeSnapshotAcquisition(
     context: SnapshotTraversalContext,
-    options: SnapshotOptions
-  ) -> DataPayload {
+    hint: CaptureHint
+  ) -> SnapshotAcquisition {
     var cachedDescendantElements: [XCUIElement]?
     func collapsedTabDescendants() -> [XCUIElement] {
       if let cachedDescendantElements {
@@ -138,66 +146,68 @@ extension RunnerTests {
       return result.elements
     }
 
-    var nodes: [SnapshotNode] = []
-    var hiddenContentHintsByNodeIndex: [Int: (above: Bool, below: Bool)] = [:]
-    let rootEvaluation = evaluateSnapshot(context.rootSnapshot, in: context)
+    // Acquisition serializes facts: every traversed node is emitted at raw traversal depth, and
+    // the regular projection's clip fold runs once inside `SnapshotPresentation` (#1797). The two
+    // walks this backend keeps are the raw budget or regular presented-depth frontier, plus
+    // collapsed-tab augmentation which needs live element handles; neither walk publishes a
+    // presentation node.
+    var nodes: [RawAXNode] = []
+    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
-    )
-    var stack: [(XCUIElementSnapshot, Int, Int, Int?, (index: Int, rect: CGRect)?)] =
-      context.rootSnapshot.children.map {
-        ($0, 1, 1, 0, rootScrollAnchor)
+    var stack: [SnapshotTraversalEntry] = []
+    if shouldVisitRootChildren {
+      stack = context.rootSnapshot.children.map {
+        SnapshotTraversalEntry(
+          snapshot: $0,
+          depth: 1,
+          parentIndex: 0,
+          parentPresentedDepth: 0,
+          parentTraversal: .root
+        )
       }
+    }
 
-    while let (snapshot, depth, visibleDepth, parentIndex, nearestScrollAnchor) = stack.popLast() {
-      if let limit = options.depth, depth > limit { continue }
+    while let entry = stack.popLast() {
+      let snapshot = entry.snapshot
+      let depth = entry.depth
+      let parentIndex = entry.parentIndex
+      if let limit = hint.rawTraversalDepth, depth > limit { continue }
 
-      let evaluation = evaluateSnapshot(snapshot, in: context)
-      let regularVisible = isVisibleInRegularSnapshot(
-        snapshot.frame,
-        viewport: context.viewport,
-        scrollContainerAnchor: nearestScrollAnchor
-      )
-      if !regularVisible, let nearestScrollAnchor {
-        rememberHiddenContentHint(
-          for: snapshot.frame,
-          relativeTo: nearestScrollAnchor,
-          hints: &hiddenContentHintsByNodeIndex
-        )
-      }
-      let include = shouldInclude(
+      let evaluation = evaluateSnapshot(snapshot)
+      let node = makeSnapshotNode(
         snapshot: snapshot,
-        label: evaluation.label,
-        identifier: evaluation.identifier,
-        valueText: evaluation.valueText,
-        options: options,
-        hittable: evaluation.hittable,
-        visible: regularVisible,
-        regularSnapshot: true
+        evaluation: evaluation,
+        depth: depth,
+        index: nodes.count,
+        parentIndex: parentIndex,
+        viewport: context.viewport
       )
-
       let key = Self.snapshotTraversalIdentity(
         elementType: snapshot.elementType,
         label: evaluation.label,
@@ -209,58 +219,58 @@ 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: regularVisible,
-              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((child, depth + 1, nextVisibleDepth, currentIndex, nextScrollContainerAnchor))
+          stack.append(
+            SnapshotTraversalEntry(
+              snapshot: child,
+              depth: depth + 1,
+              parentIndex: currentIndex,
+              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 DataPayload(
-      nodes: applyHiddenContentHints(hiddenContentHintsByNodeIndex, to: nodes),
-      truncated: false
+    return SnapshotAcquisition(
+      hint: hint,
+      nodes: nodes,
+      truncated: false,
+      effectiveDepth: nil,
+      viewport: context.viewport
     )
   }
 
   // See `snapshotFast` above: the single production entry point, no unit-test overload.
-  func snapshotRaw(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
+  func snapshotRaw(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
     if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
       return blocking
@@ -306,7 +316,6 @@ extension RunnerTests {
     let startedAt = Date()
     do {
       return try runMainThreadWork(
-        command: nil,
         timeout: slice,
         timeoutError: {
           SnapshotCaptureFailure(
@@ -351,40 +360,30 @@ extension RunnerTests {
     return min(budget, deadlineRemaining)
   }
 
-  func rawTreeSnapshotPayload(
+  func rawTreeSnapshotAcquisition(
     context: SnapshotTraversalContext,
-    options: SnapshotOptions
-  ) throws -> DataPayload {
-    var nodes: [SnapshotNode] = []
+    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 = shouldInclude(
-        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 {
@@ -393,30 +392,42 @@ extension RunnerTests {
     }
 
     try walk(context.rootSnapshot, depth: 0, parentIndex: nil)
-    return DataPayload(nodes: nodes, truncated: false)
+    return SnapshotAcquisition(
+      hint: hint,
+      nodes: nodes,
+      truncated: false,
+      effectiveDepth: nil,
+      viewport: context.viewport
+    )
   }
 
-  func snapshotFlatInteractive(
+  func querySweepSnapshotAcquisition(
     app: XCUIApplication,
-    options: SnapshotOptions,
+    hint: CaptureHint,
     planDeadline: Date = .distantFuture
-  ) -> DataPayload {
-    var nodes: [SnapshotNode] = [
+  ) -> SnapshotAcquisition {
+    var nodes: [RawAXNode] = [
       interactiveRootNode(rect: .zero)
     ]
-    if options.depth == 0 {
-      return DataPayload(nodes: nodes, truncated: false)
+    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)
     let viewport = safeSnapshotViewport(app: app)
     var seen = Set<String>()
-    var candidates: [SnapshotNode] = []
+    var candidates: [RawAXNode] = []
     let flatElements = flatInteractiveElements(app: app, deadline: deadline)
     var truncated = flatElements.truncated
     for element in flatElements.elements {
@@ -429,8 +440,7 @@ extension RunnerTests {
         element: element,
         index: 0,
         parentIndex: 0,
-        viewport: viewport,
-        options: options
+        viewport: viewport
       ) else {
         continue
       }
@@ -458,7 +468,7 @@ extension RunnerTests {
     nodes[0] = interactiveRootNode(rect: rootRect)
     for candidate in candidates {
       nodes.append(
-        SnapshotNode(
+        RawAXNode(
           index: nodes.count,
           type: candidate.type,
           label: candidate.label,
@@ -476,7 +486,13 @@ extension RunnerTests {
         )
       )
     }
-    return DataPayload(nodes: nodes, truncated: truncated)
+    return SnapshotAcquisition(
+      hint: hint,
+      nodes: nodes,
+      truncated: truncated,
+      effectiveDepth: nil,
+      viewport: viewport
+    )
   }
 
   func snapshotAccessibilityUnavailable(failure: SnapshotCaptureFailure) -> DataPayload {
@@ -521,7 +537,7 @@ extension RunnerTests {
   ) -> DataPayload {
     return DataPayload(
       message: message,
-      nodes: [interactiveRootNode(rect: .zero)],
+      nodes: [SnapshotPresentation.singleElementRead(interactiveRootNode(rect: .zero))],
       truncated: true,
       snapshotQuality: snapshotQuality,
       runnerFatal: runnerFatal,
@@ -530,8 +546,8 @@ extension RunnerTests {
   }
 
 
-  private func interactiveRootNode(rect: CGRect) -> SnapshotNode {
-    SnapshotNode(
+  private func interactiveRootNode(rect: CGRect) -> RawAXNode {
+    RawAXNode(
       index: 0,
       type: "Application",
       label: nil,
@@ -549,7 +565,7 @@ extension RunnerTests {
     )
   }
 
-  private func interactiveRootFrame(for candidates: [SnapshotNode]) -> CGRect {
+  private func interactiveRootFrame(for candidates: [RawAXNode]) -> CGRect {
     guard !candidates.isEmpty else {
       return .zero
     }
@@ -569,87 +585,29 @@ extension RunnerTests {
 
   // MARK: - Snapshot Filtering
 
-  private func shouldInclude(
-    snapshot: XCUIElementSnapshot,
-    label: String,
-    identifier: String,
-    valueText: String?,
-    options: SnapshotOptions,
-    hittable: Bool,
-    visible: Bool,
-    regularSnapshot: Bool = false
-  ) -> Bool {
-    let type = snapshot.elementType
-    let hasContent = !label.isEmpty || !identifier.isEmpty || (valueText != nil)
-    if options.interactiveOnly {
-      if isScrollableContainer(snapshot, visible: visible) { return true }
-      #if os(macOS)
-        if !visible && type != .application {
-          return false
-        }
-      #endif
-      if interactiveTypes.contains(type) { return true }
-      if hittable && type != .other { return true }
-      if hasContent { return true }
-      return false
-    }
-    if regularSnapshot {
-      if type == .application || type == .window { return true }
-      return visible
-    }
-    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: SnapshotOptions,
+    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
     )
   }
 
@@ -688,7 +646,6 @@ extension RunnerTests {
       return try captureSnapshotRoot(element)
     }
     return try runMainThreadWork(
-      command: nil,
       timeout: sliceSeconds,
       timeoutError: treeCaptureTimeoutError(sliceSeconds: sliceSeconds),
       onAbandoned: {
@@ -786,26 +743,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)
     )
   }
 
@@ -814,9 +761,10 @@ extension RunnerTests {
     evaluation: SnapshotEvaluation,
     depth: Int,
     index: Int,
-    parentIndex: Int?
-  ) -> SnapshotNode {
-    return SnapshotNode(
+    parentIndex: Int?,
+    viewport: CGRect
+  ) -> RawAXNode {
+    return RawAXNode(
       index: index,
       type: elementTypeName(snapshot.elementType),
       label: evaluation.label.isEmpty ? nil : evaluation.label,
@@ -826,7 +774,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,
@@ -834,52 +786,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)
@@ -920,121 +826,33 @@ 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 [SnapshotNode],
+    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: [SnapshotNode]
-  ) -> [SnapshotNode] {
-    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 SnapshotNode(
-        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
-  ) -> [SnapshotNode] {
+    parentIndex: Int,
+    viewport: CGRect
+  ) -> [RawAXNode] {
     if !containerSnapshot.children.isEmpty { return [] }
     guard shouldExpandCollapsedTabContainer(containerSnapshot) else { return [] }
     let containerFrame = containerSnapshot.frame
@@ -1047,7 +865,8 @@ extension RunnerTests {
       collapsedTabCandidateNode(
         element: element,
         containerSnapshot: containerSnapshot,
-        containerFrame: containerFrame
+        containerFrame: containerFrame,
+        viewport: viewport
       )
     }
     .sorted { left, right in
@@ -1073,7 +892,7 @@ extension RunnerTests {
     if uniqueCandidates.count < 2 { return [] }
 
     return uniqueCandidates.enumerated().map { offset, node in
-      SnapshotNode(
+      RawAXNode(
         index: startingIndex + offset,
         type: node.type,
         label: node.label,
@@ -1095,9 +914,10 @@ extension RunnerTests {
   private func collapsedTabCandidateNode(
     element: XCUIElement,
     containerSnapshot: XCUIElementSnapshot,
-    containerFrame: CGRect
-  ) -> SnapshotNode? {
-    var node: SnapshotNode?
+    containerFrame: CGRect,
+    viewport: CGRect
+  ) -> RawAXNode? {
+    var node: RawAXNode?
     let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
       if !element.exists { return }
       let elementType = element.elementType
@@ -1125,7 +945,7 @@ extension RunnerTests {
         return
       }
 
-      node = SnapshotNode(
+      node = RawAXNode(
         index: 0,
         type: elementTypeName(elementType),
         label: label.isEmpty ? nil : label,
@@ -1135,7 +955,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,
@@ -1261,42 +1085,27 @@ extension RunnerTests {
     element: XCUIElement,
     index: Int,
     parentIndex: Int?,
-    viewport: CGRect,
-    options: SnapshotOptions
-  ) -> SnapshotNode? {
-    var node: SnapshotNode?
+    viewport: CGRect
+  ) -> RawAXNode? {
+    var node: RawAXNode?
     let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
       if !element.exists { return }
+      // Declared residue: a flat element query has no hierarchy for geometryless semantics to
+      // attach to, so frameless elements are dropped at acquisition rather than presented.
       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 = SnapshotNode(
+      node = RawAXNode(
         index: index,
         type: elementTypeName(elementType),
         label: label.isEmpty ? nil : label,
@@ -1320,19 +1129,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)
-  }
 }