@webspatial/platform-visionos 1.6.1 → 1.7.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@webspatial/platform-visionos",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Used to publish WebSpatial projects to Apple Vision Pro",
   "type": "commonjs",
   "main": "package.json",
   "engines": {
-    "node": ">=14.15.0"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",

package/web-spatial/JSBCommand.swift

@@ -16,6 +16,7 @@ struct CreateSpatializedStatic3DElement: CommandDataProtocol {
     static let commandType: String = "CreateSpatializedStatic3DElement"
     let modelURL: String?
     let sources: [ModelSource]?
+    let loading: String?
 }
 
 struct CreateSpatializedDynamic3DElement: CommandDataProtocol {
@@ -52,6 +53,12 @@ struct CreateTexture: CommandDataProtocol {
     let url: String
 }
 
+struct UpdateTextureProperties: CommandDataProtocol {
+    static let commandType: String = "UpdateTextureProperties"
+    let id: String
+    let url: String?
+}
+
 struct CreateModelAsset: CommandDataProtocol {
     static let commandType: String = "CreateModelAsset"
     let url: String
@@ -150,6 +157,7 @@ struct UpdateUnlitMaterialProperties: CommandDataProtocol {
     static let commandType: String = "UpdateUnlitMaterialProperties"
     let id: String
     let color: String?
+    let textureId: String?
     let transparent: Bool?
     let opacity: Float?
 }
@@ -267,6 +275,9 @@ struct UpdateSpatializedStatic3DElementProperties: SpatializedElementProperties
     let loop: Bool?
     let animationPaused: Bool?
     let playbackRate: Double?
+    let currentTime: Double?
+    let posterURL: String?
+    let loading: String?
 }
 
 struct UpdateSpatializedDynamic3DElementProperties: SpatializedElementProperties {

package/web-spatial/WebMsgCommand.swift

@@ -119,6 +119,9 @@ struct ModelLoadFailure: Encodable {
 struct AnimationStateChangeDetail: Encodable {
     let paused: Bool
     let duration: Double
+    let currentTime: Double
+    /// Unix epoch time in milliseconds
+    let timestamp: Double
 }
 
 struct AnimationStateChangeEvent: Encodable {

package/web-spatial/manager/Dynamic3DManager.swift

@@ -1,6 +1,85 @@
+import CryptoKit
 import Foundation
 import RealityKit
 
+/// Serializes remote URL → local file for each distinct URL string and uses a unique on-disk name
+/// (hash + basename) so concurrent loads never `removeItem` a path another `TextureResource` read
+/// is using (the old `Documents/lastPathComponent` scheme collided across scenes / retries).
+private actor RemoteResourceLoadCache {
+    static let shared = RemoteResourceLoadCache()
+
+    private var inFlight: [String: Task<URL, Error>] = [:]
+
+    func localFileURL(forRemote urlString: String) async throws -> URL {
+        if let existing = inFlight[urlString] {
+            return try await existing.value
+        }
+        let task = Task {
+            try await Self.downloadInstallIfNeeded(urlString: urlString)
+        }
+        inFlight[urlString] = task
+        do {
+            let url = try await task.value
+            inFlight[urlString] = nil
+            return url
+        } catch {
+            inFlight[urlString] = nil
+            throw error
+        }
+    }
+
+    private static func downloadInstallIfNeeded(urlString: String) async throws -> URL {
+        guard let remote = URL(string: urlString) else {
+            throw NSError(
+                domain: "Invalid URL",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to create URL from string: \(urlString)"]
+            )
+        }
+        guard let documents = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else {
+            throw NSError(
+                domain: "Download Error",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "Documents directory is unavailable"]
+            )
+        }
+        let destination = cacheFileURL(documents: documents, urlString: urlString)
+        let fm = FileManager.default
+        if fm.fileExists(atPath: destination.path) {
+            return destination
+        }
+
+        print("start load")
+        let (tempURL, response) = try await URLSession.shared.download(from: remote)
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw NSError(
+                domain: "HTTP Error",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "Missing HTTP response"]
+            )
+        }
+        guard (200 ... 299).contains(httpResponse.statusCode) else {
+            throw NSError(
+                domain: "HTTP Error",
+                code: httpResponse.statusCode,
+                userInfo: [NSLocalizedDescriptionKey: "HTTP Error \(httpResponse.statusCode)"]
+            )
+        }
+        try await FileCoordinator.shared.moveReplacingIfExists(from: tempURL, to: destination)
+        print("load complete")
+        return destination
+    }
+
+    private static func cacheFileURL(documents: URL, urlString: String) -> URL {
+        let digest = SHA256.hash(data: Data(urlString.utf8))
+        let hex = digest.prefix(8).reduce(into: "") { $0.append(String(format: "%02x", $1)) }
+        var baseName = URL(string: urlString)?.lastPathComponent ?? "asset"
+        if baseName.isEmpty { baseName = "asset" }
+        let safe = baseName.replacingOccurrences(of: "/", with: "_")
+        return documents.appendingPathComponent("\(hex)_\(safe)")
+    }
+}
+
 enum GeometryCreationError: LocalizedError {
     case invalidType(String)
     case missingFields(String, [String])
@@ -67,7 +146,17 @@ class Dynamic3DManager {
     // Error messages are thrown from createGeometry using GeometryCreationError
 
     static func createUnlitMaterial(_ props: CreateUnlitMaterial, _ tex: TextureResource? = nil) -> SpatialUnlitMaterial {
-        return SpatialUnlitMaterial(props.color ?? "#FFFFFF", tex, props.transparent ?? true, props.opacity ?? 1)
+        let textureSpatialId: String? = {
+            guard let tid = props.textureId, !tid.isEmpty else { return nil }
+            return tid
+        }()
+        return SpatialUnlitMaterial(
+            props.color ?? "#FFFFFF",
+            tex,
+            props.transparent ?? true,
+            props.opacity ?? 1,
+            textureSpatialId: textureSpatialId
+        )
     }
 
     static func loadResourceToLocal(_ urlString: String, loadComplete: @escaping (Result<URL, Error>) -> Void) {
@@ -80,43 +169,14 @@ class Dynamic3DManager {
             loadComplete(.success(localUrl))
             return
         }
-        // load net file
-        guard let url = URL(string: urlString) else {
-            loadComplete(.failure(NSError(domain: "Invalid URL", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to create URL from string: \(urlString)"])))
-            return
-        }
-        // Use an immutable URL to avoid capturing a mutable var in concurrent code
-        let documentsUrl = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.appendingPathComponent(url.lastPathComponent)
-        let session = URLSession(configuration: URLSessionConfiguration.default)
-        var request = URLRequest(url: url)
-        request.httpMethod = "GET"
-        print("start load")
-        let task = session.downloadTask(with: request, completionHandler: { location, response, error in
-            if let error = error {
+        // load net file — coalesced per URL + unique cache filename (see RemoteResourceLoadCache).
+        Task {
+            do {
+                let url = try await RemoteResourceLoadCache.shared.localFileURL(forRemote: urlString)
+                loadComplete(.success(url))
+            } catch {
                 loadComplete(.failure(error))
-                return
             }
-            if let httpResponse = response as? HTTPURLResponse, !(200 ... 299).contains(httpResponse.statusCode) {
-                let error = NSError(domain: "HTTP Error", code: httpResponse.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP Error \(httpResponse.statusCode)"])
-                loadComplete(.failure(error))
-                return
-            }
-            guard let location = location else {
-                loadComplete(.failure(NSError(domain: "Download Error", code: 0, userInfo: [NSLocalizedDescriptionKey: "Download location is nil"])))
-                return
-            }
-            Task {
-                do {
-                    try await FileCoordinator.shared.moveReplacingIfExists(from: location, to: documentsUrl)
-                    print("load complete")
-                    loadComplete(.success(documentsUrl))
-                } catch {
-                    print("File operation error: \(error)")
-                    loadComplete(.failure(error))
-                }
-            }
-
-        })
-        task.resume()
+        }
     }
 }

package/web-spatial/manifest.swift

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

package/web-spatial/model/MaterialSceneRefresh.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+/// Scene-level helpers for keeping RealityKit model components in sync after material / texture changes.
+/// Per-material mutation lives on `SpatialUnlitMaterial` in `dynamic3d/SpatialMaterial.swift`; this type only
+/// orchestrates lookups across `spatialObjects`.
+enum MaterialSceneRefresh {
+    /// After `SpatialUnlitMaterial.updateProperties`, `ModelComponent` may still hold a stale material copy —
+    /// refresh every component and entity that references `materialId`.
+    static func refreshComponentsUsingMaterial(
+        _ materialId: String,
+        spatialObjects: [String: any SpatialObjectProtocol]
+    ) {
+        for (_, obj) in spatialObjects {
+            if let comp = obj as? SpatialModelComponent, comp.usesMaterial(materialId) {
+                comp.refreshMaterials()
+            }
+        }
+        for (_, obj) in spatialObjects {
+            if let entity = obj as? SpatialModelEntity, entity.usesMaterial(materialId) {
+                entity.refreshMaterials()
+            }
+        }
+    }
+
+    /// After `SpatialTextureResource` reloads from a new URL, push `texture.resource` into every bound unlit material and return their ids for `refreshComponentsUsingMaterial`.
+    static func pushReloadedTextureToBoundUnlitMaterials(
+        texture: SpatialTextureResource,
+        textureSpatialId: String,
+        spatialObjects: [String: any SpatialObjectProtocol]
+    ) -> Set<String> {
+        var refreshedMaterialIds = Set<String>()
+        for (_, obj) in spatialObjects {
+            guard let material = obj as? SpatialUnlitMaterial,
+                  material.textureSpatialId == textureSpatialId
+            else { continue }
+            material.updateProperties(color: nil, texture: .some(texture.resource), transparent: nil, opacity: nil)
+            refreshedMaterialIds.insert(material.spatialId)
+        }
+        return refreshedMaterialIds
+    }
+}

package/web-spatial/model/SpatialScene.swift

@@ -307,6 +307,8 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         spatialWebViewModel.addJSBListener(CreateSpatialEntity.self, onCreateEntity)
         spatialWebViewModel.addJSBListener(CreateGeometryProperties.self, onCreateGeometry)
         spatialWebViewModel.addJSBListener(CreateUnlitMaterial.self, onCreateUnlitMaterial)
+        spatialWebViewModel.addJSBListener(CreateTexture.self, onCreateTexture)
+        spatialWebViewModel.addJSBListener(UpdateTextureProperties.self, onUpdateTextureProperties)
         spatialWebViewModel.addJSBListener(CreateModelComponent.self, onCreateModelComponent)
         spatialWebViewModel.addJSBListener(AddComponentToEntity.self, onAddComponentToEntity)
         spatialWebViewModel.addJSBListener(AddEntityToDynamic3D.self, onAddEntityToDynamic3D)
@@ -548,6 +550,9 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         if let sources = command.sources {
             spatialObject.sources = sources
         }
+        if let loading = command.loading {
+            spatialObject.loading = loading
+        }
 
         resolve(.success(AddSpatializedElementReply(id: spatialObject.id)))
     }
@@ -629,6 +634,18 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
             spatializedElement.playbackRate = playbackRate
         }
 
+        if let currentTime = command.currentTime {
+            spatializedElement.pendingSeekTime = currentTime
+        }
+
+        if let posterURL = command.posterURL {
+            spatializedElement.posterURL = posterURL.isEmpty ? nil : posterURL
+        }
+
+        if let loading = command.loading {
+            spatializedElement.loading = loading
+        }
+
         resolve(.success(baseReplyData))
     }
 
@@ -964,8 +981,28 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         //      @fukang: add Component here
     }
 
+    private func onCreateTexture(command: CreateTexture, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        let texture = SpatialTextureResource(command.url)
+        addSpatialObject(texture)
+        Task {
+            do {
+                try await texture.load()
+                resolve(.success(AddSpatializedElementReply(id: texture.id)))
+            } catch {
+                texture.destroy()
+                resolve(.failure(JsbError(code: .CommandError, message: "Failed to load texture from \(command.url): \(error.localizedDescription)")))
+            }
+        }
+    }
+
     private func onCreateUnlitMaterial(command: CreateUnlitMaterial, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
-        let material = Dynamic3DManager.createUnlitMaterial(command, nil)
+        var tex: TextureResource? = nil
+        if let textureId = command.textureId,
+           let texObj = spatialObjects[textureId] as? SpatialTextureResource
+        {
+            tex = texObj.resource
+        }
+        let material = Dynamic3DManager.createUnlitMaterial(command, tex)
         addSpatialObject(material)
         resolve(.success(AddSpatializedElementReply(id: material.id)))
     }
@@ -1225,20 +1262,54 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         resolve(.success(baseReplyData))
     }
 
+    private func onUpdateTextureProperties(command: UpdateTextureProperties, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        guard let texture = spatialObjects[command.id] as? SpatialTextureResource else {
+            resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "Texture \(command.id) not found")))
+            return
+        }
+        guard let newURL = command.url else {
+            resolve(.success(baseReplyData))
+            return
+        }
+        Task {
+            do {
+                try await texture.updateURL(newURL)
+                let refreshedMaterialIds = MaterialSceneRefresh.pushReloadedTextureToBoundUnlitMaterials(
+                    texture: texture,
+                    textureSpatialId: command.id,
+                    spatialObjects: spatialObjects
+                )
+                for mid in refreshedMaterialIds {
+                    MaterialSceneRefresh.refreshComponentsUsingMaterial(mid, spatialObjects: spatialObjects)
+                }
+                resolve(.success(baseReplyData))
+            } catch {
+                resolve(.failure(JsbError(code: .CommandError, message: error.localizedDescription)))
+            }
+        }
+    }
+
     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()
