Fix #36: lift .anchor onto StoryItem and make DSLNode public

[leogdion]

Closes #36.

Problem

.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.

Approach

Introduces StoryItem — "content that can sit in a spine", matching the DTD's %clip_item; entity — and hangs 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 to Generator(.custom).color(self), so anchoring just performs that desugaring one step earlier.

The DSLNode cascade

A public protocol requirement cannot mention internal types, and DSLNode.build mentions both Built and ResourceStore. Making DSLNode public therefore requires all three — this is not called out in the spec, but it is unavoidable (confirmed with the compiler).

The cascade is kept shallow: every ResourceStore member stays internal, so only the type name is exposed. An outside type can name ResourceStore but cannot call effect(...), so no usable extension point ships. Built is a 6-case enum wrapping already-public FCPKit types, so it exposes nothing new.

Public conformers also need public witnesses, so build became public on DocumentGroup, Event, Library, Project, Sequence, and Spine.

Bug fixed along the way

.anchor replaced rather than appended (replacing(anchors:) → anchors ?? self.anchors), so x.anchor(lane: 1) { … }.anchor(lane: 2) { … } silently dropped lane 1. Latent today because nothing chains — but StoryItem makes chaining the natural idiom the moment .anchor is available everywhere. The shared modifier now appends; replacingAnchors stays the pure setter the spec specifies. Pinned by chainedAnchorsAccumulateLanes.

This changes AssetClip behavior too. No existing call site chains, so nothing breaks.

Also

• Adds the missing .video and .generator cases to anchoredExtent, so an anchored generator contributes to its parent's extent.
• transitionAnchorsAreIgnored pins the documented no-op: the DTD admits no anchored items on <transition>, so they are accepted but never emitted.

Verification

• FCPKIT_REQUIRE_DTD=1 swift test — 68 XCTest + 49/12/25 Swift Testing, all passing, zero fixture changes
• fcpxml-diff schema-completeness --fail-if-total-exceeds 0 — no structural loss
• swift-format lint and swiftlint — clean

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6f71ac30-5432-4552-aeb4-84d14a7378be

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[leogdion]

Follow-up: test coverage gap found in review

Pushed 56dcb07 after re-reviewing this branch.

The .video case I added to anchoredExtent had no test. The existing "anchored item longer than its background" test uses a Title, which the pre-existing .title case already handled — so my new branch could have been deleted and the suite would have stayed green. Now covered by an anchored generator outrunning its background.

Also added two cases that were conformances-without-coverage:

• Negative lanes (.anchor(lane: -1)) — legal FCPXML for content below the primary storyline; only lane 0 is reserved. Issue StoryItem: lift .anchor off AssetClip and make DSLNode public #36 calls this out explicitly and it was untested.
• Title and Gap as anchor hosts — both gained StoryItem conformance here with no direct test.

Correction to my commit message

e4325f7 said it "adds the missing .video and .generator cases to anchoredExtent, so an anchored generator contributes to its parent's extent." That overstated it: I added the anchoredExtent reader cases but left the .generator packing call site passing 0.

Having checked, 0 is actually correct there — FCPKit.Generator has no anchoredItems property at all, because <generator> is absent from the DTD's %anchor_item; list, and the DSL's own Generator lowers to <video> regardless. So there's no bug, but the call site now carries a comment saying why, rather than looking like an unfinished stub.

Gate: 68 XCTest + 49/12/28 Swift Testing (was 25), 0 lint violations, zero fixture changes.

Verified but unchanged

A reviewer flagged that StoryItem/DSLNode are publicly conformable, so an external type could adopt them and get a .anchor that silently discards anchors if its build doesn't lower them. That's true, but it's inherent to the public cascade this PR exists to make — the alternative is the opaque wrapper the spec explicitly rejected. Worth knowing; not worth contorting the design for pre-1.0.

[leogdion]

As a rule never use global functions or properties

[leogdion]

Done in e8bf4b1. These are now statics on an AnchoredItemBuilder enum (.item / .items).

I applied the rule module-wide rather than just here, since it's a general one: storyItems also became StoryItemLowering.items (file renamed to match), and softPromote is handled on #42. Those two predate this branch, but leaving them as the only globals in the module would have undercut the rule. FCPKitDSL now has zero top-level functions.

[leogdion]

Done in 80705de. AnchoredItemBuilder and StoryItemLowering are both gone.

Chasing this turned up a real duplication underneath. 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.

So the anchoring half became the protocol you suggested:

internal protocol AnchorableItem {
  var lane: String? { get set }
  var offset: String? { get set }
  var asAnchoredItem: FCPKit.AnchoredItem { get }
  var asSpineItem: FCPKit.SpineItem { get }
}

Each conformer knows how to re-wrap itself into both ordered-choice containers, so Built.anchorable is the only switch and there are no downcasts. Anchor.build drops from a body with its own parallel switch to three lines.

The rest became extensions on what they operate on:

• Built.anchoredItem() / Built.placed(lane:offset:) — the mapping is genuinely Built → anchored item
• [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)

.gap stays unsupported so behaviour is byte-identical; widening it is a capability change, filed as #49.

Also adopted typed throws here per your other note. Repo-wide audit is #46.

[leogdion]

Are all StoryItem a DSLNode?

[leogdion]

Yes — and good catch, the declaration didn't say so. Fixed in e8bf4b1.

Every conformer is a DSLNode, including the two extension-based ones (Color, Generator) which extend types already declared as such. StoryItem now refines DSLNode instead of DocumentContent, so the four DSLNode, StoryItem declarations drop the redundant conformance.

It also tightens the contract: the free .anchor extension calls replacingAnchors and then depends on the conformer's build actually lowering those anchors into anchoredItems — which only a DSLNode can do. The old DocumentContent bound let a type conform without any way to honour that, so anchors could be silently dropped.

[leogdion]

Confirmed and now enforced — see e8bf4b1 (earlier) and 80705de.

Every conformer is a DSLNode, including the two extension-based ones. StoryItem refines DSLNode rather than DocumentContent, so the four DSLNode, StoryItem declarations dropped the redundant conformance.

The refactor in 80705de makes the reason concrete: .anchor calls replacingAnchors and then depends on the conformer's build lowering those anchors via anchors.anchoredItems(resources:). Only a DSLNode can do that. Under the old DocumentContent bound a type could conform and silently drop every anchor.