@needle-tools/engine 5.1.4 → 5.1.5

package/src/engine/engine_license.ts

@@ -9,19 +9,19 @@ import { DeviceUtilities, getParam } from "./engine_utils.js";
 
 const debug = getParam("__debuglic__");
 
-const _$mvpTzyNE: ((result: boolean) => void)[] = [];
+const $qnPTnU: ((result: boolean) => void)[] = [];
 
 // DO NOT EDIT MANUALLY
-let __GWcsL: string = "";
+let __IsXDNQb: string = "";
 // eslint-disable-next-line prefer-const
-let MbNaU: string = "";
+let $ZDwS: string = "";
 
 if (debug) {
-    console.log("License Type: " + __GWcsL);
-    if (MbNaU) {
-        console.log("License JWT: " + MbNaU);
+    console.log("License Type: " + __IsXDNQb);
+    if ($ZDwS) {
+        console.log("License JWT: " + $ZDwS);
         try {
-            const payload = JSON.parse(atob(MbNaU.split(".")[1].replace(/-/g, '+').replace(/_/g, '/')));
+            const payload = JSON.parse(atob($ZDwS.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 KLaEb() {
-    switch (__GWcsL) {
+export function otIKt() {
+    switch (__IsXDNQb) {
         case "pro":
         case "enterprise":
             return true;
@@ -42,8 +42,8 @@ export function KLaEb() {
 }
 
 /** @internal */
-export function wPA() {
-    switch (__GWcsL) {
+export function _gNHPUn() {
+    switch (__IsXDNQb) {
         case "indie":
             return true;
     }
@@ -51,8 +51,8 @@ export function wPA() {
 }
 
 /** @internal */
-export function _bEUa() {
-    switch (__GWcsL) {
+export function $aiMWPAef() {
+    switch (__IsXDNQb) {
         case "edu":
             return true;
     }
@@ -60,20 +60,20 @@ export function _bEUa() {
 }
 
 /** @internal */
-export function __QhCnOwd() {
-    return KLaEb() || wPA() || _bEUa();
+export function $PLKRCQIf() {
+    return otIKt() || _gNHPUn() || $aiMWPAef();
 }
 
 
 /** @internal */
-export function __jFACNo(cb: (result: boolean) => void) {
-    if (KLaEb() || wPA() || _bEUa())
+export function _$sDvKPqp(cb: (result: boolean) => void) {
+    if (otIKt() || _gNHPUn() || $aiMWPAef())
         return cb(true);
-    _$mvpTzyNE.push(cb);
+    $qnPTnU.push(cb);
 }
 
-function $VtYVpv(result: boolean) {
-    for (const cb of _$mvpTzyNE) {
+function _$wgFzq(result: boolean) {
+    for (const cb of $qnPTnU) {
         try {
             cb(result);
         }
@@ -88,7 +88,7 @@ function $VtYVpv(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 _$LkmsJYaP = {
+const __lgCVJdwb = {
     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 _crQsWky(jwt: string): Promise<string | null> {
+async function __ZcVBPZ(jwt: string): Promise<string | null> {
     if (!jwt) return null;
     try {
         const parts = jwt.split(".");
@@ -122,7 +122,7 @@ async function _crQsWky(jwt: string): Promise<string | null> {
 
         const key = await crypto.subtle.importKey(
             "jwk",
-            _$LkmsJYaP,
+            __lgCVJdwb,
             { name: "ECDSA", namedCurve: "P-256" },
             false,
             ["verify"]
@@ -182,24 +182,24 @@ async function _crQsWky(jwt: string): Promise<string | null> {
 }
 
 /** Verify the injected JWT and update the license type if valid.
- * The engine ONLY trusts the JWT — the plain __GWcsL string is ignored. */
+ * The engine ONLY trusts the JWT — the plain __IsXDNQb string is ignored. */
 let _jwtVerificationPromise: Promise<void> | undefined = undefined;
-async function $yHAwAkQ(): Promise<void> {
-    // NOTE: do NOT add an `if (!MbNaU) return` guard here.
+async function _$BXZmXmG(): Promise<void> {
+    // NOTE: do NOT add an `if (!$ZDwS) 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 = MbNaU;
+    const jwt = $ZDwS;
     // Clear after reading — this reassignment also prevents esbuild from
     // constant-folding the variable (it now has multiple assignment sites).
-    MbNaU = "";
-    const verifiedType = await _crQsWky(jwt);
+    $ZDwS = "";
+    const verifiedType = await __ZcVBPZ(jwt);
     if (verifiedType) {
-        __GWcsL = verifiedType;
+        __IsXDNQb = verifiedType;
         if (debug) console.log("License type set from verified JWT: " + verifiedType);
-        $VtYVpv(__QhCnOwd());
+        _$wgFzq($PLKRCQIf());
     }
     else {
-        __GWcsL = "basic";
+        __IsXDNQb = "basic";
         if (debug && jwt) console.warn("JWT verification failed — license reset to basic");
     }
 }
@@ -650,18 +650,18 @@ export namespace Telemetry {
 }
 
 
-export function _$auU() {
+export function _$zEuYwGe() {
 
-    if(__GWcsL === "") __GWcsL = "basic";
+    if(__IsXDNQb === "") __IsXDNQb = "basic";
 
     // Start JWT verification — must be here (not top-level) to avoid tree-shaking
-    _jwtVerificationPromise = $yHAwAkQ();
+    _jwtVerificationPromise = _$BXZmXmG();
 
     Telemetry.init();
     ContextRegistry.registerCallback(ContextEvent.ContextRegistered, evt => {
-        $aCj(evt.context);
-        __DWQeDNnb(evt.context);
-        setTimeout(() => Zanq(evt.context), 2000);
+        __mJiL(evt.context);
+        $NDvkjBNe(evt.context);
+        setTimeout(() => $vIjopOW(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 _$auU() {
     });
 }
 
-export let _$OuASD: Promise<void> | undefined = undefined;
+export let $oUFilKP: Promise<void> | undefined = undefined;
 let applicationIsForbidden = false;
 let applicationForbiddenText = "";
-async function _iRYfLx() {
+async function $IWNB() {
     // Only perform the runtime license check once
-    if (_$OuASD) return _$OuASD;
+    if ($oUFilKP) return $oUFilKP;
     // Wait for JWT verification to complete first (if running)
     if (_jwtVerificationPromise) {
         await _jwtVerificationPromise;
     }
-    if (__GWcsL === "basic") {
+    if (__IsXDNQb === "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 _iRYfLx() {
             if (res?.status === 200) {
                 applicationIsForbidden = false;
                 if (debug) console.log("License check succeeded");
-                __GWcsL = "pro";
-                $VtYVpv(true);
+                __IsXDNQb = "pro";
+                _$wgFzq(true);
             }
             else if (res?.status === 403) {
-                $VtYVpv(false);
+                _$wgFzq(false);
                 applicationIsForbidden = true;
                 applicationForbiddenText = await res.text();
             }
             else {
-                $VtYVpv(false);
+                _$wgFzq(false);
                 if (debug) console.log("License check failed with status " + res?.status);
             }
         }
         catch (err) {
-            $VtYVpv(false);
+            _$wgFzq(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 \"" + __GWcsL + "\"");
+    else if (debug) console.log("Runtime license check is skipped because license is already applied as \"" + __IsXDNQb + "\"");
 }
-_$OuASD = _iRYfLx();
+$oUFilKP = $IWNB();
 
-async function __DWQeDNnb(ctx: IContext) {
+async function $NDvkjBNe(ctx: IContext) {
     function createForbiddenElement() {
         const div = document.createElement("div");
         div.className = "needle-forbidden";
@@ -779,40 +779,40 @@ async function __DWQeDNnb(ctx: IContext) {
     }, 500)
 }
 
-async function $aCj(ctx: IContext) {
+async function __mJiL(ctx: IContext) {
     try {
-        if (!KLaEb() && !wPA()) {
-            return __POTiHWtw(ctx);
+        if (!otIKt() && !_gNHPUn()) {
+            return $pTRKOi(ctx);
         }
     }
     catch (err) {
         if (debug) console.log("License check failed", err)
-        return __POTiHWtw(ctx)
+        return $pTRKOi(ctx)
     }
-    if (debug) __POTiHWtw(ctx)
+    if (debug) $pTRKOi(ctx)
 }
 
 
 
-async function __POTiHWtw(ctx: IContext) {
+async function $pTRKOi(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 _$OuASD?.catch(() => { });
+    await $oUFilKP?.catch(() => { });
 
 
-    if (KLaEb() || wPA()) return;
-    if (__QhCnOwd() === false) __Pexfzvu();
+    if (otIKt() || _gNHPUn()) return;
+    if ($PLKRCQIf() === false) __GWmHmYep();
 
     // check if the engine is already ready (meaning has finished loading)
     if (isReady) {
-        _fZxtASpV(ctx);
+        xbmulpf(ctx);
     }
     else {
         ctx.domElement.addEventListener("ready", () => {
-            _fZxtASpV(ctx);
+            xbmulpf(ctx);
         });
     }
 }
@@ -820,7 +820,7 @@ async function __POTiHWtw(ctx: IContext) {
 // const licenseElementIdentifier = "needle-license-element";
 // const licenseDuration = 10000;
 // const licenseDelay = 1200;
-function _fZxtASpV(ctx: IContext) {
+function xbmulpf(ctx: IContext) {
 
     const style = `
         position: relative;
@@ -833,7 +833,7 @@ function _fZxtASpV(ctx: IContext) {
         padding: 10px;
         padding-left: 30px;
     `;
-    if (__GWcsL === "edu") {
+    if (__IsXDNQb === "edu") {
         if (navigator.webdriver) {
             console.log("This project is supported by Needle for Education – https://needle.tools");
         }
@@ -890,7 +890,7 @@ function _fZxtASpV(ctx: IContext) {
         }
     }, 1000);
 
-    if (_bEUa()) {
+    if ($aiMWPAef()) {
         const removeDelay = 20_000;
         setTimeout(() => {
             clearInterval(interval);
@@ -899,7 +899,7 @@ function _fZxtASpV(ctx: IContext) {
             const intervalInMinutes = 5;
             setTimeout(() => {
                 if (ctx.domElement.parentNode)
-                    _fZxtASpV(ctx);
+                    xbmulpf(ctx);
             }, 1000 * 60 * intervalInMinutes)
         }, removeDelay);
     }
@@ -910,7 +910,7 @@ function _fZxtASpV(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 __Pexfzvu(_logo?: string) {
+async function __GWmHmYep(_logo?: string) {
     const now = Date.now();
     if (now - lastLogTime < 2000) return;
     lastLogTime = now;
@@ -943,7 +943,7 @@ async function __Pexfzvu(_logo?: string) {
 }
 
 
-async function Zanq(context: IContext) {
+async function $vIjopOW(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 Zanq(context: IContext) {
 
             // current url without query parameters
             const currentUrl = window.location.href.split("?")[0];
-            const license = __GWcsL;
+            const license = __IsXDNQb;
 
             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 { __QhCnOwd } from "./engine_license.js";
+import { $PLKRCQIf } 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 (__QhCnOwd()) {
+        if ($PLKRCQIf()) {
             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 (!__QhCnOwd() && filesizeInMB > maxFreeSizeInMB) {
+        else if (!$PLKRCQIf() && 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_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 { __QhCnOwd } from "./engine_license.js";
+import { $PLKRCQIf } 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 = __QhCnOwd();
+    const canUseCustomLogo = $PLKRCQIf();
 
     // 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/engine_utils_screenshot.ts

@@ -380,6 +380,7 @@ export function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOpt
  * @see {@link saveImage} for downloading data URLs
  * @see {@link ScreenshotOptions} for all available options
  */
+// #region screenshot 2
 export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTexture | ScreenshotOptionsBlob | ScreenshotOptionsShare)
     : Texture | string | null | Promise<Blob | null> | Promise<ScreenshotOptionsShareReturnType> {
 

package/src/engine/engine_utils_screenshot.xr.ts

@@ -29,7 +29,7 @@ NeedleXRSession.onSessionRequestStart(evt => {
 });
 `);
         if (isDevEnvironment()) {
-            showBalloonError("No camera feed available - please request the 'camera-access' feature before starting WebXR or add the ARCameraBackground component to your scene");
+            showBalloonError("No camera feed available - please request the 'camera-access' feature before starting WebXR or add the ARCameraBackground component to your scene", { duration: 300_000 });
         }
         return false;
     }

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 { __QhCnOwd } from "../../engine_license.js";
+import { $PLKRCQIf } 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 && __QhCnOwd()) {
+            if (!this._showNeedleLogo && $PLKRCQIf()) {
                 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 { __QhCnOwd, __jFACNo, Telemetry } from "../../engine_license.js";
+import { $PLKRCQIf, _$sDvKPqp, 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";
@@ -186,6 +186,11 @@ export class NeedleMenu {
         if (args.session.isScreenBasedAR) {
             this._menu["previousParent"] = this._menu.parentNode;
             this._context.arOverlayElement.appendChild(this._menu);
+            // The host defaults to z-index 0 (to not overlay elements outside <needle-engine> in 2D).
+            // In screen-based AR the overlay may be reparented to document.body (e.g. Needle Go App Clip /
+            // Mozilla XR) where the WebXR polyfill's fullscreen canvas wrapper sits at z-index 1 and would
+            // render on top of the menu — visible through the transparent canvas but swallowing all taps.
+            this._menu.style.zIndex = "9999";
             args.session.session.addEventListener("end", this.onExitXR);
 
             // Close the foldout if it's open on entering AR
@@ -194,6 +199,7 @@ export class NeedleMenu {
     }
 
     private onExitXR = () => {
+        this._menu.style.zIndex = "";
         if (this._menu["previousParent"]) {
             this._menu["previousParent"].appendChild(this._menu);
             delete this._menu["previousParent"];
@@ -778,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(() => __jFACNo(res => {
-                if (res == true && __QhCnOwd() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => _$sDvKPqp(res => {
+                if (res == true && $PLKRCQIf() && !debugNonCommercial) {
                     let visible = this._userRequestedLogoVisible;
                     if (visible === undefined) visible = false;
                     this.___onSetLogoVisible(visible);
@@ -830,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 (!__QhCnOwd()) {
+                    if (!$PLKRCQIf()) {
                         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) {
@@ -880,6 +886,7 @@ export class NeedleMenuElement extends HTMLElementBase {
     connectedCallback() {
         this.ensureInitialized();
         window.addEventListener("resize", this.handleSizeChange);
+        this.addEventListener("beforexrselect", this.#onBeforeXRSelect);
         this.handleMenuVisible();
         this._sizeChangeInterval = setInterval(() => this.handleSizeChange(undefined, false), 5000);
         // the dom element is set after initialization runs
@@ -890,11 +897,18 @@ export class NeedleMenuElement extends HTMLElementBase {
     }
     disconnectedCallback() {
         window.removeEventListener("resize", this.handleSizeChange);
+        this.removeEventListener("beforexrselect", this.#onBeforeXRSelect);
         clearInterval(this._sizeChangeInterval);
         this._domElement?.removeEventListener("resize", this.handleSizeChange);
         this._context?.domElement.removeEventListener("click", this.#onClick);
     }
 
+    /** Prevent XR select from firing into the scene (e.g. tap-to-place) when the user
+     * interacts with the menu during screen-based AR (dom-overlay / Needle Go App Clip) */
+    #onBeforeXRSelect = (e: Event) => {
+        e.preventDefault();
+    }
+
     #onClick = (e: Event) => {
         // detect a click outside the opened foldout to automatically close it
         if (!e.defaultPrevented
@@ -918,7 +932,7 @@ export class NeedleMenuElement extends HTMLElementBase {
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
         if (!visible) {
-            if (!__QhCnOwd() || debugNonCommercial) {
+            if (!$PLKRCQIf() || 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.ar-overlay.ts

@@ -29,11 +29,11 @@ export class AROverlayHandler {
         this.arContainer = overlayContainer;
 
         if (DeviceUtilities.isMozillaXR() || DeviceUtilities.isNeedleAppClip()) {
-            const arElements = context.domElement!.children;
-            for (let i = 0; i < arElements?.length; i++) {
-                const el = arElements[i];
-                if (!el) return;
-                if (el === this.arContainer) return;
+            // Copy the live HTMLCollection: appendChild removes elements from it while
+            // iterating, which previously skipped every other element
+            const arElements = Array.from(context.domElement!.children);
+            for (const el of arElements) {
+                if (!el || el === this.arContainer) continue;
                 this._reparentedObjects.push({ el: el, previousParent: el.parentElement });
                 this.arContainer?.appendChild(el);
             }
@@ -47,6 +47,17 @@ export class AROverlayHandler {
                     overlayContainer.style.display = "";
                     overlayContainer.style.visibility = "";
                     document.body.appendChild(overlayContainer);
+                    // Outside the shadow root the container loses its shadow CSS (fullscreen, z-index).
+                    // Without an explicit position it stays static, its z-index is ignored and it doesn't
+                    // create a stacking context — overlay children then compete individually with the
+                    // WebXR polyfill's fullscreen canvas wrapper (z-index 1) and can end up behind the
+                    // transparent canvas: visible, but unable to receive any taps.
+                    overlayContainer.style.position = "fixed";
+                    overlayContainer.style.top = "0";
+                    overlayContainer.style.left = "0";
+                    overlayContainer.style.width = "100%";
+                    overlayContainer.style.height = "100%";
+                    overlayContainer.style.zIndex = "10000";
                 }
             }
             else {
@@ -71,6 +82,23 @@ export class AROverlayHandler {
         }
         this._reparentedObjects.length = 0;
 
+        // Restore the overlay container that was reparented to document.body in onBegin
+        // (the polyfill only restores it when it received the domOverlay root) and remove
+        // the inline styles that replaced its shadow CSS while it was outside the shadow root
+        if (this.arContainer && this.originalDomOverlayParent) {
+            const style = this.arContainer.style;
+            style.position = "";
+            style.top = "";
+            style.left = "";
+            style.width = "";
+            style.height = "";
+            style.zIndex = "";
+            if (this.arContainer.parentNode !== this.originalDomOverlayParent) {
+                this.originalDomOverlayParent.appendChild(this.arContainer);
+            }
+            this.originalDomOverlayParent = null;
+        }
+
         // mozilla XR exit AR fixes
         if (DeviceUtilities.isMozillaXR()) {
             // without the timeout we get errors in mozillas code and can not enter XR again

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 { __QhCnOwd, KLaEb, _$OuASD } from "../engine_license.js";
+import { $PLKRCQIf, otIKt, $oUFilKP } 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 = KLaEb();
+        const hasLicense = otIKt();
         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 = __QhCnOwd();
+    //     let commercialLicense = $PLKRCQIf();
     //     // 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() && _$OuASD) {
+    //     if (!isDevEnvironment() && $oUFilKP) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await _$OuASD;
-    //         commercialLicense = __QhCnOwd();
+    //         await $oUFilKP;
+    //         commercialLicense = $PLKRCQIf();
     //     }
     //     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 { __QhCnOwd, Telemetry } from "../engine_license.js";
+import { $PLKRCQIf, 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 = __QhCnOwd();
+        const allowOverridingDefaultLoading = $PLKRCQIf();
         // 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

@@ -772,11 +772,18 @@ export class NeedleXRSession implements INeedleXRSession {
         this._currentSessionRequestMode = mode;
         /**@type {XRSystem} */
         const newSession = await (this._currentSessionRequest)?.catch(e => {
-            console.error(e, "Code: " + e?.code);
-            if (e?.code === 9) showBalloonWarning("Couldn't start XR session. Make sure you allow the required permissions.")
+            console.error(e, "Code: " + e?.code, "requiredFeatures:", init.requiredFeatures, "optionalFeatures:", init.optionalFeatures);
+            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
+                    ? e.message
+                    : "Make sure you allow the required permissions.";
+                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)");
             const notSecure = location.protocol === 'http:';
-            if (notSecure) showBalloonWarning("XR requires a secure connection (HTTPS)");
+            if (notSecure) showBalloonWarning("XR requires a secure connection (HTTPS)", { duration: 30_000 });
         });
         this._currentSessionRequest = undefined;
         this._currentSessionRequestMode = null;