@needle-tools/engine 4.13.1-beta → 4.13.1-next.9fc3e64

package/dist/needle-engine.d.ts

@@ -413,6 +413,7 @@ export { Animation_2 as Animation }
 
 /**
  * @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;
@@ -1287,6 +1288,7 @@ declare type AttributeChangeCallback = (value: string | null) => void;
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type AudioClipModel = {
     clip: string;
@@ -3197,6 +3199,8 @@ export declare class ClickThrough extends Component {
 
 /**
  * @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 declare enum ClipExtrapolation {
     None = 0,
@@ -3215,6 +3219,7 @@ export declare type ClipMapping = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type ClipModel = {
     start: number;
@@ -3925,6 +3930,7 @@ export declare class ContactPoint {
 /**
  * [ContactShadows](https://engine.needle.tools/docs/api/ContactShadows) renders proximity-based soft shadows on flat surfaces.
  * Ideal for products or objects that need visual grounding without real-time shadows.
+ * Produces soft, blurred shadows that hug the ground, giving a sense of contact and depth.
  *
  * ![](https://cloud.needle.tools/-/media/87bPTNXHcsbV-An-oSEvHQ.gif)
  *
@@ -3951,6 +3957,7 @@ export declare class ContactPoint {
  * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
+ * @see {@link ShadowCatcher} for real-time shadows from lights (more accurate, higher performance cost)
  * @see {@link Light} for real-time shadow casting
  * @see {@link Renderer} for material/rendering control
  * @link https://engine.needle.tools/samples/contact-shadows for a demo of contact shadows
@@ -4548,6 +4555,7 @@ export { ContextRegistry as NeedleEngine }
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type ControlClipModel = {
     sourceObject: string | Object3D;
@@ -4676,6 +4684,7 @@ export declare function createMotion(name: string, id?: InstantiateIdProvider):
  *
  * @summary Makes objects follow the cursor/touch position in 3D space
  * @category Interactivity
+ * @category Web
  * @group Components
  * @component
  */
