@needle-tools/engine 4.13.0 → 4.13.1

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

@@ -17,20 +17,15 @@ import * as Tracks from "./TimelineTracks.js";
 const debug = getParam("debugtimeline");
 
 /**
- * The wrap mode of the {@link PlayableDirector}.
+ * Controls how the {@link PlayableDirector} behaves when playback reaches the end.
+ * @see {@link PlayableDirector.extrapolationMode}
  */
 export enum DirectorWrapMode {
-    /// <summary>
-    ///   <para>Hold the last frame when the playable time reaches it's duration.</para>
-    /// </summary>
+    /** Hold the last frame when playback reaches the end of the timeline. */
     Hold = 0,
-    /// <summary>
-    ///   <para>Loop back to zero time and continue playing.</para>
-    /// </summary>
+    /** Loop back to the start and continue playing indefinitely. */
     Loop = 1,
-    /// <summary>
-    ///   <para>Do not keep playing when the time reaches the duration.</para>
-    /// </summary>
+    /** Stop playback when the end is reached. The timeline will not loop. */
     None = 2,
 }
 
@@ -53,26 +48,80 @@ export enum ClipExtrapolation {
 export type CreateTrackFunction = (director: PlayableDirector, track: Models.TrackModel) => Tracks.TrackHandler | undefined | null;
 
 /**
- * The PlayableDirector component is the main component to control timelines in needle engine.
- * It is used to play, pause, stop and evaluate timelines.  
- * Assign a TimelineAsset to the `playableAsset` property to start playing a timeline.
+ * PlayableDirector is the main component for controlling timelines in Needle Engine.  
+ * It orchestrates playback of TimelineAssets containing animation, audio, signal,  
+ * control, and activation tracks.    
+ * 
+ * ![](https://cloud.needle.tools/-/media/CkJal5dIBwFe6erA-MmiGw.webp)  
+ * *Screenshot: Timeline in Unity*
+ *
+ * **Supported track types:**  
+ * - Animation tracks - animate objects using AnimationClips
+ * - Audio tracks - play synchronized audio
+ * - Activation tracks - show/hide objects at specific times
+ * - Signal tracks - trigger events at specific points
+ * - Control tracks - control nested timelines or prefab instances
+ * - Marker tracks - add metadata and navigation points  
+ * 
+ * [![](https://cloud.needle.tools/-/media/HFudFwl8J8D-Kt_VPu7pRw.gif)](https://engine.needle.tools/samples/bike-scrollytelling-responsive-3d)
+ * 
+ * [![](https://cloud.needle.tools/-/media/xJ1rI3STbZRnOoWJrSzqlQ.gif)](https://app.songsofcultures.com/?scene=little-brother)
+ *
+ * **Playback control:**    
+ * Use `play()`, `pause()`, `stop()` for basic control.  
+ * Set `time` directly and call `evaluate()` for scrubbing.  
+ * Adjust `speed` for playback rate and `weight` for blending.  
+ *
+ * @example Basic timeline playback
+ * ```ts
+ * const director = myObject.getComponent(PlayableDirector);
+ * director.play();
+ * // Jump to specific time
+ * director.time = 2.5;
+ * director.evaluate();
+ * ```
+ *
+ * @example Control playback speed
+ * ```ts
+ * director.speed = 0.5; // Half speed
+ * director.speed = -1;  // Reverse playback
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples-uploads/product-flyover/
+ *
  * @summary Controls and plays TimelineAssets
  * @category Animation and Sequencing
  * @group Components
+ * @see {@link Animator} for playing individual AnimationClips
+ * @see {@link AudioSource} for standalone audio playback
+ * @see {@link SignalReceiver} for handling timeline signals
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
+ * @link https://app.songsofcultures.com/  
+ * @link https://engine.needle.tools/docs/blender/animation.html Blender timeline and animation export
  */
 export class PlayableDirector extends Behaviour {
 
     private static createTrackFunctions: { [key: string]: CreateTrackFunction } = {};
+
+    /**
+     * Register a function to create a track handler for a custom track type.
+     * This allows you to extend the timeline system with your own track types and handlers.
+     */
     static registerCreateTrack(type: string, fn: CreateTrackFunction) {
         this.createTrackFunctions[type] = fn;
     }
 
     /**
-     * The timeline asset that is played by this director.
+     * The timeline asset containing tracks, clips, and markers that this director will play.
+     * Assign a timeline asset exported from Unity or Blender to enable playback.
      */
     playableAsset?: Models.TimelineAssetModel;
 
-    /** Set to true to start playing the timeline when the scene starts */
+    /**
+     * When true, the timeline starts playing automatically when the component awakens.
+     * Set to false to control playback manually via `play()`.
+     * @default false
+     */
     @serializable()
     playOnAwake?: boolean;
 
@@ -83,11 +132,18 @@ export class PlayableDirector extends Behaviour {
     @serializable()
     extrapolationMode: DirectorWrapMode = DirectorWrapMode.Loop;
 
-    /** @returns true if the timeline is currently playing */
+    /** Returns true if the timeline is currently playing (not paused or stopped). */
     get isPlaying(): boolean { return this._isPlaying; }
-    /** @returns true if the timeline is currently paused */
+    /** Returns true if the timeline is currently paused. */
     get isPaused(): boolean { return this._isPaused; }
-    /** the current time of the timeline */
+    /**
+     * The current playback time in seconds. Set this and call `evaluate()` to scrub.
+     * @example Scrub to a specific time
+     * ```ts
+     * director.time = 5.0;
+     * director.evaluate();
+     * ```
+     */
     get time(): number { return this._time; }
     set time(value: number) {
         if (typeof value === "number" && !Number.isNaN(value))
@@ -96,17 +152,32 @@ export class PlayableDirector extends Behaviour {
             console.error("INVALID TIMELINE.TIME VALUE", value, this.name)
         };
     }
-    /** the duration of the timeline */
+    /** The total duration of the timeline in seconds (read from the longest track/clip). */
     get duration(): number { return this._duration; }
     set duration(value: number) { this._duration = value; }
-    /** the weight of the timeline. Set to a value below 1 to blend with other timelines */
+    /**
+     * The blend weight of the timeline (0-1). Use values below 1 to blend
+     * timeline animations with other animations like those from an Animator.
+     */
     get weight(): number { return this._weight; };
     set weight(value: number) { this._weight = value; }
-    /** the playback speed of the timeline */
+    /**
+     * The playback speed multiplier. Set to negative values for reverse playback.
+     * @example Reverse playback at double speed
+     * ```ts
+     * director.speed = -2;
+     * ```
+     */
     get speed(): number { return this._speed; }
     set speed(value: number) { this._speed = value; }
 
-    /** When enabled the timeline will wait for audio tracks to load at the current time before starting to play */
+    /**
+     * When true, `play()` will wait for audio tracks to load and for user interaction  
+     * before starting playback. Web browsers require user interaction (click/tap) before  
+     * allowing audio to play - this ensures audio is synchronized with the timeline.  
+     * Set to false if you need immediate visual playback and can tolerate audio delay.  
+     * @default true
+     */
     waitForAudio: boolean = true;
 
     private _visibilityChangeEvt?: any;
@@ -223,9 +294,9 @@ export class PlayableDirector extends Behaviour {
                 await delay(200);
         }
         this.invokeStateChangedMethodsOnTracks();
-        // Update timeline in LateUpdate to give other scripts time to react to the updated state
-        // e.g. if we animate OrbitControls look at target we want those changes to be applied in onBeforeRender
-        // if we use onBeforeRender here it will be called *after* the regular onBeforeRender events
+        // Update timeline in LateUpdate to give other scripts time to react to the updated state  
+        // e.g. if we animate OrbitControls look at target we want those changes to be applied in onBeforeRender  
+        // if we use onBeforeRender here it will be called *after* the regular onBeforeRender events  
         // which is too late
         this._internalUpdateRoutine = this.startCoroutine(this.internalUpdate(), FrameEvent.LateUpdate);
     }
@@ -762,8 +833,18 @@ export class PlayableDirector extends Behaviour {
     }
 }
 
-/** 
- * Experimental interface for receiving timeline animation callbacks. Register at the PlayableDirector
+/**
+ * Interface for receiving callbacks during timeline animation evaluation.  
+ * Allows modification of position/rotation values before they are applied.  
+ *
+ * **Registration:**
+ * ```ts
+ * director.registerAnimationCallback(this);
+ * // Later: director.unregisterAnimationCallback(this);
+ * ```
+ *
+ * @experimental This interface may change in future versions
+ * @see {@link PlayableDirector.registerAnimationCallback}
  */
 export interface ITimelineAnimationCallbacks {
     /**

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

@@ -8,7 +8,7 @@ const debug = getParam("debugsignals")
 
 
 /**
- * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.
+ * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.  
  */
 export class SignalAsset {
     @serializable()

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

@@ -1,7 +1,10 @@
-import { AnimationClip, Object3D, Quaternion, Vector3 } from "three";
+import { AnimationClip, Object3D, Quaternion, Vector3 } from "three";  
+
+import type { PlayableDirector } from "./PlayableDirector";
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type TimelineAssetModel = {
     name: string;
@@ -10,6 +13,8 @@ export declare type TimelineAssetModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link TimelineAssetModel} for the data structure of a timeline asset, which can be played using the PlayableDirector component.
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export enum TrackType {
     Activation = "ActivationTrack",
@@ -21,7 +26,9 @@ export enum TrackType {
 }
 
 /**
- * @category Animation and Sequencing
+ * @category Animation and Sequencing   
+ * @see {@link TimelineAssetModel} for the data structure of a timeline asset, which can be played using the PlayableDirector component.
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export enum ClipExtrapolation {
     None = 0,
@@ -33,6 +40,7 @@ export enum ClipExtrapolation {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type TrackModel = {
     name: string;
@@ -50,6 +58,7 @@ declare type Quat = { x: number, y: number, z: number, w: number };
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type TrackOffset = {
     position: Vec3 | Vector3;
@@ -58,6 +67,7 @@ export declare type TrackOffset = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type ClipModel = {
     start: number;
@@ -75,6 +85,7 @@ export declare type ClipModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type AnimationClipModel = {
     clip: string | number | AnimationClip;
@@ -87,6 +98,7 @@ export declare type AnimationClipModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type AudioClipModel = {
     clip: string;
@@ -96,6 +108,7 @@ export declare type AudioClipModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type ControlClipModel = {
     sourceObject: string | Object3D;
@@ -109,6 +122,7 @@ export enum MarkerType {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */export declare class MarkerModel {
     type: MarkerType;
     time: number;
@@ -116,6 +130,7 @@ export enum MarkerType {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare class SignalMarkerModel extends MarkerModel {
     retroActive: boolean;
@@ -133,5 +148,6 @@ export declare class SignalMarkerModel extends MarkerModel {
  * 
  * @link [Example Project using ScrollMarker](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
 */
 export type ScrollMarkerModel = MarkerModel & { name?: string };

package/src/engine-components/ui/Button.ts

@@ -61,12 +61,38 @@ class AnimationTriggers {
 }
 
 /**
- * Button is a UI component that can be clicked by the user to perform an action.  
- * It supports different visual states such as normal, highlighted, pressed, and disabled.  
- * You can customize the button's appearance using colors or animations for each state.
+ * [Button](https://engine.needle.tools/docs/api/Button) is a UI component that can be clicked to trigger actions.  
+ * Supports visual states (normal, highlighted, pressed, disabled) with  
+ * color tints or animation transitions.  
+ *
+ * **Visual transitions:**  
+ * - `ColorTint` - Tint the button image with state colors
+ * - `Animation` - Trigger animator states for each button state
+ * - `SpriteSwap` - Swap sprites for each state (not fully supported)
+ *
+ * **Requirements:**  
+ * - Typically paired with an {@link Image} component for visuals or any 3D object
+ *
+ * @example Listen to button clicks
+ * ```ts
+ * const button = myButton.getComponent(Button);
+ * button.onClick.addEventListener(() => {
+ *   console.log("Button clicked!");
+ * });
+ * ```
+ *
+ * @example Programmatically click a button
+ * ```ts
+ * button.click(); // Triggers onClick event
+ * ```
+ *
  * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
+ * @see {@link EventList} for onClick callback handling
+ * @see {@link Image} for button visuals
+ * @see {@link GraphicRaycaster} for UI interaction
+ * @see {@link Transition} for visual state options
  */
 export class Button extends Behaviour implements IPointerEventHandler {
 

package/src/engine-components/ui/Canvas.ts

@@ -25,13 +25,38 @@ export enum RenderMode {
 const debugLayout = getParam("debuguilayout");
 
 /**
- * Canvas is the root component for all UI elements in a scene.  
- * It defines the area where UI elements are rendered and manages their layout and rendering settings.  
- * Canvases can be set to render in world space or screen space (overlay or camera).  
- * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
+ * [Canvas](https://engine.needle.tools/docs/api/Canvas) is the root component for all UI elements in a scene.
+ * Defines the rendering area and manages layout for child UI elements.  
+ *
+ * **Render modes:**  
+ * - `WorldSpace` - UI exists in 3D space, can be viewed from any angle  
+ * - `ScreenSpaceOverlay` - UI rendered on top of everything (HUD)  
+ * - `ScreenSpaceCamera` - UI rendered at a distance from a specific camera  
+ *
+ * **Usage:**  
+ * All UI components ({@link Button}, {@link Text}, {@link Image}) must be
+ * children of a Canvas to render correctly. Multiple canvases can exist
+ * in a scene with different settings.
+ *
+ * **Rendering options:**  
+ * - `renderOnTop` - Always render above other objects
+ * - `depthWrite` - Write to depth buffer (affects occlusion)
+ * - `doubleSided` - Render both sides of UI elements
+ *
+ * @example Create a world-space UI panel
+ * ```ts
+ * const canvas = panel.getComponent(Canvas);
+ * canvas.renderMode = RenderMode.WorldSpace;
+ * canvas.doubleSided = true;
+ * ```
+ *
  * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
+ * @see {@link RenderMode} for rendering options
+ * @see {@link RectTransform} for UI layout
+ * @see {@link Button} for clickable UI elements
+ * @see {@link Text} for UI text rendering
  */
 export class Canvas extends UIRootComponent implements ICanvas {
 

package/src/engine-components/ui/CanvasGroup.ts

@@ -7,8 +7,8 @@ import { type ICanvasGroup, type IHasAlphaFactor } from "./Interfaces.js";
 
 
 /**
- * CanvasGroup is a UI component that allows you to control the transparency and interactivity of a group of UI elements.  
- * By adjusting the alpha property, you can fade in or out all child UI elements simultaneously.  
+ * [CanvasGroup](https://engine.needle.tools/docs/api/CanvasGroup) is a UI component that allows you to control the transparency and interactivity of a group of UI elements.
+ * By adjusting the alpha property, you can fade in or out all child UI elements simultaneously.
  * The interactable and blocksRaycasts properties let you enable or disable user interaction for the entire group.
  * @summary Group UI elements to control transparency and interactivity
  * @category User Interface

package/src/engine-components/ui/EventSystem.ts

@@ -36,7 +36,7 @@ onInitialized((ctx) => {
 })
 
 /**
- * The EventSystem is responsible for managing and dispatching input events to UI components within the scene.
+ * [EventSystem](https://engine.needle.tools/docs/api/EventSystem) is responsible for managing and dispatching input events to UI components within the scene.
  * @summary Manages and dispatches input events to UI components
  * @category User Interface
  * @group Components

package/src/engine-components/ui/Graphic.ts

@@ -22,6 +22,7 @@ const _colorStateObject: { backgroundColor: Color, backgroundOpacity: number, bo
 };
 
 /**
+ * [Graphic](https://engine.needle.tools/docs/api/Graphic) provides basic rendering for UI elements with color, opacity, and texture support.
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Image.ts

@@ -12,12 +12,31 @@ class Sprite {
 }
 
 /**
- * Image is a UI component that displays a sprite (2D image) in the user interface.  
- * You can set the image property to assign a texture to be displayed.  
- * The sprite can be customized with various properties such as color tinting and pixel density.
+ * [Image](https://engine.needle.tools/docs/api/Image) displays a sprite (2D texture) in the UI. Can be used for icons,
+ * backgrounds, or any visual element that needs a texture.  
+ *
+ * **Properties:**  
+ * - `image` - Direct texture assignment (convenience property)
+ * - `sprite` - Sprite object containing texture and rect info
+ * - `color` - Tint color applied to the image (inherited from Graphic)
+ *
+ * **Usage with Button:**  
+ * Image is commonly paired with {@link Button} to create clickable  
+ * UI elements with visual feedback via color tinting.  
+ *
+ * @example Set an image texture
+ * ```ts
+ * const img = myIcon.getComponent(Image);
+ * img.image = myTexture;
+ * img.color = new RGBAColor(1, 0.5, 0.5, 1); // Red tint
+ * ```
+ *
  * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
+ * @see {@link Canvas} for the UI root
+ * @see {@link Button} for clickable images
+ * @see {@link RawImage} for non-UI image display
  */
 export class Image extends MaskableGraphic {
 

package/src/engine-components/ui/InputField.ts

@@ -10,8 +10,8 @@ import { tryGetUIComponent } from "./Utils.js";
 const debug = getParam("debuginputfield");
 
 /**
- * InputField is a UI component that allows users to enter and edit text.  
- * It provides a text input area where users can type, delete, and modify text.  
+ * [InputField](https://engine.needle.tools/docs/api/InputField) is a UI component that allows users to enter and edit text.
+ * It provides a text input area where users can type, delete, and modify text.
  * The InputField supports placeholder text, events for value changes, and end edit actions.
  * @summary Text field for user input
  * @category User Interface

package/src/engine-components/ui/Layout.ts

@@ -301,6 +301,7 @@ export abstract class HorizontalOrVerticalLayoutGroup extends LayoutGroup {
 }
 
 /**
+ * [VerticalLayoutGroup](https://engine.needle.tools/docs/api/VerticalLayoutGroup) arranges child UI elements vertically with spacing, padding, and alignment options.
  * @category User Interface
  * @group Components
  */
@@ -313,6 +314,7 @@ export class VerticalLayoutGroup extends HorizontalOrVerticalLayoutGroup {
 }
 
 /**
+ * [HorizontalLayoutGroup](https://engine.needle.tools/docs/api/HorizontalLayoutGroup) arranges child UI elements horizontally with spacing, padding, and alignment options.
  * @category User Interface
  * @group Components
  */
@@ -325,6 +327,7 @@ export class HorizontalLayoutGroup extends HorizontalOrVerticalLayoutGroup {
 }
 
 /**
+ * [GridLayoutGroup](https://engine.needle.tools/docs/api/GridLayoutGroup) arranges child UI elements in a grid pattern.
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Outline.ts

@@ -5,7 +5,7 @@ import { RGBAColor } from "../../engine/js-extensions/index.js";
 import { Behaviour } from "../Component.js";
 
 /**
- * Outline is a UI component that adds an outline effect to UI elements.  
+ * [Outline](https://engine.needle.tools/docs/api/Outline) is a UI component that adds an outline effect to UI elements.
  * You can customize the outline color and distance to create a visual border around the UI element.
  * @summary Add an outline effect to UI elements
  * @category User Interface

package/src/engine-components/ui/PointerEvents.ts

@@ -10,7 +10,7 @@ export interface IInputEventArgs {
     stopImmediatePropagation?(): void;
 }
 
-/** This pointer event data object is passed to all event receivers that are currently active  
+/** [PointerEventData](https://engine.needle.tools/docs/api/PointerEventData) This pointer event data object is passed to all event receivers that are currently active  
  * It contains hit information if an object was hovered or clicked  
  * If the event is received in onPointerDown or onPointerMove, you can call `setPointerCapture` to receive onPointerMove events even when the pointer has left the object until you call `releasePointerCapture` or when the pointerUp event happens  
  * You can get additional information about the event or event source via the `event` property (of type `NEPointerEvent`)

package/src/engine-components/ui/Raycaster.ts

@@ -7,9 +7,21 @@ import { Behaviour } from "../Component.js";
 import { EventSystem } from "./EventSystem.js";
 
 
-/** Derive from this class to create your own custom Raycaster  
- * If you override awake, onEnable or onDisable, be sure to call the base class methods  
- * Implement `performRaycast` to perform your custom raycasting logic
+/**
+ * [ObjectRaycaster](https://engine.needle.tools/docs/api/ObjectRaycaster) Base class for raycasters that detect pointer interactions.  
+ * Derive from this class to create custom raycasting logic. 
+ *
+ * **Built-in raycasters:**  
+ * - {@link ObjectRaycaster} - Raycasts against 3D objects
+ * - {@link GraphicRaycaster} - Raycasts against UI elements
+ * - {@link SpatialGrabRaycaster} - Sphere overlap for XR grab
+ *
+ * **Important:** If you override `awake`, `onEnable`, or `onDisable`,  
+ * call the base class methods to ensure proper registration with {@link EventSystem}.
+ *
+ * @category Interactivity
+ * @group Components
+ * @see {@link EventSystem} for the event dispatch system
  */
 export abstract class Raycaster extends Behaviour {
     awake(): void {
@@ -29,10 +41,22 @@ export abstract class Raycaster extends Behaviour {
 
 
 /**
- * A Raycaster that performs raycasting against its own GameObject.  
+ * ObjectRaycaster enables pointer interactions with 3D objects.  
+ * Add this component to any object that needs click/hover detection.  
+ *
+ * **Usage:**  
+ * Objects with ObjectRaycaster will receive pointer events when  
+ * they implement interfaces like {@link IPointerClickHandler}.
  * 
+ * **Note:**  
+ * In older Needle Engine versions the ObjectRaycaster was required to be added to the Scene.  
+ * This is no longer the case - the EventSystem will automatically handle raycasts.  
+ *
+ *
  * @category Interactivity
  * @group Components
+ * @see {@link IPointerClickHandler} for click events
+ * @see {@link DragControls} for drag interactions
  */
 export class ObjectRaycaster extends Raycaster {
     private targets: Object3D[] | null = null;
@@ -73,11 +97,27 @@ export class ObjectRaycaster extends Raycaster {
 
 
 /**
- * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
- * 
+ * GraphicRaycaster enables pointer interactions with UI elements.
+ * Add this to a {@link Canvas} or UI hierarchy to enable button clicks,
+ * hover effects, and other UI interactions.
+ *
+ * **Requirements:**
+ * - Must be on the same object as a Canvas or on a parent
+ * - UI elements need proper RectTransform setup
+ *
+ * @example Enable UI interaction
+ * ```ts
+ * // Add to Canvas object
+ * canvas.addComponent(GraphicRaycaster);
+ * // Now buttons and other UI elements will respond to clicks
+ * ```
+ *
  * @summary Raycaster for UI elements
  * @category User Interface
  * @group Components
+ * @see {@link Canvas} for UI root
+ * @see {@link Button} for clickable UI
+ * @see {@link EventSystem} for event handling
  */
 export class GraphicRaycaster extends ObjectRaycaster {
     // eventCamera: Camera | null = null;
@@ -91,10 +131,19 @@ export class GraphicRaycaster extends ObjectRaycaster {
 }
 
 /**
- * A Raycaster that performs sphere overlap raycasting for spatial grab interactions in XR.  
- * 
+ * SpatialGrabRaycaster enables direct grab interactions in VR/AR.
+ * Uses sphere overlap detection around the controller/hand position
+ * to allow grabbing objects by reaching into them.
+ *
+ * **Features:**
+ * - Active only during XR sessions
+ * - Can be globally disabled via `SpatialGrabRaycaster.allow`
+ * - Works alongside ray-based interaction
+ *
  * @category XR
  * @group Components
+ * @see {@link WebXR} for XR session management
+ * @see {@link DragControls} for object manipulation
  */
 export class SpatialGrabRaycaster extends Raycaster {
 

package/src/engine-components/ui/RectTransform.ts

@@ -29,8 +29,8 @@ const tempVec = new Vector3();
 const tempMatrix = new Matrix4();
 const tempQuaternion = new Quaternion();
 
-/** 
-* RectTransform is a component that defines a rectangle for UI layout. 
+/**
+* [RectTransform](https://engine.needle.tools/docs/api/RectTransform) defines a rectangle for UI layout with anchoring, pivoting, and positioning capabilities.
 * @summary UI Rectangle Transform
 * @category User Interface
 * @group Components

package/src/engine-components/ui/SpatialHtml.ts

@@ -7,7 +7,7 @@ import { getWorldRotation, setWorldRotationXYZ } from '../../engine/engine_three
 import { Behaviour } from '../Component.js';
 
 /**
- * SpatialHtml is a component that allows you to integrate HTML elements into a 3D scene.  
+ * [SpatialHtml](https://engine.needle.tools/docs/api/SpatialHtml) is a component that allows you to integrate HTML elements into a 3D scene.
  * By specifying the ID of an existing HTML element, you can render it as a 3D object within the scene.
  * @summary Render HTML elements as 3D objects in the scene
  * @category User Interface