@webspatial/platform-visionos 1.2.1 → 1.4.0

package/web-spatial/view/SpatializedElementView.swift

@@ -1,10 +1,9 @@
+import CoreGraphics
 import SwiftUI
 
-// zIndex() have some bug, so use zOrderBias to simulate zIndex effect
-let zOrderBias = 0.001
-
-final class GestureFlags {
+final class GestureState {
     var isDrag = false
+    var proxyTransform: AffineTransform3D = .identity
 }
 
 struct SpatializedElementView<Content: View>: View {
@@ -14,32 +13,44 @@ struct SpatializedElementView<Content: View>: View {
     var parentScrollOffset: Vec2
     var content: Content
 
-    @State private var gestureFlags = GestureFlags()
+    @State private var gestureState = GestureState()
 
     init(parentScrollOffset: Vec2, @ViewBuilder content: () -> Content) {
         self.parentScrollOffset = parentScrollOffset
         self.content = content()
     }
 
-    // Begin Interaction
+    /// Begin Interaction
     var gesture: some Gesture {
         DragGesture(minimumDistance: 10)
             .onChanged(onDragging)
             .onEnded(onDraggingEnded)
             .simultaneously(with:
-                RotateGesture3D()
+                makeRotateGesture3D()
                     .onChanged(onRotateGesture3D)
-                    .onEnded(onRotateGesture3DEnd)
-            )
+                    .onEnded(onRotateGesture3DEnd))
             .simultaneously(with:
                 MagnifyGesture()
                     .onChanged(onMagnifyGesture)
-                    .onEnded(onMagnifyGestureEnd)
-            )
+                    .onEnded(onMagnifyGestureEnd))
             .simultaneously(with:
                 SpatialTapGesture(count: 1)
-                    .onEnded(onTapEnded)
-            )
+                    .onEnded(onTapEnded))
+    }
+
+    private func makeRotateGesture3D() -> RotateGesture3D {
+        guard let raw = spatializedElement.rotateConstrainedToAxis else {
+            return RotateGesture3D()
+        }
+        let dx = Double(raw.x)
+        let dy = Double(raw.y)
+        let dz = Double(raw.z)
+        let len = (dx * dx + dy * dy + dz * dz).squareRoot()
+        if len < 1e-9 {
+            return RotateGesture3D()
+        }
+        let axis = RotationAxis3D(x: dx / len, y: dy / len, z: dz / len)
+        return RotateGesture3D(constrainedToAxis: axis)
     }
 
     private func onRotateGesture3D(_ event: RotateGesture3D.Value) {
@@ -63,11 +74,18 @@ struct SpatializedElementView<Content: View>: View {
     }
 
     private func onDragging(_ event: DragGesture.Value) {
-        if spatializedElement.enableDragStartGesture, !gestureFlags.isDrag {
+        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 gestureEvent = WebSpatialDragStartGuestureEvent(detail: .init(
-                startLocation3D: event.startLocation3D
+                startLocation3D: startLocal,
+                globalLocation3D: globalPoint3D
             ))
-
             spatialScene.sendWebMsg(spatializedElement.id, gestureEvent)
         }
 
@@ -79,20 +97,40 @@ struct SpatializedElementView<Content: View>: View {
             spatialScene.sendWebMsg(spatializedElement.id, gestureEvent)
         }
 
-        gestureFlags.isDrag = true
+        gestureState.isDrag = true
     }
 
     private func onDraggingEnded(_ event: DragGesture.Value) {
-        gestureFlags.isDrag = false
+        gestureState.isDrag = false
         if spatializedElement.enableDragEndGesture {
             let gestureEvent = WebSpatialDragEndGuestureEvent()
             spatialScene.sendWebMsg(spatializedElement.id, gestureEvent)
         }
     }
 
+    /// Z offset that defines the local coordinate system (front face = z=0).
+    /// Only backOffset and zIndex*bias; excludes translation.z (CSS translateZ is visual-only).
+    private func localFrameOffsetZ() -> Double {
+        (spatializedElement.zIndex * zOrderBias) + spatializedElement.backOffset
+    }
+
+    /// Maps a point in the gesture's local coordinate system to SpatialScene.
+    private func localToScene(_ localPoint: Point3D) -> Point3D {
+        let p = SIMD4<Double>(localPoint.x, localPoint.y, localPoint.z, 1.0)
+        let scene = gestureState.proxyTransform.matrix * p
+        return Point3D(x: scene.x, y: scene.y, z: scene.z)
+    }
+
     private func onTapEnded(_ event: SpatialTapGesture.Value) {
         if spatializedElement.enableTapGesture {
-            spatialScene.sendWebMsg(spatializedElement.id, WebSpatialTapGuestureEvent(detail: .init(location3D: event.location3D)))
+            let frameZ = localFrameOffsetZ()
+            let localPoint3D = Point3D(
+                x: event.location3D.x,
+                y: event.location3D.y,
+                z: event.location3D.z - frameZ
+            )
+            let globalPoint3D = localToScene(event.location3D)
+            spatialScene.sendWebMsg(spatializedElement.id, WebSpatialTapGuestureEvent(detail: .init(location3D: localPoint3D, globalLocation3D: globalPoint3D)))
         }
     }
 
@@ -101,7 +139,8 @@ struct SpatializedElementView<Content: View>: View {
             let gestureEvent = WebSpatialMagnifyGuestureEvent(
                 detail: .init(
                     magnification: event.magnification
-                ))
+                )
+            )
             spatialScene.sendWebMsg(spatializedElement.id, gestureEvent)
         }
     }
