@webspatial/platform-visionos 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspatial/platform-visionos",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Used to publish WebSpatial projects to Apple Vision Pro",
   "type": "commonjs",
   "main": "package.json",

package/web-spatial/JSBCommand.swift

@@ -14,7 +14,8 @@ struct AddSpatializedElementToSpatialScene: CommandDataProtocol {
 
 struct CreateSpatializedStatic3DElement: CommandDataProtocol {
     static let commandType: String = "CreateSpatializedStatic3DElement"
-    let modelURL: String
+    let modelURL: String?
+    let sources: [ModelSource]?
 }
 
 struct CreateSpatializedDynamic3DElement: CommandDataProtocol {
@@ -145,6 +146,26 @@ protocol SpatialObjectCommand: CommandDataProtocol {
     var id: String { get }
 }
 
+struct UpdateUnlitMaterialProperties: CommandDataProtocol {
+    static let commandType: String = "UpdateUnlitMaterialProperties"
+    let id: String
+    let color: String?
+    let transparent: Bool?
+    let opacity: Float?
+}
+
+struct RemoveComponentFromEntity: CommandDataProtocol {
+    static let commandType: String = "RemoveComponentFromEntity"
+    let entityId: String
+    let componentId: String
+}
+
+struct SetMaterialsOnEntity: CommandDataProtocol {
+    static let commandType: String = "SetMaterialsOnEntity"
+    let entityId: String
+    let materialIds: [String]
+}
+
 struct DestroyCommand: CommandDataProtocol {
     static let commandType: String = "Destroy"
     var id: String
@@ -240,7 +261,12 @@ struct UpdateSpatializedStatic3DElementProperties: SpatializedElementProperties
     let rotateConstrainedToAxis: Vec3?
 
     let modelURL: String?
+    let sources: [ModelSource]?
     let modelTransform: [Double]?
+    let autoplay: Bool?
+    let loop: Bool?
+    let animationPaused: Bool?
+    let playbackRate: Double?
 }
 
 struct UpdateSpatializedDynamic3DElementProperties: SpatializedElementProperties {

package/web-spatial/WebMsgCommand.swift

@@ -25,6 +25,8 @@ enum SpatialWebMsgType: String, Encodable {
     case spatialmagnify
     case spatialmagnifyend
 
+    case animationstatechange
+
     case objectdestroy
 }
 
@@ -97,14 +99,33 @@ struct WebSpatialMagnifyEndGuestureEvent: Encodable {
     let type: SpatialWebMsgType = .spatialmagnifyend
 }
 
+struct ModelLoadSuccessDetail: Encodable {
+    let src: String
+}
+
 struct ModelLoadSuccess: Encodable {
     let type: SpatialWebMsgType = .modelloaded
+    let detail: ModelLoadSuccessDetail
+
+    init(src: String) {
+        detail = ModelLoadSuccessDetail(src: src)
+    }
 }
 
 struct ModelLoadFailure: Encodable {
     let type: SpatialWebMsgType = .modelloadfailed
 }
 
+struct AnimationStateChangeDetail: Encodable {
+    let paused: Bool
+    let duration: Double
+}
+
+struct AnimationStateChangeEvent: Encodable {
+    let type: SpatialWebMsgType = .animationstatechange
+    let detail: AnimationStateChangeDetail
+}
+
 struct SpatialObjectDestroiedEvent: Encodable {
     let type: SpatialWebMsgType = .objectdestroy
 }

package/web-spatial/manifest.swift

@@ -6,7 +6,7 @@ var pwaManager = PWAManager()
 struct PWAManager: Codable {
     var isLocal: Bool = false
 
-    var start_url: String = "http://localhost:5173/#/geometry-verify"
+    var start_url: String = "http://localhost:5173/"
 
     // var start_url: String = "http://localhost:5173/#/spatial-drag-gesture"
 

package/web-spatial/model/SpatialScene.swift

@@ -85,6 +85,8 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
 
     // TOPIC end
 
+    var isSpatialElementGestureActive = false
+
     var spatialWebViewModel: SpatialWebViewModel
 
     private var meterToPtUnscaled: Double?
@@ -321,6 +323,10 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         spatialWebViewModel.addJSBListener(InitializeAttachmentCommand.self, onInitializeAttachment)
         spatialWebViewModel.addJSBListener(ConvertCoordinate.self, onConvertCoordinate)
 
+        spatialWebViewModel.addJSBListener(UpdateUnlitMaterialProperties.self, onUpdateUnlitMaterialProperties)
+        spatialWebViewModel.addJSBListener(RemoveComponentFromEntity.self, onRemoveComponentFromEntity)
+        spatialWebViewModel.addJSBListener(SetMaterialsOnEntity.self, onSetMaterialsOnEntity)
+
         spatialWebViewModel.addJSBListener(UpdateAttachmentEntityCommand.self, onUpdateAttachmentEntity)
 
         spatialWebViewModel.addOpenWindowListener(protocal: "webspatial", onOpenWindowHandler)
@@ -425,7 +431,7 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         }
     }
 
-    // Temporary storage for webview models awaiting JSB initialization
+    /// Temporary storage for webview models awaiting JSB initialization
     private var pendingAttachmentWebViewModels = [String: SpatialWebViewModel]()
 
     private func handleCreateAttachment(_ url: URL) -> WebViewElementInfo? {
@@ -539,6 +545,9 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
     private func onCreateSpatializedStatic3DElement(command: CreateSpatializedStatic3DElement, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
         let spatialObject: SpatializedStatic3DElement = createSpatializedElement(.SpatializedStatic3DElement)
         spatialObject.modelURL = command.modelURL
+        if let sources = command.sources {
+            spatialObject.sources = sources
+        }
 
         resolve(.success(AddSpatializedElementReply(id: spatialObject.id)))
     }
@@ -581,6 +590,10 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
 
         updateSpatializedElementProperties(spatializedElement, command)
 
+        if let sources = command.sources {
+            spatializedElement.sources = sources
+        }
+
         if let modelURL = command.modelURL {
             spatializedElement.modelURL = modelURL
         }
@@ -600,6 +613,22 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
             spatializedElement.modelTransform = affineTransform3D
         }
 
+        if let autoplay = command.autoplay {
+            spatializedElement.autoplay = autoplay
+        }
+
+        if let loop = command.loop {
+            spatializedElement.loop = loop
+        }
+
+        if let animationPaused = command.animationPaused {
+            spatializedElement.animationPaused = animationPaused
+        }
+
+        if let playbackRate = command.playbackRate {
+            spatializedElement.playbackRate = playbackRate
+        }
+
         resolve(.success(baseReplyData))
     }
 
@@ -1107,22 +1136,22 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         resolve(.success(ConvertReply(id: command.entityId, position: point)))
     }
 
