@needle-tools/engine 5.1.0-next.1780579670.dramatic-pierogi.b8fa941 → 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";
@@ -291,6 +317,51 @@ export class NeedleXRSession implements INeedleXRSession {
     static get currentSessionRequest(): XRSessionMode | null { return this._currentSessionRequestMode; }
     private static _currentSessionRequestMode: XRSessionMode | null = null;
 
+    /** Base URL for branded Needle AppClip experiences */
+    private static readonly appClipBaseUrl = "https://appclip.needle.tools/x/";
+    private static _appClipUrl: string | null = null;
+    /**
+     * Optionally provide a custom Needle AppClip experience to open on iOS instead of the default Needle AppClip.
+     * This enables custom App Clip card branding (your own title and image) when launching AR on iPhone and iPad.
+     *
+     * You can provide either:
+     * - the full URL, e.g. `https://appclip.needle.tools/x/your-experience`
+     * - or just the experience id, e.g. `your-experience` (expanded to `https://appclip.needle.tools/x/your-experience`)
+     *
+     * **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.
+     *
+     * 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) {
+        if (!value) {
+            this._appClipUrl = null;
+            return;
+        }
+        const trimmed = value.trim();
+        // accept a full URL as-is, otherwise treat the value as an experience id and expand it using the base url
+        this._appClipUrl = /^https?:\/\//i.test(trimmed)
+            ? trimmed
+            : this.appClipBaseUrl + trimmed.replace(/^\/+/, "");
+    }
+
+    /**
+     * @internal
+     * Returns the AppClip launch URL to open (or prefetch) on iOS for the current page.
+     * When a custom {@link appClipUrl} is set this is the branded experience URL (opened as-is so it matches the registered URL);
+     * otherwise it is the default Needle AppClip launch URL with the current page forwarded via the `url` parameter.
+     */
+    static getAppClipLaunchUrl(): URL {
+        if (this._appClipUrl) return new URL(this._appClipUrl);
+        // Forward to the default Needle AppClip experience (using the apple.com url the appclip overlay shows immediately)
+        // alternative: `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);
+        return url;
+    }
+
     /**
      * @returns the active @type {NeedleXRSession} (if any active) or null
      */
@@ -324,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;
 
@@ -498,10 +599,10 @@ export class NeedleXRSession implements INeedleXRSession {
                 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);
+                // Forward to the AppClip experience. By default this is the Needle AppClip; a custom branded
+                // experience can be set via NeedleXRSession.appClipUrl (which is then opened as-is so it matches the registered URL).
+                const customAppClip = NeedleXRSession.appClipUrl !== null;
+                const url = NeedleXRSession.getAppClipLaunchUrl();
                 const urlStr = url.toString();
 
                 Telemetry.sendEvent(Context.Current, "xr", {
@@ -513,12 +614,15 @@ export class NeedleXRSession implements INeedleXRSession {
                 try {
                     console.debug("iOS device detected - opening Needle App Clip for AR experience", { mode, init, url });
 
-                    // Prewarm the appclip by opening the URL
+                    // Prewarm the appclip by opening the URL (with an extra ?prewarm=1 param) to fetch the app clip
+                    // metadata faster - this fixes a double-tap issue on iOS.
                     // 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;
+                    // We also skip prewarming for a custom branded experience: that URL must match the registered
+                    // App Clip experience URL exactly, so we must not append any query parameters to it.
+                    const key = "appclip-prewarm:" + url.origin;
+                    const allowMultipleNavigations = !customAppClip && sessionStorage.getItem(key) === null;
                     if (allowMultipleNavigations) {
                         const secondUrl = new URL(url);
                         secondUrl.searchParams.set("prewarm", "1");
@@ -604,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;
@@ -625,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 { __EOmPHdLs } 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 (__EOmPHdLs()) {
+        if ($Mhcqc()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine/xr/init.ts

@@ -12,9 +12,8 @@ export function initXR() {
 
     if (DeviceUtilities.isiOS()) {
 
-        // Prefetch
-        const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
-        url.searchParams.set("url", location.href);
+        // Prefetch (uses the custom branded AppClip experience if NeedleXRSession.appClipUrl is set, otherwise the default Needle AppClip)
+        const url = NeedleXRSession.getAppClipLaunchUrl();
         const urlStr = url.toString();
         fetch(urlStr, { method: "HEAD", mode: "no-cors" }).catch(() => {
             // appclip prefetch - to get metadata faster on iOS devices, this seems to fix the double tap issue when opening the appclip for AR sessions.

package/src/engine-components/Component.ts

@@ -1107,7 +1107,8 @@ export abstract class Component implements IComponent, EventTarget,
         this.__didCompleteStart = false;
         this.__inEnableOrDisableCallback = false;
         this.__didEnable = false;
-        this.__isEnabled = undefined;
+        // Preserve copied/constructor-assigned enabled state while resetting lifecycle flags.
+        // Cloned disabled components must not fall back to the default enabled=true state.
         this.__destroyed = false;
         this._internalInit(init);
         return this;
@@ -1165,6 +1166,17 @@ export abstract class Component implements IComponent, EventTarget,
         }
         this.__didEnable = true;
         this.__isEnabled = true;
+        // Enforce "enabled + not-yet-started ⇒ queued for start". A component can be
+        // re-enabled before it ever started — e.g. removed from the scene (which
+        // strips it from new_script_start via processRemoveFromScene) and then
+        // re-activated through a path other than GameObject.add (raw scene re-add +
+        // setActive, a parent activeInHierarchy flip, …). Those paths re-run onEnable
+        // but never re-enqueue start, leaving the component enabled+active but with
+        // start() never called. Re-queue it here so processStart picks it up.
+        if (!this.__didStart) {
+            const startQueue = this.context?.new_script_start;
+            if (startQueue && !startQueue.includes(this)) startQueue.push(this);
+        }
         this.__inEnableOrDisableCallback = true;
         this.onEnable();
         this.__inEnableOrDisableCallback = false;

package/src/engine-components/ContactShadows.ts

@@ -83,7 +83,7 @@ type FitParameters = {
  */
 export class ContactShadows extends Behaviour {
 
-    private static readonly _instances: Map<Context, ContactShadows> = new Map();
+    private static readonly _instances: WeakMap<Context, ContactShadows> = new WeakMap();
     /**
      * Create contact shadows for the scene. Automatically fits the shadows to the scene.  
      * The instance of contact shadows will be created only once.  
@@ -179,8 +179,9 @@ export class ContactShadows extends Behaviour {
      * in which case ContactShadows scale would affect the projection
      **/
     private readonly shadowsRoot: IGameObject = new Object3D() as IGameObject;
-    private shadowCamera?: OrthographicCamera;
     private readonly shadowGroup: Group = new Group();
+    
+    private shadowCamera?: OrthographicCamera;
 
     private renderTarget?: WebGLRenderTarget;
     private renderTargetBlur?: WebGLRenderTarget;
@@ -240,19 +241,86 @@ export class ContactShadows extends Behaviour {
         if (debug) console.log("Fitted shadows to scene", this.shadowsRoot.scale.clone());
     }
 
+    /**
+     * Call to update the shadows immediately. Only needed if `manualUpdate` is enabled, usually the shadows will update automatically when the scene changes or when the component is enabled.
+     */
+    renderShadowsNow() {
+        this._renderShadows();
+    }
 
     /** @internal */
     awake() {
         ContactShadows._instances.set(this.context, this);
-        this.shadowsRoot.hideFlags = HideFlags.DontExport;
+    }
 
+    /** @internal */
+    onEnable(): void {
+        this.shadowsRoot.hideFlags = HideFlags.DontExport;
         // ignore self for autofitting
         setAutoFitEnabled(this.shadowsRoot, false);
+
+        this._needsUpdate = true;
+        this.autoCleanup(this.context.events.on("scene-content-changed", () => {
+            if (!this.autoFit) return;
+            this._needsFit = true;
+            this._needsUpdate = true;
+        }));
+
+        if (this.autoFit) this.fitShadows();
+        else this.applyMinSize();
     }
 
+    /** @internal */
+    onDestroy(): void {
+        if (debug) console.warn("Destroying ContactShadows on " + this.gameObject.name);
+
+        const instance = ContactShadows._instances.get(this.context);
+        if (instance === this) {
+            ContactShadows._instances.delete(this.context);
+        }
+
+        // dispose the render targets
+        this.renderTarget?.dispose();
+        this.renderTargetBlur?.dispose();
+
+        // dispose the materials
+        this.depthMaterial?.dispose();
+        this.horizontalBlurMaterial?.dispose();
+        this.verticalBlurMaterial?.dispose();
+
+        // dispose the geometries
+        this.blurPlane?.geometry.dispose();
+        this.plane?.geometry.dispose();
+        this.occluderMesh?.geometry.dispose();
+    }
 
     /** @internal */
-    start(): void {
+    onBeforeRender(_frame: XRFrame | null): void {
+
+        if (this._needsFit && this.autoFit) {
+            this._needsFit = false;
+            this.fitShadows();
+        }
+
+        if (this.manualUpdate) {
+            if (!this._needsUpdate) return;
+        }
+        this._needsUpdate = false;
+        this._renderShadows();
+    }
+
+    private _ensureSetup() {
+
+        // Make sure the shadows root is parented to the game object. This is needed for the shadows to be in the correct position and scale relative to the game object. We need to do this before checking if the materials are set up because some properties (e.g. darkness) can be changed in the editor before the component is enabled, so we want to avoid re-creating everything in that case.
+        if (this.shadowsRoot.parent !== this.gameObject) {
+            this.gameObject.add(this.shadowsRoot);
+        }
+
+        // Check if everything is already set up. We need to do this because some properties (e.g. darkness) can be changed in the editor before the component is enabled, so we want to avoid re-creating everything in that case.
+        if (this.depthMaterial && this.horizontalBlurMaterial && this.verticalBlurMaterial && this.planeMaterial) {
+            return;
+        }
+
         if (debug) console.log("Create ContactShadows on " + this.gameObject.name, this)
 
         this.gameObject.add(this.shadowsRoot);
@@ -363,54 +431,11 @@ export class ContactShadows extends Behaviour {
         this.verticalBlurMaterial.depthTest = false;
 
         this.shadowGroup.visible = false;
-
-        if (this.autoFit) this.fitShadows();
-        else this.applyMinSize();
     }
 
-    onEnable(): void {
-        this._needsUpdate = true;
-        this.autoCleanup(this.context.events.on("scene-content-changed", () => {
-            if (!this.autoFit) return;
-            this._needsFit = true;
-            this._needsUpdate = true;
-        }));
-    }
+    private _renderShadows() {
 
-    /** @internal */
-    onDestroy(): void {
-        const instance = ContactShadows._instances.get(this.context);
-        if (instance === this) {
-            ContactShadows._instances.delete(this.context);
-        }
-
-        // dispose the render targets
-        this.renderTarget?.dispose();
-        this.renderTargetBlur?.dispose();
-
-        // dispose the materials
-        this.depthMaterial?.dispose();
-        this.horizontalBlurMaterial?.dispose();
-        this.verticalBlurMaterial?.dispose();
-
-        // dispose the geometries
-        this.blurPlane?.geometry.dispose();
-        this.plane?.geometry.dispose();
-        this.occluderMesh?.geometry.dispose();
-    }
-
-    /** @internal */
-    onBeforeRender(_frame: XRFrame | null): void {
-
-        if (this._needsFit && this.autoFit) {
-            this._needsFit = false;
-            this.fitShadows();
-        }
-
-        if (this.manualUpdate) {
-            if (!this._needsUpdate) return;
-        }
-        this._needsUpdate = false;
+        this._ensureSetup();
 
         if (!this.renderTarget || !this.renderTargetBlur ||
             !this.depthMaterial || !this.shadowCamera ||
@@ -536,6 +561,7 @@ export class ContactShadows extends Behaviour {
         scene.background = initialBackground;
         renderer.xr.enabled = prevXRState;
         this.context.scene.matrixWorldAutoUpdate = prevSceneMatrixAutoUpdate;
+
     }
 
     // renderTarget --> blurPlane (horizontalBlur) --> renderTargetBlur --> blurPlane (verticalBlur) --> renderTarget

package/src/engine-components/GroundProjection.ts

@@ -1,4 +1,4 @@
-import { CubeUVReflectionMapping, ShaderMaterial, Texture } from "three";
+import { CubeUVReflectionMapping, Euler, Matrix3, Matrix4, ShaderMaterial, Texture } from "three";
 import { GroundedSkybox as GroundProjection } from 'three/examples/jsm/objects/GroundedSkybox.js';
 
 import { Gizmos } from "../engine/engine_gizmos.js";
@@ -21,8 +21,13 @@ type GroundProjectionShaderUniforms = {
     needleGroundProjectionBlending: { value: number };
     needleGroundProjectionAlphaFactor: { value: number };
     needleGroundProjectionBackgroundIntensity: { value: number };
+    needleGroundProjectionBackgroundRotation: { value: Matrix3 };
 };
 
+// Reused per-frame to build the background-rotation matrix without allocating in onBeforeRender.
+const _backgroundRotationEuler = new Euler();
+const _backgroundRotationMatrix = new Matrix4();
+
 const needleCubeUvMapVarying = /* glsl */`
 #ifdef NEEDLE_USE_CUBE_UV_MAP
 varying vec3 vNeedleGroundProjectionWorldDirection;
@@ -79,7 +84,10 @@ const needleCubeUvMapFragment = /* glsl */`
 
     #endif
 
-    sampledDiffuseColor.rgb *= mix(1.0, needleGroundProjectionBackgroundIntensity, needleGroundProjectionBlurFactorValue);
+    // Apply backgroundIntensity uniformly across the whole projection (center included), matching how the
+    // skybox applies it (backgroundCube.glsl: texColor.rgb *= backgroundIntensity). Only the blurriness
+    // ramps toward the horizon - the intensity must not.
+    sampledDiffuseColor.rgb *= needleGroundProjectionBackgroundIntensity;
     diffuseColor *= sampledDiffuseColor;
 
 #endif
@@ -122,7 +130,8 @@ function getGroundProjectionShaderUniforms(material: GroundProjectionMaterial):
         needleGroundProjectionBlurriness: { value: 0 },
         needleGroundProjectionBlending: { value: 0 },
         needleGroundProjectionAlphaFactor: { value: 1 },
-        needleGroundProjectionBackgroundIntensity: { value: 1 }
+        needleGroundProjectionBackgroundIntensity: { value: 1 },
+        needleGroundProjectionBackgroundRotation: { value: new Matrix3() }
     };
 }
 
@@ -133,15 +142,25 @@ function configureGroundProjectionMaterial(material: GroundProjectionMaterial, t
         shader.uniforms.needleGroundProjectionBlending = projectionUniforms.needleGroundProjectionBlending;
         shader.uniforms.needleGroundProjectionAlphaFactor = projectionUniforms.needleGroundProjectionAlphaFactor;
         shader.uniforms.needleGroundProjectionBackgroundIntensity = projectionUniforms.needleGroundProjectionBackgroundIntensity;
+        shader.uniforms.needleGroundProjectionBackgroundRotation = projectionUniforms.needleGroundProjectionBackgroundRotation;
 
         shader.vertexShader = shader.vertexShader
-            .replace("#include <uv_pars_vertex>", `#include <uv_pars_vertex>\n${needleCubeUvMapVarying}`)
+            .replace("#include <uv_pars_vertex>", `#include <uv_pars_vertex>\n${needleCubeUvMapVarying}
+#ifdef NEEDLE_USE_CUBE_UV_MAP
+uniform mat3 needleGroundProjectionBackgroundRotation;
+#endif`)
             .replace(
                 "#include <worldpos_vertex>",
                 `#include <worldpos_vertex>
 #ifdef NEEDLE_USE_CUBE_UV_MAP
-	// GroundedSkybox mirrors geometry on Z, so undo that before deriving the sampling direction.
-	vNeedleGroundProjectionWorldDirection = transformDirection( vec3( position.x, position.y, -position.z ), modelMatrix );
+	// Sample the environment in the fragment's actual world direction. GroundedSkybox mirrors the geometry
+	// on Z (geometry.scale(1,1,-1)) and that mirrored vertex IS the on-screen direction; the skybox and
+	// environment lighting are likewise sampled in true world directions. So we must NOT undo the mirror
+	// here - doing so reflects the sampling azimuth and flips the panorama left-right vs. the skybox.
+	// backgroundRotation is applied to the sampling direction (exactly like the skybox does in
+	// backgroundCube.glsl), NOT by rotating the mesh - that keeps the floor flat and matches the skybox at
+	// the horizon for any background rotation.
+	vNeedleGroundProjectionWorldDirection = needleGroundProjectionBackgroundRotation * transformDirection( position, modelMatrix );
 #endif`
             );
 
@@ -271,6 +290,25 @@ export class GroundProjectedEnv extends Behaviour {
     private _projection?: GroundProjection;
     private _watcher?: Watch;
 
+    /** The scene's real backgroundBlurriness, stored while we temporarily override it for the render. */
+    private _savedBackgroundBlur: number | null = null;
+
+    /** pre_render_callback: force the skybox blur just before the render (after all component onBeforeRender). */
+    private readonly _forceBackgroundBlur = (_frame?: XRFrame | null) => {
+        if (this._savedBackgroundBlur !== null) return; // already overriding (safety)
+        if (!(this.scene.background instanceof Texture)) return; // no skybox to blur
+        const current = this.scene.backgroundBlurriness ?? 0;
+        this._savedBackgroundBlur = current;
+        this.scene.backgroundBlurriness = 1;
+    };
+
+    /** post_render_callback: restore the scene's real blur right after the render. */
+    private readonly _restoreBackgroundBlur = () => {
+        if (this._savedBackgroundBlur === null) return;
+        this.scene.backgroundBlurriness = this._savedBackgroundBlur;
+        this._savedBackgroundBlur = null;
+    };
+
 
     /** @internal */
     awake() {
@@ -291,11 +329,23 @@ export class GroundProjectedEnv extends Behaviour {
                 this._needsTextureUpdate = true;
             });
         }
+        // Force the skybox blur via the render-bracketing callbacks (these run after every component's
+        // onBeforeRender, so the override can't be clobbered by e.g. Camera.applyClearFlags).
+        if (this.context.pre_render_callbacks.indexOf(this._forceBackgroundBlur) < 0)
+            this.context.pre_render_callbacks.push(this._forceBackgroundBlur);
+        if (this.context.post_render_callbacks.indexOf(this._restoreBackgroundBlur) < 0)
+            this.context.post_render_callbacks.push(this._restoreBackgroundBlur);
     }
     /** @internal */
     onDisable() {
         this._watcher?.revoke();
         this._projection?.removeFromParent();
+        const pre = this.context.pre_render_callbacks.indexOf(this._forceBackgroundBlur);
+        if (pre >= 0) this.context.pre_render_callbacks.splice(pre, 1);
+        const post = this.context.post_render_callbacks.indexOf(this._restoreBackgroundBlur);
+        if (post >= 0) this.context.post_render_callbacks.splice(post, 1);
+        // If we were disabled mid-frame (after force, before restore), put the real value back.
+        this._restoreBackgroundBlur();
     }
     /** @internal */
     onEnterXR(): void {
@@ -312,7 +362,21 @@ export class GroundProjectedEnv extends Behaviour {
     /** @internal */
     onBeforeRender(): void {
         if (this._projection && this.scene.backgroundRotation) {
-            this._projection.rotation.copy(this.scene.backgroundRotation);
+            // Mirror three's WebGLBackground: build the same mat3 it applies to the skybox sampling
+            // direction and feed it to our shader. This rotates the sampled environment exactly like the
+            // skybox (backgroundCube.glsl) instead of rotating the mesh - keeping the floor flat and the
+            // horizon aligned with the skybox for any background rotation.
+            _backgroundRotationEuler.copy(this.scene.backgroundRotation);
+            // accommodate left-handed frame (same as WebGLBackground.js)
+            _backgroundRotationEuler.x *= -1;
+            _backgroundRotationEuler.y *= -1;
+            _backgroundRotationEuler.z *= -1;
+            // Note: the extra cube-texture flip in WebGLBackground only applies to raw CubeTextures, not the
+            // PMREM render-target env this shader path samples - so it is intentionally omitted here.
+            const uniforms = getGroundProjectionShaderUniforms(this._projection.material);
+            uniforms.needleGroundProjectionBackgroundRotation.value.setFromMatrix4(
+                _backgroundRotationMatrix.makeRotationFromEuler(_backgroundRotationEuler)
+            );
         }
 
         if (this._projection && this.context.scene.background instanceof Texture) {

package/src/engine-components/NeedleMenu.ts

@@ -49,8 +49,8 @@ export class NeedleMenu extends Behaviour {
     @serializable()
     position: "top" | "bottom" = "bottom";
 
-    /** 
-     * Controls the visibility of the Needle logo in the menu (requires PRO license)
+    /**
+     * Controls the visibility of the Needle logo in the menu (requires a commercial license)
      */
     @serializable()
     showNeedleLogo: boolean = false;
@@ -102,7 +102,10 @@ export class NeedleMenu extends Behaviour {
             this.context.menu.showFullscreenOption(true);
         if (this.createMuteButton === true)
             this.context.menu.showAudioPlaybackOption(true);
-        if (this.showSpatialMenu === true)
+        // Apply the value in BOTH directions: the spatial menu is enabled by
+        // default, so unchecking the option must explicitly disable it. Only skip
+        // when the field is unset (undefined) to keep the engine default.
+        if (this.showSpatialMenu !== undefined)
             this.context.menu.showSpatialMenu(this.showSpatialMenu);
         if (this.createQRCodeButton === true) {
             if (!DeviceUtilities.isMobileDevice()) {