@needle-tools/engine 5.1.0-next.1780579670.dramatic-pierogi.b8fa941 → 5.1.0

package/src/engine/engine_license.ts

@@ -9,19 +9,19 @@ import { getParam } from "./engine_utils.js";
 
 const debug = getParam("__debuglic__");
 
-const __rcJRW: ((result: boolean) => void)[] = [];
+const __HMYWc: ((result: boolean) => void)[] = [];
 
 // DO NOT EDIT MANUALLY
-let sFwQAmo: string = "";
+let _LquBhwVh: string = "";
 // eslint-disable-next-line prefer-const
-let jEi: string = "";
+let BEvs: string = "";
 
 if (debug) {
-    console.log("License Type: " + sFwQAmo);
-    if (jEi) {
-        console.log("License JWT: " + jEi);
+    console.log("License Type: " + _LquBhwVh);
+    if (BEvs) {
+        console.log("License JWT: " + BEvs);
         try {
-            const payload = JSON.parse(atob(jEi.split(".")[1].replace(/-/g, '+').replace(/_/g, '/')));
+            const payload = JSON.parse(atob(BEvs.split(".")[1].replace(/-/g, '+').replace(/_/g, '/')));
             console.log("License JWT payload:", payload);
         }
         catch { console.log("License JWT payload: (failed to decode)"); }
@@ -32,8 +32,8 @@ if (debug) {
 }
 
 /** @internal */
-export function _$zFmYj() {
-    switch (sFwQAmo) {
+export function rXELCf() {
+    switch (_LquBhwVh) {
         case "pro":
         case "enterprise":
             return true;
@@ -42,8 +42,8 @@ export function _$zFmYj() {
 }
 
 /** @internal */
-export function _$DeHzisx() {
-    switch (sFwQAmo) {
+export function $RHhhju() {
+    switch (_LquBhwVh) {
         case "indie":
             return true;
     }
@@ -51,8 +51,8 @@ export function _$DeHzisx() {
 }
 
 /** @internal */
-export function $nFnGL() {
-    switch (sFwQAmo) {
+export function FeDU() {
+    switch (_LquBhwVh) {
         case "edu":
             return true;
     }
@@ -60,20 +60,20 @@ export function $nFnGL() {
 }
 
 /** @internal */
-export function __EOmPHdLs() {
-    return _$zFmYj() || _$DeHzisx() || $nFnGL();
+export function $iujBhf() {
+    return rXELCf() || $RHhhju() || FeDU();
 }
 
 
 /** @internal */
-export function __scPCAmj(cb: (result: boolean) => void) {
-    if (_$zFmYj() || _$DeHzisx() || $nFnGL())
+export function _$GTZ(cb: (result: boolean) => void) {
+    if (rXELCf() || $RHhhju() || FeDU())
         return cb(true);
-    __rcJRW.push(cb);
+    __HMYWc.push(cb);
 }
 
-function _hpBlmJnZ(result: boolean) {
-    for (const cb of __rcJRW) {
+function _zbDz(result: boolean) {
+    for (const cb of __HMYWc) {
         try {
             cb(result);
         }
@@ -88,7 +88,7 @@ function _hpBlmJnZ(result: boolean) {
 
 // ECDSA P-256 public key for verifying license JWTs (verification-only, safe to ship)
 /* eslint-disable no-secrets/no-secrets -- public key, not a secret */
-const __FmduHvp = {
+const _FzlE = {
     kty: "EC",
     crv: "P-256",
     x: "A34nyKMjhQYVgzeE4tyLUYdx34TAKogDa7v7PRaO9Lg",
@@ -112,7 +112,7 @@ function base64urlDecode(str: string): Uint8Array {
  * Verify a JWT license token and return the `type` claim if valid.
  * Returns null if the JWT is missing, malformed, or has an invalid signature.
  */
-async function __ChbkwvSj(jwt: string): Promise<string | null> {
+async function _$jmD(jwt: string): Promise<string | null> {
     if (!jwt) return null;
     try {
         const parts = jwt.split(".");
@@ -122,7 +122,7 @@ async function __ChbkwvSj(jwt: string): Promise<string | null> {
 
         const key = await crypto.subtle.importKey(
             "jwk",
-            __FmduHvp,
+            _FzlE,
             { name: "ECDSA", namedCurve: "P-256" },
             false,
             ["verify"]
@@ -182,24 +182,24 @@ async function __ChbkwvSj(jwt: string): Promise<string | null> {
 }
 
 /** Verify the injected JWT and update the license type if valid.
- * The engine ONLY trusts the JWT — the plain sFwQAmo string is ignored. */
+ * The engine ONLY trusts the JWT — the plain _LquBhwVh string is ignored. */
 let _jwtVerificationPromise: Promise<void> | undefined = undefined;
-async function _$mNAO(): Promise<void> {
-    // NOTE: do NOT add an `if (!jEi) return` guard here.
+async function _gclCQI(): Promise<void> {
+    // NOTE: do NOT add an `if (!BEvs) return` guard here.
     // esbuild (Vite dependency pre-bundling) would see the variable as constant ""
     // and tree-shake the entire JWT verification code path.
-    const jwt = jEi;
+    const jwt = BEvs;
     // Clear after reading — this reassignment also prevents esbuild from
     // constant-folding the variable (it now has multiple assignment sites).
-    jEi = "";
-    const verifiedType = await __ChbkwvSj(jwt);
+    BEvs = "";
+    const verifiedType = await _$jmD(jwt);
     if (verifiedType) {
-        sFwQAmo = verifiedType;
+        _LquBhwVh = verifiedType;
         if (debug) console.log("License type set from verified JWT: " + verifiedType);
-        _hpBlmJnZ(__EOmPHdLs());
+        _zbDz($iujBhf());
     }
     else {
-        sFwQAmo = "basic";
+        _LquBhwVh = "basic";
         if (debug && jwt) console.warn("JWT verification failed — license reset to basic");
     }
 }
@@ -271,7 +271,7 @@ export namespace Telemetry {
 
         const attribute = domElement?.getAttribute("no-telemetry");
         if (attribute === "" || attribute === "true" || attribute === "1") {
-            if (sFwQAmo === "pro" || sFwQAmo === "enterprise") {
+            if (_LquBhwVh === "pro" || _LquBhwVh === "enterprise") {
                 if (debug) console.debug("Telemetry is disabled via no-telemetry attribute");
                 return false;
             }
@@ -378,32 +378,32 @@ export namespace Telemetry {
 }
 
 
-export function _$sRDk() {
+export function __tBFssqnm() {
 
-    if(sFwQAmo === "") sFwQAmo = "basic";
+    if(_LquBhwVh === "") _LquBhwVh = "basic";
 
     // Start JWT verification — must be here (not top-level) to avoid tree-shaking
-    _jwtVerificationPromise = _$mNAO();
+    _jwtVerificationPromise = _gclCQI();
 
     Telemetry.init();
     ContextRegistry.registerCallback(ContextEvent.ContextRegistered, evt => {
-        $jdMSrl(evt.context);
-        nJF(evt.context);
-        setTimeout(() => _fqbFnUXZ(evt.context), 2000);
+        IiDral(evt.context);
+        _ZrecT(evt.context);
+        setTimeout(() => bdYvL(evt.context), 2000);
     });
 }
 
-export let MYnb: Promise<void> | undefined = undefined;
+export let $rKLNDMS: Promise<void> | undefined = undefined;
 let applicationIsForbidden = false;
 let applicationForbiddenText = "";
-async function GNE() {
+async function _$aKpvmr() {
     // Only perform the runtime license check once
-    if (MYnb) return MYnb;
+    if ($rKLNDMS) return $rKLNDMS;
     // Wait for JWT verification to complete first (if running)
     if (_jwtVerificationPromise) {
         await _jwtVerificationPromise;
     }
-    if (sFwQAmo === "basic") {
+    if (_LquBhwVh === "basic") {
         try {
             const licenseUrl = "https://needle.tools/api/v1/needle-engine/check?location=" + encodeURIComponent(window.location.href) + "&version=" + VERSION + "&generator=" + encodeURIComponent(GENERATOR);
             const res = await fetch(licenseUrl, {
@@ -415,29 +415,29 @@ async function GNE() {
             if (res?.status === 200) {
                 applicationIsForbidden = false;
                 if (debug) console.log("License check succeeded");
-                sFwQAmo = "pro";
-                _hpBlmJnZ(true);
+                _LquBhwVh = "pro";
+                _zbDz(true);
             }
             else if (res?.status === 403) {
-                _hpBlmJnZ(false);
+                _zbDz(false);
                 applicationIsForbidden = true;
                 applicationForbiddenText = await res.text();
             }
             else {
-                _hpBlmJnZ(false);
+                _zbDz(false);
                 if (debug) console.log("License check failed with status " + res?.status);
             }
         }
         catch (err) {
-            _hpBlmJnZ(false);
+            _zbDz(false);
             if (debug) console.error("License check failed", err);
         }
     }
-    else if (debug) console.log("Runtime license check is skipped because license is already applied as \"" + sFwQAmo + "\"");
+    else if (debug) console.log("Runtime license check is skipped because license is already applied as \"" + _LquBhwVh + "\"");
 }
-MYnb = GNE();
+$rKLNDMS = _$aKpvmr();
 
-async function nJF(ctx: IContext) {
+async function _ZrecT(ctx: IContext) {
     function createForbiddenElement() {
         const div = document.createElement("div");
         div.className = "needle-forbidden";
@@ -502,40 +502,40 @@ async function nJF(ctx: IContext) {
     }, 500)
 }
 
-async function $jdMSrl(ctx: IContext) {
+async function IiDral(ctx: IContext) {
     try {
-        if (!_$zFmYj() && !_$DeHzisx()) {
-            return __hjIiBVlU(ctx);
+        if (!rXELCf() && !$RHhhju()) {
+            return __CidXaFe(ctx);
         }
     }
     catch (err) {
         if (debug) console.log("License check failed", err)
-        return __hjIiBVlU(ctx)
+        return __CidXaFe(ctx)
     }
-    if (debug) __hjIiBVlU(ctx)
+    if (debug) __CidXaFe(ctx)
 }
 
 
 
-async function __hjIiBVlU(ctx: IContext) {
+async function __CidXaFe(ctx: IContext) {
 
     // if the engine loads faster than the license check, we need to capture the ready event here
     let isReady = false;
     ctx.domElement.addEventListener("ready", () => isReady = true);
 
-    await MYnb?.catch(() => { });
+    await $rKLNDMS?.catch(() => { });
 
 
-    if (_$zFmYj() || _$DeHzisx()) return;
-    if (__EOmPHdLs() === false) __IemeBi();
+    if (rXELCf() || $RHhhju()) return;
+    if ($iujBhf() === false) _$vPpCic();
 
     // check if the engine is already ready (meaning has finished loading)
     if (isReady) {
-        wQoTi(ctx);
+        _UnZAOAPG(ctx);
     }
     else {
         ctx.domElement.addEventListener("ready", () => {
-            wQoTi(ctx);
+            _UnZAOAPG(ctx);
         });
     }
 }
@@ -543,7 +543,7 @@ async function __hjIiBVlU(ctx: IContext) {
 // const licenseElementIdentifier = "needle-license-element";
 // const licenseDuration = 10000;
 // const licenseDelay = 1200;
-function wQoTi(ctx: IContext) {
+function _UnZAOAPG(ctx: IContext) {
 
     const style = `
         position: relative;
@@ -556,7 +556,7 @@ function wQoTi(ctx: IContext) {
         padding: 10px;
         padding-left: 30px;
     `;
-    if (sFwQAmo === "edu") {
+    if (_LquBhwVh === "edu") {
         if (navigator.webdriver) {
             console.log("This project is supported by Needle for Education – https://needle.tools");
         }
@@ -613,7 +613,7 @@ function wQoTi(ctx: IContext) {
         }
     }, 1000);
 
-    if ($nFnGL()) {
+    if (FeDU()) {
         const removeDelay = 20_000;
         setTimeout(() => {
             clearInterval(interval);
@@ -622,7 +622,7 @@ function wQoTi(ctx: IContext) {
             const intervalInMinutes = 5;
             setTimeout(() => {
                 if (ctx.domElement.parentNode)
-                    wQoTi(ctx);
+                    _UnZAOAPG(ctx);
             }, 1000 * 60 * intervalInMinutes)
         }, removeDelay);
     }
@@ -633,7 +633,7 @@ function wQoTi(ctx: IContext) {
 const base64Logo = "data:image/webp;base64,UklGRrABAABXRUJQVlA4WAoAAAAQAAAAHwAAHwAAQUxQSKEAAAARN6CmbSM4WR7vdARON11EBDq3fLiNbVtVzpMCPlKAEzsx0Y/x+Ovuv4dn0EFE/ydAvz6YggXzgh5sVgXM/zOC/4sii7qgGvB5N7hmuQYwkvazWAu1JPW41FXSHq6pnaQWvqYH18Fc0j1hO/BFTtIeSBlJi5w6qIIO7IOrwhFsB2Yxukif0FTRLpXswHR8MxbslKe9VZsn/Ub5C7YFOpqSTABWUDgg6AAAAFAGAJ0BKiAAIAA+7VyoTqmkpCI3+qgBMB2JbACdMt69DwMIQBLhkTO6XwY00UEDK6cNIDnuNibPf0EgAP7Y1myuiQHLDsF/0h5unrGh6WAbv7aegg2ZMd3uRKfT/3SJztcaujYfTvMXspfCTmYcoO6a+vhC3ss4M8uM58t4siiu59I4aOl59e9Sr6xoxYlHf2v+NnBNpJYeJf8jABQAId/PXuBkLEFkiCucgSGEcfhvajql/j3reCGl0M5/9gQWy7ayNPs+wlvIxFnNfSlfuND4CZOCyxOHhRqOmHN4ULHo3tCSrUNvgAA=";
 
 let lastLogTime = 0;
-async function __IemeBi(_logo?: string) {
+async function _$vPpCic(_logo?: string) {
     const now = Date.now();
     if (now - lastLogTime < 2000) return;
     lastLogTime = now;
@@ -666,7 +666,7 @@ async function __IemeBi(_logo?: string) {
 }
 
 
-async function _fqbFnUXZ(context: IContext) {
+async function bdYvL(context: IContext) {
     // We can't send beacons from cross-origin isolated pages
     if (window.crossOriginIsolated) return;
 
@@ -681,7 +681,7 @@ async function _fqbFnUXZ(context: IContext) {
 
             // current url without query parameters
             const currentUrl = window.location.href.split("?")[0];
-            const license = sFwQAmo;
+            const license = _LquBhwVh;
 
             const beaconData = {
                 license,

package/src/engine/engine_networking_blob.ts

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

@@ -62,9 +62,10 @@ export class PostProcessing {
 
     /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
      * and restored when performance recovers.
-     * @default true
+     * @experimental
+     * @default false
      */
-    adaptiveResolution: boolean = true;
+    adaptiveResolution: boolean = false;
 
     constructor(context: Context) {
         this._context = context;

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 { _$zFmYj } from "../../engine_license.js";
+import { $iujBhf } 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 && _$zFmYj()) {
+            if (!this._showNeedleLogo && $iujBhf()) {
                 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 { __EOmPHdLs, __scPCAmj, Telemetry } from "../../engine_license.js";
+import { $iujBhf, _$GTZ, 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";
@@ -208,14 +208,14 @@ export class NeedleMenu {
     }
 
     /**
-     * Call to show or hide the menu.  
-     * NOTE: Hiding the menu is a PRO feature and requires a needle engine license. Hiding the menu will not work in production without a license.
+     * Call to show or hide the menu.
+     * NOTE: Hiding the menu requires a commercial license. Hiding the menu will not work in production without a license.
      */
     setVisible(visible: boolean) {
         this._menu.setVisible(visible);
     }
 
-    /** When set to false, the Needle Engine logo will be hidden. Hiding the logo requires a needle engine license */
+    /** When set to false, the Needle Engine logo will be hidden. Hiding the logo requires a commercial license */
     showNeedleLogo(visible: boolean) {
         this._menu.showNeedleLogo(visible);
         this._spatialMenu?.showNeedleLogo(visible);
@@ -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(() => __scPCAmj(res => {
-                if (res == true && __EOmPHdLs() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => _$GTZ(res => {
+                if (res == true && $iujBhf() && !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 (!__EOmPHdLs()) {
+                    if (!$iujBhf()) {
                         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) {
@@ -841,7 +841,7 @@ export class NeedleMenuElement extends HTMLElementBase {
                             }
                             // warn only once
                             if (change === 1) {
-                                console.warn(`Needle Menu Warning: You need a PRO license to hide the Needle Engine menu → The menu will be visible in your deployed website if you don't have a PRO license. See https://needle.tools/pricing for details.`);
+                                console.warn(`Needle Menu Warning: You need a commercial license to hide the Needle Engine menu → The menu will be visible in your deployed website without one. See https://needle.tools/pricing for details.`);
                             }
                         }
                         else {
@@ -918,8 +918,8 @@ export class NeedleMenuElement extends HTMLElementBase {
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
         if (!visible) {
-            if (!__EOmPHdLs() || debugNonCommercial) {
-                console.warn("[Needle Engine] You need a PRO license to hide the Needle Engine logo in production.");
+            if (!$iujBhf() || 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 { __EOmPHdLs, _$zFmYj, MYnb } from "../engine_license.js";
+import { $iujBhf, rXELCf, $rKLNDMS } 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 = _$zFmYj();
+        const hasLicense = rXELCf();
         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 = __EOmPHdLs();
+    //     let commercialLicense = $iujBhf();
     //     // 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() && MYnb) {
+    //     if (!isDevEnvironment() && $rKLNDMS) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await MYnb;
-    //         commercialLicense = __EOmPHdLs();
+    //         await $rKLNDMS;
+    //         commercialLicense = $iujBhf();
     //     }
     //     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 { __EOmPHdLs } from "../engine_license.js";
+import { $iujBhf } 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 = __EOmPHdLs();
+        const allowOverridingDefaultLoading = $iujBhf();
         // 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

@@ -291,6 +291,49 @@ export class NeedleXRSession implements INeedleXRSession {
     static get currentSessionRequest(): XRSessionMode | null { return this._currentSessionRequestMode; }
     private static _currentSessionRequestMode: XRSessionMode | null = null;
 
+    /** Base URL for branded Needle AppClip experiences */
+    private static readonly appClipBaseUrl = "https://appclip.needle.tools/x/";
+    private static _appClipUrl: string | null = null;
+    /**
+     * Optionally provide a custom Needle AppClip experience to open on iOS instead of the default Needle AppClip.
+     * This enables custom App Clip card branding (your own title and image) when launching AR on iPhone and iPad.
+     *
+     * You can provide either:
+     * - the full URL, e.g. `https://appclip.needle.tools/x/your-experience`
+     * - or just the experience id, e.g. `your-experience` (expanded to `https://appclip.needle.tools/x/your-experience`)
+     *
+     * **IMPORTANT**: the resulting URL must exactly match an App Clip experience URL you have registered (with custom card metadata).
+     * For this reason the URL is opened as-is, without appending any query parameters.
+     * @link https://appclip.needle.tools
+     */
+    static get appClipUrl(): string | null { return this._appClipUrl; }
+    static set appClipUrl(value: string | null) {
+        if (!value) {
+            this._appClipUrl = null;
+            return;
+        }
+        const trimmed = value.trim();
+        // accept a full URL as-is, otherwise treat the value as an experience id and expand it using the base url
+        this._appClipUrl = /^https?:\/\//i.test(trimmed)
+            ? trimmed
+            : this.appClipBaseUrl + trimmed.replace(/^\/+/, "");
+    }
+
+    /**
+     * @internal
+     * Returns the AppClip launch URL to open (or prefetch) on iOS for the current page.
+     * When a custom {@link appClipUrl} is set this is the branded experience URL (opened as-is so it matches the registered URL);
+     * otherwise it is the default Needle AppClip launch URL with the current page forwarded via the `url` parameter.
+     */
+    static getAppClipLaunchUrl(): URL {
+        if (this._appClipUrl) return new URL(this._appClipUrl);
+        // Forward to the default Needle AppClip experience (using the apple.com url the appclip overlay shows immediately)
+        // alternative: `https://appclip.needle.tools/ar?url=${location.href}`
+        const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
+        url.searchParams.set("url", location.href);
+        return url;
+    }
+
     /**
      * @returns the active @type {NeedleXRSession} (if any active) or null
      */
@@ -498,10 +541,10 @@ export class NeedleXRSession implements INeedleXRSession {
                 const topWindow = window.top || window;
                 const originalUrl = topWindow.location.href;
 
-                // Forward to the AppClip experience (Using the apple.com url the appclip overlay shows immediately)
-                // const url =`https://appclip.needle.tools/ar?url=${(location.href)}`;
-                const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
-                url.searchParams.set("url", location.href);
+                // Forward to the AppClip experience. By default this is the Needle AppClip; a custom branded
+                // experience can be set via NeedleXRSession.appClipUrl (which is then opened as-is so it matches the registered URL).
+                const customAppClip = NeedleXRSession.appClipUrl !== null;
+                const url = NeedleXRSession.getAppClipLaunchUrl();
                 const urlStr = url.toString();
 
                 Telemetry.sendEvent(Context.Current, "xr", {
@@ -513,12 +556,15 @@ export class NeedleXRSession implements INeedleXRSession {
                 try {
                     console.debug("iOS device detected - opening Needle App Clip for AR experience", { mode, init, url });
 
-                    // Prewarm the appclip by opening the URL
+                    // Prewarm the appclip by opening the URL (with an extra ?prewarm=1 param) to fetch the app clip
+                    // metadata faster - this fixes a double-tap issue on iOS.
                     // BUT on safari triggering this with multiple URLs causes the
                     // Browser to show the dialogue AGAIN in the background
                     // SO: we don't do it here...
-                    const key = "appclip-prewarm:" + new URL(url).origin;
-                    const allowMultipleNavigations = sessionStorage.getItem(key) === null;
+                    // We also skip prewarming for a custom branded experience: that URL must match the registered
+                    // App Clip experience URL exactly, so we must not append any query parameters to it.
+                    const key = "appclip-prewarm:" + url.origin;
+                    const allowMultipleNavigations = !customAppClip && sessionStorage.getItem(key) === null;
                     if (allowMultipleNavigations) {
                         const secondUrl = new URL(url);
                         secondUrl.searchParams.set("prewarm", "1");

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { __EOmPHdLs } from "../engine_license.js";
+import { $iujBhf } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (__EOmPHdLs()) {
+        if ($iujBhf()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");