@needle-tools/engine 5.0.3 → 5.1.0-alpha.1

package/src/engine/postprocessing/postprocessing.ts

@@ -0,0 +1,322 @@
+import type { EffectComposer } from "postprocessing";
+import type { ToneMapping } from "three";
+import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
+
+import { isDevEnvironment } from "../debug/index.js";
+import type { Context } from "../engine_context.js";
+import { DeviceUtilities, getParam } from "../engine_utils.js";
+import type { IPostProcessingEffect, IPostProcessingHandler, ITonemappingEffect } from "./types.js";
+
+const debug = getParam("debugpost");
+
+/**
+ * Core postprocessing stack accessible via `context.postprocessing`.
+ * Manages the effect pipeline independently of any specific component.
+ *
+ * Volumes and individual PostProcessingEffect components add/remove effects
+ * to this stack. The stack builds the EffectComposer pipeline when dirty.
+ *
+ * @example Add an effect directly
+ * ```ts
+ * const bloom = new BloomEffect({ intensity: 3 });
+ * this.context.postprocessing.addEffect(bloom);
+ * ```
+ *
+ * @example Remove an effect
+ * ```ts
+ * this.context.postprocessing.removeEffect(bloom);
+ * ```
+ */
+export class PostProcessing {
+
+    private readonly _context: Context;
+    private _handler: IPostProcessingHandler | null = null;
+    private readonly _effects: IPostProcessingEffect[] = [];
+    private _isDirty: boolean = false;
+
+    /** Currently active postprocessing effects in the stack */
+    get effects(): readonly IPostProcessingEffect[] {
+        return this._effects;
+    }
+
+    get dirty() { return this._isDirty; }
+    set dirty(value: boolean) { this._isDirty = value; }
+
+    /** The internal PostProcessingHandler that manages the EffectComposer pipeline */
+    get handler(): IPostProcessingHandler | null { return this._handler; }
+
+    /**
+     * The effect composer used to render postprocessing effects.
+     * This is set internally by the PostProcessingHandler when effects are applied.
+     */
+    get composer(): EffectComposer | ThreeEffectComposer | null { return this._composer; }
+    set composer(value: EffectComposer | ThreeEffectComposer | null) { this._composer = value; }
+    private _composer: EffectComposer | ThreeEffectComposer | null = null;
+
+    /**
+     * Set multisampling to "auto" to automatically adjust the multisampling level based on performance.
+     * Set to a number to manually set the multisampling level.
+     * @default "auto"
+     */
+    multisampling: "auto" | number = "auto";
+
+    /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
+     * and restored when performance recovers.
+     * @default true
+     */
+    adaptiveResolution: boolean = true;
+
+    constructor(context: Context) {
+        this._context = context;
+    }
+
+    /**
+     * Add a post processing effect to the stack.
+     * The effect stack will be rebuilt on the next update.
+     */
+    addEffect(effect: IPostProcessingEffect): void {
+        if (this._effects.includes(effect)) return;
+        this._effects.push(effect);
+        this._isDirty = true;
+    }
+
+    /**
+     * Remove a post processing effect from the stack.
+     * The effect stack will be rebuilt on the next update.
+     */
+    removeEffect(effect: IPostProcessingEffect): void {
+        const index = this._effects.indexOf(effect);
+        if (index !== -1) {
+            this._effects.splice(index, 1);
+            this._isDirty = true;
+        }
+    }
+
+    /** Mark the stack as dirty so the effects are rebuilt on the next update */
+    markDirty(): void {
+        this._isDirty = true;
+    }
+
+    // --- Adaptive multisampling state ---
+    private _enabledTime: number = -1;
+    private _multisampleAutoChangeTime: number = 0;
+    private _multisampleAutoDecreaseTime: number = 0;
+
+    /** @internal Called from the context render loop to update the postprocessing pipeline */
+    update(): void {
+        const context = this._context;
+        if (context.isInXR) return;
+
+        // Wait for a camera before applying
+        if (this._isDirty && context.mainCamera) {
+            this.apply();
+        }
+
+        // In tonemapping-only mode, keep renderer values in sync with the active effect
+        if (this._tonemappingOnlyActive) {
+            const activeEffects = this._effects.filter(e => e.active && e.enabled && e.isToneMapping === true);
+            if (activeEffects.length > 0) {
+                const effect = activeEffects[activeEffects.length - 1] as ITonemappingEffect;
+                context.renderer.toneMapping = effect.threeToneMapping;
+                context.renderer.toneMappingExposure = effect.toneMappingExposure;
+            }
+            return;
+        }
+
+        if (!this._handler || !this._composer || this._handler.composer !== this._composer) return;
+
+        // The composer is always a pmndrs EffectComposer (created by PostProcessingHandler)
+        const composer = this._composer as EffectComposer;
+
+        // Handle context lost
+        if (context.renderer.getContext().isContextLost()) {
+            context.renderer.forceContextRestore();
+        }
+        if (composer.getRenderer() !== context.renderer)
+            composer.setRenderer(context.renderer);
+
+        composer.setMainScene(context.scene);
+
+        // --- Adaptive multisampling ---
+        if (this.multisampling === "auto") {
+            if (this._handler.hasSmaaEffect) {
+                if (this._handler.multisampling !== 0) {
+                    this._handler.multisampling = 0;
+                    if (debug || isDevEnvironment()) {
+                        console.log(`[PostProcessing] multisampling is disabled because it's set to 'auto' and there is an SMAA effect.\n\nIf you need multisampling consider changing 'auto' to a fixed value (e.g. 4).`);
+                    }
+                }
+            }
+            else {
+                const timeSinceLastChange = context.time.realtimeSinceStartup - this._multisampleAutoChangeTime;
+
+                if (context.time.realtimeSinceStartup - this._enabledTime > 2
+                    && timeSinceLastChange > .5
+                ) {
+                    const prev = this._handler.multisampling;
+
+                    if (this._handler.multisampling > 0 && context.time.smoothedFps <= 50) {
+                        this._multisampleAutoChangeTime = context.time.realtimeSinceStartup;
+                        this._multisampleAutoDecreaseTime = context.time.realtimeSinceStartup;
+                        let newMultiSample = this._handler.multisampling * .5;
+                        newMultiSample = Math.floor(newMultiSample);
+                        if (newMultiSample != this._handler.multisampling) {
+                            this._handler.multisampling = newMultiSample;
+                        }
+                        if (debug) console.debug(`[PostProcessing] Reduced multisampling from ${prev} to ${this._handler.multisampling}`);
+                    }
+                    else if (timeSinceLastChange > 1
+                        && context.time.smoothedFps >= 59
+                        && this._handler.multisampling < context.renderer.capabilities.maxSamples
+                        && context.time.realtimeSinceStartup - this._multisampleAutoDecreaseTime > 10
+                    ) {
+                        this._multisampleAutoChangeTime = context.time.realtimeSinceStartup;
+                        let newMultiSample = this._handler.multisampling <= 0 ? 1 : this._handler.multisampling * 2;
+                        newMultiSample = Math.floor(newMultiSample);
+                        if (newMultiSample !== this._handler.multisampling) {
+                            this._handler.multisampling = newMultiSample;
+                        }
+                        if (debug) console.debug(`[PostProcessing] Increased multisampling from ${prev} to ${this._handler.multisampling}`);
+                    }
+                }
+            }
+        }
+        else {
+            const newMultiSample = Math.max(0, Math.min(this.multisampling as number, context.renderer.capabilities.maxSamples));
+            if (newMultiSample !== this._handler.multisampling)
+                this._handler.multisampling = newMultiSample;
+        }
+
+        // --- Adaptive pixel ratio ---
+        this._handler.adaptivePixelRatio = this.adaptiveResolution;
+        this._handler.updateAdaptivePixelRatio();
+
+        // Update camera on passes if needed
+        if (context.mainCamera) {
+            const passes = composer.passes;
+            for (const pass of passes) {
+                if (pass.mainCamera && pass.mainCamera !== context.mainCamera) {
+                    composer.setMainCamera(context.mainCamera);
+                    break;
+                }
+            }
+        }
+    }
+
+    private _lastApplyTime?: number;
+    private _rapidApplyCount = 0;
+
+    // --- Tonemapping-only state ---
+    /** When true, tonemapping is applied directly to the renderer (no full pipeline) */
+    private _tonemappingOnlyActive = false;
+    private _previousToneMapping?: ToneMapping;
+    private _previousToneMappingExposure?: number;
+
+    private apply() {
+        if (debug) console.log(`[PostProcessing] Apply stack (${this._effects.length} effects)`);
+
+        if (isDevEnvironment()) {
+            if (this._lastApplyTime !== undefined && Date.now() - this._lastApplyTime < 100) {
+                this._rapidApplyCount++;
+                if (this._rapidApplyCount === 5)
+                    console.warn("[PostProcessing] Detected rapid post processing modifications - this might be a bug");
+            }
+            this._lastApplyTime = Date.now();
+        }
+
+        this._isDirty = false;
+
+        // Collect active effects
+        const activeEffects = this._effects.filter(e => e.active && e.enabled);
+
+        if (activeEffects.length <= 0) {
+            this.restoreTonemapping();
+            this._handler?.unapply(false);
+            return;
+        }
+
+        // Check if ALL active effects are tonemapping-only
+        const allToneMapping = activeEffects.every(e => e.isToneMapping === true);
+
+        if (allToneMapping) {
+            // Use the last tonemapping effect added (last in the array)
+            const tonemappingEffect = activeEffects[activeEffects.length - 1] as ITonemappingEffect;
+
+            if (debug) console.log(`[PostProcessing] Only tonemapping effects in stack — applying directly to renderer`);
+
+            // Store previous values on first activation
+            if (!this._tonemappingOnlyActive) {
+                this._previousToneMapping = this._context.renderer.toneMapping as ToneMapping;
+                this._previousToneMappingExposure = this._context.renderer.toneMappingExposure;
+                this._tonemappingOnlyActive = true;
+            }
+
+            // Apply tonemapping directly to renderer
+            this._context.renderer.toneMapping = tonemappingEffect.threeToneMapping;
+            this._context.renderer.toneMappingExposure = tonemappingEffect.toneMappingExposure;
+
+            // Tear down any existing postprocessing pipeline
+            this._handler?.unapply(false);
+            return;
+        }
+
+        // We have non-tonemapping effects — restore renderer tonemapping if we were in tonemapping-only mode
+        this.restoreTonemapping();
+
+        // Build full postprocessing pipeline
+        this.ensureHandler()
+            .then(handler => {
+                if (!handler) return;
+                return handler.apply(activeEffects) as Promise<void> | void;
+            })
+            .then(() => {
+                if (this._handler) {
+                    if (this.multisampling === "auto") {
+                        this._handler.multisampling = DeviceUtilities.isMobileDevice()
+                            ? 2
+                            : 4;
+                    }
+                    else {
+                        this._handler.multisampling = Math.max(0, Math.min(this.multisampling as number, this._context.renderer.capabilities.maxSamples));
+                    }
+                    if (debug) console.debug(`[PostProcessing] Set multisampling to ${this._handler.multisampling} (Is Mobile: ${DeviceUtilities.isMobileDevice()})`);
+                }
+            });
+
+        this._enabledTime = this._context.time.realtimeSinceStartup;
+    }
+
+    /** Restore renderer tonemapping to previous values when leaving tonemapping-only mode */
+    private restoreTonemapping() {
+        if (this._tonemappingOnlyActive) {
+            if (this._previousToneMapping !== undefined)
+                this._context.renderer.toneMapping = this._previousToneMapping;
+            if (this._previousToneMappingExposure !== undefined)
+                this._context.renderer.toneMappingExposure = this._previousToneMappingExposure;
+            this._tonemappingOnlyActive = false;
+            this._previousToneMapping = undefined;
+            this._previousToneMappingExposure = undefined;
+            if (debug) console.log(`[PostProcessing] Restored renderer tonemapping`);
+        }
+    }
+
+    /** Lazily creates the PostProcessingHandler to avoid loading the postprocessing library until actually needed */
+    private async ensureHandler(): Promise<IPostProcessingHandler> {
+        if (!this._handler) {
+            const { PostProcessingHandler } = await import("../../engine-components/postprocessing/PostProcessingHandler.js");
+            if (!this._handler) {
+                this._handler = new PostProcessingHandler(this._context);
+            }
+        }
+        return this._handler;
+    }
+
+    /** @internal */
+    dispose() {
+        this.restoreTonemapping();
+        this._handler?.dispose();
+        this._handler = null;
+        this._composer = null;
+        this._effects.length = 0;
+    }
+}

