@needle-tools/engine 4.13.0 → 4.13.1

package/src/engine-components/SmoothFollow.ts

@@ -4,14 +4,58 @@ import { Mathf } from "../engine/engine_math.js";
 import { Axes } from "../engine/engine_physics.types.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getWorldPosition, getWorldQuaternion } from "../engine/engine_three_utils.js";
+import type { LookAt } from "./api.js";
 import { Behaviour } from "./Component.js";
 
 /**
- * SmoothFollow makes the {@link Object3D} (`GameObject`) smoothly follow another target {@link Object3D}.  
- * It can follow the target's position, rotation, or both.   
- * @summary Smoothly follows a target object
+ * [SmoothFollow](https://engine.needle.tools/docs/api/SmoothFollow) makes this GameObject smoothly follow another target object's position and/or rotation.  
+ *
+ * **Position Following:**  
+ * When enabled (`followFactor > 0`), this object will move towards the target's world position.  
+ * The object interpolates from its current position to the target's position each frame.  
+ * Use `positionAxes` to restrict following to specific axes (e.g., only horizontal movement).  
+ *
+ * **Rotation Following:**  
+ * When enabled (`rotateFactor > 0`), this object will rotate to match the target's world rotation.  
+ * The object smoothly interpolates from its current rotation to the target's rotation each frame.  
+ * This makes the object face the same direction as the target, not look at it (use {@link LookAt} for that).  
+ *
+ * **Smoothing:**  
+ * Both position and rotation use time-based interpolation (lerp/slerp).  
+ * Higher factor values = faster following (less lag), lower values = slower following (more lag).  
+ * Set a factor to 0 to disable that type of following entirely.  
+ *
+ * **Common Use Cases:**  
+ * - Camera following a player character  
+ * - UI elements tracking world objects  
+ * - Delayed motion effects (ghost trails, spring arms)  
+ * - Smoothed object attachment  
+ *
+ * @example Follow a target with smooth position
+ * ```ts
+ * const follower = myObject.addComponent(SmoothFollow);
+ * follower.target = playerObject;
+ * follower.followFactor = 5;  // Higher = faster following
+ * follower.rotateFactor = 0;  // Don't follow rotation
+ * ```
+ *
+ * @example Follow only on horizontal plane
+ * ```ts
+ * follower.positionAxes = Axes.X | Axes.Z; // Follow X and Z only (no vertical)
+ * ```
+ *
+ * @example Follow both position and rotation
+ * ```ts
+ * follower.target = targetObject;
+ * follower.followFactor = 3;  // Smooth position following
+ * follower.rotateFactor = 2;  // Smooth rotation following
+ * ```
+ *
+ * @summary Smoothly follows a target object's position and/or rotation
  * @category Interactivity
  * @group Components
+ * @see {@link LookAtConstraint} for making an object look at a target (different from rotation following)
+ * @see {@link Mathf} for the interpolation used
  */
 export class SmoothFollow extends Behaviour {
 
@@ -22,21 +66,34 @@ export class SmoothFollow extends Behaviour {
     target: Object3D | null = null;
 
     /**
-     * The factor to smoothly follow the target's position.  
-     * The value is clamped between 0 and 1. If 0, the GameObject will not follow the target's position.  
+     * Speed factor for position following.
+     * Controls how quickly this object moves to match the target's position.
+     * Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
+     * Set to 0 to disable position following entirely.
+     * @default 0.1
      */
     @serializable()
     followFactor = .1;
+
     /**
-     * The factor to smoothly follow the target's rotation.   
-     * The value is clamped between 0 and 1. If 0, the GameObject will not follow the target's rotation.
+     * Speed factor for rotation following.
+     * Controls how quickly this object rotates to match the target's rotation.
+     * Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
+     * Set to 0 to disable rotation following entirely.
+     * @default 0.1
      */
     @serializable()
     rotateFactor = .1;
 
+    /**
+     * Which position axes to follow. Use bitwise OR to combine:
+     * `Axes.X | Axes.Y` follows only X and Y axes.
+     * @default Axes.All
+     */
     @serializable()
     positionAxes: Axes = Axes.All;
 
+    /** When true, rotates 180° around Y axis (useful for mirrored setups) */
     flipForward: boolean = false;
 
     private static _invertForward: Quaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
@@ -49,6 +106,10 @@ export class SmoothFollow extends Behaviour {
         this.updateNow(false);
     }
 
+    /**
+     * Manually update the position/rotation to follow the target.
+     * @param hard If true, snaps instantly to target without smoothing
+     */
     updateNow(hard: boolean) {
         if (!this.target || this.target === this.gameObject) return;
         if (this.followFactor > 0) {

package/src/engine-components/SpatialTrigger.ts

@@ -24,11 +24,34 @@ function testMask(mask1, mask2) {
 }
 
 /**
- * Component that receives and responds to spatial events, like entering or exiting a trigger zone.
- * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.
+ * Component that receives and responds to spatial events, like entering or exiting a trigger zone.  
+ * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.  
+ *
+ * Place this on objects that should react when entering trigger zones. The receiver checks  
+ * against all active SpatialTriggers each frame and fires events when intersections change.  
+ *
+ * Events can be connected via {@link EventList} in the editor or listened to in code.  
+ *
+ * @example Listen to trigger events
+ * ```ts
+ * export class DoorTrigger extends Behaviour {
+ *   @serializable(SpatialTriggerReceiver)
+ *   receiver?: SpatialTriggerReceiver;
+ *
+ *   start() {
+ *     this.receiver?.onEnter?.addEventListener(() => {
+ *       console.log("Player entered door zone");
+ *     });
+ *   }
+ * }
+ * ```
+ *
  * @summary Receives spatial trigger events
  * @category Interactivity
  * @group Components
+ * @see {@link SpatialTrigger} for defining trigger zones
+ * @see {@link EventList} for event handling
+ * @link https://engine.needle.tools/samples/spatial-triggers/
  */
 export class SpatialTriggerReceiver extends Behaviour {
 
@@ -126,10 +149,34 @@ export class SpatialTriggerReceiver extends Behaviour {
 }
 
 /**
- * A spatial trigger component that detects objects within a box-shaped area.
- * Used to trigger events when objects enter, stay in, or exit the defined area
+ * A spatial trigger component that detects objects within a box-shaped area.  
+ * Used to trigger events when objects enter, stay in, or exit the defined area.  
+ *
+ * The trigger area is defined by the GameObject's bounding box (uses {@link BoxHelperComponent}).  
+ * Objects with {@link SpatialTriggerReceiver} components are tested against this area.  
+ *
+ * **Mask system:** Both trigger and receiver have a `triggerMask` - they only interact  
+ * when their masks have overlapping bits set. This allows selective triggering.  
+ *
+ * **Debug:** Use `?debugspatialtrigger` URL parameter to visualize trigger zones.  
+ *
+ * @example Create a pickup zone
+ * ```ts
+ * // On the pickup zone object
+ * const trigger = pickupZone.addComponent(SpatialTrigger);
+ * trigger.triggerMask = 1; // Layer 1 for pickups
+ *
+ * // On the player
+ * const receiver = player.addComponent(SpatialTriggerReceiver);
+ * receiver.triggerMask = 1; // Match the pickup layer
+ * ```
+ *
+ * @summary Define a trigger zone that detects entering objects
  * @category Interactivity
  * @group Components
+ * @see {@link SpatialTriggerReceiver} for objects that respond to triggers
+ * @see {@link BoxHelperComponent} for the underlying box used to define the trigger area
+ * @link https://engine.needle.tools/samples/spatial-triggers/
  */
 export class SpatialTrigger extends Behaviour {
 

package/src/engine-components/SpectatorCamera.ts

@@ -31,14 +31,32 @@ export enum SpectatorMode {
 const debug = getParam("debugspectator");
 
 /**
- * Provides functionality to follow and spectate other users in a networked environment.
- * Handles camera switching, following behavior, and network synchronization for spectator mode.
- * 
- * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
- * 
+ * SpectatorCamera enables following and spectating other users in networked sessions.  
+ * Switch between first-person (see what they see) and third-person (orbit around them) views.  
+ *
+ * **Keyboard controls** (when `useKeys = true`):  
+ * - `F` - Request all users to follow the local player
+ * - `ESC` - Stop spectating
+ *
+ * **Spectator modes:**  
+ * - `FirstPerson` - View from the followed player's perspective
+ * - `ThirdPerson` - Freely orbit around the followed player
+ *
+ * **Debug:** Use `?debugspectator` URL parameter for logging.
+ *
+ * @example Start spectating a user
+ * ```ts
+ * const spectator = camera.getComponent(SpectatorCamera);
+ * spectator.follow(targetUserId);
+ * spectator.mode = SpectatorMode.ThirdPerson;
+ * ```
+ *
  * @summary Spectator camera for following other users
  * @category Networking
  * @group Components
+ * @see {@link SpectatorMode} for view options
+ * @see {@link SyncedRoom} for networked sessions
+ * @see {@link OrbitControls} for third-person orbit
  */
 export class SpectatorCamera extends Behaviour {
 

package/src/engine-components/SyncedRoom.ts

@@ -11,8 +11,8 @@ const viewParamName = "view";
 const debug = utils.getParam("debugsyncedroom");
 
 /**
- * SyncedRoom is a behaviour that will attempt to join a networked room based on the URL parameters or a random room.  
- * It will also create a button in the menu to join or leave the room.  
+ * [SyncedRoom](https://engine.needle.tools/docs/api/SyncedRoom) is a behaviour that will attempt to join a networked room based on the URL parameters or a random room.
+ * It will also create a button in the menu to join or leave the room.
  * You can also join a networked room by calling the core methods like `this.context.connection.joinRoom("roomName")`.
  * 
  * @example Join a networked room
@@ -33,9 +33,15 @@ const debug = utils.getParam("debugsyncedroom");
  * myObject.addComponent(SyncedRoom, { joinRandomRoom: true, roomPrefix: "myApp_" });
  * ```
  * 
+ * **Debug:** Use `?debugsyncedroom` URL parameter for logging.
+ *
  * @summary Joins a networked room based on URL parameters or a random room
  * @category Networking
  * @group Components
+ * @see {@link SyncedTransform} for synchronizing object transforms
+ * @see {@link Voip} for voice communication in rooms
+ * @see {@link ScreenCapture} for screen/video sharing
+ * @link https://engine.needle.tools/docs/networking.html
  */
 export class SyncedRoom extends Behaviour {
 

package/src/engine-components/SyncedTransform.ts

@@ -55,12 +55,48 @@ onUpdate((ctx) => {
 })
 
 /**
- * SyncedTransform synchronizes the position and rotation of a game object over the network.
- * It handles ownership transfer, interpolation, and network state updates automatically.
- * 
+ * SyncedTransform synchronizes position and rotation of a GameObject across the network.
+ * When users interact with an object (e.g., via {@link DragControls}), they automatically
+ * take ownership and their changes are broadcast to other users.
+ *
+ * **Features:**
+ * - Automatic ownership transfer when interacting
+ * - Smooth interpolation of remote updates
+ * - Physics integration (can override kinematic state)
+ * - Fast mode for rapidly moving objects
+ *
+ * **Requirements:**
+ * - Active network connection via {@link SyncedRoom}
+ * - Objects must have unique GUIDs (set automatically in Unity/Blender export)
+ *
+ * **Ownership:**
+ * This component uses {@link OwnershipModel} internally to manage object ownership.
+ * Only the client that owns an object can send transform updates. Use `requestOwnership()`
+ * before modifying the transform, or check `hasOwnership()` to see if you can modify it.
+ *
+ * **Debug:** Use `?debugsync` URL parameter for logging.
+ *
+ * @example Basic networked object
+ * ```ts
+ * // Add to any object you want synced
+ * const sync = myObject.addComponent(SyncedTransform);
+ * sync.fastMode = true; // For fast-moving objects
+ *
+ * // Request ownership before modifying
+ * sync.requestOwnership();
+ * myObject.position.x += 1;
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/collaborative-sandbox
+ *
  * @summary Synchronizes object transform over the network with ownership management
  * @category Networking
  * @group Components
+ * @see {@link SyncedRoom} for room/session management
+ * @see {@link OwnershipModel} for ownership management details
+ * @see {@link DragControls} for interactive dragging with sync
+ * @see {@link Duplicatable} for networked object spawning
+ * @link https://engine.needle.tools/docs/networking.html
  */
 export class SyncedTransform extends Behaviour {
 
@@ -94,9 +130,18 @@ export class SyncedTransform extends Behaviour {
     private _receivedFastUpdate: boolean = false;
     private _shouldRequestOwnership: boolean = false;
 
-    /** 
+    /**
      * Requests ownership of this object on the network.
      * You need to be connected to a room for this to work.
+     * Call this before modifying the object's transform to ensure your changes are synchronized.
+     *
+     * @example
+     * ```ts
+     * // Request ownership before modifying
+     * syncedTransform.requestOwnership();
+     * this.gameObject.position.y += 1;
+     * ```
+     * @see {@link OwnershipModel.requestOwnership} for more details
      */
     public requestOwnership() {
         if (debug)
@@ -110,25 +155,29 @@ export class SyncedTransform extends Behaviour {
     }
 
     /**
-     * Free ownership of this object on the network.  
-     * You need to be connected to a room for this to work.  
+     * Free ownership of this object on the network.
+     * You need to be connected to a room for this to work.
      * This will also be called automatically when the component is disabled.
+     * Call this when you're done modifying an object to allow other users to interact with it.
+     * @see {@link OwnershipModel.freeOwnership} for more details
      */
     public freeOwnership() {
         this._model?.freeOwnership();
     }
 
     /**
-     * Checks if this client has ownership of the object
-     * @returns true if this client has ownership, false if not, undefined if ownership state is unknown
+     * Checks if this client has ownership of the object.
+     * @returns `true` if this client has ownership, `false` if not, `undefined` if ownership state is unknown
+     * @see {@link OwnershipModel.hasOwnership} for more details
      */
     public hasOwnership(): boolean | undefined {
         return this._model?.hasOwnership ?? undefined;
     }
 
     /**
-     * Checks if the object is owned by any client
-     * @returns true if the object is owned, false if not, undefined if ownership state is unknown
+     * Checks if the object is owned by any client (local or remote).
+     * @returns `true` if the object is owned, `false` if not, `undefined` if ownership state is unknown
+     * @see {@link OwnershipModel.isOwned} for more details
      */
     public isOwned(): boolean | undefined {
         return this._model?.isOwned;

package/src/engine-components/TransformGizmo.ts

@@ -8,12 +8,39 @@ import { OrbitControls } from "./OrbitControls.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 
 /**
- * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene.
- * It wraps three.js {@link TransformControls} and provides keyboard shortcuts for changing modes and settings.
- * 
- * @summary Object manipulation gizmo for translating, rotating, and scaling
+ * The [TransformGizmo](https://engine.needle.tools/docs/api/TransformGizmo) displays manipulation controls for translating, rotating, and scaling objects.
+ * Wraps three.js {@link TransformControls} with keyboard shortcuts and snapping support.  
+ *
+ * **Keyboard shortcuts:**
+ * - `W` - Translate mode
+ * - `E` - Rotate mode
+ * - `R` - Scale mode
+ * - `Q` - Toggle local/world space
+ * - `Shift` (hold) - Enable grid snapping
+ * - `+/-` - Adjust gizmo size
+ * - `X/Y/Z` - Toggle axis visibility
+ * - `Space` - Toggle controls enabled
+ *
+ * **Snapping:**
+ * Configure grid snapping with `translationSnap`, `rotationSnapAngle`, and `scaleSnap`.
+ *
+ * **Networking:**
+ * Automatically works with {@link SyncedTransform} for multiplayer editing.
+ *
+ * @example Add transform gizmo to an object
+ * ```ts
+ * const gizmo = editableObject.addComponent(TransformGizmo);
+ * gizmo.translationSnap = 0.5; // Snap to 0.5 unit grid
+ * gizmo.rotationSnapAngle = 45; // Snap to 45° increments
+ * ```
+ *
+ * @summary Object manipulation gizmo for translate/rotate/scale
  * @category Helpers
  * @group Components
+ * @see {@link DragControls} for simpler drag-only interaction
+ * @see {@link SyncedTransform} for network synchronization
+ * @see {@link OrbitControls} - automatically disabled during gizmo drag
+ * @link https://threejs.org/docs/index.html#examples/en/controls/TransformControls for underlying three.js controls and additional features
  */
 export class TransformGizmo extends Behaviour {
 

package/src/engine-components/VideoPlayer.ts

@@ -7,6 +7,7 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Context } from "../engine/engine_setup.js";
 import { getWorldScale } from "../engine/engine_three_utils.js";
 import { getParam } from "../engine/engine_utils.js";
+import { PointerEventData } from "./api.js";
 import { Behaviour, GameObject } from "./Component.js";
 import { Renderer } from "./Renderer.js";
 
@@ -45,18 +46,45 @@ export enum VideoRenderMode {
 }
 
 /**
- * The VideoPlayer component can be used to playback video clips from urls, streams or m3u8 playlists (livestreams)
- * @example Add a video player component to a game object and set the url to a video file. The video will start playing once the object becomes active in your scene
- * ```typescript
- * // Add a video player component to a game object and set the url to a video file. The video will start playing once the object becomes active in your scene
+ * [VideoPlayer](https://engine.needle.tools/docs/api/VideoPlayer) plays video clips from URLs, media streams, or HLS playlists (m3u8 livestreams).  
+ *
+ * **Supported formats:**  
+ * - Standard video files (MP4, WebM, etc.)
+ * - Media streams (from webcam, screen capture, etc.)
+ * - HLS playlists (m3u8) for livestreaming  
+ * 
+ * [![](https://cloud.needle.tools/-/media/w1uHur5yu3Ni7qFaKIFX-g.gif)](https://engine.needle.tools/samples/video-playback/)
+ *
+ * **Rendering modes:**  
+ * Video can be rendered to a material texture, render texture, or camera planes.  
+ * Set `targetMaterialRenderer` to apply video to a specific mesh's material.  
+ *
+ * **Browser autoplay:**  
+ * Videos may require user interaction to play with audio.  
+ * Set `playOnAwake = true` for automatic playback (muted if needed).  
+ *
+ * @example Basic video playback
+ * ```ts
  * const videoPlayer = addComponent(obj, VideoPlayer, {
- *    url: "https://www.w3schools.com/html/mov_bbb.mp4",
- *    playOnAwake: true,
+ *   url: "https://example.com/video.mp4",
+ *   playOnAwake: true,
+ *   loop: true,
  * });
  * ```
+ *
+ * @example Play video on a 3D surface
+ * ```ts
+ * const video = myScreen.getComponent(VideoPlayer);
+ * video.targetMaterialRenderer = myScreen.getComponent(Renderer);
+ * video.play();
+ * ```
+ *
  * @summary Plays video clips from URLs or streams
  * @category Multimedia
  * @group Components
+ * @see {@link AudioSource} for audio-only playback
+ * @see {@link ScreenCapture} for capturing and sharing video
+ * @see {@link Renderer} for video texture targets
  */
 export class VideoPlayer extends Behaviour {
 
@@ -72,6 +100,20 @@ export class VideoPlayer extends Behaviour {
     @serializable()
     aspectMode: AspectMode = AspectMode.None;
 
+    // /**
+    //  * If true the video will toggle between play and pause when clicked.   
+    //  * Note that this requires the video element to be interactable which is not the case when using certain render modes like CameraNearPlane or CameraFarPlane. In those cases you can use the `requestPictureInPicture()` method to open the video in a separate window which allows interaction with the video element.
+    //  */
+    // @serializable()
+    // clickToToggle: boolean = true;
+
+    // onPointerClick(_args: PointerEventData) {
+    //     if (this.clickToToggle) {
+    //         if (this.isPlaying) this.pause();
+    //         else this.play();
+    //     }
+    // }
+
     @serializable(URL)
     private clip?: string | MediaStream | null = null;
 

package/src/engine-components/Voip.ts

@@ -12,11 +12,42 @@ export const noVoip = "noVoip";
 const debugParam = getParam("debugvoip");
 
 /**
- * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.  
- * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).  
+ * [Voip](https://engine.needle.tools/docs/api/Voip) Voice over IP (VoIP) component for real-time audio communication between users.  
+ * Allows sending and receiving audio streams in networked rooms.  
+ *
+ * **Requirements:**  
+ * - Active network connection (via {@link SyncedRoom} or manual connection)  
+ * - User permission for microphone access (requested automatically)  
+ * - HTTPS connection (required for WebRTC)  
+ *
+ * **Features:**  
+ * - Automatic connection when joining rooms (`autoConnect`)  
+ * - Background audio support (`runInBackground`)  
+ * - Optional UI toggle button (`createMenuButton`)  
+ * - Mute/unmute control  
+ *
+ * **Debug:** Use `?debugvoip` URL parameter or set `debug = true` for logging.  
+ * Press 'v' to toggle mute, 'c' to connect/disconnect when debugging.  
+ *
+ * @example Enable VoIP in your scene
+ * ```ts
+ * const voip = myObject.addComponent(Voip);
+ * voip.autoConnect = true;
+ * voip.createMenuButton = true;
+ *
+ * // Manual control
+ * voip.connect();    // Start sending audio
+ * voip.disconnect(); // Stop sending
+ * voip.setMuted(true); // Mute microphone
+ * ```
+ *
  * @summary Voice over IP for networked audio communication
  * @category Networking
  * @group Components
+ * @see {@link SyncedRoom} for room management
+ * @see {@link NetworkedStreams} for the underlying streaming
+ * @see {@link ScreenCapture} for video streaming
+ * @link https://engine.needle.tools/docs/networking.html
  */
 export class Voip extends Behaviour {
 

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

@@ -71,22 +71,56 @@ type BeforeLODExportArguments = {
 }
 
 /**
- * Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.  
- * The USDZ file is generated using the Needle Engine ThreeUSDZExporter.  
- * The exporter supports various extensions to add custom behaviors and interactions to the USDZ file.  
- * The exporter can automatically collect Animations and AudioSources and export them as playing at the start.  
- * The exporter can also add a custom QuickLook overlay with a call to action button and custom branding.  
- * @example
- * ```typescript
- * const usdz = new USDZExporter();
- * usdz.objectToExport = myObject;
- * usdz.autoExportAnimations = true;
- * usdz.autoExportAudioSources = true;
- * usdz.exportAsync();
+ * USDZExporter creates USDZ files and opens them in Apple QuickLook on iOS/iPadOS/visionOS.  
+ * Enables "View in AR" functionality for Apple devices directly from web experiences.  
+ *
+ * **Key features:**  
+ * - Auto-exports animations and audio sources  
+ * - Interactive behaviors via Needle's "Everywhere Actions" system  
+ * - RealityKit physics support (iOS 18+, visionOS 1+)
+ * - Custom QuickLook overlay with call-to-action buttons
+ * - Progressive texture/mesh LOD handling
+ * 
+ * [![](https://cloud.needle.tools/-/media/YyUz1lUVlOhEY4fWZ-oMsA.gif)](https://engine.needle.tools/samples/?overlay=samples&tag=usdz)
+ *
+ * **Automatic setup:**  
+ * - Creates QuickLook button on compatible devices
+ * - Respects {@link XRFlag} for AR-specific visibility
+ * - Handles {@link WebARSessionRoot} scale
+ *
+ * **Custom extensions:**  
+ * Add custom behaviors by implementing {@link IUSDExporterExtension} and adding to {@link extensions} array.  
+ * 
+ * **Debug:** Use `?debugusdz` URL parameter. Press 'T' to trigger export.  
+ *
+ * @example Basic USDZ export  
+ * ```ts
+ * const exporter = myObject.addComponent(USDZExporter);
+ * exporter.objectToExport = productModel;
+ * exporter.autoExportAnimations = true;
+ * exporter.interactive = true; // Enable QuickLook behaviors
+ *
+ * // Trigger export
+ * await exporter.exportAndOpen();
  * ```
- * @summary Export 3D objects as USDZ files for QuickLook
+ *
+ * @example Custom branding  
+ * ```ts
+ * exporter.customBranding = {
+ *   callToAction: "Buy Now",
+ *   checkoutTitle: "Product Name",
+ *   callToActionURL: "https://shop.example.com"
+ * };
+ * ```
+ *
+ * @summary Export 3D objects as USDZ files for Apple QuickLook AR
  * @category XR
  * @group Components
+ * @see {@link WebXR} for WebXR-based AR/VR
+ * @see {@link WebARSessionRoot} for AR placement and scaling
+ * @see {@link XRFlag} for AR-specific object visibility
+ * @see {@link CustomBranding} for QuickLook overlay customization  
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=usdz
  */
 export class USDZExporter extends Behaviour {