Add hierarchical accessibility parsing API with container visualization

This adds:
- ContainerType enum (list, landmark, dataTable, semanticGroup)
- ContainerInfo struct for container metadata
- AccessibilityHierarchyNode enum for tree structure representation
- parseAccessibilityHierarchy() method returning hierarchical structure
- Hierarchy utilities for flattening and traversal

The hierarchical API preserves parent-child relationships and container
semantics, enabling container visualization in snapshots.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: RoyalPineapple

Sources/AccessibilitySnapshot/Parser/Swift/Classes/AccessibilityHierarchyParser.swift

@@ -153,6 +153,76 @@ public struct AccessibilityMarker: Equatable {
 
 }
 
+// MARK: - Container Visualization Types
+
+/// Types of accessibility containers
+public enum ContainerType: String, Equatable {
+    case none
+    case list
+    case landmark
+    case dataTable
+    case semanticGroup
+}
+
+/// Information about a container node
+public struct ContainerInfo: Equatable {
+    /// The type of container
+    public let type: ContainerType
+
+    /// Container's accessibility label (if any)
+    public let label: String?
+
+    /// Container's accessibility value (if any)
+    public let value: String?
+
+    /// Container's accessibility identifier (if any)
+    public let identifier: String?
+
+    /// Container's frame in the root view's coordinate space (for visualization)
+    public let frame: CGRect
+
+    public init(type: ContainerType, label: String?, value: String?, identifier: String?, frame: CGRect) {
+        self.type = type
+        self.label = label
+        self.value = value
+        self.identifier = identifier
+        self.frame = frame
+    }
+}
+
+/// A node in the accessibility hierarchy tree
+public enum AccessibilityHierarchyNode: Equatable {
+    /// A leaf node representing an accessibility element
+    /// - marker: The accessibility marker for this element
+    /// - traversalIndex: Position in VoiceOver traversal order
+    case element(marker: AccessibilityMarker, traversalIndex: Int)
+
+    /// A container node that groups child elements
+    /// - info: Container metadata (type, label, value, identifier, frame)
+    /// - children: Child nodes within this container
+    case container(info: ContainerInfo, children: [AccessibilityHierarchyNode])
+
+    /// Child nodes (empty for leaf elements, contains children for containers)
+    public var children: [AccessibilityHierarchyNode] {
+        switch self {
+        case .element:
+            return []
+        case .container(_, let children):
+            return children
+        }
+    }
+
+    /// Position in VoiceOver traversal order (nil for container-only nodes)
+    public var traversalIndex: Int? {
+        switch self {
+        case .element(_, let index):
+            return index
+        case .container:
+            return nil
+        }
+    }
+}
+
 // MARK: -
 
 public protocol UserInterfaceLayoutDirectionProviding {
@@ -166,7 +236,7 @@ extension UIApplication: UserInterfaceLayoutDirectionProviding {}
 public protocol UserInterfaceIdiomProviding {
 
     var userInterfaceIdiom: UIUserInterfaceIdiom { get }
-    
+
 }
 
 extension UIDevice: UserInterfaceIdiomProviding {}
@@ -325,6 +395,42 @@ public final class AccessibilityHierarchyParser {
         }
     }
 
+    /// Parses the accessibility hierarchy starting from the `root` view and returns a tree structure
+    /// preserving parent-child relationships and container semantics.
+    ///
+    /// The returned hierarchy uses smart container flattening: containers are only explicit nodes when they
+    /// have meaningful properties (label, value, identifier) or provide important semantic context
+    /// (list, landmark, data table).
+    ///
+    /// Each element node includes a `traversalIndex` indicating its position in VoiceOver's navigation order.
+    ///
+    /// - parameter root: The root view of the accessibility hierarchy
+    /// - parameter rotorResultLimit: Maximum number of rotor results to collect in each direction. Defaults to 10.
+    /// - parameter userInterfaceLayoutDirectionProvider: Provider of the device's UI layout direction
+    /// - parameter userInterfaceIdiomProvider: Provider of the device's interface idiom
+    /// - returns: Array of root-level hierarchy nodes (typically one node for the root view's hierarchy)
+    public func parseAccessibilityHierarchy(
+        in root: UIView,
+        rotorResultLimit: Int = AccessibilityMarker.defaultRotorResultLimit,
+        userInterfaceLayoutDirectionProvider: UserInterfaceLayoutDirectionProviding = UIApplication.shared,
+        userInterfaceIdiomProvider: UserInterfaceIdiomProviding = UIDevice.current
+    ) -> [AccessibilityHierarchyNode] {
+        let userInterfaceLayoutDirection = userInterfaceLayoutDirectionProvider.userInterfaceLayoutDirection
+        let userInterfaceIdiom = userInterfaceIdiomProvider.userInterfaceIdiom
+
+        let accessibilityNodes = root.recursiveAccessibilityHierarchy()
+
+        let (hierarchy, _) = buildHierarchy(
+            from: accessibilityNodes,
+            in: root,
+            rotorResultLimit: rotorResultLimit,
+            userInterfaceLayoutDirection: userInterfaceLayoutDirection,
+            userInterfaceIdiom: userInterfaceIdiom
+        )
+
+        return hierarchy
+    }
+
     // MARK: - Private Types
 
     /// Representation of an accessibility element, made up of the element `object` itself and the `context` in which it
