@needle-tools/engine 5.1.8 → 5.1.9

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 { _$qxlHFE, _iXmRJVD, _$vVym } 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 = _iXmRJVD();
         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 = _$qxlHFE();
     //     // 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() && _$vVym) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await __pRlh;
-    //         commercialLicense = __sKHtRdk();
+    //         await _$vVym;
+    //         commercialLicense = _$qxlHFE();
     //     }
     //     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 { _$qxlHFE, 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 = _$qxlHFE();
         // 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 { _$qxlHFE } 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 (_$qxlHFE()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

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/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 { _iXmRJVD } 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 (!_iXmRJVD()) {
             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 (!_iXmRJVD()) {
                             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 (!_iXmRJVD()) {
             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/WebXRImageTracking.ts

@@ -4,6 +4,7 @@ import { Object3DEventMap } from "three";
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../engine/debug/index.js";
 import { AssetReference } from "../../engine/engine_addressables.js";
 import { Context } from "../../engine/engine_context.js";
+import { Telemetry } from "../../engine/engine_license.js";
 import { serializable } from "../../engine/engine_serialization.js";
 import { IGameObject } from "../../engine/engine_types.js";
 import { CircularBuffer, delay, DeviceUtilities, getParam } from "../../engine/engine_utils.js";
@@ -14,6 +15,7 @@ import { USDZExporter } from "../../engine-components/export/usdz/USDZExporter.j
 import { Behaviour, GameObject } from "../Component.js";
 import { EventList } from "../EventList.js";
 import { Renderer } from "../Renderer.js";
+import { _imageElements, collectTrackedImages, loadImage } from "./WebXRImageTracking.utils.js";
 
 // https://github.com/immersive-web/marker-tracking/blob/main/explainer.md
 
@@ -216,9 +218,9 @@ export class WebXRImageTrackingModel {
      * @param params.imageDoesNotMove Enable for static markers (floor/wall mounted) to improve tracking stability
      * @param params.hideWhenTrackingIsLost If true, hides the object when tracking is lost; if false, leaves it at the last known position
      */
-    constructor(params: { url: string, widthInMeters: number, /** Object to track */ object: AssetReference | Object3D, createObjectInstance?: boolean, imageDoesNotMove?: boolean, hideWhenTrackingIsLost?: boolean }) {
+    constructor(params: Omit<WebXRImageTrackingOptions, "asPrimary">) {
         this.image = params.url;
-        this.widthInMeters = params.widthInMeters;
+        if (params.widthInMeters !== undefined) this.widthInMeters = params.widthInMeters;
         if (params.object instanceof Object3D) {
             this.object = new AssetReference({ asset: params.object });
         }
@@ -322,6 +324,27 @@ export class WebXRImageTrackingModel {
     }
 }
 
+/**
+ * Options for adding a trackable image marker via {@link WebXRImageTracking.addImage}.
+ * A convenience shape that also accepts a plain {@link Object3D} for `object`.
+ */
+export interface WebXRImageTrackingOptions {
+    /** URL to the marker image to track. Use high-contrast images with unique features for reliable tracking. */
+    url?: string;
+    /** The 3D object (or {@link AssetReference}) to display when the marker is detected. */
+    object: AssetReference | Object3D;
+    /** Physical width of the printed marker in meters. Must match the real marker size. @default 0.25 */
+    widthInMeters?: number;
+    /** Create a new instance of the object for each detection. @default false */
+    createObjectInstance?: boolean;
+    /** Enable for static markers (walls/floor) to improve tracking stability. @default false */
+    imageDoesNotMove?: boolean;
+    /** Hide the object when tracking is lost. @default true */
+    hideWhenTrackingIsLost?: boolean;
+    /** Make this the primary marker (used in QuickLook fallback mode). @default false */
+    asPrimary?: boolean;
+}
+
 /** Data passed to image tracking event listeners. */
 export interface WebXRImageTrackingEvent {
     /** The images currently being tracked this frame. */
@@ -619,27 +642,37 @@ export class WebXRImageTracking extends Behaviour {
      * **Tip:** Add all your markers upfront. In WebXR mode they all work simultaneously.
      * In QuickLook mode, the first (primary) marker is used.
      *
-     * @param image The marker configuration to add
-     * @param asPrimary Set to true to make this the primary marker (for QuickLook fallback)
+     * @param image The marker configuration - either a plain options object or a {@link WebXRImageTrackingModel}.
+     *              Set `asPrimary: true` to make this the primary marker (for QuickLook fallback).
      *
      * @example
      * ```ts
-     * // Super simple - works across all platforms
-     * const marker = new WebXRImageTrackingModel({
+     * // Super simple - just pass the marker url and the object to show
+     * imageTracking.addImage({
      *   url: "https://mysite.com/poster.png",
-     *   widthInMeters: 0.42, // A3 poster width
-     *   object: cool3DModel
+     *   object: cool3DModel,
+     *   widthInMeters: 0.42, // A3 poster width (optional, defaults to 0.25)
      * });
-     * imageTracking.addImage(marker);
      * // That's it! Needle does the rest.
      * ```
      */
-    addImage(image: WebXRImageTrackingModel, asPrimary: boolean = false) {
-        if (!this.trackedImages.includes(image)) {
-            this.trackedImages.push(image);
-            loadImage(image.image!);
+    addImage(options: WebXRImageTrackingOptions): void;
+    addImage(model: WebXRImageTrackingModel): void;
+    addImage(image: WebXRImageTrackingOptions | WebXRImageTrackingModel): void {
+        // Accept either a ready-made model or a plain options object (which allows `object` to be a
+        // plain Object3D). Normalize to a WebXRImageTrackingModel; the constructor wraps Object3D in
+        // an AssetReference for us.
+        const model = image instanceof WebXRImageTrackingModel ? image : new WebXRImageTrackingModel(image);
+        if (!this.trackedImages.includes(model)) {
+            this.trackedImages.push(model);
+            loadImage(model.image!);
+            if(isDevEnvironment()) {
+                if(model.widthInMeters <= 0) {
+                    this.onInvalidImageSizeDetected(model.image!);
+                }
+            }
         }
-        if (asPrimary) this.setPrimaryImage(image);
+        if (!(image instanceof WebXRImageTrackingModel) && image.asPrimary) this.setPrimaryImage(model);
     }
 
 
@@ -689,6 +722,9 @@ export class WebXRImageTracking extends Behaviour {
         for (const trackedImage of this.trackedImages) {
             if (trackedImage.image) {
                 loadImage(trackedImage.image);
+                if(isDevEnvironment() && trackedImage.widthInMeters <= 0) {
+                    this.onInvalidImageSizeDetected(trackedImage.image);
+                }
             }
         }
     }
@@ -701,6 +737,16 @@ export class WebXRImageTracking extends Behaviour {
         USDZExporter.beforeExport.removeEventListener(this.onBeforeUSDZExport);
     }
 
+
+    private onInvalidImageSizeDetected(url:string) {
+        if(globalThis["__NEEDLE_DEBUG_WebARImageSizeInvalid__"]) return;
+        globalThis["__NEEDLE_DEBUG_WebARImageSizeInvalid__"] = true;
+        console.warn(`[WebXRImageTracking] Invalid marker size detected for image ${url}. Ensure 'widthInMeters' is greater than 0 for accurate tracking.`);
+        if(isDevEnvironment()) {
+            showBalloonWarning(`[WebXRImageTracking] Invalid marker size detected for image ${url}. Ensure 'widthInMeters' is greater than 0 for accurate tracking.`);
+        }
+    }
+
     private onBeforeUSDZExport = (args: { exporter: USDZExporter }) => {
         if (this.activeAndEnabled && this.trackedImages?.length) {
             args.exporter.extensions.push(new ImageTrackingExtension(args.exporter, this));
@@ -709,31 +755,30 @@ export class WebXRImageTracking extends Behaviour {
 
 
     /** @internal */
-    onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): void {
-        // console.log("onXRRequested", args, this.trackedImages)
-        if (this.trackedImages) {
-            args.optionalFeatures = args.optionalFeatures || [];
-            if (!args.optionalFeatures.includes("image-tracking"))
-                args.optionalFeatures.push("image-tracking");
+    async onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): Promise<void> {
+        if (!this.trackedImages) return;
 
-            if(!args.trackedImages) args.trackedImages = [];
-            for (const trackedImage of this.trackedImages) {
-                if (trackedImage.image?.length && trackedImage.widthInMeters > 0) {
-                    const bitmap = _imageElements.get(trackedImage.image);
-                    if (bitmap) {
-                        this.trackedImageIndexMap.set(args.trackedImages.length, trackedImage);
-                        args.trackedImages.push({
-                            image: bitmap,
-                            widthInMeters: trackedImage.widthInMeters
-                        });
-                    }
-                }
-            }
+        args.optionalFeatures = args.optionalFeatures || [];
+        if (!args.optionalFeatures.includes("image-tracking"))
+            args.optionalFeatures.push("image-tracking");
+
+        // Resolve the marker bitmaps *before* the session is requested.
+        // onBeforeXR runs the moment "Enter AR" is tapped. Marker images load asynchronously
+        // (network fetch + createImageBitmap), so without awaiting here a marker that hasn't finished
+        // decoding yet would be silently dropped from `trackedImages` and never registered with the
+        // native/WebXR session - it would then only start working after exiting and re-entering AR,
+        // once the bitmap has been cached. Awaiting the (idempotent) loads closes that race.
+        // A marker that can not be loaded resolves to null and is skipped individually, so a single
+        // unavailable image never rejects the whole XR session request. See forum topic #2859.
+        this.trackedImageIndexMap.clear();
+        const indexMap = await collectTrackedImages(this.trackedImages, args);
+        for (const [index, model] of indexMap) {
+            this.trackedImageIndexMap.set(index, model);
         }
     }
 
     /** @internal */
-    onEnterXR(_args: NeedleXREventArgs): void {
+    onEnterXR(args: NeedleXREventArgs): void {
         if (this.trackedImages) {
             for (const trackedImage of this.trackedImages) {
                 if (trackedImage.object?.asset) {
@@ -753,11 +798,52 @@ export class WebXRImageTracking extends Behaviour {
         for (const trackedData of this.imageToObjectMap.values()) {
             trackedData.frames = 0;
         }
+
+        // A session GRANTED before the scene finished loading (App Clip / NeedleGo
+        // handoff, Quest link traversal) was requested without this component's
+        // markers — onBeforeXR never contributed to its init, and the WebXR spec has
+        // no way to add tracked images to a running session. The NeedleGo polyfill
+        // CAN (ARKit re-runs its configuration with new detection images), so
+        // register late where supported and surface the misconfiguration otherwise.
+        if (this.trackedImages?.length && this.trackedImageIndexMap.size === 0) {
+            if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] No marker images made it into the session init (granted session?) — attempting runtime registration for ${this.trackedImages.length} image(s)`);
+            this.registerImagesWithRunningSession(args.xr.session);
+        }
+        else if (this.trackedImages?.length && (isDevEnvironment() || debug)) {
+            console.debug(`[WebXRImageTracking] ${this.trackedImageIndexMap.size} marker image(s) registered via the session init`);
+        }
     };
 
+    /** Late-registers this component's marker images into an already running session
+     * via the NeedleGo polyfill's runtime hook. See {@link onEnterXR}. */
+    private async registerImagesWithRunningSession(session: XRSession) {
+        const register = (session as XRSession & { nonStandard_registerTrackedImages?: (images: Array<{ image: ImageBitmap, widthInMeters: number }>) => number }).nonStandard_registerTrackedImages;
+        if (typeof register !== "function") {
+            console.warn("[WebXRImageTracking] The XR session was started before the scene finished loading and does not support registering marker images at runtime — image tracking will not work in this session. Exit and re-enter AR from the loaded page.");
+            Telemetry.sendEvent(this.context, "xr", { action: "image_tracking_missed_session_init" });
+            return;
+        }
+        const args: { trackedImages?: Array<{ image: ImageBitmap, widthInMeters: number }> } = {};
+        const indexMap = await collectTrackedImages(this.trackedImages, args);
+        if (!args.trackedImages?.length) return;
+        // the session may have ended (or been replaced) while marker bitmaps loaded
+        if (this.context.xr?.session !== session) return;
+        const baseIndex = register.call(session, args.trackedImages);
+        if (baseIndex < 0) return;
+        for (const [index, model] of indexMap) {
+            this.trackedImageIndexMap.set(baseIndex + index, model);
+        }
+        if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Registered ${args.trackedImages.length} marker image(s) with the running session (granted before the scene loaded)`);
+    }
+
     /** @internal */
     onLeaveXR(_args: NeedleXREventArgs): void {
 
+        // result indices are scoped to the session that registered the images — a new
+        // session rebuilds the map (onBeforeXR, or the late registration in onEnterXR
+        // for granted sessions, which detects the empty map)
+        this.trackedImageIndexMap.clear();
+
         if (!this.supported && DeviceUtilities.isAndroidDevice()) {
             showBalloonWarning(this.webXRIncubationsWarning);
         }
@@ -942,36 +1028,4 @@ export class WebXRImageTracking extends Behaviour {
             }
         }
     }
-}
-
-
-
-
-const _imageElements: Map<string, ImageBitmap | null> = new Map();
-const _imageLoadingPromises: Map<string, Promise<boolean>> = new Map();
-
-async function loadImage(url: string) {
-    if (_imageElements.has(url)) {
-        if (_imageLoadingPromises.has(url)) return _imageLoadingPromises.get(url);
-        return Promise.resolve(true);
-    }
-    const promise = new Promise<boolean>(res => {
-        _imageElements.set(url, null);
-        if(isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Start loading image for tracking: ${url}`);
-        const imageElement = document.createElement("img") as HTMLImageElement;
-        imageElement.src = url;
-        imageElement.addEventListener("load", async () => {
-            if(isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Loaded image for tracking: ${url}`);
-            const img = await createImageBitmap(imageElement);
-            _imageElements.set(url, img);
-            res(true);
-        });
-    });
-
-    _imageLoadingPromises.set(url, promise);
-    promise.finally(() => {
-        _imageLoadingPromises.delete(url);
-    });
-
-    return promise;
 }

package/src/engine-components/webxr/WebXRImageTracking.utils.ts

@@ -0,0 +1,105 @@
+import { isDevEnvironment } from "../../engine/debug/index.js";
+import { getParam } from "../../engine/engine_utils.js";
+
+import type { WebXRImageTrackingModel } from "./WebXRImageTracking.js";
+
+// Kept in a dedicated module (with only lightweight imports) so the marker-loading logic can be unit
+// tested without pulling in the heavy WebXRImageTracking / USDZ exporter import graph.
+
+const debug = getParam("debugimagetracking");
+
+/**
+ * Cache of decoded marker bitmaps, keyed by image url.
+ * Also read by the USDZ exporter (see {@link WebXRImageTracking}) to embed the marker into the .usdz.
+ */
+export const _imageElements: Map<string, ImageBitmap | null> = new Map();
+const _imageLoadingPromises: Map<string, Promise<ImageBitmap | null>> = new Map();
+
+/**
+ * Resolve marker bitmaps for the given tracked-image models and append them to `args.trackedImages`
+ * (the list handed to `navigator.xr.requestSession`).
+ *
+ * Every valid marker is awaited so that images which are still decoding when the XR session is
+ * requested get included instead of being silently dropped (which previously caused markers to only
+ * work after re-entering AR). Loading happens in parallel and never rejects: a marker that can not be
+ * loaded is skipped individually so a single unavailable image can not fail the whole session request.
+ *
+ * @param models The configured tracked-image models
+ * @param args The session init object; `trackedImages` is created if missing and appended to
+ * @param load Injectable loader (defaults to {@link loadImage}); resolves the decoded bitmap or null
+ * @returns Map of `trackedImages` index -> model for the appended images (used to resolve results)
+ */
+export async function collectTrackedImages(
+    models: readonly WebXRImageTrackingModel[] | undefined | null,
+    args: { trackedImages?: Array<{ image: ImageBitmap, widthInMeters: number }> },
+    load: (url: string) => Promise<ImageBitmap | null> = loadImage,
+): Promise<Map<number, WebXRImageTrackingModel>> {
+    const indexMap = new Map<number, WebXRImageTrackingModel>();
+    if (!args.trackedImages) args.trackedImages = [];
+    if (!models) return indexMap;
+
+    const valid = models.filter(m => !!m.image?.length && m.widthInMeters > 0);
+    // Load in parallel and wait for all of them. Guard every load with a catch so that a rejecting
+    // loader is treated as "unavailable" (null) rather than aborting the whole session request.
+    const bitmaps = await Promise.all(valid.map(m => load(m.image!).catch(() => null)));
+
+    for (let i = 0; i < valid.length; i++) {
+        const model = valid[i];
+        const bitmap = bitmaps[i];
+        if (bitmap) {
+            indexMap.set(args.trackedImages.length, model);
+            args.trackedImages.push({ image: bitmap, widthInMeters: model.widthInMeters });
+        }
+        else if (isDevEnvironment() || debug) {
+            console.warn(`[WebXRImageTracking] Marker image could not be loaded, skipping: ${model.image}`);
+        }
+    }
+    return indexMap;
+}
+
+/**
+ * Load and decode a marker image into an {@link ImageBitmap}, caching it in {@link _imageElements}.
+ * Idempotent: concurrent or repeated calls for the same URL share a single in-flight load.
+ *
+ * Resolves to `null` and never rejects when the image can not be fetched or decoded, so callers can
+ * skip an unavailable marker without failing the surrounding XR session request. A failed load clears
+ * its cache entry so a later attempt (e.g. re-entering AR) can retry.
+ */
+export async function loadImage(url: string): Promise<ImageBitmap | null> {
+    const cached = _imageElements.get(url);
+    if (cached) return cached;
+    const pending = _imageLoadingPromises.get(url);
+    if (pending) return pending;
+
+    const promise = new Promise<ImageBitmap | null>(res => {
+        _imageElements.set(url, null); // placeholder to dedupe concurrent loads
+        if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Start loading image for tracking: ${url}`);
+        const imageElement = document.createElement("img") as HTMLImageElement;
+        imageElement.addEventListener("load", async () => {
+            try {
+                const img = await createImageBitmap(imageElement);
+                _imageElements.set(url, img);
+                if (isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Loaded image for tracking: ${url}`);
+                res(img);
+            }
+            catch (err) {
+                console.error(`[WebXRImageTracking] Failed to decode marker image for tracking: ${url}`, err);
+                _imageElements.delete(url); // allow a retry later (e.g. re-entering AR)
+                res(null);
+            }
+        });
+        imageElement.addEventListener("error", (evt) => {
+            console.error(`[WebXRImageTracking] Failed to load marker image for tracking: ${url}`, evt);
+            _imageElements.delete(url); // allow a retry later (e.g. re-entering AR)
+            res(null);
+        });
+        imageElement.src = url;
+    });
+
+    _imageLoadingPromises.set(url, promise);
+    promise.finally(() => {
+        _imageLoadingPromises.delete(url);
+    });
+
+    return promise;
+}