@needle-tools/engine 4.12.0-next.ca2cebd → 4.12.0-next.dcaf2b0

package/src/engine/engine_license.ts

@@ -1,9 +1,14 @@
+import { dof } from "three/src/nodes/TSL.js";
+
 import { isDevEnvironment } from "./debug/index.js";
 import { BUILD_TIME, GENERATOR, PUBLIC_KEY, VERSION } from "./engine_constants.js";
 import { ContextEvent, ContextRegistry } from "./engine_context_registry.js";
+import { onInitialized } from "./engine_lifecycle_api.js";
+import { isLocalNetwork } from "./engine_networking_utils.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 +72,174 @@ function invokeLicenseCheckResultChanged(result: boolean) {
     }
 }
 
+
+
+// #region Telemetry
+export namespace Telemetry {
+
+    window.addEventListener("error", (event: ErrorEvent) => {
+        sendError(Context.Current, "unhandled_error", event);
+    });
+    window.addEventListener("unhandledrejection", (event: PromiseRejectionEvent) => {
+        sendError(Context.Current, "unhandled_promise_rejection", {
+            message: event.reason?.message,
+            stack: event.reason?.stack,
+            timestamp: Date.now(),
+        });
+    });
+
+    onInitialized((ctx => sendPageViewEvent(ctx)), { once: true });
+
+    function sendPageViewEvent(ctx: IContext) {
+        if (!isAllowed(ctx)) {
+            if (debug) console.debug("Telemetry is disabled via no-telemetry attribute");
+            return;
+        }
+        return doFetch({
+            site_id: "dabb8317376f",
+            type: "pageview",
+            pathname: window.location.pathname,
+            hostname: window.location.hostname,
+            page_title: document.title,
+            referrer: document.referrer,
+            user_agent: navigator.userAgent,
+            querystring: window.location.search,
+            language: navigator.language,
+            screenWidth: window.screen.width,
+            screenHeight: window.screen.height,
+            event_name: "page_view"
+        }).then(res => {
+            if (res instanceof Response && res.ok && isLocalNetwork()) {
+                const src = ctx.domElement?.getAttribute("src") || "";
+                const sessionKey = src + VERSION + GENERATOR + BUILD_TIME + PUBLIC_KEY;
+                if (window.sessionStorage.getItem("session_key") !== sessionKey) {
+                    window.sessionStorage.setItem("session_key", sessionKey);
+                    sendEvent(ctx, "info", {
+                        src: ctx.domElement?.getAttribute("src") || "",
+                        version: VERSION,
+                        generator: GENERATOR,
+                        build_time: BUILD_TIME,
+                        public_key: PUBLIC_KEY,
+                    });
+                }
+            }
+        })
+    }
+
+    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;
+    }
+
+    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",
+            event_name: errorName || "error",
+            properties: JSON.stringify({
+                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 +254,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 +514,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 +539,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 +547,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

@@ -6,6 +6,7 @@ import { type Websocket } from 'websocket-ts';
 
 import * as schemes from "../engine-schemes/schemes.js";
 import { isDevEnvironment } from './debug/index.js';
+import { Telemetry } from './engine_license.js';
 import { PeerNetworking } from './engine_networking_peer.js';
 import { type IModel, type INetworkConnection, SendQueue } from './engine_networking_types.js';
 import { isHostedOnGlitch } from './engine_networking_utils.js';
@@ -629,7 +630,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 +642,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 +657,13 @@ export class NetworkConnection implements INetworkConnection {
                     console.error(msg);
                 })
                 .onError((_e) => {
-                    console.error("⊠ Websocket connection failed...");
+                    console.error("Websocket connection failed...");
                     resolve(false);
+                    Telemetry.sendEvent(this.context, "networking", {
+                        event: "connection_error",
+                    });
                 })
-                .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);
@@ -727,6 +731,9 @@ export class NetworkConnection implements INetworkConnection {
                                 "server did not send connection id", connection.id);
                             console.debug("Your id is: " + connection.id, this.context.alias ?? "");
                             this._connectionId = connection.id;
+                            Telemetry.sendEvent(this.context, "networking", {
+                                event: "connected",
+                            });
                         }
                     }
                     else console.warn("Expected connection id in " + message.key);
@@ -754,6 +761,10 @@ export class NetworkConnection implements INetworkConnection {
                     }
 
                     this.onSendQueued(SendQueue.OnRoomJoin);
+                    Telemetry.sendEvent(this.context, "networking", {
+                        event: "joined_room",
+                        room: this._currentRoomName,
+                    });
                     break;
 
                 case RoomEvents.LeftRoom:
