@needle-tools/engine 5.1.0-canary.db0c38f → 5.1.0-canary.e6680fa

package/src/engine/engine_serialization_core.ts

@@ -207,6 +207,15 @@ export interface ISerializable {
     onAfterDeserialize?(data: any, context: SerializationContext): void;
 };
 
+export function isSerializable(obj: any): obj is ISerializable {
+    return obj && typeof obj === "object" && (
+        typeof obj.$serializedTypes === "object" ||
+        typeof obj.onBeforeDeserialize === "function" ||
+        typeof obj.onBeforeDeserializeMember === "function" ||
+        typeof obj.onAfterDeserializeMember === "function" ||
+        typeof obj.onAfterDeserialize === "function"
+    )
+}
 
 export function serializeObject(obj: ISerializable, context: SerializationContext): object | null {
     const types = obj.$serializedTypes;

package/src/engine/engine_ssr.ts

@@ -9,14 +9,40 @@
  * to a plain empty class so that `class Foo extends HTMLElementBase` is valid.
  */
 
+
+/** True when running in an SSR/Node environment (no browser globals). */
+export const SSR: boolean = typeof window === "undefined";
+
 /** SSR-safe base class for web components. */
 export const HTMLElementBase: typeof HTMLElement =
-    typeof HTMLElement !== "undefined" ? HTMLElement : (class {} as unknown as typeof HTMLElement);
+    typeof HTMLElement !== "undefined" ? HTMLElement : (class { } as unknown as typeof HTMLElement);
 
 /** SSR-safe base class for pointer events. */
 export const PointerEventBase: typeof PointerEvent =
-    typeof PointerEvent !== "undefined" ? PointerEvent : (class {} as unknown as typeof PointerEvent);
+    typeof PointerEvent !== "undefined" ? PointerEvent : (class { } as unknown as typeof PointerEvent);
 
 /** SSR-safe base class for keyboard events. */
 export const KeyboardEventBase: typeof KeyboardEvent =
-    typeof KeyboardEvent !== "undefined" ? KeyboardEvent : (class {} as unknown as typeof KeyboardEvent);
+    typeof KeyboardEvent !== "undefined" ? KeyboardEvent : (class { } as unknown as typeof KeyboardEvent);
+
+
+
+
+// #region minimal polyfills
+// Three.js FileLoader uses ProgressEvent in fetch stream callbacks.
+// It doesn't exist in Node — install a minimal stub so SSR doesn't crash.
+if (typeof globalThis.ProgressEvent === "undefined") {
+    (globalThis as any).ProgressEvent = class ProgressEvent {
+        readonly type: string;
+        readonly lengthComputable: boolean;
+        readonly loaded: number;
+        readonly total: number;
+        constructor(type: string, init?: { lengthComputable?: boolean; loaded?: number; total?: number }) {
+            this.type = type;
+            this.lengthComputable = init?.lengthComputable ?? false;
+            this.loaded = init?.loaded ?? 0;
+            this.total = init?.total ?? 0;
+        }
+    };
+}
+// #endregion

package/src/engine/engine_types.ts

@@ -5,7 +5,6 @@ import { type GLTF as THREE_GLTF } from "three/examples/jsm/loaders/GLTFLoader.j
 
 import type { Camera as CameraComponent } from "../engine-components/api.js";
 import type { Context } from "./engine_context.js";
-import { InstantiateContext } from "./engine_gameobject.js";
 import { CollisionDetectionMode, type PhysicsMaterial, RigidbodyConstraints } from "./engine_physics.types.js";
 import { CircularBuffer } from "./engine_utils.js";
 import type { NeedleXRSession } from "./engine_xr.js";
@@ -196,13 +195,11 @@ export interface IComponent extends IHasGuid {
     /** @internal */
     __internalStart();
     /** @internal */
-    __internalEnable(isAddingOrRemovingFromScene?: boolean);
+    __internalEnable(isHierarchyChange?: boolean);
     /** @internal */
-    __internalDisable(isAddingOrRemovingFromScene?: boolean);
+    __internalDisable(isHierarchyChange?: boolean);
     /** @internal */
     __internalDestroy();
-    /** @internal */
-    resolveGuids?(guidsMap: GuidsMap): void;
 
     /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
     registering?();
@@ -240,14 +237,14 @@ export interface IComponent extends IHasGuid {
 }
 
 export function isComponent(obj: any): obj is IComponent {
-    return obj && obj.isComponent;
+    return obj && typeof obj === "object" && obj.isComponent;
 }
 
 export type ICamera = CameraComponent;
 
 export type IAnimationComponent = Pick<IComponent, "gameObject"> & {
     isAnimationComponent: boolean;
-    addClip?(clip: AnimationClip);
+    addClip?(clip: AnimationClip): void;
 }
 
 /** Interface for a camera controller component that can be attached to a camera to control it */
@@ -258,6 +255,8 @@ export declare interface ICameraController {
 export declare interface ILight extends IComponent {
     intensity: number;
     color: Color;
+    /** The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"` */
+    readonly type: "directional" | "point" | "spot";
 }
 
 export declare interface ISharedMaterials {
@@ -272,7 +271,10 @@ export declare interface IRenderer extends IComponent {
 
 export declare interface IEventList {
     readonly isEventList: true;
-    __internalOnInstantiate(map: InstantiateContext): IEventList;
+}
+
+export declare interface ISignalReceiver {
+    readonly isSignalReceiver: true;
 }
 
 // export declare interface IPhysicsComponent extends IComponent {
@@ -300,12 +302,18 @@ export declare interface ICollider extends IComponent {
      * Default: [0]
     */
     membership?: number[];
-    /** The collider filter indicates what groups the collider can interact with (e.g. group 3 and 4)   
-     * An `undefined` array indicates that the collider can interact with all groups   
-     * Note: Make sure to call updateProperties after having changed this property  
+    /** The collider filter indicates what groups the collider can interact with (e.g. group 3 and 4)
+     * An `undefined` array indicates that the collider can interact with all groups
+     * Note: Make sure to call updateProperties after having changed this property
      * Default: undefined
     */
     filter?: number[];
+    /** The density of the collider used for automatic mass calculation.
+     * When the attached Rigidbody has `autoMass` enabled, the mass is computed as `density × volume`.
+     * Note: Make sure to call updateProperties after having changed this property
+     * Default: undefined (uses physics engine default of 1.0)
+    */
+    density?: number;
 }
 
 export declare interface ISphereCollider extends ICollider {
@@ -473,8 +481,10 @@ export interface IPhysicsEngine {
     postStep();
     /** Indicates whether the physics engine is currently updating */
     get isUpdating(): boolean;
-    /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
-    clearCaches();
+    /** Tears down the physics world and frees all resources. The world will be re-created on next use. */
+    dispose(): void;
+    /** @deprecated Use {@link dispose} instead. */
+    clearCaches(): void;
 
     /** Enables or disables the physics engine */
     enabled: boolean;
@@ -511,20 +521,25 @@ export interface IPhysicsEngine {
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** 
-         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
-         * The scene query will only consider hits with colliders with collision groups compatible with 
+        /**
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query.
+         * The scene query will only consider hits with colliders with collision groups compatible with
          * this collision group (using the bitwise test described in the collision groups section).
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002
          * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
          */
         filterGroups?: number,
-        /** 
+        /**
          * Predicate to filter colliders in raycast results
          * @param collider The collider being tested
          * @returns False to ignore this collider, true to include it
          */
-        filterPredicate?: (collider: ICollider) => boolean
+        filterPredicate?: (collider: ICollider) => boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     }): RaycastResult;
 
     /**
@@ -539,20 +554,25 @@ export interface IPhysicsEngine {
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** 
-         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
-         * The scene query will only consider hits with colliders with collision groups compatible with 
+        /**
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query.
+         * The scene query will only consider hits with colliders with collision groups compatible with
          * this collision group (using the bitwise test described in the collision groups section).
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002
          * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
          */
         filterGroups?: number,
-        /** 
+        /**
          * Predicate to filter colliders in raycast results
          * @param collider The collider being tested
          * @returns False to ignore this collider, true to include it
          */
-        filterPredicate?: (collider: ICollider) => boolean
+        filterPredicate?: (collider: ICollider) => boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     }): RaycastResult;
 
     /**
@@ -736,8 +756,9 @@ export interface IPhysicsEngine {
     getBody(obj: ICollider | IRigidbody): null | any;
 
     // Joints
-    addFixedJoint(body1: IRigidbody, body2: IRigidbody);
-    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3);
+    addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<any> | any;
+    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): Promise<any> | any;
+    removeJoint(joint: any): void;
 
     /** Enable to render collider shapes */
     debugRenderColliders: boolean;

package/src/engine/engine_util_decorator.ts

@@ -79,8 +79,12 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
                 return;
             }
 
-            // only build wrapper once per type
-            if (this[$prop] === undefined) {
+            // Only install the getter/setter once per instance.
+            // processStart may call __internalAwake again for components that were inactive
+            // during processNewScripts — the base Component.__internalAwake has a __didAwake guard
+            // but this decorator wrapper runs before reaching it, so we need our own idempotency check.
+            const desc = Object.getOwnPropertyDescriptor(this, propertyKey);
+            if (!desc || !desc.get) {
 
                 // make sure the field is initialized in a hidden property
                 this[$prop] = this[propertyKey];
@@ -99,6 +103,7 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
                 }
 
                 Object.defineProperty(this, propertyKey, {
+                    configurable: true,
                     set: function (v) {
                         if (this[$isAssigningProperties] === true) {
                             this[$prop] = v;

package/src/engine/engine_utils.ts

@@ -279,24 +279,35 @@ declare type deepClonePredicate = (owner: any, propertyName: string, current: an
  *   return true;
  * });
  * */
-export function deepClone(obj: any, predicate?: deepClonePredicate): any {
+export function deepClone(obj: any, predicate?: deepClonePredicate, _visited?: WeakSet<object>): any {
     if (obj !== null && obj !== undefined && typeof obj === "object") {
+        if (!_visited) _visited = new WeakSet();
+        if (_visited.has(obj)) return obj;
+        _visited.add(obj);
+
         let clone;
         if (Array.isArray(obj)) clone = [];
         else {
-            clone = Object.create(obj);
-            Object.assign(clone, obj);
+            clone = Object.create(Object.getPrototypeOf(obj));
+            // Copy own properties, skipping getter-only properties that can't be set
+            const descriptors = Object.getOwnPropertyDescriptors(obj);
+            for (const key in descriptors) {
+                const desc = descriptors[key];
+                if (desc.set || desc.writable !== false) {
+                    try { clone[key] = obj[key]; }
+                    catch { /* skip read-only properties */ }
+                }
+            }
         }
         for (const key of Object.keys(obj)) {
             const val = obj[key];
             if (predicate && !predicate(obj, key, val)) {
-                // console.log("SKIP", val);
                 clone[key] = val;
             }
             else if (val?.clone !== undefined && typeof val.clone === "function")
                 clone[key] = val.clone();
             else
-                clone[key] = deepClone(val, predicate);
+                clone[key] = deepClone(val, predicate, _visited);
         }
         return clone;
     }

package/src/engine/engine_utils_format.ts

@@ -205,7 +205,26 @@ export function tryDetermineMimetypeFromBinary(url: string, data: ArrayBuffer, r
         if (debug) console.debug("OBJ detected");
         return "model/obj";
     }
-    else if (response.headers.has("content-type")) {
+    // Run registered mimetype callbacks BEFORE the Content-Type-based dispatch
+    // below. Otherwise files served as `image/*` (HDRIs, KTX2 textures, etc.)
+    // hit the hardcoded `image/* → "unsupported"` early-out and the engine
+    // never asks our custom detectors whether they want to claim them.
+    // Known binary signatures (GLTF, USD, FBX, OBJ above) still resolve first
+    // and bypass this loop — no perf regression for the common path.
+    for (const callback of registeredMimetypeCallbacks) {
+        const mimetype = callback({
+            url: url,
+            response: response,
+            contentType: response.headers.get("content-type"),
+            bytes: bytes
+        })
+        if (mimetype) {
+            if (debug) console.debug(`Mimetype callback returned: ${mimetype}`);
+            return mimetype;
+        }
+    }
+
+    if (response.headers.has("content-type")) {
         const content_type = response.headers.get("content-type");
         if (content_type?.startsWith("image/")) {
             if (debug) console.debug("Image detected, not a model file");
@@ -259,19 +278,6 @@ export function tryDetermineMimetypeFromBinary(url: string, data: ArrayBuffer, r
     //     return "gltf";
     // }
 
-    for (const callback of registeredMimetypeCallbacks) {
-        const mimetype = callback({
-            url: url,
-            response: response,
-            contentType: response.headers.get("content-type"),
-            bytes: bytes
-        })
-        if (mimetype) {
-            if (debug) console.debug(`Mimetype callback returned: ${mimetype}`);
-            return mimetype;
-        }
-    }
-
 
     if (isDevEnvironment() || debug) {
         const text = new TextDecoder().decode(data.slice(0, Math.min(data.byteLength, 32)));

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 { hasCommercialLicense } from "./engine_license.js";
+import { __gGoBKfJa } 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 = hasCommercialLicense();
+    const canUseCustomLogo = __gGoBKfJa();
 
     // 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/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js

@@ -35,7 +35,7 @@ export class GenerateMeshBVHWorker extends WorkerBase {
 
             worker.onerror = e => {
 
-                reject(new Error(`[GenerateMeshBVHWorker] ${e.message || "Unknown error. Please check the server console. If you're using vite try adding 'three-mesh-bvh' to 'optimizeDeps.exclude' in your vite.config.js"}`));
+                reject(new Error(`[GenerateMeshBVHWorker] ${e.message || "Could not load worker."}`));
             
 			};
 

package/src/engine/webcomponents/jsx.d.ts

@@ -0,0 +1,51 @@
+/**
+ * JSX IntrinsicElements declarations for Needle Engine web components.
+ *
+ * Covers both the global JSX namespace (Preact, SolidJS, Svelte, vanilla TS)
+ * and React's module-scoped JSX namespace (react-jsx / react-jsxdev transform).
+ *
+ * IMPORTANT: This file must be a module (has a top-level import/export) so that
+ * `declare module "react"` is treated as a *module augmentation* (merging into
+ * the existing React types) rather than an *ambient module declaration* (which
+ * would shadow/replace @types/react).
+ */
+
+import type { NeedleEngineAttributes } from "./needle-engine.js";
+
+interface NeedleButtonJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+    style?: Partial<CSSStyleDeclaration>;
+    ar?: boolean | string;
+    vr?: boolean | string;
+    quicklook?: boolean | string;
+    qrcode?: boolean | string;
+    unstyled?: boolean | string;
+}
+
+interface NeedleMenuJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+    style?: Partial<CSSStyleDeclaration>;
+}
+
+interface NeedleLogoElementJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+    style?: Partial<CSSStyleDeclaration>;
+}
+
+interface NeedleElements {
+    "needle-engine": Partial<NeedleEngineAttributes>;
+    "needle-button": NeedleButtonJSXAttributes;
+    "needle-menu": NeedleMenuJSXAttributes;
+    "needle-logo-element": NeedleLogoElementJSXAttributes;
+}
+
+// Global JSX namespace — Preact, SolidJS, Svelte, vanilla TS
+declare global {
+    namespace JSX {
+        interface IntrinsicElements extends NeedleElements {}
+    }
+}
+
+// React module-scoped JSX namespace (module augmentation, not ambient declaration)
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements extends NeedleElements {}
+    }
+}

package/src/engine/webcomponents/logo-element.ts

@@ -3,6 +3,7 @@ import { HTMLElementBase } from "../engine_ssr.js";
 
 const elementName = "needle-logo-element";
 
+// NOTE: keep JSX attributes in sync with ./jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
         "needle-logo-element": NeedleLogoElement;

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 { hasProLicense } from "../../engine_license.js";
+import { $TXm } 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 && hasProLicense()) {
+            if (!this._showNeedleLogo && $TXm()) {
                 if (index >= 0) {
                     this._poweredByNeedleElement.removeFromParent();
                     this.markDirty();

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -1,8 +1,8 @@
 import { showBalloonMessage } from "../../debug/debug.js";
-import { HTMLElementBase } from "../../engine_ssr.js";
 import type { Context } from "../../engine_context.js";
-import { hasCommercialLicense, onLicenseCheckResultChanged, Telemetry } from "../../engine_license.js";
+import { __gGoBKfJa, _MFjTEBcQ, 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";
 import { onXRSessionStart, XRSessionEventArgs } from "../../xr/events.js";
 import { ButtonsFactory } from "../buttons.js";
@@ -12,9 +12,10 @@ import { NeedleLogoElement } from "../logo-element.js";
 import { getElementPriority, setElementPriority as _setElementPriority } from "./menu-priority.js";
 import { NeedleSpatialMenu } from "./needle-menu-spatial.js";
 
+// NOTE: keep JSX attributes in sync with ../jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
-        "needle-logo-element": NeedleLogoElement;
+        "needle-menu": NeedleMenuElement;
     }
 }
 
@@ -777,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(() => onLicenseCheckResultChanged(res => {
-                if (res == true && hasCommercialLicense() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => _MFjTEBcQ(res => {
+                if (res == true && __gGoBKfJa() && !debugNonCommercial) {
                     let visible = this._userRequestedLogoVisible;
                     if (visible === undefined) visible = false;
                     this.___onSetLogoVisible(visible);
@@ -829,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 (!hasCommercialLicense()) {
+                    if (!__gGoBKfJa()) {
                         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) {
@@ -917,7 +918,7 @@ export class NeedleMenuElement extends HTMLElementBase {
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
         if (!visible) {
-            if (!hasCommercialLicense() || debugNonCommercial) {
+            if (!__gGoBKfJa() || debugNonCommercial) {
                 console.warn("[Needle Engine] You need a PRO license to hide the Needle Engine logo in production.");
                 const localNetwork = isLocalNetwork()
                 if (!localNetwork) return;

package/src/engine/webcomponents/needle-button.ts

@@ -4,6 +4,7 @@ import { ButtonsFactory } from "./buttons.js";
 import { iconFontUrl, loadFont } from "./fonts.js";
 import { WebXRButtonFactory } from "./WebXRButtons.js";
 
+// NOTE: keep JSX attributes in sync with ./jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
         "needle-button": NeedleButtonElement;

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 { hasCommercialLicense, hasProLicense, runtimeLicenseCheckPromise } from "../engine_license.js";
+import { __gGoBKfJa, $TXm, $NzCTiAr } 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 = hasProLicense();
+        const hasLicense = $TXm();
         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 = hasCommercialLicense();
+    //     let commercialLicense = __gGoBKfJa();
     //     // 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() && runtimeLicenseCheckPromise) {
+    //     if (!isDevEnvironment() && $NzCTiAr) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await runtimeLicenseCheckPromise;
-    //         commercialLicense = hasCommercialLicense();
+    //         await $NzCTiAr;
+    //         commercialLicense = __gGoBKfJa();
     //     }
     //     if (commercialLicense) return;
     //     nonCommercialContainer.style.transition = "opacity .5s ease-in-out";

package/src/engine/webcomponents/needle-engine.ts

@@ -1,11 +1,11 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { HTMLElementBase } from "../engine_ssr.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { hasCommercialLicense } from "../engine_license.js";
+import { __gGoBKfJa } 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";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { nameToThreeTonemapping } from "../engine_tonemapping.js";
 import { type INeedleEngineComponent, type LoadedModel } from "../engine_types.js";
 import type { addAttributeChangeCallback } from "../engine_utils.js";
@@ -17,6 +17,7 @@ import { arContainerClassName, AROverlayHandler } from "./needle-engine.ar-overl
 import type { registerObservableAttribute } from "./needle-engine.extras.js";
 import { calculateProgress01, EngineLoadingView, type ILoadingViewHandler } from "./needle-engine.loading.js";
 
+// NOTE: keep JSX attributes in sync with ./jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
         "needle-engine": NeedleEngineWebComponent;
@@ -41,11 +42,17 @@ export interface NeedleEngineAttributes {
     'hash': string;
     /** Set to automatically add OrbitControls to the loaded scene. */
     'camera-controls': string;
-    /** Override the default draco decoder path location. */
+    /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
+     * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
+     * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
+     */
     'dracoDecoderPath': string;
-    /** Override the default draco library type. */
+    /** Override the default Draco decoder type. */
     'dracoDecoderType': 'wasm' | 'js';
-    /** Override the default KTX2 transcoder/decoder path. */
+    /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
+     * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
+     * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
+     */
     'ktx2DecoderPath': string;
     /** Prevent context from being disposed when element is removed from DOM. */
     'keep-alive': 'true' | 'false';
@@ -539,7 +546,7 @@ export class NeedleEngineWebComponent extends HTMLElementBase implements INeedle
 
 
         // Loading start events
-        const allowOverridingDefaultLoading = hasCommercialLicense();
+        const allowOverridingDefaultLoading = __gGoBKfJa();
         // default loading can be overriden by calling preventDefault in the onload start event
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {