@needle-tools/engine 5.1.0-alpha → 5.1.0-canary.30cc545

package/src/engine/engine_init.ts

@@ -12,6 +12,7 @@ import { patchLayers } from "./js-extensions/Layers.js";
 import { initObject3DExtensions } from "./js-extensions/Object3D.js";
 import { initVectorExtensions } from "./js-extensions/Vector.js";
 import { initWebComponents } from "./webcomponents/init.js";
+import { initPhysics } from "./engine_physics_rapier.js";
 import { initXR } from "./xr/init.js";
 
 let initialized = false;
@@ -43,5 +44,6 @@ export function initEngine() {
     initAnimationAutoplay();
     initSkyboxAttributes();
     initSceneSwitcherAttributes();
+    initPhysics();
     initXR();
 }

package/src/engine/engine_input.ts

@@ -1,6 +1,7 @@
 import { Intersection, Matrix4, Object3D, Ray, Vector2, Vector3 } from 'three';
 
 import { showBalloonMessage, showBalloonWarning } from './debug/debug.js';
+import { PointerEventBase, KeyboardEventBase } from './engine_ssr.js';
 import { Context } from './engine_setup.js';
 import { getTempVector, getWorldQuaternion } from './engine_three_utils.js';
 import type { ButtonName, CursorTypeName, IGameObject, IInput, MouseButtonName, Vec2 } from './engine_types.js';