package/src/engine/postprocessing/types.ts

@@ -0,0 +1,43 @@
+import type { EffectComposer } from "postprocessing";
+import type { ToneMapping } from "three";
+import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
+
+/**
+ * Minimal interface for a postprocessing effect as seen by the core stack.
+ * Implemented by `PostProcessingEffect` in engine-components.
+ */
+export interface IPostProcessingEffect {
+    readonly active: boolean;
+    readonly enabled: boolean;
+    /** When true, this effect is a tonemapping effect. The core stack uses this to detect tonemapping-only scenarios. */
+    readonly isToneMapping?: boolean;
+}
+
+/**
+ * Extended interface for tonemapping effects.
+ * When ONLY tonemapping effects are in the stack, the core applies tonemapping
+ * directly to the renderer instead of creating a full postprocessing pipeline.
+ */
+export interface ITonemappingEffect extends IPostProcessingEffect {
+    readonly isToneMapping: true;
+    /** The three.js ToneMapping enum value to apply to the renderer */
+    readonly threeToneMapping: ToneMapping;
+    /** The exposure value to apply to the renderer */
+    readonly toneMappingExposure: number;
+}
+
+/**
+ * Interface for the pipeline builder that manages the EffectComposer.
+ * Implemented by `PostProcessingHandler` in engine-components.
+ */
+export interface IPostProcessingHandler {
+    readonly composer: EffectComposer | ThreeEffectComposer | null;
+    readonly hasSmaaEffect: boolean;
+    multisampling: number;
+    adaptivePixelRatio: boolean;
+
+    apply(effects: IPostProcessingEffect[]): Promise<void>;
+    unapply(dispose?: boolean): void;
+    updateAdaptivePixelRatio(): void;
+    dispose(): void;
+}

