@webspatial/platform-visionos 1.7.0 → 2.0.0

package/package.json

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

package/web-spatial/JSBCommand.swift

@@ -278,6 +278,7 @@ struct UpdateSpatializedStatic3DElementProperties: SpatializedElementProperties
     let currentTime: Double?
     let posterURL: String?
     let loading: String?
+    let stagemode: String?
 }
 
 struct UpdateSpatializedDynamic3DElementProperties: SpatializedElementProperties {

package/web-spatial/WebMsgCommand.swift

@@ -24,9 +24,8 @@ enum SpatialWebMsgType: String, Encodable {
     case spatialrotateend
     case spatialmagnify
     case spatialmagnifyend
-
     case animationstatechange
-
+    case entitytransformchange
     case objectdestroy
 }
 
@@ -129,6 +128,31 @@ struct AnimationStateChangeEvent: Encodable {
     let detail: AnimationStateChangeDetail
 }
 
+/// 16-element column-major representation of the new `entityTransform`,
+/// matching the wire format that JS already uses when sending the matrix to
+/// native via `UpdateSpatializedStatic3DElementProperties.modelTransform`.
+struct EntityTransformChangeDetail: Encodable {
+    let transform: [Double]
+}
+
+struct EntityTransformChangeEvent: Encodable {
+    let type: SpatialWebMsgType = .entitytransformchange
+    let detail: EntityTransformChangeDetail
+
+    /// Emits the transform to the web layer as a 16-element column-major matrix.
+    init(_ transform: AffineTransform3D) {
+        let m = transform.matrix
+        let c0 = m.columns.0, c1 = m.columns.1, c2 = m.columns.2, c3 = m.columns.3
+        let array: [Double] = [
+            c0.x, c0.y, c0.z, 0,
+            c1.x, c1.y, c1.z, 0,
+            c2.x, c2.y, c2.z, 0,
+            c3.x, c3.y, c3.z, 1,
+        ]
+        detail = EntityTransformChangeDetail(transform: array)
+    }
+}
+
 struct SpatialObjectDestroiedEvent: Encodable {
     let type: SpatialWebMsgType = .objectdestroy
 }

package/web-spatial/WebSpatialApp.swift

@@ -40,13 +40,31 @@ struct WebSpatialApp: App {
         )
     }
 
+    func getSceneOrCreate(_ sceneID: String?, _ style: SpatialScene.WindowStyle) -> SpatialScene {
+        if let sceneID, let spatialScene = SpatialApp.Instance.getScene(sceneID) {
+            return spatialScene
+        }
+
+        logger.debug("Missing scene for WindowGroup data. Recreating scene.")
+        return SpatialApp.Instance.createScene(
+            startURL,
+            style,
+            .visible,
+            app.getSceneOptions()
+        )
+    }
+
+    func getSceneOrCreate(_ sceneID: String, _ style: SpatialScene.WindowStyle) -> SpatialScene {
+        return getSceneOrCreate(Optional(sceneID), style)
+    }
+
     var body: some Scene {
         WindowGroup(
             id: SpatialScene.WindowStyle.window.rawValue,
             for: String.self
         ) { $windowData in
-            let spatialScene = SpatialApp.Instance.getScene(windowData)
-            SpatialSceneView(spatialScene: spatialScene!)
+            let spatialScene = getSceneOrCreate(windowData, .window)
+            SpatialSceneView(spatialScene: spatialScene)
         }
         defaultValue: {
             let scene = SpatialApp.Instance.createScene(
@@ -66,20 +84,20 @@ struct WebSpatialApp: App {
         )
 
         WindowGroup(id: SpatialScene.WindowStyle.volume.rawValue, for: String.self) { $windowData in
-            let spatialScene = SpatialApp.Instance.getScene(windowData)
-            SpatialSceneView(spatialScene: spatialScene!)
+            let spatialScene = getSceneOrCreate(windowData, .volume)
+            SpatialSceneView(spatialScene: spatialScene)
                 .frame(
                     minWidth: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.minWidth
+                        spatialScene.sceneConfig?.resizeRange?.minWidth
                     ),
                     maxWidth: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.maxWidth
+                        spatialScene.sceneConfig?.resizeRange?.maxWidth
                     ),
                     minHeight: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.minHeight
+                        spatialScene.sceneConfig?.resizeRange?.minHeight
                     ),
                     maxHeight: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.maxHeight
+                        spatialScene.sceneConfig?.resizeRange?.maxHeight
                     )
                 )
         }

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/#/"
+    ///    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/SpatialScene.swift

