From e4325f72406268a3a0b697f1c5153ab54cd8fb57 Mon Sep 17 00:00:00 2001
From: Leo Dion <leogdion@brightdigit.com>
Date: Mon, 3 Aug 2026 06:44:12 -0400
Subject: [PATCH 1/5] Fix #36: lift .anchor onto StoryItem and make DSLNode
 public
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`.anchor(lane:offset:content:)` was declared only on `AssetClip`, so nothing
could be anchored onto a generator or a color. A media-free slide deck needs
exactly that: text over a solid color background.

Introduce `StoryItem` — "content that can sit in a spine", matching the DTD's
`%clip_item;` entity — and hang the shared `.anchor` modifier off it.
`AssetClip`, `Generator`, `Title`, `Gap`, and `Transition` conform directly.
`Color` promotes to `Generator`, since it is a model type in another module
and cannot gain stored properties; `Color.build` already desugared that way,
so anchoring just performs the desugaring one step earlier.

A public protocol requirement cannot mention internal types, so `DSLNode`,
`Built`, and `ResourceStore` become public. Every `ResourceStore` member stays
internal, so only the type name is exposed and no usable extension point ships.

Anchoring onto a `Transition` is accepted but never emitted: the DTD does not
admit anchored items there. Pinned by a test so it stays documented behavior
rather than something a later change "fixes" into a throw.

Also fixes a latent bug: `.anchor` replaced rather than appended, so chained
calls silently dropped earlier lanes. The shared modifier now appends, and
`replacingAnchors` is documented as the pure setter it is. This was latent
because nothing chained; `StoryItem` makes chaining the natural idiom.

Adds the missing `.video` and `.generator` cases to `anchoredExtent`, so an
anchored generator contributes to its parent's extent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 Sources/FCPKitDSL/AnchoredItemBuilder.swift   |  54 ++++++
 Sources/FCPKitDSL/AssetClip+Modifiers.swift   |  15 --
 Sources/FCPKitDSL/AssetClip.swift             |  29 ++--
 Sources/FCPKitDSL/Built.swift                 |  11 +-
 Sources/FCPKitDSL/Color+DSL.swift             |  24 ++-
 Sources/FCPKitDSL/DSLNode.swift               |  14 +-
 Sources/FCPKitDSL/DocumentGroup.swift         |   3 +-
 Sources/FCPKitDSL/Event.swift                 |   3 +-
 Sources/FCPKitDSL/Gap.swift                   |  23 ++-
 Sources/FCPKitDSL/Generator+Modifiers.swift   |  37 +++++
 Sources/FCPKitDSL/Generator.swift             |  29 +++-
 Sources/FCPKitDSL/Layout+Packing.swift        |   8 +
 Sources/FCPKitDSL/Library.swift               |   3 +-
 Sources/FCPKitDSL/Project.swift               |   3 +-
 Sources/FCPKitDSL/ResourceStore.swift         |   7 +-
 Sources/FCPKitDSL/Sequence.swift              |   3 +-
 Sources/FCPKitDSL/Spine.swift                 |   3 +-
 Sources/FCPKitDSL/StoryItem.swift             |  86 ++++++++++
 Sources/FCPKitDSL/Title.swift                 |  71 ++++++--
 Sources/FCPKitDSL/Transition.swift            |  16 +-
 .../StoryItemAnchorErrorTests.swift           | 102 ++++++++++++
 Tests/FCPKitDSLTests/StoryItemDoc.swift       |  44 +++++
 Tests/FCPKitDSLTests/StoryItemSupport.swift   |  65 ++++++++
 Tests/FCPKitDSLTests/StoryItemTests.swift     | 155 ++++++++++++++++++
 24 files changed, 734 insertions(+), 74 deletions(-)
 create mode 100644 Sources/FCPKitDSL/AnchoredItemBuilder.swift
 create mode 100644 Sources/FCPKitDSL/Generator+Modifiers.swift
 create mode 100644 Sources/FCPKitDSL/StoryItem.swift
 create mode 100644 Tests/FCPKitDSLTests/StoryItemAnchorErrorTests.swift
 create mode 100644 Tests/FCPKitDSLTests/StoryItemDoc.swift
 create mode 100644 Tests/FCPKitDSLTests/StoryItemSupport.swift
 create mode 100644 Tests/FCPKitDSLTests/StoryItemTests.swift

diff --git a/Sources/FCPKitDSL/AnchoredItemBuilder.swift b/Sources/FCPKitDSL/AnchoredItemBuilder.swift
new file mode 100644
index 0000000..573da88
--- /dev/null
+++ b/Sources/FCPKitDSL/AnchoredItemBuilder.swift
@@ -0,0 +1,54 @@
+//
+//  AnchoredItemBuilder.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+
+/// Lowers a single anchor node into the DTD's `%anchor_item;` entity.
+internal func anchoredItem(
+  _ node: any DSLNode,
+  resources: inout ResourceStore
+) throws -> FCPKit.AnchoredItem {
+  switch try node.build(&resources) {
+  case .item(.title(let title)): return .title(title)
+  case .item(.assetClip(let clip)): return .assetClip(clip)
+  case .item(.generator(let gen)): return .generator(gen)
+  case .item(.video(let vid)): return .video(vid)
+  case .spine(let spine): return .spine(spine)
+  default: throw BuildError.unsupportedContent
+  }
+}
+
+/// Lowers a list of anchor nodes, returning `nil` when the list is empty.
+internal func anchoredItems(
+  _ nodes: [any DSLNode],
+  resources: inout ResourceStore
+) throws -> [FCPKit.AnchoredItem]? {
+  let items = try nodes.map { try anchoredItem($0, resources: &resources) }
+  return items.isEmpty ? nil : items
+}
diff --git a/Sources/FCPKitDSL/AssetClip+Modifiers.swift b/Sources/FCPKitDSL/AssetClip+Modifiers.swift
index 110cdbd..b4b55c2 100644
--- a/Sources/FCPKitDSL/AssetClip+Modifiers.swift
+++ b/Sources/FCPKitDSL/AssetClip+Modifiers.swift
@@ -34,19 +34,4 @@ extension AssetClip {
   public func audioRole(_ role: String) -> AssetClip {
     replacing(audioRole: role)
   }
-  /// Anchors content on a connected lane. `lane` must be nonzero.
-  public func anchor(
-    lane: Int,
-    offset: FCPTime = .zero,
-    @DocumentBuilder content: () -> DocumentGroup
-  ) -> AssetClip {
-    replacing(
-      anchors: content().contents.compactMap { value in
-        guard let node = value as? any DSLNode else {
-          return nil
-        }
-        return Anchor(lane: lane, offset: offset, content: node)
-      }
-    )
-  }
 }
diff --git a/Sources/FCPKitDSL/AssetClip.swift b/Sources/FCPKitDSL/AssetClip.swift
index d0dec80..40a3a7c 100644
--- a/Sources/FCPKitDSL/AssetClip.swift
+++ b/Sources/FCPKitDSL/AssetClip.swift
@@ -31,12 +31,13 @@ import FCPKit
 import Foundation
 
 /// An `asset-clip` story item with optional anchors and audio role.