package/src/engine/webcomponents/WebXRButtons.ts

@@ -6,7 +6,7 @@ import { onXRSessionEnd, onXRSessionStart } from "../xr/events.js";
 import { ButtonsFactory } from "./buttons.js";
 import { getIconElement } from "./icons.js";
 import { NeedleMenu } from "./needle menu/needle-menu.js";
-import { getOrCreateQuicklookHandler,type IQuicklookHandler } from "./quicklook-handler.js";
+import { getOrCreateQuicklookHandler, type IQuicklookHandler } from "./quicklook-handler.js";
 
 // TODO: move these buttons into their own web components so their logic is encapsulated (e.g. the CSS animation when a xr session is requested)
 
@@ -120,10 +120,27 @@ export class WebXRButtonFactory {
 
         button.classList.add("webxr-button");
         button.dataset["needle"] = "webxr-ar-button";
-        button.innerText = "Enter AR";
-        button.prepend(getIconElement("view_in_ar"))
         button.title = "Click to start an AR session";
-        button.addEventListener("click", () => NeedleXRSession.start(mode, init));
+        const setDefaultText = () => {
+            button.innerText = "Enter AR";
+            button.prepend(getIconElement("view_in_ar"));
+        };
+        setDefaultText();
+
+        let tapAgainTimeout: ReturnType<typeof setTimeout>;
+        button.addEventListener("click", () => {
+
+            NeedleXRSession.start(mode, init);
+
+            if (DeviceUtilities.isiOS() && !DeviceUtilities.isVisionOS()) {
+                setTimeout(() => {
+                    button.innerHTML = "Tap again";
+                    button.prepend(getIconElement("view_in_ar"));
+                    clearTimeout(tapAgainTimeout);
+                    tapAgainTimeout = setTimeout(setDefaultText, 4000);
+                }, 500);
+            }
+        });
         NeedleMenu.setElementPriority(button, arButtonPriority);
         this.updateSessionSupported(button, mode);
         this.listenToXRSessionState(button, mode);

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
@@ -79,13 +79,9 @@ function getDOMOverlayElement(domElement: HTMLElement) {
 }
 
 
-
 handleSessionGranted();
 async function handleSessionGranted() {
 
-    // await delay(400);
-
-
     let defaultMode: XRSessionMode = "immersive-vr";
 
     try {
@@ -109,8 +105,6 @@ async function handleSessionGranted() {
         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>;
@@ -149,7 +143,6 @@ async function handleSessionGranted() {
         navigator.xr?.addEventListener('sessiongranted', async () => {
             // enableSpatialConsole(true);
 
-
             const lastSessionMode = sessionStorage.getItem("needle_xr_session_mode") as XRSessionMode;
             const lastSessionInit = sessionStorage.getItem("needle_xr_session_init") ?? null;
             const init = lastSessionInit ? JSON.parse(lastSessionInit) : null;
@@ -331,7 +324,18 @@ export class NeedleXRSession implements INeedleXRSession {
      * @param mode The XRSessionMode to check if it is supported
      * @returns true if the browser supports the given XRSessionMode
      */
-    static isSessionSupported(mode: XRSessionMode) { return this.xrSystem?.isSessionSupported(mode).catch(err => { if (debug) console.error(err); return false }) ?? Promise.resolve(false); }
+    static isSessionSupported(mode: XRSessionMode) {
+        // We cache the result of the session support check to avoid unnecessary calls to isSessionSupported. This is especially important for user input events that internally run session support checks during onclick where the event must be resolved as fast as possible.
+        if (this._sessionSupportedCache[mode] !== undefined) {
+            return Promise.resolve(this._sessionSupportedCache[mode]);
+        }
+        return this.xrSystem?.isSessionSupported(mode).then(supported => {
+            this._sessionSupportedCache[mode] = supported;
+            return supported;
+        }).catch(err => { if (debug) console.error(err); return false }) ?? Promise.resolve(false);
+    }
+
+    private static _sessionSupportedCache: { [mode in XRSessionMode]?: boolean } = {};
 
     private static _currentSessionRequest?: Promise<XRSession>;
     private static _activeSession: NeedleXRSession | null;
@@ -466,10 +470,11 @@ export class NeedleXRSession implements INeedleXRSession {
         // 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()) {
 
-            const arSupported = await this.isARSupported().catch(() => false);
+            // IMPORTANT: on iOS we should have prefetched immersive-ar support already on app start (this is done in xrInit()) - if not then clicking the Enter AR button for the very first time does not immediately open the AppClip overlay.  
+            // Without an async await here the overlay *does* however open even when clicking for the very first time. (To test this you need to clear the local experience cache on device)
+            const arSupported = this._sessionSupportedCache["immersive-ar"] ?? await this.isARSupported();
 
             // On VisionOS, we use QuickLook for AR experiences; no AppClip support for now.
             if (DeviceUtilities.isVisionOS() && !arSupported && (mode === "ar" || mode === "immersive-ar")) {
@@ -487,13 +492,16 @@ 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;
+                const originalUrl = topWindow.location.href;
 
                 // Forward to the AppClip experience (Using the apple.com url the appclip overlay shows immediately)
                 // const url =`https://appclip.needle.tools/ar?url=${(location.href)}`;
                 const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
                 url.searchParams.set("url", location.href);
-
                 const urlStr = url.toString();
 
                 Telemetry.sendEvent(Context.Current, "xr", {
@@ -502,16 +510,43 @@ export class NeedleXRSession implements INeedleXRSession {
                     url: urlStr,
                 });
 
-                // if we are in an iframe, we need to navigate the top window
-                const topWindow = window.top || window;
                 try {
                     console.debug("iOS device detected - opening Needle App Clip for AR experience", { mode, init, url });
+
+                    // Prewarm the appclip by opening the URL
+                    // BUT on safari triggering this with multiple URLs causes the
+                    // Browser to show the dialogue AGAIN in the background
+                    // SO: we don't do it here...
+                    const key = "appclip-prewarm:" + new URL(url).origin;
+                    const allowMultipleNavigations = sessionStorage.getItem(key) === null;
+                    if (allowMultipleNavigations) {
+                        const secondUrl = new URL(url);
+                        secondUrl.searchParams.set("prewarm", "1");
+                        // eslint-disable-next-line xss/no-location-href-assign
+                        topWindow.location.href = secondUrl.toString();
+
+                        // wait a bit to give the device time to fetch the app clip metadata - this seems to fix the double tap issue (500 ms seem to work)
+                        await new Promise(res => setTimeout(res, 300));
+                    }
+
                     // navigate to app clip url but keep the current url in history, open in same tab
                     // eslint-disable-next-line xss/no-location-href-assign
                     topWindow.location.href = urlStr;
+
+                    if (allowMultipleNavigations && !DeviceUtilities.isSafari()) {
+                        setTimeout(() => {
+                            const url2 = new URL(url);
+                            url2.searchParams.set("prewarm", "1");
+                            // eslint-disable-next-line xss/no-location-href-assign
+                            topWindow.location.href = url2.toString();
+                        }, 500);
+                    }
+
+                    sessionStorage.setItem(key, "1");
+
                 }
                 catch (e) {
-                    console.warn("Error navigating to AppClip " + urlStr + "\n", e);
+                    console.warn(`Error navigating to AppClip ${urlStr}\n`, e);
                     // if top window navigation fails and we are in an iframe, we try to navigate the top window directly
                     const weAreInIframe = window !== window.top;
                     if (weAreInIframe) {
@@ -531,7 +566,7 @@ export class NeedleXRSession implements INeedleXRSession {
         }
 
         if (mode === "quicklook") {
-            console.warn("QuickLook mode is only supported on iOS devices");
+            console.error("QuickLook mode is only supported on iOS devices.");
             return null;
         }
 
@@ -627,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",
@@ -658,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