@@ -613,6 +719,170 @@ public final class AccessibilityHierarchyParser {
     /// Used for memoization of accessibility hierarchy parsing when determining element contexts.
     private var viewToElementsMap: [UIView: [NSObject]] = [:]
 
+    // MARK: - Private Hierarchy Methods
+
+    /// Creates ContainerInfo for a container object if it should be represented as an explicit container node
+    private func containerInfo(
+        for object: NSObject,
+        containerType: ContainerType,
+        in root: UIView
+    ) -> ContainerInfo? {
+        let label = object.accessibilityLabel
+        let value = object.accessibilityValue
+        let identifier = object.identifier
+
+        // Get container's frame in root coordinate space
+        let frame: CGRect
+        if let view = object as? UIView {
+            frame = root.convert(view.bounds, from: view)
+        } else {
+            frame = root.convert(object.accessibilityFrame, from: nil)
+        }
+
+        // Always keep data tables (complex structure)
+        if containerType == .dataTable {
+            return ContainerInfo(type: containerType, label: label, value: value, identifier: identifier, frame: frame)
+        }
+
+        // Keep container if it has meaningful properties
+        if label != nil || value != nil || identifier != nil {
+            return ContainerInfo(type: containerType, label: label, value: value, identifier: identifier, frame: frame)
+        }
+
+        // Keep list/landmark containers for semantic meaning
+        if containerType == .list || containerType == .landmark {
+            return ContainerInfo(type: containerType, label: label, value: value, identifier: identifier, frame: frame)
+        }
+
+        // Flatten semantic groups without properties
+        return nil
+    }
+
+    /// Recursively builds the accessibility hierarchy from internal AccessibilityNode tree
+    /// Returns tuple of (hierarchy nodes, next traversal index)
+    private func buildHierarchy(
+        from nodes: [AccessibilityNode],
+        in root: UIView,
+        rotorResultLimit: Int,
+        userInterfaceLayoutDirection: UIUserInterfaceLayoutDirection,
+        userInterfaceIdiom: UIUserInterfaceIdiom,
+        startingTraversalIndex: Int = 0
+    ) -> ([AccessibilityHierarchyNode], Int) {
+        var hierarchyNodes: [AccessibilityHierarchyNode] = []
+        var currentTraversalIndex = startingTraversalIndex
+
+        // First, sort elements to get proper traversal order
+        let sortedElementList = sortedElements(
+            for: nodes,
+            explicitlyOrdered: false,
+            in: root,
+            userInterfaceLayoutDirection: userInterfaceLayoutDirection,
+            userInterfaceIdiom: userInterfaceIdiom
+        )
+
+        // Create context for each element
+        let contextualized = sortedElementList.map { element in
+            return ContextualElement(
+                object: element.object,
+                context: context(
+                    for: element.object,
+                    from: element.contextProvider,
+                    userInterfaceLayoutDirection: userInterfaceLayoutDirection,
+                    userInterfaceIdiom: userInterfaceIdiom
+                )
+            )
+        }
+
+        // Build markers for all elements
+        let markers = contextualized.map { element -> AccessibilityMarker in
+            let (description, hint) = element.object.accessibilityDescription(context: element.context)
+            let activationPoint = element.object.accessibilityActivationPoint
+
+            return AccessibilityMarker(
+                description: description,
+                label: element.object.accessibilityLabel,
+                value: element.object.accessibilityValue,
+                traits: element.object.accessibilityTraits,
+                identifier: element.object.identifier,
+                hint: hint,
+                userInputLabels: element.object.accessibilityUserInputLabels,
+                shape: Self.accessibilityShape(for: element.object, in: root),
+                activationPoint: root.convert(activationPoint, from: nil),
+                usesDefaultActivationPoint: activationPoint.approximatelyEquals(
+                    Self.defaultActivationPoint(for: element.object),
+                    tolerance: 1 / (root.window?.screen ?? UIScreen.main).scale
+                ),
+                customActions: element.object.accessibilityCustomActions?.map { $0.name } ?? [],
+                customContent: element.object.customContent,
+                customRotors: element.object.customRotors(in: root, context: element.context, resultLimit: rotorResultLimit),
+                accessibilityLanguage: element.object.accessibilityLanguage,
+                respondsToUserInteraction: element.object.accessibilityRespondsToUserInteraction
+            )
+        }
+
+        // Now process nodes recursively to build hierarchy
+        func processNodes(_ nodes: [AccessibilityNode]) -> [AccessibilityHierarchyNode] {
+            var result: [AccessibilityHierarchyNode] = []
+
+            for node in nodes {
+                switch node {
+                case .element(let object, _):
+                    // Find this element's marker
+                    if let index = sortedElementList.firstIndex(where: { $0.object === object }),
+                       index < markers.count {
+                        let marker = markers[index]
+                        let hierarchyNode = AccessibilityHierarchyNode.element(
+                            marker: marker,
+                            traversalIndex: currentTraversalIndex
+                        )
+                        result.append(hierarchyNode)
+                        currentTraversalIndex += 1
+                    }
+
+                case .group(let children, _, let frameProvider):
+                    // Determine container type and check if it should be explicit
+                    var containerType: ContainerType? = nil
+                    var shouldBeContainer = false
+
+                    if let view = frameProvider as? UIView {
+                        if view.accessibilityContainerType == .list {
+                            containerType = .list
+                        } else if view.accessibilityContainerType == .landmark {
+                            containerType = .landmark
+                        } else if view.accessibilityContainerType == .dataTable {
+                            containerType = .dataTable
+                        } else if view.shouldGroupAccessibilityChildren {
+                            containerType = .semanticGroup
+                        }
+
+                        if let type = containerType {
+                            if let info = containerInfo(for: view, containerType: type, in: root) {
+                                // Create container node with children
+                                let childNodes = processNodes(children)
+                                let containerNode = AccessibilityHierarchyNode.container(
+                                    info: info,
+                                    children: childNodes
+                                )
+                                result.append(containerNode)
+                                shouldBeContainer = true
+                            }
+                        }
+                    }
+
+                    // If not a container, flatten children
+                    if !shouldBeContainer {
+                        result.append(contentsOf: processNodes(children))
+                    }
+                }
+            }
+
+            return result
+        }
+
+        hierarchyNodes = processNodes(nodes)
+        return (hierarchyNodes, currentTraversalIndex)
+    }
+
 }
 
 fileprivate extension AccessibilityHierarchyParser {
@@ -948,3 +1218,63 @@ internal extension UITextInput  {
         }
     }
 }