+        var texture: TextureResource?? = nil
+        if let textureId = command.textureId {
+            if textureId.isEmpty {
+                texture = .some(nil)
+            } else if let texObj = spatialObjects[textureId] as? SpatialTextureResource {
+                texture = .some(texObj.resource)
+            } else {
+                resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "Texture \(textureId) not found")))
+                return
             }
         }
+        material.updateProperties(color: command.color, texture: texture, transparent: command.transparent, opacity: command.opacity)
+        if let tid = command.textureId {
+            material.textureSpatialId = tid.isEmpty ? nil : tid
+        }
+        MaterialSceneRefresh.refreshComponentsUsingMaterial(command.id, spatialObjects: spatialObjects)
         resolve(.success(baseReplyData))
     }
 

package/web-spatial/model/SpatializedStatic3DElement.swift

@@ -15,7 +15,15 @@ class SpatializedStatic3DElement: SpatializedElement {
     var loop: Bool = false
     var animationPaused: Bool = true
     var playbackRate: Double = 1.0
+    /// Requested seek position in seconds. Setting it triggers a seek in
+    /// `SpatializedStatic3DView`, which clears it back to `nil`.
+    var pendingSeekTime: Double?
+    var posterURL: String?
+    /// `"eager"` (default) fetches the model immediately; `"lazy"` defers
+    /// fetching until the web layer flips it back to `"eager"`.
+    var loading: String = "eager"
     var allSources: [ModelSource] {
+        guard loading == "eager" else { return [] }
         return if let modelURL {
             [ModelSource(src: modelURL, type: nil)] + sources
         } else { sources }

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

@@ -22,37 +22,53 @@ class SpatialMaterial: SpatialObject {
 
 @Observable
 class SpatialUnlitMaterial: SpatialMaterial {
+    /// Single RealityKit unlit instance we mutate in place; avoids allocating a new `UnlitMaterial()` on every property update.
+    private var _mat: UnlitMaterial
     private(set) var currentColor: UIColor
     private(set) var currentTexture: TextureResource?
     private(set) var currentTransparent: Bool
     private(set) var currentOpacity: Float
+    /// Spatial id of the bound `SpatialTextureResource`, when this material displays a texture. Used to push `TextureResource` updates after `UpdateTextureProperties`.
+    var textureSpatialId: String?
 
-    init(_ color: String, _ texture: TextureResource? = nil, _ transparent: Bool = true, _ opacity: Float = 1) {
+    init(_ color: String, _ texture: TextureResource? = nil, _ transparent: Bool = true, _ opacity: Float = 1, textureSpatialId: String? = nil) {
         currentColor = UIColor(Color(hex: color))
         currentTexture = texture
         currentTransparent = transparent
         currentOpacity = opacity
+        self.textureSpatialId = textureSpatialId
+        _mat = UnlitMaterial()
         super.init(.UnlitMaterial)
-        var mat = UnlitMaterial()
-        mat.color = .init(tint: currentColor, texture: texture != nil ? .init(texture!) : nil)
-        mat.blending = transparent ? .transparent(opacity: .init(scale: opacity)) : .opaque
-        _resource = mat
+        applyProperties()
     }
 
-    func updateProperties(color: String?, transparent: Bool?, opacity: Float?) {
+    /// Pushes `currentColor` / `currentTexture` / blending into `_mat` and exposes it as `resource`.
+    /// ModelComponent still holds its own copy, so callers must `refreshMaterials()` on affected components after this.
+    private func applyProperties() {
+        _mat.color = .init(
+            tint: currentColor,
+            texture: currentTexture.map { .init($0) }
+        )
+        _mat.blending = currentTransparent
+            ? .transparent(opacity: .init(scale: currentOpacity))
+            : .opaque
+        _resource = _mat
+    }
+
+    func updateProperties(color: String?, texture: TextureResource?? = nil, transparent: Bool?, opacity: Float?) {
         if let color = color {
             currentColor = UIColor(Color(hex: color))
         }
+        if let tex = texture {
+            currentTexture = tex
+        }
         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
+        applyProperties()
     }
 }
 

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

@@ -9,9 +9,11 @@ class SpatialModelEntity: SpatialEntity {
 
     required init(_ modelResource: SpatialModelResource, _ _name: String = "") {
         super.init(_name)
-        modelEntity = modelResource.resource
-        addChild(modelEntity!)
-        generateCollisionShapes(recursive: true)
+        modelEntity = modelResource.resource?.clone(recursive: true)
+        if let modelEntity = modelEntity {
+            addChild(modelEntity)
+            generateCollisionShapes(recursive: true)
+        }
     }
 
     required init() {

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

@@ -3,15 +3,40 @@ import SwiftUI
 
 @Observable
 class SpatialTextureResource: SpatialObject {
+    private(set) var url: String
     var _resource: TextureResource?
     var resource: TextureResource? {
         _resource
     }
 
     override init(_ url: String) {
+        self.url = url
         super.init()
     }
 
+    func load() async throws {
+        let localURL = try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<URL, Error>) in
+            Dynamic3DManager.loadResourceToLocal(url) { result in
+                continuation.resume(with: result)
+            }
+        }
+        _resource = try await Task { @MainActor in
+            try await TextureResource(contentsOf: localURL)
+        }.value
+    }
+
+    func updateURL(_ newURL: String) async throws {
+        url = newURL
+        let localURL = try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<URL, Error>) in
+            Dynamic3DManager.loadResourceToLocal(url) { result in
+                continuation.resume(with: result)
+            }
+        }
+        _resource = try await Task { @MainActor in
+            try await TextureResource(contentsOf: localURL)
+        }.value
+    }
+
     override func onDestroy() {
         _resource = nil
     }

package/web-spatial/view/SpatializedStatic3DView.swift

@@ -5,14 +5,17 @@ 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
+    @State private var loadState: LoadState = .idle
 
     private var spatializedStatic3DElement: SpatializedStatic3DElement {
         return spatializedElement as! SpatializedStatic3DElement
     }
 
+    private var asset: Model3DAsset? {
+        if case let .loaded(asset, _) = loadState { return asset }
+        return nil
+    }
+
     func onLoadSuccess(src: String) {
         spatialScene.sendWebMsg(spatializedElement.id, ModelLoadSuccess(src: src))
     }
@@ -34,9 +37,10 @@ struct SpatializedStatic3DView: View {
         let enableGesture = spatializedElement.enableGesture
         if !spatializedStatic3DElement.allSources.isEmpty {
             Group {
-                if isLoading {
-                    ProgressView()
-                } else if let asset, let source {
+                switch loadState {
+                case .idle, .loading:
+                    posterView { ProgressView() }
+                case let .loaded(asset, _):
                     Model3D(asset: asset) { resolvedModel3D in
                         resolvedModel3D
                             .resizable(true)
@@ -45,15 +49,10 @@ struct SpatializedStatic3DView: View {
                                 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()
-                    }
+                case .failed:
+                    posterView {}
                 }
             }
             .scaleEffect(
@@ -82,12 +81,35 @@ struct SpatializedStatic3DView: View {
             }
             .onChange(of: spatializedStatic3DElement.animationPaused) { onPlayback(isPaused: $1) }
             .onChange(of: spatializedStatic3DElement.playbackRate) { asset?.animationPlaybackController?.speed = Float($1) }
+            .onChange(of: spatializedStatic3DElement.pendingSeekTime) { _, time in onSeek(time: time) }
             .task(id: spatializedStatic3DElement.allSources) { await loadSources() }
         } else {
             EmptyView()
         }
     }
 
+    /// Renders the poster image while the 3D model is loading or after all
+    /// sources fail. When no poster URL is provided, or the poster itself is
+    /// still loading/failed, the supplied `fallback` view is shown instead.
+    @ViewBuilder
+    private func posterView<Fallback: View>(
+        @ViewBuilder fallback: @escaping () -> Fallback
+    ) -> some View {
+        if let posterURL = spatializedStatic3DElement.posterURL,
+           let url = localOrRemoteURL(url: posterURL)
+        {
+            AsyncImage(url: url) { phase in
+                if case let .success(image) = phase {
+                    image.resizable().aspectRatio(contentMode: .fit)
+                } else {
+                    fallback()
+                }
+            }
+        } else {
+            fallback()
+        }
+    }
+
     /// Plays or pauses the model animation and sends an animation state to the web code
     private func onPlayback(isPaused: Bool) {
         guard let asset else {
@@ -101,12 +123,40 @@ struct SpatializedStatic3DView: View {
         }
         let controller = asset.animationPlaybackController
         controller?.speed = Float(spatializedStatic3DElement.playbackRate)
+        if let time = spatializedStatic3DElement.pendingSeekTime, let controller {
+            controller.time = time
+            spatializedStatic3DElement.pendingSeekTime = nil
+        }
         isPaused ? controller?.pause() : controller?.resume()
+        sendAnimationStateChange(isPaused: isPaused)
+    }
+
+    /// Seeks the underlying animation controller when a non-nil `time` is
+    /// requested, then clears `pendingSeekTime` so subsequent identical
+    /// requests still trigger a fresh seek.
+    private func onSeek(time: Double?) {
+        guard let controller = asset?.animationPlaybackController, let time else { return }
+        controller.time = time
+        spatializedStatic3DElement.pendingSeekTime = nil
+        sendAnimationStateChange(isPaused: spatializedStatic3DElement.animationPaused)
+    }
+
+    /// Emits the current animation state to the web layer, sampling the
+    /// controller's position and the wall clock together so the web side can
+    /// extrapolate between samples.
+    private func sendAnimationStateChange(isPaused: Bool) {
+        let controller = asset?.animationPlaybackController
         let duration = controller?.duration ?? 0
+        let currentTime = controller?.time ?? 0
         spatialScene.sendWebMsg(
             spatializedElement.id,
             AnimationStateChangeEvent(
-                detail: AnimationStateChangeDetail(paused: isPaused, duration: duration)
+                detail: AnimationStateChangeDetail(
+                    paused: isPaused,
+                    duration: duration,
+                    currentTime: currentTime,
+                    timestamp: Date().timeIntervalSince1970 * 1000
+                )
             )
         )
     }
@@ -127,18 +177,23 @@ struct SpatializedStatic3DView: View {
     }
 
     private func loadSources() async {
-        isLoading = true
+        loadState = .loading
         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) }
+        guard !Task.isCancelled else { return }
+        if let result {
+            loadState = .loaded(result.asset, result.url.absoluteString)
+            onLoadSuccess(src: 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) }
+            }
+        } else {
+            loadState = .failed
+            onLoadFailure()
         }
-        isLoading = false
     }
 
     /// Attempts to load from each source in order, returning the first success.
@@ -158,3 +213,10 @@ struct SpatializedStatic3DView: View {
 private func localOrRemoteURL(url: String) -> URL? {
     URL(string: url.hasPrefix("file://") ? pwaManager.getLocalResourceURL(url: url) : url)
 }
+
+private enum LoadState {
+    case idle
+    case loading
+    case loaded(Model3DAsset, String)
+    case failed
+}

package/web-spatial.xcodeproj/project.pbxproj

@@ -14,7 +14,6 @@
 		2B06AEE62E4C1AE8000327E9 /* JSBCommand.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2B06AEC02E4C1AE8000327E9 /* JSBCommand.swift */; };
 		2B06AEE92E4C1AE8000327E9 /* EventEmitter.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2B06AEBF2E4C1AE8000327E9 /* EventEmitter.swift */; };
 		2B1008A22F0B000800000002 /* NavigationCleanupTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2B1008A12F0B000800000001 /* NavigationCleanupTests.swift */; };
-		2B2F1D692BEBFAAA006897EE /* RealityKitContent in Frameworks */ = {isa = PBXBuildFile; productRef = 2B2F1D682BEBFAAA006897EE /* RealityKitContent */; };
 		2B2F1D712BEBFAAC006897EE /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 2B2F1D702BEBFAAC006897EE /* Assets.xcassets */; };
 		2B2F1D742BEBFAAC006897EE /* Preview Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 2B2F1D732BEBFAAC006897EE /* Preview Assets.xcassets */; };
 		2B89E38C2E699104004079AA /* WebMsgCommand.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2B89E38B2E699104004079AA /* WebMsgCommand.swift */; };