@@ -114,12 +153,8 @@ struct SpatializedElementView<Content: View>: View {
 
     // End Interaction
 
-    @ViewBuilder
     var body: some View {
         let transform = spatializedElement.transform
-        let translation = transform.translation
-        let scale = transform.scale
-        let rotation = transform.rotation!
 
         let width = spatializedElement.width
         let height = spatializedElement.height
@@ -133,8 +168,17 @@ struct SpatializedElementView<Content: View>: View {
         let visible = spatializedElement.visible
         let enableGesture = spatializedElement.enableGesture
 
-        let z = translation.z + (spatializedElement.zIndex * zOrderBias)
-        let smallOffset = z == 0.0 ? 0.0001 : 0
+        let frameOffsetZ = localFrameOffsetZ()
+        let smallOffset = abs(frameOffsetZ) < 0.0001 ? 0.0001 : 0
+
+        // Wrap CSS transform with anchor (CSS transform-origin) since
+        // transform3DEffect does not support anchor. Preserves the original
+        // CSS transform order (e.g. rotateX(90deg) translateZ(100px)).
+        let ax = width * anchor.x
+        let ay = height * anchor.y
+        let toAnchor = AffineTransform3D(translation: Vector3D(x: -ax, y: -ay, z: 0))
+        let fromAnchor = AffineTransform3D(translation: Vector3D(x: ax, y: ay, z: 0))
+        let anchoredTransform = fromAnchor.concatenating(transform).concatenating(toAnchor)
 
         // when spatialdiv have regular/thick/thin material and alignment is back, there'll be a bug that clipping content
         // so when spatializedElement is spatialdiv, .center alignment will be applied
@@ -143,32 +187,26 @@ struct SpatializedElementView<Content: View>: View {
         content
             .frame(width: width, height: height)
             .frame(depth: depth, alignment: alignment)
-            .onGeometryChange3D(for: AffineTransform3D.self) { proxy in
-                let rect3d = proxy.frame(in: .named("SpatialScene"))
-                spatialScene.sendWebMsg(spatializedElement.id, SpatiaizedContainerClientCube(origin: rect3d.origin, size: rect3d.size))
-                return proxy.transform(in: .named("SpatialScene"))!
-            } action: { _, new in
-                spatialScene.sendWebMsg(spatializedElement.id, SpatiaizedContainerTransform(detail: new))
-            }
             .frame(depth: 0, alignment: .back)
             // use .offset(smallVal) to workaround for glassEffect not working and small width/height spatialDiv not working
             .offset(z: smallOffset)
-            .scaleEffect(
-                x: scale.width,
-                y: scale.height,
-                z: scale.depth,
-                anchor: anchor
-            )
-            .rotation3DEffect(
-                rotation,
-                anchor: anchor
-            )
-            .offset(x: translation.x, y: translation.y)
-            .offset(z: z)
+            // Full CSS transform matrix with anchor baked in. Preserves transform
+            // composition order; CSS translateZ participates in rotation direction.
+            .transform3DEffect(anchoredTransform)
+            // backOffset + zIndex: always along parent Z, independent of CSS transform.
+            .offset(z: frameOffsetZ)
+            // 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)
+            .onGeometryChange3D(for: AffineTransform3D.self) { proxy in
+                proxy.transform(in: .named("SpatialScene"))!
+            } action: { new in
+                gestureState.proxyTransform = new
+                spatializedElement.proxySceneTransform = new
+            }
+
             .position(x: centerX + width / 2, y: centerY + height / 2)
-            .offset(z: spatializedElement.backOffset)
             .opacity(opacity)
             .hidden(!visible)
-            .simultaneousGesture(enableGesture ? gesture : nil)
     }
 }

package/web-spatial/view/SpatializedStatic3DView.swift

@@ -8,7 +8,7 @@ struct SpatializedStatic3DView: View {
     private var spatializedStatic3DElement: SpatializedStatic3DElement {
         return spatializedElement as! SpatializedStatic3DElement
     }
-    
+
     func onLoadSuccess() {
         spatialScene.sendWebMsg(spatializedElement.id, ModelLoadSuccess())
     }
@@ -17,7 +17,6 @@ struct SpatializedStatic3DView: View {
         spatialScene.sendWebMsg(spatializedElement.id, ModelLoadFailure())
     }
 
-    @ViewBuilder
     var body: some View {
         let depth = spatializedElement.depth
         let transform = spatializedStatic3DElement.modelTransform
@@ -27,14 +26,17 @@ struct SpatializedStatic3DView: View {
         let x = translation.x
         let y = translation.y
         let z = translation.z
-        
+
         let enableGesture = spatializedElement.enableGesture
-        if let url = URL(string: spatializedStatic3DElement.modelURL) {
+        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:
                     ProgressView()
-
                 case let .success(resolvedModel3D):
                     resolvedModel3D
                         .resizable(true)
@@ -42,11 +44,11 @@ struct SpatializedStatic3DView: View {
                             nil,
                             contentMode: .fit
                         )
-                        .if(!depth.isZero){ view in view.scaledToFit3D()}
+                        .if(!depth.isZero) { view in view.scaledToFit3D() }
                         .onAppear {
                             self.onLoadSuccess()
                         }
-                        .if(enableGesture) { view in view.hoverEffect()}
+                        .if(enableGesture) { view in view.hoverEffect() }
                 case .failure:
                     Text("").onAppear {
                         self.onLoadFailure()

package/web-spatial/view/view-modifier/HideViewModifier.swift

@@ -2,14 +2,14 @@ import SwiftUI
 
 struct HideViewModifier: ViewModifier {
     let isHidden: Bool
-    @ViewBuilder func body(content: Content) -> some View {
+    func body(content: Content) -> some View {
         content
             .opacity(isHidden ? 0 : 1)
             .disabled(isHidden)
     }
 }
 
-// Extending on View to apply to all Views
+/// Extending on View to apply to all Views
 extension View {
     func hidden(_ isHidden: Bool) -> some View {
         modifier(HideViewModifier(isHidden: isHidden))

package/web-spatial/webview/SpatialWebController.swift

@@ -9,7 +9,7 @@ class SpatialWebController: NSObject, WKNavigationDelegate, WKScriptMessageHandl
     private var openWindowInvoke: ((_ data: URL) -> WebViewElementInfo?)?
     private var webviewStateChangeInvoke: ((_ type: SpatialWebViewState) -> Void)?
     private var scorllUpdateInvoke: ((_ type: ScrollState, _ point: CGPoint) -> Void)?
-    private var webviewTitle: String? = nil
+    private var webviewTitle: String?
     private var firstLoad = true
     private var jsbManager = JSBManager()
 
@@ -62,25 +62,29 @@ class SpatialWebController: NSObject, WKNavigationDelegate, WKScriptMessageHandl
         }
     }
 
-    // navigation request
-    // SpatialDiv/forcestyle/normal web link protocol
+    /// navigation request
+    /// SpatialDiv/forcestyle/normal web link protocol
     func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {
         let deciside = navigationInvoke?(navigationAction.request.url!)
         if deciside == true {
-            if !firstLoad{
+            if !firstLoad {
                 webviewStateChangeInvoke?(.didUnload)
             }
             firstLoad = false
         }
         var needAllow = deciside ?? false
-        
-        if !needAllow{
-            UIApplication.shared.open(navigationAction.request.url!, options: [:], completionHandler: nil)
+
+        if !needAllow {
+            // webspatial:// is an internal scheme for in-app routing between main and attachment windows.
+            // Only open non-webspatial URLs externally via the system.
+            if navigationAction.request.url?.scheme != "webspatial" {
+                UIApplication.shared.open(navigationAction.request.url!, options: [:], completionHandler: nil)
+            }
         }
         decisionHandler(needAllow ? .allow : .cancel)
     }
 
-    // open window request
+    /// open window request
     func webView(
         _ webView: WKWebView,
         createWebViewWith configuration: WKWebViewConfiguration,
@@ -95,7 +99,7 @@ class SpatialWebController: NSObject, WKNavigationDelegate, WKScriptMessageHandl
         return nil
     }
 
-    // invoke jsb
+    /// invoke jsb
     func userContentController(
         _ userContentController: WKUserContentController,
         didReceive message: WKScriptMessage, replyHandler: @escaping (Any?, String?) -> Void
@@ -104,12 +108,26 @@ class SpatialWebController: NSObject, WKNavigationDelegate, WKScriptMessageHandl
         jsbManager.handlerMessage(message.body as! String, replyHandler)
     }
 
-    // custom scheme request
+    /// custom scheme request
     func webView(_ webView: WKWebView, start urlSchemeTask: any WKURLSchemeTask) {
         print("urlSchemeTask")
         let url = urlSchemeTask.request.url
         if url!.absoluteString.starts(with: "file://") {
-            let urlRequest = urlSchemeTask.request
+            let resource: String = pwaManager.getLocalResourceURL(url: url!.absoluteString)
+            var urlRequest = urlSchemeTask.request
+            if resource != "" {
+                if let resourceUrl = URL(string: resource) {
+                    urlRequest = URLRequest(url: resourceUrl)
+                } else {
+                    let error = NSError(domain: "LocalResourceError", code: 404, userInfo: [NSLocalizedDescriptionKey: "Local file resource mapping failed"])
+                    urlSchemeTask.didFailWithError(error)
+                    return
+                }
+            } else {
+                let error = NSError(domain: "LocalResourceError", code: 404, userInfo: [NSLocalizedDescriptionKey: "Local resource not found"])
+                urlSchemeTask.didFailWithError(error)
+                return
+            }
 
             let session = URLSession(configuration: URLSessionConfiguration.default)
             let dataTask = session.dataTask(with: urlRequest) { [task = urlSchemeTask as AnyObject] data, response, _ in
@@ -221,8 +239,8 @@ class SpatialWebController: NSObject, WKNavigationDelegate, WKScriptMessageHandl
         scorllUpdateInvoke = nil
         model = nil
     }
-    
-    private var state:SpatialWebViewState?
+
+    private var state: SpatialWebViewState?
 
     func destroyView() {
         stopObserving()
@@ -236,15 +254,15 @@ class SpatialWebController: NSObject, WKNavigationDelegate, WKScriptMessageHandl
             webviewStateChangeInvoke?(.didDestroyView)
         }
     }
-    
+
     private var isPageLoaded = false
-    
+
     private var jsQueue: [String] = []
-    
+
     private func enqueueJS(_ js: String) {
         jsQueue.append(js)
     }
-    
+
     private func flushJSQueue() {
         guard !jsQueue.isEmpty else { return }
         let combined = jsQueue.joined(separator: ";")
@@ -253,7 +271,7 @@ class SpatialWebController: NSObject, WKNavigationDelegate, WKScriptMessageHandl
     }
 
     func callJS(_ js: String) {
-        if webview != nil && isPageLoaded {
+        if webview != nil, isPageLoaded {
             webview!.evaluateJavaScript(js)
         } else {
             enqueueJS(js)
@@ -268,13 +286,13 @@ enum ScrollState {
     case end
 }
 
-// extend webview to support file://
- @available(iOS 11.0, *)
- extension WKWebView {
+/// extend webview to support file://
+@available(iOS 11.0, *)
+extension WKWebView {
     /// WKWebView,  Support setting file scheme in configuration
     public private(set) static var isEnableFileSupport = false
     public static func enableFileScheme() {
-        /// This method supports adapting supported files through Configuration, but cannot be cancelled (Configuration is immutable).
+        // This method supports adapting supported files through Configuration, but cannot be cancelled (Configuration is immutable).
         if !isEnableFileSupport {
             switchHandlesURLScheme()
         }
@@ -292,9 +310,8 @@ enum ScrollState {
     }
 
     /// Return true if WKWebview supports handling this protocol, but WKWebview supports HTTP by default, so return false to support using custom HTTP Handler
-    @objc private dynamic
-    static func wrapHandles(urlScheme: String) -> Bool {
+    @objc private dynamic static func wrapHandles(urlScheme: String) -> Bool {
         if urlScheme == "file" { return false }
         return wrapHandles(urlScheme: urlScheme)
     }
- }
+}

package/web-spatial/webview/SpatialWebView.swift

@@ -8,7 +8,11 @@ struct SpatialWebView: UIViewRepresentable {
 
     func makeUIView(context: Context) -> WKWebView {
         webviewStateChangeInvoke?(.didMakeView)
-        return model!.getController().webview!
+        let controller = model?.getController()
+        if controller?.webview == nil {
+            model?.load()
+        }
+        return controller?.webview ?? WKWebView(frame: .zero, configuration: WKWebViewConfiguration())
     }
 
     func makeCoordinator() -> SpatialWebController {

package/web-spatial/webview/SpatialWebViewModel.swift

@@ -76,6 +76,12 @@ class SpatialWebViewModel {
     }
 
     func getController() -> SpatialWebController {
+        // See TODO in AttachmentManager — async destroy() during SwiftUI teardown
+        // can nil the controller while the view is still being removed.
+        if controller == nil {
+            controller = SpatialWebController()
+            controller!.model = self
+        }
         return controller!
     }
 
@@ -103,8 +109,8 @@ class SpatialWebViewModel {
         controller?.setWebViewTitle(title)
     }
 
-    // events
-    // navigation event
+    /// events
+    /// navigation event
     func addNavigationListener(protocal: String, event: @escaping (_ data: URL) -> Bool) {
         navigationList[protocal] = event
     }
@@ -113,7 +119,7 @@ class SpatialWebViewModel {
         navigationList = [:]
     }
 
-    // open window event
+    /// open window event
     func addOpenWindowListener(protocal: String, _ event: @escaping (_ data: URL) -> WebViewElementInfo?) {
         openWindowList[protocal] = event
     }
@@ -122,7 +128,7 @@ class SpatialWebViewModel {
         openWindowList = [:]
     }
 
-    // jsb event
+    /// jsb event
     func addJSBListener<T: CommandDataProtocol>(_ dataClass: T.Type, _ event: @escaping (T, @escaping JSBManager.ResolveHandler<Encodable>) -> Void) {
         controller?.registeJSBHandler(dataClass, event)
     }
@@ -143,7 +149,7 @@ class SpatialWebViewModel {
         controller?.mockJSB(command)
     }
 
-    // webview state event
+    /// webview state event
     func addStateListener(_ event: @escaping (_ type: SpatialWebViewState) -> Void) {
         stateChangeListeners.append(event)
     }
@@ -176,7 +182,7 @@ class SpatialWebViewModel {
         stateListeners[state] = nil
     }
 
-    // scroll update event
+    /// scroll update event
     func addScrollUpdateListener(_ event: @escaping (_ type: ScrollState, _ point: CGPoint) -> Void) {
         scrollUpdateListeners.append(event)
     }
@@ -199,7 +205,7 @@ class SpatialWebViewModel {
         removeAllScrollUpdateListener()
     }
 
-    // invokes
+    /// invokes
     private func onNavigationInvoke(_ url: URL) -> Bool {
         var matchProtocol = false
         for key in navigationList.keys {

package/web-spatial.xcodeproj/project.pbxproj

@@ -13,6 +13,7 @@
 		2B06AEE42E4C1AE8000327E9 /* manifest.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2B06AEC12E4C1AE8000327E9 /* manifest.swift */; };
 		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 */; };
@@ -37,6 +38,7 @@
 		2B06AEC22E4C1AE8000327E9 /* SpatialObject.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SpatialObject.swift; sourceTree = "<group>"; };
 		2B06AEC32E4C1AE8000327E9 /* WebSpatialApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WebSpatialApp.swift; sourceTree = "<group>"; };
 		2B06AEC42E4C1AE8000327E9 /* Window.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Window.swift; sourceTree = "<group>"; };
+		2B1008A12F0B000800000001 /* NavigationCleanupTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NavigationCleanupTests.swift; sourceTree = "<group>"; };
 		2B2F1D632BEBFAAA006897EE /* WebSpatial.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = WebSpatial.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		2B2F1D672BEBFAAA006897EE /* RealityKitContent */ = {isa = PBXFileReference; lastKnownFileType = wrapper; path = RealityKitContent; sourceTree = "<group>"; };
 		2B2F1D702BEBFAAC006897EE /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
@@ -51,6 +53,7 @@
 		2B06AF302E4C1AF8000327E9 /* PBXFileSystemSynchronizedBuildFileExceptionSet */ = {
 			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
 			membershipExceptions = (
+				AttachmentManager.swift,
 				Dynamic3DManager.swift,
 				FileCoordinator.swift,
 				JSBManager.swift,
@@ -152,10 +155,19 @@
 /* End PBXFrameworksBuildPhase section */
 
 /* Begin PBXGroup section */
+		2B1008A32F0B000800000003 /* web-spatialTests */ = {
+			isa = PBXGroup;
+			children = (
+				2B1008A12F0B000800000001 /* NavigationCleanupTests.swift */,
+			);
+			path = "web-spatialTests";
+			sourceTree = "<group>";
+		};
 		2B2F1D5A2BEBFAAA006897EE = {
 			isa = PBXGroup;
 			children = (
 				2B2F1D652BEBFAAA006897EE /* web-spatial */,
+				2B1008A32F0B000800000003 /* web-spatialTests */,
 				2B2F1D662BEBFAAA006897EE /* Packages */,
 				2B2F1D642BEBFAAA006897EE /* Products */,
 			);
@@ -334,6 +346,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				2B1008A22F0B000800000002 /* NavigationCleanupTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

package/web-spatialTests/NavigationCleanupTests.swift

@@ -0,0 +1,33 @@
+@testable import WebSpatial
+import XCTest
+
+final class NavigationCleanupTests: XCTestCase {
+    func test_resetForNavigation_destroysSceneSpatialObjectsAndAttachments() {
+        // Given: a scene with spatial objects and attachments created by the current page
+        let scene = SpatialApp.Instance.createScene(
+            "http://localhost:5173/",
+            .window,
+            .visible
+        )
+
+        let panel: Spatialized2DElement = scene.createSpatializedElement(.Spatialized2DElement)
+        panel.setParent(scene)
+        XCTAssertNotNil(scene.findSpatialObject(panel.id) as Spatialized2DElement?)
+
+        _ = scene.attachmentManager.create(
+            id: "test-attachment",
+            parentEntityId: "test-parent-entity",
+            position: SIMD3<Float>(0, 0, 0),
+            size: CGSize(width: 100, height: 100)
+        )
+        XCTAssertFalse(scene.attachmentManager.attachments.isEmpty)
+
+        // When: navigation happens (reload/back/forward/new URL)
+        scene.resetForNavigation()
+
+        // Then: all existing spatial objects and attachments should be cleaned up
+        XCTAssertNil(scene.findSpatialObject(panel.id) as Spatialized2DElement?)
+        XCTAssertTrue(scene.attachmentManager.attachments.isEmpty)
+        XCTAssertNil(SpatialObject.get(panel.id))
+    }
+}