@needle-tools/engine 4.17.0-next.36dcae2 → 4.17.0-next.4989636

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

@@ -8,6 +8,7 @@ import { ButtonsFactory } from "../buttons.js";
 import { ensureFonts, iconFontUrl, loadFont } from "../fonts.js";
 import { getIconElement } from "../icons.js";
 import { NeedleLogoElement } from "../logo-element.js";
+import { getElementPriority, setElementPriority as _setElementPriority } from "./menu-priority.js";
 import { NeedleSpatialMenu } from "./needle-menu-spatial.js";
 
 declare global {
@@ -111,16 +112,11 @@ export declare type ButtonInfo = {
 export class NeedleMenu {
 
     static setElementPriority(button: HTMLElement, priority: number) {
-        button.setAttribute("priority", String(priority));
+        _setElementPriority(button, priority);
     }
 
     static getElementPriority(button: HTMLElement): number | undefined {
-        const priority = button.getAttribute("priority");
-        if (priority) {
-            const val = Number.parseFloat(priority);
-            if (!Number.isNaN(val)) return val;
-        }
-        return undefined;
+        return getElementPriority(button);
     }
 
     private readonly _context: Context;
@@ -310,7 +306,10 @@ export class NeedleMenu {
 export class NeedleMenuElement extends HTMLElement {
 
     static create() {
-        // https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#is
+        // Ensure the element is registered before creating — guards against
+        // cases where this is called before initWebComponents() has run.
+        if (!customElements.get(elementName))
+            customElements.define(elementName, NeedleMenuElement);
         return document.createElement(elementName);
     }
 
@@ -1335,8 +1334,4 @@ export class NeedleMenuElement extends HTMLElement {
         });
         this.appendChild(anotherButton);
     }
-}
-
-
-if (!customElements.get(elementName))
-    customElements.define(elementName, NeedleMenuElement);
+}

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

@@ -9,7 +9,6 @@ declare global {
     }
 }
 