@@ -765,6 +776,10 @@ export class NetworkConnection implements INetworkConnection {
                         this._currentInRoom.length = 0;
                         if (debugnetBin || isDevEnvironment()) console.debug("Left Needle Engine Room: " + model.room);
                     }
+                    Telemetry.sendEvent(this.context, "networking", {
+                        event: "left_room",
+                        room: model.room,
+                    });
                     break;
                 case RoomEvents.UserJoinedRoom:
                     if (message.data) {

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

@@ -242,8 +242,10 @@ export function setWorldPosition(obj: Object3D, val: Vector3): Object3D {
     const wp = _worldPositions.get();
     if (val !== wp)
         wp.copy(val);
-    const obj2 = obj?.parent ?? obj;
-    obj2.worldToLocal(wp);
+
+    if (obj.parent !== null)
+         obj.parent.worldToLocal(wp);
+
     obj.position.set(wp.x, wp.y, wp.z);
     return obj;
 }

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

@@ -104,7 +104,8 @@ export class NeedleSpatialMenu {
         }
 
         const xr = this._context.xr;
-        if (!xr?.running) {
+        const isImmersiveXR = xr?.running && (xr?.isPassThrough || xr?.isVR)
+        if (!isImmersiveXR) {
             if (this._wasInXR) {
                 this._wasInXR = false;
                 this.onExitXR();

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

@@ -1,5 +1,5 @@
 import type { Context } from "../../engine_context.js";
-import { hasCommercialLicense, onLicenseCheckResultChanged } from "../../engine_license.js";
+import { hasCommercialLicense, onLicenseCheckResultChanged, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
 import { DeviceUtilities, getParam } from "../../engine_utils.js";
 import { onXRSessionStart, XRSessionEventArgs } from "../../xr/events.js";
@@ -149,6 +149,9 @@ export class NeedleMenu {
                             else console.error("NeedleMenu: onclick is not a valid link", buttoninfo.onclick);
                         }
                     }
+                    Telemetry.sendEvent(this._context, "needle-menu", {
+                        action: "button_added_via_postmessage",
+                    });
                     this._menu.appendChild(button);
                 }
                 else if (debug) console.error("NeedleMenu: unknown postMessage event", data);
@@ -601,16 +604,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 {
@@ -936,12 +938,39 @@ export class NeedleMenuElement extends HTMLElement {
     /** @private foldout container used in compact mode */
     private readonly foldout: HTMLDivElement;
 
+
+    private readonly trackedElements: WeakSet<Node> = new WeakSet();
+    private trackElement(el: Node) {
+        if (this.trackedElements.has(el)) return;
+        this.trackedElements.add(el);
+        el.addEventListener("click", (evt) => {
+            Telemetry.sendEvent(this._context, "needle-menu", {
+                action: "button_clicked",
+                element: evt.target instanceof Node ? evt.target.nodeName : el.nodeName,
+                label: el.textContent,
+                title: (el instanceof HTMLElement) ? el.title : undefined,
+                pointerid: (evt instanceof PointerEvent) ? evt.pointerId : undefined,
+            });
+        });
+        // el.addEventListener("pointerenter", (evt) => {
+        //     Telemetry.sendEvent(this._context, "needle-menu", {
+        //         action: "button_hovered",
+        //         element: evt.target instanceof Node ? evt.target.nodeName : el.nodeName,
+        //         label: el.textContent,
+        //         title: (el instanceof HTMLElement) ? el.title : undefined,
+        //         pointerid: (evt instanceof PointerEvent) ? evt.pointerId : undefined,
+        //     });
+        // });
+    }
+
     append(...nodes: (string | Node)[]): void {
         for (const node of nodes) {
             if (typeof node === "string") {
                 const element = document.createTextNode(node);
+                this.trackElement(element);
                 this.options.appendChild(element);
             } else {
+                this.trackElement(node);
                 this.options.appendChild(node);
             }
         }
@@ -988,9 +1017,10 @@ export class NeedleMenuElement extends HTMLElement {
             if (node.class) {
                 button.classList.add(node.class);
             }
+
             node = button as unknown as T;
         }
-
+        this.trackElement(node);
         const res = this.options.appendChild(node);
         return res;
     }
@@ -998,8 +1028,10 @@ export class NeedleMenuElement extends HTMLElement {
         for (const node of nodes) {
             if (typeof node === "string") {
                 const element = document.createTextNode(node);
+                this.trackElement(element);
                 this.options.prepend(element);
             } else {
+                this.trackElement(node);
                 this.options.prepend(node);
             }
         }