@@ -5073,6 +5082,7 @@ declare enum DeviceType {
 
 /**
  * Utility functions to detect certain device types (mobile, desktop), browsers, or capabilities.
+ * @category Utilities
  */
 export declare namespace DeviceUtilities {
     /** @returns `true` for MacOS or Windows devices. `false` for Hololens and other headsets. */
@@ -10018,6 +10028,7 @@ export declare function markAsInstancedRendered(go: Object3D, instanced: boolean
 
 /**
  * @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;
@@ -11310,7 +11321,12 @@ export declare type NeedleXRHitTestResult = {
  * The XRRig can be accessed via the `rig` property
  * Set a custom XRRig via `NeedleXRSession.addRig(...)` or `NeedleXRSession.removeRig(...)`
  * By default the active XRRig with the highest priority in the scene is used
+ *
+ * ### Screenshots in XR
+ * Screenshots work automatically during XR sessions, including AR camera feed compositing. See {@link screenshot2} for more information.
+ *
  * @category XR
+ * @see {@link screenshot2} for taking screenshots in XR sessions
  */
 export declare class NeedleXRSession implements INeedleXRSession {
     private static _sync;
@@ -12583,6 +12599,7 @@ export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void):
  * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
  *
  * @category Interactivity
+ * @category Web
  * @group Components
  */
 export declare class OpenURL extends Component implements IPointerClickHandler {
@@ -13579,6 +13596,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * ```ts
       * const hit = this.context.physics.engine?.raycast(origin, direction);
       * ```
+      * @see {@link Rigidbody} for physics simulation component
+      * @see {@link Collider} for collision detection component
       * @see {@link RapierPhysics} for physics engine implementation details
       */
      export declare class Physics {
@@ -13691,6 +13710,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * 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
@@ -13733,6 +13755,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @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 declare class PlayableDirector extends Component {
          private static createTrackFunctions;
@@ -14723,6 +14746,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *   const colliderDesc = MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.ball(1.0);
       * }
       * ```
+      * @see {@link Rigidbody} for physics simulation component
+      * @see {@link Collider} for collision detection component
       * @see {@link Physics} for general raycasting and physics utilities
       * @see {@link MODULES.RAPIER_PHYSICS} for direct access to the Rapier module
       * @link https://rapier.rs/docs/ for Rapier documentation
@@ -15120,20 +15145,52 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare const relativePathPrefix = "rel:";
 
      /**
-      * [RemoteSkybox](https://engine.needle.tools/docs/api/RemoteSkybox) Is a component that allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.
-      * It supports .hdr, .exr, .jpg, .png files.
+      * The [RemoteSkybox](https://engine.needle.tools/docs/api/RemoteSkybox) component allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.
+      * It supports .hdr, .exr, .jpg, .png, and .ktx2 files.
+      *
+      * **HTML Attributes:**
+      * You can control skybox and environment from HTML using `<needle-engine>` attributes:
+      * - `background-image`: Sets the scene background/skybox image
+      * - `environment-image`: Sets the scene environment map (for reflections and lighting)
+      *
+      * These attributes accept URLs or magic skybox names (see examples below).
+      *
+      * **Magic Skybox Names:**
+      * Built-in optimized skyboxes hosted on Needle CDN:
+      * - `"studio"` - Neutral studio lighting (default)
+      * - `"blurred-skybox"` - Blurred environment
+      * - `"quicklook"` - Apple QuickLook object mode style
+      * - `"quicklook-ar"` - Apple QuickLook AR mode style
       *
       * ### Events
       * - `dropped-unknown-url`: Emitted when a file is dropped on the scene. The event detail contains the sender, the url and a function to apply the url.
       *
-      * @example adding a skybox
+      * @example Using HTML attributes
+      * ```html
+      * <needle-engine
+      *   background-image="https://example.com/skybox.hdr"
+      *   environment-image="studio">
+      * </needle-engine>
+      * ```
+      *
+      * @example Using magic skybox names
+      * ```html
+      * <needle-engine background-image="studio"></needle-engine>
+      * <needle-engine environment-image="quicklook"></needle-engine>
+      * ```
+      *
+      * @example Adding via code
       * ```ts
-      * GameObject.addComponent(gameObject, Skybox, { url: "https://example.com/skybox.hdr", background: true, environment: true });
+      * GameObject.addComponent(gameObject, RemoteSkybox, {
+      *   url: "https://example.com/skybox.hdr",
+      *   background: true,
+      *   environment: true
+      * });
       * ```
       *
-      * @example handle custom url
+      * @example Handle custom dropped URL
       * ```ts
-      * const skybox = GameObject.addComponent(gameObject, Skybox);
+      * const skybox = GameObject.addComponent(gameObject, RemoteSkybox);
       * skybox.addEventListener("dropped-unknown-url", (evt) => {
       *    let url = evt.detail.url;
       *    console.log("User dropped file", url);
@@ -15144,14 +15201,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * });
       * ```
       *
-      * @example update skybox url
+      * @example Update skybox at runtime
       * ```ts
       * skybox.setSkybox("https://example.com/skybox.hdr");
+      * // Or use a magic name:
+      * skybox.setSkybox("studio");
       * ```
       *
       * @summary Sets the skybox or environment texture of a scene
       * @category Rendering
       * @group Components
+      * @see {@link Camera} for clearFlags and background control
+      * @link https://engine.needle.tools/docs/html.html#needle-engine-element
       */
      export declare class RemoteSkybox extends Component {
          /**
@@ -15227,7 +15288,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare function removePatch(prototype: object, fieldName: string, prefixOrPostfix: Prefix | Postfix): void;
 
      /**
-      * [Renderer](https://engine.needle.tools/docs/api/Renderer) controls rendering properties of meshes including materials,
+      * The [Renderer](https://engine.needle.tools/docs/api/Renderer) component controls rendering properties of meshes including materials,
       * lightmaps, reflection probes, and GPU instancing.
       *
       * **Materials:**
@@ -15239,9 +15300,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * Use `Renderer.setInstanced(obj, true)` or `enableInstancing` property.
       *
       * **Lightmaps:**
-      * Baked lighting is automatically applied when exported from Unity.
+      * Baked lighting is automatically applied when exported from Unity or Blender.
       * Access via the associated {@link RendererLightmap} component.
       *
+      * [![](https://cloud.needle.tools/-/media/Vk944XVswtPEuxlNPLMxPQ.gif)](https://engine.needle.tools/samples/multiple-lightmaps/)
+      *
       * **Debug options:**
       * - `?debugrenderer` - Log renderer info
       * - `?wireframe` - Show wireframe rendering
@@ -15262,7 +15325,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @group Components
       * @see {@link ReflectionProbe} for environment reflections
       * @see {@link Light} for scene lighting
-      * @see {@link LODGroup} for level of detail
       */
      export declare class Renderer extends Component implements IRenderer {
          /** Enable or disable instancing for an object. This will create a Renderer component if it does not exist yet.
@@ -15514,15 +15576,67 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * A Rigidbody is used together with a Collider to create physical interactions between objects in the scene.
+      * Rigidbody component for realistic physics simulation and dynamic interactions.
+      * Used together with a {@link Collider} to enable physical behavior like gravity, collisions,
+      * forces, and constraints. Powered by the Rapier physics engine.
       *
-      * - Example: https://samples.needle.tools/physics-basic
-      * - Example: https://samples.needle.tools/physics-playground
-      * - Example: https://samples.needle.tools/physics-&-animation
+      * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
       *
-      * @summary Rigidbody for physical interactions
+      * **Key features:**
+      * - Dynamic, kinematic, or static body types
+      * - Automatic or manual mass calculation
+      * - Gravity, drag, and angular drag control
+      * - Position and rotation constraints (locking axes)
+      * - Force, impulse, and velocity manipulation
+      * - Sleep/wake optimization for performance
+      * - Continuous collision detection (CCD) support
+      *
+      * @example Basic dynamic rigidbody
+      * ```ts
+      * const rb = this.gameObject.getComponent(Rigidbody);
+      * rb.useGravity = true;
+      * rb.mass = 2.0;
+      * rb.drag = 0.5;
+      * ```
+      *
+      * @example Apply force to move object
+      * ```ts
+      * const rb = this.gameObject.getComponent(Rigidbody);
+      * rb.applyForce(new Vector3(0, 10, 0)); // Upward force
+      * rb.applyImpulse(new Vector3(5, 0, 0)); // Instant velocity change
+      * ```
+      *
+      * @example Kinematic rigidbody (manually controlled)
+      * ```ts
+      * const rb = this.gameObject.getComponent(Rigidbody);
+      * rb.isKinematic = true; // Not affected by forces
+      * rb.teleport({ x: 0, y: 5, z: 0 }); // Move without physics
+      * ```
+      *
+      * @example Lock rotation on Y axis (useful for characters)
+      * ```ts
+      * const rb = this.gameObject.getComponent(Rigidbody);
+      * rb.lockRotationY = true;
+      * // Or use constraints for multiple axes:
+      * rb.constraints = RigidbodyConstraints.FreezeRotationY | RigidbodyConstraints.FreezePositionZ;
+      * ```
+      *
+      * @summary Enables physics simulation with forces, gravity, and collisions
       * @category Physics
       * @group Components
+      * @see {@link BoxCollider} for box-shaped colliders
+      * @see {@link SphereCollider} for sphere-shaped colliders
+      * @see {@link CapsuleCollider} for capsule-shaped colliders
+      * @see {@link MeshCollider} for mesh-based colliders
+      * @see {@link Collider} for collider base class
+      * @see {@link CharacterController} for character movement
+      * @see {@link Joint} for connecting bodies
+      * @see {@link RapierPhysics} for physics engine implementation
+      * @see {@link Physics} for raycasting and physics utilities
+      * @link https://engine.needle.tools/samples/physics-basic/
+      * @link https://engine.needle.tools/samples/physics-playground/
+      * @link https://engine.needle.tools/samples/physics-&-animation/
+      * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies
       */
      export declare class Rigidbody extends Component implements IRigidbody {
          get isRigidbody(): boolean;
@@ -16072,6 +16186,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * @summary Share screen, camera or microphone in a networked room
       * @category Networking
+      * @category Multimedia
       * @group Components
       * @see {@link VideoPlayer} for displaying the received stream
       * @see {@link Voip} for voice-only communication
@@ -16220,40 +16335,179 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * const dataUrl = screenshot();
       * saveImage(dataUrl, "screenshot.png");
       * ```
+      *
       */
      export declare function screenshot(context?: Context, width?: number, height?: number, mimeType?: ScreenshotImageMimeType, camera?: Camera_2 | null): string | null;
 
      /**
-      * Take a screenshot from the current scene and return a {@link Texture}. This can applied to a surface in 3D space.
+      * Take a screenshot from the current scene and return a {@link Texture}. This can be applied to a surface in 3D space.
       * @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.
       * @returns The texture of the screenshot. Returns null if the screenshot could not be taken.
+      * @category Utilities
+      * @example
+      * ```ts
+      * // Create a texture from the current view
+      * const screenshotTexture = screenshot2({ type: "texture", width: 512, height: 512 });
+      * if (screenshotTexture) {
+      *   myMaterial.map = screenshotTexture;
+      *   myMaterial.needsUpdate = true;
+      * }
+      *
+      * // Update an existing texture
+      * const existingTexture = new Texture();
+      * screenshot2({ type: "texture", target: existingTexture, transparent: true });
+      * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsTexture): Texture | null;
 
      /**
-      * Take a screenshot from the current scene.
-      * @param opts
-      * @returns The data url of the screenshot. Returns null if the screenshot could not be taken.
+      * Take a screenshot from the current scene and return a data URL string.
+      *
+      * @param opts Screenshot options. All properties are optional.
+      * @returns The data URL of the screenshot (e.g., "data:image/png;base64,..."). Returns null if the screenshot could not be taken.
+      * @category Utilities
+      *
+      * @example Basic screenshot
       * ```ts
-      * const res = screenshot2({
-      *    width: 1024,
+      * // Take a simple screenshot with default settings
+      * const dataUrl = screenshot2({});
+      * console.log(dataUrl); // "data:image/webp;base64,..."
+      * ```
+      *
+      * @example High-resolution screenshot with transparent background
+      * ```ts
+      * const dataUrl = screenshot2({
+      *   width: 2048,
+      *   height: 2048,
+      *   mimeType: "image/png",
+      *   transparent: true,
+      *   trim: true, // Remove transparent edges
+      * });
+      * ```
+      *
+      * @example Screenshot with custom background color
+      * ```ts
+      * import { Color } from "three";
+      *
+      * const dataUrl = screenshot2({
+      *   width: 1024,
       *   height: 1024,
-      *  mimeType: "image/webp",
-      * transparent: true,
-      * })
-      * // use saveImage to download the image
-      * saveImage(res, "screenshot.webp");
+      *   background: new Color(0x00ff00), // Green background
+      * });
+      * ```
+      *
+      * @example Download screenshot automatically
+      * ```ts
+      * screenshot2({
+      *   width: 1920,
+      *   height: 1080,
+      *   mimeType: "image/jpeg",
+      *   download_filename: "my-scene.jpg",
+      * });
+      * ```
+      *
+      * @example Manual download using saveImage
+      * ```ts
+      * const dataUrl = screenshot2({
+      *   width: 1024,
+      *   height: 1024,
+      *   mimeType: "image/webp",
+      *   transparent: true,
+      * });
+      * if (dataUrl) {
+      *   saveImage(dataUrl, "screenshot.webp");
+      * }
+      * ```
+      *
+      * @example Screenshot from specific camera
+      * ```ts
+      * const myCamera = this.gameObject.getComponent(Camera);
+      * const dataUrl = screenshot2({
+      *   camera: myCamera,
+      *   width: 1024,
+      *   height: 1024,
+      * });
       * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsDataUrl): string | null;
 
      /**
-      * Take a screenshot asynchronously from the current scene.
-      * @returns A promise that resolves with the blob of the screenshot. Returns null if the screenshot could not be taken.
-      * @param {ScreenshotOptionsBlob} opts Set `{ type: "blob" }` to get a blob instead of a data url.
+      * Take a screenshot asynchronously and return a Blob. This is useful when you need to process or upload the image data.
+      *
+      * @param opts Set `{ type: "blob" }` to get a blob instead of a data url. All other {@link ScreenshotOptions} are also available.
+      * @returns A Promise that resolves with the Blob of the screenshot. Returns null if the screenshot could not be taken.
+      * @category Utilities
+      *
+      * @example Upload screenshot to server
+      * ```ts
+      * const blob = await screenshot2({ type: "blob", mimeType: "image/png" });
+      * if (blob) {
+      *   const formData = new FormData();
+      *   formData.append("screenshot", blob, "screenshot.png");
+      *   await fetch("/api/upload", { method: "POST", body: formData });
+      * }
+      * ```
+      *
+      * @example Save blob to file (browser download)
+      * ```ts
+      * const blob = await screenshot2({
+      *   type: "blob",
+      *   width: 1920,
+      *   height: 1080,
+      *   transparent: true
+      * });
+      * if (blob) {
+      *   const url = URL.createObjectURL(blob);
+      *   saveImage(url, "screenshot.png");
+      *   URL.revokeObjectURL(url); // Clean up
+      * }
+      * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsBlob): Promise<Blob | null>;
 
+     /**
+      * Take a screenshot and share it using the Web Share API (mobile-friendly).
+      *
+      * **Note**: The Web Share API is only available in secure contexts (HTTPS) and may not be supported on all platforms/browsers.
+      *
+      * @param opts Set `{ type: "share" }` to share the screenshot. Additional options like `filename`, `title`, `text`, and `url` can be provided.
+      * @returns A Promise that resolves with an object containing the blob and whether it was successfully shared.
+      * @category Utilities
+      *
+      * @example Share screenshot on mobile
+      * ```ts
+      * const result = await screenshot2({
+      *   type: "share",
+      *   filename: "my-creation.png",
+      *   title: "Check out my 3D scene!",
+      *   text: "I created this with Needle Engine",
+      *   url: "https://engine.needle.tools",
+      *   mimeType: "image/png",
+      * });
+      *
+      * if (result.shared) {
+      *   console.log("Screenshot shared successfully!");
+      * } else {
+      *   console.log("User cancelled or sharing not supported");
+      * }
+      * ```
+      *
+      * @example Share with fallback
+      * ```ts
+      * const result = await screenshot2({
+      *   type: "share",
+      *   filename: "screenshot.webp",
+      *   file_type: "image/webp",
+      * });
+      *
+      * if (!result.shared && result.blob) {
+      *   // Fallback: download the image instead
+      *   const url = URL.createObjectURL(result.blob);
+      *   saveImage(url, "screenshot.webp");
+      *   URL.revokeObjectURL(url);
+      * }
+      * ```
+      */
      export declare function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOptionsShareReturnType>;
 
      declare type ScreenshotImageMimeType = "image/webp" | "image/png" | "image/jpeg";
@@ -16315,11 +16569,29 @@ export declare class OrbitControls extends Component implements ICameraControlle
      };
 
      export declare type ScreenshotOptionsShare = ScreenshotOptions & {
+         /**
+          * Set `{ type: "share" }` to share the screenshot using the Web Share API. The promise will resolve with the blob of the screenshot and whether it was shared successfully or not. Note that the Web Share API is only available in secure contexts (HTTPS) and on some platforms.
+          */
          type: "share";
+         /**
+          * The filename to use when sharing the screenshot. If not provided, a default filename will be used.
+          */
          filename?: string;
+         /**
+          * The mime type of the shared file. If not provided, the mime type will be inferred from the screenshot options or default to "image/png".
+          */
          file_type?: ScreenshotImageMimeType;
+         /**
+          * The title to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          title?: string;
+         /**
+          * The text to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          text?: string;
+         /**
+          * The URL to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          url?: string;
      };
 
@@ -16461,6 +16733,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * @summary Links scroll position to target objects
       * @category Web
+      * @category Interaction
       * @group Components
       * @component
       */
@@ -16543,23 +16816,89 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * @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 declare type ScrollMarkerModel = MarkerModel & {
          name?: string;
      };
 
      /**
-      * Makes the object fade out when it is obscuring the reference point from the camera. This component can be put on any object in the scene. It will affect all Renderer components on the same object and child objects.
+      * Automatically fades objects to transparent when they obscure a reference point from the camera's view.
+      * Perfect for architectural visualization, third-person games, or any scenario where objects should
+      * become see-through when blocking the view of important content.
+      *
+      * [![](https://cloud.needle.tools/-/media/1gbMOJLgTlXOug_g6xeKfg.gif)](https://engine.needle.tools/samples/see-through)
+      *
+      * **How it works:**
+      * - Monitors the angle between the camera, this object, and a reference point
+      * - When the object blocks the view to the reference point, it fades out
+      * - Automatically affects all {@link Renderer} components on this object and children
+      * - Supports both transparent fading and alpha hash (dithered) fading
       *
-      * Useful for e.g. making walls transparent when the camera is outside or hiding object's that would otherwise block the view.
+      * **Key Features:**
+      * - Smooth fade transitions with configurable duration
+      * - Optional alpha hash for maintaining opaque rendering (better performance)
+      * - Automatic or manual update modes
+      * - Disables raycasting when faded (objects become click-through)
+      * - Preserves original material properties when re-enabled
+      *
+      * **Configuration:**
+      * - `referencePoint` - Object to keep visible (defaults to scene root)
+      * - `fadeDuration` - Transition speed (default: 0.05 seconds)
+      * - `minAlpha` - Minimum opacity when faded (default: 0 = fully transparent)
+      * - `useAlphaHash` - Use dithered transparency instead of true transparency (default: true)
+      *
+      * **Performance:**
+      * - Materials are cloned once per renderer to avoid affecting shared materials
+      * - Updates direction calculation every 20 frames by default (configurable via `autoUpdate`)
+      * - Use `needsUpdate = true` to force immediate recalculation
+      *
+      * **Requirements:**
+      * Requires at least one {@link Renderer} component on the same object or child objects.
       *
-      * Requires a Renderer component on the same object or a child object.
+      * @example Make walls transparent when blocking view
+      * ```ts
+      * // Add to walls or obstacles
+      * const seeThrough = wall.addComponent(SeeThrough);
+      * seeThrough.referencePoint = player; // Keep player visible
+      * seeThrough.fadeDuration = 0.2; // Smooth fade
+      * seeThrough.minAlpha = 0.2; // Slightly visible when faded
+      * ```
+      *
+      * @example Third-person camera with see-through objects
+      * ```ts
+      * const character = GameObject.findByName("Character");
+      * const obstacles = GameObject.findByTag("Obstacle");
+      *
+      * for (const obstacle of obstacles) {
+      *   const st = obstacle.addComponent(SeeThrough);
+      *   st.referencePoint = character;
+      *   st.useAlphaHash = true; // Better performance
+      * }
+      * ```
+      *
+      * @example Manual control of see-through effect
+      * ```ts
+      * const seeThrough = this.gameObject.getComponent(SeeThrough);
+      * if (seeThrough) {
+      *   seeThrough.autoUpdate = false; // Disable automatic fading
       *
-      * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
+      *   // Manually control transparency
+      *   seeThrough.updateAlpha(0.5, 0.3); // Fade to 50% over 0.3 seconds
       *
-      * @summary Makes objects fade out when obscuring a reference point from the camera
+      *   // Or use override for precise control
+      *   seeThrough.overrideAlpha = 0.8; // Force 80% opacity
+      * }
+      * ```
+      *
+      * @summary Fades objects when they obscure the camera's view of a reference point
       * @category Rendering
       * @group Components
+      * @see {@link Renderer} for material/rendering control (required)
+      * @see {@link Camera} for camera setup and configuration
+      * @see {@link OrbitControls} for camera controls in similar use cases
+      * @link https://see-through-walls-z23hmxbz1kjfjn.needle.run/ for live demo
+      * @link https://engine.needle.tools/samples/see-through for sample project
       */
      export declare class SeeThrough extends Component {
          /**
@@ -16821,14 +17160,66 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.
-      * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.
+      * ShadowCatcher renders real-time shadows cast by lights onto a mesh surface.
+      * Captures actual shadow data from the scene's lighting system (directional lights, point lights, spot lights).
+      *
+      * If the GameObject is a Mesh, it applies a shadow-catching material to it.
+      * Otherwise, it creates a quad mesh with the shadow-catching material automatically.
+      *
+      * [![](https://cloud.needle.tools/-/media/pFXPchA4vynNKOjgG_KucQ.gif)](https://engine.needle.tools/samples/shadow-catcher/)
+      * *Additive ShadowCatcher mode with point light shadows*
+      *
+      * [![](https://cloud.needle.tools/-/media/oIWgEU49rEA0xJ2TrbzVlg.gif)](https://engine.needle.tools/samples/transmission/)
+      * *ShadowCatcher with directional light shadows*
+      *
+      * **Shadow Modes:**
+      * - `ShadowMask` - Only renders shadows (works best with directional lights)
+      * - `Additive` - Renders light additively (works best with point/spot lights)
+      * - `Occluder` - Occludes light without rendering shadows
+      *
+      * **ShadowCatcher vs ContactShadows:**
+      * - **ShadowCatcher**: Real-time shadows from actual lights. Accurate directional shadows that match light sources. Requires lights with shadows enabled. Updates every frame.
+      * - **{@link ContactShadows}**: Proximity-based ambient occlusion-style shadows. Extremely soft and diffuse, ideal for subtle grounding. Better performance, works without lights.
+      *
+      * **When to use ShadowCatcher:**
+      * - You need accurate shadows that match specific light directions
+      * - Scene has real-time lighting with shadow-casting lights
+      * - Shadows need to follow light attenuation and angles
+      * - AR/VR scenarios where light estimation is available
+      * - Hard or semi-hard shadow edges are desired
       *
-      * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
+      * **When to use ContactShadows instead:**
+      * - You want very soft, ambient occlusion-style ground shadows
+      * - Performance is critical (no per-frame shadow rendering)
+      * - Scene doesn't have shadow-casting lights
+      * - Product visualization or configurators (subtle grounding effect)
+      * - Soft, diffuse shadows are more visually appealing than accurate ones
       *
-      * @summary Creates a shadow mask or a light occluder
+      * **Note:** ShadowCatcher meshes are not raycastable by default (layer 2). Change layers in `onEnable()` if raycasting is needed.
+      *
+      * @example Basic shadow catcher plane
+      * ```ts
+      * const plane = new Object3D();
+      * const catcher = addComponent(plane, ShadowCatcher);
+      * catcher.mode = ShadowMode.ShadowMask;
+      * catcher.shadowColor = new RGBAColor(0, 0, 0, 0.8);
+      * ```
+      *
+      * @example Apply to existing mesh
+      * ```ts
+      * const mesh = this.gameObject.getComponent(Mesh);
+      * const catcher = addComponent(mesh, ShadowCatcher);
+      * // The mesh will now catch shadows from scene lights
+      * ```
+      *
+      * @summary Renders real-time shadows from lights onto surfaces
       * @category Rendering
       * @group Components
+      * @see {@link ContactShadows} for proximity-based fake shadows (better performance)
+      * @see {@link Light} for shadow-casting light configuration
+      * @see {@link Renderer} for shadow receiving settings
+      * @link https://engine.needle.tools/samples/shadow-catcher/
+      * @link https://engine.needle.tools/samples/transmission/
       */
      export declare class ShadowCatcher extends Component {
          mode: ShadowMode;
@@ -16982,6 +17373,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * @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;
@@ -18975,6 +19367,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * @category Animation and Sequencing
+      * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
       */
      export declare type TimelineAssetModel = {
          name: string;
@@ -19031,6 +19424,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * @category Animation and Sequencing
+      * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
       */
      export declare type TrackModel = {
          name: string;
@@ -19045,6 +19439,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * @category Animation and Sequencing
+      * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
       */
      export declare type TrackOffset = {
          position: Vec3_3 | Vector3;
@@ -19064,6 +19459,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * @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 declare enum TrackType {
          Activation = "ActivationTrack",
@@ -19901,7 +20298,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * - Media streams (from webcam, screen capture, etc.)
       * - HLS playlists (m3u8) for livestreaming
       *
-      * ![](https://cloud.needle.tools/-/media/w1uHur5yu3Ni7qFaKIFX-g.gif)
+      * [![](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.
@@ -20548,11 +20945,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**
       * WebARCameraBackground is a component that allows to display the camera feed as a background in an AR session to more easily blend the real world with the virtual world or applying effects to the camera feed.
       *
+      * This component automatically requests `camera-access` permission when entering AR mode, which is required to:
+      * - Display the real-world camera feed as a background
+      * - Include the camera feed in AR screenshots taken with {@link screenshot2}
+      *
+      * **Note**: If you want to take AR screenshots with the camera feed but don't need to display it as a background,
+      * you can still add this component to your scene (it will request camera access) or manually request the
+      * `camera-access` feature in your `onBeforeXR` method.
+      *
       * - Example: https://samples.needle.tools/ar-camera-background
       *
       * @summary Displays the camera feed as background in WebAR sessions
       * @category XR
       * @group Components
+      * @see {@link screenshot2} for taking screenshots in AR (requires camera access for camera feed compositing)
       */
      export declare class WebARCameraBackground extends Component {
          /* Excluded from this release type: onBeforeXR */
@@ -20711,6 +21117,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @see {@link XRControllerMovement} for VR locomotion
       * @see {@link WebARSessionRoot} for AR session configuration
       * @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
       * @link https://engine.needle.tools/samples/?overlay=samples&tag=xr
       * @link https://engine.needle.tools/samples/collaborative-sandbox