@@ -1,5 +1,6 @@
 import Combine
 import Foundation
+import Observation
 import RealityKit
 import simd
 import SwiftUI
@@ -40,6 +41,15 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
     var parent: (any ScrollAbleSpatialElementContainer)?
 
     var attachmentManager = AttachmentManager()
+    /// NOTE: `@Observable` + `lazy` 在新版本 Swift 宏展开下会触发编译器报错（init accessor 访问 backing storage）。
+    /// 这里不需要让动画管理器参与 Observation，避免生成 `@ObservationTracked` 相关访问器即可。
+    @ObservationIgnored
+    lazy var animationManager: EntityAnimationManager = .init(scene: self)
+
+    @ObservationIgnored
+    lazy var elementAnimationManager: SpatializedElementAnimationManager = .init(sendWebMsg: { [weak self] id, msg in
+        self?.sendWebMsg(id, msg)
+    })
 
     /// Enum
     enum WindowStyle: String, Codable, CaseIterable {
@@ -331,6 +341,10 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
 
         spatialWebViewModel.addJSBListener(UpdateAttachmentEntityCommand.self, onUpdateAttachmentEntity)
 
+        spatialWebViewModel.addJSBListener(AnimateTransformCommand.self, onAnimateTransform)
+
+        spatialWebViewModel.addJSBListener(CreateSpatializedElementAnimationCommand.self, onCreateSpatializedElementAnimation)
+        spatialWebViewModel.addJSBListener(ControlSpatializedElementAnimationCommand.self, onControlSpatializedElementAnimation)
         spatialWebViewModel.addOpenWindowListener(protocal: "webspatial", onOpenWindowHandler)
 
         spatialWebViewModel
@@ -361,6 +375,7 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
     }
 
     var didFailLoad = false
+    private var currentPageGeneration = 0
 
     private func setupWebViewStateListener() {
         spatialWebViewModel.addStateListener(.didStartLoad) {
@@ -378,6 +393,7 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         }
 
         spatialWebViewModel.addStateListener(.didReceive) {
+            self.injectPageEpoch()
             if let meterToPtUnscaled = self.meterToPtUnscaled,
                let meterToPtScaled = self.meterToPtScaled
             {
@@ -394,27 +410,7 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
 
         spatialWebViewModel.addStateListener(.didFinishLoad) {
             if self.state == .pending {
-                self.checkHookExist()
-            }
-        }
-    }
-
-    private func checkHookExist(_ completion: ((Bool) -> Void)? = nil) {
-        let js = """
-        (function() {
-            return typeof window.xrCurrentSceneDefaults !== 'undefined';
-        })();
-        """
-
-        spatialWebViewModel.evaluateJS(js) { result in
-            let exists = result as? Bool ?? false
-
-            if let completion = completion {
-                completion(exists)
-            } else {
-                if !exists {
-                    self.moveToState(.willVisible, defaultSceneConfig)
-                }
+                self.moveToState(.willVisible, self.sceneConfig ?? defaultSceneConfig)
             }
         }
     }
@@ -425,11 +421,17 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
             return handleWindowOpenCustom(url)
         } else if host == "createAttachment" {
             return handleCreateAttachment(url)
-        } else {
+        } else if host == "createSpatialized2DElement" {
+            guard shouldAcceptSpatialRequest(url, command: host) else {
+                return nil
+            }
             let spatialized2DElement: Spatialized2DElement = createSpatializedElement(
                 .Spatialized2DElement
             )
             return WebViewElementInfo(id: spatialized2DElement.id, element: spatialized2DElement.getWebViewModel())
+        } else {
+            logger.warning("Unknown webspatial open-window command: \(host)")
+            return nil
         }
     }
 
