Make transforms chained on a tag reference move it in the local frame

Direct chains on a tag (e.g. tag.translated(x: 10)) used to be silently
cancelled by the world-anchor logic, which was a common source of
confusion. Tag now overrides transformed(_:) to return a TagReference
that composes successive transforms and applies them to the
world-anchored geometry in the local coordinate frame at the call
site — matching how transforms behave on regular geometry. Outer
wrappers (transforms applied to a parent containing a reference) still
flow through the environment and are cancelled, preserving the world
anchor for that case.

Expanded the doc comments to explain the two cases with examples.

Author: tomasf

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

@@ -16,9 +16,45 @@ import Foundation
 ///     “used” in the current tree so it can be resolved in a later pass. If a tag remains unresolved at the top level,
 ///     a warning is printed.
 ///
-/// - Coordinate systems:
-///   - Referencing a tag reproduces the tagged geometry at the same world-space location and orientation it had at the
-///     time of tagging. This means the geometry appears where you would expect, relative to the current transform context.
+/// ## World-anchored references
+///
+/// A tag reference reproduces its geometry at the world-space position it had at the time of tagging,
+/// **regardless of where the reference appears in the tree**. This is the central property of tags:
+/// they are anchored to a captured world position, so transforms applied to ancestor geometry around
+/// a reference do not move it.
+///
+/// ```swift
+/// let part = Tag()
+/// let model = Box(1)
+///     .translated(x: 5)         // tagged box is at world (5...6)
+///     .tagged(part)
+///     .adding {
+///         // The Union below would normally translate everything inside it by +100,
+///         // but the reference stays anchored at its captured world position (5...6).
+///         Union { part }.translated(x: 100)
+///     }
+/// ```
+///
+/// ## Transforms applied directly to a reference
+///
+/// Transforms chained directly onto a tag reference *do* move it. They are applied in the
+/// **local coordinate frame** at the call site — the same way transforms on regular geometry behave:
+///
+/// ```swift
+/// part.translated(x: 10)              // reference moves +10 along local X
+/// part.translated(x: 10).rotated(...) // chained transforms compose in local frame
+/// ```
+///
+/// If the reference sits inside a rotated parent, the direct transforms see that rotation as the
+/// local frame, so `.translated(x: 10)` moves along the parent's local X — not world X.
+///
+/// The distinction is:
+/// - **Direct chains** on a tag/reference (via `translated`, `rotated`, etc.) compose into a single
+///   transform and move the reference, in the local frame.
+/// - **Outer wrappers** (transforms applied to a parent containing a reference) flow through the
+///   environment and are cancelled, preserving the world anchor.
+///
+/// This means `tag.translated(x: 10)` translates; but `Group { tag }.translated(x: 10)` does not.
 ///
 public struct Tag: Hashable, Sendable {
     internal let id = UUID()
@@ -43,8 +79,16 @@ public struct Tag: Hashable, Sendable {
 public extension Geometry3D {
     /// Attaches a tag to this geometry, allowing it to be referenced elsewhere in the same model.
     ///
-    /// The tagged geometry is recorded in its current coordinate system so that later references to the tag reproduce
-    /// the same geometry at the same world-space location and orientation.
+    /// The tagged geometry is recorded in its **current** coordinate system, meaning the world-space position
+    /// it has at the point where `tagged(_:)` is called — including any transforms applied to it earlier in
+    /// the chain. References to this tag later reproduce the geometry at that same world position.
+    ///
+    /// ```swift
+    /// // The tagged box is captured at world (5...6) — the translation is part of the anchor.
+    /// Box(1).translated(x: 5).tagged(myTag)
+    /// ```
+    ///
+    /// See ``Tag`` for how references behave when transforms are applied to them.
     ///
     /// - Multiple definitions:
     ///   - You can tag multiple geometries with the same `Tag`. When that tag is referenced, all tagged geometries are
@@ -64,6 +108,10 @@ public extension Geometry3D {
 /// location and orientation it had at the time of tagging. If the tag was applied to multiple geometries,
 /// the referenced result is the merged (unioned) combination of all of them.
 ///
+/// Transforms applied to ancestor geometry around the reference are cancelled by the world-anchor logic,
+/// while transforms chained directly onto the reference (via `translated`, `rotated`, etc.) move it
+/// relative to its anchor. See ``Tag`` for a full discussion of these two cases.
+///
 /// - Undefined tags:
 ///   - If the tag has not yet been defined in the model, this produces an empty geometry placeholder and marks the
 ///     tag as “used” so it can be resolved in a later pass. If the tag is still undefined at the top level, a
@@ -78,6 +126,48 @@ extension Tag: Geometry {
         return try await context.buildResult(for: output, in: environment)
             .modifyingElement(ReferenceState.self) { $0.read(tag: self) }
     }
+
+    /// Applies a transform to this tag reference.
+    ///
+    /// Transforms chained directly onto a tag reference (e.g. `tag.translated(x: 10)`) are applied
+    /// to the world-anchored geometry, so they move it as expected. Transforms applied to a parent
+    /// geometry that contains a tag reference still flow through the environment and are cancelled
+    /// by the world-anchor logic, preserving the captured position.
+    ///
+    public func transformed(_ transform: Transform3D) -> any Geometry3D {
+        if transform.isIdentity {
+            return self
+        }
+        return TagReference(tag: self, transform: transform)
+    }
+}
+
+/// A tag reference with applied modifications.
+///
+/// Currently this carries an explicit transform; additional kinds of per-reference modifications
+/// (e.g. material or color overrides) can be added here without affecting `Tag`'s identity semantics.
+///
+internal struct TagReference: Geometry {
+    let tag: Tag
+    let transform: Transform3D
+
+    func transformed(_ additional: Transform3D) -> any Geometry3D {
+        if additional.isIdentity {
+            return self
+        }
+        return TagReference(tag: tag, transform: transform.transformed(additional))
+    }
+
+    func build(in environment: EnvironmentValues, context: EvaluationContext) async throws -> D3.BuildResult {
+        let output = Union {
+            environment.buildResults(for: tag)
+        }
+        .transformed(environment.transform.inverse)
+        .transformed(transform)
+
+        return try await context.buildResult(for: output, in: environment)
+            .modifyingElement(ReferenceState.self) { $0.read(tag: tag) }
+    }
 }
 
 public extension Tag {

Tests/Tests/Tags.swift

@@ -92,6 +92,114 @@ struct TagTests {
         #expect(try await geometry.measurements.volume ≈ 21)
     }
 
+    @Test func `direct transform on tag reference translates it`() async throws {
+        let t = Tag()
+        let geometry = Box(1)
+            .tagged(t)
+            .adding {
+                t.translated(x: 10)
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum ≈ [0, 0, 0])
+        #expect(bounds?.maximum ≈ [11, 1, 1])
+    }
+
+    @Test func `chained transforms on tag reference compose`() async throws {
+        let t = Tag()
+        let geometry = Box(2)
+            .tagged(t)
+            .adding {
+                t.translated(x: 10).translated(y: 5)
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum ≈ [0, 0, 0])
+        #expect(bounds?.maximum ≈ [12, 7, 2])
+    }
+
+    @Test func `rotation chained with translation on tag reference applies in order`() async throws {
+        // Box(2,1,1) rotated 90° around z: (x,y,z) → (-y, x, z), so corners (0..2, 0..1, 0..1)
+        // become (-1..0, 0..2, 0..1). Then translated by x:5 → (4..5, 0..2, 0..1).
+        let t = Tag()
+        let geometry = Box([2, 1, 1])
+            .tagged(t)
+            .adding {
+                t.rotated(z: 90°).translated(x: 5)
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum.x ≈ 0)
+        #expect(bounds?.maximum.x ≈ 5)
+        #expect(bounds?.minimum.y ≈ 0)
+        #expect(bounds?.maximum.y ≈ 2)
+    }
+
+    @Test func `tag world anchor reflects tagged geometry's own transform`() async throws {
+        // Tagged geometry was already translated by x:5 when tagged, so its world position is x:5..6.
+        // The reference then translates that by an additional x:10 → x:15..16.
+        let t = Tag()
+        let geometry = Box(1)
+            .translated(x: 5)
+            .tagged(t)
+            .adding {
+                t.translated(x: 10)
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum ≈ [5, 0, 0])
+        #expect(bounds?.maximum ≈ [16, 1, 1])
+    }
+
+    @Test func `outer transform around a tag reference is cancelled by world anchor`() async throws {
+        // Wrapping the tag reference inside a group and translating the group should NOT move
+        // the reference — the world anchor is preserved. Only direct chains on the tag/modified
+        // reference move it.
+        let t = Tag()
+        let geometry = Box(1)
+            .tagged(t)
+            .adding {
+                Union { t }.translated(x: 100)
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum ≈ [0, 0, 0])
+        #expect(bounds?.maximum ≈ [1, 1, 1])
+    }
+
+    @Test func `tag translation applies in local frame of containing rotation`() async throws {
+        // Tag captured at world (0..1, 0..1, 0..1). Inside a parent rotated by z:90°, the local +X
+        // axis points along world +Y. So `.translated(x: 10)` on the reference should move it by
+        // +10 in world Y, not in world X.
+        let t = Tag()
+        let geometry = Box(1)
+            .tagged(t)
+            .adding {
+                Union { t.translated(x: 10) }.rotated(z: 90°)
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum.x ≈ 0)
+        #expect(bounds?.maximum.x ≈ 1)
+        #expect(bounds?.minimum.y ≈ 0)
+        #expect(bounds?.maximum.y ≈ 11)
+    }
+
+    @Test func `outer transform around a modified tag reference is also cancelled`() async throws {
+        // Same as above, but with a direct chain on the tag first. The direct chain should still
+        // take effect; the outer group translate is cancelled.
+        let t = Tag()
+        let geometry = Box(1)
+            .tagged(t)
+            .adding {
+                Union { t.translated(x: 10) }.translated(x: 100)
+            }
+
+        let bounds = try await geometry.bounds
+        #expect(bounds?.minimum ≈ [0, 0, 0])
+        #expect(bounds?.maximum ≈ [11, 1, 1])
+    }
+
     @Test func `tag can map each member separately`() async throws {
         let sharedTag = Tag("shared tag")