@needle-tools/engine 4.13.0 → 4.13.1

package/lib/engine-components/web/HoverAnimation.d.ts

@@ -2,39 +2,168 @@ import { AnimationClip } from "three";
 import { ScaleClipType } from "../../engine/engine_animation.js";
 import { Behaviour } from "../Component.js";
 /**
- * Plays a hover animation on the object this component was added to when the mouse pointer (or touch) is over the object or any of it's children.
+ * [HoverAnimation](https://engine.needle.tools/docs/api/HoverAnimation) plays animations in response to pointer hover events on the object this component is attached to.
+ * The component automatically detects when the mouse pointer or touch enters/exits the object or any of its children, triggering the corresponding animations.
  *
- * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
+ * **How It Works:**
+ * The component listens to pointer enter and exit events and switches between two animation states:
+ * - **Hover state**: Plays when the pointer enters the object (default: scale up to 110%)
+ * - **Idle state**: Plays when the pointer exits the object (default: returns to original scale)
  *
- * @summary Hover Animation on Pointer Enter/Exit
+ * **Default Behavior:**
+ * If no custom animation clips are provided, the component automatically creates a smooth scale-up animation using the
+ * {@link type}, {@link duration}, and {@link scaleFactor} properties. This provides instant hover feedback without
+ * requiring any animation setup.
+ *
+ * **Custom Animations:**
+ * You can provide your own animation clips for complete control over the hover effect. This allows you to create
+ * complex animations involving position, rotation, color changes, or any other animated property.
+ *
+ * **Common Use Cases:**
+ * - Interactive buttons with scale feedback
+ * - Product showcases with highlight animations
+ * - Menu items with hover effects
+ * - Interactive 3D objects in AR/VR experiences
+ * - Call-to-action elements with attention-grabbing animations
+ *
+ * @example Basic usage with default scale animation
+ * ```ts
+ * const button = new Object3D();
+ * button.addComponent(HoverAnimation, {
+ *   scaleFactor: 1.2,    // Scale to 120% on hover
+ *   duration: 0.2,       // 200ms animation
+ *   type: "ease-in-out"  // Smooth easing
+ * });
+ * scene.add(button);
+ * ```
+ *
+ * @example Custom hover animations
+ * ```ts
+ * const obj = new Object3D();
+ * const hoverAnim = loadAnimationClip("hover-glow.anim");
+ * const idleAnim = loadAnimationClip("idle-pulse.anim");
+ *
+ * obj.addComponent(HoverAnimation, {
+ *   hovered: hoverAnim,  // Custom hover animation
+ *   idle: idleAnim       // Custom idle animation
+ * });
+ * scene.add(obj);
+ * ```
+ *
+ * @example Quick scale animation with custom settings
+ * ```ts
+ * gameObject.addComponent(HoverAnimation, {
+ *   scaleFactor: 1.15,
+ *   duration: 0.15,
+ *   type: "ease-out"
+ * });
+ * ```
+ *
+ * @see {@link Animation} - The underlying animation component used to play clips
+ * @see {@link AnimationClip} - For creating custom animation clips
+ * @see {@link AnimationUtils} - Utility functions for creating animations programmatically
+ * @see {@link ScaleClipType} - Available easing types for the default scale animation
+ * @see {@link ObjectRaycaster} - Controls which objects receive pointer events
+ * @see {@link PointerEvents} - For more complex pointer interaction handling
+ *
+ * @summary Plays animations on pointer hover enter/exit events
  * @category Interactivity
  * @group Components
+ * @component
  */
 export declare class HoverAnimation extends Behaviour {
     /**
-     * Default hover animation type if no custom clip is provided.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * The easing type for the default scale animation.
+     *
+     * This property controls how the scale animation interpolates from the start to end value.
+     * Different easing types create different "feels" for the hover effect.
+     *
+     * **Available types:**
+     * - `"linear"`: Constant speed throughout the animation
+     * - `"ease-in"`: Starts slow, ends fast
+     * - `"ease-out"`: Starts fast, ends slow (good for responsive feel)
+     * - `"ease-in-out"`: Starts slow, fast in middle, ends slow (smooth and natural)
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
+     * @see {@link ScaleClipType} for all available easing types
      * @default "linear"
      */
     type: ScaleClipType;
     /**
-     * Duration of the hover animation in seconds.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * Duration of the default hover animation in seconds.
+     *
+     * This controls how long it takes for the object to scale up when hovered.
+     * Shorter durations feel more responsive, while longer durations feel smoother.
+     *
+     * **Recommendations:**
+     * - `0.1-0.15s`: Snappy, responsive feel (good for buttons)
+     * - `0.2-0.3s`: Smooth, noticeable animation
+     * - `0.4s+`: Slow, emphasized effect
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
      * @default 0.1
      */
     duration: number;
     /**
-     * Scale factor to apply when hovering.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * The scale multiplier to apply when the object is hovered.
+     *
+     * This value is multiplied with the object's original scale to determine the hover size.
+     * A value of `1.0` means no change, values greater than `1.0` scale up, and values less than `1.0` scale down.
+     *
+     * **Examples:**
+     * - `1.0`: No scale change
+     * - `1.1`: Scale to 110% (subtle effect, default)
+     * - `1.2`: Scale to 120% (noticeable effect)
+     * - `1.5`: Scale to 150% (dramatic effect)
+     * - `0.9`: Scale to 90% (shrink on hover)
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
      * @default 1.1
      */
     scaleFactor: number;
     /**
-     * Animation clip to play when hovering. If null, a default scale-up animation is used.
+     * Custom animation clip to play when the pointer hovers over the object.
+     *
+     * If `null`, the component automatically generates a scale-up animation based on the
+     * {@link type}, {@link duration}, and {@link scaleFactor} properties.
+     *
+     * Provide a custom animation clip if you want more complex hover effects such as:
+     * - Color changes or material property animations
+     * - Position or rotation changes
+     * - Multi-property animations
+     * - Animations affecting child objects
+     *
+     * **Tip:** The animation plays with a 0.1s fade duration for smooth transitions.
+     *
+     * @see {@link AnimationClip} for creating custom animation clips
+     * @see {@link AnimationUtils.createScaleClip} for programmatically creating scale animations
+     * @default null (generates default scale animation)
      */
     hovered: AnimationClip | null;
     /**
-     * Animation clip to play when not hovering. If null, an empty clip is used.
+     * Custom animation clip to play when the pointer is not hovering over the object (idle state).
+     *
+     * If `null`, an empty animation clip is used, which returns the object to its original state
+     * when the hover animation ends.
+     *
+     * You can provide a custom idle animation for effects such as:
+     * - Subtle breathing or floating motion when not hovered
+     * - Pulsing or glowing effects in idle state
+     * - Return-to-normal animations with custom easing
+     * - Looping ambient animations
+     *
+     * **Tip:** The idle animation is played with `loop: true`, so it will repeat continuously
+     * until the object is hovered again.
+     *
+     * @see {@link AnimationClip} for creating custom animation clips
+     * @see {@link AnimationUtils.emptyClip} to see how the default empty clip is created
+     * @default null (uses empty clip that returns to original state)
      */
     idle: AnimationClip | null;
     private animation;

package/lib/engine-components/web/HoverAnimation.js

@@ -11,39 +11,168 @@ import { registerType } from "../../engine/engine_typestore.js";
 import { Animation } from "../Animation.js";
 import { Behaviour } from "../Component.js";
 /**
- * Plays a hover animation on the object this component was added to when the mouse pointer (or touch) is over the object or any of it's children.
+ * [HoverAnimation](https://engine.needle.tools/docs/api/HoverAnimation) plays animations in response to pointer hover events on the object this component is attached to.
+ * The component automatically detects when the mouse pointer or touch enters/exits the object or any of its children, triggering the corresponding animations.
  *
- * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
+ * **How It Works:**
+ * The component listens to pointer enter and exit events and switches between two animation states:
+ * - **Hover state**: Plays when the pointer enters the object (default: scale up to 110%)
+ * - **Idle state**: Plays when the pointer exits the object (default: returns to original scale)
  *
- * @summary Hover Animation on Pointer Enter/Exit
+ * **Default Behavior:**
+ * If no custom animation clips are provided, the component automatically creates a smooth scale-up animation using the
+ * {@link type}, {@link duration}, and {@link scaleFactor} properties. This provides instant hover feedback without
+ * requiring any animation setup.
+ *
+ * **Custom Animations:**
+ * You can provide your own animation clips for complete control over the hover effect. This allows you to create
+ * complex animations involving position, rotation, color changes, or any other animated property.
+ *
+ * **Common Use Cases:**
+ * - Interactive buttons with scale feedback
+ * - Product showcases with highlight animations
+ * - Menu items with hover effects
+ * - Interactive 3D objects in AR/VR experiences
+ * - Call-to-action elements with attention-grabbing animations
+ *
+ * @example Basic usage with default scale animation
+ * ```ts
+ * const button = new Object3D();
+ * button.addComponent(HoverAnimation, {
+ *   scaleFactor: 1.2,    // Scale to 120% on hover
+ *   duration: 0.2,       // 200ms animation
+ *   type: "ease-in-out"  // Smooth easing
+ * });
+ * scene.add(button);
+ * ```
+ *
+ * @example Custom hover animations
+ * ```ts
+ * const obj = new Object3D();
+ * const hoverAnim = loadAnimationClip("hover-glow.anim");
+ * const idleAnim = loadAnimationClip("idle-pulse.anim");
+ *
+ * obj.addComponent(HoverAnimation, {
+ *   hovered: hoverAnim,  // Custom hover animation
+ *   idle: idleAnim       // Custom idle animation
+ * });
+ * scene.add(obj);
+ * ```
+ *
+ * @example Quick scale animation with custom settings
+ * ```ts
+ * gameObject.addComponent(HoverAnimation, {
+ *   scaleFactor: 1.15,
+ *   duration: 0.15,
+ *   type: "ease-out"
+ * });
+ * ```
+ *
+ * @see {@link Animation} - The underlying animation component used to play clips
+ * @see {@link AnimationClip} - For creating custom animation clips
+ * @see {@link AnimationUtils} - Utility functions for creating animations programmatically
+ * @see {@link ScaleClipType} - Available easing types for the default scale animation
+ * @see {@link ObjectRaycaster} - Controls which objects receive pointer events
+ * @see {@link PointerEvents} - For more complex pointer interaction handling
+ *
+ * @summary Plays animations on pointer hover enter/exit events
  * @category Interactivity
  * @group Components
+ * @component
  */
 let HoverAnimation = class HoverAnimation extends Behaviour {
     /**
-     * Default hover animation type if no custom clip is provided.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * The easing type for the default scale animation.
+     *
+     * This property controls how the scale animation interpolates from the start to end value.
+     * Different easing types create different "feels" for the hover effect.
+     *
+     * **Available types:**
+     * - `"linear"`: Constant speed throughout the animation
+     * - `"ease-in"`: Starts slow, ends fast
+     * - `"ease-out"`: Starts fast, ends slow (good for responsive feel)
+     * - `"ease-in-out"`: Starts slow, fast in middle, ends slow (smooth and natural)
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
+     * @see {@link ScaleClipType} for all available easing types
      * @default "linear"
      */
     type = "linear";
     /**
-     * Duration of the hover animation in seconds.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * Duration of the default hover animation in seconds.
+     *
+     * This controls how long it takes for the object to scale up when hovered.
+     * Shorter durations feel more responsive, while longer durations feel smoother.
+     *
+     * **Recommendations:**
+     * - `0.1-0.15s`: Snappy, responsive feel (good for buttons)
+     * - `0.2-0.3s`: Smooth, noticeable animation
+     * - `0.4s+`: Slow, emphasized effect
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
      * @default 0.1
      */
     duration = 0.1;
     /**
-     * Scale factor to apply when hovering.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * The scale multiplier to apply when the object is hovered.
+     *
+     * This value is multiplied with the object's original scale to determine the hover size.
+     * A value of `1.0` means no change, values greater than `1.0` scale up, and values less than `1.0` scale down.
+     *
+     * **Examples:**
+     * - `1.0`: No scale change
+     * - `1.1`: Scale to 110% (subtle effect, default)
+     * - `1.2`: Scale to 120% (noticeable effect)
+     * - `1.5`: Scale to 150% (dramatic effect)
+     * - `0.9`: Scale to 90% (shrink on hover)
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
      * @default 1.1
      */
     scaleFactor = 1.1;
     /**
-     * Animation clip to play when hovering. If null, a default scale-up animation is used.
+     * Custom animation clip to play when the pointer hovers over the object.
+     *
+     * If `null`, the component automatically generates a scale-up animation based on the
+     * {@link type}, {@link duration}, and {@link scaleFactor} properties.
+     *
+     * Provide a custom animation clip if you want more complex hover effects such as:
+     * - Color changes or material property animations
+     * - Position or rotation changes
+     * - Multi-property animations
+     * - Animations affecting child objects
+     *
+     * **Tip:** The animation plays with a 0.1s fade duration for smooth transitions.
+     *
+     * @see {@link AnimationClip} for creating custom animation clips
+     * @see {@link AnimationUtils.createScaleClip} for programmatically creating scale animations
+     * @default null (generates default scale animation)
      */
     hovered = null;
     /**
-     * Animation clip to play when not hovering. If null, an empty clip is used.
+     * Custom animation clip to play when the pointer is not hovering over the object (idle state).
+     *
+     * If `null`, an empty animation clip is used, which returns the object to its original state
+     * when the hover animation ends.
+     *
+     * You can provide a custom idle animation for effects such as:
+     * - Subtle breathing or floating motion when not hovered
+     * - Pulsing or glowing effects in idle state
+     * - Return-to-normal animations with custom easing
+     * - Looping ambient animations
+     *
+     * **Tip:** The idle animation is played with `loop: true`, so it will repeat continuously
+     * until the object is hovered again.
+     *
+     * @see {@link AnimationClip} for creating custom animation clips
+     * @see {@link AnimationUtils.emptyClip} to see how the default empty clip is created
+     * @default null (uses empty clip that returns to original state)
      */
     idle = null;
     animation = null;

package/lib/engine-components/web/HoverAnimation.js.map

@@ -1 +1 @@
-{"version":3,"file":"HoverAnimation.js","sourceRoot":"","sources":["../../../src/engine-components/web/HoverAnimation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HoverAnimation.js","sourceRoot":"","sources":["../../../src/engine-components/web/HoverAnimation.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAGtC,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAEI,IAAM,cAAc,GAApB,MAAM,cAAe,SAAQ,SAAS;IAEzC;;;;;;;;;;;;;;;;;OAiBG;IAEH,IAAI,GAAkB,QAAQ,CAAC;IAE/B;;;;;;;;;;;;;;;OAeG;IAEH,QAAQ,GAAW,GAAG,CAAC;IAEvB;;;;;;;;;;;;;;;;;OAiBG;IAEH,WAAW,GAAW,GAAG,CAAC;IAG1B;;;;;;;;;;;;;;;;;OAiBG;IAEH,OAAO,GAAyB,IAAI,CAAC;IAErC;;;;;;;;;;;;;;;;;;OAkBG;IAEH,IAAI,GAAyB,IAAI,CAAC;IAE1B,SAAS,GAAqB,IAAI,CAAC;IAE3C,KAAK;QACD,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,SAAS,EAAE,CAAC;QAEvD,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,YAAY,aAAa,CAAC,EAAE;YAC3D,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,eAAe,CAAC;gBAC1C,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,GAAG;gBAC9B,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;gBAC5B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,GAAG;aACvC,CAAC,CAAC;SACN;QAED,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,CAAC,iBAAiB,GAAG,KAAK,CAAC;QACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;IACpB,CAAC;IAED,QAAQ;QACJ,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;QAClD,IAAI,CAAC,QAAQ,EAAE,CAAC;IACpB,CAAC;IACD,SAAS;QACL,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC;QACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;IACpB,CAAC;IAED,cAAc;QACV,IAAI,CAAC,SAAS,EAAE,CAAC;IACrB,CAAC;IAED,aAAa;QACT,IAAI,CAAC,QAAQ,EAAE,CAAC;IACpB,CAAC;IAEO,QAAQ;QACZ,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACtG,CAAC;IACO,SAAS;QACb,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IACtI,CAAC;CAEJ,CAAA;AAjIG;IADC,YAAY,EAAE;4CACgB;AAmB/B;IADC,YAAY,EAAE;gDACQ;AAqBvB;IADC,YAAY,EAAE;mDACW;AAsB1B;IADC,YAAY,CAAC,aAAa,CAAC;+CACS;AAsBrC;IADC,YAAY,CAAC,aAAa,CAAC;4CACM;AAzGzB,cAAc;IAD1B,YAAY;GACA,cAAc,CAsJ1B;SAtJY,cAAc"}

package/lib/engine-components/web/ScrollFollow.d.ts

@@ -13,10 +13,13 @@ type ScrollFollowEvent = {
     defaultPrevented: boolean;
 };
 /**
- * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.
+ * The [ScrollFollow](https://engine.needle.tools/docs/api/ScrollFollow) component allows you to link the scroll position of the page (or a specific element) to one or more target objects.
  
  * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
  *
+ * ![](https://cloud.needle.tools/-/media/SYuH-vXxO4Jf30oU1HhjKQ.gif)
+ * ![](https://cloud.needle.tools/-/media/RplmU_j7-xb8XHXkOzc9PA.gif)
+ *
  * Assign {@link target} objects to the component to have them updated based on the current scroll position (check the 'target' property for supported types).
  *
  * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/

package/lib/engine-components/web/ScrollFollow.js

@@ -22,10 +22,13 @@ import { SplineWalker } from "../splines/SplineWalker.js";
 import { PlayableDirector } from "../timeline/PlayableDirector.js";
 const debug = getParam("debugscroll");
 /**
- * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.
+ * The [ScrollFollow](https://engine.needle.tools/docs/api/ScrollFollow) component allows you to link the scroll position of the page (or a specific element) to one or more target objects.
  
  * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
  *
+ * ![](https://cloud.needle.tools/-/media/SYuH-vXxO4Jf30oU1HhjKQ.gif)
+ * ![](https://cloud.needle.tools/-/media/RplmU_j7-xb8XHXkOzc9PA.gif)
+ *
  * Assign {@link target} objects to the component to have them updated based on the current scroll position (check the 'target' property for supported types).
  *
  * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/

package/lib/engine-components/web/ScrollFollow.js.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/ScrollFollow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScrollFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/ScrollFollow.ts"],"names":[],"mappings":"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"}

package/lib/engine-components/web/ViewBox.d.ts

@@ -1,21 +1,82 @@
 import { Behaviour } from "../Component.js";
+/**
+ * Defines how the {@link ViewBox} component applies camera framing adjustments.
+ *
+ * - `"continuous"`: Camera framing is continuously updated while the ViewBox is active. Use for animated or dynamic ViewBoxes.
+ * - `"once"`: Camera framing is applied once when the ViewBox becomes active, then updates stop. Use for initial framing with subsequent user control.
+ */
 export type ViewBoxMode = "continuous" | "once";
 /**
- * This component can be used to automatically fit a certain box area into the camera view - no matter your screen size or aspect ratio.
- * This is useful for example to frame a character or object in the center of the screen and ensure it is always fully visible. You can also animate or scale the viewbox to create zoom or framing effects.
+ * [ViewBox](https://engine.needle.tools/docs/api/ViewBox) automatically fits a defined box area into the camera view regardless of screen size or aspect ratio.
+ * This component is useful for framing characters, objects, or scenes in the center of the view while ensuring they remain fully visible.
+ * You can animate or scale the viewbox to create dynamic zoom effects, cinematic transitions, or responsive framing.
+ *
+ * [![](https://cloud.needle.tools/-/media/Thy6svVftsIC6Z_wIxUJMA.gif)](https://engine.needle.tools/samples/bike-scrollytelling-responsive-3d)
+ *
+ * The ViewBox component works by adjusting the camera's focus rect settings (offset and zoom) to ensure that the box defined by the
+ * GameObject's position, rotation, and scale fits perfectly within the visible viewport. It supports different modes for one-time
+ * fitting or continuous adjustment, making it versatile for both static compositions and animated sequences.
+ *
+ * **Key Features:**
+ * - Automatically adjusts camera framing to fit the box area
+ * - Works with any screen size and aspect ratio
+ * - Supports one-time fitting or continuous updates
+ * - Can be animated for dynamic zoom and framing effects
+ * - Multiple ViewBoxes can be active, with the most recently enabled taking priority
+ * - Handles camera positioning to ensure the box is visible (moves camera if inside the box)
+ *
+ * **Common Use Cases:**
+ * - Character framing in cutscenes or dialogue
+ * - Product showcases with guaranteed visibility
+ * - Scrollytelling experiences with animated camera movements
+ * - Responsive layouts that adapt to different screen sizes
+ * - UI-driven camera transitions
  *
  * - [Example on needle.run](https://viewbox-demo-z23hmxbz2gkayo-z1nyzm6.needle.run/)
  * - [Scrollytelling Demo using animated Viewbox](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)
  * - [Example on Stackblitz](https://stackblitz.com/edit/needle-engine-view-box-example)
  *
- * @example Add a Viewbox component to an object in your scene
+ * @example Basic setup - Add a ViewBox component to frame an object
+ * ```ts
+ * const viewBox = new Object3D();
+ * viewBox.position.set(0, 1, 0); // Position the viewbox center
+ * viewBox.scale.set(2, 2, 2);    // Define the box size
+ * viewBox.addComponent(ViewBox, { debug: true });
+ * scene.add(viewBox);
+ * ```
+ *
+ * @example Animated ViewBox for zoom effects
+ * ```ts
+ * const viewBox = new Object3D();
+ * viewBox.addComponent(ViewBox, { mode: "continuous" });
+ * scene.add(viewBox);
+ *
+ * // Animate the viewbox scale over time
+ * function update() {
+ *   const scale = 1 + Math.sin(Date.now() * 0.001) * 0.5;
+ *   viewBox.scale.setScalar(scale);
+ * }
+ * ```
+ *
+ * @example One-time fitting with user control afterwards
  * ```ts
-  const viewBox = new Object3D();
-  viewBox.scale.set(0, 0, 0);
-  viewBox.addComponent(ViewBox, { debug: true });
-  scene.add(viewBox);
+ * const viewBox = new Object3D();
+ * viewBox.addComponent(ViewBox, {
+ *   mode: "once", // Fit once, then allow free camera control
+ *   referenceFieldOfView: 60
+ * });
+ * scene.add(viewBox);
  * ```
-  
+ *
+ * @see {@link Camera} - The camera component that ViewBox controls
+ * @see {@link OrbitControls} - Camera controls that work alongside ViewBox
+ * @see {@link DragControls} - Alternative camera controls compatible with ViewBox
+ * @see {@link LookAtConstraint} - Another way to control camera targeting
+ * @see {@link SceneSwitcher} - Can be combined with ViewBox for scene transitions
+ * @see {@link Context.setCameraFocusRect} - The underlying focus rect API used by ViewBox
+ * @see {@link Context.focusRectSettings} - Manual control of focus rect settings
+ * @see {@link ViewBoxMode} - The mode type for controlling ViewBox behavior
+ *
  * @summary Automatically fits a box area into the camera view
  * @category Camera and Controls
  * @group Components
@@ -23,25 +84,64 @@ export type ViewBoxMode = "continuous" | "once";
  */
 export declare class ViewBox extends Behaviour {
     /**
-     * All active ViewBox instances. The last one in the array is the currently active one.
+     * Array of all active ViewBox instances in the scene.
+     * When multiple ViewBoxes are enabled, the last one in the array (most recently enabled) takes priority and controls the camera.
+     * Other ViewBoxes remain registered but inactive, displayed with a dimmed gizmo color when debug visualization is enabled.
      */
     static readonly instances: ViewBox[];
     /**
-     * The reference field of view is used to calculate the box size. This should usually be the same as your camera's fov.
-     * @default -1 (meaning it will use the camera fov on the first frame)
+     * The reference field of view (in degrees) used to calculate how the box should fit within the camera view.
+     * This determines the baseline camera FOV for fitting calculations.
+     *
+     * **Behavior:**
+     * - If set to `-1` (default), the component will automatically use the camera's FOV on the first frame
+     * - Should typically match your camera's FOV for predictable framing
+     * - Can be set to a different value to create specific framing effects
+     *
+     * **Example:**
+     * If your camera has an FOV of 60° and you set `referenceFieldOfView` to 60, the ViewBox will fit objects
+     * as they would appear with that field of view. Setting it to a wider FOV (e.g., 90) makes objects appear
+     * smaller, while a narrower FOV (e.g., 30) makes them appear larger.
+     *
+     * @see {@link Camera} for the camera component and its FOV property
+     * @default -1 (automatically uses the camera's FOV on the first frame)
      */
     referenceFieldOfView: number;
     /**
-     * The mode determines if the viewbox should be applied once or continuously while it is the active viewbox.
-     * Options:
-     * - "once": The viewbox will be applied once when it becomes the active viewbox. This is useful if you want to fit the view once and then allow the user to zoom or pan freely.
-     * - "continuous": The viewbox will be applied continuously while it is the active viewbox. This is useful if you animate or scale the viewbox over time.
+     * Controls how the ViewBox applies camera adjustments.
+     *
+     * **Modes:**
+     * - `"once"`: Applies the framing adjustment once when the ViewBox becomes active, then stops updating.
+     *   This is ideal when you want to frame the view initially but allow users to freely zoom, pan, or orbit afterwards.
+     *   Perfect for interactive scenes where you want a good starting view but full user control.
+     *
+     * - `"continuous"`: Continuously updates the camera framing while this ViewBox is active.
+     *   Use this when animating or scaling the ViewBox over time, or when you need the framing to constantly adjust.
+     *   Great for cutscenes, scrollytelling, or any scenario with animated ViewBoxes.
+     *
+     * **Example Use Cases:**
+     * - Set to `"once"` for: Initial scene framing, product showcases where users explore freely after initial framing
+     * - Set to `"continuous"` for: Animated zoom effects, scrollytelling sequences, dynamic camera movements tied to ViewBox transforms
+     *
+     * @see {@link ViewBoxMode} for the type definition
+     * @default "continuous"
     */
     get mode(): ViewBoxMode;
     set mode(v: ViewBoxMode);
     private _mode;
     /**
-     * Enable debug logs and rendering for this component instance
+     * Enables debug visualization and logging for this ViewBox instance.
+     *
+     * **When enabled, you will see:**
+     * - A yellow wireframe box showing the active ViewBox bounds in 3D space
+     * - Gray wireframe boxes for inactive ViewBox instances
+     * - A red dashed outline on screen showing the projected box in 2D (when using `?debugviewbox` URL parameter)
+     * - Console logs for mode changes, FOV settings, and camera adjustments
+     *
+     * **Tip:** You can also enable debug visualization globally for all ViewBoxes by adding `?debugviewbox` to your URL.
+     *
+     * @see {@link Gizmos} for the gizmo rendering system used for debug visualization
+     * @default false
      */
     debug: boolean;
     /** @internal */