-public struct AssetClip: DSLNode {
+public struct AssetClip: DSLNode, StoryItem {
   internal let source: AssetSource
   /// Clip duration on the storyline, when set explicitly.
   public let duration: FCPTime?
   internal let name: String?
-  internal let anchors: [any DSLNode]
+  /// The anchors attached to this clip.
+  public let anchors: [any DSLNode]
   internal let audioRole: String?
 
   /// Creates a clip from an ``AssetSource``.
@@ -89,7 +90,13 @@ public struct AssetClip: DSLNode {
     )
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Returns a copy of this clip carrying exactly the given anchors.
+  public func replacingAnchors(_ anchors: [any DSLNode]) -> AssetClip {
+    replacing(anchors: anchors)
+  }
+
+  /// Lowers this clip into an `<asset-clip>` story item.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     let ref = try resources.asset(source)
     guard let value = duration?.description ?? source.asset.duration, FCPTime(value) != nil else {
       throw BuildError.missingDuration(name ?? source.asset.name ?? "asset clip")
@@ -104,8 +111,7 @@ public struct AssetClip: DSLNode {
     if let format = source.format, source.formatOnClip {
       clip.format = try resources.format(FormatPreset(format))
     }
-    let items = try anchors.map { try anchoredItem($0, resources: &resources) }
-    clip.anchoredItems = items.isEmpty ? nil : items
+    clip.anchoredItems = try anchoredItems(anchors, resources: &resources)
     return .item(.assetClip(clip))
   }
 
@@ -118,17 +124,4 @@ public struct AssetClip: DSLNode {
       audioRole: audioRole ?? self.audioRole
     )
   }
-
-  private func anchoredItem(_ node: any DSLNode, resources: inout ResourceStore) throws
-    -> FCPKit.AnchoredItem
-  {
-    switch try node.build(&resources) {
-    case .item(.title(let title)): return .title(title)
-    case .item(.assetClip(let clip)): return .assetClip(clip)
-    case .item(.generator(let gen)): return .generator(gen)
-    case .item(.video(let vid)): return .video(vid)
-    case .spine(let spine): return .spine(spine)
-    default: throw BuildError.unsupportedContent
-    }
-  }
 }
diff --git a/Sources/FCPKitDSL/Built.swift b/Sources/FCPKitDSL/Built.swift
index d0867ae..631f037 100644
--- a/Sources/FCPKitDSL/Built.swift
+++ b/Sources/FCPKitDSL/Built.swift
@@ -29,11 +29,20 @@
 
 import FCPKit
 
-internal enum Built {
+/// The model value a ``DSLNode`` lowers to.
+///
+/// - Warning: The case list is expected to evolve before 1.0.
+public enum Built {
+  /// A built `<library>` element.
   case library(FCPKit.Library)
+  /// A built `<event>` element.
   case event(FCPKit.Event)
+  /// A built `<project>` element.
   case project(FCPKit.Project)
+  /// A built `<sequence>` element.
   case sequence(FCPKit.Sequence)
+  /// A built `<spine>` element.
   case spine(FCPKit.Spine)
+  /// A built story item, such as an asset clip, title, gap, or video.
   case item(FCPKit.SpineItem)
 }
diff --git a/Sources/FCPKitDSL/Color+DSL.swift b/Sources/FCPKitDSL/Color+DSL.swift
index 885042e..6615044 100644
--- a/Sources/FCPKitDSL/Color+DSL.swift
+++ b/Sources/FCPKitDSL/Color+DSL.swift
@@ -40,7 +40,8 @@ extension Color: DSLNode {
     return copy
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this color into a custom solid generator `<video>` story item.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     guard let duration else {
       throw BuildError.missingDuration("color generator")
     }
@@ -48,3 +49,24 @@ extension Color: DSLNode {
     return try generator.build(&resources)
   }
 }
+
+extension Color: StoryItem {
+  /// Always empty: a color carries no anchors until it is promoted to a ``Generator``.
+  public var anchors: [any DSLNode] { [] }
+
+  /// Promotes this color to a ``Generator`` carrying the given anchors.
+  ///
+  /// `Color` is a model type and cannot gain stored properties, so anchoring performs
+  /// the `Color` → `Generator` desugaring one step early. Chaining still works, because
+  /// ``Generator`` is itself a ``StoryItem``.
+  ///
+  /// - Important: Call `.duration(_:)` *before* `.anchor(lane:offset:content:)`. Because
+  ///   `.anchor` cannot throw from builder position, a color with no duration promotes
+  ///   with a zero duration, which surfaces later as ``BuildError/missingDuration`` at
+  ///   `export()`.
+  public func replacingAnchors(_ anchors: [any DSLNode]) -> Generator {
+    Generator(.custom, duration: duration ?? .zero)
+      .color(self)
+      .replacingAnchors(anchors)
+  }
+}
diff --git a/Sources/FCPKitDSL/DSLNode.swift b/Sources/FCPKitDSL/DSLNode.swift
index 1b099e8..ef3b9b2 100644
--- a/Sources/FCPKitDSL/DSLNode.swift
+++ b/Sources/FCPKitDSL/DSLNode.swift
@@ -29,6 +29,18 @@
 
 import FCPKit
 
-internal protocol DSLNode: DocumentContent {
+/// A piece of DSL content that can lower itself into FCPXML model values.
+///
+/// Conformance is an implementation detail of the built-in DSL types. The protocol is
+/// `public` only so that public API such as ``StoryItem`` can name it; the pieces it
+/// hands you (``ResourceStore``) expose no usable members outside this module.
+public protocol DSLNode: DocumentContent {
+  /// Lowers this node into a ``Built`` value, registering any resources it needs.
+  ///
+  /// - Parameter resources: The document's shared resource table, mutated in place as
+  ///   assets, formats, and effects are interned.
+  /// - Returns: The model value this node lowers to.
+  /// - Throws: A ``BuildError`` when the node is incomplete or cannot be represented.
+  /// - Warning: This signature is expected to evolve before 1.0.
   func build(_ resources: inout ResourceStore) throws -> Built
 }
diff --git a/Sources/FCPKitDSL/DocumentGroup.swift b/Sources/FCPKitDSL/DocumentGroup.swift
index e6b45e5..3069d28 100644
--- a/Sources/FCPKitDSL/DocumentGroup.swift
+++ b/Sources/FCPKitDSL/DocumentGroup.swift
@@ -38,7 +38,8 @@ public struct DocumentGroup: DocumentContent, DSLNode {
     self.contents = contents
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this group's single child, or a synthesized spine of its children.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     if contents.count == 1, let node = contents[0] as? any DSLNode {
       return try node.build(&resources)
     }
diff --git a/Sources/FCPKitDSL/Event.swift b/Sources/FCPKitDSL/Event.swift
index c1573bd..11182ee 100644
--- a/Sources/FCPKitDSL/Event.swift
+++ b/Sources/FCPKitDSL/Event.swift
@@ -44,7 +44,8 @@ public struct Event: DSLNode {
     self.content = content()
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this event into an `<event>` containing its promoted projects.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     let built = try content.build(&resources)
     let project = try project(from: built)
     return .event(FCPKit.Event(name: name ?? "Untitled", uid: uid, projects: [project]))
diff --git a/Sources/FCPKitDSL/Gap.swift b/Sources/FCPKitDSL/Gap.swift
index f26763f..bfc750b 100644
--- a/Sources/FCPKitDSL/Gap.swift
+++ b/Sources/FCPKitDSL/Gap.swift
@@ -30,22 +30,37 @@
 import FCPKit
 
 /// A gap on the storyline. Duration is required — set in initializer or via `.duration(...)`.
-public struct Gap: DSLNode {
+public struct Gap: DSLNode, StoryItem {
   /// Gap duration on the storyline, when set.
   public let duration: FCPTime?
+  /// The anchors attached to this gap.
+  public let anchors: [any DSLNode]
 
   /// Creates a gap. Export fails when `duration` is omitted.
   public init(duration: FCPTime? = nil) {
+    self.init(duration: duration, anchors: [])
+  }
+
+  private init(duration: FCPTime?, anchors: [any DSLNode]) {
     self.duration = duration
+    self.anchors = anchors
   }
 
   /// Sets the gap duration.
   public func duration(_ duration: FCPTime) -> Gap {
-    Gap(duration: duration)
+    Gap(duration: duration, anchors: anchors)
+  }
+
+  /// Returns a copy of this gap carrying exactly the given anchors.
+  public func replacingAnchors(_ anchors: [any DSLNode]) -> Gap {
+    Gap(duration: duration, anchors: anchors)
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this gap into a `<gap>` story item.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     guard let duration else { throw BuildError.missingDuration("gap") }
-    return .item(.gap(FCPKit.Gap(duration: duration.description)))
+    var element = FCPKit.Gap(duration: duration.description)
+    element.anchoredItems = try anchoredItems(anchors, resources: &resources)
+    return .item(.gap(element))
   }
 }
diff --git a/Sources/FCPKitDSL/Generator+Modifiers.swift b/Sources/FCPKitDSL/Generator+Modifiers.swift
new file mode 100644
index 0000000..a44f7ed
--- /dev/null
+++ b/Sources/FCPKitDSL/Generator+Modifiers.swift
@@ -0,0 +1,37 @@
+//
+//  Generator+Modifiers.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+
+extension Generator: StoryItem {
+  /// Returns a copy of this generator carrying exactly the given anchors.
+  public func replacingAnchors(_ anchors: [any DSLNode]) -> Generator {
+    replacing(anchors: anchors)
+  }
+}
diff --git a/Sources/FCPKitDSL/Generator.swift b/Sources/FCPKitDSL/Generator.swift
index 9b9dbf1..dfbd3e2 100644
--- a/Sources/FCPKitDSL/Generator.swift
+++ b/Sources/FCPKitDSL/Generator.swift
@@ -41,6 +41,8 @@ public struct Generator: DSLNode {
   internal let params: [ParamElement]
   internal let lane: Int?
   internal let offset: FCPTime?
+  /// The anchors attached to this generator clip.
+  public let anchors: [any DSLNode]
 
   /// Creates a generator clip from a preset and optional duration.
   public init(_ preset: GeneratorPreset = .custom, duration: FCPTime? = nil, name: String? = nil) {
@@ -50,7 +52,8 @@ public struct Generator: DSLNode {
       name: name,
       params: [],
       lane: nil,
-      offset: nil
+      offset: nil,
+      anchors: []
     )
   }
 
@@ -60,7 +63,8 @@ public struct Generator: DSLNode {
     name: String?,
     params: [ParamElement],
     lane: Int?,
-    offset: FCPTime?
+    offset: FCPTime?,
+    anchors: [any DSLNode]
   ) {
     self.preset = preset
     self.duration = duration
@@ -68,6 +72,7 @@ public struct Generator: DSLNode {
     self.params = params
     self.lane = lane
     self.offset = offset
+    self.anchors = anchors
   }
 
   /// Sets the clip duration.
@@ -110,9 +115,16 @@ public struct Generator: DSLNode {
     return replacing(params: updated)
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this generator into a `<video>` story item.
+  ///
+  /// - Throws: ``BuildError/missingDuration(_:)`` when no duration was ever set. This is
+  ///   how a ``Color`` anchored before `.duration(_:)` surfaces at `export()`.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
+    guard duration != .zero else {
+      throw BuildError.missingDuration(name ?? preset.name)
+    }
     let ref = try resources.effect(name: preset.name, uid: preset.uid)
-    let videoElement = FCPKit.Video(
+    var videoElement = FCPKit.Video(
       ref: ResourceRef<AssetKind>(ref.rawValue),
       lane: lane.map(String.init),
       offset: offset?.description ?? "0s",
@@ -121,16 +133,18 @@ public struct Generator: DSLNode {
       duration: duration.description,
       param: params.isEmpty ? nil : params
     )
+    videoElement.anchoredItems = try anchoredItems(anchors, resources: &resources)
     return .item(.video(videoElement))
   }
 
-  private func replacing(
+  internal func replacing(
     preset: GeneratorPreset? = nil,
     duration: FCPTime? = nil,
     name: String? = nil,
     params: [ParamElement]? = nil,
     lane: Int? = nil,
-    offset: FCPTime? = nil
+    offset: FCPTime? = nil,
+    anchors: [any DSLNode]? = nil
   ) -> Generator {
     Generator(
       preset: preset ?? self.preset,
@@ -138,7 +152,8 @@ public struct Generator: DSLNode {
       name: name ?? self.name,
       params: params ?? self.params,
       lane: lane ?? self.lane,
-      offset: offset ?? self.offset
+      offset: offset ?? self.offset,
+      anchors: anchors ?? self.anchors
     )
   }
 }
diff --git a/Sources/FCPKitDSL/Layout+Packing.swift b/Sources/FCPKitDSL/Layout+Packing.swift
index f2186b8..196878b 100644
--- a/Sources/FCPKitDSL/Layout+Packing.swift
+++ b/Sources/FCPKitDSL/Layout+Packing.swift
@@ -173,6 +173,14 @@ extension Layout {
         let offset = (try? ticks(clip.offset ?? "0s", denominator, "asset clip")) ?? 0
         let duration = (try? ticks(clip.duration, denominator, "asset clip")) ?? 0
         return max(result, offset + duration)
+      case .video(let video):
+        let offset = (try? ticks(video.offset ?? "0s", denominator, "video")) ?? 0
+        let duration = (try? ticks(video.duration, denominator, "video")) ?? 0
+        return max(result, offset + duration)
+      case .generator(let gen):
+        let offset = (try? ticks(gen.offset ?? "0s", denominator, "generator")) ?? 0
+        let duration = (try? ticks(gen.duration, denominator, "generator")) ?? 0
+        return max(result, offset + duration)
       default:
         return result
       }
diff --git a/Sources/FCPKitDSL/Library.swift b/Sources/FCPKitDSL/Library.swift
index b4c8610..cde868e 100644
--- a/Sources/FCPKitDSL/Library.swift
+++ b/Sources/FCPKitDSL/Library.swift
@@ -46,7 +46,8 @@ public struct Library: DSLNode {
     self.content = content()
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this library into a `<library>` with the default smart collections.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     let built = try content.build(&resources)
     let event = try event(from: built)
     return .library(
diff --git a/Sources/FCPKitDSL/Project.swift b/Sources/FCPKitDSL/Project.swift
index e6fbfeb..49c86f2 100644
--- a/Sources/FCPKitDSL/Project.swift
+++ b/Sources/FCPKitDSL/Project.swift
@@ -49,7 +49,8 @@ public struct Project: DSLNode {
     self.content = content()
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this project into a `<project>` wrapping its promoted sequence.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     guard case .sequence(let sequence) = try content.build(&resources) else {
       throw BuildError.unsupportedContent
     }
diff --git a/Sources/FCPKitDSL/ResourceStore.swift b/Sources/FCPKitDSL/ResourceStore.swift
index 2ab2a35..6c38cb4 100644
--- a/Sources/FCPKitDSL/ResourceStore.swift
+++ b/Sources/FCPKitDSL/ResourceStore.swift
@@ -30,7 +30,12 @@
 import FCPKit
 import Foundation
 
-internal struct ResourceStore {
+/// The document's shared table of assets, formats, and effects.
+///
+/// Instances are created and threaded through the build by the DSL itself. The type is
+/// `public` only so that ``DSLNode/build(_:)`` can name it; every member is internal, so
+/// it offers no extension point outside this module.
+public struct ResourceStore {
   internal static let draftID: ResourceID = "draft"
 
   private var assets: [FCPKit.Asset] = []
diff --git a/Sources/FCPKitDSL/Sequence.swift b/Sources/FCPKitDSL/Sequence.swift
index 4847ed1..27a975a 100644
--- a/Sources/FCPKitDSL/Sequence.swift
+++ b/Sources/FCPKitDSL/Sequence.swift
@@ -40,7 +40,8 @@ public struct Sequence: DSLNode {
     self.content = content()
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this sequence into a `<sequence>`, packing its spine onto the timeline.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     let formatRef = try format.map { try resources.format($0) }
     let packed = try Layout.pack(
       storyItems(content.contents, resources: &resources),
diff --git a/Sources/FCPKitDSL/Spine.swift b/Sources/FCPKitDSL/Spine.swift
index 493c9ce..597bed1 100644
--- a/Sources/FCPKitDSL/Spine.swift
+++ b/Sources/FCPKitDSL/Spine.swift
@@ -38,7 +38,8 @@ public struct Spine: DSLNode {
     self.content = content()
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this spine into an ordered `<spine>` of story items.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     let packed = try Layout.pack(
       storyItems(content.contents, resources: &resources),
       frameDuration: FormatPreset.p1080p24.format.frameDuration
diff --git a/Sources/FCPKitDSL/StoryItem.swift b/Sources/FCPKitDSL/StoryItem.swift
new file mode 100644
index 0000000..087699f
--- /dev/null
+++ b/Sources/FCPKitDSL/StoryItem.swift
@@ -0,0 +1,86 @@
+//
+//  StoryItem.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+
+/// Content that can sit in a spine, per the FCPXML DTD's `%clip_item;` entity.
+///
+/// Conformers gain ``anchor(lane:offset:content:)``, which attaches connected clips on
+/// numbered lanes above or below the storyline.
+public protocol StoryItem: DocumentContent {
+  /// The type produced by anchoring. Usually `Self`, but ``Color`` promotes to
+  /// ``Generator`` because a model type cannot gain stored properties.
+  associatedtype Anchored: DocumentContent
+
+  /// The anchors already attached to this item.
+  var anchors: [any DSLNode] { get }
+
+  /// Returns a copy of this item carrying exactly the given anchors.
+  ///
+  /// This is a pure setter: it replaces rather than appends. Callers that want to add
+  /// anchors should use ``anchor(lane:offset:content:)``.
+  ///
+  /// - Parameter anchors: The complete anchor list for the returned copy.
+  /// - Returns: A copy carrying `anchors`.
+  func replacingAnchors(_ anchors: [any DSLNode]) -> Anchored
+}
+
+extension StoryItem {
+  /// Anchors content on a connected lane. `lane` must be nonzero.
+  ///
+  /// Chaining accumulates: each call appends to the anchors already present, so
+  /// `clip.anchor(lane: 1) { … }.anchor(lane: 2) { … }` keeps both lanes.
+  ///
+  /// A lane of `0` is the storyline itself and is rejected at build time with
+  /// ``BuildError/invalidLane``, because this modifier cannot throw from builder
+  /// position.
+  ///
+  /// Anchoring onto a ``Transition`` has no effect: the FCPXML DTD does not admit
+  /// anchored items on transitions, so they are accepted but never emitted.
+  ///
+  /// - Parameters:
+  ///   - lane: The connected lane. Positive lanes sit above the storyline, negative
+  ///     lanes below. Must not be `0`.
+  ///   - offset: How far into this item the anchored content begins.
+  ///   - content: The content to anchor.
+  /// - Returns: A copy of this item carrying the existing anchors plus the new ones.
+  public func anchor(
+    lane: Int,
+    offset: FCPTime = .zero,
+    @DocumentBuilder content: () -> DocumentGroup
+  ) -> Anchored {
+    let added: [any DSLNode] = content().contents.compactMap { value in
+      guard let node = value as? any DSLNode else {
+        return nil
+      }
+      return Anchor(lane: lane, offset: offset, content: node)
+    }
+    return replacingAnchors(anchors + added)
+  }
+}
diff --git a/Sources/FCPKitDSL/Title.swift b/Sources/FCPKitDSL/Title.swift
index a59fb03..2349288 100644
--- a/Sources/FCPKitDSL/Title.swift
+++ b/Sources/FCPKitDSL/Title.swift
@@ -30,13 +30,15 @@
 import FCPKit
 
 /// A title clip, typically anchored onto an asset clip.
-public struct Title: DSLNode {
+public struct Title: DSLNode, StoryItem {
   internal let preset: TitlePreset
   internal let text: String
   /// Clip duration on the storyline.
   public let duration: FCPTime
   internal let lane: Int?
   internal let offset: FCPTime?
+  /// The anchors attached to this title.
+  public let anchors: [any DSLNode]
 
   /// Creates a Basic Title from text and optional duration.
   public init(_ text: String, duration: FCPTime? = nil) {
@@ -45,23 +47,58 @@ public struct Title: DSLNode {
 
   /// Creates a title from a preset, text, and optional duration.
   public init(_ preset: TitlePreset, text: String, duration: FCPTime? = nil) {
-    self.init(preset: preset, text: text, duration: duration ?? .zero, lane: nil, offset: nil)
+    self.init(
+      preset: preset,
+      text: text,
+      duration: duration ?? .zero,
+      lane: nil,
+      offset: nil,
+      anchors: []
+    )
   }
 
-  private init(preset: TitlePreset, text: String, duration: FCPTime, lane: Int?, offset: FCPTime?) {
+  private init(
+    preset: TitlePreset,
+    text: String,
+    duration: FCPTime,
+    lane: Int?,
+    offset: FCPTime?,
+    anchors: [any DSLNode]
+  ) {
     self.preset = preset
     self.text = text
     self.duration = duration
     self.lane = lane
     self.offset = offset
+    self.anchors = anchors
   }
 
   /// Sets the title clip duration.
   public func duration(_ duration: FCPTime) -> Title {
-    Title(preset: preset, text: text, duration: duration, lane: lane, offset: offset)
+    Title(
+      preset: preset,
+      text: text,
+      duration: duration,
+      lane: lane,
+      offset: offset,
+      anchors: anchors
+    )
+  }
+
+  /// Returns a copy of this title carrying exactly the given anchors.
+  public func replacingAnchors(_ anchors: [any DSLNode]) -> Title {
+    Title(
+      preset: preset,
+      text: text,
+      duration: duration,
+      lane: lane,
+      offset: offset,
+      anchors: anchors
+    )
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Lowers this title into a `<title>` story item.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     let ref = try resources.effect(name: preset.name, uid: preset.uid)
     let style = FCPKit.TextStyle(ref: "ts1", content: text)
     let definition = FCPKit.TextStyleDef(
@@ -74,19 +111,17 @@ public struct Title: DSLNode {
         alignment: "center"
       )
     )
-    return .item(
-      .title(
-        FCPKit.Title(
-          ref: ref,
-          name: preset.name,
-          duration: duration.description,
-          start: "3600s",
-          lane: lane.map(String.init),
-          offset: offset?.description ?? "0s",
-          text: [FCPKit.TextElement(textStyle: [style])],
-          textStyleDef: [definition]
-        )
-      )
+    var element = FCPKit.Title(
+      ref: ref,
+      name: preset.name,
+      duration: duration.description,
+      start: "3600s",
+      lane: lane.map(String.init),
+      offset: offset?.description ?? "0s",
+      text: [FCPKit.TextElement(textStyle: [style])],
+      textStyleDef: [definition]
     )
+    element.anchoredItems = try anchoredItems(anchors, resources: &resources)
+    return .item(.title(element))
   }
 }
diff --git a/Sources/FCPKitDSL/Transition.swift b/Sources/FCPKitDSL/Transition.swift
index 9b67ce4..af76b79 100644
--- a/Sources/FCPKitDSL/Transition.swift
+++ b/Sources/FCPKitDSL/Transition.swift
@@ -30,11 +30,14 @@
 import FCPKit
 
 /// A transition between adjacent story items.
-public struct Transition: DSLNode {
+public struct Transition: DSLNode, StoryItem {
   internal let preset: TransitionPreset
   /// Transition duration on the storyline.
   public let duration: FCPTime
 
+  /// Always empty. The FCPXML DTD does not admit anchored items on a `<transition>`.
+  public var anchors: [any DSLNode] { [] }
+
   /// Creates a transition from a preset. Default duration is one second.
   public init(_ preset: TransitionPreset, duration: FCPTime = FCPTime(numerator: 1)) {
     self.preset = preset
@@ -46,7 +49,16 @@ public struct Transition: DSLNode {
     Transition(preset, duration: duration)
   }
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  /// Discards the given anchors and returns this transition unchanged.
+  ///
+  /// Anchoring onto a transition is a documented no-op: the FCPXML DTD's
+  /// `%anchor_item;` entity does not include transitions, so nothing is emitted.
+  public func replacingAnchors(_ anchors: [any DSLNode]) -> Transition {
+    self
+  }
+
+  /// Lowers this transition into a `<transition>` story item.
+  public func build(_ resources: inout ResourceStore) throws -> Built {
     let video = try resources.effect(name: preset.name, uid: preset.videoUID)
     let audio = try resources.effect(name: "Audio Crossfade", uid: preset.audioUID)
     let filters = CrossDissolveFilters.make(video: video, audio: audio)
diff --git a/Tests/FCPKitDSLTests/StoryItemAnchorErrorTests.swift b/Tests/FCPKitDSLTests/StoryItemAnchorErrorTests.swift
new file mode 100644
index 0000000..4f94fdb
--- /dev/null
+++ b/Tests/FCPKitDSLTests/StoryItemAnchorErrorTests.swift
@@ -0,0 +1,102 @@
+//
+//  StoryItemAnchorErrorTests.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+import FCPKitDSL
+import Foundation
+import Testing
+
+@Suite
+internal struct StoryItemAnchorErrorTests {
+  @Test
+  internal func generatorLaneZeroThrowsInvalidLane() throws {
+    let document = StoryItemDoc(
+      content: Generator(.custom, duration: FCPTime(numerator: 6))
+        .color(.blue)
+        .anchor(lane: 0) {
+          Title("Heading", duration: FCPTime(numerator: 4))
+        }
+    )
+
+    #expect(throws: BuildError.invalidLane) {
+      _ = try document.export()
+    }
+  }
+
+  @Test
+  internal func colorLaneZeroThrowsInvalidLane() throws {
+    let document = StoryItemDoc(
+      content: Color.red
+        .duration(FCPTime(numerator: 6))
+        .anchor(lane: 0) {
+          Title("Heading", duration: FCPTime(numerator: 4))
+        }
+    )
+
+    #expect(throws: BuildError.invalidLane) {
+      _ = try document.export()
+    }
+  }
+
+  @Test
+  internal func colorAnchoredBeforeDurationFailsLoudly() throws {
+    // `.anchor` cannot throw from builder position, so promotion uses a zero
+    // duration and the mistake surfaces at export() rather than silently
+    // producing a zero-length clip.
+    let document = StoryItemDoc(
+      content: Color.red
+        .anchor(lane: 1) {
+          Title("Heading", duration: FCPTime(numerator: 4))
+        }
+    )
+
+    #expect(throws: BuildError.missingDuration("Custom")) {
+      _ = try document.export()
+    }
+  }
+
+  @Test
+  internal func transitionAnchorsAreIgnored() throws {
+    let exported = try StoryItemSupport.TransitionAnchored().export()
+    let items = try StoryItemSupport.spine(exported)
+    #expect(items.count == 3)
+    guard case .transition(let transition) = items[1] else {
+      Issue.record("Expected spine item 1 to be .transition")
+      return
+    }
+    #expect(transition.name == TransitionPreset.crossDissolve.name)
+
+    // The DTD admits no anchored items on <transition>, so anchoring one is a
+    // documented no-op rather than an error: the document still builds, and the
+    // serialized transition carries no anchored children.
+    let encoded = try FCPXMLParser().encode(exported)
+    let xml = try #require(String(data: encoded, encoding: .utf8))
+    #expect(!xml.contains("Ignored"))
+  }
+}
diff --git a/Tests/FCPKitDSLTests/StoryItemDoc.swift b/Tests/FCPKitDSLTests/StoryItemDoc.swift
new file mode 100644
index 0000000..0d3e5df
--- /dev/null
+++ b/Tests/FCPKitDSLTests/StoryItemDoc.swift
@@ -0,0 +1,44 @@
+//
+//  StoryItemDoc.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+import FCPKitDSL
+import Foundation
+import Testing
+
+/// Wraps arbitrary story content in a 1080p24 sequence.
+internal struct StoryItemDoc<Content: DocumentContent>: Document {
+  internal let content: Content
+
+  internal var body: some DocumentContent {
+    Sequence(format: .p1080p24) {
+      content
+    }
+  }
+}
diff --git a/Tests/FCPKitDSLTests/StoryItemSupport.swift b/Tests/FCPKitDSLTests/StoryItemSupport.swift
new file mode 100644
index 0000000..ee7910e
--- /dev/null
+++ b/Tests/FCPKitDSLTests/StoryItemSupport.swift
@@ -0,0 +1,65 @@
+//
+//  StoryItemSupport.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+import FCPKitDSL
+import Foundation
+import Testing
+
+internal enum StoryItemSupport {
+  /// A deck whose middle transition carries an anchor that must not be emitted.
+  internal struct TransitionAnchored: Document {
+    internal var body: some DocumentContent {
+      Sequence(format: .p1080p24) {
+        Generator(.custom, duration: FCPTime(numerator: 5)).color(.blue)
+        Transition(.crossDissolve)
+          .anchor(lane: 1) {
+            Title("Ignored", duration: FCPTime(numerator: 2))
+          }
+        Generator(.custom, duration: FCPTime(numerator: 5)).color(.green)
+      }
+    }
+  }
+
+  /// Returns the packed spine items of an exported document.
+  internal static func spine(_ exported: FCPXML) throws -> [FCPKit.SpineItem] {
+    let sequence = try #require(exported.library?.events?.first?.projects?.first?.sequence)
+    return try #require(sequence.spine?.items)
+  }
+
+  /// Returns the `lane` of every anchored title, in order.
+  internal static func anchoredTitleLanes(_ items: [FCPKit.AnchoredItem]) -> [String?] {
+    items.compactMap { item in
+      guard case .title(let title) = item else {
+        return nil
+      }
+      return title.lane
+    }
+  }
+}
diff --git a/Tests/FCPKitDSLTests/StoryItemTests.swift b/Tests/FCPKitDSLTests/StoryItemTests.swift
new file mode 100644
index 0000000..de5b93b
--- /dev/null
+++ b/Tests/FCPKitDSLTests/StoryItemTests.swift
@@ -0,0 +1,155 @@
+//
+//  StoryItemTests.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+import FCPKitDSL
+import Foundation
+import Testing
+
+@Suite
+internal struct StoryItemTests {
+  @Test
+  internal func generatorAnchorsTitleOnLaneOne() throws {
+    let document = StoryItemDoc(
+      content: Generator(.custom, duration: FCPTime(numerator: 6))
+        .color(.blue)
+        .anchor(lane: 1) {
+          Title("Heading", duration: FCPTime(numerator: 4))
+        }
+    )
+
+    let items = try StoryItemSupport.spine(try document.export())
+    guard case .video(let video) = items[0] else {
+      Issue.record("Expected spine item to be .video")
+      return
+    }
+
+    let anchored = try #require(video.anchoredItems)
+    #expect(anchored.count == 1)
+    #expect(StoryItemSupport.anchoredTitleLanes(anchored) == ["1"])
+    guard case .title(let title) = anchored[0] else {
+      Issue.record("Expected anchored item to be .title")
+      return
+    }
+    #expect(title.duration == "4s")
+  }
+
+  @Test
+  internal func colorPromotesToGeneratorWhenAnchored() throws {
+    let document = StoryItemDoc(
+      content: Color.red
+        .duration(FCPTime(numerator: 6))
+        .anchor(lane: 1) {
+          Title("Heading", duration: FCPTime(numerator: 4))
+        }
+    )
+
+    let items = try StoryItemSupport.spine(try document.export())
+    guard case .video(let video) = items[0] else {
+      Issue.record("Expected promoted color to build as .video")
+      return
+    }
+
+    // The color survives promotion as the Custom generator's Color param.
+    let params = try #require(video.param)
+    #expect(params[0].value == "1 0 0 1")
+
+    let anchored = try #require(video.anchoredItems)
+    #expect(StoryItemSupport.anchoredTitleLanes(anchored) == ["1"])
+  }
+
+  @Test
+  internal func chainedAnchorsAccumulateLanes() throws {
+    let document = StoryItemDoc(
+      content: Generator(.custom, duration: FCPTime(numerator: 8))
+        .color(.blue)
+        .anchor(lane: 1) {
+          Title("First", duration: FCPTime(numerator: 3))
+        }
+        .anchor(lane: 2) {
+          Title("Second", duration: FCPTime(numerator: 3))
+        }
+    )
+
+    let items = try StoryItemSupport.spine(try document.export())
+    guard case .video(let video) = items[0] else {
+      Issue.record("Expected spine item to be .video")
+      return
+    }
+
+    // Chaining must append. Replacing would drop lane 1 entirely.
+    let anchored = try #require(video.anchoredItems)
+    #expect(anchored.count == 2)
+    #expect(StoryItemSupport.anchoredTitleLanes(anchored) == ["1", "2"])
+  }
+
+  @Test
+  internal func anchoredTitleLongerThanBackgroundExtendsSequence() throws {
+    let document = StoryItemDoc(
+      content: Generator(.custom, duration: FCPTime(numerator: 4))
+        .color(.blue)
+        .anchor(lane: 1) {
+          Title("Long", duration: FCPTime(numerator: 9))
+        }
+    )
+
+    let exported = try document.export()
+    let sequence = try #require(exported.library?.events?.first?.projects?.first?.sequence)
+    // The anchored title outruns its 4s background, so the sequence must span 9s.
+    #expect(sequence.duration == "9s")
+  }
+
+  @Test
+  internal func nestedSpineInsideAnchorPassesThrough() throws {
+    let document = StoryItemDoc(
+      content: Generator(.custom, duration: FCPTime(numerator: 10))
+        .color(.blue)
+        .anchor(lane: 1) {
+          Spine {
+            Title("First", duration: FCPTime(numerator: 3))
+            Title("Second", duration: FCPTime(numerator: 3))
+          }
+        }
+    )
+
+    let items = try StoryItemSupport.spine(try document.export())
+    guard case .video(let video) = items[0] else {
+      Issue.record("Expected spine item to be .video")
+      return
+    }
+
+    let anchored = try #require(video.anchoredItems)
+    #expect(anchored.count == 1)
+    guard case .spine(let nested) = anchored[0] else {
+      Issue.record("Expected anchored item to be .spine")
+      return
+    }
+    #expect(nested.items.count == 2)
+  }
+}

From 56dcb07a9796b7e98fa25ab83652f6ee1f775e1f Mon Sep 17 00:00:00 2001
From: Leo Dion <leogdion@brightdigit.com>
Date: Mon, 3 Aug 2026 13:18:09 -0400
Subject: [PATCH 2/5] Cover the new anchoredExtent case, negative lanes, and
 Title/Gap hosts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up from an adversarial review of e4325f7.

The `.video` case added to `anchoredExtent` had no test: the existing
"anchored item longer than its background" test used a Title, which the
pre-existing `.title` case already handled. The new branch could have been
deleted with the suite staying green. Now covered by an anchored *generator*
outrunning its background.

Also adds the negative-lane case (legal FCPXML — content below the primary
storyline; only lane 0 is reserved) and Title/Gap as anchor hosts, both of
which gained StoryItem conformance in e4325f7 without direct coverage.

Documents why the `.generator` packing branch passes `anchoredExtent: 0`:
`FCPKit.Generator` has no `anchoredItems` property at all, because
`<generator>` is absent from the DTD's `%anchor_item;` list. Zero is the
correct value there, not a stub — the previous commit message implied that
call site was also updated, which overstated the change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 Sources/FCPKitDSL/Layout+Packing.swift    |  3 +
 Tests/FCPKitDSLTests/StoryItemTests.swift | 70 +++++++++++++++++++++++
 2 files changed, 73 insertions(+)

diff --git a/Sources/FCPKitDSL/Layout+Packing.swift b/Sources/FCPKitDSL/Layout+Packing.swift
index 196878b..f00e5d1 100644
--- a/Sources/FCPKitDSL/Layout+Packing.swift
+++ b/Sources/FCPKitDSL/Layout+Packing.swift
@@ -76,6 +76,9 @@ extension Layout {
         cursor: cursor,
         longest: longest,
         tickDenominator: tickDenominator,
+        // `FCPKit.Generator` has no `anchoredItems`: `<generator>` is absent from
+        // the DTD's `%anchor_item;` list, and the DSL's own `Generator` lowers to
+        // `<video>` anyway. Zero is the only correct extent here, not a stub.
         anchoredExtent: 0
       )
       gen.offset = render(placement.offset, tickDenominator)
diff --git a/Tests/FCPKitDSLTests/StoryItemTests.swift b/Tests/FCPKitDSLTests/StoryItemTests.swift
index de5b93b..7e6472f 100644
--- a/Tests/FCPKitDSLTests/StoryItemTests.swift
+++ b/Tests/FCPKitDSLTests/StoryItemTests.swift
@@ -152,4 +152,74 @@ internal struct StoryItemTests {
     }
     #expect(nested.items.count == 2)
   }
+
+  @Test
+  internal func anchoredGeneratorLongerThanBackgroundExtendsSequence() throws {
+    // Covers the `.video` case added to `anchoredExtent`. The pre-existing
+    // `.title` case would not exercise it, so without this the new branch could
+    // be deleted and the suite would stay green.
+    let document = StoryItemDoc(
+      content: Generator(.custom, duration: FCPTime(numerator: 4))
+        .color(.blue)
+        .anchor(lane: 1) {
+          Generator(.custom, duration: FCPTime(numerator: 9)).color(.green)
+        }
+    )
+
+    let exported = try document.export()
+    let sequence = try #require(exported.library?.events?.first?.projects?.first?.sequence)
+    #expect(sequence.duration == "9s")
+  }
+
+  @Test
+  internal func negativeLanesAreAccepted() throws {
+    // Negative lanes are legal FCPXML — content below the primary storyline.
+    // Only lane 0 is reserved and rejected.
+    let document = StoryItemDoc(
+      content: Generator(.custom, duration: FCPTime(numerator: 6))
+        .color(.blue)
+        .anchor(lane: -1) {
+          Title("Below", duration: FCPTime(numerator: 4))
+        }
+    )
+
+    let items = try StoryItemSupport.spine(try document.export())
+    guard case .video(let video) = items[0] else {
+      Issue.record("Expected spine item to be .video")
+      return
+    }
+    let anchored = try #require(video.anchoredItems)
+    #expect(StoryItemSupport.anchoredTitleLanes(anchored) == ["-1"])
+  }
+
+  @Test
+  internal func titleAndGapAlsoHostAnchors() throws {
+    // `Title` and `Gap` gained `StoryItem` conformance in this change but were
+    // otherwise untested as anchor hosts.
+    let titleHost = StoryItemDoc(
+      content: Title("Host", duration: FCPTime(numerator: 6))
+        .anchor(lane: 1) {
+          Title("Anchored", duration: FCPTime(numerator: 3))
+        }
+    )
+    let titleItems = try StoryItemSupport.spine(try titleHost.export())
+    guard case .title(let host) = titleItems[0] else {
+      Issue.record("Expected spine item to be .title")
+      return
+    }
+    #expect(try #require(host.anchoredItems).count == 1)
+
+    let gapHost = StoryItemDoc(
+      content: Gap(duration: FCPTime(numerator: 6))
+        .anchor(lane: 1) {
+          Title("Anchored", duration: FCPTime(numerator: 3))
+        }
+    )
+    let gapItems = try StoryItemSupport.spine(try gapHost.export())
+    guard case .gap(let gap) = gapItems[0] else {
+      Issue.record("Expected spine item to be .gap")
+      return
+    }
+    #expect(try #require(gap.anchoredItems).count == 1)
+  }
 }

From e8bf4b1e2e738e0709674275316462ecd2611a6f Mon Sep 17 00:00:00 2001
From: Leo Dion <leogdion@brightdigit.com>
Date: Mon, 3 Aug 2026 13:45:57 -0400
Subject: [PATCH 3/5] Replace global functions with namespaced statics;
 StoryItem refines DSLNode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses review feedback on #43.

"As a rule never use global functions or properties": the anchored-item
lowering helpers become statics on a new `AnchoredItemBuilder` enum, and the
pre-existing `storyItems` global becomes `StoryItemLowering.items`. The latter
predates this branch, but the rule is a general one, so leaving it behind would
undercut it. `StoryItems.swift` is renamed to match its type.

"Are all StoryItem a DSLNode?" — yes. Every conformer is a `DSLNode`, and the
two extension-based conformances (`Color`, `Generator`) extend types already
declared as such. `StoryItem` now refines `DSLNode` rather than
`DocumentContent`, which makes the relationship explicit and lets the four
`DSLNode, StoryItem` declarations drop the redundant conformance.

This also tightens the protocol: the free `.anchor` extension calls
`replacingAnchors` and relies on the conformer's `build` lowering those anchors,
which only a `DSLNode` can do. The old declaration did not require that.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 Sources/FCPKitDSL/AnchoredItemBuilder.swift   | 43 ++++++++++---------
 Sources/FCPKitDSL/AssetClip.swift             |  4 +-
 Sources/FCPKitDSL/DocumentGroup.swift         |  2 +-
 Sources/FCPKitDSL/Gap.swift                   |  4 +-
 Sources/FCPKitDSL/Generator.swift             |  2 +-
 Sources/FCPKitDSL/Sequence.swift              |  2 +-
 Sources/FCPKitDSL/Spine.swift                 |  2 +-
 Sources/FCPKitDSL/StoryItem.swift             |  2 +-
 ...oryItems.swift => StoryItemLowering.swift} | 24 +++++++----
 Sources/FCPKitDSL/Title.swift                 |  4 +-
 Sources/FCPKitDSL/Transition.swift            |  2 +-
 11 files changed, 50 insertions(+), 41 deletions(-)
 rename Sources/FCPKitDSL/{StoryItems.swift => StoryItemLowering.swift} (69%)

diff --git a/Sources/FCPKitDSL/AnchoredItemBuilder.swift b/Sources/FCPKitDSL/AnchoredItemBuilder.swift
index 573da88..c559dfc 100644
--- a/Sources/FCPKitDSL/AnchoredItemBuilder.swift
+++ b/Sources/FCPKitDSL/AnchoredItemBuilder.swift
@@ -29,26 +29,29 @@
 
 import FCPKit
 
-/// Lowers a single anchor node into the DTD's `%anchor_item;` entity.
-internal func anchoredItem(
-  _ node: any DSLNode,
-  resources: inout ResourceStore
-) throws -> FCPKit.AnchoredItem {
-  switch try node.build(&resources) {
-  case .item(.title(let title)): return .title(title)
-  case .item(.assetClip(let clip)): return .assetClip(clip)
-  case .item(.generator(let gen)): return .generator(gen)
-  case .item(.video(let vid)): return .video(vid)
-  case .spine(let spine): return .spine(spine)
-  default: throw BuildError.unsupportedContent
+/// Lowers anchor nodes into the DTD's `%anchor_item;` entity.
+internal enum AnchoredItemBuilder {
+  /// Lowers a single anchor node into an anchored item.
+  internal static func item(
+    _ node: any DSLNode,
+    resources: inout ResourceStore
+  ) throws -> FCPKit.AnchoredItem {
+    switch try node.build(&resources) {
+    case .item(.title(let title)): return .title(title)
+    case .item(.assetClip(let clip)): return .assetClip(clip)
+    case .item(.generator(let gen)): return .generator(gen)
+    case .item(.video(let vid)): return .video(vid)
+    case .spine(let spine): return .spine(spine)
+    default: throw BuildError.unsupportedContent
+    }
   }
-}
 
-/// Lowers a list of anchor nodes, returning `nil` when the list is empty.
-internal func anchoredItems(
-  _ nodes: [any DSLNode],
-  resources: inout ResourceStore
-) throws -> [FCPKit.AnchoredItem]? {
-  let items = try nodes.map { try anchoredItem($0, resources: &resources) }
-  return items.isEmpty ? nil : items
+  /// Lowers a list of anchor nodes, returning `nil` when the list is empty.
+  internal static func items(
+    _ nodes: [any DSLNode],
+    resources: inout ResourceStore
+  ) throws -> [FCPKit.AnchoredItem]? {
+    let items = try nodes.map { try item($0, resources: &resources) }
+    return items.isEmpty ? nil : items
+  }
 }
diff --git a/Sources/FCPKitDSL/AssetClip.swift b/Sources/FCPKitDSL/AssetClip.swift
index 40a3a7c..907e61d 100644
--- a/Sources/FCPKitDSL/AssetClip.swift
+++ b/Sources/FCPKitDSL/AssetClip.swift
@@ -31,7 +31,7 @@ import FCPKit
 import Foundation
 
 /// An `asset-clip` story item with optional anchors and audio role.
-public struct AssetClip: DSLNode, StoryItem {
+public struct AssetClip: StoryItem {
   internal let source: AssetSource
   /// Clip duration on the storyline, when set explicitly.
   public let duration: FCPTime?
@@ -111,7 +111,7 @@ public struct AssetClip: DSLNode, StoryItem {
     if let format = source.format, source.formatOnClip {
       clip.format = try resources.format(FormatPreset(format))
     }
-    clip.anchoredItems = try anchoredItems(anchors, resources: &resources)
+    clip.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
     return .item(.assetClip(clip))
   }
 
diff --git a/Sources/FCPKitDSL/DocumentGroup.swift b/Sources/FCPKitDSL/DocumentGroup.swift
index 3069d28..e6880fb 100644
--- a/Sources/FCPKitDSL/DocumentGroup.swift
+++ b/Sources/FCPKitDSL/DocumentGroup.swift
@@ -43,7 +43,7 @@ public struct DocumentGroup: DocumentContent, DSLNode {
     if contents.count == 1, let node = contents[0] as? any DSLNode {
       return try node.build(&resources)
     }
-    let items = try storyItems(contents, resources: &resources)
+    let items = try StoryItemLowering.items(contents, resources: &resources)
     let packed = try Layout.pack(items, frameDuration: FormatPreset.p1080p24.format.frameDuration)
     return .spine(FCPKit.Spine(items: packed.items))
   }
diff --git a/Sources/FCPKitDSL/Gap.swift b/Sources/FCPKitDSL/Gap.swift
index bfc750b..f7f8431 100644
--- a/Sources/FCPKitDSL/Gap.swift
+++ b/Sources/FCPKitDSL/Gap.swift
@@ -30,7 +30,7 @@
 import FCPKit
 
 /// A gap on the storyline. Duration is required — set in initializer or via `.duration(...)`.
-public struct Gap: DSLNode, StoryItem {
+public struct Gap: StoryItem {
   /// Gap duration on the storyline, when set.
   public let duration: FCPTime?
   /// The anchors attached to this gap.
@@ -60,7 +60,7 @@ public struct Gap: DSLNode, StoryItem {
   public func build(_ resources: inout ResourceStore) throws -> Built {
     guard let duration else { throw BuildError.missingDuration("gap") }
     var element = FCPKit.Gap(duration: duration.description)
-    element.anchoredItems = try anchoredItems(anchors, resources: &resources)
+    element.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
     return .item(.gap(element))
   }
 }
diff --git a/Sources/FCPKitDSL/Generator.swift b/Sources/FCPKitDSL/Generator.swift
index dfbd3e2..e5f4f6b 100644
--- a/Sources/FCPKitDSL/Generator.swift
+++ b/Sources/FCPKitDSL/Generator.swift
@@ -133,7 +133,7 @@ public struct Generator: DSLNode {
       duration: duration.description,
       param: params.isEmpty ? nil : params
     )
-    videoElement.anchoredItems = try anchoredItems(anchors, resources: &resources)
+    videoElement.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
     return .item(.video(videoElement))
   }
 
diff --git a/Sources/FCPKitDSL/Sequence.swift b/Sources/FCPKitDSL/Sequence.swift
index 27a975a..3cc6695 100644
--- a/Sources/FCPKitDSL/Sequence.swift
+++ b/Sources/FCPKitDSL/Sequence.swift
@@ -44,7 +44,7 @@ public struct Sequence: DSLNode {
   public func build(_ resources: inout ResourceStore) throws -> Built {
     let formatRef = try format.map { try resources.format($0) }
     let packed = try Layout.pack(
-      storyItems(content.contents, resources: &resources),
+      StoryItemLowering.items(content.contents, resources: &resources),
       frameDuration: format?.format.frameDuration
     )
     return .sequence(
diff --git a/Sources/FCPKitDSL/Spine.swift b/Sources/FCPKitDSL/Spine.swift
index 597bed1..bef9625 100644
--- a/Sources/FCPKitDSL/Spine.swift
+++ b/Sources/FCPKitDSL/Spine.swift
@@ -41,7 +41,7 @@ public struct Spine: DSLNode {
   /// Lowers this spine into an ordered `<spine>` of story items.
   public func build(_ resources: inout ResourceStore) throws -> Built {
     let packed = try Layout.pack(
-      storyItems(content.contents, resources: &resources),
+      StoryItemLowering.items(content.contents, resources: &resources),
       frameDuration: FormatPreset.p1080p24.format.frameDuration
     )
     return .spine(FCPKit.Spine(items: packed.items))
diff --git a/Sources/FCPKitDSL/StoryItem.swift b/Sources/FCPKitDSL/StoryItem.swift
index 087699f..4d8319f 100644
--- a/Sources/FCPKitDSL/StoryItem.swift
+++ b/Sources/FCPKitDSL/StoryItem.swift
@@ -33,7 +33,7 @@ import FCPKit
 ///
 /// Conformers gain ``anchor(lane:offset:content:)``, which attaches connected clips on
 /// numbered lanes above or below the storyline.
-public protocol StoryItem: DocumentContent {
+public protocol StoryItem: DSLNode {
   /// The type produced by anchoring. Usually `Self`, but ``Color`` promotes to
   /// ``Generator`` because a model type cannot gain stored properties.
   associatedtype Anchored: DocumentContent
diff --git a/Sources/FCPKitDSL/StoryItems.swift b/Sources/FCPKitDSL/StoryItemLowering.swift
similarity index 69%
rename from Sources/FCPKitDSL/StoryItems.swift
rename to Sources/FCPKitDSL/StoryItemLowering.swift
index 921448f..1910bd5 100644
--- a/Sources/FCPKitDSL/StoryItems.swift
+++ b/Sources/FCPKitDSL/StoryItemLowering.swift
@@ -1,5 +1,5 @@
 //
-//  StoryItems.swift
+//  StoryItemLowering.swift
 //  FCPKit
 //
 //  Created by Leo Dion.
@@ -29,14 +29,20 @@
 
 import FCPKit
 
-internal func storyItems(
-  _ content: [any DocumentContent],
-  resources: inout ResourceStore
-) throws -> [FCPKit.SpineItem] {
-  try content.map { value in
-    guard let node = value as? any DSLNode, case .item(let item) = try node.build(&resources) else {
-      throw BuildError.unsupportedContent
+/// Lowers document content into ordered spine items.
+internal enum StoryItemLowering {
+  /// Lowers each content value into a spine item, preserving order.
+  internal static func items(
+    _ content: [any DocumentContent],
+    resources: inout ResourceStore
+  ) throws -> [FCPKit.SpineItem] {
+    try content.map { value in
+      guard let node = value as? any DSLNode,
+        case .item(let item) = try node.build(&resources)
+      else {
+        throw BuildError.unsupportedContent
+      }
+      return item
     }
-    return item
   }
 }
diff --git a/Sources/FCPKitDSL/Title.swift b/Sources/FCPKitDSL/Title.swift
index 2349288..c6c9b1d 100644
--- a/Sources/FCPKitDSL/Title.swift
+++ b/Sources/FCPKitDSL/Title.swift
@@ -30,7 +30,7 @@
 import FCPKit
 
 /// A title clip, typically anchored onto an asset clip.
-public struct Title: DSLNode, StoryItem {
+public struct Title: StoryItem {
   internal let preset: TitlePreset
   internal let text: String
   /// Clip duration on the storyline.
@@ -121,7 +121,7 @@ public struct Title: DSLNode, StoryItem {
       text: [FCPKit.TextElement(textStyle: [style])],
       textStyleDef: [definition]
     )
-    element.anchoredItems = try anchoredItems(anchors, resources: &resources)
+    element.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
     return .item(.title(element))
   }
 }
diff --git a/Sources/FCPKitDSL/Transition.swift b/Sources/FCPKitDSL/Transition.swift
index af76b79..199770a 100644
--- a/Sources/FCPKitDSL/Transition.swift
+++ b/Sources/FCPKitDSL/Transition.swift
@@ -30,7 +30,7 @@
 import FCPKit
 
 /// A transition between adjacent story items.
-public struct Transition: DSLNode, StoryItem {
+public struct Transition: StoryItem {
   internal let preset: TransitionPreset
   /// Transition duration on the storyline.
   public let duration: FCPTime

From 80705dec418ce35c905d4f5f477061cc7c5949fc Mon Sep 17 00:00:00 2001
From: Leo Dion <leogdion@brightdigit.com>
Date: Mon, 3 Aug 2026 15:45:13 -0400
Subject: [PATCH 4/5] Replace lowering namespaces with a protocol and array
 extensions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses review feedback on #43: AnchoredItemBuilder and StoryItemLowering are
namespaces holding functions rather than types that mean anything.

The anchoring case had a real duplication behind it. `Anchor.applyLaneOffset`
and `AnchoredItemBuilder.item` each switched over the same four shapes, and both
already omitted `.gap` despite the schema admitting it — two switches, one
concept, already drifted.

`AnchorableItem` states that set once. Each conformer describes how to re-wrap
itself into both ordered-choice containers, so `Built.anchorable` is the only
switch and no downcasts are needed. `Anchor.build` drops from a body with its
own parallel switch to three lines. `.gap` stays unsupported, so behaviour is
unchanged; widening it is a capability change and gets its own issue.

The rest become extensions on what they operate on:

- `Built.anchoredItem()` and `Built.placed(lane:offset:)` — the mapping is
  genuinely `Built` to an anchored item, so it lives on `Built`.
- `[any DSLNode].anchoredItems(resources:)` and
  `[any DocumentContent].spineItems(resources:)` — both always took a
  collection, so they read as collection operations:
  `content.contents.spineItems(resources: &resources)`.

Adopts typed throws across the module, matching #42. Every throw site already
raised `BuildError`, so `throws(BuildError)` runs end to end and callers get a
concrete catch type. Note this narrows `DSLNode.build`: an external conformer
declaring plain `throws` no longer satisfies the protocol. Pre-1.0 and
in-policy for a protocol documented as evolving, but it is an API narrowing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 Sources/FCPKitDSL/Anchor.swift                | 27 +-----
 Sources/FCPKitDSL/AnchorableItem.swift        | 67 ++++++++++++++
 Sources/FCPKitDSL/AnchoredItemBuilder.swift   | 57 ------------
 ...temLowering.swift => Array+Lowering.swift} | 22 +++--
 Sources/FCPKitDSL/AssetClip.swift             |  4 +-
 Sources/FCPKitDSL/Built+Anchoring.swift       | 87 +++++++++++++++++++
 Sources/FCPKitDSL/Color+DSL.swift             |  2 +-
 Sources/FCPKitDSL/DSLNode.swift               |  2 +-
 Sources/FCPKitDSL/Defaults.swift              |  2 +-
 Sources/FCPKitDSL/Document+Export.swift       |  2 +-
 Sources/FCPKitDSL/DocumentGroup.swift         |  4 +-
 Sources/FCPKitDSL/Event.swift                 |  4 +-
 Sources/FCPKitDSL/Gap.swift                   |  4 +-
 Sources/FCPKitDSL/Generator.swift             |  4 +-
 Sources/FCPKitDSL/Layout+Packing.swift        |  8 +-
 Sources/FCPKitDSL/Layout.swift                |  6 +-
 Sources/FCPKitDSL/Library.swift               |  4 +-
 Sources/FCPKitDSL/Project.swift               |  2 +-
 Sources/FCPKitDSL/ResourceStore.swift         | 14 +--
 Sources/FCPKitDSL/Sequence.swift              |  8 +-
 Sources/FCPKitDSL/SoftPromote.swift           |  6 +-
 Sources/FCPKitDSL/Spine.swift                 |  4 +-
 Sources/FCPKitDSL/Title.swift                 |  4 +-
 Sources/FCPKitDSL/Transition.swift            |  2 +-
 24 files changed, 217 insertions(+), 129 deletions(-)
 create mode 100644 Sources/FCPKitDSL/AnchorableItem.swift
 delete mode 100644 Sources/FCPKitDSL/AnchoredItemBuilder.swift
 rename Sources/FCPKitDSL/{StoryItemLowering.swift => Array+Lowering.swift} (72%)
 create mode 100644 Sources/FCPKitDSL/Built+Anchoring.swift

diff --git a/Sources/FCPKitDSL/Anchor.swift b/Sources/FCPKitDSL/Anchor.swift
index d799ae5..2036b9b 100644
--- a/Sources/FCPKitDSL/Anchor.swift
+++ b/Sources/FCPKitDSL/Anchor.swift
@@ -34,10 +34,10 @@ internal struct Anchor: DSLNode {
   internal let offset: FCPTime
   internal let content: any DSLNode
 
-  internal func build(_ resources: inout ResourceStore) throws -> Built {
+  internal func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     guard lane != 0 else { throw BuildError.invalidLane }
     let built = try content.build(&resources)
-    if let item = try applyLaneOffset(to: built) {
+    if let item = built.placed(lane: lane, offset: offset) {
       return item
     }
     guard case .spine(let spine) = built else {
@@ -45,27 +45,4 @@ internal struct Anchor: DSLNode {
     }
     return .spine(spine)
   }
-
-  private func applyLaneOffset(to built: Built) throws -> Built? {
-    switch built {
-    case .item(.title(var title)):
-      title.lane = String(lane)
-      title.offset = offset.description
-      return .item(.title(title))
-    case .item(.assetClip(var clip)):
-      clip.lane = String(lane)
-      clip.offset = offset.description
-      return .item(.assetClip(clip))
-    case .item(.generator(var gen)):
-      gen.lane = String(lane)
-      gen.offset = offset.description
-      return .item(.generator(gen))
-    case .item(.video(var vid)):
-      vid.lane = String(lane)
-      vid.offset = offset.description
-      return .item(.video(vid))
-    default:
-      return nil
-    }
-  }
 }
diff --git a/Sources/FCPKitDSL/AnchorableItem.swift b/Sources/FCPKitDSL/AnchorableItem.swift
new file mode 100644
index 0000000..c6b78f3
--- /dev/null
+++ b/Sources/FCPKitDSL/AnchorableItem.swift
@@ -0,0 +1,67 @@
+//
+//  AnchorableItem.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+
+/// A model element that may be attached to a connected lane.
+///
+/// The FCPXML DTD's `%anchor_item;` entity admits a subset of story elements.
+/// Conformers describe how to re-wrap themselves into both ordered-choice
+/// containers, so the set of anchorable shapes is stated exactly once — in
+/// ``Built/anchorable`` — instead of being re-enumerated by every caller.
+internal protocol AnchorableItem {
+  /// The connected lane this element sits on.
+  var lane: String? { get set }
+  /// The element's offset within its parent.
+  var offset: String? { get set }
+  /// This element as an anchored child.
+  var asAnchoredItem: FCPKit.AnchoredItem { get }
+  /// This element as a spine item.
+  var asSpineItem: FCPKit.SpineItem { get }
+}
+
+extension FCPKit.Title: AnchorableItem {
+  internal var asAnchoredItem: FCPKit.AnchoredItem { .title(self) }
+  internal var asSpineItem: FCPKit.SpineItem { .title(self) }
+}
+
+extension FCPKit.AssetClip: AnchorableItem {
+  internal var asAnchoredItem: FCPKit.AnchoredItem { .assetClip(self) }
+  internal var asSpineItem: FCPKit.SpineItem { .assetClip(self) }
+}
+
+extension FCPKit.Generator: AnchorableItem {
+  internal var asAnchoredItem: FCPKit.AnchoredItem { .generator(self) }
+  internal var asSpineItem: FCPKit.SpineItem { .generator(self) }
+}
+
+extension FCPKit.Video: AnchorableItem {
+  internal var asAnchoredItem: FCPKit.AnchoredItem { .video(self) }
+  internal var asSpineItem: FCPKit.SpineItem { .video(self) }
+}
diff --git a/Sources/FCPKitDSL/AnchoredItemBuilder.swift b/Sources/FCPKitDSL/AnchoredItemBuilder.swift
deleted file mode 100644
index c559dfc..0000000
--- a/Sources/FCPKitDSL/AnchoredItemBuilder.swift
+++ /dev/null
@@ -1,57 +0,0 @@
-//
-//  AnchoredItemBuilder.swift
-//  FCPKit
-//
-//  Created by Leo Dion.
-//  Copyright © 2026 BrightDigit.
-//
-//  Permission is hereby granted, free of charge, to any person
-//  obtaining a copy of this software and associated documentation
-//  files (the "Software"), to deal in the Software without
-//  restriction, including without limitation the rights to use,
-//  copy, modify, merge, publish, distribute, sublicense, and/or
-//  sell copies of the Software, and to permit persons to whom the
-//  Software is furnished to do so, subject to the following
-//  conditions:
-//
-//  The above copyright notice and this permission notice shall be
-//  included in all copies or substantial portions of the Software.
-//
-//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-//  OTHER DEALINGS IN THE SOFTWARE.
-//
-
-import FCPKit
-
-/// Lowers anchor nodes into the DTD's `%anchor_item;` entity.
-internal enum AnchoredItemBuilder {
-  /// Lowers a single anchor node into an anchored item.
-  internal static func item(
-    _ node: any DSLNode,
-    resources: inout ResourceStore
-  ) throws -> FCPKit.AnchoredItem {
-    switch try node.build(&resources) {
-    case .item(.title(let title)): return .title(title)
-    case .item(.assetClip(let clip)): return .assetClip(clip)
-    case .item(.generator(let gen)): return .generator(gen)
-    case .item(.video(let vid)): return .video(vid)
-    case .spine(let spine): return .spine(spine)
-    default: throw BuildError.unsupportedContent
-    }
-  }
-
-  /// Lowers a list of anchor nodes, returning `nil` when the list is empty.
-  internal static func items(
-    _ nodes: [any DSLNode],
-    resources: inout ResourceStore
-  ) throws -> [FCPKit.AnchoredItem]? {
-    let items = try nodes.map { try item($0, resources: &resources) }
-    return items.isEmpty ? nil : items
-  }
-}
diff --git a/Sources/FCPKitDSL/StoryItemLowering.swift b/Sources/FCPKitDSL/Array+Lowering.swift
similarity index 72%
rename from Sources/FCPKitDSL/StoryItemLowering.swift
rename to Sources/FCPKitDSL/Array+Lowering.swift
index 1910bd5..e6e5b1f 100644
--- a/Sources/FCPKitDSL/StoryItemLowering.swift
+++ b/Sources/FCPKitDSL/Array+Lowering.swift
@@ -1,5 +1,5 @@
 //
-//  StoryItemLowering.swift
+//  Array+Lowering.swift
 //  FCPKit
 //
 //  Created by Leo Dion.
@@ -29,20 +29,24 @@
 
 import FCPKit
 
-/// Lowers document content into ordered spine items.
-internal enum StoryItemLowering {
-  /// Lowers each content value into a spine item, preserving order.
-  internal static func items(
-    _ content: [any DocumentContent],
+extension Array where Element == any DocumentContent {
+  /// Lowers this content into ordered spine items, preserving authored order.
+  ///
+  /// - Throws: ``BuildError/unsupportedContent`` when a value is not a story
+  ///   item — a document shell such as a `Project` cannot sit in a spine.
+  internal func spineItems(
     resources: inout ResourceStore
-  ) throws -> [FCPKit.SpineItem] {
-    try content.map { value in
+  ) throws(BuildError) -> [FCPKit.SpineItem] {
+    var items: [FCPKit.SpineItem] = []
+    items.reserveCapacity(count)
+    for value in self {
       guard let node = value as? any DSLNode,
         case .item(let item) = try node.build(&resources)
       else {
         throw BuildError.unsupportedContent
       }
-      return item
+      items.append(item)
     }
+    return items
   }
 }
diff --git a/Sources/FCPKitDSL/AssetClip.swift b/Sources/FCPKitDSL/AssetClip.swift
index 907e61d..0a05e66 100644
--- a/Sources/FCPKitDSL/AssetClip.swift
+++ b/Sources/FCPKitDSL/AssetClip.swift
@@ -96,7 +96,7 @@ public struct AssetClip: StoryItem {
   }
 
   /// Lowers this clip into an `<asset-clip>` story item.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     let ref = try resources.asset(source)
     guard let value = duration?.description ?? source.asset.duration, FCPTime(value) != nil else {
       throw BuildError.missingDuration(name ?? source.asset.name ?? "asset clip")
@@ -111,7 +111,7 @@ public struct AssetClip: StoryItem {
     if let format = source.format, source.formatOnClip {
       clip.format = try resources.format(FormatPreset(format))
     }
-    clip.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
+    clip.anchoredItems = try anchors.anchoredItems(resources: &resources)
     return .item(.assetClip(clip))
   }
 
diff --git a/Sources/FCPKitDSL/Built+Anchoring.swift b/Sources/FCPKitDSL/Built+Anchoring.swift
new file mode 100644
index 0000000..536262b
--- /dev/null
+++ b/Sources/FCPKitDSL/Built+Anchoring.swift
@@ -0,0 +1,87 @@
+//
+//  Built+Anchoring.swift
+//  FCPKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import FCPKit
+
+extension Built {
+  /// This value as an anchorable element, or `nil` if it cannot be anchored.
+  ///
+  /// The single description of what the DTD's `%anchor_item;` entity admits.
+  /// A `<gap>` is anchorable per the schema but is not produced here, matching
+  /// long-standing behaviour; widening that is a capability change.
+  internal var anchorable: (any AnchorableItem)? {
+    switch self {
+    case .item(.title(let title)): return title
+    case .item(.assetClip(let clip)): return clip
+    case .item(.generator(let generator)): return generator
+    case .item(.video(let video)): return video
+    default: return nil
+    }
+  }
+
+  /// This value lowered into the DTD's `%anchor_item;` entity.
+  ///
+  /// - Throws: ``BuildError/unsupportedContent`` when the value cannot be anchored.
+  internal func anchoredItem() throws(BuildError) -> FCPKit.AnchoredItem {
+    if case .spine(let spine) = self {
+      return .spine(spine)
+    }
+    guard let anchorable else {
+      throw BuildError.unsupportedContent
+    }
+    return anchorable.asAnchoredItem
+  }
+
+  /// A copy placed on `lane` at `offset`, or `nil` if it cannot be anchored.
+  internal func placed(lane: Int, offset: FCPTime) -> Built? {
+    guard var item = anchorable else {
+      return nil
+    }
+    item.lane = String(lane)
+    item.offset = offset.description
+    return .item(item.asSpineItem)
+  }
+}
+
+extension Array where Element == any DSLNode {
+  /// Lowers these nodes into anchored items, returning `nil` when empty.
+  ///
+  /// The optional is load-bearing: the model omits the element entirely rather
+  /// than emitting an empty container.
+  internal func anchoredItems(
+    resources: inout ResourceStore
+  ) throws(BuildError) -> [FCPKit.AnchoredItem]? {
+    var items: [FCPKit.AnchoredItem] = []
+    items.reserveCapacity(count)
+    for node in self {
+      items.append(try node.build(&resources).anchoredItem())
+    }
+    return items.isEmpty ? nil : items
+  }
+}
diff --git a/Sources/FCPKitDSL/Color+DSL.swift b/Sources/FCPKitDSL/Color+DSL.swift
index 6615044..d38ff37 100644
--- a/Sources/FCPKitDSL/Color+DSL.swift
+++ b/Sources/FCPKitDSL/Color+DSL.swift
@@ -41,7 +41,7 @@ extension Color: DSLNode {
   }
 
   /// Lowers this color into a custom solid generator `<video>` story item.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     guard let duration else {
       throw BuildError.missingDuration("color generator")
     }
diff --git a/Sources/FCPKitDSL/DSLNode.swift b/Sources/FCPKitDSL/DSLNode.swift
index ef3b9b2..4224438 100644
--- a/Sources/FCPKitDSL/DSLNode.swift
+++ b/Sources/FCPKitDSL/DSLNode.swift
@@ -42,5 +42,5 @@ public protocol DSLNode: DocumentContent {
   /// - Returns: The model value this node lowers to.
   /// - Throws: A ``BuildError`` when the node is incomplete or cannot be represented.
   /// - Warning: This signature is expected to evolve before 1.0.
-  func build(_ resources: inout ResourceStore) throws -> Built
+  func build(_ resources: inout ResourceStore) throws(BuildError) -> Built
 }
diff --git a/Sources/FCPKitDSL/Defaults.swift b/Sources/FCPKitDSL/Defaults.swift
index 2839a8d..96c31f1 100644
--- a/Sources/FCPKitDSL/Defaults.swift
+++ b/Sources/FCPKitDSL/Defaults.swift
@@ -71,7 +71,7 @@ internal enum Defaults {
   internal static func sequence(
     spine: FCPKit.Spine,
     format: ResourceRef<FormatKind>?
-  ) throws -> FCPKit.Sequence {
+  ) throws(BuildError) -> FCPKit.Sequence {
     let packed = try Layout.pack(
       spine.items,
       frameDuration: FormatPreset.p1080p24.format.frameDuration
diff --git a/Sources/FCPKitDSL/Document+Export.swift b/Sources/FCPKitDSL/Document+Export.swift
index 31a2760..49ed45f 100644
--- a/Sources/FCPKitDSL/Document+Export.swift
+++ b/Sources/FCPKitDSL/Document+Export.swift
@@ -31,7 +31,7 @@ import FCPKit
 
 extension Document {
   /// Soft-promotes shells, interns resources, packs the spine, and returns `FCPXML`.
-  public func export(version: FCPXMLVersion = .supportedGeneration) throws -> FCPXML {
+  public func export(version: FCPXMLVersion = .supportedGeneration) throws(BuildError) -> FCPXML {
     guard let root = body as? any DSLNode else {
       throw BuildError.unsupportedContent
     }
diff --git a/Sources/FCPKitDSL/DocumentGroup.swift b/Sources/FCPKitDSL/DocumentGroup.swift
index e6880fb..e5d7f7b 100644
--- a/Sources/FCPKitDSL/DocumentGroup.swift
+++ b/Sources/FCPKitDSL/DocumentGroup.swift
@@ -39,11 +39,11 @@ public struct DocumentGroup: DocumentContent, DSLNode {
   }
 
   /// Lowers this group's single child, or a synthesized spine of its children.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     if contents.count == 1, let node = contents[0] as? any DSLNode {
       return try node.build(&resources)
     }
-    let items = try StoryItemLowering.items(contents, resources: &resources)
+    let items = try contents.spineItems(resources: &resources)
     let packed = try Layout.pack(items, frameDuration: FormatPreset.p1080p24.format.frameDuration)
     return .spine(FCPKit.Spine(items: packed.items))
   }
diff --git a/Sources/FCPKitDSL/Event.swift b/Sources/FCPKitDSL/Event.swift
index 11182ee..8dd460c 100644
--- a/Sources/FCPKitDSL/Event.swift
+++ b/Sources/FCPKitDSL/Event.swift
@@ -45,13 +45,13 @@ public struct Event: DSLNode {
   }
 
   /// Lowers this event into an `<event>` containing its promoted projects.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     let built = try content.build(&resources)
     let project = try project(from: built)
     return .event(FCPKit.Event(name: name ?? "Untitled", uid: uid, projects: [project]))
   }
 
-  private func project(from built: Built) throws -> FCPKit.Project {
+  private func project(from built: Built) throws(BuildError) -> FCPKit.Project {
     switch built {
     case .project(let project): return project
     case .sequence(let sequence): return FCPKit.Project(name: "Untitled", sequence: sequence)
diff --git a/Sources/FCPKitDSL/Gap.swift b/Sources/FCPKitDSL/Gap.swift
index f7f8431..208c59d 100644
--- a/Sources/FCPKitDSL/Gap.swift
+++ b/Sources/FCPKitDSL/Gap.swift
@@ -57,10 +57,10 @@ public struct Gap: StoryItem {
   }
 
   /// Lowers this gap into a `<gap>` story item.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     guard let duration else { throw BuildError.missingDuration("gap") }
     var element = FCPKit.Gap(duration: duration.description)
-    element.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
+    element.anchoredItems = try anchors.anchoredItems(resources: &resources)
     return .item(.gap(element))
   }
 }
diff --git a/Sources/FCPKitDSL/Generator.swift b/Sources/FCPKitDSL/Generator.swift
index e5f4f6b..0daada9 100644
--- a/Sources/FCPKitDSL/Generator.swift
+++ b/Sources/FCPKitDSL/Generator.swift
@@ -119,7 +119,7 @@ public struct Generator: DSLNode {
   ///
   /// - Throws: ``BuildError/missingDuration(_:)`` when no duration was ever set. This is
   ///   how a ``Color`` anchored before `.duration(_:)` surfaces at `export()`.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     guard duration != .zero else {
       throw BuildError.missingDuration(name ?? preset.name)
     }
@@ -133,7 +133,7 @@ public struct Generator: DSLNode {
       duration: duration.description,
       param: params.isEmpty ? nil : params
     )
-    videoElement.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
+    videoElement.anchoredItems = try anchors.anchoredItems(resources: &resources)
     return .item(.video(videoElement))
   }
 
diff --git a/Sources/FCPKitDSL/Layout+Packing.swift b/Sources/FCPKitDSL/Layout+Packing.swift
index f00e5d1..7522589 100644
--- a/Sources/FCPKitDSL/Layout+Packing.swift
+++ b/Sources/FCPKitDSL/Layout+Packing.swift
@@ -36,7 +36,7 @@ extension Layout {
     cursor: Int64,
     longest: Int64,
     tickDenominator: Int32
-  ) throws -> PackStep? {
+  ) throws(BuildError) -> PackStep? {
     switch item {
     case .assetClip(var clip):
       let placement = try placeOverlapping(
@@ -96,7 +96,7 @@ extension Layout {
     cursor: Int64,
     longest: Int64,
     tickDenominator: Int32
-  ) throws -> PackStep {
+  ) throws(BuildError) -> PackStep {
     switch item {
     case .gap(var gap):
       let duration = try ticks(gap.duration, tickDenominator, "gap")
@@ -130,7 +130,7 @@ extension Layout {
     longest: Int64,
     tickDenominator: Int32,
     anchoredExtent: Int64
-  ) throws -> Placement {
+  ) throws(BuildError) -> Placement {
     let original = try ticks(description, tickDenominator, subject)
     let start = overlap.previous
     let duration = original - start - overlap.next
@@ -148,7 +148,7 @@ extension Layout {
     _ description: String?,
     _ denominator: Int32,
     _ subject: String
-  ) throws -> Int64 {
+  ) throws(BuildError) -> Int64 {
     guard let description, let value = FCPTime(description) else {
       throw BuildError.missingDuration(subject)
     }
diff --git a/Sources/FCPKitDSL/Layout.swift b/Sources/FCPKitDSL/Layout.swift
index 3735b71..8976555 100644
--- a/Sources/FCPKitDSL/Layout.swift
+++ b/Sources/FCPKitDSL/Layout.swift
@@ -59,7 +59,9 @@ internal enum Layout {
   /// Each transition of duration `T` overlaps the previous clip's end and the next
   /// clip's start by `T/2`. Times that reduce to whole seconds render as `"Ns"`;
   /// otherwise they keep the sequence tick denominator (for 24fps, `/2400s`).
-  internal static func pack(_ items: [FCPKit.SpineItem], frameDuration: String?) throws -> Packed {
+  internal static func pack(_ items: [FCPKit.SpineItem], frameDuration: String?) throws(BuildError)
+    -> Packed
+  {
     let tickDenominator = tickDenominator(for: frameDuration)
     var cursor: Int64 = 0
     var longest: Int64 = 0
@@ -87,7 +89,7 @@ internal enum Layout {
     cursor: Int64,
     longest: Int64,
     tickDenominator: Int32
-  ) throws -> PackStep {
+  ) throws(BuildError) -> PackStep {
     if let overlapping = try packOverlapping(
       item,
       overlap: overlap,
diff --git a/Sources/FCPKitDSL/Library.swift b/Sources/FCPKitDSL/Library.swift
index cde868e..e6f2a7d 100644
--- a/Sources/FCPKitDSL/Library.swift
+++ b/Sources/FCPKitDSL/Library.swift
@@ -47,7 +47,7 @@ public struct Library: DSLNode {
   }
 
   /// Lowers this library into a `<library>` with the default smart collections.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     let built = try content.build(&resources)
     let event = try event(from: built)
     return .library(
@@ -60,7 +60,7 @@ public struct Library: DSLNode {
     )
   }
 
-  private func event(from built: Built) throws -> FCPKit.Event {
+  private func event(from built: Built) throws(BuildError) -> FCPKit.Event {
     switch built {
     case .event(let event): return event
     case .project(let project): return FCPKit.Event(name: "Untitled", projects: [project])
diff --git a/Sources/FCPKitDSL/Project.swift b/Sources/FCPKitDSL/Project.swift
index 49c86f2..febc7e8 100644
--- a/Sources/FCPKitDSL/Project.swift
+++ b/Sources/FCPKitDSL/Project.swift
@@ -50,7 +50,7 @@ public struct Project: DSLNode {
   }
 
   /// Lowers this project into a `<project>` wrapping its promoted sequence.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     guard case .sequence(let sequence) = try content.build(&resources) else {
       throw BuildError.unsupportedContent
     }
diff --git a/Sources/FCPKitDSL/ResourceStore.swift b/Sources/FCPKitDSL/ResourceStore.swift
index 6c38cb4..ad323c5 100644
--- a/Sources/FCPKitDSL/ResourceStore.swift
+++ b/Sources/FCPKitDSL/ResourceStore.swift
@@ -75,7 +75,9 @@ public struct ResourceStore {
     ].joined(separator: "|")
   }
 
-  internal mutating func format(_ preset: FormatPreset) throws -> ResourceRef<FormatKind> {
+  internal mutating func format(_ preset: FormatPreset) throws(BuildError) -> ResourceRef<
+    FormatKind
+  > {
     let fingerprint = Self.formatFingerprint(preset.format)
     let id = try register(
       key: "format:\(fingerprint)",
@@ -90,7 +92,7 @@ public struct ResourceStore {
     return try resourceRef(id)
   }
 
-  internal mutating func asset(_ source: AssetSource) throws -> ResourceRef<AssetKind> {
+  internal mutating func asset(_ source: AssetSource) throws(BuildError) -> ResourceRef<AssetKind> {
     let fingerprint = Self.assetFingerprint(source.asset)
     let id = try register(
       key: "asset:\(fingerprint)",
@@ -108,7 +110,9 @@ public struct ResourceStore {
     return try resourceRef(id)
   }
 
-  internal mutating func effect(name: String, uid: String) throws -> ResourceRef<EffectKind> {
+  internal mutating func effect(name: String, uid: String) throws(BuildError) -> ResourceRef<
+    EffectKind
+  > {
     let fingerprint = "\(name)|\(uid)"
     let id = try register(
       key: "effect:\(fingerprint)",
@@ -133,7 +137,7 @@ public struct ResourceStore {
     key: String,
     explicitID: ResourceID?,
     fingerprint: String
-  ) throws -> ResourceID {
+  ) throws(BuildError) -> ResourceID {
     if let existing = fingerprints[key] {
       return existing
     }
@@ -154,7 +158,7 @@ public struct ResourceStore {
     return id
   }
 
-  private func resourceRef<Kind>(_ id: ResourceID) throws -> ResourceRef<Kind> {
+  private func resourceRef<Kind>(_ id: ResourceID) throws(BuildError) -> ResourceRef<Kind> {
     guard let ref = ResourceRef<Kind>(id.rawValue) else {
       throw BuildError.invalidResourceID(id.rawValue)
     }
diff --git a/Sources/FCPKitDSL/Sequence.swift b/Sources/FCPKitDSL/Sequence.swift
index 3cc6695..ac47b44 100644
--- a/Sources/FCPKitDSL/Sequence.swift
+++ b/Sources/FCPKitDSL/Sequence.swift
@@ -41,10 +41,12 @@ public struct Sequence: DSLNode {
   }
 
   /// Lowers this sequence into a `<sequence>`, packing its spine onto the timeline.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
-    let formatRef = try format.map { try resources.format($0) }
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
+    let formatRef = try format.map { preset throws(BuildError) in
+      try resources.format(preset)
+    }
     let packed = try Layout.pack(
-      StoryItemLowering.items(content.contents, resources: &resources),
+      content.contents.spineItems(resources: &resources),
       frameDuration: format?.format.frameDuration
     )
     return .sequence(
diff --git a/Sources/FCPKitDSL/SoftPromote.swift b/Sources/FCPKitDSL/SoftPromote.swift
index 9c444ca..4301270 100644
--- a/Sources/FCPKitDSL/SoftPromote.swift
+++ b/Sources/FCPKitDSL/SoftPromote.swift
@@ -29,7 +29,9 @@
 
 import FCPKit
 
-internal func softPromote(_ built: Built, resources: inout ResourceStore) throws -> FCPKit.Library {
+internal func softPromote(_ built: Built, resources: inout ResourceStore) throws(BuildError)
+  -> FCPKit.Library
+{
   switch built {
   case .library(let library):
     return library
@@ -64,6 +66,6 @@ private func project(for sequence: FCPKit.Sequence) -> FCPKit.Project {
 private func sequence(
   for spine: FCPKit.Spine,
   resources: inout ResourceStore
-) throws -> FCPKit.Sequence {
+) throws(BuildError) -> FCPKit.Sequence {
   try Defaults.sequence(spine: spine, format: resources.format(.p1080p24))
 }
diff --git a/Sources/FCPKitDSL/Spine.swift b/Sources/FCPKitDSL/Spine.swift
index bef9625..04b33db 100644
--- a/Sources/FCPKitDSL/Spine.swift
+++ b/Sources/FCPKitDSL/Spine.swift
@@ -39,9 +39,9 @@ public struct Spine: DSLNode {
   }
 
   /// Lowers this spine into an ordered `<spine>` of story items.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     let packed = try Layout.pack(
-      StoryItemLowering.items(content.contents, resources: &resources),
+      content.contents.spineItems(resources: &resources),
       frameDuration: FormatPreset.p1080p24.format.frameDuration
     )
     return .spine(FCPKit.Spine(items: packed.items))
diff --git a/Sources/FCPKitDSL/Title.swift b/Sources/FCPKitDSL/Title.swift
index c6c9b1d..fdead75 100644
--- a/Sources/FCPKitDSL/Title.swift
+++ b/Sources/FCPKitDSL/Title.swift
@@ -98,7 +98,7 @@ public struct Title: StoryItem {
   }
 
   /// Lowers this title into a `<title>` story item.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     let ref = try resources.effect(name: preset.name, uid: preset.uid)
     let style = FCPKit.TextStyle(ref: "ts1", content: text)
     let definition = FCPKit.TextStyleDef(
@@ -121,7 +121,7 @@ public struct Title: StoryItem {
       text: [FCPKit.TextElement(textStyle: [style])],
       textStyleDef: [definition]
     )
-    element.anchoredItems = try AnchoredItemBuilder.items(anchors, resources: &resources)
+    element.anchoredItems = try anchors.anchoredItems(resources: &resources)
     return .item(.title(element))
   }
 }
diff --git a/Sources/FCPKitDSL/Transition.swift b/Sources/FCPKitDSL/Transition.swift
index 199770a..1dd93ef 100644
--- a/Sources/FCPKitDSL/Transition.swift
+++ b/Sources/FCPKitDSL/Transition.swift
@@ -58,7 +58,7 @@ public struct Transition: StoryItem {
   }
 
   /// Lowers this transition into a `<transition>` story item.
-  public func build(_ resources: inout ResourceStore) throws -> Built {
+  public func build(_ resources: inout ResourceStore) throws(BuildError) -> Built {
     let video = try resources.effect(name: preset.name, uid: preset.videoUID)
     let audio = try resources.effect(name: "Audio Crossfade", uid: preset.audioUID)
     let filters = CrossDissolveFilters.make(video: video, audio: audio)

From 2528191769753dfa4af26fe049d72a91efe26840 Mon Sep 17 00:00:00 2001
From: Leo Dion <leogdion@brightdigit.com>
Date: Mon, 3 Aug 2026 16:56:46 -0400
Subject: [PATCH 5/5] Carry the version property through the v0.1.x merge

`ResourceStore` needs both this branch's public cascade and #42's `version`
property. The merge resolution restored this branch's copy, which predates
#42, so `ResourceStore(version:)` went missing and `Document+Export` failed to
compile against it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 Sources/FCPKitDSL/ResourceStore.swift | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Sources/FCPKitDSL/ResourceStore.swift b/Sources/FCPKitDSL/ResourceStore.swift
index ad323c5..6797c65 100644
--- a/Sources/FCPKitDSL/ResourceStore.swift
+++ b/Sources/FCPKitDSL/ResourceStore.swift
@@ -38,6 +38,9 @@ import Foundation
 public struct ResourceStore {
   internal static let draftID: ResourceID = "draft"
 
+  /// Target document version, used to gate version-specific default vocabulary.
+  internal let version: FCPXMLVersion
+
   private var assets: [FCPKit.Asset] = []
   private var formats: [FCPKit.Format] = []
   private var effects: [FCPKit.Effect] = []
@@ -45,6 +48,11 @@ public struct ResourceStore {
   private var explicitFingerprints: [String: String] = [:]
   private var nextNumber = 1
 
+  /// Creates a store targeting the given document version.
+  internal init(version: FCPXMLVersion = .supportedGeneration) {
+    self.version = version
+  }
+
   private static func formatFingerprint(_ format: FCPKit.Format) -> String {
     [
       format.name ?? "",