@webspatial/platform-visionos 1.2.1 → 1.4.0

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@webspatial/platform-visionos",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Used to publish WebSpatial projects to Apple Vision Pro",
   "type": "commonjs",
+  "main": "package.json",
   "engines": {
     "node": ">=14.15.0"
   },

package/web-spatial/EventEmitter.swift

@@ -1,38 +1,38 @@
 class EventEmitter {
     private var listeners: [String: [(_ object: Any, _ data: Any) -> Void]] = [:]
 
-    public func on(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void) {
+    func on(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void) {
         if listeners[event] == nil {
             listeners[event] = []
         }
         listeners[event]?.append(listener)
     }
 
-    public func emit(event: String, data: Any) {
+    func emit(event: String, data: Any) {
         listeners[event]?.forEach { listener in
             listener(self, data)
         }
     }
 
-    public func off(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void) {
+    func off(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void) {
         listeners[event]?.removeAll(where: { $0 as AnyObject === listener as AnyObject })
     }
-    
-    public func reset(){
+
+    func reset() {
         listeners = [:]
     }
 }
 
-protocol EventEmitterProtocol{
-    var listeners: [String: [(_ object: Any, _ data: Any) -> Void]] {get set}
-    
+protocol EventEmitterProtocol {
+    var listeners: [String: [(_ object: Any, _ data: Any) -> Void]] { get set }
+
     mutating func on(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void)
     func emit(event: String, data: Any)
     mutating func off(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void)
     mutating func reset()
 }
 
-extension EventEmitterProtocol{
+extension EventEmitterProtocol {
     mutating func on(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void) {
         if listeners[event] == nil {
             listeners[event] = []
@@ -49,8 +49,8 @@ extension EventEmitterProtocol{
     mutating func off(event: String, listener: @escaping (_ object: Any, _ data: Any) -> Void) {
         listeners[event]?.removeAll(where: { $0 as AnyObject === listener as AnyObject })
     }
-    
-    mutating func reset(){
+
+    mutating func reset() {
         listeners = [:]
     }
 }

package/web-spatial/JSBCommand.swift

@@ -129,6 +129,13 @@ struct ConvertFromSceneToEntity: CommandDataProtocol {
     let position: Vec3
 }
 
+struct ConvertCoordinate: CommandDataProtocol {
+    static let commandType: String = "ConvertCoordinate"
+    let position: Vec3
+    let fromId: String
+    let toId: String
+}
+
 struct InspectCommand: CommandDataProtocol {
     static let commandType: String = "Inspect"
     var id: String?
@@ -166,6 +173,7 @@ protocol SpatializedElementProperties: SpatialObjectCommand {
     var enableMagnifyGesture: Bool? { get }
     var enableMagnifyEndGesture: Bool? { get }
     var enableTapGesture: Bool? { get }
+    var rotateConstrainedToAxis: Vec3? { get }
 }
 
 struct UpdateSpatialized2DElementProperties: SpatializedElementProperties {
@@ -193,12 +201,14 @@ struct UpdateSpatialized2DElementProperties: SpatializedElementProperties {
     var enableMagnifyEndGesture: Bool?
     var enableTapGesture: Bool?
 
+    let rotateConstrainedToAxis: Vec3?
+
     let scrollPageEnabled: Bool?
     let material: BackgroundMaterial?
     let cornerRadius: CornerRadius?
 
-    // this value is used by previous WebSpatial code, keep it here only for Compatibility consideration
-    // may delete it when we think it's not needed
+    /// this value is used by previous WebSpatial code, keep it here only for Compatibility consideration
+    /// may delete it when we think it's not needed
     let scrollEdgeInsetsMarginRight: Double?
 }
 
@@ -227,6 +237,8 @@ struct UpdateSpatializedStatic3DElementProperties: SpatializedElementProperties
     let enableMagnifyEndGesture: Bool?
     let enableTapGesture: Bool?
 
+    let rotateConstrainedToAxis: Vec3?
+
     let modelURL: String?
     let modelTransform: [Double]?
 }
@@ -255,6 +267,8 @@ struct UpdateSpatializedDynamic3DElementProperties: SpatializedElementProperties
     let enableMagnifyGesture: Bool?
     let enableMagnifyEndGesture: Bool?
     let enableTapGesture: Bool?
+
+    let rotateConstrainedToAxis: Vec3?
 }
 
 struct UpdateSpatializedElementTransform: SpatialObjectCommand {
@@ -269,7 +283,7 @@ struct AddSpatializedElementToSpatialized2DElement: SpatialObjectCommand {
     let spatializedElementId: String
 }
 
-// incomming JSB data
+/// incomming JSB data
 struct XSceneOptionsJSB: Codable {
     let defaultSize: Size?
     let type: SpatialScene.WindowStyle?
@@ -338,3 +352,24 @@ struct FocusSceneCommand: CommandDataProtocol {
 struct GetSpatialSceneStateCommand: CommandDataProtocol {
     static let commandType = "GetSpatialSceneState"
 }
+
+struct InitializeAttachmentCommand: CommandDataProtocol {
+    static let commandType = "InitializeAttachment"
+    let id: String
+    let parentEntityId: String
+    let position: [Float]?
+    let size: AttachmentSize?
+    let ownerViewId: String
+}
+
+struct UpdateAttachmentEntityCommand: CommandDataProtocol {
+    static let commandType = "UpdateAttachmentEntity"
+    let id: String
+    let position: [Float]?
+    let size: AttachmentSize?
+}
+
+struct AttachmentSize: Codable {
+    let width: Double
+    let height: Double
+}

package/web-spatial/WebMsgCommand.swift

@@ -14,8 +14,6 @@ enum WebSpatialGestureType: String, Encodable {
 }
 
 enum SpatialWebMsgType: String, Encodable {
-    case cubeInfo
-    case transform
     case modelloaded
     case modelloadfailed
     case spatialtap
@@ -30,24 +28,13 @@ enum SpatialWebMsgType: String, Encodable {
     case objectdestroy
 }
 
-// notify Spatialized3DElement Container Cube, used for ref.current.getBoundingClientCube()
-struct SpatiaizedContainerClientCube: Encodable {
-    let type: SpatialWebMsgType = .cubeInfo
-    let origin: Point3D
-    let size: Size3D
-}
-
-// notify Spatialized3DElement Container Transform to SpatialScene, used for ref.current.convertToSpatialScene()
-struct SpatiaizedContainerTransform: Encodable {
-    let type: SpatialWebMsgType = .transform
-    let detail: AffineTransform3D
-}
-
 struct WebSpatialTapGuestureEventDetail: Encodable {
     let location3D: Point3D
+    /// Global scene location (maps to clientX/clientY/clientZ on the web side).
+    let globalLocation3D: Point3D?
 }
 
-// notify SpatializedElement/SpatialEntity tapped
+/// notify SpatializedElement/SpatialEntity tapped
 struct WebSpatialTapGuestureEvent: Encodable {
     let type: SpatialWebMsgType = .spatialtap
     let detail: WebSpatialTapGuestureEventDetail
@@ -55,6 +42,8 @@ struct WebSpatialTapGuestureEvent: Encodable {
 
 struct WebSpatialDragStartGuestureEventDetail: Encodable {
     let startLocation3D: Point3D
+    /// Global scene location for the drag start point.
+    let globalLocation3D: Point3D?
 }
 
 struct WebSpatialDragStartGuestureEvent: Encodable {

package/web-spatial/WebSpatialApp.swift

@@ -22,26 +22,22 @@ struct WebSpatialApp: App {
     @State var app = SpatialApp.Instance
 
     func getDefaultSize() -> CGSize {
-        let ans = CGSize(
+        return CGSize(
             width: app
                 .getSceneOptions().defaultSize!.width,
             height: app
                 .getSceneOptions().defaultSize!.height
         )
-
-        return ans
     }
 
     func getDefaultSize3D() -> Size3D {
-        let ans = Size3D(
+        return Size3D(
             width: app
                 .getSceneOptions().defaultSize!.width,
             height: app
                 .getSceneOptions().defaultSize!.height,
             depth: app.getSceneOptions().defaultSize!.depth ?? 0
         )
-
-        return ans
     }
 
     var body: some Scene {
@@ -74,13 +70,17 @@ struct WebSpatialApp: App {
             SpatialSceneView(spatialScene: spatialScene!)
                 .frame(
                     minWidth: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.minWidth),
+                        app.getSceneOptions(windowData)?.resizeRange?.minWidth
+                    ),
                     maxWidth: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.maxWidth),
+                        app.getSceneOptions(windowData)?.resizeRange?.maxWidth
+                    ),
                     minHeight: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.minHeight),
+                        app.getSceneOptions(windowData)?.resizeRange?.minHeight
+                    ),
                     maxHeight: getCGFloat(
-                        app.getSceneOptions(windowData)?.resizeRange?.maxHeight)
+                        app.getSceneOptions(windowData)?.resizeRange?.maxHeight
+                    )
                 )
         }
         defaultValue: {

package/web-spatial/Window.swift

@@ -1,7 +1,7 @@
 import Foundation
 import SwiftUI
 
-// Access window (https://stackoverflow.com/questions/60359808/how-to-access-own-window-within-swiftui-view/60359809#60359809)
+/// Access window (https://stackoverflow.com/questions/60359808/how-to-access-own-window-within-swiftui-view/60359809#60359809)
 class SceneDelegate: NSObject, ObservableObject, UIWindowSceneDelegate {
     var window: UIWindow? // << contract of `UIWindowSceneDelegate`
 
@@ -11,7 +11,7 @@ class SceneDelegate: NSObject, ObservableObject, UIWindowSceneDelegate {
         window?.overrideUserInterfaceStyle = .light
     }
 
-    // do memory cleanup after scene removed, otherwise windowContainer cannot destroy content after being dismissed
+    /// do memory cleanup after scene removed, otherwise windowContainer cannot destroy content after being dismissed
     func sceneDidDisconnect(_ scene: UIScene) {
         window = nil
     }

package/web-spatial/manager/AttachmentManager.swift

@@ -0,0 +1,84 @@
+import Foundation
+import SwiftUI
+
+struct AttachmentInfo: Identifiable, Equatable {
+    let id: String
+    var parentEntityId: String
+    var position: SIMD3<Float>
+    var size: CGSize
+    var webViewModel: SpatialWebViewModel
+
+    static func == (lhs: AttachmentInfo, rhs: AttachmentInfo) -> Bool {
+        lhs.id == rhs.id
+    }
+}
+
+@Observable
+class AttachmentManager {
+    var attachments: [String: AttachmentInfo] = [:]
+
+    // TODO: AttachmentManager.remove() dispatches destroy() asynchronously while
+    // SwiftUI tears down the outgoing SpatialWebView from the RealityView's
+    // ForEach. Both happen on the main queue but ordering isn't guaranteed — if
+    // destroy() nils the controller before SwiftUI finishes teardown,
+    // getController() re-creates it with only `model` set, missing the four
+    // callback registrations from init(url:). Refactor to give attachments a
+    // dedicated view path (e.g. AttachmentWebView) that doesn't depend on
+    // SpatialWebViewModel's lazy re-init.
+    func create(
+        id: String,
+        parentEntityId: String,
+        position: SIMD3<Float>,
+        size: CGSize,
+        webViewModel: SpatialWebViewModel
+    ) -> AttachmentInfo {
+        webViewModel.setBackgroundTransparent(true)
+        // webViewModel.scrollEnabled = false
+
+        let info = AttachmentInfo(
+            id: id,
+            parentEntityId: parentEntityId,
+            position: position,
+            size: size,
+            webViewModel: webViewModel
+        )
+        attachments[id] = info
+        return info
+    }
+
+    func update(id: String, position: SIMD3<Float>?, size: CGSize?) {
+        guard var info = attachments[id] else { return }
+
+        if let position = position {
+            info.position = position
+        }
+        if let size = size {
+            info.size = size
+        }
+
+        attachments[id] = info
+    }
+
+    func remove(id: String) {
+        if let info = attachments.removeValue(forKey: id) {
+            DispatchQueue.main.async {
+                info.webViewModel.destroy()
+            }
+        }
+    }
+
+    func get(id: String) -> AttachmentInfo? {
+        attachments[id]
+    }
+
+    func destroyAll() {
+        let toDestroy = Array(attachments.values)
+        attachments.removeAll()
+
+        DispatchQueue.main.async {
+            for info in toDestroy {
+                info.webViewModel.destroy()
+            }
+        }
+    }
+}

package/web-spatial/manager/Dynamic3DManager.swift

@@ -71,6 +71,16 @@ class Dynamic3DManager {
     }
 
     static func loadResourceToLocal(_ urlString: String, loadComplete: @escaping (Result<URL, Error>) -> Void) {
+        // load local file
+        if urlString.starts(with: "file://") {
+            guard let localUrl = URL(string: pwaManager.getLocalResourceURL(url: urlString)) else {
+                loadComplete(.failure(NSError(domain: "Download Error", code: 0, userInfo: [NSLocalizedDescriptionKey: "Local file is not found"])))
+                return
+            }
+            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

package/web-spatial/manager/JSBManager.swift

@@ -123,8 +123,7 @@ class JSBManager {
         if cmdContent == nil {
             return nil
         }
-        let concreteData = try decoder.decode(type.self, from: cmdContent!.data(using: .utf8)!)
-        return concreteData
+        return try decoder.decode(type.self, from: cmdContent!.data(using: .utf8)!)
     }
 
     private func typeof(for key: String) -> CommandDataProtocol.Type? {

package/web-spatial/manager/WKWebViewManager.swift

@@ -8,8 +8,8 @@ class WKWebViewManager {
 
     func create(controller: SpatialWebController, configuration: WKWebViewConfiguration? = nil, spatialId: String? = "") -> WKWebView {
         let userContentController = WKUserContentController()
-        // TODO: get native api instead of PACKAGE_VERSION
-        let userScript = WKUserScript(source: "window.WebSpatailEnabled = true; window.WebSpatailNativeVersion = 'PACKAGE_VERSION';", injectionTime: .atDocumentStart, forMainFrameOnly: false)
+        // TODO: get native api instead of using the injected WS_SDK_VERSION placeholder
+        let userScript = WKUserScript(source: "window.WebSpatailEnabled = true; window.WebSpatailNativeVersion = 'WS_SDK_VERSION';", injectionTime: .atDocumentStart, forMainFrameOnly: false)
         userContentController.addUserScript(userScript)
 //        userContentController.add(controller, name: "bridge")
         userContentController.addScriptMessageHandler(controller, contentWorld: .page, name: "bridge")
@@ -25,8 +25,8 @@ class WKWebViewManager {
         // change webview ua
         let ua = controller.webview!.value(forKey: "userAgent") as? String ?? ""
         let webviewVersion = ua.split(separator: configUA)[0].split(separator: "AppleWebKit")[1]
-        // TODO: get native api instead of PACKAGE_VERSION
-        controller.webview!.customUserAgent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit\(webviewVersion)WebSpatial/\("PACKAGE_VERSION") SpatialID/\(spatialId!)"
+        // TODO: get native api instead of relying on injected shell/sdk versions
+        controller.webview!.customUserAgent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit\(webviewVersion)WSAppShell/\(pwaManager.getShellVersion()) WebSpatial/\(pwaManager.getSdkVersion()) SpatialID/\(spatialId!)"
         controller.webview!.uiDelegate = controller
         controller.webview!.allowsBackForwardNavigationGestures = false
         controller.webview!.isInspectable = true

package/web-spatial/manifest.swift

@@ -6,9 +6,9 @@ var pwaManager = PWAManager()
 struct PWAManager: Codable {
     var isLocal: Bool = false
 
-    var start_url: String = "http://localhost:5173"
+    var start_url: String = "http://localhost:5173/#/geometry-verify"
 
-//    var start_url: String = "http://localhost:5173/webspatial/avp/materialApiTest"
+    // var start_url: String = "http://localhost:5173/#/spatial-drag-gesture"
 
     var scope: String = ""
     var id: String = "com.webspatial.pico"
@@ -38,7 +38,8 @@ struct PWAManager: Codable {
         baseplateVisibility: nil
     )
     var useMainScene: Bool = true
-    private var version: String = "PACKAGE_VERSION"
+    private var shellVersion: String = "WS_SHELL_VERSION"
+    private var sdkVersion: String = "WS_SDK_VERSION"
 
     mutating func _init() {
         let urlType = start_url.split(separator: "://").first
@@ -66,7 +67,7 @@ struct PWAManager: Codable {
         return url.starts(with: scope)
     }
 
-    // web+spatial://test
+    /// web+spatial://test
     func checkInDeeplink(url: String) -> String {
         var linkUrl: String = url
         for item in protocol_handlers {
@@ -102,8 +103,12 @@ struct PWAManager: Codable {
         return resource
     }
 
-    func getVersion() -> String {
-        return version
+    func getShellVersion() -> String {
+        return shellVersion
+    }
+
+    func getSdkVersion() -> String {
+        return sdkVersion
     }
 }
 

package/web-spatial/model/SpatialApp.swift

@@ -3,10 +3,10 @@ import SwiftUI
 
 let logger = Logger()
 
-// To load a local path, remove http:// eg.  "static-web/"
-let nativeAPIVersion = pwaManager.getVersion()
+/// To load a local path, remove http:// eg.  "static-web/"
+let nativeAPIVersion = pwaManager.getShellVersion()
 
-// start URL
+/// start URL
 let startURL = pwaManager.start_url
 
 let DefaultPlainWindowContainerSize = CGSize(width: 1280, height: 720)
@@ -37,7 +37,6 @@ struct Size: Codable {
     var depth: Double?
 }
 
-
 extension SceneOptions {
     init(_ options: XSceneOptionsJSB) {
         defaultSize = Size(
@@ -47,7 +46,7 @@ extension SceneOptions {
         )
         windowResizability = decodeWindowResizability(nil)
         resizeRange = options.resizability
-        /// volume only
+        // volume only
         worldScaling = options.worldScaling?.toSDK ?? .automatic
         worldAlignment = options.worldAlignment?.toSDK ?? .automatic
         baseplateVisibility = options.baseplateVisibility?.toSDK ?? .automatic
@@ -56,31 +55,44 @@ extension SceneOptions {
 
 func decodeWindowResizability(_ windowResizability: String?) -> WindowResizability {
     switch windowResizability {
-        case "automatic":
-            return .automatic
-        case "contentSize":
-            return .contentSize
-        case "contentMinSize":
-            return .contentMinSize
-        default:
-            return .automatic
+    case "automatic":
+        return .automatic
+    case "contentSize":
+        return .contentSize
+    case "contentMinSize":
+        return .contentMinSize
+    default:
+        return .automatic
     }
 }
 
 @Observable
 class SpatialApp {
     private var scenes = [String: SpatialScene]()
-    
-    // delegate properties to pwaManager
-    var name: String { pwaManager.name }
-    var scope: String { pwaManager.scope }
-    var displayMode: PWADisplayMode { pwaManager.display }
-    var version: String { pwaManager.getVersion() }
-    var startURL: String { pwaManager.start_url }
-    
-    // used to cache scene config
-    private var sceneOptions: SceneOptions
 
+    /// delegate properties to pwaManager
+    var name: String {
+        pwaManager.name
+    }
+
+    var scope: String {
+        pwaManager.scope
+    }
+
+    var displayMode: PWADisplayMode {
+        pwaManager.display
+    }
+
+    var version: String {
+        pwaManager.getShellVersion()
+    }
+
+    var startURL: String {
+        pwaManager.start_url
+    }
+
+    /// used to cache scene config
+    private var sceneOptions: SceneOptions
 
     static let Instance: SpatialApp = .init()
 
@@ -90,14 +102,12 @@ class SpatialApp {
 
         Logger.initLogger()
 
-        sceneOptions = SceneOptions(pwaManager.mainScene);
-        
-        print("plainSceneOptions",sceneOptions)
-        
+        sceneOptions = SceneOptions(pwaManager.mainScene)
+
+        print("plainSceneOptions", sceneOptions)
+
         logger.debug("WebSpatial App Started -------- rootURL: " + startURL)
     }
-    
-
 
     func createScene(_ url: String, _ style: SpatialScene.WindowStyle, _ state: SpatialScene.SceneStateKind, _ sceneOptions: SceneOptions? = nil) -> SpatialScene {
         var scene = SpatialScene(url, style, state, sceneOptions)
@@ -105,15 +115,14 @@ class SpatialApp {
         scene
             .on(event: SpatialObject.Events.Destroyed.rawValue, listener: onSceneDestroyed)
 
-        
         return scene
     }
-    
+
     private func onSceneDestroyed(_ object: Any, _ data: Any) {
         var spatialObject = object as! SpatialObject
         spatialObject
             .off(event: SpatialObject.Events.Destroyed.rawValue, listener: onSceneDestroyed)
-        
+
         scenes.removeValue(forKey: spatialObject.id)
     }
 
@@ -121,63 +130,58 @@ class SpatialApp {
         return scenes[id]
     }
 
-    
     func getSceneOptions() -> SceneOptions {
         return sceneOptions
     }
-    
-    func getSceneOptions(_ sceneId:String) -> SceneOptions? {
+
+    func getSceneOptions(_ sceneId: String) -> SceneOptions? {
         let spatialScene = getScene(sceneId)
         return spatialScene?.sceneConfig
     }
-    
-    
-    // used form window.open logic
-    public func openWindowGroup(
+
+    /// used form window.open logic
+    func openWindowGroup(
         _ targetSpatialScene: SpatialScene,
         _ sceneData: SceneOptions
     ) {
         if let activeScene = firstActiveScene {
             // cache scene config
             sceneOptions = sceneData
-                        
-            DispatchQueue.main.async() {
+
+            DispatchQueue.main.async {
                 activeScene.openWindowData.send(targetSpatialScene.id)
             }
-
         }
     }
-    
-    public func closeWindowGroup(_ targetSpatialScene: SpatialScene) {
+
+    func closeWindowGroup(_ targetSpatialScene: SpatialScene) {
         if let activeScene = firstActiveScene {
             activeScene.closeWindowData
                 .send(targetSpatialScene.id)
         }
     }
-    
-    // used form window.open logic with loading ui
-    public func openLoadingUI(_ targetSpatialScene: SpatialScene,_ open: Bool) {
+
+    /// used form window.open logic with loading ui
+    func openLoadingUI(_ targetSpatialScene: SpatialScene, _ open: Bool) {
         let lwgdata = XLoadingViewData(
             sceneID: targetSpatialScene.id,
             method: open ? .show : .hide,
             windowStyle: nil
         )
-        
+
         if let activeScene = firstActiveScene {
             activeScene.setLoadingWindowData.send(lwgdata)
         }
     }
-    
+
     private var firstActiveScene: SpatialScene? {
-        get {
-            let activeKV = scenes.first() { kv in
-                kv.value.state == .visible
-            }
-            return (activeKV?.value)
+        let activeKV = scenes.first { kv in
+            kv.value.state == .visible
         }
+        return (activeKV?.value)
     }
-    
-    public func focusScene(_ targetSpatialScene: SpatialScene) {
+
+    func focusScene(_ targetSpatialScene: SpatialScene) {
         // only work when fully visible
         if targetSpatialScene.state != .visible {
             return