@@ -437,6 +439,9 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
     private var pendingAttachmentWebViewModels = [String: SpatialWebViewModel]()
 
     private func handleCreateAttachment(_ url: URL) -> WebViewElementInfo? {
+        guard shouldAcceptSpatialRequest(url, command: "createAttachment") else {
+            return nil
+        }
         // Just create a bare webview — metadata arrives via InitializeAttachment JSB
         let id = UUID().uuidString
         let webViewModel = SpatialWebViewModel(url: nil)
@@ -481,6 +486,12 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
     }
 
     private func onPageStartLoad() {
+        currentPageGeneration += 1
+        injectPageEpoch()
+        logger.debug("SpatialScene page generation advanced to \(currentPageGeneration)")
+        // Clean up all animation sessions
+        animationManager.removeAll()
+        elementAnimationManager.removeAll()
         // destroy all SpatialObject asset
         let spatialObjectArray = spatialObjects.map { $0.value }
         for spatialObject in spatialObjectArray {
@@ -490,6 +501,50 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         backgroundMaterial = .None
     }
 
+    private func injectPageEpoch() {
+        // Mirror the native page generation into JS so frontend-created
+        // webspatial:// requests can carry page ownership metadata.
+        let js = """
+        window.__webspatialsdk__ = window.__webspatialsdk__ || {};
+        window.__webspatialsdk__.pageEpoch = "\(currentPageGeneration)";
+        """
+        spatialWebViewModel.getController().callJS(js)
+    }
+
+    private struct SpatialRequestMetadata {
+        let rid: String?
+        let pageEpoch: String?
+    }
+
+    private func parseSpatialRequestMetadata(_ url: URL) -> SpatialRequestMetadata {
+        let items = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems ?? []
+        let rid = items.first { $0.name == "rid" }?.value
+        let pageEpoch = items.first { $0.name == "wsepoch" }?.value
+        return SpatialRequestMetadata(rid: rid, pageEpoch: pageEpoch)
+    }
+
+    private func shouldAcceptSpatialRequest(_ url: URL, command: String) -> Bool {
+        let metadata = parseSpatialRequestMetadata(url)
+
+        guard let pageEpoch = metadata.pageEpoch, !pageEpoch.isEmpty else {
+            // Compatibility mode for older frontend bundles that do not emit
+            // request epoch yet.
+            logger.warning("SpatialScene accepts \(command) without wsepoch in compatibility mode, rid=\(metadata.rid ?? "nil")")
+            return true
+        }
+
+        let currentEpoch = String(currentPageGeneration)
+        if pageEpoch != currentEpoch {
+            // Drop requests that were initiated by an older page generation so
+            // they cannot recreate stale 2D content after refresh.
+            logger.warning("SpatialScene drops stale \(command), rid=\(metadata.rid ?? "nil"), requestEpoch=\(pageEpoch), currentEpoch=\(currentEpoch)")
+            return false
+        }
+
+        logger.debug("SpatialScene accepts \(command), rid=\(metadata.rid ?? "nil"), epoch=\(pageEpoch)")
+        return true
+    }
+
     /// Some SPA navigations (history back/forward) do not trigger a full WKNavigation
     /// lifecycle. SpatialNavView calls this before navigation actions to ensure
     /// previously-created spatial objects are cleaned up.
@@ -551,7 +606,7 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
             spatialObject.sources = sources
         }
         if let loading = command.loading {
-            spatialObject.loading = loading
+            spatialObject.loading = Loading(stringValue: loading)
         }
 
         resolve(.success(AddSpatializedElementReply(id: spatialObject.id)))
