@needle-tools/engine 5.1.0 → 5.1.1

package/src/engine/xr/NeedleXRSession.ts

@@ -23,6 +23,28 @@ import type { IXRRig } from "./XRRig.js";
 const measure_SessionStartedMarker = "NeedleXRSession onStart";
 const measure_SessionEndedMarker = "NeedleXRSession onEnd";
 
+/**
+ * Whether the `xr-spatial-tracking` permission policy is allowed in the current document.
+ * WebXR APIs (isSessionSupported / requestSession) require it; an embedded page/iframe must
+ * be granted it via the iframe `allow` attribute (delegated from a parent that has it) and/or
+ * a `Permissions-Policy` response header. Returns true when the policy API is unavailable
+ * (can't determine → don't block, preserve prior behavior).
+ * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#allow
+ */
+function isXrSpatialTrackingAllowed(): boolean {
+    try {
+        const doc = globalThis.document as (Document & { permissionsPolicy?: { allowsFeature(f: string): boolean }, featurePolicy?: { allowsFeature(f: string): boolean } }) | undefined;
+        const policy = doc?.permissionsPolicy ?? doc?.featurePolicy;
+        if (policy && typeof policy.allowsFeature === "function") {
+            return policy.allowsFeature("xr-spatial-tracking");
+        }
+    }
+    catch {
+        /* ignore — fall through to default */
+    }
+    return true;
+}
+
 
 /** @link https://developer.mozilla.org/en-US/docs/Web/API/XRFrame/fillPoses */
 declare type FillPosesFunction = (spaces: IterableIterator<XRJointSpace>, referenceSpace: XRSpace, targetArray: Float32Array) => void;