+
+// MARK: - Hierarchy Utilities
+
+extension AccessibilityHierarchyNode {
+
+    /// Flattens the hierarchy tree into an array of markers in VoiceOver traversal order
+    public func flattenToMarkers() -> [AccessibilityMarker] {
+        var markers: [(index: Int, marker: AccessibilityMarker)] = []
+
+        func collectMarkers(from node: AccessibilityHierarchyNode) {
+            switch node {
+            case .element(let marker, let index):
+                markers.append((index, marker))
+            case .container(_, let children):
+                // Containers don't have markers, just traverse children
+                for child in children {
+                    collectMarkers(from: child)
+                }
+            }
+        }
+
+        collectMarkers(from: self)
+
+        // Sort by traversal index and return markers
+        return markers.sorted { $0.index < $1.index }.map { $0.marker }
+    }
+
+    /// Recursively traverses the hierarchy tree, calling the visitor for each node
+    public func traverse(_ visitor: (AccessibilityHierarchyNode) -> Void) {
+        visitor(self)
+        for child in children {
+            child.traverse(visitor)
+        }
+    }
+}
+
+extension Array where Element == AccessibilityHierarchyNode {
+
+    /// Flattens an array of hierarchy nodes into a single array of markers in VoiceOver traversal order
+    public func flattenToMarkers() -> [AccessibilityMarker] {
+        var allMarkers: [(index: Int, marker: AccessibilityMarker)] = []
+
+        for node in self {
+            func collectMarkers(from node: AccessibilityHierarchyNode) {
+                switch node {
+                case .element(let marker, let index):
+                    allMarkers.append((index, marker))
+                case .container(_, let children):
+                    for child in children {
+                        collectMarkers(from: child)
+                    }
+                }
+            }
+
+            collectMarkers(from: node)
+        }
+
+        return allMarkers.sorted { $0.index < $1.index }.map { $0.marker }
+    }
+}