@@ -615,7 +670,9 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
             let column3 = simd_double4(array[12], array[13], array[14], array[15])
             let simd_double4x4 = simd_double4x4(columns: (column0, column1, column2, column3))
             let affineTransform3D = AffineTransform3D(truncating: simd_double4x4)
-            spatializedElement.modelTransform = affineTransform3D
+            if !spatializedElement.animatingMask.locksTransform {
+                spatializedElement.entityTransform = affineTransform3D
+            }
         }
 
         if let autoplay = command.autoplay {
@@ -643,7 +700,11 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         }
 
         if let loading = command.loading {
-            spatializedElement.loading = loading
+            spatializedElement.loading = Loading(stringValue: loading)
+        }
+
+        if let stagemode = command.stagemode {
+            spatializedElement.stagemode = StageMode(stringValue: stagemode)
         }
 
         resolve(.success(baseReplyData))
@@ -755,7 +816,9 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         }
 
         if let opacity = command.opacity {
-            spatializedElement.opacity = opacity
+            if !spatializedElement.animatingMask.locksOpacity {
+                spatializedElement.opacity = opacity
+            }
         }
 
         if let scrollWithParent = command.scrollWithParent {
@@ -821,6 +884,11 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
             return resolve(.failure(JsbError(code: .InvalidMatrix, message: "invalid UpdateSpatializedElementTransform matrix should have length 16!")))
         }
 
+        if spatializedElement.animatingMask.locksTransform {
+            resolve(.success(baseReplyData))
+            return
+        }
+
         let column0 = simd_double4(array[0], array[1], array[2], array[3])
         let column1 = simd_double4(array[4], array[5], array[6], array[7])
         let column2 = simd_double4(array[8], array[9], array[10], array[11])
@@ -859,17 +927,8 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         children.removeValue(forKey: spatializedElement.id)
     }
 
-    func getChildrenOfType(_ type: SpatializedElementType) -> [String: SpatializedElement] {
-        return children.filter {
-            switch type {
-            case .Spatialized2DElement:
-                return $0.value is Spatialized2DElement
-            case .SpatializedStatic3DElement:
-                return $0.value is SpatializedStatic3DElement
-            case .SpatializedDynamic3DElement:
-                return $0.value is SpatializedDynamic3DElement
-            }
-        }
+    func getChildren<T: SpatializedElement>(ofType type: T.Type) -> [T] {
+        return children.values.compactMap { $0 as? T }
     }
 
     func getChildren() -> [String: SpatializedElement] {
@@ -1289,6 +1348,76 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         }
     }
 