-    /// Input: command.position, command.fromId, command.toId
-    /// fromId/toId can reference either the scene (window) or an entity.
-    /// Step 1: Convert position to window coordinates (view global, px)
-    ///   - If from is window (scene), position is already in view global (px). Go to Step 2.
-    ///   - If from is 2d frame(SpatializedElement), position is in view local (px).
-    ///     - view local → window (view global, px) using SpatializedElement.convertToScene
-    ///   - If from is an entity, position is in reality entity local (meters):
-    ///     - entity local → reality world (scene)
-    ///     - reality world → window (view global, px)
-    /// Step 2: Convert window coordinates (view global, px) to target output
-    ///   - If to is window, output directly.
-    ///   - If to is 2d frame(SpatializedElement), output in view local (px).
-    ///     - window (view global, px) → view local using SpatializedElement.convertFromScene
-    ///   - If to is an entity, output in reality entity local (meters):
-    ///     - window (view global, px) → reality world (scene)
-    ///     - reality world → reality entity local (meters)
+    // Input: command.position, command.fromId, command.toId
+    // fromId/toId can reference either the scene (window) or an entity.
+    // Step 1: Convert position to window coordinates (view global, px)
+    //   - If from is window (scene), position is already in view global (px). Go to Step 2.
+    //   - If from is 2d frame(SpatializedElement), position is in view local (px).
+    //     - view local → window (view global, px) using SpatializedElement.convertToScene
+    //   - If from is an entity, position is in reality entity local (meters):
+    //     - entity local → reality world (scene)
+    //     - reality world → window (view global, px)
+    // Step 2: Convert window coordinates (view global, px) to target output
+    //   - If to is window, output directly.
+    //   - If to is 2d frame(SpatializedElement), output in view local (px).
+    //     - window (view global, px) → view local using SpatializedElement.convertFromScene
+    //   - If to is an entity, output in reality entity local (meters):
+    //     - window (view global, px) → reality world (scene)
+    //     - reality world → reality entity local (meters)
 
     private func onConvertCoordinate(command: ConvertCoordinate, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
         func isSceneId(_ id: String) -> Bool {
@@ -1196,6 +1225,52 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         resolve(.success(baseReplyData))
     }
 
+    private func onUpdateUnlitMaterialProperties(command: UpdateUnlitMaterialProperties, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        guard let material = spatialObjects[command.id] as? SpatialUnlitMaterial else {
+            resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "Material \(command.id) not found")))
+            return
+        }
+        material.updateProperties(color: command.color, transparent: command.transparent, opacity: command.opacity)
+        // Re-apply material to any ModelComponent or ModelEntity override that references it
+        for (_, obj) in spatialObjects {
+            if let comp = obj as? SpatialModelComponent, comp.usesMaterial(command.id) {
+                comp.refreshMaterials()
+            } else if let modelEntity = obj as? SpatialModelEntity, modelEntity.usesMaterial(command.id) {
+                modelEntity.refreshMaterials()
+            }
+        }
+        resolve(.success(baseReplyData))
+    }
+
+    private func onRemoveComponentFromEntity(command: RemoveComponentFromEntity, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        guard let entity = spatialObjects[command.entityId] as? SpatialEntity,
+              let component = spatialObjects[command.componentId] as? SpatialComponent
+        else {
+            resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "Remove component failed")))
+            return
+        }
+        entity.removeComponent(component)
+        resolve(.success(baseReplyData))
+    }
+
+    private func onSetMaterialsOnEntity(command: SetMaterialsOnEntity, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        guard let entity = spatialObjects[command.entityId] as? SpatialModelEntity else {
+            resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "ModelEntity \(command.entityId) not found")))
+            return
+        }
+        var materials: [SpatialMaterial] = []
+        for mid in command.materialIds {
+            if let material = spatialObjects[mid] as? SpatialMaterial {
+                materials.append(material)
+            } else {
+                resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "Material \(mid) not found")))
+                return
+            }
+        }
+        entity.setMaterials(materials)
+        resolve(.success(baseReplyData))
+    }
+
     private func addSpatialObject(_ object: any SpatialObjectProtocol) {
         var spatialObject = object
         spatialObjects[spatialObject.spatialId] = spatialObject
@@ -1227,19 +1302,12 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
             return nil
         }
 
