Add container visualization for accessibility snapshot legends

When showContainers is enabled in the configuration, the legend renders
a hierarchical view that groups elements by their accessibility
containers using dashed borders and container badges.

Scope: legend-only. All element overlay rendering (ElementOverlay,
positions, colors, coordinates) is completely unchanged. The snapshot
image and its overlays are rendered identically regardless of
showContainers — only the legend content differs.

New files:
- HierarchyColorAssignment: assigns color indices to hierarchy nodes
  (elements use traversal-order position to match overlay colors;
  containers use a separate counter)
- ContainerLegendEntryView: dashed-border legend entry with a badge
  that displays the container type (Semantic Group/List/Landmark/
  Data Table/Tab Bar) or its label/value/identifier
- HierarchyLegendView: recursive hierarchical legend renderer
- ContainerDemo: demo using SemanticGroupWrapper to create real UIKit
  accessibility containers from a SwiftUI demo (SwiftUI has no native
  equivalent for UIAccessibilityContainerType.semanticGroup)

Changes:
- AccessibilitySnapshotConfiguration: add showContainers flag
- ParsedAccessibilityData: add hierarchy tree alongside flat markers
- PreParsedAccessibilitySnapshotView: swap legend based on showContainers;
  snapshot+overlay section untouched
- SwiftUIAccessibilitySnapshotContainerView: pass hierarchy through

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: RoyalPineapple

Example/AccessibilitySnapshotPreviewsDemo/ContainerDemo.swift

@@ -0,0 +1,107 @@
+import AccessibilitySnapshotPreviews
+import SwiftUI
+import UIKit
+
+struct ContainerDemo: View {
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            DemoSection(title: "Account Info", description: "Semantic group container") {
+                Text("Balance: $1,234.56")
+                Text("Last updated: Today")
+            }
+            .semanticGroupContainer(label: "Account Info")
+
+            DemoSection(title: "Transactions", description: "Another semantic group") {
+                Text("Coffee Shop - $4.50")
+                Text("Grocery Store - $52.30")
+                Text("Gas Station - $35.00")
+            }
+            .semanticGroupContainer(label: "Transactions")
+
+            Button("View All Transactions") {}
+                .buttonStyle(.bordered)
+
+            Spacer()
+        }
+        .padding()
+    }
+}
+
+// MARK: - Semantic Group Container
+
+/// A SwiftUI modifier that wraps the content in a UIKit view with
+/// `accessibilityContainerType = .semanticGroup`, since SwiftUI has no native equivalent.
+private extension View {
+    func semanticGroupContainer(label: String? = nil) -> some View {
+        SemanticGroupWrapper(label: label) { self }
+    }
+}
+
+private struct SemanticGroupWrapper<Content: View>: UIViewRepresentable {
+    let label: String?
+    let content: Content
+
+    init(label: String?, @ViewBuilder content: () -> Content) {
+        self.label = label
+        self.content = content()
+    }
+
+    func makeUIView(context: Context) -> SemanticGroupUIView {
+        let container = SemanticGroupUIView()
+        container.accessibilityLabel = label
+
+        let hosting = UIHostingController(rootView: content)
+        hosting.view.backgroundColor = .clear
+        hosting.view.translatesAutoresizingMaskIntoConstraints = false
+        container.addSubview(hosting.view)
+        NSLayoutConstraint.activate([
+            hosting.view.topAnchor.constraint(equalTo: container.topAnchor),
+            hosting.view.bottomAnchor.constraint(equalTo: container.bottomAnchor),
+            hosting.view.leadingAnchor.constraint(equalTo: container.leadingAnchor),
+            hosting.view.trailingAnchor.constraint(equalTo: container.trailingAnchor),
+        ])
+        context.coordinator.hostingController = hosting
+        return container
+    }
+
+    func updateUIView(_ uiView: SemanticGroupUIView, context: Context) {
+        context.coordinator.hostingController?.rootView = content
+        uiView.accessibilityLabel = label
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
+
+    class Coordinator {
+        var hostingController: UIHostingController<Content>?
+    }
+}
+
+/// A UIView that reports itself as a semantic group accessibility container.
+private class SemanticGroupUIView: UIView {
+    override var accessibilityContainerType: UIAccessibilityContainerType {
+        get { .semanticGroup }
+        set {}
+    }
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        isAccessibilityElement = false
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError() }
+}
+
+// MARK: - Previews
+
+#Preview {
+    ContainerDemo()
+        .accessibilityPreview()
+}
+
+#Preview("Containers") {
+    ContainerDemo()
+        .accessibilityPreview(
+            configuration: .init(viewRenderingMode: .drawHierarchyInRect, showContainers: true)
+        )
+}

