@needle-tools/engine 5.1.8 → 5.1.10

package/src/engine/engine_networking_blob.ts

@@ -1,7 +1,7 @@
 import { FileLoader } from "three";
 
 import { showBalloonWarning } from "./debug/index.js";
-import { __sKHtRdk } from "./engine_license.js";
+import { __KODK } 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 (__sKHtRdk()) {
+        if (__KODK()) {
             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 (!__sKHtRdk() && filesizeInMB > maxFreeSizeInMB) {
+        else if (!__KODK() && 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 { __sKHtRdk } from "./engine_license.js";
+import { __KODK } 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 = __sKHtRdk();
+    const canUseCustomLogo = __KODK();
 
     // 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/postprocessing/postprocessing.ts

@@ -42,6 +42,32 @@ export class PostProcessing {
     get dirty() { return this._isDirty; }
     set dirty(value: boolean) { this._isDirty = value; }
 
+    private _enabled: boolean = true;
+
+    /**
+     * Whether the postprocessing stack runs at all. When disabled the scene is
+     * rendered directly, with no effects and no composer.
+     *
+     * Every effect keeps its own `enabled` state, so switching this back on
+     * restores exactly the stack that was there before. Useful for a quality
+     * setting, for a clean screenshot, or for comparing a scene with and
+     * without effects.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * context.postprocessing.enabled = false;
+     * ```
+     */
+    get enabled(): boolean { return this._enabled; }
+    set enabled(value: boolean) {
+        if (value === this._enabled) return;
+        this._enabled = value;
+        // Rebuild on the next update: the effects are either collected again
+        // or torn down.
+        this.markDirty();
+    }
+
     /** The internal PostProcessingHandler that manages the EffectComposer pipeline */
     get handler(): IPostProcessingHandler | null { return this._handler; }
 
@@ -227,8 +253,12 @@ export class PostProcessing {
 
         this._isDirty = false;
 
-        // Collect active effects
-        const activeEffects = this._effects.filter(e => e.active && e.enabled);
+        // Collect active effects. A disabled stack collects none, which falls
+        // into the teardown below — the same path taken when a scene simply
+        // has no effects, so there is only one way to end up bypassed.
+        const activeEffects = this._enabled
+            ? this._effects.filter(e => e.active && e.enabled)
+            : [];
 
         if (activeEffects.length <= 0) {
             this.restoreTonemapping();

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 { __sKHtRdk } from "../../engine_license.js";
+import { __KODK } 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 && __sKHtRdk()) {
+            if (!this._showNeedleLogo && __KODK()) {
                 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 { __sKHtRdk, __YcMNHT, Telemetry } from "../../engine_license.js";
+import { __KODK, __spV, 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(() => __YcMNHT(res => {
-                if (res == true && __sKHtRdk() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => __spV(res => {
+                if (res == true && __KODK() && !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 (!__sKHtRdk()) {
+                    if (!__KODK()) {
                         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 (!__sKHtRdk() || debugNonCommercial) {
+            if (!__KODK() || 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

@@ -63,7 +63,20 @@ export class AROverlayHandler {
             else {
                 console.warn("WebXRViewer: No DOM Overlay found");
             }
+
+            // Balloon messages raised BEFORE the session started live in the
+            // needle-engine shadow root — these platforms hide everything except the
+            // overlay root during the session, so exactly the messages that explain
+            // a broken session start (e.g. a marker image failing ARKit validation)
+            // would be invisible. Move them into the AR overlay; they stay inside
+            // the overlay container afterwards, which returns to the shadow root on
+            // session end.
+            const preSessionLogs = context.domElement?.shadowRoot?.querySelector(":scope > [data-needle_engine_debug_overlay]");
+            if (preSessionLogs && this.arContainer && this.arContainer !== preSessionLogs.parentNode) {
+                this.arContainer.appendChild(preSessionLogs);
+            }
         }
+
         this.ensureQuitARButton(this.arContainer);
     }
 

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 { __sKHtRdk, LuMYUbW, __pRlh } from "../engine_license.js";
+import { __KODK, $Ljyi, $AHhz } 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 = LuMYUbW();
+        const hasLicense = $Ljyi();
         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 = __sKHtRdk();
+    //     let commercialLicense = __KODK();
     //     // 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() && __pRlh) {
+    //     if (!isDevEnvironment() && $AHhz) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await __pRlh;
-    //         commercialLicense = __sKHtRdk();
+    //         await $AHhz;
+    //         commercialLicense = __KODK();
     //     }
     //     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 { __sKHtRdk, Telemetry } from "../engine_license.js";
+import { __KODK, 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 = __sKHtRdk();
+        const allowOverridingDefaultLoading = __KODK();
         // 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

@@ -1,6 +1,6 @@
 import { Camera, Object3D, PerspectiveCamera, Quaternion, Vector3 } from "three";
 
-import { enableSpatialConsole, isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../debug/index.js";
+import { enableSpatialConsole, isDevEnvironment, showBalloonError, showBalloonMessage, showBalloonWarning } from "../debug/index.js";
 import { Application, internalOnUserInputRegistered } from "../engine_application.js";
 import { Context, FrameEvent } from "../engine_context.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
@@ -72,8 +72,8 @@ let debugFPSFramesSinceLastUpdate = 0;
 export interface INeedleXRSessionEventReceiver extends Pick<IComponent, "destroyed"> {
     get activeAndEnabled(): boolean;
     supportsXR?(mode: XRSessionMode): boolean;
-    /** Called before requesting a XR session */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    /** Called before requesting a XR session. May return a promise that is awaited before requesting. */
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
     onEnterXR?(args: NeedleXREventArgs): void;
     onUpdateXR?(args: NeedleXREventArgs): void;
     onLeaveXR?(args: NeedleXREventArgs): void;
@@ -243,6 +243,20 @@ if (typeof window !== "undefined" && DeviceUtilities.isDesktop() && isDevEnviron
     });
 }
 
+// Native ARKit diagnostics forwarded by the Needle App Clip (WebXRBridge
+// logToWebConsole dispatches these alongside a console line): surface warnings and
+// errors as balloon messages — the balloon overlay lives in the dom-overlay root,
+// so they are visible INSIDE a running AR session (e.g. "marker failed ARKit
+// validation" instead of a marker that silently never tracks).
+if (typeof document !== "undefined") {
+    document.addEventListener("needlego-log", evt => {
+        const detail = (evt as CustomEvent<{ l?: string, m?: string }>).detail;
+        if (!detail?.m) return;
+        if (detail.l === "error") showBalloonError(detail.m);
+        else if (detail.l === "warn") showBalloonWarning(detail.m);
+    });
+}
+
 function handleAutoStart(value: string | null) {
     if (!value) return;
     switch (value?.toLowerCase()) {
@@ -757,7 +771,15 @@ export class NeedleXRSession implements INeedleXRSession {
             console.log("%c" + `Requesting ${mode} session`, "font-weight:bold;");
         for (const script of scripts) {
             if (script.onBeforeXR && script.activeAndEnabled && !script.destroyed) {
-                script.onBeforeXR(mode, init);
+                try {
+                    // Await: onBeforeXR may be async (e.g. WebXRImageTracking awaits marker bitmap loads
+                    // so late-decoding markers aren't dropped). A failing hook must not abort the session
+                    // request for every other component.
+                    await script.onBeforeXR(mode, init);
+                }
+                catch (err) {
+                    console.error("[NeedleXRSession] onBeforeXR hook failed:", err);
+                }
             }
         }
         this.invokeSessionRequestStart(mode, init, context ?? Context.Current);
@@ -888,7 +910,13 @@ export class NeedleXRSession implements INeedleXRSession {
     /** XR Session Mode: AR or VR */
     readonly mode: XRSessionMode;
 
-    /** 
+    /** The framebuffer scale factor this session was started with. On this
+     * version the engine never requests a custom scale, so it is always 1 —
+     * the property exists so session-resolution handling (e.g. the App Clip
+     * canvas scaling) reads one authoritative value. */
+    readonly appliedFramebufferScaleFactor: number = 1;
+
+    /**
      * The XRSession interface's read-only interactionMode property describes the best space (according to the user agent) for the application to draw an interactive UI for the current session.
      * @link https://developer.mozilla.org/en-US/docs/Web/API/XRSession/interactionMode 
      */
@@ -1320,13 +1348,19 @@ export class NeedleXRSession implements INeedleXRSession {
                 const dpr = window.devicePixelRatio || 1;
                 const currentWidth = canvas.width;
                 const currentHeight = canvas.height;
+                // The NeedleGo polyfill renders through the canvas, so the canvas buffer
+                // size IS the AR render resolution — apply the session's framebuffer
+                // scale here too (a real WebXR framebuffer gets it via
+                // setFramebufferScaleFactor; without this the App Clip silently renders
+                // at full native DPR and e.g. the splat low preset's 0.8 scale is lost).
+                const scale = dpr * this.appliedFramebufferScaleFactor;
                 // Check if DPR is already applied (avoid double-scaling)
-                const expectedWidth = Math.floor(window.innerWidth * dpr);
-                const expectedHeight = Math.floor(window.innerHeight * dpr);
+                const expectedWidth = Math.floor(window.innerWidth * scale);
+                const expectedHeight = Math.floor(window.innerHeight * scale);
                 if (Math.abs(currentWidth - expectedWidth) > 2 || Math.abs(currentHeight - expectedHeight) > 2) {
                     canvas.width = expectedWidth;
                     canvas.height = expectedHeight;
-                    console.debug("Applied DPR scaling for Needle AppClip XR session", dpr, canvas.width, canvas.height);
+                    console.debug("Applied DPR scaling for Needle AppClip XR session", dpr, this.appliedFramebufferScaleFactor, canvas.width, canvas.height);
                 }
             });
         }
@@ -1420,6 +1454,32 @@ export class NeedleXRSession implements INeedleXRSession {
 
         console.debug("XR Session ended");
 
+        // Diagnostic for the App Clip post-session freeze: on device, exactly ONE
+        // render-loop tick runs after session end, then the page appears dead while
+        // focus/visibility events still arrive (observed on every App Clip AR exit).
+        // This heartbeat distinguishes the possible causes: no heartbeat logs = JS
+        // fully suspended by the native layer; heartbeats with rAF ticks ≈ 0 = the
+        // compositor starves rAF (webview still marked hidden); rAF ticks ≈ 60 while
+        // the engine renders nothing = three's animation-loop handoff from the
+        // polyfill session back to the window broke.
+        if (DeviceUtilities.isNeedleAppClip() && isDevEnvironment()) {
+            let rafTicks = 0;
+            let beats = 0;
+            let rafHandle = window.requestAnimationFrame(function countRaf() {
+                rafTicks++;
+                rafHandle = window.requestAnimationFrame(countRaf);
+            });
+            const heartbeat = window.setInterval(() => {
+                beats++;
+                console.debug(`[XR] post-session heartbeat ${beats}/10: window rAF ticks last second=${rafTicks}, engine frame=${this.context.time.frameCount}, visibility=${document.visibilityState}, focus=${document.hasFocus()}`);
+                rafTicks = 0;
+                if (beats >= 10) {
+                    window.clearInterval(heartbeat);
+                    window.cancelAnimationFrame(rafHandle);
+                }
+            }, 1000);
+        }
+
         Telemetry.sendEvent(Context.Current, "xr", {
             action: "session_end",
             mode: this.mode,

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 { __sKHtRdk } from "../engine_license.js";
+import { __KODK } 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 (__sKHtRdk()) {
+        if (__KODK()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine/xr/XRHandMeshModel.ts

@@ -0,0 +1,179 @@
+import { type Bone, type Object3D, type XRHandSpace } from "three";
+import type { GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+
+/**
+ * Vendored from three's `examples/jsm/webxr/XRHandMeshModel.js` (r185).
+ *
+ * WHY THIS IS OWNED BY THE ENGINE AND NOT PATCHED IN THE THREE FORK
+ * -----------------------------------------------------------------
+ * three addons carry no API stability guarantee and this one changed under us twice:
+ *
+ *  - r184 replaced `const object = gltf.scene.children[0]` with
+ *    `const object = clone(gltf.scene.children[0])`. That single word broke every custom
+ *    (Unity-exported) hand model, silently: `SkeletonUtils.clone` runs `Object3D.copy`,
+ *    which deep-copies userData via `JSON.parse(JSON.stringify(...))`. Needle stores live
+ *    component instances in `userData.components`, and components hold a `gameObject`
+ *    back-reference, so that throws "Converting circular structure to JSON" — swallowed by
+ *    GLTFLoader into an onError nobody had set, leaving an empty, invisible hand.
+ *  - The clone also broke component creation: `XRControllerModel` creates the glTF's builtin
+ *    components after load, but the parser's node -> object associations point at the parsed
+ *    original while the clone is what gets displayed.
+ *
+ * DELIBERATE DIFFERENCES FROM UPSTREAM
+ * ------------------------------------
+ *  1. No clone. Upstream needs it only because of `customCache`, where several hands share
+ *     one parsed gltf. We never pass a cache and build a fresh GLTFLoader per hand load, so
+ *     nothing is shared and the clone was pure overhead. Using the parsed object directly
+ *     restores the pre-r184 contract the engine is written against: `handModel.add(object)`
+ *     reparents it out of `gltf.scene` (Object3D.add calls removeFromParent), object identity
+ *     is preserved so the parser's node map stays valid, and components created during parse
+ *     live on the object that is actually rendered.
+ *  2. `customCache` is dropped entirely rather than left unused — sharing a parsed hand
+ *     between models would reintroduce the aliasing the clone existed to prevent.
+ *  3. The hand mesh inherits the layer mask of the object it is added to (the engine puts
+ *     hands on the ignore-raycast layer).
+ *  4. Load failures are reported instead of vanishing.
+ *  5. A missing SkinnedMesh or missing joints no longer throw / spam per joint.
+ *
+ * When bumping three, diff this against the upstream file and fold in real fixes by hand.
+ */
+
+const DEFAULT_HAND_PROFILE_PATH = "https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/generic-hand/";
+
+/** The joints of a WebXR hand, in the order three's hand models declare them. */
+const JOINT_NAMES = [
+    "wrist",
+    "thumb-metacarpal",
+    "thumb-phalanx-proximal",
+    "thumb-phalanx-distal",
+    "thumb-tip",
+    "index-finger-metacarpal",
+    "index-finger-phalanx-proximal",
+    "index-finger-phalanx-intermediate",
+    "index-finger-phalanx-distal",
+    "index-finger-tip",
+    "middle-finger-metacarpal",
+    "middle-finger-phalanx-proximal",
+    "middle-finger-phalanx-intermediate",
+    "middle-finger-phalanx-distal",
+    "middle-finger-tip",
+    "ring-finger-metacarpal",
+    "ring-finger-phalanx-proximal",
+    "ring-finger-phalanx-intermediate",
+    "ring-finger-phalanx-distal",
+    "ring-finger-tip",
+    "pinky-finger-metacarpal",
+    "pinky-finger-phalanx-proximal",
+    "pinky-finger-phalanx-intermediate",
+    "pinky-finger-phalanx-distal",
+    "pinky-finger-tip",
+] as const;
+
+type JointBone = Bone & { jointName?: string };
+
+/**
+ * Renders a skinned hand mesh and drives its bones from the tracked WebXR joint poses.
+ *
+ * @see {@link XRControllerModel} which creates one per tracked hand.
+ */
+export class XRHandMeshModel {
+
+    /** The three XRHandSpace whose `joints` drive this mesh. */
+    readonly controller: XRHandSpace;
+    /** The object the loaded hand mesh is added to. */
+    readonly handModel: Object3D;
+    /** The bones driven by {@link updateMesh}, in {@link JOINT_NAMES} order. Sparse if the model lacks joints. */
+    readonly bones: Array<JointBone | undefined> = [];
+
+    /**
+     * @param handModel the object the loaded mesh is parented to
+     * @param controller the hand space providing joint poses
+     * @param path base path for the model (defaults to the generic hand profile CDN)
+     * @param handedness file name to load (without extension) — either "left"/"right" for the
+     *                   default profile, or a full path for a custom hand model
+     * @param loader loader to use; a plain GLTFLoader is created when omitted
+     * @param onLoad invoked with the loaded hand object once it has been added
+     */
+    constructor(
+        handModel: Object3D,
+        controller: XRHandSpace,
+        path: string | null,
+        handedness: string,
+        loader: GLTFLoader | null = null,
+        onLoad: ((object: Object3D) => void) | null = null,
+    ) {
+        this.controller = controller;
+        this.handModel = handModel;
+
+        const pathToUse = path || DEFAULT_HAND_PROFILE_PATH;
+
+        if (loader === null) {
+            loader = new GLTFLoader();
+            loader.setPath(pathToUse);
+        }
+
+        const url = `${handedness}.glb`;
+        loader.load(url,
+            (gltf: GLTF) => {
+                const object = gltf.scene.children[0];
+                if (!object) {
+                    console.error(`XRHandMeshModel: "${pathToUse}${url}" contains no hand object.`);
+                    return;
+                }
+
+                // NOTE: adding reparents `object` out of `gltf.scene` (Object3D.add calls
+                // removeFromParent), which is what lets the caller detect that the hand has
+                // been taken over and create the glTF's builtin components on it.
+                this.handModel.add(object);
+                // the hand mesh inherits the layers of whatever it was added to
+                object.layers.mask = this.handModel.layers.mask;
+
+                const mesh = object.getObjectByProperty("type", "SkinnedMesh");
+                if (mesh) {
+                    mesh.frustumCulled = false;
+                    mesh.castShadow = true;
+                    mesh.receiveShadow = true;
+                }
+                else {
+                    console.warn(`XRHandMeshModel: no SkinnedMesh in the ${handedness} hand model — it will not deform.`);
+                }
+
+                const missing: string[] = [];
+                for (const jointName of JOINT_NAMES) {
+                    const bone = object.getObjectByName(jointName) as JointBone | undefined;
+                    if (bone) bone.jointName = jointName;
+                    else missing.push(jointName);
+                    this.bones.push(bone);
+                }
+                // one warning instead of one per joint — a model with the wrong rig misses all 25
+                if (missing.length) {
+                    console.warn(`XRHandMeshModel: the ${handedness} hand model is missing ${missing.length} of ${JOINT_NAMES.length} joints (${missing.join(", ")}).`);
+                }
+
+                onLoad?.(object);
+            },
+            undefined,
+            (err: unknown) => {
+                // Upstream passes no error handler, so a failed hand model silently leaves an
+                // empty object and no hand is ever visible. Surface it instead.
+                console.error(`XRHandMeshModel: failed to load the ${handedness} hand model from "${pathToUse}${url}" — the hand will not be visible.`, err);
+            });
+    }
+
+    /** Copies the current tracked joint poses onto the mesh bones. Called every XR frame. */
+    updateMesh() {
+        const XRJoints = this.controller.joints;
+
+        for (let i = 0; i < this.bones.length; i++) {
+            const bone = this.bones[i];
+            if (!bone?.jointName) continue;
+
+            const XRJoint = XRJoints[bone.jointName];
+            if (XRJoint?.visible) {
+                bone.position.copy(XRJoint.position);
+                bone.quaternion.copy(XRJoint.quaternion);
+            }
+        }
+    }
+}

package/src/engine-components/Component.ts

@@ -930,8 +930,9 @@ export abstract class Component implements IComponent, EventTarget,
      * Use to modify session initialization parameters
      * @param mode The XR session mode being requested
      * @param args The session initialization parameters that can be modified
+     * @returns void, or a promise that is awaited before the session is requested (e.g. to load assets)
      */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
 
     /**
      * Called when this component joins an XR session or becomes active in a running session

package/src/engine-components/ReflectionProbe.ts

@@ -289,9 +289,9 @@ export class ReflectionProbe extends Behaviour {
         if (block) {
             const current = block.getOverride("envMap")?.value;
             if (current === this.texture) {
-                block.removeOveride("envMap");
-                block.removeOveride("envMapRotation");
-                block.removeOveride("envMapIntensity");
+                block.removeOverride("envMap");
+                block.removeOverride("envMapRotation");
+                block.removeOverride("envMapIntensity");
             }
         }
     }

package/src/engine-components/RendererLightmap.ts

@@ -146,7 +146,7 @@ export class RendererLightmap {
         }
         const block = MaterialPropertyBlock.get(this.gameObject);
         if (block) {
-            block.removeOveride("lightMap");
+            block.removeOverride("lightMap");
         }
     }
 

package/src/engine-components/SyncedRoom.ts

@@ -190,6 +190,11 @@ export class SyncedRoom extends Behaviour {
             if (val && (typeof val === "string" || typeof val === "number")) {
                 hasRoomParameter = true;
                 const roomNameParam = utils.sanitizeString(val.toString());
+                // The URL parameter takes precedence over the configured roomName. That is
+                // easy to miss when a room name was set deliberately, so say so in dev.
+                if ((debug || isDevEnvironment()) && this.roomName?.length > 0 && this.roomName !== roomNameParam) {
+                    console.warn(`[SyncedRoom] Joining "${roomNameParam}" from the "${this.urlParameterName}" URL parameter — the roomName set on the component ("${this.roomName}") is ignored.\nThe URL parameter always wins. To use the component's room name instead, clear "urlParameterName".`);
+                }
                 this.roomName = roomNameParam;
             }
             else if (this.joinRandomRoom) {

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