Support binary XCFramework dependencies in SPM build system (#75)

Author: obj-p

Sources/PreviewsCore/SPMBuildSystem.swift

@@ -71,11 +71,20 @@ public actor SPMBuildSystem: BuildSystem {
             consumerTargetName: targetName
         )
 
+        // 6b. Discover binary XCFramework dependencies.
+        //     SPM copies pre-built .framework bundles (from binaryTarget / XCFramework
+        //     dependencies) directly into binPath. These aren't covered by the
+        //     .build/-directory scan above — they need -F (framework search path)
+        //     and -framework flags instead of -L/-l.
+        let frameworkNames = collectFrameworks(binPath: binPath)
+
         // 7. Build compiler flags
         //    -I <Modules>   resolves dependency .swiftmodule files at compile time
         //    -L <binPath>   library search path for the archives created above
         //    -l<Dep>        per-dependency archive (lazy archive linking means only
         //                   object files actually referenced get pulled in)
+        //    -F <binPath>   framework search path for binary XCFramework deps
+        //    -framework X   link against a binary framework
         var flags: [String] = [
             "-I", modulesDir.path,
         ]
@@ -85,6 +94,16 @@ public actor SPMBuildSystem: BuildSystem {
                 flags += ["-l\(dep)"]
             }
         }
+        if !frameworkNames.isEmpty {
+            flags += ["-F", binPath.path]
+            for fw in frameworkNames {
+                flags += ["-framework", fw]
+            }
+            // Embed the framework search path as an rpath so dlopen can
+            // find the framework at runtime (the dylib references it via
+            // @rpath/Foo.framework/...).
+            flags += ["-Xlinker", "-rpath", "-Xlinker", binPath.path]
+        }
 
         // Add C module include paths for targets with C shims
         let targetBuildDir = binPath.appendingPathComponent("\(targetName).build")
@@ -247,6 +266,34 @@ public actor SPMBuildSystem: BuildSystem {
         return libs
     }
 
+    /// Collect `.framework` bundles in binPath (binary XCFramework dependencies).
+    /// Returns the framework names (e.g. ["Lottie"]) for use with `-framework`.
+    private func collectFrameworks(binPath: URL) -> [String] {
+        let fm = FileManager.default
+        guard
+            let entries = try? fm.contentsOfDirectory(
+                at: binPath,
+                includingPropertiesForKeys: [.isDirectoryKey],
+                options: [.skipsHiddenFiles]
+            )
+        else {
+            return []
+        }
+
+        var frameworks: [String] = []
+        for entry in entries {
+            let name = entry.lastPathComponent
+            guard name.hasSuffix(".framework") else { continue }
+            var isDir: ObjCBool = false
+            guard fm.fileExists(atPath: entry.path, isDirectory: &isDir), isDir.boolValue else {
+                continue
+            }
+            let frameworkName = String(name.dropLast(".framework".count))
+            frameworks.append(frameworkName)
+        }
+        return frameworks
+    }
+
     /// Recursively collect `.o` files under a target's build directory, including
     /// files named `Foo.swift.o` that swift build emits for Swift sources.
     private func collectObjectFiles(in directory: URL) -> [URL] {

Tests/PreviewsCoreTests/PreviewSessionBuildContextTests.swift

@@ -73,6 +73,27 @@ struct PreviewSessionBuildContextTests {
             !flags.contains("-lToDo"),
             "Consumer target should not be linked as a library"
         )
+        // Binary XCFramework dependency (lottie-spm) — SPM copies .framework bundles
+        // into binPath instead of producing .build/ directories with loose .o files.
+        #expect(
+            flags.contains("-F"),
+            "SPMBuildSystem should add -F <binPath> for binary framework deps; flags were: \(flags)"
+        )
+        #expect(
+            flags.contains("-framework"),
+            "SPMBuildSystem should add -framework flags for binary deps; flags were: \(flags)"
+        )
+        // Verify the actual framework name is emitted, not just the flag.
+        if let idx = flags.firstIndex(of: "-framework") {
+            #expect(
+                idx + 1 < flags.count && flags[idx + 1] == "Lottie",
+                "Expected -framework Lottie; flags were: \(flags)"
+            )
+        }
+        #expect(
+            flags.contains("-rpath"),
+            "SPMBuildSystem should add -rpath for framework dlopen; flags were: \(flags)"
+        )
     }
 
     @Test("Tier 2 compile: dylib + populated literals + DesignTimeStore symbols")

examples/spm/Package.swift

@@ -9,7 +9,8 @@ let package = Package(
         .library(name: "ToDoExtras", targets: ["ToDoExtras"]),
     ],
     dependencies: [
-        .package(path: "LocalDep")
+        .package(path: "LocalDep"),
+        .package(url: "https://github.com/airbnb/lottie-spm.git", from: "4.4.0"),
     ],
     targets: [
         .target(
@@ -18,7 +19,11 @@ let package = Package(
         ),
         .target(
             name: "ToDo",
-            dependencies: ["ToDoExtras", .product(name: "LocalDep", package: "LocalDep")],
+            dependencies: [
+                "ToDoExtras",
+                .product(name: "LocalDep", package: "LocalDep"),
+                .product(name: "Lottie", package: "lottie-spm"),
+            ],
             path: "Sources/ToDo"
         ),
     ]

examples/spm/Sources/ToDo/ToDoView.swift

@@ -1,3 +1,4 @@
+import Lottie
 import SwiftUI
 
 /// A view that references `Item` from Item.swift.
@@ -60,6 +61,12 @@ struct ToDoView: View {
                 }
             }
             .navigationTitle("My Items")
+            .overlay {
+                if items.isEmpty {
+                    LottieView(animation: nil)
+                        .frame(width: 100, height: 100)
+                }
+            }
         }
     }
 }