Add hierarchical accessibility parsing API

Introduces `parseAccessibilityHierarchy()` which returns accessibility
data as a tree structure preserving container relationships, compared
to the existing `parseAccessibilityElements()` which returns a flat list.

New types:
- `AccessibilityHierarchy`: Recursive enum with `.element` and `.container` cases
- `AccessibilityContainer`: Container metadata (type, frame, traits)
- `ContainerType`: Enum for semantic groups, lists, landmarks, data tables, tab bars

All types conform to Codable for serialization. The hierarchy can be
flattened back to elements via `flattenToElements()` for compatibility.

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

Author: RoyalPineapple

Example/SnapshotTests/ReferenceImages/_64/SnapshotTests.AccessibilitySnapshotTests/testTabBars_17_5_393x852@3x.png

@@ -0,0 +1,33 @@
+import CoreGraphics
+
+/// Information about a container node
+public struct AccessibilityContainer: Equatable, Codable {
+    /// The type of accessibility container with its associated data
+    public enum ContainerType: Equatable, Codable {
+        /// A semantic grouping with optional label, value, and identifier
+        case semanticGroup(label: String?, value: String?, identifier: String?)
+
+        /// A list container (affects rotor navigation)
+        case list
+
+        /// A landmark container (affects rotor navigation)
+        case landmark
+
+        /// A data table with row and column counts
+        case dataTable(rowCount: Int, columnCount: Int)
+
+        /// A tab bar container (detected via .tabBar trait)
+        case tabBar
+    }
+
+    /// The type of container with its associated data
+    public let type: ContainerType
+
+    /// Container's frame in the root view's coordinate space (for visualization)
+    public let frame: CGRect
+
+    public init(type: ContainerType, frame: CGRect) {
+        self.type = type
+        self.frame = frame
+    }
+}

Example/UnitTests/AccessibilityHierarchyParserTests.swift