-        for (_, object) in spatialObjects {
-            guard let dynamic3dElement = object as? SpatializedDynamic3DElement else {
-                continue
-            }
-
-            let root = dynamic3dElement.getRoot()
-            var current: Entity? = entity
-            while let node = current {
-                if node === root {
-                    return dynamic3dElement
-                }
-                current = node.parent
+        var current: Entity? = entity
+        while let node = current {
+            if let rootEntity = node as? SpatialRootEntity {
+                return rootEntity.root
             }
+            current = node.parent
         }
 
         return nil

package/web-spatial/model/SpatializedDynamic3DElement.swift

@@ -4,9 +4,14 @@ import RealityKit
 
 @Observable
 class SpatializedDynamic3DElement: SpatializedElement {
-    private var rootEntity = SpatialEntity()
+    private var rootEntity = SpatialRootEntity()
     private var viewContent: RealityViewContent? = nil
 
+    override init() {
+        super.init()
+        rootEntity.root = self
+    }
+
     func getRoot() -> SpatialEntity {
         return rootEntity
     }

package/web-spatial/model/SpatializedStatic3DElement.swift

@@ -1,10 +1,25 @@
 import Foundation
 import SwiftUI
 
+struct ModelSource: Codable, Equatable {
+    let src: String
+    let type: String?
+}
+
 @Observable
 class SpatializedStatic3DElement: SpatializedElement {
-    var modelURL: String = ""
+    var modelURL: String?
+    var sources: [ModelSource] = []
     var modelTransform: AffineTransform3D = .identity
+    var autoplay: Bool = false
+    var loop: Bool = false
+    var animationPaused: Bool = true
+    var playbackRate: Double = 1.0
+    var allSources: [ModelSource] {
+        return if let modelURL {
+            [ModelSource(src: modelURL, type: nil)] + sources
+        } else { sources }
+    }
 
     enum CodingKeys: String, CodingKey {
         case modelURL, type

package/web-spatial/model/dynamic3d/SpatialComponent.swift

@@ -43,7 +43,12 @@ class SpatialComponent: SpatialObject {
 
 @Observable
 class SpatialModelComponent: SpatialComponent {
+    private(set) var spatialMaterials: [SpatialMaterial] = []
+    private(set) var mesh: Geometry?
+
     init(mesh: Geometry, mats: [SpatialMaterial]) {
+        spatialMaterials = mats
+        self.mesh = mesh
         super.init(.ModelComponent)
         var materials: [any RealityKit.Material] = []
         for item in mats {
@@ -52,6 +57,27 @@ class SpatialModelComponent: SpatialComponent {
         _resource = ModelComponent(mesh: mesh.resource!, materials: materials)
     }
 
+    /// Rebuild the ModelComponent with current material resources (called after material properties change)
+    func refreshMaterials() {
+        guard let mesh = mesh else { return }
+        var materials: [any RealityKit.Material] = []
+        for item in spatialMaterials {
+            if let res = item.resource {
+                materials.append(res)
+            }
+        }
+        _resource = ModelComponent(mesh: mesh.resource!, materials: materials)
+        if let entity = _entity {
+            entity.components.set(_resource!)
+            entity.generateCollisionShapes(recursive: true)
+        }
+    }
+
+    /// Check if this component uses the given material
+    func usesMaterial(_ materialId: String) -> Bool {
+        return spatialMaterials.contains { $0.id == materialId }
+    }
+
     override func addToEntity(entity: SpatialEntity) {
         super.addToEntity(entity: entity)
         entity.generateCollisionShapes(recursive: true)
@@ -63,7 +89,12 @@ class SpatialModelComponent: SpatialComponent {
     }
 
     override func onDestroy() {
+        // TODO(P2): `mesh` is a registered `Geometry` spatial object; clearing the reference does not
+        // run `Geometry.destroy()`, so dynamic mesh rebuilds can leak mesh/registry entries until the
+        // scene ends. Call `mesh?.destroy()` (or equivalent) before nil-ing when ownership is exclusive.
         _resource = nil
+        spatialMaterials = []
+        mesh = nil
     }
 }
 

package/web-spatial/model/dynamic3d/SpatialMaterial.swift

@@ -22,16 +22,38 @@ class SpatialMaterial: SpatialObject {
 
 @Observable
 class SpatialUnlitMaterial: SpatialMaterial {
-    let color: UIColor
+    private(set) var currentColor: UIColor
+    private(set) var currentTexture: TextureResource?
+    private(set) var currentTransparent: Bool
+    private(set) var currentOpacity: Float
 
     init(_ color: String, _ texture: TextureResource? = nil, _ transparent: Bool = true, _ opacity: Float = 1) {
-        self.color = UIColor(Color(hex: color))
+        currentColor = UIColor(Color(hex: color))
+        currentTexture = texture
+        currentTransparent = transparent
+        currentOpacity = opacity
         super.init(.UnlitMaterial)
         var mat = UnlitMaterial()
-        mat.color = .init(tint: UIColor(Color(hex: color)), texture: texture != nil ? .init(texture!) : nil)
+        mat.color = .init(tint: currentColor, texture: texture != nil ? .init(texture!) : nil)
         mat.blending = transparent ? .transparent(opacity: .init(scale: opacity)) : .opaque
         _resource = mat
     }
+
+    func updateProperties(color: String?, transparent: Bool?, opacity: Float?) {
+        if let color = color {
+            currentColor = UIColor(Color(hex: color))
+        }
+        if let transparent = transparent {
+            currentTransparent = transparent
+        }
+        if let opacity = opacity {
+            currentOpacity = opacity
+        }
+        var mat = UnlitMaterial()
+        mat.color = .init(tint: currentColor, texture: currentTexture != nil ? .init(currentTexture!) : nil)
+        mat.blending = currentTransparent ? .transparent(opacity: .init(scale: currentOpacity)) : .opaque
+        _resource = mat
+    }
 }
 
 enum SpatialMaterialType: String {

package/web-spatial/model/dynamic3d/SpatialModelEntity.swift

@@ -4,6 +4,9 @@ import SwiftUI
 @Observable
 class SpatialModelEntity: SpatialEntity {
     private var modelEntity: Entity?
+    /// Retained so `UpdateUnlitMaterialProperties` can re-apply current `SpatialMaterial.resource` after native material updates.
+    private(set) var overrideSpatialMaterials: [SpatialMaterial] = []
+
     required init(_ modelResource: SpatialModelResource, _ _name: String = "") {
         super.init(_name)
         modelEntity = modelResource.resource
@@ -15,12 +18,44 @@ class SpatialModelEntity: SpatialEntity {
         super.init()
     }
 
+    func setMaterials(_ materials: [SpatialMaterial]) {
+        overrideSpatialMaterials = materials
+        applyOverrideMaterials()
+    }
+
+    /// Re-apply stored override materials using each `SpatialMaterial`'s current `resource` (e.g. after unlit property updates).
+    func refreshMaterials() {
+        applyOverrideMaterials()
+    }
+
+    func usesMaterial(_ materialId: String) -> Bool {
+        overrideSpatialMaterials.contains { $0.id == materialId }
+    }
+
+    private func applyOverrideMaterials() {
+        guard let modelEntity = modelEntity else { return }
+        // TODO(P1): Clearing overrides (`setMaterials([])`) assigns an empty material list here; there is
+        // no baseline of the model asset’s authored materials to restore. Persist per-component defaults
+        // at load (or skip writing when overrides are empty) so clears return to the authored look.
+        func applyMaterials(to entity: Entity) {
+            if var modelComp = entity.components[ModelComponent.self] {
+                modelComp.materials = overrideSpatialMaterials.compactMap { $0.resource }
+                entity.components.set(modelComp)
+            }
+            for child in entity.children {
+                applyMaterials(to: child)
+            }
+        }
+        applyMaterials(to: modelEntity)
+    }
+
     override func onDestroy() {
         super.onDestroy()
         if let modelEntity = modelEntity {
             removeChild(modelEntity)
         }
         modelEntity = nil
+        overrideSpatialMaterials = []
     }
 
     enum CodingKeys: String, CodingKey {

package/web-spatial/model/dynamic3d/SpatialRootEntity.swift

@@ -0,0 +1,12 @@
+import RealityKit
+import SwiftUI
+
+@Observable
+class SpatialRootEntity: SpatialEntity {
+    weak var root: SpatializedDynamic3DElement?
+
+    convenience init(root: SpatializedDynamic3DElement) {
+        self.init()
+        self.root = root
+    }
+}

package/web-spatial/view/Spatialized2DElementView.swift

@@ -72,6 +72,9 @@ struct Spatialized2DElementView: View {
         DragGesture()
             .onChanged { gesture in
 //                print("\(spatialized2DElement.name) dragWebGesture")
+                if spatialScene.isSpatialElementGestureActive {
+                    return
+                }
                 if spatialized2DElement.scrollPageEnabled {
                     if !gestureData.dragStarted {
                         gestureData.dragStarted = true
@@ -86,6 +89,9 @@ struct Spatialized2DElementView: View {
             }
             .onEnded { _ in
                 print("\(spatialized2DElement.name) dragWebGestureEnd")
+                if spatialScene.isSpatialElementGestureActive {
+                    return
+                }
                 if spatialized2DElement.scrollPageEnabled {
                     gestureData.dragStarted = false
                     gestureData.dragStart = 0

package/web-spatial/view/SpatializedElementView.swift

@@ -22,7 +22,7 @@ struct SpatializedElementView<Content: View>: View {
 
     /// Begin Interaction
     var gesture: some Gesture {
-        DragGesture(minimumDistance: 10)
+        DragGesture(minimumDistance: 10, coordinateSpace: .named("SpatialScene"))
             .onChanged(onDragging)
             .onEnded(onDraggingEnded)
             .simultaneously(with:
@@ -74,14 +74,13 @@ struct SpatializedElementView<Content: View>: View {
     }
 
     private func onDragging(_ event: DragGesture.Value) {
+        if !gestureState.isDrag {
+            spatialScene.isSpatialElementGestureActive = true
+        }
+
         if spatializedElement.enableDragStartGesture, !gestureState.isDrag {
-            let frameZ = localFrameOffsetZ()
-            let startLocal = Point3D(
-                x: event.startLocation3D.x,
-                y: event.startLocation3D.y,
-                z: event.startLocation3D.z - frameZ
-            )
-            let globalPoint3D = localToScene(event.startLocation3D)
+            let startLocal = sceneToLocal(event.startLocation3D)
+            let globalPoint3D = event.startLocation3D
             let gestureEvent = WebSpatialDragStartGuestureEvent(detail: .init(
                 startLocation3D: startLocal,
                 globalLocation3D: globalPoint3D
@@ -102,6 +101,7 @@ struct SpatializedElementView<Content: View>: View {
 
     private func onDraggingEnded(_ event: DragGesture.Value) {
         gestureState.isDrag = false
+        spatialScene.isSpatialElementGestureActive = false
         if spatializedElement.enableDragEndGesture {
             let gestureEvent = WebSpatialDragEndGuestureEvent()
             spatialScene.sendWebMsg(spatializedElement.id, gestureEvent)
@@ -121,6 +121,11 @@ struct SpatializedElementView<Content: View>: View {
         return Point3D(x: scene.x, y: scene.y, z: scene.z)
     }
 
+    private func sceneToLocal(_ scenePoint: Point3D) -> Point3D {
+        let local = spatializedElement.convertFromScene(SIMD3<Double>(scenePoint.x, scenePoint.y, scenePoint.z))
+        return Point3D(x: local.x, y: local.y, z: local.z)
+    }
+
     private func onTapEnded(_ event: SpatialTapGesture.Value) {
         if spatializedElement.enableTapGesture {
             let frameZ = localFrameOffsetZ()
@@ -198,6 +203,9 @@ struct SpatializedElementView<Content: View>: View {
             // Gesture before .position(): event.location3D is in the element's local space
             // (top-left origin), and does not include visual transforms.
             .simultaneousGesture(enableGesture ? gesture : nil)
+            .onDisappear {
+                spatialScene.isSpatialElementGestureActive = false
+            }
             .onGeometryChange3D(for: AffineTransform3D.self) { proxy in
                 proxy.transform(in: .named("SpatialScene"))!
             } action: { new in

package/web-spatial/view/SpatializedStatic3DView.swift

@@ -5,12 +5,16 @@ struct SpatializedStatic3DView: View {
     @Environment(SpatializedElement.self) var spatializedElement: SpatializedElement
     @Environment(SpatialScene.self) var spatialScene: SpatialScene
 
+    @State private var asset: Model3DAsset?
+    @State private var source: String?
+    @State private var isLoading = false
+
     private var spatializedStatic3DElement: SpatializedStatic3DElement {
         return spatializedElement as! SpatializedStatic3DElement
     }
 
-    func onLoadSuccess() {
-        spatialScene.sendWebMsg(spatializedElement.id, ModelLoadSuccess())
+    func onLoadSuccess(src: String) {
+        spatialScene.sendWebMsg(spatializedElement.id, ModelLoadSuccess(src: src))
     }
 
     func onLoadFailure() {
@@ -28,33 +32,28 @@ struct SpatializedStatic3DView: View {
         let z = translation.z
 
         let enableGesture = spatializedElement.enableGesture
-        let rawModelURL = spatializedStatic3DElement.modelURL
-        let modelURL = rawModelURL.hasPrefix("file://")
-            ? pwaManager.getLocalResourceURL(url: rawModelURL)
-            : rawModelURL
-        if let url = URL(string: modelURL) {
-            Model3D(url: url) { newPhase in
-                switch newPhase {
-                case .empty:
+        if !spatializedStatic3DElement.allSources.isEmpty {
+            Group {
+                if isLoading {
                     ProgressView()
-                case let .success(resolvedModel3D):
-                    resolvedModel3D
-                        .resizable(true)
-                        .aspectRatio(
-                            nil,
-                            contentMode: .fit
-                        )
-                        .if(!depth.isZero) { view in view.scaledToFit3D() }
-                        .onAppear {
-                            self.onLoadSuccess()
-                        }
-                        .if(enableGesture) { view in view.hoverEffect() }
-                case .failure:
+                } else if let asset, let source {
+                    Model3D(asset: asset) { resolvedModel3D in
+                        resolvedModel3D
+                            .resizable(true)
+                            .aspectRatio(
+                                nil,
+                                contentMode: .fit
+                            )
+                            .if(!depth.isZero) { view in view.scaledToFit3D() }
+                            .onAppear {
+                                self.onLoadSuccess(src: source)
+                            }
+                            .if(enableGesture) { view in view.hoverEffect() }
+                    }
+                } else {
                     Text("").onAppear {
                         self.onLoadFailure()
                     }
-                @unknown default:
-                    EmptyView()
                 }
             }
             .scaleEffect(
@@ -67,8 +66,95 @@ struct SpatializedStatic3DView: View {
             )
             .offset(x: x, y: y)
             .offset(z: z)
+            .onChange(of: asset?.animationPlaybackController?.isComplete) { _, isComplete in
+                guard isComplete == true else { return }
+                if spatializedStatic3DElement.loop,
+                   let asset,
+                   let animation = asset.availableAnimations.first
+                {
+                    asset.selectedAnimation = animation
+                    asset.animationPlaybackController?.speed = Float(spatializedStatic3DElement.playbackRate)
+                    asset.animationPlaybackController?.resume()
+                } else {
+                    // Non-looping animation completed naturally; sync paused state to JS
+                    spatializedStatic3DElement.animationPaused = true
+                }
+            }
+            .onChange(of: spatializedStatic3DElement.animationPaused) { onPlayback(isPaused: $1) }
+            .onChange(of: spatializedStatic3DElement.playbackRate) { asset?.animationPlaybackController?.speed = Float($1) }
+            .task(id: spatializedStatic3DElement.allSources) { await loadSources() }
         } else {
             EmptyView()
         }
     }
+
+    /// Plays or pauses the model animation and sends an animation state to the web code
+    private func onPlayback(isPaused: Bool) {
+        guard let asset else {
+            // If entity has not loaded yet and play is called then autoplay after load
+            if !isPaused { spatializedStatic3DElement.autoplay = true }
+            return
+        }
+        // Setting selectedAnimation resets the animation and autoplays on first load
+        if asset.selectedAnimation == nil || asset.animationPlaybackController?.isComplete == true {
+            asset.selectedAnimation = asset.availableAnimations.first
+        }
+        let controller = asset.animationPlaybackController
+        controller?.speed = Float(spatializedStatic3DElement.playbackRate)
+        isPaused ? controller?.pause() : controller?.resume()
+        let duration = controller?.duration ?? 0
+        spatialScene.sendWebMsg(
+            spatializedElement.id,
+            AnimationStateChangeEvent(
+                detail: AnimationStateChangeDetail(paused: isPaused, duration: duration)
+            )
+        )
+    }
+
+    /// Downloads a remote model file and loads it as a Model3DAsset.
+    /// Model3DAsset(url:) requires a local file URL, so remote
+    /// resources must be downloaded first.
+    private func loadAsset(from url: URL) async throws -> Model3DAsset {
+        if url.isFileURL {
+            return try await Model3DAsset(url: url)
+        }
+        let (tempURL, _) = try await URLSession.shared.download(from: url)
+        // TODO: Use FileManager.temporaryDirectory and FileManager.removeItem for auto cleanup
+        let localURL = tempURL.deletingPathExtension()
+            .appendingPathExtension(url.pathExtension)
+        try FileManager.default.moveItem(at: tempURL, to: localURL)
+        return try await Model3DAsset(url: localURL)
+    }
+
+    private func loadSources() async {
+        isLoading = true
+        let result = await loadSources(spatializedStatic3DElement.allSources)
+        asset = result?.asset
+        source = result?.url.absoluteString
+        if spatializedStatic3DElement.autoplay {
+            // If animationPaused didn't change then SwiftUI will not trigger onChange so manually trigger playback
+            // This happens when play is called before load and autoplay is enabled
+            if spatializedStatic3DElement.animationPaused {
+                spatializedStatic3DElement.animationPaused = false
+            } else { onPlayback(isPaused: false) }
+        }
+        isLoading = false
+    }
+
+    /// Attempts to load from each source in order, returning the first success.
+    private func loadSources(_ sources: [ModelSource]) async -> (url: URL, asset: Model3DAsset)? {
+        for source in sources {
+            guard let url = localOrRemoteURL(url: source.src) else { continue }
+            do {
+                return try (url, await loadAsset(from: url))
+            } catch {
+                continue
+            }
+        }
+        return nil
+    }
+}
+
+private func localOrRemoteURL(url: String) -> URL? {
+    URL(string: url.hasPrefix("file://") ? pwaManager.getLocalResourceURL(url: url) : url)
 }

package/web-spatial.xcodeproj/project.pbxproj

@@ -70,6 +70,7 @@
 				dynamic3d/SpatialMaterial.swift,
 				dynamic3d/SpatialModelEntity.swift,
 				dynamic3d/SpatialModelResource.swift,
+				dynamic3d/SpatialRootEntity.swift,
 				dynamic3d/SpatialTextureResource.swift,
 				SpatialApp.swift,
 				Spatialized2DElement.swift,