angular-three-theatre 4.0.0-next.116 → 4.0.0-next.118

package/fesm2022/angular-three-theatre.mjs

@@ -7,11 +7,45 @@ import { Group } from 'three';
 import { NgtsTransformControls } from 'angular-three-soba/gizmos';
 import { mergeInputs } from 'ngxtension/inject-inputs';
 
+/**
+ * Component that creates and manages a Theatre.js project.
+ *
+ * A Theatre.js project is the top-level container for all animation data.
+ * It contains sheets, which in turn contain sheet objects that hold animatable properties.
+ *
+ * @example
+ * ```html
+ * <theatre-project name="my-animation" [config]="{ state: savedState }">
+ *   <ng-container sheet="scene1">
+ *     <!-- sheet objects here -->
+ *   </ng-container>
+ * </theatre-project>
+ * ```
+ */
 class TheatreProject {
     constructor() {
+        /**
+         * The name of the Theatre.js project.
+         * This name is used to identify the project and must be unique.
+         *
+         * @default 'default-theatre-project'
+         */
         this.name = input('default-theatre-project', ...(ngDevMode ? [{ debugName: "name" }] : []));
+        /**
+         * Configuration options for the Theatre.js project.
+         * Can include saved state data for restoring animations.
+         *
+         * @default {}
+         */
         this.config = input({}, ...(ngDevMode ? [{ debugName: "config" }] : []));
+        /**
+         * Computed signal containing the Theatre.js project instance.
+         */
         this.project = computed(() => getProject(this.name(), this.config()), ...(ngDevMode ? [{ debugName: "project" }] : []));
+        /**
+         * Internal registry of sheets created within this project.
+         * Tracks sheet instances and their reference counts for cleanup.
+         */
         this.sheets = {};
         effect(() => {
             const project = this.project();
@@ -34,8 +68,40 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
                 }]
         }], ctorParameters: () => [], propDecorators: { name: [{ type: i0.Input, args: [{ isSignal: true, alias: "name", required: false }] }], config: [{ type: i0.Input, args: [{ isSignal: true, alias: "config", required: false }] }] } });
 