@@ -116,7 +117,7 @@ export declare type NEPointerEventIntersection = Intersection & { event?: NEPoin
  * @see {@link Input} for the input management system
  * @see {@link PointerType} for available pointer types
  */
-export class NEPointerEvent extends PointerEvent {
+export class NEPointerEvent extends PointerEventBase {
 
     /**
      * Spatial input data
@@ -242,7 +243,7 @@ export class NEPointerEvent extends PointerEvent {
         if (debug) console.warn("Stop propagation...", this.pointerId, this.pointerType)
     }
 }
-export class NEKeyboardEvent extends KeyboardEvent {
+export class NEKeyboardEvent extends KeyboardEventBase {
     source?: Event
     constructor(type: InputEvents, source: Event, init: KeyboardEventInit) {
         super(type, init)

package/src/engine/engine_license.ts

@@ -77,16 +77,18 @@ 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(),
+    if (typeof window !== "undefined") {
+        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 });
 

package/src/engine/engine_networking_blob.ts

@@ -1,11 +1,9 @@
-import * as _md5 from "md5";
-// CJS interop: md5 may appear as { default: fn } or fn depending on bundler
-const md5 = typeof _md5 === "function" ? _md5 : (_md5 as any).default;
 import { FileLoader } from "three";
 
 import { showBalloonWarning } from "./debug/index.js";
 import { hasCommercialLicense } from "./engine_license.js";
 import { delay } from "./engine_utils.js";
+import { md5Hex, md5AsBytes, sha256Base64 } from "./engine_utils_hash.js";
 
 
 export namespace BlobStorage {
@@ -22,21 +20,17 @@ export namespace BlobStorage {
     /**
      * Generates an md5 hash from a given buffer
      * @param buffer The buffer to hash
-     * @returns The md5 hash
+     * @returns The md5 hash as a hex string
      */
     export function hashMD5(buffer: ArrayBuffer): string {
-        return md5(new Uint8Array(buffer))
+        return md5Hex(new Uint8Array(buffer));
     }
     export function hashMD5_Base64(buffer: ArrayBuffer): string {
-        const bytes = md5(new Uint8Array(buffer), { encoding: "binary", asBytes: true });
+        const bytes = md5AsBytes(new Uint8Array(buffer));
         return btoa(String.fromCharCode(...bytes));
     }
     export function hashSha256(buffer: ArrayBuffer): Promise<string> {
-        const bytes = new Uint8Array(buffer);
-        const hash = crypto.subtle.digest('SHA-256', bytes).then(res => {
-            return btoa(String.fromCharCode(...new Uint8Array(res)));
-        })
-        return hash;
+        return sha256Base64(buffer);
     }
 
     export type Upload_Result = {

package/src/engine/engine_physics_rapier.ts

@@ -44,18 +44,20 @@ const $bodyKey = Symbol("physics body");
 const $colliderRigidbody = Symbol("rigidbody");
 
 
-declare const NEEDLE_USE_RAPIER: boolean;
-globalThis["NEEDLE_USE_RAPIER"] = globalThis["NEEDLE_USE_RAPIER"] !== undefined ? globalThis["NEEDLE_USE_RAPIER"] : true;
-if (debugPhysics)
-    console.log("Use Rapier", NEEDLE_USE_RAPIER, globalThis["NEEDLE_USE_RAPIER"])
-
-if (NEEDLE_USE_RAPIER) {
-    ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, evt => {
-        if (debugPhysics)
-            console.log("Register rapier physics backend")
-        evt.context.physics.engine = new RapierPhysics(evt.context);
-        // We do not initialize physics immediately to avoid loading the physics engine if it is not needed
-    });
+/** Register the Rapier physics backend. Called from {@link initEngine}
+ * to ensure it runs regardless of tree-shaking. */
+export function initPhysics() {
+    if (debugPhysics)
+        console.log("Use Rapier", NEEDLE_USE_RAPIER, globalThis["NEEDLE_USE_RAPIER"])
+
+    if (NEEDLE_USE_RAPIER) {
+        ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, evt => {
+            if (debugPhysics)
+                console.log("Register rapier physics backend")
+            evt.context.physics.engine = new RapierPhysics(evt.context);
+            // We do not initialize physics immediately to avoid loading the physics engine if it is not needed
+        });
+    }
 }
 
 

package/src/engine/engine_pmrem.ts

@@ -1,8 +1,8 @@
 import { createLoaders } from "@needle-tools/gltf-progressive";
 import { CubeUVReflectionMapping, EquirectangularRefractionMapping, SRGBColorSpace, Texture, TextureLoader, WebGLRenderer } from "three";
-import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader";
-import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader";
-import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader";
+import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
+import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
 
 const running: Map<string, Promise<Texture | null>> = new Map();
 

package/src/engine/engine_scenedata.ts

@@ -0,0 +1,110 @@
+import type { SceneData } from "needle:bindings";
+import type { IContext } from "./engine_types.js";
+import { getComponent } from "./engine_components.js";
+import { TypeStore } from "./engine_typestore.js";
+import { isDevEnvironment } from "./debug/index.js";
+import { ContextRegistry } from "./engine_context_registry.js";
+
+/**
+ * Global proxy for the primary Needle Engine context.
+ * Resolves lazily on property access via `ContextRegistry.Current` —
+ * safe to import at module level, including in SSR environments
+ * (returns a silent error proxy when no context is active).
+ *
+ * Use this outside of Needle component lifecycle (e.g. in Svelte/React/Vue
+ * components, button handlers, or vanilla JS) instead of threading `ctx` around.
+ *
+ * For multiple `<needle-engine>` elements on the same page, use `ctx` directly.
+ *
+ * @example
+ * import { needle } from "@needle-tools/engine";
+ * button.onclick = () => {
+ *   needle.sceneData.Camera.OrbitControls.autoRotate = true;
+ * };
+ */
+export const needle: IContext = new Proxy({} as IContext, {
+    get(_target, prop: string) {
+        if (prop === "then") return undefined; // not a Promise
+        const ctx = ContextRegistry.Current;
+        if (!ctx) {
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[needle] needle.${prop} accessed before scene started`);
+            return makeErrorProxy(`needle not ready — scene hasn't started yet`);
+        }
+        const val = (ctx as any)[prop];
+        return typeof val === "function" ? val.bind(ctx) : val;
+    },
+    set(_target, prop: string, value: unknown) {
+        const ctx = ContextRegistry.Current;
+        if (!ctx) {
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[needle] needle.${prop} set before scene started`);
+            return true;
+        }
+        (ctx as any)[prop] = value;
+        return true;
+    },
+});
+
+const cache = new WeakMap<IContext, SceneData>();
+
+/**
+ * Returns a proxy that silently absorbs any property get/set and logs a
+ * developer-friendly warning. Used when a node or component lookup fails so
+ * that chained access like `ctx.sceneData.Foo.Bar.baz = 1` never throws.
+ */
+function makeErrorProxy(message: string): object {
+    const handler: ProxyHandler<object> = {
+        get(_t, prop: string) {
+            if (prop === "then") return undefined; // not a Promise
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[SceneData] ${message}`);
+            return makeErrorProxy(message);
+        },
+        set(_t, prop: string) {
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[SceneData] ${message} (tried to set "${prop}")`);
+            return true; // suppress TypeError
+        },
+    };
+    return new Proxy({}, handler);
+}
+
+/**
+ * Returns a lazily-resolved proxy typed as {@link SceneData}.
+ * The proxy is cached per context — each context gets exactly one instance.
+ *
+ * Accessing a property traverses the scene graph on demand:
+ * - First level  → find Object3D by node name
+ * - Second level → getComponent by component name (via TypeStore)
+ * - Third level  → read/write a field on the real component instance
+ *
+ * If a node or component is not found, property accesses log a warning
+ * instead of throwing, so chained access never crashes.
+ *
+ * @example
+ * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+ */
+export function getSceneData(ctx: IContext): SceneData {
+    let proxy = cache.get(ctx);
+    if (!proxy) {
+        proxy = new Proxy({} as SceneData, {
+            get(_target, nodeName: string) {
+                return new Proxy({}, {
+                    get(_target, compName: string) {
+                        const node = ctx.scene.getObjectByName(nodeName) ?? null;
+                        if (!node) return makeErrorProxy(`Node "${nodeName}" not found in scene`);
+                        if (compName === "$node") return node;
+                        const ctor = TypeStore.get(compName);
+                        if (!ctor) return makeErrorProxy(`Component type "${compName}" not registered (node "${nodeName}")`);
+                        const comp = getComponent(node, ctor);
+                        if (!comp) return makeErrorProxy(`Component "${compName}" not found on node "${nodeName}"`);
+                        return comp;
+                    }
+                });
+            }
+        });
+        cache.set(ctx, proxy);
+    }
+    return proxy;
+}

package/src/engine/engine_ssr.ts

@@ -0,0 +1,45 @@
+/**
+ * SSR-safe base classes for browser globals that are not available in Node/SSR environments.
+ *
+ * Use these instead of extending browser globals directly so that class definitions
+ * do not throw a ReferenceError at module evaluation time in SSR/Node contexts
+ * (SvelteKit, Next.js, etc.).
+ *
+ * In browser environments each constant is the real global; in SSR it falls back
+ * to a plain empty class so that `class Foo extends HTMLElementBase` is valid.
+ */
+
+
+/** SSR-safe base class for web components. */
+export const HTMLElementBase: typeof HTMLElement =
+    typeof HTMLElement !== "undefined" ? HTMLElement : (class { } as unknown as typeof HTMLElement);
+
+/** SSR-safe base class for pointer events. */
+export const PointerEventBase: typeof PointerEvent =
+    typeof PointerEvent !== "undefined" ? PointerEvent : (class { } as unknown as typeof PointerEvent);
+
+/** SSR-safe base class for keyboard events. */
+export const KeyboardEventBase: typeof KeyboardEvent =
+    typeof KeyboardEvent !== "undefined" ? KeyboardEvent : (class { } as unknown as typeof KeyboardEvent);
+
+
+
+
+// #region minimal polyfills
+// Three.js FileLoader uses ProgressEvent in fetch stream callbacks.
+// It doesn't exist in Node — install a minimal stub so SSR doesn't crash.
+if (typeof globalThis.ProgressEvent === "undefined") {
+    (globalThis as any).ProgressEvent = class ProgressEvent {
+        readonly type: string;
+        readonly lengthComputable: boolean;
+        readonly loaded: number;
+        readonly total: number;
+        constructor(type: string, init?: { lengthComputable?: boolean; loaded?: number; total?: number }) {
+            this.type = type;
+            this.lengthComputable = init?.lengthComputable ?? false;
+            this.loaded = init?.loaded ?? 0;
+            this.total = init?.total ?? 0;
+        }
+    };
+}
+// #endregion

package/src/engine/engine_three_utils.ts

@@ -493,13 +493,21 @@ void main(){
  * Utility class to perform various graphics operations like copying textures to canvas
  */
 export class Graphics {
-    private static readonly planeGeometry = new PlaneGeometry(2, 2, 1, 1);
-    private static readonly renderer: WebGLRenderer = new WebGLRenderer({ antialias: false, alpha: true });
-    private static readonly perspectiveCam = new PerspectiveCamera();
-    private static readonly orthographicCam = new OrthographicCamera();
-    private static readonly scene = new Scene();
-    private static readonly blitMaterial: BlitMaterial = new BlitMaterial();
-    private static readonly mesh: Mesh = new Mesh(Graphics.planeGeometry, Graphics.blitMaterial);
+    private static _planeGeometry: PlaneGeometry | undefined;
+    private static _renderer: WebGLRenderer | undefined;
+    private static _perspectiveCam: PerspectiveCamera | undefined;
+    private static _orthographicCam: OrthographicCamera | undefined;
+    private static _scene: Scene | undefined;
+    private static _blitMaterial: BlitMaterial | undefined;
+    private static _mesh: Mesh | undefined;
+
+    private static get planeGeometry() { return this._planeGeometry ??= new PlaneGeometry(2, 2, 1, 1); }
+    private static get renderer() { return this._renderer ??= new WebGLRenderer({ antialias: false, alpha: true }); }
+    private static get perspectiveCam() { return this._perspectiveCam ??= new PerspectiveCamera(); }
+    private static get orthographicCam() { return this._orthographicCam ??= new OrthographicCamera(); }
+    private static get scene() { return this._scene ??= new Scene(); }
+    private static get blitMaterial() { return this._blitMaterial ??= new BlitMaterial(); }
+    private static get mesh() { return this._mesh ??= new Mesh(Graphics.planeGeometry, Graphics.blitMaterial); }
 
 
     /** 

package/src/engine/engine_utils.ts

@@ -184,12 +184,12 @@ export function setOrAddParamsToUrl(url: URLSearchParams, paramName: string, par
 
 /** Adds an entry to the browser history. Internally uses `window.history.pushState` */
 export function pushState(title: string, urlParams: URLSearchParams, state?: any) {
-    window.history.pushState(state, title, "?" + urlParams.toString());
+    window.history.pushState(state, title, "?" + urlParams.toString() + window.location.hash);
 }
 
 /** Replaces the current entry in the browser history. Internally uses `window.history.replaceState` */
 export function setState(title: string, urlParams: URLSearchParams, state?: any) {
-    window.history.replaceState(state, title, "?" + urlParams.toString());
+    window.history.replaceState(state, title, "?" + urlParams.toString() + window.location.hash);
 }
 
 // for room id
@@ -597,6 +597,7 @@ export namespace DeviceUtilities {
     /** @returns `true` for MacOS or Windows devices. `false` for Hololens and other headsets. */
     export function isDesktop() {
         if (_isDesktop !== undefined) return _isDesktop;
+        if (typeof window === "undefined") return _isDesktop = false;
         const ua = window.navigator.userAgent;
         const standalone = /Windows|MacOS|Mac OS/.test(ua);
         const isHololens = /Windows NT/.test(ua) && /Edg/.test(ua) && !/Win64/.test(ua);

package/src/engine/engine_utils_hash.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure-JS hashing utilities — no external dependencies, works in browser and Node/SSR.
+ */
+
+// MD5 based on the public-domain RSA Data Security MD5 algorithm.
+function md5Bytes(input: Uint8Array): number[] {
+    function safeAdd(x: number, y: number) { const lsw = (x & 0xffff) + (y & 0xffff); return ((x >> 16) + (y >> 16) + (lsw >> 16)) << 16 | lsw & 0xffff; }
+    function bitRotateLeft(num: number, cnt: number) { return num << cnt | num >>> 32 - cnt; }
+    function md5cmn(q: number, a: number, b: number, x: number, s: number, t: number) { return safeAdd(bitRotateLeft(safeAdd(safeAdd(a, q), safeAdd(x, t)), s), b); }
+    function md5ff(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(b & c | ~b & d, a, b, x, s, t); }
+    function md5gg(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(b & d | c & ~d, a, b, x, s, t); }
+    function md5hh(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(b ^ c ^ d, a, b, x, s, t); }
+    function md5ii(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(c ^ (b | ~d), a, b, x, s, t); }
+
+    const len8 = input.length;
+    const padded = new Uint8Array((Math.ceil((len8 + 9) / 64) * 64));
+    padded.set(input);
+    padded[len8] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, len8 << 3, true);
+    view.setUint32(padded.length - 4, (len8 / 0x20000000) | 0, true);
+
+    let a = 0x67452301, b = 0xefcdab89, c = 0x98badcfe, d = 0x10325476;
+    for (let i = 0; i < padded.length >> 2; i += 16) {
+        const M = (j: number) => view.getInt32((i + j) * 4, true);
+        const [oa, ob, oc, od] = [a, b, c, d];
+        a = md5ff(a,b,c,d,M(0),7,-680876936); d=md5ff(d,a,b,c,M(1),12,-389564586); c=md5ff(c,d,a,b,M(2),17,606105819); b=md5ff(b,c,d,a,M(3),22,-1044525330);
+        a=md5ff(a,b,c,d,M(4),7,-176418897); d=md5ff(d,a,b,c,M(5),12,1200080426); c=md5ff(c,d,a,b,M(6),17,-1473231341); b=md5ff(b,c,d,a,M(7),22,-45705983);
+        a=md5ff(a,b,c,d,M(8),7,1770035416); d=md5ff(d,a,b,c,M(9),12,-1958414417); c=md5ff(c,d,a,b,M(10),17,-42063); b=md5ff(b,c,d,a,M(11),22,-1990404162);
+        a=md5ff(a,b,c,d,M(12),7,1804603682); d=md5ff(d,a,b,c,M(13),12,-40341101); c=md5ff(c,d,a,b,M(14),17,-1502002290); b=md5ff(b,c,d,a,M(15),22,1236535329);
+        a=md5gg(a,b,c,d,M(1),5,-165796510); d=md5gg(d,a,b,c,M(6),9,-1069501632); c=md5gg(c,d,a,b,M(11),14,643717713); b=md5gg(b,c,d,a,M(0),20,-373897302);
+        a=md5gg(a,b,c,d,M(5),5,-701558691); d=md5gg(d,a,b,c,M(10),9,38016083); c=md5gg(c,d,a,b,M(15),14,-660478335); b=md5gg(b,c,d,a,M(4),20,-405537848);
+        a=md5gg(a,b,c,d,M(9),5,568446438); d=md5gg(d,a,b,c,M(14),9,-1019803690); c=md5gg(c,d,a,b,M(3),14,-187363961); b=md5gg(b,c,d,a,M(8),20,1163531501);
+        a=md5gg(a,b,c,d,M(13),5,-1444681467); d=md5gg(d,a,b,c,M(2),9,-51403784); c=md5gg(c,d,a,b,M(7),14,1735328473); b=md5gg(b,c,d,a,M(12),20,-1926607734);
+        a=md5hh(a,b,c,d,M(5),4,-378558); d=md5hh(d,a,b,c,M(8),11,-2022574463); c=md5hh(c,d,a,b,M(11),16,1839030562); b=md5hh(b,c,d,a,M(14),23,-35309556);
+        a=md5hh(a,b,c,d,M(1),4,-1530992060); d=md5hh(d,a,b,c,M(4),11,1272893353); c=md5hh(c,d,a,b,M(7),16,-155497632); b=md5hh(b,c,d,a,M(10),23,-1094730640);
+        a=md5hh(a,b,c,d,M(13),4,681279174); d=md5hh(d,a,b,c,M(0),11,-358537222); c=md5hh(c,d,a,b,M(3),16,-722521979); b=md5hh(b,c,d,a,M(6),23,76029189);
+        a=md5hh(a,b,c,d,M(9),4,-640364487); d=md5hh(d,a,b,c,M(12),11,-421815835); c=md5hh(c,d,a,b,M(15),16,530742520); b=md5hh(b,c,d,a,M(2),23,-995338651);
+        a=md5ii(a,b,c,d,M(0),6,-198630844); d=md5ii(d,a,b,c,M(7),10,1126891415); c=md5ii(c,d,a,b,M(14),15,-1416354905); b=md5ii(b,c,d,a,M(5),21,-57434055);
+        a=md5ii(a,b,c,d,M(12),6,1700485571); d=md5ii(d,a,b,c,M(3),10,-1894986606); c=md5ii(c,d,a,b,M(10),15,-1051523); b=md5ii(b,c,d,a,M(1),21,-2054922799);
+        a=md5ii(a,b,c,d,M(8),6,1873313359); d=md5ii(d,a,b,c,M(15),10,-30611744); c=md5ii(c,d,a,b,M(6),15,-1560198380); b=md5ii(b,c,d,a,M(13),21,1309151649);
+        a=md5ii(a,b,c,d,M(4),6,-145523070); d=md5ii(d,a,b,c,M(11),10,-1120210379); c=md5ii(c,d,a,b,M(2),15,718787259); b=md5ii(b,c,d,a,M(9),21,-343485551);
+        a=safeAdd(a,oa); b=safeAdd(b,ob); c=safeAdd(c,oc); d=safeAdd(d,od);
+    }
+    const result = new DataView(new ArrayBuffer(16));
+    result.setUint32(0, a, true); result.setUint32(4, b, true); result.setUint32(8, c, true); result.setUint32(12, d, true);
+    return Array.from(new Uint8Array(result.buffer));
+}
+
+/** Returns the MD5 hash of the given bytes as a lowercase hex string. */
+export function md5Hex(input: Uint8Array): string {
+    return md5Bytes(input).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Returns the MD5 hash of the given bytes as a raw byte array. */
+export function md5AsBytes(input: Uint8Array): number[] {
+    return md5Bytes(input);
+}
+
+/** Returns the SHA-256 hash of the given buffer as a base64 string. */
+export function sha256Base64(buffer: ArrayBuffer): Promise<string> {
+    return crypto.subtle.digest("SHA-256", new Uint8Array(buffer)).then(res =>
+        btoa(String.fromCharCode(...new Uint8Array(res)))
+    );
+}

package/src/engine/webcomponents/logo-element.ts

@@ -1,4 +1,5 @@
 import { madeWithNeedleSVG, needleLogoOnlySVG, needleLogoSVG } from "../assets/index.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 
 const elementName = "needle-logo-element";
 
@@ -12,7 +13,7 @@ declare global {
  * Needle logo web component used in the hosting UI (small, compact logo or full)
  * @element needle-logo-element
  */
-export class NeedleLogoElement extends HTMLElement {
+export class NeedleLogoElement extends HTMLElementBase {
 
     static get elementName() { return elementName; }
 

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

@@ -1,4 +1,5 @@
 import { showBalloonMessage } from "../../debug/debug.js";
+import { HTMLElementBase } from "../../engine_ssr.js";
 import type { Context } from "../../engine_context.js";
 import { hasCommercialLicense, onLicenseCheckResultChanged, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
@@ -303,7 +304,7 @@ export class NeedleMenu {
  *
  * @element needle-menu
  */
-export class NeedleMenuElement extends HTMLElement {
+export class NeedleMenuElement extends HTMLElementBase {
 
     static create() {
         // Ensure the element is registered before creating — guards against

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

@@ -1,4 +1,5 @@
 import { isDevEnvironment } from "../debug/index.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { ButtonsFactory } from "./buttons.js";
 import { iconFontUrl, loadFont } from "./fonts.js";
 import { WebXRButtonFactory } from "./WebXRButtons.js";
@@ -65,7 +66,7 @@ const isDev = isDevEnvironment();
  * @see {@link NeedleEngineWebComponent} for the main <needle-engine> element
  * @see {@link NeedleMenu} for the built-in menu component that can display similar buttons
  */
-export class NeedleButtonElement extends HTMLElement {
+export class NeedleButtonElement extends HTMLElementBase {
 
     static observedAttributes = ["ar", "vr", "quicklook", "qrcode"];
 

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

@@ -1,4 +1,5 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
 import { hasCommercialLicense } from "../engine_license.js";
@@ -153,7 +154,7 @@ const observedAttributes = [
  * @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via <needle-button>
  * @see {@link NeedleMenu} for the built-in menu configuration component
  */
-export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
+export class NeedleEngineWebComponent extends HTMLElementBase implements INeedleEngineComponent {
 
     static get observedAttributes() {
         return observedAttributes;

package/src/engine/xr/NeedleXRSession.ts

@@ -32,7 +32,7 @@ declare type NeedleXRFrame = XRFrame & { fillPoses?: FillPosesFunction };
  * Use `args.xr` to access the NeedleXRSession */
 export type NeedleXREventArgs = { readonly xr: NeedleXRSession }
 export type SessionChangedEvt = (args: NeedleXREventArgs) => void;
-export type SessionRequestedEvent = (args: { readonly mode: XRSessionMode, readonly init: XRSessionInit }) => void;
+export type SessionRequestedEvent = (args: { readonly mode: XRSessionMode, readonly init: XRSessionInit, readonly context: Context }) => void;
 export type SessionRequestedEndEvent = (args: { readonly mode: XRSessionMode, readonly init: XRSessionInit, newSession: XRSession | null }) => void;
 
 /** Result of a XR hit-test
@@ -207,7 +207,7 @@ function waitForContextLoadingFinished(): Promise<void> {
 }
 
 
-if (DeviceUtilities.isDesktop() && isDevEnvironment()) {
+if (typeof window !== "undefined" && DeviceUtilities.isDesktop() && isDevEnvironment()) {
     window.addEventListener("keydown", (evt) => {
         if (evt.key === "x" || evt.key === "Escape") {
             if (NeedleXRSession.active) {
@@ -492,7 +492,7 @@ export class NeedleXRSession implements INeedleXRSession {
 
             if (!arSupported && (mode === "immersive-ar" || mode === "ar")) {
 
-                this.invokeSessionRequestStart("immersive-ar", init);
+                this.invokeSessionRequestStart("immersive-ar", init, context ?? Context.Current);
 
                 // if we are in an iframe, we need to navigate the top window
                 const topWindow = window.top || window;
@@ -662,7 +662,7 @@ export class NeedleXRSession implements INeedleXRSession {
                 script.onBeforeXR(mode, init);
             }
         }
-        this.invokeSessionRequestStart(mode, init);
+        this.invokeSessionRequestStart(mode, init, context ?? Context.Current);
         if (debug) showBalloonMessage("Requesting " + mode + " session (" + Date.now() + ")");
         Telemetry.sendEvent(Context.Current, "xr", {
             action: "session_request",
@@ -693,9 +693,9 @@ export class NeedleXRSession implements INeedleXRSession {
         return session;
     }
 
-    private static invokeSessionRequestStart(mode: XRSessionMode, init: XRSessionInit) {
+    private static invokeSessionRequestStart(mode: XRSessionMode, init: XRSessionInit, context: Context) {
         for (const listener of this._sessionRequestStartListeners) {
-            listener({ mode, init });
+            listener({ mode, init, context });
         }
     }
     private static invokeSessionRequestEnd(mode: XRSessionMode, init: XRSessionInit, session: XRSession | null | undefined | void) {

package/src/engine/xr/events.ts

@@ -1,4 +1,5 @@
-import type { NeedleXRSession } from "./NeedleXRSession.js";
+import { NeedleXRSession } from "./NeedleXRSession.js";
+import type { Context } from "../engine_context.js";
 
 export declare type XRSessionEventArgs = { session: NeedleXRSession };
 
@@ -14,11 +15,13 @@ const onXRSessionStartListeners: ((evt: XRSessionEventArgs) => void)[] = [];
  *   console.log("XR session started", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
 export function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void) {
     if (onXRSessionStartListeners.indexOf(fn) === -1) {
         onXRSessionStartListeners.push(fn);
     }
+    return () => offXRSessionStart(fn);
 }
 /**
  * Remove a listener for when an XR session starts
@@ -51,11 +54,13 @@ const onXRSessionEndListeners: ((evt: XRSessionEventArgs) => void)[] = [];
  *    console.log("XR session ended", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
 export function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void) {
     if (onXRSessionEndListeners.indexOf(fn) === -1) {
         onXRSessionEndListeners.push(fn);
     }
+    return () => offXRSessionEnd(fn);
 };
 
 /**
@@ -78,6 +83,44 @@ export function offXRSessionEnd(fn: (evt: XRSessionEventArgs) => void) {
 }
 
 
+export declare type XRSessionRequestEventArgs = { readonly mode: XRSessionMode, readonly init: XRSessionInit, readonly context: Context };
+
+/**
+ * Add a listener that fires before an XR session is requested.
+ * Use this to modify the session init options, e.g. to add optional features like `camera-access`.
+ * @param fn The function to call before the XR session is requested
+ * @example
+ * ```js
+ * onBeforeXRSession((args) => {
+ *   args.init.optionalFeatures ??= [];
+ *   args.init.optionalFeatures.push("camera-access");
+ * });
+ * ```
+ * @return A function to remove the listener
+ */
+export function onBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void) {
+    if (onBeforeXRSessionListeners.indexOf(fn) === -1) {
+        onBeforeXRSessionListeners.push(fn);
+        // Delegate to NeedleXRSession which owns the actual invocation
+        NeedleXRSession.onSessionRequestStart(fn);
+    }
+    return () => offBeforeXRSession(fn);
+}
+
+/**
+ * Remove a listener for before an XR session is requested
+ * @param fn The function to remove from the listeners
+ */
+export function offBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void) {
+    const index = onBeforeXRSessionListeners.indexOf(fn);
+    if (index !== -1) {
+        onBeforeXRSessionListeners.splice(index, 1);
+        NeedleXRSession.offSessionRequestStart(fn);
+    }
+}
+
+const onBeforeXRSessionListeners: ((args: XRSessionRequestEventArgs) => void)[] = [];
+
 /**
  * @internal
  * Invoke the XRSessionStart event

package/src/engine/xr/init.ts

@@ -1,4 +1,3 @@
-import { isDevEnvironment, showBalloonMessage } from "../debug/index.js";
 import { DeviceUtilities, setParamWithoutReload } from "../engine_utils.js";
 import { NeedleXRSession } from "./NeedleXRSession.js";
 
@@ -13,12 +12,6 @@ export function initXR() {
 
     if (DeviceUtilities.isiOS()) {
 
-        if (isDevEnvironment()) {
-            const randomParameterValue = Date.now().toString();
-            setParamWithoutReload("debug_appclip", randomParameterValue);
-            showBalloonMessage("iOS appclip debug: " + randomParameterValue);
-        }
-
         // Prefetch
         const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
         url.searchParams.set("url", location.href);