@@ -85,6 +107,10 @@ async function handleSessionGranted() {
     let defaultMode: XRSessionMode = "immersive-vr";
 
     try {
+        // If xr-spatial-tracking isn't allowed in this document (e.g. an embed whose page/iframe
+        // wasn't granted it), XR can't run here — skip the probe so we don't log a
+        // Permissions-Policy violation on load.
+        if (!isXrSpatialTrackingAllowed()) return;
         // In app clips we default to AR
         if (DeviceUtilities.isNeedleAppClip()) {
             defaultMode = "immersive-ar";
@@ -304,7 +330,9 @@ export class NeedleXRSession implements INeedleXRSession {
      *
      * **IMPORTANT**: the resulting URL must exactly match an App Clip experience URL you have registered (with custom card metadata).
      * For this reason the URL is opened as-is, without appending any query parameters.
-     * @link https://appclip.needle.tools
+     *
+     * Note: custom App Clip branding requires an active PRO subscription. See the iOS WebXR App Clip docs (Custom Branding for iOS AR).
+     * @link https://engine.needle.tools/docs/how-to-guides/xr/ios-webxr-app-clip#custom-branding-for-ios-ar
      */
     static get appClipUrl(): string | null { return this._appClipUrl; }
     static set appClipUrl(value: string | null) {
@@ -367,19 +395,49 @@ 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) {
-        // 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);
+    static isSessionSupported(mode: XRSessionMode): Promise<boolean> {
+        // Re-probe when XR devices change (e.g. a headset connects).
+        this.ensureDeviceChangeInvalidation();
+
+        // Cache AND de-duplicate the check by storing the in-flight PROMISE (not just the
+        // resolved value). A burst of callers in the same tick (XR buttons, offer-session,
+        // support checks) then shares ONE underlying navigator.xr.isSessionSupported() call
+        // per mode. Each call otherwise repeats the `xr-spatial-tracking` Permissions-Policy
+        // check and floods the console. It also keeps user-input onclick checks fast.
+        const cached = this._sessionSupportedCache[mode];
+        if (cached !== undefined) return cached;
+
+        let result: Promise<boolean>;
+        // isSessionSupported() requires the `xr-spatial-tracking` permission policy to be
+        // allowed in this document. In an embed whose page/iframe wasn't granted it, calling
+        // the API logs a Permissions-Policy violation and can't succeed — so skip the call
+        // and report "unsupported" instead of spamming the console.
+        // See https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#allow
+        if (!isXrSpatialTrackingAllowed()) {
+            if (debug) console.warn("[WebXR] xr-spatial-tracking is not allowed in this document — reporting XR as unsupported. The embedding page/iframe must grant the policy.");
+            result = Promise.resolve(false);
+        }
+        else {
+            result = (this.xrSystem?.isSessionSupported(mode) ?? Promise.resolve(false))
+                .catch(err => { if (debug) console.error(err); return false; });
+        }
+        this._sessionSupportedCache[mode] = result;
+        return result;
+    }
+
+    private static _sessionSupportedCache: { [mode in XRSessionMode]?: Promise<boolean> } = {};
+    private static _deviceChangeHooked = false;
+    /** Invalidate the support cache when the set of XR devices changes, so a newly
+     * connected headset is picked up by the next isSessionSupported() call. */
+    private static ensureDeviceChangeInvalidation() {
+        if (this._deviceChangeHooked) return;
+        this._deviceChangeHooked = true;
+        try {
+            this.xrSystem?.addEventListener?.("devicechange", () => { this._sessionSupportedCache = {}; });
+        }
+        catch { /* xrSystem may not support events; cache simply won't be invalidated */ }
     }
 
-    private static _sessionSupportedCache: { [mode in XRSessionMode]?: boolean } = {};
-
     private static _currentSessionRequest?: Promise<XRSession>;
     private static _activeSession: NeedleXRSession | null;
 
@@ -650,7 +708,7 @@ export class NeedleXRSession implements INeedleXRSession {
             // Setup VR initialization parameters
             case "immersive-ar":
                 {
-                    const supported = await this.xrSystem?.isSessionSupported('immersive-ar')
+                    const supported = await NeedleXRSession.isSessionSupported('immersive-ar')
                     if (supported !== true) {
                         console.error(mode + ' is not supported by this browser.');
                         return null;
@@ -671,7 +729,7 @@ export class NeedleXRSession implements INeedleXRSession {
             // Setup AR initialization parameters
             case "immersive-vr":
                 {
-                    const supported = await this.xrSystem?.isSessionSupported('immersive-vr')
+                    const supported = await NeedleXRSession.isSessionSupported('immersive-vr')
                     if (supported !== true) {
                         console.error(mode + ' is not supported by this browser.');
                         return null;

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 { $iujBhf } from "../engine_license.js";
+import { $Mhcqc } 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 ($iujBhf()) {
+        if ($Mhcqc()) {
             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 { rXELCf } from "../../../engine/engine_license.js";
+import { __dSkNu } 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 (!rXELCf()) {
+        if (!__dSkNu()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!rXELCf()) {
+                        if (!__dSkNu()) {
                             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 (!rXELCf()) {
+        if (!__dSkNu()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";

package/src/engine-components/webxr/WebXR.ts

@@ -237,22 +237,30 @@ export class WebXR extends Behaviour {
         // Showing the QuickLook button depends on whether we're on iOS or visionOS –
         // on iOS we have AppClip support, so we don't need QuickLook button there,
         // while on visionOS we use QuickLook for AR experiences for now (unless it happens to have WebXR support by then).
-        navigator.xr?.isSessionSupported("immersive-ar").catch(() => false).then((arSupported) => {
-
-            const isVisionOSFallback = DeviceUtilities.isVisionOS() && !arSupported;
-            
-            if (this.useQuicklookExport || isVisionOSFallback) {
-                const existingUSDZExporter = GameObject.findObjectOfType(USDZExporter);
-                if (!existingUSDZExporter) {
-                    // if no USDZ Exporter is found we add one and assign the scene to be exported
-                    if (debug) console.log("WebXR: Adding USDZExporter");
-                    this._usdzExporter = GameObject.addComponent(this.gameObject, USDZExporter);
-                    this._usdzExporter.objectToExport = this.context.scene;
-                    this._usdzExporter.autoExportAnimations = true;
-                    this._usdzExporter.autoExportAudioSources = true;
-                }
+        const addUsdzExporterIfMissing = () => {
+            const existingUSDZExporter = GameObject.findObjectOfType(USDZExporter);
+            if (!existingUSDZExporter) {
+                // if no USDZ Exporter is found we add one and assign the scene to be exported
+                if (debug) console.log("WebXR: Adding USDZExporter");
+                this._usdzExporter = GameObject.addComponent(this.gameObject, USDZExporter);
+                this._usdzExporter.objectToExport = this.context.scene;
+                this._usdzExporter.autoExportAnimations = true;
+                this._usdzExporter.autoExportAudioSources = true;
             }
-        });
+        };
+        // QuickLook is added when explicitly requested, or as the visionOS fallback when
+        // WebXR AR isn't available. Only probe XR support on visionOS (the only case that
+        // consumes the result) and go through the cached NeedleXRSession.isARSupported() so
+        // we don't eagerly hit navigator.xr on every enable — that probe trips the
+        // `xr-spatial-tracking` Permissions-Policy in embeds that weren't granted it.
+        if (this.useQuicklookExport) {
+            addUsdzExporterIfMissing();
+        }
+        else if (DeviceUtilities.isVisionOS()) {
+            NeedleXRSession.isARSupported().then((arSupported) => {
+                if (!arSupported) addUsdzExporterIfMissing();
+            });
+        }
 
         this.handleCreatingHTML();
         this.handleOfferSession();