+/**
+ * Directive that creates and manages a Theatre.js sheet within a project.
+ *
+ * A sheet is a container for sheet objects and their animations. Multiple sheets
+ * can exist within a project, allowing you to organize animations into logical groups.
+ *
+ * The directive automatically handles reference counting and cleanup when the
+ * directive is destroyed.
+ *
+ * @example
+ * ```html
+ * <theatre-project>
+ *   <ng-container sheet="mainScene">
+ *     <!-- sheet objects here -->
+ *   </ng-container>
+ * </theatre-project>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Using with template reference -->
+ * <ng-container sheet="mySheet" #sheetRef="sheet">
+ *   {{ sheetRef.sheet().sequence.position }}
+ * </ng-container>
+ * ```
+ */
 let TheatreSheet$1 = class TheatreSheet {
     constructor() {
+        /**
+         * The name of the sheet within the project.
+         * This name must be unique within the parent project.
+         *
+         * @default 'default-theatre-sheet'
+         */
         this.name = input('default-theatre-sheet', { ...(ngDevMode ? { debugName: "name" } : {}), transform: (value) => {
                 if (value === '')
                     return 'default-theatre-sheet';
@@ -43,6 +109,11 @@ let TheatreSheet$1 = class TheatreSheet {
             },
             alias: 'sheet' });
         this.project = inject(TheatreProject);
+        /**
+         * Computed signal containing the Theatre.js sheet instance.
+         * Returns an existing sheet if one with the same name already exists,
+         * otherwise creates a new sheet.
+         */
         this.sheet = computed(() => {
             const name = this.name();
             const existing = this.project.sheets[name] || [];
@@ -74,13 +145,90 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
             args: [{ selector: '[sheet]', exportAs: 'sheet' }]
         }], ctorParameters: () => [], propDecorators: { name: [{ type: i0.Input, args: [{ isSignal: true, alias: "sheet", required: false }] }] } });
 
+/**
+ * Injection token for accessing the Theatre.js Studio instance.
+ *
+ * The studio provides a visual editor for creating and editing animations.
+ * This token is provided by the TheatreStudio directive and can be injected
+ * into child components.
+ *
+ * @example
+ * ```typescript
+ * import { THEATRE_STUDIO } from 'angular-three-theatre';
+ *
+ * @Component({...})
+ * export class MyComponent {
+ *   private studio = inject(THEATRE_STUDIO, { optional: true });
+ *
+ *   selectObject() {
+ *     this.studio()?.setSelection([mySheetObject]);
+ *   }
+ * }
+ * ```
+ */
 const THEATRE_STUDIO = new InjectionToken('Theatre Studio');
 
+/**
+ * Directive that creates a Theatre.js sheet object for animating properties.
+ *
+ * A sheet object is a container for animatable properties within a sheet.
+ * This directive must be applied to an `ng-template` element and provides
+ * a structural context with access to the sheet object and its values.
+ *
+ * The template context includes:
+ * - `sheetObject`: The Theatre.js sheet object instance (read-only signal)
+ * - `values`: Current values of all animated properties (read-only signal)
+ * - `select()`: Method to select this object in Theatre.js Studio
+ * - `deselect()`: Method to deselect this object in Theatre.js Studio
+ *
+ * @example
+ * ```html
+ * <ng-template sheetObject="cube" [sheetObjectProps]="{ opacity: 1 }" let-values="values">
+ *   <ngt-mesh>
+ *     <ngt-mesh-standard-material [opacity]="values().opacity" />
+ *   </ngt-mesh>
+ * </ng-template>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- With selection support -->
+ * <ng-template
+ *   sheetObject="cube"
+ *   [(sheetObjectSelected)]="isSelected"
+ *   let-select="select"
+ *   let-deselect="deselect"
+ * >
+ *   <ngt-mesh (click)="select()" />
+ * </ng-template>
+ * ```
+ */
 let TheatreSheetObject$1 = class TheatreSheetObject {
     constructor() {
+        /**
+         * Unique key identifying this sheet object within its parent sheet.
+         * This key is used by Theatre.js to track and persist animation data.
+         */
         this.key = input.required({ ...(ngDevMode ? { debugName: "key" } : {}), alias: 'sheetObject' });
+        /**
+         * Initial properties and their default values for this sheet object.
+         * These properties will be animatable in Theatre.js Studio.
+         *
+         * @default {}
+         */
         this.props = input({}, { ...(ngDevMode ? { debugName: "props" } : {}), alias: 'sheetObjectProps' });
+        /**
+         * Whether to detach (remove) the sheet object when this directive is destroyed.
+         * When true, the animation data for this object will be removed from the sheet.
+         *
+         * @default false
+         */
         this.detach = input(false, { ...(ngDevMode ? { debugName: "detach" } : {}), transform: booleanAttribute, alias: 'sheetObjectDetach' });
+        /**
+         * Two-way bindable signal indicating whether this object is selected in Theatre.js Studio.
+         *
+         * @default false
+         */
         this.selected = model(false, { ...(ngDevMode ? { debugName: "selected" } : {}), alias: 'sheetObjectSelected' });
         this.templateRef = inject(TemplateRef);
         this.vcr = inject(ViewContainerRef);
@@ -91,7 +239,15 @@ let TheatreSheetObject$1 = class TheatreSheetObject {
             const sheet = this.sheet.sheet();
             return sheet.object(this.key(), untracked(this.props), { reconfigure: true });
         }, ...(ngDevMode ? [{ debugName: "originalSheetObject" }] : []));
+        /**
+         * Signal containing the Theatre.js sheet object instance.
+         * This is a linked signal that updates when the sheet or key changes.
+         */
         this.sheetObject = linkedSignal(this.originalSheetObject, ...(ngDevMode ? [{ debugName: "sheetObject" }] : []));
+        /**
+         * Signal containing the current values of all animated properties.
+         * Updates automatically when Theatre.js values change.
+         */
         this.values = linkedSignal(() => this.sheetObject().value, ...(ngDevMode ? [{ debugName: "values" }] : []));
         this.detached = false;
         this.aggregatedProps = {};
@@ -135,6 +291,10 @@ let TheatreSheetObject$1 = class TheatreSheetObject {
             }
         });
     }