+    private func onAnimateTransform(command: AnimateTransformCommand, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        switch command.type {
+        case "play":
+            guard let entityId = command.entityId else {
+                resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "AnimateTransform play: entityId is required")))
+                return
+            }
+            guard let entity: SpatialEntity = findSpatialObject(entityId) else {
+                resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "AnimateTransform play: entity \(entityId) not found")))
+                return
+            }
+            animationManager.handlePlay(command: command, entity: entity, resolve: resolve)
+
+        case "pause":
+            animationManager.handlePause(command: command, resolve: resolve)
+
+        case "resume":
+            guard let session = animationManager.getSession(command.animationId),
+                  let entity: SpatialEntity = findSpatialObject(session.entityId)
+            else {
+                resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "AnimateTransform resume: session or entity not found")))
+                return
+            }
+            animationManager.handleResume(command: command, entity: entity, resolve: resolve)
+
+        case "cancel":
+            guard let session = animationManager.getSession(command.animationId),
+                  let entity: SpatialEntity = findSpatialObject(session.entityId)
+            else {
+                // Session may have already been cleaned up - acknowledge silently.
+                resolve(.success(nil))
+                return
+            }
+            animationManager.handleCancel(command: command, entity: entity, resolve: resolve)
+
+        default:
+            resolve(.failure(JsbError(code: .TypeError, message: "AnimateTransform: unknown command type '\(command.type)'")))
+        }
+    }
+
+    private func onCreateSpatializedElementAnimation(command: CreateSpatializedElementAnimationCommand, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        guard let element: SpatializedElement = findSpatialObject(command.elementId) else {
+            resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "CreateSpatializedElementAnimation play: element \(command.elementId) not found")))
+            return
+        }
+
+        do {
+            let animation = try elementAnimationManager.createAnimation(command: command, target: element)
+            addSpatialObject(animation)
+            resolve(.success(AddSpatializedElementReply(id: animation.id)))
+        } catch let SpatializedElementAnimationManagerError.invalidTarget(reason) {
+            resolve(.failure(JsbError(code: .CommandError, message: reason)))
+        } catch {
+            resolve(.failure(JsbError(code: .CommandError, message: error.localizedDescription)))
+        }
+    }
+
+    private func onControlSpatializedElementAnimation(command: ControlSpatializedElementAnimationCommand, resolve: @escaping JSBManager.ResolveHandler<Encodable>) {
+        do {
+            try elementAnimationManager.controlAnimation(command)
+            resolve(.success(nil))
+        } catch let SpatializedElementAnimationManagerError.animationNotFound(animationId) {
+            resolve(.failure(JsbError(code: .InvalidSpatialObject, message: "Animation \(animationId) not found")))
+        } catch let SpatializedElementAnimationManagerError.invalidTarget(reason) {
+            resolve(.failure(JsbError(code: .CommandError, message: reason)))
+        } 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")))
@@ -1359,6 +1488,9 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
                 event: SpatialObject.Events.BeforeDestroyed.rawValue,
                 listener: onSptatialObjectDestroyed
             )
+        if let element = spatialObject as? SpatializedElement {
+            elementAnimationManager.destroyAnimationsForElement(element.spatialId)
+        }
         spatialObjects.removeValue(forKey: spatialObject.spatialId)
 
         // notify web side, spatialObject is destroyed
@@ -1393,6 +1525,8 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
      */
 
     override func onDestroy() {
+        animationManager.removeAll()
+        elementAnimationManager.removeAll()
         let spatialObjectArray = spatialObjects.map { $0.value }
         for spatialObject in spatialObjectArray {
             spatialObject.destroy()
@@ -1402,7 +1536,7 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
     }
 
     enum CodingKeys: String, CodingKey {
-        case children, url, backgroundMaterial, cornerRadius, scrollOffset, webviewIsOpaque, spatialObjectCount, spatialObjectRefCount, spatialObjectList
+        case children, url, backgroundMaterial, cornerRadius, scrollOffset, currentPageGeneration, childrenIds, sceneSpatialObjectIds, webviewIsOpaque, spatialObjectCount, spatialObjectRefCount, spatialObjectList
     }
 
     override func encode(to encoder: Encoder) throws {
@@ -1413,8 +1547,13 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
         try container.encode(cornerRadius, forKey: .cornerRadius)
         try container.encode(scrollOffset, forKey: .scrollOffset)
         try container.encode(children, forKey: .children)
+        try container.encode(currentPageGeneration, forKey: .currentPageGeneration)
 
         // for debug only
+        let childrenIds = children.map { $0.key }
+        try container.encode(childrenIds, forKey: .childrenIds)
+        let sceneSpatialObjectIds = spatialObjects.map { $0.key }
+        try container.encode(sceneSpatialObjectIds, forKey: .sceneSpatialObjectIds)
         try container.encode(spatialWebViewModel.getController().webview?.isOpaque, forKey: .webviewIsOpaque)
         try container.encode(SpatialObject.objects.count, forKey: .spatialObjectCount)
 
@@ -1425,4 +1564,4 @@ class SpatialScene: SpatialObject, ScrollAbleSpatialElementContainer, WebMsgSend
 
         try container.encode(SpatialObjectWeakRefManager.weakRefObjects.count, forKey: .spatialObjectRefCount)
     }
-}
+}

