@needle-tools/engine 4.12.0-next.de80571 → 4.12.0-next.f0b1535

package/src/engine/engine_input.ts

@@ -150,6 +150,12 @@ export class NEPointerEvent extends PointerEvent {
     override get pointerType(): PointerTypeNames { return this._pointerType; }
     private readonly _pointerType: PointerTypeNames;
 
+    /**
+     * The button name that raised this event (e.g. for mouse events "left", "right", "middle" or for XRTrigger "xr-standard-trigger" or "xr-standard-thumbstick")    
+     * Use {@link button} to get the numeric button index (e.g. 0, 1, 2...) on the controller or mouse.
+     */
+    readonly buttonName?: ButtonName | "none" = undefined;
+
     // this is set via the init arguments (we override it here for intellisense to show the string options)
     /** The input that raised this event like `pointerdown` */
     override get type(): InputEventNames { return this._type; }
@@ -176,6 +182,7 @@ export class NEPointerEvent extends PointerEvent {
         this.mode = init.mode;
         this._ray = init.ray;
         this.space = init.device;
+        this.buttonName = init.buttonName;
     }
 
     private _immediatePropagationStopped = false;

package/src/engine/engine_license.ts

@@ -81,7 +81,7 @@ async function checkLicense() {
     if (runtimeLicenseCheckPromise) return runtimeLicenseCheckPromise;
     if (NEEDLE_ENGINE_LICENSE_TYPE === "basic") {
         try {
-            const licenseUrl = "https://engine.needle.tools/licensing/check?location=" + encodeURIComponent(window.location.href) + "&version=" + VERSION + "&generator=" + encodeURIComponent(GENERATOR);
+            const licenseUrl = "https://needle.tools/api/v1/needle-engine/check?location=" + encodeURIComponent(window.location.href) + "&version=" + VERSION + "&generator=" + encodeURIComponent(GENERATOR);
             const res = await fetch(licenseUrl, {
                 method: "GET",
             }).catch(_err => {
@@ -352,17 +352,12 @@ async function sendUsageMessageToAnalyticsBackend(context: IContext) {
     }
 
     try {
-        const analyticsUrl = "htt" + "ps://nee" + "dle.tools/api/v1/ana" + "lytics";
+        const analyticsUrl = "htt" + "ps://" + "needle" + ".tools/" + "api/v1/needle-engine/ping";
         if (analyticsUrl) {
 
             // current url without query parameters
             const currentUrl = window.location.href.split("?")[0];
-
-            let endpoint = "api/v2/new/request";
-            if (!analyticsUrl.endsWith("/")) endpoint = "/" + endpoint;
             const license = NEEDLE_ENGINE_LICENSE_TYPE;
-            const finalUrl = `${analyticsUrl}${endpoint}`;
-            if (debug) console.debug("Sending beacon");
 
             const beaconData = {
                 license,
@@ -376,7 +371,7 @@ async function sendUsageMessageToAnalyticsBackend(context: IContext) {
                 build_time: BUILD_TIME,
                 public_key: PUBLIC_KEY,
             };
-            const res = navigator.sendBeacon?.(finalUrl, JSON.stringify(beaconData));
+            const res = navigator.sendBeacon?.(analyticsUrl, JSON.stringify(beaconData));
             if (debug) console.debug("Sent beacon: " + res);
         }
     }

package/src/engine/engine_networking.ts

@@ -629,7 +629,7 @@ export class NetworkConnection implements INetworkConnection {
                 return;
             }
 
-            console.debug("⊡ Connecting to networking backend on\n" + networkingServerUrl)
+            console.debug("Connecting to networking backend on\n" + networkingServerUrl)
             const pkg = await import('websocket-ts');
             // @ts-ignore
             const WebsocketBuilder = pkg.default?.WebsocketBuilder ?? pkg.WebsocketBuilder;
@@ -641,8 +641,8 @@ export class NetworkConnection implements INetworkConnection {
                     this._connectingToWebsocketPromise = null;
                     this._ws = ws;
                     this.connected = true;
-                    if (isDevEnvironment() || debugNet) console.log("⊞ Connected to networking backend\n" + networkingServerUrl);
-                    else console.debug("⊞ Connected to networking backend", networkingServerUrl);
+                    if (isDevEnvironment() || debugNet) console.log("Connected to networking backend\n" + networkingServerUrl);
+                    else console.debug("Connected to networking backend", networkingServerUrl);
                     resolve(true);
                     this.onSendQueued(SendQueue.OnConnection);
                 })
@@ -656,10 +656,10 @@ export class NetworkConnection implements INetworkConnection {
                     console.error(msg);
                 })
                 .onError((_e) => {
-                    console.error("⊠ Websocket connection failed...");
+                    console.error("Websocket connection failed...");
                     resolve(false);
                 })
-                .onRetry(() => { console.log("→ Retry connecting to networking websocket") })
+                .onRetry(() => { console.log("Retry connecting to networking websocket") })
                 .build();
             ws.addEventListener(pkg.WebsocketEvent.message, (socket, msg) => {
                 this.onMessage(socket, msg);

package/src/engine/engine_physics.ts

@@ -1,7 +1,7 @@
 import { getRaycastMesh } from '@needle-tools/gltf-progressive';
 import { ArrayCamera, Box3, BufferGeometry, Camera, type Intersection, Layers, Line, Matrix3, Matrix4, Mesh, Object3D, PerspectiveCamera, Plane, Ray, Raycaster, SkinnedMesh, Sphere, SphereGeometry, Vector2, Vector3 } from 'three'
 import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js';
-import type { MeshBVH, MeshBVHOptions, StaticGeometryGenerator } from 'three-mesh-bvh';
+import type { ComputeBVHOptions, GeometryBVH, MeshBVH, StaticGeometryGenerator } from 'three-mesh-bvh';
 import type { GenerateMeshBVHWorker } from 'three-mesh-bvh/src/workers/GenerateMeshBVHWorker.js';
 
 import { isDevEnvironment } from './debug/index.js';
@@ -762,7 +762,7 @@ namespace NEMeshBVH {
             return true;
         }
         else if (method instanceof Sphere) {
-            const bvh = geom.boundsTree;
+            const bvh = geom.boundsTree as MeshBVH | undefined;
             if (bvh) {
                 const sphere = method;
                 // Gizmos.DrawWireSphere(sphere.center, sphere.radius, 0xdddd00, 1, false);
@@ -789,7 +789,7 @@ namespace NEMeshBVH {
     let _acceleratedRaycast: Function | null = null;
     let _MeshBVH: ConstructorConcrete<MeshBVH> | null = null;
     let _StaticGeometryGenerator: ConstructorConcrete<StaticGeometryGenerator> | null = null;
-    let _computeBoundsTree: ((_opt?: MeshBVHOptions) => MeshBVH) | null = null;
+    let _computeBoundsTree: (( options?: ComputeBVHOptions ) => GeometryBVH) | null = null;
 
     function loadMeshBVHLibrary() {
         if (didLoadMeshBVHLibrary) return;

package/src/engine/engine_physics_rapier.ts

@@ -273,7 +273,7 @@ export class RapierPhysics implements IPhysicsEngine {
         if (MODULES.RAPIER_PHYSICS.MAYBEMODULE == undefined) {
             if (debugPhysics) console.trace("Loading rapier physics engine");
             const module = await MODULES.RAPIER_PHYSICS.load();
-            // https://github.com/dimforge/rapier/issues/811
+            // https://github.com/dimforge/rapier/issues/811 < but single object parameter still warns
             await module.init();
         }
         if (debugPhysics) console.log("Physics engine initialized, creating world...");

package/src/engine/engine_utils.ts

@@ -606,7 +606,8 @@ export namespace DeviceUtilities {
     /** @returns `true` if we're currently on an iPad */
     export function isiPad() {
         if (__isiPad !== undefined) return __isiPad;
-        return __isiPad = /iPad/.test(navigator.userAgent);
+        const userAgent = navigator.userAgent.toLowerCase();
+        return __isiPad = /iPad/.test(navigator.userAgent) || userAgent.includes("macintosh") && "ontouchend" in document;
     }
 
     let __isAndroidDevice: boolean | undefined;
@@ -623,17 +624,25 @@ export namespace DeviceUtilities {
         return __isMozillaXR = /WebXRViewer\//i.test(navigator.userAgent);
     }
 
+    let __isNeedleAppClip: boolean | undefined;
+    /** @returns `true` if we're currently in the Needle App Clip */
+    export function isNeedleAppClip() {
+        if (__isNeedleAppClip !== undefined) return __isNeedleAppClip;
+        return __isNeedleAppClip = /NeedleAppClip\//i.test(navigator.userAgent);
+    }
+
     let __isMacOS: boolean | undefined;
     // https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgentData
     /** @returns `true` for MacOS devices */
     export function isMacOS() {
         if (__isMacOS !== undefined) return __isMacOS;
+        if (isiOS() || isiPad()) return __isMacOS = false;
+        const userAgent = navigator.userAgent.toLowerCase();
         if (navigator.userAgentData) {
             // Use modern UA Client Hints API if available
             return __isMacOS = navigator.userAgentData.platform === 'macOS';
         } else {
             // Fallback to user agent string parsing
-            const userAgent = navigator.userAgent.toLowerCase();
             return __isMacOS = userAgent.includes('mac os x') || userAgent.includes('macintosh');
         }
     }
@@ -642,13 +651,13 @@ export namespace DeviceUtilities {
     /** @returns `true` for VisionOS devices */
     export function isVisionOS() {
         if (__isVisionOS !== undefined) return __isVisionOS;
-        return __isVisionOS = (isMacOS() && "xr" in navigator);
+        return __isVisionOS = (isiPad() && "xr" in navigator && supportsQuickLookAR());
     }
 
     let __isiOS: boolean | undefined;
     const iosDevices = ['iPad Simulator', 'iPhone Simulator', 'iPod Simulator', 'iPad', 'iPhone', 'iPod'];
 
-    /** @returns `true` for iOS devices like iPad, iPhone, iPod... */
+    /** @returns `true` for mobile Apple devices like iPad, iPhone, iPod, Vision Pro, ... */
     export function isiOS() {
         if (__isiOS !== undefined) return __isiOS;
         // eslint-disable-next-line deprecation/deprecation
@@ -725,6 +734,16 @@ export namespace DeviceUtilities {
         else __chromeVersion = null;
         return __chromeVersion;
     }
+
+    let __safariVersion: string | null | undefined;
+    export function getSafariVersion() {
+        if (__safariVersion !== undefined) return __safariVersion;
+        const match = navigator.userAgent.match(/Version\/(\d+\.\d+)/);
+        if (match && isSafari()) {
+            __safariVersion = match[1];
+        } else __safariVersion = null;
+        return __safariVersion;
+    }
 }
 
 /**

package/src/engine/extensions/extensions.ts

@@ -30,20 +30,44 @@ const KHR_ANIMATIONPOINTER_IMPORT = import("@needle-tools/three-animation-pointe
 });
 
 
-declare type OnImportCallback = (loader: GLTFLoader, url: string, context: Context) => void;
-declare type OnExportCallback = (exporter: GLTFExporter, context: Context) => void;
+/**
+ * Callback type for glTF import plugins. See {@link INeedleGLTFExtensionPlugin.onImport}
+ */
+export type OnImportCallback = (loader: GLTFLoader, url: string, context: Context) => void;
+
+/**
+ * Callback type for glTF export plugins. See {@link INeedleGLTFExtensionPlugin.onExport}
+ */
+export type OnExportCallback = (exporter: GLTFExporter, context: Context) => void;
 
 /**
- * Interface for registering custom glTF extensions to the Needle Engine GLTFLoaders. Register your plugin via {@link addCustomExtensionPlugin}
+ * Interface for registering custom glTF extensions to the Needle Engine GLTFLoaders.   
+ * Register your plugin using the {@link addCustomExtensionPlugin} method
  */
 export interface INeedleGLTFExtensionPlugin {
     /** The Name of your plugin */
     name: string;
-    /** Called before starting to load a glTF file. This callback can be used to add custom extensions to the GLTFLoader */
+    /** Called before starting to load a glTF file. This callback can be used to add custom extensions to the [GLTFLoader](https://threejs.org/docs/#GLTFLoader.register)  
+     * 
+     * @example Add a custom extension to the GLTFloader
+     * ```ts
+     * onImport: (loader, url, context) => {
+     *    loader.register((parser) => new MyCustomExtension(parser));
+     * }
+     * ```
+     */
     onImport?: OnImportCallback;
-    /** Called after the glTF has been loaded */
+    /** Called after a glTF file has been loaded */
     onLoaded?: (url: string, gltf: GLTF, context: Context) => void;
-    /** Called before starting to export a glTF file. This callback can be used to add custom extensions to the GLTFExporter */
+    /** Called before starting to export a glTF file. This callback can be used to add custom extensions to the [GLTFExporter](https://threejs.org/docs/#examples/en/exporters/GLTFExporter.register) 
+     * 
+     * @example Add a custom extension to the GLTFExporter
+     * ```ts
+     * onExport: (exporter, context) => {
+     *    exporter.register((writer) => new MyCustomExportExtension(writer));
+     * }
+     * 
+    */
     onExport?: OnExportCallback;
 }
 

package/src/engine/webcomponents/WebXRButtons.ts

@@ -57,13 +57,16 @@ export class WebXRButtonFactory {
         this._quicklookButton = button;
         button.dataset["needle"] = "quicklook-button";
         const supportsQuickLook = DeviceUtilities.supportsQuickLookAR();
+        let buttonText = "View in AR";
         // we can immediately enter this scene, because the platform supports rel="ar" links
-        if (supportsQuickLook) {
-            button.innerText = "View in AR";
+        if (DeviceUtilities.isVisionOS()) {
+            buttonText = "View in AR";
         }
-        else {
-            button.innerText = "View in AR";
+        else if (supportsQuickLook || DeviceUtilities.isiOS()) {
+            buttonText = "Open in Quicklook";
         }
+
+        button.innerText = buttonText;
         button.prepend(getIconElement("view_in_ar"));
 
         let createdExporter = false;
@@ -209,13 +212,20 @@ export class WebXRButtonFactory {
     }
 
     private updateSessionSupported(button: HTMLButtonElement, mode: XRSessionMode) {
+        if (mode === "immersive-ar" && DeviceUtilities.isiOS() && !DeviceUtilities.isVisionOS()) {
+            // on iOS, we can forward to the AppClip experience from the same button,
+            // so we always show the button. No AppClip support on VisionOS for now, so
+            // button state depends on WebXR support there.
+            return;
+        }
+
         if (!("xr" in navigator)) {
             button.style.display = "none";
             return;
         }
         NeedleXRSession.isSessionSupported(mode).then(supported => {
             button.style.display = !supported ? "none" : "";
-            if (isDevEnvironment() && !supported) console.log("[WebXR] \"" + mode + "\" is not supported on this device – make sure your server runs using HTTPS and you have a device connected that supports " + mode);
+            if (isDevEnvironment() && !supported) console.log("[WebXR] \"" + mode + "\" is not supported on this device. Make sure your server runs using HTTPS and you have a device connected that supports " + mode);
         });
     }
 

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -601,16 +601,15 @@ export class NeedleMenuElement extends HTMLElement {
             bottom: calc(100% + 5px);
             z-index: 100;
             width: auto;
-            left: .2rem;
-            right: .2rem;
-            padding: .2rem;
+            max-width: 90vw;
+            left: 50%;
+            transform: translateX(-50%);
+            padding: .2rem 1em;
 
         }
         .compact.logo-hidden .foldout {
             /** for when there's no logo we want to center the foldout **/
             min-width: 24ch;
-            margin-left: 50%;
-            transform: translateX(calc(-50% - .2rem));
         }
         
         .compact.top .foldout {

package/src/engine/webcomponents/needle-engine.ar-overlay.ts

@@ -118,6 +118,12 @@ export class AROverlayHandler {
     }
 
     private ensureQuitARButton(element: HTMLElement) {
+
+        // No quit button in app clips, we provide one via the native UI
+        if (DeviceUtilities.isNeedleAppClip()) {
+            return;
+        }
+
         const quitARSlot = document.createElement("slot");
         quitARSlot.setAttribute("name", "quit-ar");
         this.appendElement(quitARSlot, element);

package/src/engine/webcomponents/needle-engine.ts

@@ -356,7 +356,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             case "loadfinished":
                 if (typeof newValue === "string" && newValue.length > 0) {
                     if (debug) console.log(name + " attribute changed", newValue);
-                    this.registerEventFromAttribute("loadfinished", newValue);
+                    this.registerEventFromAttribute(name, newValue);
                 }
                 break;
             case "dracoDecoderPath":
@@ -708,7 +708,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (attributeValue)
             this.registerEventFromAttribute("loadstart", attributeValue);
     }
-    private registerEventFromAttribute(eventName: 'loadfinished' | 'loadstart', code: string) {
+    private registerEventFromAttribute(eventName: 'loadfinished' | 'loadstart' | 'progress', code: string) {
         const prev = this._previouslyRegisteredMap.get(eventName);
         if (prev) {
             this._previouslyRegisteredMap.delete(eventName);

package/src/engine/xr/NeedleXRSession.ts

@@ -82,6 +82,34 @@ function getDOMOverlayElement(domElement: HTMLElement) {
 handleSessionGranted();
 async function handleSessionGranted() {
 
+    // await delay(400);
+
+
+    let defaultMode: XRSessionMode = "immersive-vr";
+
+    try {
+        // In app clips we default to AR
+        if (DeviceUtilities.isNeedleAppClip()) {
+            defaultMode = "immersive-ar";
+        }
+        // Check if VR is even supported, otherwise try AR
+        else if (!(await navigator.xr?.isSessionSupported("immersive-vr"))) {
+            defaultMode = "immersive-ar";
+        }
+        // Check if AR is supported, otherwise we can't do anything
+        if (!(await navigator.xr?.isSessionSupported("immersive-ar")) && defaultMode === "immersive-ar") {
+            console.warn("[NeedleXRSession:granted] Neither VR nor AR supported, aborting session start.");
+            // showBalloonMessage("NeidleXRSession: Neither VR nor AR supported, aborting session start.");
+            return;
+        }
+    } catch (e) {
+        console.error("[NeedleXRSession:granted] Error while checking XR support:", e);
+        // showBalloonWarning("NeedleXRSession: Error while checking XR support: " + (e as Error).message);
+        return;
+    }
+
+    // showBalloonMessage("sessiongranted: " + defaultMode);
+
     // TODO: asap session granted doesnt handle the pre-room yet
     if (getParam("debugasap")) {
         let asapSession = globalThis["needle:XRSession"] as XRSession | undefined | Promise<XRSession>;
@@ -94,11 +122,11 @@ async function handleSessionGranted() {
                 enableSpatialConsole(true);
                 const session = await asapSession;
                 if (session) {
-                    const sessionInit = NeedleXRSession.getDefaultSessionInit("immersive-vr");
-                    NeedleXRSession.setSession("immersive-vr", session, sessionInit, cb.context);
+                    const sessionInit = NeedleXRSession.getDefaultSessionInit(defaultMode);
+                    NeedleXRSession.setSession(defaultMode, session, sessionInit, cb.context);
                 }
                 else {
-                    console.error("NeedleXRSession: ASAP session was rejected");
+                    console.error("[NeedleXRSession:granted] ASAP session was rejected");
                 }
                 asapSession = undefined;
             });
@@ -106,6 +134,9 @@ async function handleSessionGranted() {
         }
     }
 
+    // console.log("Attaching sessiongranted handler...", { haveXR: 'xr' in navigator });
+    // setTimeout(() => console.log("Session Granted handler attached.", { haveXR: 'xr' in navigator }), 1000);
+
     if ('xr' in navigator) {
         // WebXRViewer (based on Firefox) has a bug where addEventListener
         // throws a silent exception and aborts execution entirely.
@@ -115,10 +146,7 @@ async function handleSessionGranted() {
         }
 
         navigator.xr?.addEventListener('sessiongranted', async () => {
-            enableSpatialConsole(true);
-
-            console.log("Received Session Granted...")
-            await delay(100);
+            // enableSpatialConsole(true);
 
             const lastSessionMode = sessionStorage.getItem("needle_xr_session_mode") as XRSessionMode;
             const lastSessionInit = sessionStorage.getItem("needle_xr_session_init") ?? null;
@@ -126,7 +154,8 @@ async function handleSessionGranted() {
 
             let info: SessionInfo | null = null;
             if (contextIsLoading()) {
-                await TemporaryXRContext.start(lastSessionMode || "immersive-vr", init || NeedleXRSession.getDefaultSessionInit("immersive-vr"));
+                await TemporaryXRContext.start(lastSessionMode || defaultMode, init || NeedleXRSession.getDefaultSessionInit(defaultMode))
+                    .catch(e => console.warn("[NeedleXRSession:granted] TemporaryXRContext start failed:", e));
                 await waitForContextLoadingFinished();
                 info = await TemporaryXRContext.handoff();
             }
@@ -134,17 +163,19 @@ async function handleSessionGranted() {
                 NeedleXRSession.setSession(info.mode, info.session, info.init, Context.Current);
             }
             else if (lastSessionMode && lastSessionInit) {
-                console.log("Session Granted: Restore last session")
+                console.log("[NeedleXRSession:granted] Restore last session")
                 const init = JSON.parse(lastSessionInit);
                 NeedleXRSession.start(lastSessionMode as XRSessionMode, init).catch(e => console.warn(e));
             }
             else {
                 // if no session was found we start VR by default
-                NeedleXRSession.start("immersive-vr").catch(e => console.warn("Session Granted failed:", e));
+                NeedleXRSession.start(defaultMode).catch(e => console.warn("[NeedleXRSession:granted] failed:", e));
             }
             // make sure we only subscribe to the event once
         }, { once: true });
-
+    }
+    else {
+        // showBalloonWarning("NeedleXRSession: WebXR not available in this browser.");
     }
 }
 function saveSessionInfo(mode: XRSessionMode, init: XRSessionInit) {
@@ -419,28 +450,48 @@ export class NeedleXRSession implements INeedleXRSession {
      * @param init The XRSessionInit to use (optional), docs: https://developer.mozilla.org/en-US/docs/Web/API/XRSessionInit
      * @param context The Needle Engine context to use
      */
-    static async start(mode: XRSessionMode | "ar", init?: XRSessionInit, context?: Context): Promise<NeedleXRSession | null> {
+    static async start(mode: XRSessionMode | "ar" | "quicklook", init?: XRSessionInit, context?: Context): Promise<NeedleXRSession | null> {
 
-        // handle iOS platform where "immersive-ar" is not supported
+        // handle iOS platform where "immersive-ar" is special:
+        // - we either launch QuickLook
+        // - or forward to the Needle App Clip experience for WebXR AR
         // TODO: should we add a separate mode (e.g. "AR")? https://linear.app/needle/issue/NE-5303
         if (DeviceUtilities.isiOS()) {
-            if (mode === "ar") {
-                const arSupported = await this.isARSupported();
-                if (!arSupported) {
-                    InternalUSDZRegistry.exportAndOpen();
-                    return null;
-                }
-                else {
-                    mode = "immersive-ar";
-                }
+
+            const arSupported = await this.isARSupported().catch(() => false);
+            
+            // On VisionOS, we use QuickLook for AR experiences; no AppClip support for now.
+            if (DeviceUtilities.isVisionOS() && !arSupported && (mode === "ar" || mode === "immersive-ar")) {
+                mode = "quicklook";
+            }
+
+            if (mode === "quicklook") {
+                InternalUSDZRegistry.exportAndOpen();
+                return null;
             }
+            
+            if (!arSupported && (mode === "immersive-ar" || mode === "ar")) {
+                // Forward to the AppClip experience
+                // const url = `https://appclip.apple.com/id?p=tools.needle.launch-app.Clip&url=${encodeURIComponent(location.href)}` 
+                const url =`https://appclip.needle.tools/ar?url=${encodeURIComponent(location.href)}`;
+                console.debug("iOS device detected - opening Needle App Clip for AR experience", url, { mode, init });
+                // navigate to app clip url but keep the current url in history, open in same tab
+                window.location.href = url;
+
+                return null;
+            }
+        }
+
+        if (mode === "quicklook") {
+            console.warn("QuickLook mode is only supported on iOS devices");
+            return null;
         }
-        else if (mode == "ar") {
+        
+        // Since we now know we are not on iOS, ar mode becomes "immersive-ar"
+        if (mode == "ar") {
             mode = "immersive-ar";
         }
 
-
-
         if (isDevEnvironment() && getParam("debugxrpreroom")) {
             console.warn("Debug: Starting temporary XR session");
             await TemporaryXRContext.start(mode, init || NeedleXRSession.getDefaultSessionInit(mode));
@@ -539,8 +590,8 @@ export class NeedleXRSession implements INeedleXRSession {
         this._currentSessionRequestMode = mode;
         /**@type {XRSystem} */
         const newSession = await (this._currentSessionRequest)?.catch(e => {
-            console.error(e, "Code: " + e.code);
-            if (e.code === 9) showBalloonWarning("Make sure your device has the required permissions (e.g. camera access)")
+            console.error(e, "Code: " + e?.code);
+            if (e?.code === 9) showBalloonWarning("Couldn't start XR session. Make sure you allow the required permissions.")
             console.log("If the specified XR configuration is not supported (e.g. entering AR doesnt work) - make sure you access the website on a secure connection (HTTPS) and your device has the required permissions (e.g. camera access)");
             const notSecure = location.protocol === 'http:';
             if (notSecure) showBalloonWarning("XR requires a secure connection (HTTPS)");

package/src/engine/xr/TempXRContext.ts

@@ -32,7 +32,13 @@ export class TemporaryXRContext {
                 return null;
             }
             this._requestInFlight = true;
-            const session = await navigator.xr.requestSession(mode, init);
+            const session = await navigator.xr.requestSession(mode, init).catch(err => {
+                console.error("Failed to start temporary XR session:", err);
+            });
+            if (!session) {
+                this._requestInFlight = false;
+                return null;
+            }
             session.addEventListener("end", () => {
                 this._active = null;
             });
@@ -82,10 +88,14 @@ export class TemporaryXRContext {
         this._session = session;
         this._session.addEventListener("end", this.onEnd);
 
-        this._renderer = new WebGLRenderer({ alpha: true });
+        this._renderer = new WebGLRenderer({ alpha: true, antialias: true }); 
+        this._renderer.outputColorSpace = 'srgb';
         this._renderer.setAnimationLoop(this.onFrame);
         this._renderer.xr.setSession(session);
         this._renderer.xr.enabled = true;
+        // Set pixel ratio and size
+        this._renderer.setPixelRatio(Math.min(2, window.devicePixelRatio));
+        this._renderer.setSize(window.innerWidth, window.innerHeight);
         this._camera = new PerspectiveCamera();
         this._scene = new Scene();
         this._scene.fog = new Fog(0x444444, 10, 250);

package/src/engine/xr/usdz.ts

@@ -1,3 +1,4 @@
+import { isDevEnvironment } from "../debug/index.js";
 
 declare type USDZExporter = {
     exportAndOpen(): Promise<any>,
@@ -11,7 +12,11 @@ export namespace InternalUSDZRegistry {
     const usdzExporter: USDZExporter[] = [];
 
     export function exportAndOpen(): boolean {
-        if (!usdzExporter?.length) return false;
+        if (!usdzExporter?.length) {
+            if (isDevEnvironment()) {
+                console.warn("No USDZ exporters found – cannot export USDZ for QuickLook.");
+            }
+        }
         for (const exp of usdzExporter) {
             exp.exportAndOpen();
         }

package/src/engine-components/AlignmentConstraint.ts

@@ -9,7 +9,7 @@ import { Behaviour, GameObject } from "./Component.js";
  * You can use this to create dynamic beams or connectors between objects.
  *
  * @summary Aligns and scales the object between two target GameObjects
- * @category Utility
+ * @category Constraints
  * @group Components 
  **/
 export class AlignmentConstraint extends Behaviour {

package/src/engine-components/Animation.ts

@@ -60,7 +60,7 @@ class Vec2 { x!: number; y!: number }
 /**
  * Animation component to play animations on a GameObject.
  * 
- * @summary Play animations
+ * @summary Plays animations from AnimationClips 
  * @category Animation and Sequencing
  * @group Components
  */

package/src/engine-components/Animator.ts

@@ -43,7 +43,7 @@ export declare class PlayOptions {
  * It works with an {@link AnimatorController} to handle state transitions and animation blending.
  * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
  * 
- * @summary Animation controller and playback component
+ * @summary Plays and manages animations on a GameObject based on an AnimatorController
  * @category Animation and Sequencing
  * @group Components
 */

package/src/engine-components/AudioListener.ts

@@ -9,7 +9,7 @@ import { Behaviour, GameObject } from "./Component.js";
  * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
  * to the main camera or a Camera in the parent hierarchy.
  * 
- * @summary Audio listener for 3D audio capture
+ * @summary Receives audio in the scene and outputs it to speakers
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/AudioSource.ts

@@ -52,7 +52,7 @@ export enum AudioRolloffMode {
  * is muted, the volume is set to 0. When unmuted, the volume
  * returns to its previous value.
  * 
- * @summary 3D audio source with spatial positioning and playback controls
+ * @summary Plays audio clips from files or media streams
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/Camera.ts

@@ -37,7 +37,7 @@ const debugscreenpointtoray = getParam("debugscreenpointtoray");
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  * 
  * @summary Rendering scenes from a specific viewpoint
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  */
 export class Camera extends Behaviour implements ICamera {