+    /**
+     * Updates the sheet object with the current aggregated props.
+     * Detaches the existing object and creates a new one with reconfigured properties.
+     */
     update() {
         if (this.detached)
             return;
@@ -142,10 +302,22 @@ let TheatreSheetObject$1 = class TheatreSheetObject {
         sheet.detachObject(key);
         this.sheetObject.set(sheet.object(key, this.aggregatedProps, { reconfigure: true }));
     }
+    /**
+     * Adds new properties to the sheet object.
+     * The properties are merged with existing properties and the object is reconfigured.
+     *
+     * @param props - Properties to add to the sheet object
+     */
     addProps(props) {
         this.aggregatedProps = { ...this.aggregatedProps, ...props };
         this.update();
     }
+    /**
+     * Removes properties from the sheet object.
+     * If all properties are removed and `detach` is true, the object is detached from the sheet.
+     *
+     * @param props - Array of property names to remove
+     */
     removeProps(props) {
         const [detach, sheet, key] = [untracked(this.detach), untracked(this.sheet.sheet), untracked(this.key)];
         // remove props from sheet object
@@ -164,12 +336,20 @@ let TheatreSheetObject$1 = class TheatreSheetObject {
             this.update();
         }
     }
+    /**
+     * Selects this sheet object in Theatre.js Studio.
+     * Only works when the studio is available.
+     */
     select() {
         const studio = this.studio?.();
         if (!studio)
             return;
         studio.setSelection([this.sheetObject()]);
     }
+    /**
+     * Deselects this sheet object in Theatre.js Studio.
+     * Only deselects if this object is currently selected.
+     */
     deselect() {
         const studio = this.studio?.();
         if (!studio)
@@ -178,6 +358,14 @@ let TheatreSheetObject$1 = class TheatreSheetObject {
             studio.setSelection([]);
         }
     }
+    /**
+     * Type guard for the template context.
+     * Provides type safety for the template variables exposed by this directive.
+     *
+     * @param _ - The directive instance
+     * @param ctx - The template context
+     * @returns Type predicate for the template context
+     */
     static ngTemplateContextGuard(_, ctx) {
         return true;
     }
@@ -189,11 +377,45 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
             args: [{ selector: 'ng-template[sheetObject]', exportAs: 'sheetObject' }]
         }], ctorParameters: () => [], propDecorators: { key: [{ type: i0.Input, args: [{ isSignal: true, alias: "sheetObject", required: true }] }], props: [{ type: i0.Input, args: [{ isSignal: true, alias: "sheetObjectProps", required: false }] }], detach: [{ type: i0.Input, args: [{ isSignal: true, alias: "sheetObjectDetach", required: false }] }], selected: [{ type: i0.Input, args: [{ isSignal: true, alias: "sheetObjectSelected", required: false }] }, { type: i0.Output, args: ["sheetObjectSelectedChange"] }] } });
 
+/**
+ * Factory function for creating a Theatre.js transformer.
+ *
+ * This is a convenience function that provides type inference for transformer creation.
+ *
+ * @param transformer - The transformer configuration object
+ * @returns The same transformer object (identity function with type inference)
+ *
+ * @example
+ * ```typescript
+ * import { createTransformer } from 'angular-three-theatre';
+ * import { types } from '@theatre/core';
+ *
+ * export const percentage = createTransformer({
+ *   transform: (value) => types.number(value * 100, { range: [0, 100] }),
+ *   apply: (target, property, value) => { target[property] = value / 100; }
+ * });
+ * ```
+ */
 function createTransformer(transformer) {
     return transformer;
 }
 
 const _color = new THREE.Color();
