@needle-tools/engine 5.1.6 → 5.1.7

package/src/engine/engine_license.ts

@@ -9,19 +9,19 @@ import { DeviceUtilities, getParam } from "./engine_utils.js";
 
 const debug = getParam("__debuglic__");
 
-const _CkM: ((result: boolean) => void)[] = [];
+const __JlN: ((result: boolean) => void)[] = [];
 
 // DO NOT EDIT MANUALLY
-let __KXugUk: string = "";
+let _$feH: string = "";
 // eslint-disable-next-line prefer-const
-let _lYh: string = "";
+let Cll: string = "";
 
 if (debug) {
-    console.log("License Type: " + __KXugUk);
-    if (_lYh) {
-        console.log("License JWT: " + _lYh);
+    console.log("License Type: " + _$feH);
+    if (Cll) {
+        console.log("License JWT: " + Cll);
         try {
-            const payload = JSON.parse(atob(_lYh.split(".")[1].replace(/-/g, '+').replace(/_/g, '/')));
+            const payload = JSON.parse(atob(Cll.split(".")[1].replace(/-/g, '+').replace(/_/g, '/')));
             console.log("License JWT payload:", payload);
         }
         catch { console.log("License JWT payload: (failed to decode)"); }
@@ -32,8 +32,8 @@ if (debug) {
 }
 
 /** @internal */
-export function _RTmnPEj() {
-    switch (__KXugUk) {
+export function _owM() {
+    switch (_$feH) {
         case "pro":
         case "enterprise":
             return true;
@@ -42,8 +42,8 @@ export function _RTmnPEj() {
 }
 
 /** @internal */
-export function _wHm() {
-    switch (__KXugUk) {
+export function _$lAjTeY() {
+    switch (_$feH) {
         case "indie":
             return true;
     }
@@ -51,8 +51,8 @@ export function _wHm() {
 }
 
 /** @internal */
-export function BwwAkey() {
-    switch (__KXugUk) {
+export function WfpL() {
+    switch (_$feH) {
         case "edu":
             return true;
     }
@@ -60,20 +60,20 @@ export function BwwAkey() {
 }
 
 /** @internal */
-export function _$SVo() {
-    return _RTmnPEj() || _wHm() || BwwAkey();
+export function _ERXbX() {
+    return _owM() || _$lAjTeY() || WfpL();
 }
 
 
 /** @internal */
-export function _MxpvNPuw(cb: (result: boolean) => void) {
-    if (_RTmnPEj() || _wHm() || BwwAkey())
+export function _$fUPpV(cb: (result: boolean) => void) {
+    if (_owM() || _$lAjTeY() || WfpL())
         return cb(true);
-    _CkM.push(cb);
+    __JlN.push(cb);
 }
 
-function _qknHtcMb(result: boolean) {
-    for (const cb of _CkM) {
+function $tNDg(result: boolean) {
+    for (const cb of __JlN) {
         try {
             cb(result);
         }
@@ -88,7 +88,7 @@ function _qknHtcMb(result: boolean) {
 
 // ECDSA P-256 public key for verifying license JWTs (verification-only, safe to ship)
 /* eslint-disable no-secrets/no-secrets -- public key, not a secret */
-const iWS = {
+const UaNi = {
     kty: "EC",
     crv: "P-256",
     x: "A34nyKMjhQYVgzeE4tyLUYdx34TAKogDa7v7PRaO9Lg",
@@ -112,7 +112,7 @@ function base64urlDecode(str: string): Uint8Array {
  * Verify a JWT license token and return the `type` claim if valid.
  * Returns null if the JWT is missing, malformed, or has an invalid signature.
  */
-async function _nbExawP(jwt: string): Promise<string | null> {
+async function _jkTgbWSW(jwt: string): Promise<string | null> {
     if (!jwt) return null;
     try {
         const parts = jwt.split(".");
@@ -122,7 +122,7 @@ async function _nbExawP(jwt: string): Promise<string | null> {
 
         const key = await crypto.subtle.importKey(
             "jwk",
-            iWS,
+            UaNi,
             { name: "ECDSA", namedCurve: "P-256" },
             false,
             ["verify"]
@@ -182,24 +182,24 @@ async function _nbExawP(jwt: string): Promise<string | null> {
 }
 
 /** Verify the injected JWT and update the license type if valid.
- * The engine ONLY trusts the JWT — the plain __KXugUk string is ignored. */
+ * The engine ONLY trusts the JWT — the plain _$feH string is ignored. */
 let _jwtVerificationPromise: Promise<void> | undefined = undefined;
-async function yuH(): Promise<void> {
-    // NOTE: do NOT add an `if (!_lYh) return` guard here.
+async function _$xpTijs(): Promise<void> {
+    // NOTE: do NOT add an `if (!Cll) return` guard here.
     // esbuild (Vite dependency pre-bundling) would see the variable as constant ""
     // and tree-shake the entire JWT verification code path.
-    const jwt = _lYh;
+    const jwt = Cll;
     // Clear after reading — this reassignment also prevents esbuild from
     // constant-folding the variable (it now has multiple assignment sites).
-    _lYh = "";
-    const verifiedType = await _nbExawP(jwt);
+    Cll = "";
+    const verifiedType = await _jkTgbWSW(jwt);
     if (verifiedType) {
-        __KXugUk = verifiedType;
+        _$feH = verifiedType;
         if (debug) console.log("License type set from verified JWT: " + verifiedType);
-        _qknHtcMb(_$SVo());
+        $tNDg(_ERXbX());
     }
     else {
-        __KXugUk = "basic";
+        _$feH = "basic";
         if (debug && jwt) console.warn("JWT verification failed — license reset to basic");
     }
 }
@@ -650,18 +650,18 @@ export namespace Telemetry {
 }
 
 
-export function __gVa() {
+export function _QQIM() {
 
-    if(__KXugUk === "") __KXugUk = "basic";
+    if(_$feH === "") _$feH = "basic";
 
     // Start JWT verification — must be here (not top-level) to avoid tree-shaking
-    _jwtVerificationPromise = yuH();
+    _jwtVerificationPromise = _$xpTijs();
 
     Telemetry.init();
     ContextRegistry.registerCallback(ContextEvent.ContextRegistered, evt => {
-        KjRK(evt.context);
-        _$LyU(evt.context);
-        setTimeout(() => _ZJOGEA(evt.context), 2000);
+        _vIz(evt.context);
+        __YpDHW(evt.context);
+        setTimeout(() => _fTHGCOy(evt.context), 2000);
     });
     // ContextCreated fires after the renderer exists, so the canvas is available for context-loss monitoring
     ContextRegistry.registerCallback(ContextEvent.ContextCreated, evt => {
@@ -670,17 +670,17 @@ export function __gVa() {
     });
 }
 
-export let nOo: Promise<void> | undefined = undefined;
+export let _jcZJFQ: Promise<void> | undefined = undefined;
 let applicationIsForbidden = false;
 let applicationForbiddenText = "";
-async function __KTmAYg() {
+async function QBdsZzv() {
     // Only perform the runtime license check once
-    if (nOo) return nOo;
+    if (_jcZJFQ) return _jcZJFQ;
     // Wait for JWT verification to complete first (if running)
     if (_jwtVerificationPromise) {
         await _jwtVerificationPromise;
     }
-    if (__KXugUk === "basic") {
+    if (_$feH === "basic") {
         try {
             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, {
@@ -692,29 +692,29 @@ async function __KTmAYg() {
             if (res?.status === 200) {
                 applicationIsForbidden = false;
                 if (debug) console.log("License check succeeded");
-                __KXugUk = "pro";
-                _qknHtcMb(true);
+                _$feH = "pro";
+                $tNDg(true);
             }
             else if (res?.status === 403) {
-                _qknHtcMb(false);
+                $tNDg(false);
                 applicationIsForbidden = true;
                 applicationForbiddenText = await res.text();
             }
             else {
-                _qknHtcMb(false);
+                $tNDg(false);
                 if (debug) console.log("License check failed with status " + res?.status);
             }
         }
         catch (err) {
-            _qknHtcMb(false);
+            $tNDg(false);
             if (debug) console.error("License check failed", err);
         }
     }
-    else if (debug) console.log("Runtime license check is skipped because license is already applied as \"" + __KXugUk + "\"");
+    else if (debug) console.log("Runtime license check is skipped because license is already applied as \"" + _$feH + "\"");
 }
-nOo = __KTmAYg();
+_jcZJFQ = QBdsZzv();
 
-async function _$LyU(ctx: IContext) {
+async function __YpDHW(ctx: IContext) {
     function createForbiddenElement() {
         const div = document.createElement("div");
         div.className = "needle-forbidden";
@@ -779,40 +779,40 @@ async function _$LyU(ctx: IContext) {
     }, 500)
 }
 
-async function KjRK(ctx: IContext) {
+async function _vIz(ctx: IContext) {
     try {
-        if (!_RTmnPEj() && !_wHm()) {
-            return $GvoIiWw(ctx);
+        if (!_owM() && !_$lAjTeY()) {
+            return _qdVRlod(ctx);
         }
     }
     catch (err) {
         if (debug) console.log("License check failed", err)
-        return $GvoIiWw(ctx)
+        return _qdVRlod(ctx)
     }
-    if (debug) $GvoIiWw(ctx)
+    if (debug) _qdVRlod(ctx)
 }
 
 
 
-async function $GvoIiWw(ctx: IContext) {
+async function _qdVRlod(ctx: IContext) {
 
     // if the engine loads faster than the license check, we need to capture the ready event here
     let isReady = false;
     ctx.domElement.addEventListener("ready", () => isReady = true);
 
-    await nOo?.catch(() => { });
+    await _jcZJFQ?.catch(() => { });
 
 
-    if (_RTmnPEj() || _wHm()) return;
-    if (_$SVo() === false) _XLWxG();
+    if (_owM() || _$lAjTeY()) return;
+    if (_ERXbX() === false) $nAg();
 
     // check if the engine is already ready (meaning has finished loading)
     if (isReady) {
-        _sEwWUCOP(ctx);
+        __lRxm(ctx);
     }
     else {
         ctx.domElement.addEventListener("ready", () => {
-            _sEwWUCOP(ctx);
+            __lRxm(ctx);
         });
     }
 }
@@ -820,7 +820,7 @@ async function $GvoIiWw(ctx: IContext) {
 // const licenseElementIdentifier = "needle-license-element";
 // const licenseDuration = 10000;
 // const licenseDelay = 1200;
-function _sEwWUCOP(ctx: IContext) {
+function __lRxm(ctx: IContext) {
 
     const style = `
         position: relative;
@@ -833,7 +833,7 @@ function _sEwWUCOP(ctx: IContext) {
         padding: 10px;
         padding-left: 30px;
     `;
-    if (__KXugUk === "edu") {
+    if (_$feH === "edu") {
         if (navigator.webdriver) {
             console.log("This project is supported by Needle for Education – https://needle.tools");
         }
@@ -890,7 +890,7 @@ function _sEwWUCOP(ctx: IContext) {
         }
     }, 1000);
 
-    if (BwwAkey()) {
+    if (WfpL()) {
         const removeDelay = 20_000;
         setTimeout(() => {
             clearInterval(interval);
@@ -899,7 +899,7 @@ function _sEwWUCOP(ctx: IContext) {
             const intervalInMinutes = 5;
             setTimeout(() => {
                 if (ctx.domElement.parentNode)
-                    _sEwWUCOP(ctx);
+                    __lRxm(ctx);
             }, 1000 * 60 * intervalInMinutes)
         }, removeDelay);
     }
@@ -910,7 +910,7 @@ function _sEwWUCOP(ctx: IContext) {
 const base64Logo = "data:image/webp;base64,UklGRrABAABXRUJQVlA4WAoAAAAQAAAAHwAAHwAAQUxQSKEAAAARN6CmbSM4WR7vdARON11EBDq3fLiNbVtVzpMCPlKAEzsx0Y/x+Ovuv4dn0EFE/ydAvz6YggXzgh5sVgXM/zOC/4sii7qgGvB5N7hmuQYwkvazWAu1JPW41FXSHq6pnaQWvqYH18Fc0j1hO/BFTtIeSBlJi5w6qIIO7IOrwhFsB2Yxukif0FTRLpXswHR8MxbslKe9VZsn/Ub5C7YFOpqSTABWUDgg6AAAAFAGAJ0BKiAAIAA+7VyoTqmkpCI3+qgBMB2JbACdMt69DwMIQBLhkTO6XwY00UEDK6cNIDnuNibPf0EgAP7Y1myuiQHLDsF/0h5unrGh6WAbv7aegg2ZMd3uRKfT/3SJztcaujYfTvMXspfCTmYcoO6a+vhC3ss4M8uM58t4siiu59I4aOl59e9Sr6xoxYlHf2v+NnBNpJYeJf8jABQAId/PXuBkLEFkiCucgSGEcfhvajql/j3reCGl0M5/9gQWy7ayNPs+wlvIxFnNfSlfuND4CZOCyxOHhRqOmHN4ULHo3tCSrUNvgAA=";
 
 let lastLogTime = 0;
-async function _XLWxG(_logo?: string) {
+async function $nAg(_logo?: string) {
     const now = Date.now();
     if (now - lastLogTime < 2000) return;
     lastLogTime = now;
@@ -943,7 +943,7 @@ async function _XLWxG(_logo?: string) {
 }
 
 
-async function _ZJOGEA(context: IContext) {
+async function _fTHGCOy(context: IContext) {
     // isAllowed() now also covers cross-origin-isolated pages (where beacons can't be sent)
     // and Do Not Track / GPC.
     if (!Telemetry.isAllowed(context)) {
@@ -957,7 +957,7 @@ async function _ZJOGEA(context: IContext) {
 
             // current url without query parameters
             const currentUrl = window.location.href.split("?")[0];
-            const license = __KXugUk;
+            const license = _$feH;
 
             const beaconData = {
                 license,

package/src/engine/engine_networking_blob.ts

@@ -1,7 +1,7 @@
 import { FileLoader } from "three";
 
 import { showBalloonWarning } from "./debug/index.js";
-import { _$SVo } from "./engine_license.js";
+import { _ERXbX } from "./engine_license.js";
 import { delay } from "./engine_utils.js";
 import { md5AsBytes, md5Hex, sha256Base64 } from "./engine_utils_hash.js";
 
@@ -45,7 +45,7 @@ export namespace BlobStorage {
      */
     export function canUpload(info: { filesize: number }) {
         const sizeInMB = info.filesize / 1024 / 1024;
-        if (_$SVo()) {
+        if (_ERXbX()) {
             return sizeInMB < maxSizeInMB;
         }
         return sizeInMB < maxFreeSizeInMB;
@@ -100,7 +100,7 @@ export namespace BlobStorage {
             console.warn(`Your file is too large for uploading (${filesizeInMB.toFixed(1)}MB). Max allowed size is ${maxSizeInMB}MB`);
             return null;
         }
-        else if (!_$SVo() && filesizeInMB > maxFreeSizeInMB) {
+        else if (!_ERXbX() && filesizeInMB > maxFreeSizeInMB) {
             if (opts?.silent !== true) showBalloonWarning(`File is too large for uploading. Please get a <a href=\"https://needle.tools/pricing\" target=\"_blank\">commercial license</a> to upload files larger than 5MB`);
             console.warn(`Your file is too large for uploading (${filesizeInMB.toFixed(1)}MB). Max size is 5MB for non-commercial users. Please get a commercial license at https://needle.tools/pricing for larger files (up to 50MB)`);
             return null;

package/src/engine/engine_utils.ts

@@ -687,6 +687,8 @@ export namespace DeviceUtilities {
     /** @returns `true` for MacOS devices */
     export function isMacOS() {
         if (__isMacOS !== undefined) return __isMacOS;
+        // Guard against non-browser (SSR / prerender) environments where `navigator` is undefined.
+        if (typeof navigator === "undefined") return __isMacOS = false;
         if (isiOS() || isiPad()) return __isMacOS = false;
         const userAgent = navigator.userAgent.toLowerCase();
         if (navigator.userAgentData) {
@@ -711,6 +713,8 @@ export namespace DeviceUtilities {
     /** @returns `true` for mobile Apple devices like iPad, iPhone, iPod, Vision Pro, ... */
     export function isiOS() {
         if (__isiOS !== undefined) return __isiOS;
+        // Guard against non-browser (SSR / prerender) environments where `navigator` is undefined.
+        if (typeof navigator === "undefined") return __isiOS = false;
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         return __isiOS = iosDevices.includes(navigator.platform)
             // iPad on iOS 13 detection

package/src/engine/engine_utils_qrcode.ts

@@ -4,7 +4,7 @@ import { Quaternion, Vector2, Vector3, Vector4 } from "three";
 
 import { needleLogoOnlySVG } from "./assets/index.js";
 import { isDevEnvironment } from "./debug/debug.js";
-import { _$SVo } from "./engine_license.js";
+import { _ERXbX } from "./engine_license.js";
 import { InternalAttributeUtils } from "./engine_utils_attributes.js";
 import type { NeedleEngineWebComponent } from "./webcomponents/needle-engine.js";
 
@@ -135,7 +135,7 @@ async function internalRenderQRCodeOverlays(canvas: HTMLCanvasElement, args: { s
         console.debug("[QR Code] No web component found")
     }
 
-    const canUseCustomLogo = _$SVo();
+    const canUseCustomLogo = _ERXbX();
 
     // Query logo src from needle-engine attribute.
     // For any supported attribute it's possible to use "falsey" values (e.g. "0" or "false" to disable the logo in the QR code)

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

@@ -2,7 +2,7 @@ import { Mesh, Object3D, TextureLoader, Vector4 } from "three";
 import ThreeMeshUI from "three-mesh-ui";
 
 import { addNewComponent } from "../../engine_components.js";
-import { _$SVo } from "../../engine_license.js";
+import { _ERXbX } from "../../engine_license.js";
 import { OneEuroFilterXYZ } from "../../engine_math.js";
 import type { Context } from "../../engine_setup.js";
 import { lookAtObject } from "../../engine_three_utils.js";
@@ -321,7 +321,7 @@ export class NeedleSpatialMenu {
         }
         if (this.menu) {
             const index = this.menu.children.indexOf(this._poweredByNeedleElement as any);
-            if (!this._showNeedleLogo && _$SVo()) {
+            if (!this._showNeedleLogo && _ERXbX()) {
                 if (index >= 0) {
                     this._poweredByNeedleElement.removeFromParent();
                     this.markDirty();

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

@@ -1,6 +1,6 @@
 import { showBalloonMessage } from "../../debug/debug.js";
 import type { Context } from "../../engine_context.js";
-import { _$SVo, _MxpvNPuw, Telemetry } from "../../engine_license.js";
+import { _ERXbX, _$fUPpV, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
 import { HTMLElementBase } from "../../engine_ssr.js";
 import { DeviceUtilities, getParam } from "../../engine_utils.js";
@@ -784,8 +784,8 @@ export class NeedleMenuElement extends HTMLElementBase {
         try {
             // if the user has a license then we CAN hide the needle logo
             // calling this method immediately will cause an issue with vite bundling tho
-            window.requestAnimationFrame(() => _MxpvNPuw(res => {
-                if (res == true && _$SVo() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => _$fUPpV(res => {
+                if (res == true && _ERXbX() && !debugNonCommercial) {
                     let visible = this._userRequestedLogoVisible;
                     if (visible === undefined) visible = false;
                     this.___onSetLogoVisible(visible);
@@ -836,7 +836,7 @@ export class NeedleMenuElement extends HTMLElementBase {
                 // ensure the menu is not hidden or removed
                 const requiredParent = this?.parentNode;
                 if (this.style.display != "flex" || this.style.visibility != "visible" || this.style.opacity != "1" || requiredParent != this._domElement?.shadowRoot) {
-                    if (!_$SVo()) {
+                    if (!_ERXbX()) {
                         const change = changeEventCounter++;
                         // if a user doesn't have a local pro license *but* for development the menu is hidden then we show a warning
                         if (isLocalNetwork() && this._userRequestedMenuVisible === false) {
@@ -932,7 +932,7 @@ export class NeedleMenuElement extends HTMLElementBase {
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
         if (!visible) {
-            if (!_$SVo() || debugNonCommercial) {
+            if (!_ERXbX() || debugNonCommercial) {
                 console.warn("[Needle Engine] You need a commercial license to hide the Needle Engine logo in production.");
                 const localNetwork = isLocalNetwork()
                 if (!localNetwork) return;

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

@@ -1,6 +1,6 @@
 import { needleLogoOnlySVG } from "../assets/index.js"
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { _$SVo, _RTmnPEj, nOo } from "../engine_license.js";
+import { _ERXbX, _owM, _jcZJFQ } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { LoadingProgressArgs } from "../engine_setup.js";
 import { getParam } from "../engine_utils.js";
@@ -205,7 +205,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
         }
 
 
-        const hasLicense = _RTmnPEj();
+        const hasLicense = _owM();
         if (!existing) {
             this._loadingElement.style.position = "absolute";
             this._loadingElement.style.width = "100%";
@@ -373,7 +373,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
 
     // private async handleRuntimeLicense(loadingElement: HTMLElement) {
     //     // First check if we have a commercial license
-    //     let commercialLicense = _$SVo();
+    //     let commercialLicense = _ERXbX();
     //     // if it's the case then we don't need to perform a runtime check
     //     if (commercialLicense) return;
 
@@ -393,10 +393,10 @@ export class EngineLoadingView implements ILoadingViewHandler {
     //     loadingElement.appendChild(nonCommercialContainer);
 
     //     // Use the runtime license check
-    //     if (!isDevEnvironment() && nOo) {
+    //     if (!isDevEnvironment() && _jcZJFQ) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await nOo;
-    //         commercialLicense = _$SVo();
+    //         await _jcZJFQ;
+    //         commercialLicense = _ERXbX();
     //     }
     //     if (commercialLicense) return;
     //     nonCommercialContainer.style.transition = "opacity .5s ease-in-out";

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

@@ -3,7 +3,7 @@ import type { Texture } from "three";
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { _$SVo, Telemetry } from "../engine_license.js";
+import { _ERXbX, Telemetry } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
@@ -579,7 +579,7 @@ export class NeedleEngineWebComponent extends HTMLElementBase implements INeedle
 
 
         // Loading start events
-        const allowOverridingDefaultLoading = _$SVo();
+        const allowOverridingDefaultLoading = _ERXbX();
         // default loading can be overriden by calling preventDefault in the onload start event
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {

package/src/engine/xr/NeedleXRSession.ts

@@ -710,8 +710,8 @@ export class NeedleXRSession implements INeedleXRSession {
                     const defaultInit: XRSessionInit = this.getDefaultSessionInit(mode);
                     const domOverlayElement = getDOMOverlayElement(context.domElement);
                     if (domOverlayElement && !DeviceUtilities.isQuest()) { // excluding quest since dom-overlay breaks sessiongranted
+                        // 'dom-overlay' is already part of the default optional features — only the root needs to be assigned
                         defaultInit.domOverlay = { root: domOverlayElement };
-                        defaultInit.optionalFeatures!.push('dom-overlay');
                     }
                     init = {
                         ...defaultInit,
@@ -761,6 +761,13 @@ export class NeedleXRSession implements INeedleXRSession {
             }
         }
         this.invokeSessionRequestStart(mode, init, context ?? Context.Current);
+        // Features are collected from multiple places (default init, user init, component onBeforeXR
+        // callbacks, session request hooks) — make sure the final request contains no duplicates and
+        // no optional feature that is already required
+        const requiredFeatures = Array.from(new Set(init.requiredFeatures));
+        const optionalFeatures = Array.from(new Set(init.optionalFeatures)).filter(f => !requiredFeatures.includes(f));
+        init.requiredFeatures = requiredFeatures;
+        init.optionalFeatures = optionalFeatures;
         if (debug) showBalloonMessage("Requesting " + mode + " session (" + Date.now() + ")");
         Telemetry.sendEvent(Context.Current, "xr", {
             action: "session_request",
@@ -776,9 +783,19 @@ export class NeedleXRSession implements INeedleXRSession {
             if (e?.code === 9) {
                 // NotSupportedError: surface the platform's reason if it provides one
                 // (e.g. which required feature is unsupported) instead of only a generic hint
-                const reason = typeof e?.message === "string" && e.message.length > 0
+                let reason = typeof e?.message === "string" && e.message.length > 0
                     ? e.message
                     : "Make sure you allow the required permissions.";
+                if (!init.requiredFeatures?.length) {
+                    // All requested features are optional, so the session *configuration* can not be
+                    // the reason for the rejection (the platform message claiming so is misleading):
+                    // the browser or device is blocking the session mode itself
+                    reason = mode === "immersive-ar"
+                        ? "AR seems to be blocked or unavailable on this device. Check the browser's site settings (Augmented Reality and Camera permissions) and that 'Google Play Services for AR' is installed and up to date."
+                        : "VR seems to be blocked or unavailable on this device. Check the browser's site settings (Virtual Reality permission).";
+                    if (window.self !== window.top) reason += " Embedded pages need allow=\"xr-spatial-tracking; camera\" on the iframe.";
+                    console.warn(`[Needle] The ${mode} session request was rejected although all requested features are optional — the device or browser is blocking the session mode itself, not the session configuration.`);
+                }
                 showBalloonWarning(`Couldn't start XR session: ${reason}`, { duration: 30_000 });
             }
             console.log("If the specified XR configuration is not supported (e.g. entering AR doesnt work) - make sure you access the website on a secure connection (HTTPS) and your device has the required permissions (e.g. camera access)");

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { _$SVo } from "../engine_license.js";
+import { _ERXbX } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (_$SVo()) {
+        if (_ERXbX()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -3,7 +3,7 @@ import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "t
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { findObjectOfType } from "../../../engine/engine_components.js";
-import { _RTmnPEj } from "../../../engine/engine_license.js";
+import { _owM } from "../../../engine/engine_license.js";
 import { serializable } from "../../../engine/engine_serialization.js";
 import { getFormattedDate, Progress } from "../../../engine/engine_time_utils.js";
 import { DeviceUtilities, getParam } from "../../../engine/engine_utils.js";
@@ -277,7 +277,7 @@ export class USDZExporter extends Behaviour {
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
 
-        if (!_RTmnPEj()) {
+        if (!_owM()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!_RTmnPEj()) {
+                        if (!_owM()) {
                             console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
                         }
                         else {
@@ -697,7 +697,7 @@ export class USDZExporter extends Behaviour {
     private buildQuicklookOverlay(): CustomBranding {
         const obj: CustomBranding = {};
         if (this.customBranding) Object.assign(obj, this.customBranding);
-        if (!_RTmnPEj()) {
+        if (!_owM()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";