@@ -72,6 +71,7 @@
 				dynamic3d/SpatialModelResource.swift,
 				dynamic3d/SpatialRootEntity.swift,
 				dynamic3d/SpatialTextureResource.swift,
+				MaterialSceneRefresh.swift,
 				SpatialApp.swift,
 				Spatialized2DElement.swift,
 				SpatializedDynamic3DElement.swift,
@@ -142,7 +142,6 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
-				2B2F1D692BEBFAAA006897EE /* RealityKitContent in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -244,7 +243,6 @@
 			);
 			name = "web-spatial";
 			packageProductDependencies = (
-				2B2F1D682BEBFAAA006897EE /* RealityKitContent */,
 			);
 			productName = "web-spatial";
 			productReference = 2B2F1D632BEBFAAA006897EE /* WebSpatial.app */;
@@ -605,12 +603,6 @@
 		};
 /* End XCConfigurationList section */
 
-/* Begin XCSwiftPackageProductDependency section */
-		2B2F1D682BEBFAAA006897EE /* RealityKitContent */ = {
-			isa = XCSwiftPackageProductDependency;
-			productName = RealityKitContent;
-		};
-/* End XCSwiftPackageProductDependency section */
 	};
 	rootObject = 2B2F1D5B2BEBFAAA006897EE /* Project object */;
 }