+/**
+ * Transformer for Three.js Color objects.
+ *
+ * Converts Three.js Color to Theatre.js RGBA format for the color picker UI.
+ * Uses sRGB color space for accurate color representation.
+ *
+ * @example
+ * ```typescript
+ * import { color } from 'angular-three-theatre';
+ *
+ * // Used automatically for Color properties, or manually:
+ * [sync]="material"
+ * [syncProps]="[['emissive', { transformer: color }]]"
+ * ```
+ */
 const color = createTransformer({
     transform(value) {
         value.getRGB(_color, THREE.SRGBColorSpace);
@@ -204,6 +426,21 @@ const color = createTransformer({
     },
 });
 
+/**
+ * Transformer for radian values that displays as degrees in the UI.
+ *
+ * Converts between radians (used by Three.js) and degrees (more intuitive for users).
+ * Used automatically for rotation.x, rotation.y, and rotation.z properties.
+ *
+ * @example
+ * ```typescript
+ * import { degrees } from 'angular-three-theatre';
+ *
+ * // Used automatically for rotation components, or manually:
+ * [sync]="camera"
+ * [syncProps]="[['fov', { transformer: degrees }]]"
+ * ```
+ */
 const degrees = createTransformer({
     transform(target) {
         return types.number(target * THREE.MathUtils.RAD2DEG);
@@ -213,6 +450,23 @@ const degrees = createTransformer({
     },
 });
 
+/**
+ * Transformer for Three.js Euler rotation objects.
+ *
+ * Converts Euler angles from radians to degrees for display in Theatre.js Studio.
+ * Creates a compound property with x, y, z components shown in degrees.
+ *
+ * Used automatically for properties where `isEuler` is true (e.g., Object3D.rotation).
+ *
+ * @example
+ * ```typescript
+ * import { euler } from 'angular-three-theatre';
+ *
+ * // Used automatically for Euler properties, or manually:
+ * [sync]="mesh"
+ * [syncProps]="[['rotation', { transformer: euler }]]"
+ * ```
+ */
 const euler = createTransformer({
     transform(value) {
         return types.compound({
@@ -228,6 +482,26 @@ const euler = createTransformer({
     },
 });
 
+/**
+ * Generic fallback transformer that handles common JavaScript types.
+ *
+ * Automatically detects the value type and applies the appropriate Theatre.js type:
+ * - Numbers → `types.number` (Infinity converted to MAX_VALUE)
+ * - Strings → `types.string`
+ * - Booleans → `types.boolean`
+ * - Objects → `types.compound` (spreads properties)
+ *
+ * Used as the default transformer when no specific transformer matches.
+ *
+ * @example
+ * ```typescript
+ * import { generic } from 'angular-three-theatre';
+ *
+ * // Explicitly use generic transformer:
+ * [sync]="mesh"
+ * [syncProps]="[['customProperty', { transformer: generic }]]"
+ * ```
+ */
 const generic = createTransformer({
     transform(value) {
         if (typeof value === 'number') {
@@ -251,6 +525,22 @@ const generic = createTransformer({
     },
 });
 
+/**
+ * Transformer for normalized values in the 0-1 range.
+ *
+ * Creates a number input with a slider constrained to the 0-1 range.
+ * Used automatically for material properties like opacity, roughness,
+ * metalness, transmission, and color components (r, g, b).
+ *
+ * @example
+ * ```typescript
+ * import { normalized } from 'angular-three-theatre';
+ *
+ * // Used automatically for common properties, or manually:
+ * [sync]="material"
+ * [syncProps]="[['customNormalizedValue', { transformer: normalized }]]"
+ * ```
+ */
 const normalized = createTransformer({
     transform(value) {
         return types.number(value, { range: [0, 1] });
@@ -260,6 +550,23 @@ const normalized = createTransformer({
     },
 });
 
+/**
+ * Transformer for Three.js material side property.
+ *
+ * Converts between Three.js side constants (FrontSide, BackSide, DoubleSide)
+ * and a switch UI in Theatre.js Studio with human-readable labels.
+ *
+ * Used automatically for the `side` property on materials.
+ *
+ * @example
+ * ```typescript
+ * import { side } from 'angular-three-theatre';
+ *
+ * // Used automatically for material.side, or manually:
+ * [sync]="material"
+ * [syncProps]="[['side', { transformer: side }]]"
+ * ```
+ */
 const side = createTransformer({
     transform(value) {
         // TODO: fix this type
@@ -270,9 +577,42 @@ const side = createTransformer({
     },
 });
 
+/**
+ * Checks if a property path matches a pattern exactly or ends with the pattern.
+ *
+ * @param fullPropertyPath - The full property path (e.g., 'material.opacity')
+ * @param pattern - The pattern to match (e.g., 'opacity')
+ * @returns True if the path matches or ends with the pattern
+ */
 function isFullOrEndingPattern(fullPropertyPath, pattern) {
     return fullPropertyPath.endsWith(`.${pattern}`) || fullPropertyPath === pattern;
 }
+/**
+ * Determines the appropriate transformer for a Three.js property based on its type and path.
+ *
+ * This function automatically selects the best transformer for common Three.js properties:
+ * - Euler rotations → `euler` transformer (degrees display)
+ * - Color values → `color` transformer (RGBA picker)
+ * - Rotation components (x, y, z) → `degrees` transformer
+ * - Color components (r, g, b) → `normalized` transformer (0-1 range)
+ * - Material properties (opacity, roughness, metalness, transmission) → `normalized` transformer
+ * - Side property → `side` transformer (Front/Back/Double switch)
+ * - All others → `generic` transformer
+ *
+ * @param target - The parent object containing the property
+ * @param path - The property name on the target
+ * @param fullPropertyPath - The full dot-notation path to the property
+ * @returns The appropriate transformer for the property
+ *
+ * @example
+ * ```typescript
+ * import { getDefaultTransformer } from 'angular-three-theatre';
+ *
+ * const mesh = new THREE.Mesh();
+ * const transformer = getDefaultTransformer(mesh, 'rotation', 'rotation');
+ * // Returns the euler transformer
+ * ```
+ */
 function getDefaultTransformer(target, path, fullPropertyPath) {
     const property = target[path];
     if (property.isEuler)
@@ -305,11 +645,67 @@ function getDefaultTransformer(target, path, fullPropertyPath) {
 }
 
 const updateProjectionMatrixKeys = ['fov', 'near', 'far', 'zoom', 'left', 'right', 'top', 'bottom', 'aspect'];
+/**
+ * Directive that synchronizes Three.js object properties with Theatre.js animations.
+ *
+ * This directive allows you to expose specific properties of a Three.js object
+ * to Theatre.js for animation. It automatically handles property transformation
+ * (e.g., converting Euler angles to degrees for the UI).
+ *
+ * Must be used within a `TheatreSheetObject` context.
+ *
+ * @example
+ * ```html
+ * <ng-template sheetObject="myMaterial">
+ *   <ngt-mesh-standard-material
+ *     [sync]="material"
+ *     [syncProps]="['opacity', 'roughness', 'metalness']"
+ *     #material
+ *   />
+ * </ng-template>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- With custom property mapping -->
+ * <ng-template sheetObject="myLight">
+ *   <ngt-point-light
+ *     [sync]="light"
+ *     [syncProps]="[
+ *       ['intensity', { label: 'Light Intensity', key: 'lightIntensity' }],
+ *       'color'
+ *     ]"
+ *     #light
+ *   />
+ * </ng-template>
+ * ```
+ *
+ * @typeParam TObject - The type of the Three.js object being synchronized
+ */
 class TheatreSheetObjectSync {
     constructor() {
+        /**
+         * The Three.js object to synchronize with Theatre.js.
+         * Can be an object reference, ElementRef, or a function returning either.
+         */
         this.parent = input.required({ ...(ngDevMode ? { debugName: "parent" } : {}), alias: 'sync' });
+        /**
+         * Array of property paths to synchronize with Theatre.js.
+         *
+         * Each item can be:
+         * - A string property path (e.g., 'opacity', 'position.x')
+         * - A tuple of [propertyPath, keyOrOptions] where options can include:
+         *   - `label`: Display label in Theatre.js Studio
+         *   - `key`: Unique key for the property in Theatre.js
+         *   - `transformer`: Custom transformer for the property value
+         *
+         * @default []
+         */
         this.props = input([], { ...(ngDevMode ? { debugName: "props" } : {}), alias: 'syncProps' });
         this.theatreSheetObject = inject(TheatreSheetObject$1);
+        /**
+         * Computed signal containing the Theatre.js sheet object instance.
+         */
         this.sheetObject = computed(() => this.theatreSheetObject.sheetObject(), ...(ngDevMode ? [{ debugName: "sheetObject" }] : []));
         this.studio = inject(THEATRE_STUDIO, { optional: true });
         this.parentRef = computed(() => {
@@ -389,6 +785,13 @@ class TheatreSheetObjectSync {
             this.theatreSheetObject.removeProps(Object.keys(this.propsMapping));
         });
     }
+    /**
+     * Captures the current values of all synchronized properties from the Three.js object
+     * and commits them to Theatre.js.
+     *
+     * This is useful for "baking" the current state of the Three.js object into the
+     * Theatre.js animation. Requires Theatre.js Studio to be available.
+     */
     capture() {
         const studio = this.studio?.();
         if (!studio)
@@ -414,6 +817,12 @@ class TheatreSheetObjectSync {
         });
         scrub.commit();
     }
+    /**
+     * Converts a property path (e.g., 'position.x') to a safe alphanumeric key.
+     *
+     * @param propPath - The property path to convert
+     * @returns A safe alphanumeric key string
+     */
     resolvePropertyPath(propPath) {
         return (propPath
             // make the label alphanumeric by first removing dots (fundamental feature for pierced props)
@@ -431,6 +840,40 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
             args: [{ selector: '[sync]', exportAs: 'sync' }]
         }], ctorParameters: () => [], propDecorators: { parent: [{ type: i0.Input, args: [{ isSignal: true, alias: "sync", required: true }] }], props: [{ type: i0.Input, args: [{ isSignal: true, alias: "syncProps", required: false }] }] } });
 
+/**
+ * Component that provides transform controls for animating position, rotation, and scale
+ * of child Three.js objects via Theatre.js.
+ *
+ * When the sheet object is selected in Theatre.js Studio, transform controls appear
+ * allowing direct manipulation of the object's transform. Changes are captured and
+ * committed to Theatre.js.
+ *
+ * Must be used within a `TheatreSheetObject` context.
+ *
+ * @example
+ * ```html
+ * <ng-template sheetObject="myCube">
+ *   <theatre-transform>
+ *     <ngt-mesh>
+ *       <ngt-box-geometry />
+ *       <ngt-mesh-standard-material />
+ *     </ngt-mesh>
+ *   </theatre-transform>
+ * </ng-template>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- With custom key and options -->
+ * <ng-template sheetObject="scene">
+ *   <theatre-transform key="cubeTransform" label="Cube" [options]="{ mode: 'rotate' }">
+ *     <ngt-mesh />
+ *   </theatre-transform>
+ * </ng-template>
+ * ```
+ *
+ * @typeParam TLabel - The type of the label string
+ */
 class TheatreSheetObjectTransform {
     onMouseDown() {
         if (!this.studio)
@@ -465,12 +908,31 @@ class TheatreSheetObjectTransform {
         });
     }
     constructor() {
+        /**
+         * Display label for the transform properties in Theatre.js Studio.
+         */
         this.label = input(...(ngDevMode ? [undefined, { debugName: "label" }] : []));
+        /**
+         * Unique key for grouping the transform properties in Theatre.js.
+         * If provided, position/rotation/scale will be nested under this key.
+         */
         this.key = input(...(ngDevMode ? [undefined, { debugName: "key" }] : []));
+        /**
+         * Options for the transform controls gizmo.
+         * Allows configuring the transform mode, snap values, and coordinate space.
+         *
+         * @default {}
+         */
         this.options = input({}, ...(ngDevMode ? [{ debugName: "options" }] : []));
+        /**
+         * Reference to the Three.js Group element that wraps the transformed content.
+         */
         this.groupRef = viewChild.required('group');
         this.controlsRef = viewChild(NgtsTransformControls, ...(ngDevMode ? [{ debugName: "controlsRef" }] : []));
         this.theatreSheetObject = inject(TheatreSheetObject$1);
+        /**
+         * Computed signal containing the Theatre.js sheet object instance.
+         */
         this.sheetObject = computed(() => this.theatreSheetObject.sheetObject(), ...(ngDevMode ? [{ debugName: "sheetObject" }] : []));
         this.studio = inject(THEATRE_STUDIO, { optional: true });
         this.selected = this.theatreSheetObject.selected.asReadonly();
@@ -580,12 +1042,75 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
                 }]
         }], ctorParameters: () => [], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], key: [{ type: i0.Input, args: [{ isSignal: true, alias: "key", required: false }] }], options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: false }] }], groupRef: [{ type: i0.ViewChild, args: ['group', { isSignal: true }] }], controlsRef: [{ type: i0.ViewChild, args: [i0.forwardRef(() => NgtsTransformControls), { isSignal: true }] }] } });
 
+/**
+ * Combined array of sheet object directives for convenient importing.
+ *
+ * Includes:
+ * - `TheatreSheetObject` - Base directive for creating sheet objects
+ * - `TheatreSheetObjectTransform` - Component for animating transform properties
+ * - `TheatreSheetObjectSync` - Directive for syncing arbitrary object properties
+ *
+ * @example
+ * ```typescript
+ * import { TheatreSheetObject } from 'angular-three-theatre';
+ *
+ * @Component({
+ *   imports: [TheatreSheetObject],
+ *   template: `
+ *     <ng-template sheetObject="myObject">
+ *       <theatre-transform>
+ *         <ngt-mesh />
+ *       </theatre-transform>
+ *     </ng-template>
+ *   `
+ * })
+ * export class MyComponent {}
+ * ```
+ */
 const TheatreSheetObject = [TheatreSheetObject$1, TheatreSheetObjectTransform, TheatreSheetObjectSync];
 
+/**
+ * Directive that initializes and manages the Theatre.js Studio.
+ *
+ * Theatre.js Studio is a visual editor that allows you to create and edit
+ * animations directly in the browser. The studio UI is dynamically imported
+ * to avoid including it in production builds.
+ *
+ * This directive must be applied to a `theatre-project` element and provides
+ * the studio instance via the `THEATRE_STUDIO` injection token.
+ *
+ * @example
+ * ```html
+ * <!-- Enable studio (default) -->
+ * <theatre-project studio>
+ *   <ng-container sheet="scene">...</ng-container>
+ * </theatre-project>
+ *
+ * <!-- Conditionally enable/disable studio -->
+ * <theatre-project [studio]="isDevelopment">
+ *   <ng-container sheet="scene">...</ng-container>
+ * </theatre-project>
+ *
+ * <!-- Disable studio -->
+ * <theatre-project [studio]="false">
+ *   <ng-container sheet="scene">...</ng-container>
+ * </theatre-project>
+ * ```
+ */
 class TheatreStudio {
     constructor() {
+        /**
+         * Whether the studio UI should be visible.
+         * When false, the studio UI is hidden but the studio instance remains active.
+         *
+         * @default true
+         */
         this.enabled = input(true, { ...(ngDevMode ? { debugName: "enabled" } : {}), alias: 'studio', transform: booleanAttribute });
         this.Studio = signal(null, ...(ngDevMode ? [{ debugName: "Studio" }] : []));
+        /**
+         * Read-only signal containing the Theatre.js Studio instance.
+         * May be null while the studio is being loaded.
+         */
         this.studio = this.Studio.asReadonly();
         import('@theatre/studio').then((m) => {
             const Studio = 'default' in m.default ? m.default.default : m.default;
@@ -630,12 +1155,65 @@ const defaultOptions = {
     autopause: false,
     delay: 0,
 };
+/**
+ * Directive that provides control over a Theatre.js sequence.
+ *
+ * A sequence controls the playback of animations within a sheet. This directive
+ * provides methods to play, pause, and reset the sequence, as well as reactive
+ * signals for the current position, playing state, and length.
+ *
+ * Must be used on an element that also has the `sheet` directive.
+ *
+ * @example
+ * ```html
+ * <ng-container sheet="scene" [sequence]="{ autoplay: true, rate: 1 }" #seq="sequence">
+ *   <p>Position: {{ seq.position() }}</p>
+ *   <button (click)="seq.play()">Play</button>
+ *   <button (click)="seq.pause()">Pause</button>
+ * </ng-container>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- With audio synchronization -->
+ * <ng-container
+ *   sheet="scene"
+ *   [sequence]="{ autoplay: true }"
+ *   [sequenceAudio]="{ source: '/audio/soundtrack.mp3' }"
+ * />
+ * ```
+ */
 class TheatreSequence {
     constructor() {
+        /**
+         * Sequence configuration options.
+         * Merged with default options using ngxtension's mergeInputs.
+         *
+         * @default { rate: 1, autoplay: false, autopause: false, delay: 0 }
+         */
         this.options = input(defaultOptions, { ...(ngDevMode ? { debugName: "options" } : {}), alias: 'sequence', transform: mergeInputs(defaultOptions) });
+        /**
+         * Audio options for synchronizing playback with an audio file.
+         * When provided, the sequence will be synchronized with the audio.
+         */
         this.audioOptions = input(undefined, { ...(ngDevMode ? { debugName: "audioOptions" } : {}), alias: 'sequenceAudio' });
+        /**
+         * Two-way bindable signal for the current playback position in seconds.
+         *
+         * @default 0
+         */
         this.position = model(0, ...(ngDevMode ? [{ debugName: "position" }] : []));
+        /**
+         * Two-way bindable signal indicating whether the sequence is currently playing.
+         *
+         * @default false
+         */
         this.playing = model(false, ...(ngDevMode ? [{ debugName: "playing" }] : []));
+        /**
+         * Two-way bindable signal for the total length of the sequence in seconds.
+         *
+         * @default 0
+         */
         this.length = model(0, ...(ngDevMode ? [{ debugName: "length" }] : []));
         this.playOptions = omit(this.options, ['autoplay', 'autopause', 'delay', 'autoreset']);
         this.autoplay = pick(this.options, 'autoplay');
@@ -644,6 +1222,9 @@ class TheatreSequence {
         this.delay = pick(this.options, 'delay');
         this.project = inject(TheatreProject);
         this.sheet = inject(TheatreSheet$1, { host: true });
+        /**
+         * Computed signal containing the Theatre.js sequence instance.
+         */
         this.sequence = computed(() => this.sheet.sheet().sequence, ...(ngDevMode ? [{ debugName: "sequence" }] : []));
         effect((onCleanup) => {
             const autoplay = untracked(this.autoplay);
@@ -698,10 +1279,21 @@ class TheatreSequence {
             });
         });
     }
+    /**
+     * Pauses the sequence playback at the current position.
+     */
     pause() {
         const sequence = this.sequence();
         sequence.pause();
     }
+    /**
+     * Starts or resumes sequence playback.
+     *
+     * Waits for the project to be ready before starting playback.
+     * Options are merged with the configured play options.
+     *
+     * @param options - Optional play options that override the configured options
+     */
     play(options = {}) {
         const sequence = this.sequence();
         const project = this.project.project();
@@ -709,6 +1301,12 @@ class TheatreSequence {
             sequence.play({ ...this.playOptions(), ...options });
         });
     }
+    /**
+     * Resets the sequence position to 0.
+     *
+     * If the sequence was playing before reset, it will continue playing
+     * from the beginning.
+     */
     reset() {
         const sequence = this.sequence();
         const isPlaying = val(sequence.pointer.playing);
@@ -724,6 +1322,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
             args: [{ selector: '[sheet][sequence]', exportAs: 'sequence' }]
         }], ctorParameters: () => [], propDecorators: { options: [{ type: i0.Input, args: [{ isSignal: true, alias: "sequence", required: false }] }], audioOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "sequenceAudio", required: false }] }], position: [{ type: i0.Input, args: [{ isSignal: true, alias: "position", required: false }] }, { type: i0.Output, args: ["positionChange"] }], playing: [{ type: i0.Input, args: [{ isSignal: true, alias: "playing", required: false }] }, { type: i0.Output, args: ["playingChange"] }], length: [{ type: i0.Input, args: [{ isSignal: true, alias: "length", required: false }] }, { type: i0.Output, args: ["lengthChange"] }] } });
 
+/**
+ * Angular Three Theatre.js integration library
+ *
+ * This library provides Angular components and directives for integrating
+ * Theatre.js animation toolkit with Angular Three applications.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Combined array of TheatreSheet and TheatreSequence directives for convenient importing.
+ *
+ * @example
+ * ```typescript
+ * import { TheatreSheet } from 'angular-three-theatre';
+ *
+ * @Component({
+ *   imports: [TheatreSheet],
+ *   template: `<ng-container sheet="mySheet" sequence />`
+ * })
+ * export class MyComponent {}
+ * ```
+ */
 const TheatreSheet = [TheatreSheet$1, TheatreSequence];
 
 /**