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

package/src/engine/engine_context.ts

@@ -43,6 +43,7 @@ import { deepClone, delay, DeviceUtilities, getParam } from './engine_utils.js';
 import type { INeedleXRSessionEventReceiver, NeedleXRSession } from './engine_xr.js';
 import { NeedleMenu } from './webcomponents/needle menu/needle-menu.js';
 import type { NeedleEngineWebComponent } from './webcomponents/needle-engine.js';
+import { Telemetry } from './engine_license.js';
 
 const debug = getParam("debugcontext");
 const stats = getParam("stats");
@@ -1403,6 +1404,7 @@ export class Context implements IContext {
 				if (this._renderlooperrors >= 3) {
 					console.warn("Stopping render loop due to error")
 					this.renderer.setAnimationLoop(null);
+					Telemetry.sendError(Context.Current, "renderloop", err instanceof Error ? err : new Error(String(err)) );
 				}
 				this.domElement.dispatchEvent(new CustomEvent("error", { detail: err }));
 			}

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

@@ -4,6 +4,7 @@ import { ContextEvent, ContextRegistry } from "./engine_context_registry.js";
 import { Context } from "./engine_setup.js";
 import type { IContext } from "./engine_types.js";
 import { getParam } from "./engine_utils.js";
+import { InternalAttributeUtils } from "./engine_utils_attributes.js";
 
 const debug = getParam("debuglicense");
 
@@ -67,6 +68,126 @@ function invokeLicenseCheckResultChanged(result: boolean) {
     }
 }
 
+
+
+export namespace Telemetry {
+
+    export function isAllowed(context: IContext | null | undefined): boolean {
+        let domElement = context?.domElement as HTMLElement | null;
+        if (!domElement) domElement = document.querySelector<HTMLElement>("needle-engine");
+        if (!domElement && !context) return false;
+
+        const attribute = domElement?.getAttribute("no-telemetry");
+        if (attribute === "" || attribute === "true" || attribute === "1") {
+            if (NEEDLE_ENGINE_LICENSE_TYPE === "pro" || NEEDLE_ENGINE_LICENSE_TYPE === "enterprise") {
+                if (debug) console.debug("Telemetry is disabled via no-telemetry attribute");
+                return false;
+            }
+        }
+        return true;
+    }
+
+    const id = "dabb8317376f";
+
+    /**
+     * Sends a telemetry event
+     */
+    export async function sendEvent(context: IContext | null | undefined, eventName: string, properties?: Record<string, any>) {
+        if (!isAllowed(context)) {
+            if (debug) console.debug("Telemetry is disabled");
+            return;
+        }
+        const body = {
+            site_id: id,
+            type: "custom_event",
+            pathname: window.location.pathname,
+            event_name: eventName,
+            properties: properties ? JSON.stringify(properties) : undefined,
+        }
+        return doFetch(body);
+    }
+
+    type ErrorData = {
+        message?: string;
+        stack?: string;
+        filename?: string;
+        lineno?: number;
+        colno?: number;
+        timestamp?: number;
+    }
+    function isErrorData(obj: any): obj is ErrorData {
+        return obj && (typeof obj.message === "string" || typeof obj.stack === "string");
+    }
+
+    export async function sendError(context: IContext, errorName: string, error: ErrorData | ErrorEvent | Error) {
+
+        if (!isAllowed(context)) {
+            if (debug) console.debug("Telemetry is disabled");
+            return;
+        }
+
+        if (error instanceof ErrorEvent) {
+            error = {
+                message: error.message,
+                stack: error.error?.stack,
+                filename: error.filename,
+                lineno: error.lineno,
+                colno: error.colno,
+                timestamp: error.timeStamp || Date.now(),
+
+            };
+        }
+        else if (error instanceof Error) {
+            error = {
+                message: error.message,
+                stack: error.stack,
+                timestamp: Date.now(),
+            };
+        }
+        const body = {
+            site_id: id,
+            type: "error",
+            properties: {
+                error_name: errorName,
+                message: error.message,
+                stack: error.stack,
+                filename: error.filename,
+                lineno: error.lineno,
+                colno: error.colno,
+                timestamp: error.timestamp,
+            }
+        }
+        return doFetch(body);
+    }
+
+    function doFetch(body: Record<string, any>) {
+        try {
+            const url = "https://needle.tools/api/v1/rum/t";
+            return fetch(url, {
+                method: "POST",
+                body: JSON.stringify(body),
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                // Ensures request completes even if page unloads
+                keepalive: true,
+                // Allow CORS requests
+                mode: 'cors',
+                // Low priority to avoid blocking other requests
+                // @ts-ignore
+                priority: 'low',
+            }).catch(e => {
+                if (debug) console.error("Failed to send telemetry", e);
+            })
+        }
+        catch (err) {
+            if (debug) console.error(err);
+        }
+        return Promise.resolve();
+    }
+}
+
+
 ContextRegistry.registerCallback(ContextEvent.ContextRegistered, evt => {
     showLicenseInfo(evt.context);
     handleForbidden(evt.context);
@@ -81,7 +202,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 => {
@@ -341,28 +462,18 @@ async function sendUsageMessageToAnalyticsBackend(context: IContext) {
     // We can't send beacons from cross-origin isolated pages
     if (window.crossOriginIsolated) return;
 
-    const licenseType = NEEDLE_ENGINE_LICENSE_TYPE;
-    if (licenseType === "pro" || licenseType === "enterprise") {
-        const attribute = context?.domElement?.getAttribute("no-telemetry");
-        if (attribute === "" || attribute === "true" || attribute === "1") {
-            if (debug) console.debug("Telemetry is disabled");
-            return;
-        }
-        if (debug) console.debug("Telemetry attribute: " + attribute);
+    if (!Telemetry.isAllowed(context)) {
+        if (debug) console.debug("Telemetry is disabled via no-telemetry attribute");
+        return;
     }
 
     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 +487,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);
         }
     }
@@ -384,4 +495,4 @@ async function sendUsageMessageToAnalyticsBackend(context: IContext) {
         if (debug)
             console.log("Failed to send non-commercial usage message to analytics backend", err);
     }
-}
+}

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_serialization_builtin_serializer.ts

@@ -337,7 +337,7 @@ class EventListSerializer extends TypeSerializer {
                             args = call.arguments.map(deserializeArgument);
                         }
                         const method = target[call.method];
-                        if (!method) {
+                        if (method === undefined) {
                             console.warn(`EventList method not found: \"${call.method}\" on ${target?.name}`);
                         }
                         else {

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);