Example/AccessibilitySnapshotPreviewsTests/AccessibilitySnapshotPreviewsTestCase.swift

@@ -1,3 +1,4 @@
+import AccessibilitySnapshotCore
 import FBSnapshotTestCase_Accessibility
 import iOSSnapshotTestCase
 
@@ -35,17 +36,30 @@ class AccessibilitySnapshotPreviewsTestCase: FBSnapshotTestCase {
     func snapshotVerifyAccessibility<V: View>(
         _ view: V,
         identifier: String = "",
+        configuration: AccessibilitySnapshotConfiguration? = nil,
         file: StaticString = #file,
         line: UInt = #line
     ) {
-        SnapshotVerifyAccessibility(
-            view,
-            size: UIScreen.main.bounds.size,
-            identifier: identifier,
-            layoutEngine: .swiftui,
-            file: file,
-            line: line
-        )
+        if let configuration {
+            SnapshotVerifyAccessibility(
+                view,
+                size: UIScreen.main.bounds.size,
+                identifier: identifier,
+                layoutEngine: .swiftui,
+                snapshotConfiguration: configuration,
+                file: file,
+                line: line
+            )
+        } else {
+            SnapshotVerifyAccessibility(
+                view,
+                size: UIScreen.main.bounds.size,
+                identifier: identifier,
+                layoutEngine: .swiftui,
+                file: file,
+                line: line
+            )
+        }
     }
 
     // MARK: - Configuration
@@ -59,6 +73,7 @@ class AccessibilitySnapshotPreviewsTestCase: FBSnapshotTestCase {
     private static let testedDevices = [
         TestDeviceConfig(systemVersion: "18.5", screenSize: CGSize(width: 402, height: 874), screenScale: 3),
         TestDeviceConfig(systemVersion: "26.2", screenSize: CGSize(width: 402, height: 874), screenScale: 3),
+        TestDeviceConfig(systemVersion: "26.4", screenSize: CGSize(width: 402, height: 874), screenScale: 3),
     ]
 
     override func setUp() {

Example/AccessibilitySnapshotPreviewsTests/ReferenceImages/_64/AccessibilitySnapshotPreviewsTests.SwiftUIRendererTests/testContainerDemoWithoutContainers_no_containers_26_4_402x874@3x.png

@@ -1,3 +1,4 @@
+import AccessibilitySnapshotCore
 @testable import AccessibilitySnapshotPreviewsDemo
 
 @available(iOS 16.0, *)
@@ -25,4 +26,18 @@ final class SwiftUIRendererTests: AccessibilitySnapshotPreviewsTestCase {
     func testUnspokenTraitsDemo() {
         snapshotVerifyAccessibility(UnspokenTraitsDemoView())
     }
+
+    func testContainerDemoWithoutContainers() {
+        snapshotVerifyAccessibility(
+            ContainerDemo(),
+            identifier: "no_containers"
+        )
+    }
+
+    func testContainerDemo() {
+        snapshotVerifyAccessibility(
+            ContainerDemo(),
+            configuration: .init(viewRenderingMode: .renderLayerInContext, showContainers: true)
+        )
+    }
 }

Example/AccessibilitySnapshotPreviewsTests/ReferenceImages/_64/AccessibilitySnapshotPreviewsTests.SwiftUIRendererTests/testContainerDemo_26_4_402x874@3x.png

@@ -0,0 +1,89 @@
+import AccessibilitySnapshotCore
+import AccessibilitySnapshotParser
+import SwiftUI
+
+/// A legend entry for an accessibility container, with its children inside a dashed border.
+@available(iOS 16.0, *)
+struct ContainerLegendEntryView: View {
+    let index: Int
+    let container: AccessibilityContainer
+    let palette: ColorPalette
+    let childViews: AnyView
+
+    private static let containerInset: CGFloat = 10
+    private let badgeHeight: CGFloat = DesignTokens.Badge.minSize
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            Color.clear
+                .frame(height: badgeHeight / 2)
+
+            VStack(alignment: .leading, spacing: LegendLayoutMetrics.legendVerticalSpacing) {
+                childViews
+            }
+            .padding(Self.containerInset)
+            .padding(.top, badgeHeight / 2)
+            .overlay(
+                RoundedRectangle(cornerRadius: DesignTokens.Element.legendCornerRadius)
+                    .stroke(
+                        palette.strokeColor(at: index),
+                        style: StrokeStyle(lineWidth: DesignTokens.Element.strokeWidth, dash: [4, 4])
+                    )
+            )
+            .overlay(alignment: .topLeading) {
+                ContainerBadge(index: index, container: container, palette: palette)
+                    .offset(
+                        x: Self.containerInset,
+                        y: -badgeHeight / 2
+                    )
+            }
+        }
+    }
+}
+
+/// A badge for container entries that includes a layer icon, number, and container label.
+@available(iOS 16.0, *)
+struct ContainerBadge: View {
+    let index: Int
+    let container: AccessibilityContainer
+    let palette: ColorPalette
+
+    var body: some View {
+        HStack(spacing: 2) {
+            Image(systemName: "square.on.square")
+                .font(.system(size: 8, weight: .bold))
+                .foregroundColor(.white)
+
+            Text(displayName)
+                .font(DesignTokens.Typography.badgeNumber)
+                .foregroundColor(.white)
+        }
+        .padding(.horizontal, 4)
+        .frame(minHeight: DesignTokens.Badge.minSize)
+        .background(
+            RoundedRectangle(cornerRadius: DesignTokens.Badge.cornerRadius)
+                .fill(palette.color(at: index))
+        )
+    }
+
+    private var displayName: String {
+        switch container.type {
+        case let .semanticGroup(label, value, identifier):
+            let parts = [label, value].compactMap { $0?.isEmpty == false ? $0 : nil }
+            if !parts.isEmpty {
+                return parts.joined(separator: ": ")
+            } else if let identifier, !identifier.isEmpty {
+                return identifier
+            }
+            return "Semantic Group"
+        case .list:
+            return "List"
+        case .landmark:
+            return "Landmark"
+        case let .dataTable(rowCount, columnCount):
+            return "Data Table (\(rowCount) × \(columnCount))"
+        case .tabBar:
+            return "Tab Bar"
+        }
+    }
+}

Example/AccessibilitySnapshotPreviewsTests/SwiftUIRendererTests.swift

@@ -0,0 +1,62 @@
+import AccessibilitySnapshotCore
+import AccessibilitySnapshotParser
+
+/// Assigns color indices to containers and elements in the hierarchy.
+///
+/// Elements use their position in the sorted traversal order (matching the `markers` array
+/// and overlay indices). Containers use a separate sequential counter starting at 0, so
+/// elements and containers cycle through palette colors independently.
+@available(iOS 16.0, *)
+public struct HierarchyColorAssignment {
+    /// A node with its assigned color index.
+    public enum AssignedNode {
+        case element(AccessibilityElement, colorIndex: Int)
+        case container(AccessibilityContainer, colorIndex: Int, children: [AssignedNode])
+    }
+
+    /// The assigned nodes in hierarchy order.
+    public let nodes: [AssignedNode]
+
+    /// Builds color assignments from a hierarchy tree.
+    public static func build(from hierarchy: [AccessibilityHierarchy]) -> HierarchyColorAssignment {
+        var containerCounter = 0
+
+        // Map each element's traversal index to its position in the sorted
+        // markers array. This ensures legend colors match overlay colors.
+        var traversalIndexToPosition: [Int: Int] = [:]
+        var allTraversalIndices: [Int] = []
+        func collectTraversalIndices(_ nodes: [AccessibilityHierarchy]) {
+            for node in nodes {
+                switch node {
+                case let .element(_, traversalIndex):
+                    allTraversalIndices.append(traversalIndex)
+                case let .container(_, children):
+                    collectTraversalIndices(children)
+                }
+            }
+        }
+        collectTraversalIndices(hierarchy)
+        for (position, traversalIndex) in allTraversalIndices.sorted().enumerated() {
+            traversalIndexToPosition[traversalIndex] = position
+        }
+
+        func assign(_ nodes: [AccessibilityHierarchy]) -> [AssignedNode] {
+            nodes.map { node in
+                switch node {
+                case let .container(container, children):
+                    let index = containerCounter
+                    containerCounter += 1
+                    let assignedChildren = assign(children)
+                    return .container(container, colorIndex: index, children: assignedChildren)
+
+                case let .element(element, traversalIndex):
+                    let index = traversalIndexToPosition[traversalIndex] ?? 0
+                    return .element(element, colorIndex: index)
+                }
+            }
+        }
+
+        let assignedNodes = assign(hierarchy)
+        return HierarchyColorAssignment(nodes: assignedNodes)
+    }
+}

Sources/AccessibilitySnapshot/AccessibilitySnapshotPreviews/ContainerLegendEntryView.swift

@@ -0,0 +1,48 @@
+import AccessibilitySnapshotCore
+import AccessibilitySnapshotParser
+import SwiftUI
+
+/// Renders a hierarchical legend from assigned nodes, with containers wrapping their children.
+@available(iOS 16.0, *)
+struct HierarchyLegendView: View {
+    let nodes: [HierarchyColorAssignment.AssignedNode]
+    let palette: ColorPalette
+    let showUserInputLabels: Bool
+    let showUnspokenTraits: Bool
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: LegendLayoutMetrics.legendVerticalSpacing) {
+            ForEach(nodes.indices, id: \.self) { i in
+                nodeView(for: nodes[i])
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func nodeView(for node: HierarchyColorAssignment.AssignedNode) -> some View {
+        switch node {
+        case let .element(element, colorIndex):
+            LegendEntryView(
+                index: colorIndex,
+                marker: element,
+                palette: palette,
+                showUserInputLabels: showUserInputLabels,
+                showUnspokenTraits: showUnspokenTraits
+            )
+
+        case let .container(container, colorIndex, children):
+            ContainerLegendEntryView(
+                index: colorIndex,
+                container: container,
+                palette: palette,
+                childViews: AnyView(
+                    VStack(alignment: .leading, spacing: LegendLayoutMetrics.legendVerticalSpacing) {
+                        ForEach(children.indices, id: \.self) { i in
+                            nodeView(for: children[i])
+                        }
+                    }
+                )
+            )
+        }
+    }
+}

Sources/AccessibilitySnapshot/AccessibilitySnapshotPreviews/HierarchyColorAssignment.swift

@@ -39,6 +39,7 @@ public final class SwiftUIAccessibilitySnapshotContainerView: AccessibilitySnaps
         let swiftUIView = PreParsedAccessibilitySnapshotView(
             snapshotImage: data.image,
             markers: data.markers,
+            hierarchy: data.hierarchy,
             configuration: snapshotConfiguration,
             palette: palette,
             renderSize: data.containedViewBounds