@@ -0,0 +1,215 @@
+import UIKit
+
+/// A type alias for backwards compatibility.
+public typealias AccessibilityMarker = AccessibilityElement
+
+public struct AccessibilityElement: Equatable, Codable {
+    /// Default number of rotor results to collect in each direction.
+    public static let defaultRotorResultLimit: Int = 10
+
+    // MARK: - Public Types
+
+    public enum Shape: Equatable {
+        /// Accessibility frame, in the coordinate space of the view being snapshotted.
+        case frame(CGRect)
+
+        /// Accessibility path, in the coordinate space of the view being snapshotted.
+        case path(UIBezierPath)
+    }
+
+    public struct CustomRotor: Equatable, CustomStringConvertible, Codable {
+        public struct ResultMarker: Equatable, CustomStringConvertible, Codable {
+            public let elementDescription: String
+            public let rangeDescription: String?
+            public let shape: Shape?
+
+            public var description: String {
+                guard let rangeDescription else {
+                    return elementDescription
+                }
+                return "\(elementDescription) \(rangeDescription)"
+            }
+        }
+
+        public var name: String
+        public var resultMarkers: [AccessibilityElement.CustomRotor.ResultMarker] = []
+        public let limit: UIAccessibilityCustomRotor.CollectedRotorResults.Limit
+
+        init?(from: UIAccessibilityCustomRotor, parentElement: NSObject, root: UIView, context: AccessibilityHierarchyParser.Context? = nil, resultLimit: Int) {
+            guard from.isKnownRotorType else { return nil }
+            name = from.displayName(locale: parentElement.accessibilityLanguage)
+            let collected = from.collectAllResults(nextLimit: resultLimit, previousLimit: resultLimit)
+            limit = collected.limit
+            resultMarkers = collected.results.compactMap { result in
+                guard let element = result.targetElement as? NSObject else { return nil }
+                var description = element.accessibilityDescription(context: context).description
+                var shape: Shape? = AccessibilityHierarchyParser.accessibilityShape(for: element, in: root)
+
+                if let range = result.targetRange,
+                   let input = element as? UITextInput
+                {
+                    if let path = input.accessibilityPath(for: range) {
+                        let converted = root.convert(path, from: input as? UIView)
+                        shape = .path(converted)
+                    }
+                    if let substring = input.text(in: range) {
+                        description = substring
+                    }
+                    return ResultMarker(elementDescription: description, rangeDescription: range.formatted(in: input), shape: shape)
+                }
+                return ResultMarker(elementDescription: description, rangeDescription: nil, shape: shape)
+            }
+        }
+
+        public var description: String {
+            return name + ": " + resultMarkers.map { $0.description }.joined(separator: "\n")
+        }
+    }
+
+    public struct CustomContent: Codable, Equatable {
+        public var label: String
+        public var value: String
+        public var isImportant: Bool
+
+        @available(iOS 14.0, *)
+        init(from: AXCustomContent) {
+            label = from.label
+            value = from.value
+            isImportant = from.importance == .high
+        }
+    }
+
+    public struct CustomAction: Equatable, Codable {
+        public var name: String
+        public var image: UIImage?
+
+        init(name: String, image: UIImage?) {
+            self.name = name
+            self.image = image
+        }
+
+        @available(iOS 14.0, *)
+        init(from: UIAccessibilityCustomAction) {
+            name = from.name
+            image = from.image
+        }
+
+        private enum CodingKeys: String, CodingKey {
+            case name
+            case imageData
+            case imageScale
+        }
+
+        public init(from decoder: Decoder) throws {
+            let container = try decoder.container(keyedBy: CodingKeys.self)
+            name = try container.decode(String.self, forKey: .name)
+
+            if let imageData = try container.decodeIfPresent(Data.self, forKey: .imageData) {
+                let scale = try container.decodeIfPresent(CGFloat.self, forKey: .imageScale) ?? 1.0
+                image = UIImage(data: imageData, scale: scale)
+            } else {
+                image = nil
+            }
+        }
+
+        public func encode(to encoder: Encoder) throws {
+            var container = encoder.container(keyedBy: CodingKeys.self)
+            try container.encode(name, forKey: .name)
+
+            if let image = image, let pngData = image.pngData() {
+                try container.encode(pngData, forKey: .imageData)
+                try container.encode(image.scale, forKey: .imageScale)
+            }
+        }
+    }
+
+    // MARK: - Public Properties
+
+    /// The description of the accessibility element that will be read by VoiceOver when the element is brought into
+    /// focus.
+    public let description: String
+
+    public let label: String?
+
+    public let value: String?
+
+    public let traits: UIAccessibilityTraits
+
+    /// A unique identifier for the element, primarily used in UI tests for locating and interacting with elements.
+    /// This identifier is not visible to users.
+    public let identifier: String?
+
+    /// A hint that will be read by VoiceOver if focus remains on the element after the `description` is read.
+    public let hint: String?
+
+    /// The labels that will be used by Voice Control for user input.
+    /// These labels are displayed based on the `AccessibilityContentDisplayMode` configuration:
+    /// - `.always`: Always shows user input labels
+    /// - `.whenOverridden`: Shows labels only when they differ from default values (future enhancement)
+    /// - `.never`: Never shows user input labels
+    public let userInputLabels: [String]?
+
+    /// The shape that will be highlighted on screen while the element is in focus.
+    public let shape: Shape
+
+    /// The accessibility activation point, in the coordinate space of the view being snapshotted.
+    public let activationPoint: CGPoint
+
+    /// Whether or not the `activationPoint` is the default activation point for the object.
+    ///
+    /// For most elements, the default activation point is the midpoint of the element's accessibility frame. Certain
+    /// elements have distinct defaults - for example, a `UISlider` puts its activation point at the center of its thumb
+    /// by default.
+    public let usesDefaultActivationPoint: Bool
+
+    /// The custom actions supported by the element.
+    public let customActions: [CustomAction]
+
+    /// Any custom content included by the element.
+    public let customContent: [CustomContent]
+
+    /// Any custom rotors included by the element.
+    public let customRotors: [CustomRotor]
+
+    /// The language code of the language used to localize strings in the description.
+    public let accessibilityLanguage: String?
+
+    /// Whether the element performs an action based on user interaction.
+    public let respondsToUserInteraction: Bool
+
+    // MARK: - Initialization
+
+    init(
+        description: String,
+        label: String?,
+        value: String?,
+        traits: UIAccessibilityTraits,
+        identifier: String?,
+        hint: String?,
+        userInputLabels: [String]?,
+        shape: Shape,
+        activationPoint: CGPoint,
+        usesDefaultActivationPoint: Bool,
+        customActions: [CustomAction],
+        customContent: [CustomContent],
+        customRotors: [CustomRotor],
+        accessibilityLanguage: String?,
+        respondsToUserInteraction: Bool
+    ) {
+        self.description = description
+        self.label = label
+        self.value = value
+        self.traits = traits
+        self.identifier = identifier
+        self.hint = hint
+        self.userInputLabels = userInputLabels
+        self.shape = shape
+        self.activationPoint = activationPoint
+        self.usesDefaultActivationPoint = usesDefaultActivationPoint
+        self.customActions = customActions
+        self.customContent = customContent
+        self.customRotors = customRotors
+        self.accessibilityLanguage = accessibilityLanguage
+        self.respondsToUserInteraction = respondsToUserInteraction
+    }
+}