@needle-tools/engine 5.1.3 → 5.1.4

package/src/engine/engine_utils_screenshot.needlego.ts

@@ -0,0 +1,53 @@
+import { DeviceUtilities } from "./engine_utils.js";
+
+/**
+ * Arguments for the native screenshot bridge exposed by the Needle Go App Clip (injected as `window.NeedleGoNativeScreenshot`).
+ */
+declare type NeedleGoNativeScreenshotArgs = {
+    /** Data URL (PNG) of the rendered 3D layer with a transparent background. Native code composites the live camera frame behind it. */
+    image: string;
+    /** "share" presents the native share sheet, "return" sends the composited image back. @default "share" */
+    action?: "share" | "return";
+    /** Share sheet title (action "share") */
+    title?: string;
+    /** Share sheet text (action "share") */
+    text?: string;
+    /** Share sheet url (action "share") */
+    url?: string;
+    /** Mime type for the returned image (action "return"): "image/png" or "image/jpeg" (default jpeg, the composite is opaque) */
+    mimeType?: string;
+    /** JPEG quality 0..1 for action "return" (default 0.9) */
+    quality?: number;
+}
+
+declare type NeedleGoNativeScreenshotResult = {
+    /** action "share": whether the user completed the share */
+    shared?: boolean;
+    /** action "share": the activity the user chose, if any */
+    activity?: string;
+    /** action "return": data URL of the composited image */
+    image?: string;
+    /** action "return": mime type of the returned image */
+    mimeType?: string;
+}
+
+declare type NeedleGoNativeScreenshotFunction = (args: NeedleGoNativeScreenshotArgs) => Promise<NeedleGoNativeScreenshotResult>;
+
+/**
+ * Returns the native screenshot bridge when running inside the Needle Go App Clip.
+ *
+ * In the App Clip the camera feed is rendered natively *behind* the transparent webview,
+ * so the page can never capture it (there is no `camera-access` WebXR feature). The bridge
+ * lets us send the rendered 3D layer to the native app, which composites the current camera
+ * frame behind it and can present the native share sheet — which, unlike `navigator.share`,
+ * does not require (transient) user activation, so a single tap is enough even though the
+ * screenshot pipeline is asynchronous.
+ *
+ * Returns null when not in the App Clip or when the App Clip version doesn't support it yet.
+ */
+export function getNativeScreenshotBridge(): NeedleGoNativeScreenshotFunction | null {
+    if (typeof window === "undefined") return null;
+    if (!DeviceUtilities.isNeedleAppClip()) return null;
+    const fn = (window as any).NeedleGoNativeScreenshot;
+    return typeof fn === "function" ? fn as NeedleGoNativeScreenshotFunction : null;
+}

package/src/engine/engine_utils_screenshot.ts

@@ -11,6 +11,7 @@ import { registerFrameEventCallback } from "./engine_lifecycle_functions_interna
 import { Context, FrameEvent } from "./engine_setup.js";
 import { ICamera } from "./engine_types.js";
 import { DeviceUtilities } from "./engine_utils.js";
+import { getNativeScreenshotBridge } from "./engine_utils_screenshot.needlego.js";
 import { updateTextureFromXRFrame } from "./engine_utils_screenshot.xr.js";
 import { RGBAColor } from "./js-extensions/index.js";
 import { setCustomVisibility } from "./js-extensions/Layers.js";
@@ -355,6 +356,11 @@ export function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOpt
  * ```
  * Without camera access, AR screenshots will only show your 3D content without the real-world background.
  *
+ * **Needle Go App Clip**: When running in the Needle Go iOS App Clip, `type: "share"` and `type: "blob"`
+ * screenshots are handled by the native app: the camera feed (which is rendered natively and not
+ * accessible from the page) is composited automatically, and `type: "share"` presents the native iOS
+ * share sheet — which works with a single tap because it doesn't require web user activation.
+ *
  * @example Combining multiple options
  * ```ts
  * // High-res transparent screenshot with custom camera
@@ -401,6 +407,15 @@ export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTe
     const renderer = context.renderer;
     const isXRScreenshot = renderer.xr.enabled && renderer.xr.isPresenting;
 
