Add APIs for reading individual tag members

Author: tomasf

Sources/Cadova/Abstract Layer/Geometry/References/Tag.swift

@@ -80,6 +80,52 @@ extension Tag: Geometry {
     }
 }
 
+public extension Tag {
+    /// Reads the individual geometry members associated with this tag and provides them for further composition.
+    ///
+    /// This is similar to using the tag directly as geometry, except the tagged definitions are passed to the
+    /// `reader` closure as separate geometries instead of being unioned first. Each geometry is positioned in the
+    /// same coordinate system as a direct tag reference, preserving the world-space transform captured when tagged.
+    ///
+    /// - Parameter reader: A closure that receives all geometries currently associated with this tag.
+    /// - Returns: A geometry object resulting from the `reader` closure.
+    func readingMembers<Output: Dimensionality>(
+        @GeometryBuilder<Output> _ reader: @Sendable @escaping (_ members: [D3.Geometry]) -> Output.Geometry
+    ) -> Output.Geometry {
+        TagGeometryReader(tag: self, reader: reader)
+    }
+
+    /// Applies a transform to each individual geometry member associated with this tag and unions the results.
+    ///
+    /// This is a convenience wrapper around `readingMembers` for the common case where every tagged definition should
+    /// be processed independently.
+    ///
+    /// - Parameter transform: A closure called once for each tagged geometry member.
+    /// - Returns: The union of all geometries returned by `transform`.
+    func map<Output: Dimensionality>(
+        @GeometryBuilder<Output> _ transform: @Sendable @escaping (_ member: D3.Geometry) -> Output.Geometry
+    ) -> Output.Geometry {
+        readingMembers { members in
+            for member in members {
+                transform(member)
+            }
+        }
+    }
+}
+
+internal struct TagGeometryReader<Output: Dimensionality>: Geometry {
+    let tag: Tag
+    let reader: @Sendable ([D3.Geometry]) -> Output.Geometry
+
+    func build(in environment: EnvironmentValues, context: EvaluationContext) async throws -> Output.BuildResult {
+        let geometries = environment.buildResults(for: tag).map {
+            $0.transformed(environment.transform.inverse)
+        }
+        return try await context.buildResult(for: reader(geometries), in: environment)
+            .modifyingElement(ReferenceState.self) { $0.read(tag: tag) }
+    }
+}
+
 internal struct TagGeometry: Geometry {
     let body: any Geometry3D
     let tag: Tag

Tests/Tests/Tags.swift

@@ -57,4 +57,62 @@ struct TagTests {
 
         #expect(try await geometry.measurements.volume ≈ 19)
     }
+
+    @Test func `tag can read definitions as separate members`() async throws {
+        let sharedTag = Tag("shared tag")
+
+        let geometry = Box(x: 21, y: 1, z: 1)
+            .subtracting {
+                sharedTag
+            }
+            .adding {
+                Box(1)
+                    .tagged(sharedTag)
+                    .subtracting { Box(1) }
+                    .translated(x: 5)
+            }
+            .adding {
+                Box(1)
+                    .tagged(sharedTag)
+                    .subtracting { Box(1) }
+                    .translated(x: 15)
+            }
+            .adding {
+                sharedTag.readingMembers { members in
+                    for (index, member) in members.enumerated() {
+                        member.translated(y: Double(index) * 10)
+                    }
+                }
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum.x ≈ 0)
+        #expect(bounds?.maximum.x ≈ 21)
+        #expect(bounds?.maximum.y ≈ 11)
+        #expect(try await geometry.measurements.volume ≈ 21)
+    }
+
+    @Test func `tag can map each member separately`() async throws {
+        let sharedTag = Tag("shared tag")
+
+        let geometry = Box(1)
+            .tagged(sharedTag)
+            .translated(x: 5)
+            .adding {
+                Box(1)
+                    .tagged(sharedTag)
+                    .translated(x: 15)
+            }
+            .adding {
+                sharedTag.map { member in
+                    member.translated(z: 10)
+                }
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum.x ≈ 5)
+        #expect(bounds?.maximum.x ≈ 16)
+        #expect(bounds?.maximum.z ≈ 11)
+        #expect(try await geometry.measurements.volume ≈ 4)
+    }
 }