-const htmlTagName = "needle-button";
 const isDev = isDevEnvironment();
 
 /**
@@ -219,5 +218,3 @@ export class NeedleButtonElement extends HTMLElement {
 
 
 
-if (typeof window !== "undefined" && !window.customElements.get(htmlTagName))
-    window.customElements.define(htmlTagName, NeedleButtonElement);

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

@@ -1,18 +1,17 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { registerLoader } from "../engine_gltf.js";
 import { hasCommercialLicense } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
-import { NeedleLoader } from "../engine_loaders.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
 import { nameToThreeTonemapping } from "../engine_tonemapping.js";
 import { type INeedleEngineComponent, type LoadedModel } from "../engine_types.js";
 import type { addAttributeChangeCallback } from "../engine_utils.js";
 import { getParam } from "../engine_utils.js";
 import { RGBAColor } from "../js-extensions/RGBAColor.js";
-import { ensureFonts } from "./fonts.js";
+import { robotoFlexFontUrl } from "./font-urls.js";
+import { ensureFonts, loadFont } from "./fonts.js";
 import { arContainerClassName, AROverlayHandler } from "./needle-engine.ar-overlay.js";
 import type { registerObservableAttribute } from "./needle-engine.extras.js";
 import { calculateProgress01, EngineLoadingView, type ILoadingViewHandler } from "./needle-engine.loading.js";
@@ -23,13 +22,8 @@ declare global {
     }
 }
 
-
-// registering loader here too to make sure it's imported when using engine via vanilla js
-registerLoader(NeedleLoader);
-
 const debug = getParam("debugwebcomponent");
 
-const htmlTagName = "needle-engine";
 const vrContainerClassName = "vr";
 const desktopContainerClassname = "desktop";
 const knownClasses = [arContainerClassName, vrContainerClassName, desktopContainerClassname];
@@ -234,8 +228,6 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         this.attachShadow({ mode: 'open', delegatesFocus: true });
         const template = document.createElement('template');
         template.innerHTML = `<style>
-    @import url('https://fonts.googleapis.com/css2?family=Roboto+Flex:opsz,wght@8..144,100..1000&display=swap');
-
     :host {
         position: absolute;
         display: block;
@@ -313,6 +305,8 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 `;
 
         this.shadowRoot!.appendChild(template.content.cloneNode(true));
+        // Load Roboto font into shadow DOM (instead of @import in CSS to avoid duplicate network requests)
+        loadFont(robotoFlexFontUrl, { element: this.shadowRoot! });
 
         // TODO: do we want to rename this event?
         this.addEventListener("ready", this.onReady);
@@ -1021,9 +1015,6 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     }
 }
 
-if (typeof window !== "undefined" && !window.customElements.get(htmlTagName))
-    window.customElements.define(htmlTagName, NeedleEngineWebComponent);
-
 /** Quick testing for the types as declared above */
 /*
 const elem = document.querySelector("needle-engine")!;

package/src/engine/webcomponents/quicklook-handler.ts

@@ -0,0 +1,37 @@
+/**
+ * Interface for a quicklook handler that can export and open a USDZ file.
+ * Used as an abstraction layer to break the circular dependency between
+ * WebXRButtons and USDZExporter.
+ */
+export interface IQuicklookHandler {
+    objectToExport: any;
+    exportAndOpen(): Promise<any>;
+}
+
+type QuicklookHandlerFactory = {
+    /** Find an existing quicklook handler in the scene */
+    find(): IQuicklookHandler | null;
+    /** Create a new quicklook handler instance */
+    create(): IQuicklookHandler;
+};
+
+let _factory: QuicklookHandlerFactory | undefined;
+
+/**
+ * Register a factory for creating quicklook handlers.
+ * Called by USDZExporter to register itself as the handler.
+ */
+export function setQuicklookHandlerFactory(factory: QuicklookHandlerFactory) {
+    _factory = factory;
+}
+
+/**
+ * Find an existing quicklook handler in the scene, or create a new one if none exists.
+ * @returns A quicklook handler, or null if no factory has been registered.
+ */
+export function getOrCreateQuicklookHandler(): { readonly handler: IQuicklookHandler, readonly created: boolean } | null {
+    if (!_factory) return null;
+    const existing = _factory.find();
+    if (existing) return { handler: existing, created: false };
+    return { handler: _factory.create(), created: true };
+}

package/src/engine/xr/NeedleXRSession.ts