+    // In the Needle Go App Clip the camera feed is rendered natively behind the transparent
+    // webview and can not be captured from the page. For "blob"/"share" screenshots we send
+    // the rendered (transparent) 3D layer to the native app instead, which composites the
+    // current camera frame behind it. For "share" the native share sheet is used, which does
+    // not require user activation — so a single tap works despite the async pipeline.
+    const nativeScreenshotBridge = "type" in opts && (opts.type === "share" || (opts.type === "blob" && isXRScreenshot))
+        ? getNativeScreenshotBridge()
+        : null;
+
 
     // Perform XR screenshot in onBeforeRender (after the screenshot we want to render the original camera view)
     // If we do it in onAfterRender we will see one frame of a wrong image which is not what we want
@@ -422,6 +437,8 @@ export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTe
 
     const prevWidth = domElement.width;
     const prevHeight = domElement.height;
+    const prevStyleWidth = domElement.style.width;
+    const prevStyleHeight = domElement.style.height;
 
     if (!width) width = prevWidth;
     if (!height) height = prevHeight;
@@ -532,6 +549,9 @@ export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTe
                 scene: context.scene,
                 camera: camera,
                 renderer: renderer,
+                // When the native bridge composites the camera frame we only need the
+                // transparent 3D layer here (camera-access is not available in the App Clip)
+                skipCameraImage: nativeScreenshotBridge != null,
             });
         }
         else {
@@ -586,6 +606,19 @@ export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTe
                 return targetTexture.texture;
             }
             else if (opts.type === "blob") {
+                if (nativeScreenshotBridge) {
+                    const fallbackCanvas = outputCanvas;
+                    return nativeScreenshotBridge({
+                        image: outputCanvas.toDataURL("image/png"),
+                        action: "return",
+                        mimeType: mimeType,
+                    })
+                        .then(res => res?.image ? dataURLToBlob(res.image) : null)
+                        .catch(err => {
+                            console.warn("Native screenshot failed, falling back to canvas capture", err);
+                            return new Promise<Blob | null>(resolve => fallbackCanvas.toBlob(resolve, mimeType));
+                        });
+                }
                 const promise = new Promise<Blob | null>((resolve, _) => {
                     outputCanvas.toBlob(blob => {
                         resolve(blob);
@@ -594,6 +627,20 @@ export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTe
                 return promise;
             }
             else if (opts.type === "share") {
+                if (nativeScreenshotBridge) {
+                    return nativeScreenshotBridge({
+                        image: outputCanvas.toDataURL("image/png"),
+                        action: "share",
+                        title: "title" in opts ? opts.title : undefined,
+                        text: "text" in opts ? opts.text : undefined,
+                        url: "url" in opts ? opts.url : undefined,
+                    })
+                        .then(res => ({ blob: null, shared: res?.shared === true }))
+                        .catch(err => {
+                            console.warn("Native share failed", err);
+                            return { blob: null, shared: false };
+                        });
+                }
                 const promise = new Promise<ScreenshotOptionsShareReturnType>((resolve, _) => {
                     outputCanvas.toBlob(blob => {
                         if (blob && "share" in navigator) {
@@ -653,7 +700,15 @@ export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTe
     finally {
         renderer.setRenderTarget(prevRenderTarget);
         context.scene.background = previousBackground;
-        renderer.setSize(prevWidth, prevHeight, false);
+        // setSize multiplies by the renderer pixel ratio, but prevWidth/prevHeight are the
+        // canvas backing store size (device pixels) — divide so the backing store is restored exactly
+        const pixelRatio = renderer.getPixelRatio() || 1;
+        renderer.setSize(prevWidth / pixelRatio, prevHeight / pixelRatio, false);
+        // restore the canvas CSS size that was overridden during the screenshot. This is
+        // particularly important for XR screenshots where updateSize (which resets the style
+        // to 100%) is not called below — otherwise the canvas stays at the screenshot size
+        domElement.style.width = prevStyleWidth;
+        domElement.style.height = prevStyleHeight;
         renderer.setClearColor(previousClearColor, previousClearAlpha);
         // Make sure to reset the aspect ratio. This is crucial if the main camera is not the currently active rendering camera
         // For example if we did a screenshot from a different camera that has a different aspect ratio / fov
@@ -673,6 +728,10 @@ export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTe
 
 
 
+function dataURLToBlob(dataUrl: string): Promise<Blob | null> {
+    return fetch(dataUrl).then(res => res.blob()).catch(() => null);
+}
+
 // trim to transparent pixels
 function trimCanvas(originalCanvas: HTMLCanvasElement): HTMLCanvasElement | null {
     if (!("document" in globalThis)) return null;
@@ -760,10 +819,11 @@ export namespace InternalScreenshotUtils {
 
     /**
      * Screenshot rendering for AR
-     * @param args
+     * @param args Set `skipCameraImage` to render only the 3D layer with a transparent background
+     * (used when the camera feed is composited elsewhere, e.g. natively in the Needle Go App Clip)
      * @returns The canvas with the screenshot
      */
-    export function compositeWithCameraImage(args: { scene: Scene, camera: Camera, renderer: WebGLRenderer, width: number, height: number }) {
+    export function compositeWithCameraImage(args: { scene: Scene, camera: Camera, renderer: WebGLRenderer, width: number, height: number, skipCameraImage?: boolean }) {
 
         const { renderer, width, height } = args;
 
@@ -811,7 +871,14 @@ export namespace InternalScreenshotUtils {
         }
 
         if (!otherPlaneMesh) {
-            otherPlaneMesh = makeFullscreenPlane();
+            // Premultiply alpha when blitting into the canvas (which is premultiplied) so that
+            // transparent/anti-aliased pixels survive the drawImage readback without fringing.
+            // With an opaque camera background alpha is 1 everywhere and this is a no-op.
+            otherPlaneMesh = makeFullscreenPlane({
+                defines: {
+                    PREMULTIPLY_ALPHA: true
+                },
+            });
         }
 
         if (!threeTexture) {
@@ -834,27 +901,38 @@ export namespace InternalScreenshotUtils {
         renderer.xr.enabled = false;
         renderer.autoClear = false;
         renderer.clear();
-        renderer.setSize(expectedWidth, expectedHeight);
+        // updateStyle=false: don't write the screenshot size into the live canvas CSS
+        renderer.setSize(expectedWidth, expectedHeight, false);
         renderer.setRenderTarget(rtTexture);
 
-        // First we update the render texture which will hold the camera image
-        if (!updateTextureFromXRFrame(args.renderer, threeTexture)) {
-            console.error("Could not update texture from XR frame");
-        }
+        // The render target is reused between screenshots: clear it with transparent black
+        // so the 3D layer stays transparent where nothing is rendered (no ghosting)
+        const prevClearColor = renderer.getClearColor(new Color());
+        const prevClearAlpha = renderer.getClearAlpha();
+        renderer.setClearColor(0x000000, 0);
+        renderer.clear();
+        renderer.setClearColor(prevClearColor, prevClearAlpha);
 
-        const camBg = GameObject.findObjectOfType(WebARCameraBackground);
-        if (camBg) {
-            // the scene uses WebARCameraBackground, so we make sure it has the latest camera-access texture
-            camBg.setTexture(threeTexture);
-        }
-        else {
-            // the scene doesn't use WebARCameraBackground, so we render the camera feed fullscreen
-            backgroundPlane.setTexture(threeTexture);
-            renderer.render(backgroundPlane, args.camera);
+        if (!args.skipCameraImage) {
+            // First we update the render texture which will hold the camera image
+            if (!updateTextureFromXRFrame(args.renderer, threeTexture)) {
+                console.error("Could not update texture from XR frame");
+            }
+
+            const camBg = GameObject.findObjectOfType(WebARCameraBackground);
+            if (camBg) {
+                // the scene uses WebARCameraBackground, so we make sure it has the latest camera-access texture
+                camBg.setTexture(threeTexture);
+            }
+            else {
+                // the scene doesn't use WebARCameraBackground, so we render the camera feed fullscreen
+                backgroundPlane.setTexture(threeTexture);
+                renderer.render(backgroundPlane, args.camera);
+            }
         }
 
         renderer.clearDepth();
-        renderer.setSize(expectedWidth, expectedHeight);
+        renderer.setSize(expectedWidth, expectedHeight, false);
         renderer.render(args.scene, args.camera);
 
         // Blit the render texture first into our renderer on the GPU,
@@ -862,7 +940,10 @@ export namespace InternalScreenshotUtils {
         renderer.setRenderTarget(null);
         otherPlaneMesh.setTexture(rtTexture.texture);
         renderer.render(otherPlaneMesh, args.camera);
-        const _context = customCanvas.getContext('2d', { alpha: false })!;
+        // alpha-enabled context: the 3D layer must stay transparent when the camera image
+        // is composited elsewhere (with a camera background the image is opaque anyway)
+        const _context = customCanvas.getContext('2d')!;
+        _context.clearRect(0, 0, customCanvas.width, customCanvas.height);
         _context.drawImage(renderer.domElement, 0, 0, customCanvas.width, customCanvas.height);
 
         renderer.setRenderTarget(prevRT);
@@ -890,6 +971,12 @@ void main() {
     gl_FragColor = texColor;
     #include <tonemapping_fragment>
     #include <colorspace_fragment>
+
+    #ifdef PREMULTIPLY_ALPHA
+
+        gl_FragColor.rgb *= gl_FragColor.a;
+
+    #endif
 }
 `;
 

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 { Ojgqq } from "../../engine_license.js";
+import { __QhCnOwd } 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 && Ojgqq()) {
+            if (!this._showNeedleLogo && __QhCnOwd()) {
                 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 { Ojgqq, _lEbGNc, Telemetry } from "../../engine_license.js";
+import { __QhCnOwd, __jFACNo, 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";
@@ -778,8 +778,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(() => _lEbGNc(res => {
-                if (res == true && Ojgqq() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => __jFACNo(res => {
+                if (res == true && __QhCnOwd() && !debugNonCommercial) {
                     let visible = this._userRequestedLogoVisible;
                     if (visible === undefined) visible = false;
                     this.___onSetLogoVisible(visible);
@@ -830,7 +830,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 (!Ojgqq()) {
+                    if (!__QhCnOwd()) {
                         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) {
@@ -918,7 +918,7 @@ export class NeedleMenuElement extends HTMLElementBase {
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
         if (!visible) {
-            if (!Ojgqq() || debugNonCommercial) {
+            if (!__QhCnOwd() || 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.loading.ts

@@ -1,6 +1,6 @@
 import { needleLogoOnlySVG } from "../assets/index.js"
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { Ojgqq, __OBvkie, zis } from "../engine_license.js";
+import { __QhCnOwd, KLaEb, _$OuASD } 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 = __OBvkie();
+        const hasLicense = KLaEb();
         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 = Ojgqq();
+    //     let commercialLicense = __QhCnOwd();
     //     // 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() && zis) {
+    //     if (!isDevEnvironment() && _$OuASD) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await zis;
-    //         commercialLicense = Ojgqq();
+    //         await _$OuASD;
+    //         commercialLicense = __QhCnOwd();
     //     }
     //     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 { Ojgqq, Telemetry } from "../engine_license.js";
+import { __QhCnOwd, 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 = Ojgqq();
+        const allowOverridingDefaultLoading = __QhCnOwd();
         // 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

@@ -399,13 +399,23 @@ export class NeedleXRSession implements INeedleXRSession {
         // 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;
+        // Return the RESOLVED boolean once we have it. This cache stores booleans (not promises)
+        // on purpose: some call sites read it synchronously — e.g. the iOS AppClip path in start()
+        // must decide within the user gesture, so it can't await here.
+        const resolved = this._sessionSupportedCache[mode];
+        if (resolved !== undefined) return Promise.resolve(resolved);
+        // De-duplicate concurrent probes: a burst of callers in the same tick (XR buttons,
+        // offer-session, support checks) shares ONE underlying navigator.xr.isSessionSupported()
+        // call per mode instead of each re-running the `xr-spatial-tracking` Permissions-Policy check.
+        const inflight = this._sessionSupportedInFlight[mode];
+        if (inflight !== undefined) return inflight;
+
+        // No WebXR API available right now: report unsupported but do NOT cache it. A WebXR
+        // polyfill or emulator (iwer, the WebXR browser extension) may install navigator.xr
+        // AFTER engine init, and until it exists there is no devicechange event that could
+        // invalidate a cached false.
+        const xrSystem = this.xrSystem;
+        if (!xrSystem) return Promise.resolve(false);
 
         let result: Promise<boolean>;
         // isSessionSupported() requires the `xr-spatial-tracking` permission policy to be
@@ -418,22 +428,32 @@ export class NeedleXRSession implements INeedleXRSession {
             result = Promise.resolve(false);
         }
         else {
-            result = (this.xrSystem?.isSessionSupported(mode) ?? Promise.resolve(false))
+            result = xrSystem.isSessionSupported(mode)
                 .catch(err => { if (debug) console.error(err); return false; });
         }
-        this._sessionSupportedCache[mode] = result;
+        this._sessionSupportedInFlight[mode] = result;
+        result.then(v => {
+            this._sessionSupportedCache[mode] = v;
+            delete this._sessionSupportedInFlight[mode];
+        });
         return result;
     }
 
-    private static _sessionSupportedCache: { [mode in XRSessionMode]?: Promise<boolean> } = {};
+    /** Resolved support results, kept as booleans so call sites can read them synchronously (e.g. the iOS AppClip path). */
+    private static _sessionSupportedCache: { [mode in XRSessionMode]?: boolean } = {};
+    /** In-flight probes, to de-duplicate concurrent isSessionSupported() calls per mode. */
+    private static _sessionSupportedInFlight: { [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;
+        const xr = this.xrSystem;
+        // navigator.xr may not exist yet (polyfill/emulator installed later) — retry on the next call.
+        if (!xr) return;
         this._deviceChangeHooked = true;
         try {
-            this.xrSystem?.addEventListener?.("devicechange", () => { this._sessionSupportedCache = {}; });
+            xr.addEventListener?.("devicechange", () => { this._sessionSupportedCache = {}; this._sessionSupportedInFlight = {}; });
         }
         catch { /* xrSystem may not support events; cache simply won't be invalidated */ }
     }
@@ -597,11 +617,9 @@ export class NeedleXRSession implements INeedleXRSession {
 
                 // if we are in an iframe, we need to navigate the top window
                 const topWindow = window.top || window;
-                const originalUrl = topWindow.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();
 
@@ -614,40 +632,16 @@ 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 (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...
-                    // 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");
-                        // eslint-disable-next-line xss/no-location-href-assign
-                        topWindow.location.href = secondUrl.toString();
-
-                        // wait a bit to give the device time to fetch the app clip metadata - this seems to fix the double tap issue (500 ms seem to work)
-                        await new Promise(res => setTimeout(res, 300));
-                    }
-
-                    // navigate to app clip url but keep the current url in history, open in same tab
+                    // Navigate to the App Clip invocation URL synchronously, INSIDE the tap's user
+                    // activation. iOS only presents the App Clip card for a navigation that happens
+                    // within the user gesture — the previous prewarm sequence (navigate to a
+                    // `?prewarm=1` variant, await 300ms, navigate again) pushed the real invocation
+                    // out of the gesture, which is one reason the card regularly needed a second tap.
+                    // The invocation itself makes iOS fetch the experience metadata, so on a cold
+                    // metadata cache the card may still need a second tap (the button shows
+                    // "Tap again" for that case), but a warm cache now presents on the first tap.
                     // eslint-disable-next-line xss/no-location-href-assign
                     topWindow.location.href = urlStr;
-
-                    if (allowMultipleNavigations && !DeviceUtilities.isSafari()) {
-                        setTimeout(() => {
-                            const url2 = new URL(url);
-                            url2.searchParams.set("prewarm", "1");
-                            // eslint-disable-next-line xss/no-location-href-assign
-                            topWindow.location.href = url2.toString();
-                        }, 500);
-                    }
-
-                    sessionStorage.setItem(key, "1");
-
                 }
                 catch (e) {
                     console.warn(`Error navigating to AppClip ${urlStr}\n`, e);

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

package/src/engine/xr/init.ts

@@ -12,12 +12,11 @@ export function initXR() {
 
     if (DeviceUtilities.isiOS()) {
 
-        // Prefetch (uses the custom branded AppClip experience if NeedleXRSession.appClipUrl is set, otherwise the default Needle AppClip)
+        // Note: a page-level fetch() of the AppClip URL was removed here — it only warms the
+        // BROWSER's http cache, while the App Clip card is gated on the OS-level experience
+        // metadata cache, which page javascript cannot populate. The preconnect below covers
+        // the useful part (warming the connection for the invocation navigation).
         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.
-        });
 
         try {
             // We add the meta tag here to preload app clip card data for iOS.