package/web-spatial/model/Spatialized2DElement.swift

@@ -74,17 +74,8 @@ class Spatialized2DElement: SpatializedElement, ScrollAbleSpatialElementContaine
         return children
     }
 
-    func getChildrenOfType(_ type: SpatializedElementType) -> [String: SpatializedElement] {
-        return children.filter {
-            switch type {
-            case .Spatialized2DElement:
-                return $0.value is Spatialized2DElement
-            case .SpatializedStatic3DElement:
-                return $0.value is SpatializedStatic3DElement
-            case .SpatializedDynamic3DElement:
-                return $0.value is SpatializedDynamic3DElement
-            }
-        }
+    func getChildren<T: SpatializedElement>(ofType type: T.Type) -> [T] {
+        return children.values.compactMap { $0 as? T }
     }
 
     func loadHtml(_ html: String) {

package/web-spatial/model/SpatializedElement.swift

@@ -5,6 +5,43 @@ import SwiftUI
 /// zIndex() have some bug, so use zOrderBias to simulate zIndex effect
 let zOrderBias = 0.001
 
+struct SpatializedElementAnimatingMask {
+    var transformAnimationId: String?
+    var opacityAnimationId: String?
+}
+
+extension SpatializedElementAnimatingMask {
+    mutating func acquire(transform animationId: String?) {
+        transformAnimationId = animationId
+    }
+
+    mutating func acquire(opacity animationId: String?) {
+        opacityAnimationId = animationId
+    }
+
+    mutating func release(animationId: String) {
+        if transformAnimationId == animationId {
+            transformAnimationId = nil
+        }
+        if opacityAnimationId == animationId {
+            opacityAnimationId = nil
+        }
+    }
+
+    mutating func clear() {
+        transformAnimationId = nil
+        opacityAnimationId = nil
+    }
+
+    var locksTransform: Bool {
+        transformAnimationId != nil
+    }
+
+    var locksOpacity: Bool {
+        opacityAnimationId != nil
+    }
+}
+
 enum SpatializedElementType: String, Codable {
     case Spatialized2DElement
     case SpatializedStatic3DElement
@@ -25,6 +62,7 @@ class SpatializedElement: SpatialObject {
     var visible = true
     var scrollWithParent = true
     var zIndex: Double = 0
+    var animatingMask = SpatializedElementAnimatingMask()
 
     var enableDragStartGesture: Bool = false
     var enableDragGesture: Bool = false

package/web-spatial/model/SpatializedStatic3DElement.swift

@@ -6,11 +6,29 @@ struct ModelSource: Codable, Equatable {
     let type: String?
 }
 
+enum Loading: String {
+    case eager
+    case lazy
+
+    init(stringValue value: String) {
+        self = Loading(rawValue: value) ?? .eager
+    }
+}
+
+enum StageMode: String {
+    case none
+    case orbit
+
+    init(stringValue value: String) {
+        self = StageMode(rawValue: value) ?? .none
+    }
+}
+
 @Observable
 class SpatializedStatic3DElement: SpatializedElement {
     var modelURL: String?
     var sources: [ModelSource] = []
-    var modelTransform: AffineTransform3D = .identity
+    var entityTransform: AffineTransform3D = .identity
     var autoplay: Bool = false
     var loop: Bool = false
     var animationPaused: Bool = true
@@ -19,14 +37,15 @@ class SpatializedStatic3DElement: SpatializedElement {
     /// `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 loading: Loading = .eager
+    var stagemode: StageMode = .none
     var allSources: [ModelSource] {
-        guard loading == "eager" else { return [] }
-        return if let modelURL {
-            [ModelSource(src: modelURL, type: nil)] + sources
-        } else { sources }
+        if let modelURL { [ModelSource(src: modelURL, type: nil)] + sources }
+        else { sources }
+    }
+
+    override var enableGesture: Bool {
+        stagemode == .orbit || super.enableGesture
     }
 
     enum CodingKeys: String, CodingKey {