@@ -843,9 +843,10 @@ export class NeedleXRSession implements INeedleXRSession {
      * 
      * **For AR**   
      * If you want to modify the scale in AR at runtime get the WebARSessionRoot component via `findObjectOfType(WebARSessionRoot)` and then set the `arScale` value. 
+     * @returns the scale of the XR rig
      * 
     */
-    get rigScale() {
+    get rigScale(): number {
         // const ar_scaleValue = this.context.domElement.getAttribute("ar-scale");
         // if (ar_scaleValue) {
         //     const scale = parseFloat(ar_scaleValue);

package/src/engine-components/AnimationUtilsAutoplay.ts

@@ -7,7 +7,13 @@ import { Animator } from "./Animator.js";
 import { GameObject } from "./Component.js";
 import { PlayableDirector } from "./timeline/PlayableDirector.js";
 
-ContextRegistry.registerCallback(ContextEvent.ContextCreated, args => {
+let initialized = false;
+
+export function initAnimationAutoplay() {
+    if (initialized) return;
+    initialized = true;
+
+    ContextRegistry.registerCallback(ContextEvent.ContextCreated, args => {
     const autoplay = args.context.domElement.getAttribute("autoplay");
     if (autoplay !== undefined && (autoplay === "" || autoplay === "true" || autoplay === "1")) {
         if (args.files) {
@@ -34,5 +40,4 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreated, args => {
         }
     }
 });
-
-
+}

package/src/engine-components/AnimatorController.ts

@@ -11,7 +11,7 @@ import { TypeStore } from "../engine/engine_typestore.js";
 import { deepClone, getParam } from "../engine/engine_utils.js";
 import type { AnimatorControllerModel, Condition, State, Transition } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 import { AnimatorConditionMode, AnimatorControllerParameterType, AnimatorStateInfo, createMotion, StateMachineBehaviour } from "../engine/extensions/NEEDLE_animator_controller_model.js";
-import { Animator } from "./Animator.js";
+import type { Animator } from "./Animator.js";
 
 const debug = getParam("debuganimatorcontroller");
 const debugRootMotion = getParam("debugrootmotion");

package/src/engine-components/CameraUtils.ts

@@ -13,14 +13,20 @@ import { EnvironmentScene } from "./utils/EnvironmentScene.js";
 
 const debug = getParam("debugmissingcamera");
 
-/**
- * Handler for missing camera events. Creates a default fallback camera when no camera is found in the scene.
- * Sets up camera properties based on the context and HTML element attributes.
- * 
- * @param evt The context event containing scene and configuration information
- * @returns The created camera component
- */
-ContextRegistry.registerCallback(ContextEvent.MissingCamera, (evt) => {
+let initialized = false;
+
+export function initCameraUtils() {
+    if (initialized) return;
+    initialized = true;
+
+    /**
+     * Handler for missing camera events. Creates a default fallback camera when no camera is found in the scene.
+     * Sets up camera properties based on the context and HTML element attributes.
+     *
+     * @param evt The context event containing scene and configuration information
+     * @returns The created camera component
+     */
+    ContextRegistry.registerCallback(ContextEvent.MissingCamera, (evt) => {
     if (debug) console.warn("Creating missing camera")
     const scene = evt.context.scene;
 
@@ -101,6 +107,7 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreated, (evt) => {
         createDefaultCameraControls(evt.context);
     }
 })
+}
 
 /**
  * Creates default orbit camera controls for the specified camera.

package/src/engine-components/Collider.ts

@@ -113,6 +113,16 @@ export abstract class Collider extends Behaviour implements ICollider {
     }
     /** @internal */
     onDisable() {
+        // Use setEnabled(false) to disable the collider without destroying it.
+        // This avoids the cost of recreating the rapier collider on re-enable.
+        if (!this.context.physics.engine?.setColliderEnabled(this, false)) {
+            // Fallback: if the collider wasn't found (e.g. not yet created), remove it
+            this.context.physics.engine?.removeBody(this);
+        }
+    }
+    /** @internal */
+    onDestroy() {
+        // Actually remove the collider from the physics world on destroy
         this.context.physics.engine?.removeBody(this);
     }
 
@@ -183,7 +193,10 @@ export class SphereCollider extends Collider implements ISphereCollider {
      */
     onEnable() {
         super.onEnable();
-        this.context.physics.engine?.addSphereCollider(this);
+        // Re-enable existing collider instead of recreating it
+        if (!this.context.physics.engine?.setColliderEnabled(this, true)) {
+            this.context.physics.engine?.addSphereCollider(this);
+        }
         watchWrite(this.gameObject.scale, this.updateProperties);
     }
 
@@ -267,7 +280,10 @@ export class BoxCollider extends Collider implements IBoxCollider {
      */
     onEnable() {
         super.onEnable();
-        this.context.physics.engine?.addBoxCollider(this, this.size);
+        // Re-enable existing collider instead of recreating it
+        if (!this.context.physics.engine?.setColliderEnabled(this, true)) {
+            this.context.physics.engine?.addBoxCollider(this, this.size);
+        }
         watchWrite(this.gameObject.scale, this.updateProperties);
     }
 
@@ -362,6 +378,8 @@ export class MeshCollider extends Collider {
     onEnable() {
         super.onEnable();
         if (!this.context.physics.engine) return;
+        // Re-enable existing collider instead of recreating it
+        if (this.context.physics.engine.setColliderEnabled(this, true)) return;
 
         if (!this.sharedMesh?.isMesh) {
             // HACK using the renderer mesh
@@ -453,6 +471,9 @@ export class CapsuleCollider extends Collider {
      */
     onEnable() {
         super.onEnable();
-        this.context.physics.engine?.addCapsuleCollider(this, this.height, this.radius);
+        // Re-enable existing collider instead of recreating it
+        if (!this.context.physics.engine?.setColliderEnabled(this, true)) {
+            this.context.physics.engine?.addCapsuleCollider(this, this.height, this.radius);
+        }
     }
 }

package/src/engine-components/LookAtConstraint.ts

@@ -1,7 +1,52 @@
+import { Object3D, Vector3 } from "three";
+
+import { serializable } from "../engine/engine_serialization.js";
 import { Behaviour } from "./Component.js";
 
 /**
- * @deprecated LookAtConstraint has been removed. Use a plain Object3D/Transform reference on OrbitControls instead.
+ * @deprecated LookAtConstraint will be removed in future versions. Please either use a direct object reference instead (e.g. assigning an Object3D as a look target in scripts that reply on the LookAtConstraint) or implement the LookAtConstraint signature in your web project:   
+ * ```ts
+ * export class LookAtConstraint extends Behaviour {
+ *   constraintActive: boolean = true;
+ *   locked: boolean = false;
+ *   sources: Object3D[] = [];
+ *   setConstraintPosition(worldPosition: Vector3) {
+ *     const source = this.sources[0];
+ *     if (source) source.worldPosition = worldPosition;
+ *   }
+ * }
+ * ```
  */
 export class LookAtConstraint extends Behaviour {
+
+    /**
+     * When true, the constraint is active and affects the target.
+     * Set to false to temporarily disable without removing sources.
+     */
+    @serializable()
+    constraintActive: boolean = true;
+
+    /**
+     * When true, the look-at position is locked and won't update
+     * even if source objects move.
+     */
+    @serializable()
+    locked: boolean = false;
+
+    /**
+     * Objects to look at. The first object in the array is used
+     * as the primary look-at target.
+     */
+    @serializable(Object3D)
+    sources: Object3D[] = [];
+
+    /**
+     * Sets the world position that the constraint should look at.
+     * Updates the first source object's position.
+     * @param worldPosition The world-space position to look at
+     */
+    setConstraintPosition(worldPosition: Vector3) {
+        const source = this.sources[0];
+        if (source) source.worldPosition = worldPosition;
+    }
 }

package/src/engine-components/Networking.ts

@@ -1,4 +1,5 @@
 import type { INetworkingWebsocketUrlProvider } from "../engine/engine_networking.js";
+import type { NetworkConnection } from "../engine/engine_networking.js";
 import { isLocalNetwork } from "../engine/engine_networking_utils.js";
 import { serializable } from "../engine/engine_serialization.js";
 import { getParam } from "../engine/engine_utils.js";
@@ -7,7 +8,7 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugnet");
 
 /**
- * Provides websocket URL configuration for the built-in networking system.
+ * Provides websocket URL configuration for the {@link NetworkConnection | built-in networking system}.
  * Add this component to override the default networking backend URL used by {@link NetworkConnection} (`this.context.connection`).
  *
  * The component registers itself as a URL provider on `awake()`. When the networking system connects,
@@ -34,6 +35,7 @@ const debug = getParam("debugnet");
  * @see {@link SyncedRoom} for automatic room joining
  * @see {@link OwnershipModel} for networked object ownership
  * @see {@link RoomEvents} for room lifecycle events
+ * @see {@link isLocalNetwork} for local network detection
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
  * @summary Networking configuration
  * @category Networking

package/src/engine-components/SceneSwitcher.ts

@@ -14,7 +14,9 @@ const debug = getParam("debugsceneswitcher");
 const experimental_clearSceneOnLoad = getParam("sceneswitcher:clearscene");
 
 const ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME = "scene";
-registerObservableAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
+export function initSceneSwitcherAttributes() {
+    registerObservableAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
+}
 
 // ContextRegistry.registerCallback(ContextEvent.ContextRegistered, async _ => {
 //     // We need to defer import to not get issues with circular dependencies

package/src/engine-components/Skybox.ts

@@ -13,8 +13,10 @@ import { Behaviour, GameObject } from "./Component.js";
 
 const debug = getParam("debugskybox");
 
-registerObservableAttribute("background-image");
-registerObservableAttribute("environment-image");
+export function initSkyboxAttributes() {
+    registerObservableAttribute("background-image");
+    registerObservableAttribute("environment-image");
+}
 
 
 type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";

package/src/engine-components/SyncedRoom.ts

@@ -1,5 +1,6 @@
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../engine/debug/index.js";
 import { Mathf } from "../engine/engine_math.js";
+import type { NetworkConnection } from "../engine/engine_networking.js";
 import { RoomEvents } from "../engine/engine_networking.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import * as utils from "../engine/engine_utils.js"
@@ -38,6 +39,7 @@ const debug = utils.getParam("debugsyncedroom");
  * @summary Joins a networked room based on URL parameters or a random room
  * @category Networking
  * @group Components
+ * @see {@link NetworkConnection} for the main networking API (`this.context.connection`)
  * @see {@link SyncedTransform} for synchronizing object transforms
  * @see {@link Voip} for voice communication in rooms
  * @see {@link ScreenCapture} for screen/video sharing

package/src/engine-components/api.ts

@@ -40,24 +40,19 @@ export { Behaviour, Component, GameObject } from "./Component.js";
 
 // We dont want to export everything in the extensions
 export { ClearFlags } from "./Camera.js"
+export { DragMode } from "./DragControls.js";
+export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";
 export * from "./export/index.js"
+export * from "./particlesystem/api.js"
 export * from "./postprocessing/index.js"
 export { type ISceneEventListener } from "./SceneSwitcher.js";
+export * from "./splines/index.js";
 export * from "./timeline/index.js"
 export * from "./ui/index.js"
+export * from "./web/index.js";
 export * from "./webxr/index.js"
 export * from "./webxr/XRFlag.js"
 
-import "./CameraUtils.js"
-import "./AnimationUtils.js"
-import "./AnimationUtilsAutoplay.js"
-
-export { DragMode } from "./DragControls.js";
-export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";
-export * from "./particlesystem/api.js"
-export * from "./splines/index.js";
-export * from "./web/index.js";
-
 // for correct type resolution in JSDoc
 import type { PhysicsMaterial } from "../engine/engine_physics.types.js";
 import type { Animation } from "./Animation.js";

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -2,10 +2,12 @@ import { NEEDLE_progressive } from "@needle-tools/gltf-progressive";
 import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
+import { findObjectOfType } from "../../../engine/engine_components.js";
 import { hasProLicense } 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";
+import { setQuicklookHandlerFactory } from "../../../engine/webcomponents/quicklook-handler.js";
 import { WebXRButtonFactory } from "../../../engine/webcomponents/WebXRButtons.js";
 import { InternalUSDZRegistry } from "../../../engine/xr/usdz.js"
 import { InstancingHandler } from "../../../engine-components/RendererInstancing.js";
@@ -793,3 +795,10 @@ export class USDZExporter extends Behaviour {
         return button;
     }
 }
+
+// Register USDZExporter as the quicklook handler so that WebXRButtons
+// can create/find exporters without a direct import (avoids circular dependency).
+setQuicklookHandlerFactory({
+    find: () => findObjectOfType(USDZExporter),
+    create: () => new USDZExporter(),
+});

package/src/engine-components/postprocessing/PostProcessingHandler.ts

@@ -1,5 +1,5 @@
 import type { Effect, EffectComposer, Pass, ToneMappingEffect as _TonemappingEffect } from "postprocessing";
-import { Camera as Camera3, DepthTexture, HalfFloatType, LinearFilter, NoToneMapping, Scene, Texture, ToneMapping, WebGLRenderTarget } from "three";
+import { Camera as Camera3, DepthTexture, HalfFloatType, LinearFilter, NoToneMapping, Scene, Source, Texture, ToneMapping, WebGLRenderTarget } from "three";
 
 import { isDevEnvironment, showBalloonWarning } from "../../engine/debug/index.js";
 // import { internal_SetSharpeningEffectModule } from "./Effects/Sharpening.js";
@@ -435,14 +435,15 @@ export class PostProcessingHandler {
                     this._customInputBuffer.depthTexture.format = inputBuffer.depthTexture.format;
                     this._customInputBuffer.depthTexture.type = inputBuffer.depthTexture.type;
                 }
-                // https://github.com/pmndrs/postprocessing/blob/ad338df710ef41fee4e5d10ad2c2c299030d46ef/src/core/EffectComposer.js#L366
-                if (this._customInputBuffer.samples > 0)
-                    (this._customInputBuffer as any).ignoreDepthForMultisampleCopy = false;
-
                 if (debug) console.warn(`[PostProcessing] Input buffer created with size ${this._customInputBuffer.width}x${this._customInputBuffer.height} and samples ${this._customInputBuffer.samples}`);
             }
-            // Calling the original render function with the input buffer
+            // Calling the original render function with the custom multisampled buffer
             screenPassRender.call(screenpass, renderer, this._customInputBuffer, outputBuffer, deltaTime, stencilTest);
+            // Switch to inputBuffer before the blit so that Graphics.blit's save/restore
+            // doesn't restore _customInputBuffer (multisampled) as the active render target.
+            // This triggers the MSAA resolve of _customInputBuffer exactly once and avoids
+            // subsequent unnecessary resolves that can cause glBlitFramebuffer depth errors.
+            renderer.setRenderTarget(inputBuffer);
             // Blit the resulting buffer to the input buffer passed in by the composer so it's used for subsequent effects
             Graphics.blit(this._customInputBuffer.texture, inputBuffer, {
                 renderer,
@@ -568,7 +569,18 @@ export class PostProcessingHandler {
 
         }
 
-        
+        // Fix: the postprocessing EffectComposer uses DepthTexture.clone() to create a stable depth target,
+        // but Three.js's Texture.copy() shares the Source object between original and clone.
+        // Since Three.js deduplicates GL textures by Source + cache key, both depth textures end up
+        // as the same GL texture, causing "glBlitFramebuffer: Read and write depth stencil attachments
+        // cannot be the same image" when blitDepthBuffer copies between them.
+        // Assigning a new Source breaks the deduplication so they get separate GL textures.
+        const composerDepthTexture = (composer as any).depthTexture as DepthTexture | null;
+        if (composerDepthTexture) {
+            composerDepthTexture.source = new Source({ width: 0, height: 0 });
+            composerDepthTexture.needsUpdate = true;
+        }
+
         this.handleDevicePixelRatio();
 
         

package/src/engine-components/postprocessing/utils.ts

@@ -114,8 +114,13 @@ export function orderEffects(effects: Array<PostprocessingEffectData>) {
         builtinOrder.set(MODULES.POSTPROCESSING.MODULE.DepthDownsamplingPass, PostProcessingEffectOrder.DepthDownsamplingPass);
         builtinOrder.set(MODULES.POSTPROCESSING.MODULE.SMAAEffect, PostProcessingEffectOrder.SMAA);
         builtinOrder.set(MODULES.POSTPROCESSING.MODULE.SSAOEffect, PostProcessingEffectOrder.SSAO);
-        builtinOrder.set(MODULES.POSTPROCESSING_AO.MODULE.N8AOPostPass, PostProcessingEffectOrder.SSAO);
-        builtinOrder.set(MODULES.POSTPROCESSING_AO.MODULE.N8AOPass, PostProcessingEffectOrder.SSAO);
+        // Use MAYBEMODULE to avoid creating a static dependency on n8ao — otherwise the
+        // bundler eagerly loads the 481 KB chunk even when AO is not used.
+        const n8ao = MODULES.POSTPROCESSING_AO.MAYBEMODULE;
+        if (n8ao) {
+            builtinOrder.set(n8ao.N8AOPostPass, PostProcessingEffectOrder.SSAO);
+            builtinOrder.set(n8ao.N8AOPass, PostProcessingEffectOrder.SSAO);
+        }
         builtinOrder.set(MODULES.POSTPROCESSING.MODULE.TiltShiftEffect, PostProcessingEffectOrder.TiltShift);
         builtinOrder.set(MODULES.POSTPROCESSING.MODULE.DepthOfFieldEffect, PostProcessingEffectOrder.DepthOfField);
         builtinOrder.set(MODULES.POSTPROCESSING.MODULE.ChromaticAberrationEffect, PostProcessingEffectOrder.ChromaticAberration);

package/src/engine-components/timeline/TimelineTracks.ts

@@ -2,12 +2,13 @@ import { AnimationAction, AnimationClip, AnimationMixer, Audio, AudioListener, A
 
 import { isDevEnvironment } from "../../engine/debug/index.js";
 import { Context } from "../../engine/engine_setup.js";
+import type { Constructor } from "../../engine/engine_types.js";
 import { getParam, resolveUrl } from "../../engine/engine_utils.js";
 import { setObjectAnimated } from "../AnimationUtils.js";
 import { Animator } from "../Animator.js"
 import { AudioSource } from "../AudioSource.js";
 import { GameObject } from "../Component.js";
-import { PlayableDirector } from "./PlayableDirector.js";
+import type { PlayableDirector } from "./PlayableDirector.js";
 import { SignalReceiver } from "./SignalAsset.js";
 import * as Models from "./TimelineModels.js";
 
@@ -940,7 +941,10 @@ export class ControlTrackHandler extends TrackHandler {
                 continue;
             }
             else {
-                const timeline = GameObject.getComponent(asset.sourceObject, PlayableDirector)!;
+                // Use the director's constructor to get the PlayableDirector class reference
+                // without a runtime import, avoiding a circular dependency.
+                const DirectorType = this.director.constructor as Constructor<PlayableDirector>;
+                const timeline = GameObject.getComponent(asset.sourceObject, DirectorType)!;
                 // always add it to keep size of timelines and models in sync (index of model is index of timeline)
                 this.timelines.push(timeline);
                 if (timeline) {

package/src/engine-components/web/ScrollFollow.ts

@@ -514,7 +514,5 @@ declare global {
         currentTime: { unit: 'seconds' | 'percent', value: number };
         duration: { unit: 'seconds' | 'percent', value: number };
         source: Element | null;
-        startOffset: { unit: 'px', value: number };
-        endOffset: { unit: 'px', value: number };
     }
 }

package/src/engine-components/webxr/WebXR.ts

@@ -23,7 +23,7 @@ const debug = getParam("debugwebxr");
 const debugQuicklook = getParam("debugusdz");
 
 /**
- * Use the WebXR component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.  
+ * Use the [WebXR](https://engine.needle.tools/docs/api/WebXR) component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.  
  * 
  * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.  
  * 
@@ -52,12 +52,25 @@ const debugQuicklook = getParam("debugusdz");
  * });
  * ```
  * 
+ * 
+ * @example Start AR session with placement reticle and touch to place and adjust the scene
+ * ```ts
+ * import { onStart, WebXR } from "@needle-tools/engine";
+ * onStart(context => {
+ *  const webxr = context.scene.addComponent(WebXR);
+ *  webxr.autoPlace = false; // disable auto placement, we want the user to tap to place the scene
+ *  webxr.usePlacementReticle = true; // show the placement reticle to help the user find surfaces to place the scene
+ *  webxr.usePlacementAdjustment = true; // allow the user to adjust the position, rotation and scale of the scene with touch after placing
+ *  webxr.arScale = 2; // set the initial scale of the scene in AR. Larger values make the scene appear smaller in AR.
+ *  webxr.enterAR(); // start AR session
+ * });
+ * 
  * @summary WebXR Component for VR and AR support
  * @category XR
  * @group Components
  * @see {@link NeedleXRSession} for low-level XR API
  * @see {@link XRControllerMovement} for VR locomotion
- * @see {@link WebARSessionRoot} for AR session configuration
+ * @see {@link WebARSessionRoot} for AR session configuration and an AR content placement event
  * @see {@link Avatar} for networked user avatars
  * @see {@link screenshot2} for taking screenshots in XR (including AR camera feed compositing)
  * @link https://engine.needle.tools/docs/xr.html

package/src/needle-engine.ts

@@ -1,6 +1,7 @@
+import { initEngine } from "./engine/engine_init.js";
+initEngine();
 import "./engine/webcomponents/needle-engine.js";
 import "./engine/engine_setup.js";
-import "./engine/engine_audio.js";
 export * from "./engine/api.js";
 export * from "./engine-components/api.js";
 export * from "./engine-components-experimental/api.js";