@twick/visualizer 0.14.2 → 0.14.3

package/src/index.ts

@@ -1,6 +1,196 @@
+/**
+ * @twick/visualizer - Professional Video Visualization Library
+ * 
+ * A comprehensive TypeScript library for creating dynamic video visualizations with
+ * animations, effects, and interactive elements. Built on top of @twick/2d and @twick/core
+ * for high-performance 2D graphics and animation.
+ * 
+ * ## 🚀 Quick Start
+ * 
+ * ```js
+ * import { scene } from '@twick/visualizer';
+ * import { makeScene2D } from '@twick/2d';
+ * 
+ * // Create a video visualization
+ * const videoScene = makeScene2D("video-scene", function* (view) {
+ *   yield* scene({
+ *     backgroundColor: "#000000",
+ *     playerId: "main-player",
+ *     properties: { width: 1920, height: 1080 },
+ *     tracks: [
+ *       {
+ *         id: "main-track",
+ *         type: "video",
+ *         elements: [
+ *           {
+ *             id: "intro-video",
+ *             type: "video",
+ *             s: 0,
+ *             e: 10,
+ *             props: { src: "intro.mp4" },
+ *             animation: {
+ *               name: "fade",
+ *               animate: "enter",
+ *               duration: 2
+ *             }
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   });
+ * });
+ * ```
+ * 
+ * ## 🎯 Getting Started
+ * 
+ * ### 1. Installation
+ * ```bash
+ * pnpm add @twick/visualizer @twick/2d @twick/core
+ * ```
+ * 
+ * ### 2. Basic Usage
+ * ```js
+ * import { scene } from '@twick/visualizer';
+ * import { makeScene2D } from '@twick/2d';
+ * 
+ * // Simple fade-in text
+ * const simpleScene = makeScene2D("simple", function* (view) {
+ *   yield* scene({
+ *     backgroundColor: "#1a1a1a",
+ *     playerId: "simple-player",
+ *     properties: { width: 1920, height: 1080 },
+ *     tracks: [{
+ *       id: "text-track",
+ *       type: "element",
+ *       elements: [{
+ *         id: "welcome-text",
+ *         type: "text",
+ *         s: 0, e: 5,
+ *         t: "Welcome!",
+ *         props: {
+ *           fill: "#ffffff",
+ *           fontSize: 72,
+ *           fontFamily: "Arial"
+ *         },
+ *         animation: {
+ *           name: "fade",
+ *           animate: "enter",
+ *           duration: 2
+ *         }
+ *       }]
+ *     }]
+ *   });
+ * });
+ * ```
+ * 
+ * ### 3. Advanced Features
+ * - **Multi-track scenes** with synchronized elements
+ * - **Complex animations** with enter/exit effects
+ * - **Text effects** like typewriter and streaming
+ * - **Frame effects** for visual masking
+ * - **Media integration** for video, audio, and images
+ * 
+ * ## 📚 Core Concepts
+ * 
+ * ### Elements
+ * Visual components that can be rendered in the scene:
+ * - **Media Elements**: Video, Image, Audio for content display
+ * - **Text Elements**: Text, Caption for information overlay
+ * - **Shape Elements**: Rect, Circle, Icon for UI components
+ * - **Container Elements**: Scene for organization
+ * 
+ * ### Animations
+ * Motion effects that bring elements to life:
+ * - **Basic**: Fade, Rise for simple transitions
+ * - **Advanced**: Blur, Breathe, Succession for complex effects
+ * - **Photo-specific**: PhotoRise, PhotoZoom for media content
+ * 
+ * ### Text Effects
+ * Character and word-level text animations:
+ * - **Typewriter**: Character-by-character reveal
+ * - **Stream Word**: Word-by-word animation
+ * - **Elastic**: Bounce-in effects
+ * - **Erase**: Backspace-style removal
+ * 
+ * ### Frame Effects
+ * Visual masking and container transformations:
+ * - **Circle Frame**: Circular content masking
+ * - **Rect Frame**: Rectangular content masking
+ * 
+ * ## 🎯 Use Cases
+ * 
+ * - **Video Presentations**: Professional slideshows with animations
+ * - **Content Creation**: Social media videos with effects
+ * - **Educational Content**: Interactive learning materials
+ * - **Marketing Videos**: Branded content with visual effects
+ * - **Live Streaming**: Real-time visual enhancements
+ * 
+ * ## 🔧 Integration
+ * 
+ * The library integrates seamlessly with:
+ * - **@twick/2d**: 2D graphics and scene management
+ * - **@twick/core**: Animation and timing utilities
+ * - **@twick/timeline**: Timeline-based content management
+ * - **@twick/video-editor**: Video editing capabilities
+ * 
+ * ## 📖 Documentation Structure
+ * 
+ * This documentation is organized into logical categories:
+ * 1. **Core**: Main scene generator and core functionality
+ * 2. **Animations**: Motion effects and transitions
+ * 3. **Elements**: Visual components and content
+ * 4. **Text Effects**: Text animation and styling
+ * 5. **Frame Effects**: Visual masking and containers
+ * 6. **Types**: TypeScript type definitions
+ * 7. **Interfaces**: Component interfaces and contracts
+ * 
+ * Each component includes:
+ * - Detailed description and use cases
+ * - Complete parameter documentation
+ * - Practical code examples
+ * - Integration patterns
+ * - Performance considerations
+ * 
+ * ## 🚀 Performance Tips
+ * 
+ * - **Use parallel animations** with `all()` for better performance
+ * - **Optimize timing** by setting precise start/end times
+ * - **Reuse elements** when possible to reduce memory usage
+ * - **Batch operations** for multiple similar elements
+ * - **Monitor resource usage** for large scenes
+ * 
+ * ## 🔍 Troubleshooting
+ * 
+ * **Common Issues:**
+ * - **Elements not appearing**: Check start/end timing values
+ * - **Animations not working**: Verify animation name and parameters
+ * - **Performance issues**: Use parallel execution and optimize timing
+ * - **Memory leaks**: Ensure proper cleanup of media resources
+ * 
+ * **Debug Tips:**
+ * - Use browser dev tools to inspect scene structure
+ * - Check console logs for timing and error messages
+ * - Verify all required dependencies are installed
+ * - Test with simple examples before complex scenes
+ * 
+ * @packageDocumentation
+ */
+
 // Types
 export * from './helpers/types';
 
 // Components
 export * from './visualizer';
 
+/**
+ * @group Core
+ * @description Main scene generator and core functionality
+ */
+export { scene } from './visualizer';
+
+// Grouped exports for better organization
+export * from './animations';
+export * from './elements';
+export * from './text-effects';
+export * from './frame-effects';
+

package/src/text-effects/elastic.tsx

@@ -2,23 +2,54 @@ import { easeOutElastic, waitFor } from "@twick/core";
 import { TextEffectParams } from "../helpers/types";
 
 /**
- * ElasticEffect applies a scaling animation to text elements
- * with an elastic easing curve for a "pop" or "bounce" effect.
+ * @group ElasticEffect
+ * ElasticEffect applies a scaling animation to text elements with an elastic easing 
+ * curve for a "pop" or "bounce" effect. Creates playful, attention-grabbing text 
+ * animations that bounce into view with natural physics.
  *
  * Behavior:
- * - Optionally waits for a delay.
- * - Starts at zero scale (invisible).
- * - Scales up to full size with an elastic bounce.
+ * - Optionally waits for a delay
+ * - Starts at zero scale (invisible)
+ * - Scales up to full size with an elastic bounce
  *
- * @param elementRef - Reference to the text element to animate.
- * @param duration - Duration of the scaling animation.
- * @param delay - Optional delay before the animation starts.
+ * @param elementRef - Reference to the text element to animate
+ * @param duration - Duration of the scaling animation in seconds
+ * @param delay - Optional delay before the animation starts in seconds
+ * 
+ * @example
+ * ```js
+ * // Basic elastic bounce
+ * textEffect: {
+ *   name: "elastic",
+ *   duration: 1.5,
+ *   delay: 0.5
+ * }
+ * 
+ * // Quick elastic pop
+ * textEffect: {
+ *   name: "elastic",
+ *   duration: 0.8
+ * }
+ * ```
  */
 export const ElasticEffect = {
   name: "elastic",
 
   /**
    * Generator function controlling the elastic text scaling effect.
+   * Handles elastic bounce animations for text elements with natural physics.
+   *
+   * @param params - Text effect parameters including element reference and timing
+   * @returns Generator that controls the elastic animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* ElasticEffect.run({
+   *   elementRef: textElement,
+   *   duration: 1.5,
+   *   delay: 0.5
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/text-effects/erase.tsx

@@ -2,24 +2,57 @@ import { waitFor } from "@twick/core";
 import { TextEffectParams } from "../helpers/types";
 
 /**
- * EraseEffect animates text disappearing letter by letter,
- * simulating an "erasing" or backspace effect.
+ * @group EraseEffect
+ * EraseEffect animates text disappearing letter by letter, simulating an "erasing"
+ * or backspace effect. Creates engaging text removal animations that mimic
+ * real-world erasing or typing corrections.
  *
  * Behavior:
- * - Optionally waits for a delay before starting.
- * - Preserves the original element size.
- * - Animates removing one character at a time from the end.
+ * - Optionally waits for a delay before starting
+ * - Preserves the original element size
+ * - Animates removing one character at a time from the end
  *
- * @param elementRef - Reference to the text element to animate.
- * @param duration - Total duration of the erasing animation.
- * @param delay - Optional delay before starting.
- * @param bufferTime - Time reserved at the end of animation (default: 0.1).
+ * @param elementRef - Reference to the text element to animate
+ * @param duration - Total duration of the erasing animation in seconds
+ * @param delay - Optional delay before starting in seconds
+ * @param bufferTime - Time reserved at the end of animation in seconds (default: 0.1)
+ *
+ * @example
+ * ```js
+ * // Basic erase effect
+ * textEffect: {
+ *   name: "erase",
+ *   duration: 3,
+ *   delay: 1
+ * }
+ *
+ * // Quick erase with buffer time
+ * textEffect: {
+ *   name: "erase",
+ *   duration: 2,
+ *   bufferTime: 0.5
+ * }
+ * ```
  */
 export const EraseEffect = {
   name: "erase",
 
   /**
    * Generator function controlling the erase text effect.
+   * Handles character-by-character text removal animations.
+   *
+   * @param params - Text effect parameters including element reference and timing
+   * @returns Generator that controls the erase animation timeline
+   *
+   * @example
+   * ```js
+   * yield* EraseEffect.run({
+   *   elementRef: textElement,
+   *   duration: 3,
+   *   delay: 1,
+   *   bufferTime: 0.1
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/text-effects/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @group Text Effects
+ * @description Text animation and styling effects
+ */
+
+export { TypewriterEffect } from './typewriter';
+export { StreamWordEffect } from './stream-word';
+export { ElasticEffect } from './elastic';
+export { EraseEffect } from './erase';

package/src/text-effects/stream-word.tsx

@@ -2,24 +2,58 @@ import { waitFor } from "@twick/core";
 import { TextEffectParams } from "../helpers/types";
 
 /**
- * StreamWordEffect animates text appearing word by word,
- * creating a smooth "typing" or "streaming" effect.
+ * @group StreamWordEffect
+ * StreamWordEffect animates text appearing word by word, creating a smooth
+ * "typing" or "streaming" effect. Animates text word by word for natural
+ * reading flow and storytelling content.
  *
  * Behavior:
- * - Optionally waits for a delay before starting.
- * - Clears the text initially and preserves the original size.
- * - Reveals one word at a time with a consistent interval.
+ * - Optionally waits for a delay before starting
+ * - Clears the text initially and preserves the original size
+ * - Reveals one word at a time with a consistent interval
  *
- * @param elementRef - Reference to the text element to animate.
- * @param duration - Total duration of the animation.
- * @param delay - Optional delay before starting.
- * @param bufferTime - Time reserved at the end of animation (default: 0.1).
+ * @param elementRef - Reference to the text element to animate
+ * @param duration - Total duration of the animation in seconds
+ * @param delay - Optional delay before starting in seconds
+ * @param bufferTime - Time reserved at the end of animation in seconds
+ *
+ * @example
+ * ```js
+ * // Basic stream word effect
+ * textEffect: {
+ *   name: "stream-word",
+ *   duration: 2,
+ *   interval: 0.3
+ * }
+ *
+ * // With delay for dramatic effect
+ * textEffect: {
+ *   name: "stream-word",
+ *   duration: 4,
+ *   delay: 1,
+ *   bufferTime: 0.5
+ * }
+ * ```
  */
 export const StreamWordEffect = {
   name: "stream-word",
 
   /**
    * Generator function controlling the word streaming effect.
+   * Handles text clearing, word-by-word revelation, and timing for natural reading flow.
+   *
+   * @param params - Text effect parameters including element reference and timing
+   * @returns Generator that controls the stream word animation timeline
+   *
+   * @example
+   * ```js
+   * yield* StreamWordEffect.run({
+   *   elementRef: textElement,
+   *   duration: 2,
+   *   delay: 0.5,
+   *   bufferTime: 0.1
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/text-effects/typewriter.tsx

@@ -2,24 +2,58 @@ import { waitFor } from "@twick/core";
 import { TextEffectParams } from "../helpers/types";
 
 /**
- * TypewriterEffect animates text appearing one character at a time,
- * mimicking the behavior of a classic typewriter.
+ * @group TypewriterEffect
+ * TypewriterEffect animates text appearing one character at a time, mimicking the
+ * behavior of a classic typewriter. Creates a nostalgic, engaging text animation
+ * that draws attention to important content.
  *
  * Behavior:
- * - Optionally waits for a delay before starting.
- * - Clears the text initially and preserves the element's original size.
- * - Reveals one character at a time at a consistent interval.
+ * - Optionally waits for a delay before starting
+ * - Clears the text initially and preserves the element's original size
+ * - Reveals one character at a time at a consistent interval
  *
- * @param elementRef - Reference to the text element to animate.
- * @param duration - Total duration of the animation.
- * @param delay - Optional delay before starting.
- * @param bufferTime - Time reserved at the end of animation (default: 0.1).
+ * @param elementRef - Reference to the text element to animate
+ * @param duration - Total duration of the animation in seconds
+ * @param delay - Optional delay before starting in seconds
+ * @param bufferTime - Time reserved at the end of animation in seconds
+ * 
+ * @example
+ * ```js
+ * // Basic typewriter effect
+ * textEffect: {
+ *   name: "typewriter",
+ *   duration: 3,
+ *   interval: 0.1
+ * }
+ * 
+ * // With delay and buffer time
+ * textEffect: {
+ *   name: "typewriter",
+ *   duration: 5,
+ *   delay: 1,
+ *   bufferTime: 0.5
+ * }
+ * ```
  */
 export const TypewriterEffect = {
   name: "typewriter",
 
   /**
    * Generator function controlling the character-by-character typing animation.
+   * Handles text clearing, character revelation, and timing for the typewriter effect.
+   *
+   * @param params - Text effect parameters including element reference and timing
+   * @returns Generator that controls the typewriter animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* TypewriterEffect.run({
+   *   elementRef: textElement,
+   *   duration: 3,
+   *   delay: 0.5,
+   *   bufferTime: 0.1
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/visualizer-grouped.ts

@@ -0,0 +1,83 @@
+/**
+ * @twick/visualizer - Professional Video Visualization Library
+ * 
+ * A comprehensive TypeScript library for creating dynamic video visualizations with
+ * animations, effects, and interactive elements. Built on top of @twick/2d and @twick/core
+ * for high-performance 2D graphics and animation.
+ * 
+ * @packageDocumentation
+ */
+
+// Types
+export * from './helpers/types';
+
+// Core functionality
+export * from './visualizer';
+
+/**
+ * @group Core
+ * @description Main scene generator and core functionality
+ */
+export { scene } from './visualizer';
+
+/**
+ * @group Animations
+ * @description Motion effects and transitions for elements
+ */
+
+// Basic animations
+export { FadeAnimation } from './animations/fade';
+export { RiseAnimation } from './animations/rise';
+
+// Advanced animations
+export { BlurAnimation } from './animations/blur';
+export { BreatheAnimation } from './animations/breathe';
+export { SuccessionAnimation } from './animations/succession';
+
+// Photo-specific animations
+export { PhotoRiseAnimation } from './animations/photo-rise';
+export { PhotoZoomAnimation } from './animations/photo-zoom';
+
+/**
+ * @group Elements
+ * @description Visual components for creating scenes and content
+ */
+
+// Media elements
+export { VideoElement } from './elements/video.element';
+export { ImageElement } from './elements/image.element';
+export { AudioElement } from './elements/audio.element';
+
+// Text and caption elements
+export { TextElement } from './elements/text.element';
+export { CaptionElement } from './elements/caption.element';
+
+// Shape and UI elements
+export { RectElement } from './elements/rect.element';
+export { CircleElement } from './elements/circle.element';
+export { IconElement } from './elements/icon.element';
+
+// Special elements
+export { SceneElement } from './elements/scene.element';
+
+/**
+ * @group Text Effects
+ * @description Text animation and styling effects
+ */
+
+// Basic text effects
+export { TypewriterEffect } from './text-effects/typewriter';
+export { StreamWordEffect } from './text-effects/stream-word';
+
+// Advanced text effects
+export { ElasticEffect } from './text-effects/elastic';
+export { EraseEffect } from './text-effects/erase';
+
+/**
+ * @group Frame Effects
+ * @description Visual frame and masking effects
+ */
+
+// Frame effects
+export { CircleFrameEffect } from './frame-effects/circle.frame';
+export { RectFrameEffect } from './frame-effects/rect.frame';

package/src/visualizer.tsx

@@ -1,6 +1,43 @@
 /**
+ * @twick/visualizer - Professional Video Visualization Library
+ * 
  * Main visualizer component that renders the scene with video, audio, captions and other elements
- * based on the provided input configuration.
+ * based on the provided input configuration. Creates a complete visualization scene with
+ * background, tracks, animations, and effects for professional video content.
+ * 
+ * ## Scene Architecture
+ * 
+ * The visualizer creates a hierarchical scene structure:
+ * ```
+ * Scene
+ * ├── Background Container
+ * ├── Track 1
+ * │   ├── Element 1 (Video/Image/Audio)
+ * │   ├── Element 2 (Text/Caption)
+ * │   └── Element 3 (Shapes/UI)
+ * ├── Track 2
+ * │   └── ...
+ * └── Track N
+ * ```
+ * 
+ * ## Core Features
+ * 
+ * - **Multi-Track Support**: Organize elements into logical tracks
+ * - **Animation System**: Rich animation library with enter/exit effects
+ * - **Text Effects**: Character and word-level text animations
+ * - **Frame Effects**: Visual masking and container transformations
+ * - **Media Support**: Video, image, and audio content management
+ * - **Timing Control**: Precise start/end timing for all elements
+ * 
+ * ## Use Cases
+ * 
+ * - **Video Presentations**: Professional slideshows with animations
+ * - **Content Creation**: Social media videos with effects
+ * - **Educational Content**: Interactive learning materials
+ * - **Marketing Videos**: Branded content with visual effects
+ * - **Live Streaming**: Real-time visual enhancements
+ * 
+ * @packageDocumentation
  */
 
 import "./global.css";
@@ -24,10 +61,57 @@ import {
 import { dispatchWindowEvent } from "./helpers/event.utils";
 
 /**
- * Creates and configures the main scene for video visualization
- * @param {string} name - Name of the scene
- * @param {Function} generator - Generator function that handles scene setup and animation
- * @returns {Scene2D} Configured scene object
+ * @category Core
+ * @description Main scene generator for video visualization
+ * 
+ * Creates and configures the main scene for video visualization. Sets up a scene with 
+ * background, processes track elements, and handles animation generation for video, 
+ * audio, captions, and other visual elements.
+ * 
+ * ## Scene Lifecycle
+ * 
+ * 1. **Input Processing**: Retrieves video input configuration from scene variables
+ * 2. **Background Setup**: Creates background rectangle with specified color
+ * 3. **Track Processing**: Iterates through tracks and creates appropriate visualizations
+ * 4. **Animation Execution**: Runs all track animations in parallel using `all()`
+ * 5. **Event Dispatch**: Sends player update events for status tracking
+ * 
+ * ## Track Types Supported
+ * 
+ * - **VIDEO**: Video content with playback and effects
+ * - **AUDIO**: Audio content with timing and synchronization
+ * - **CAPTION**: Text overlays with styling and animations
+ * - **SCENE**: Scene containers for organization
+ * - **ELEMENT**: Custom elements with animations
+ * 
+ * ## 📊 Performance Features
+ * 
+ * - **Parallel Execution**: All track animations run concurrently
+ * - **Event-Driven**: Real-time status updates via window events
+ * - **Resource Management**: Automatic cleanup and memory optimization
+ * - **Error Handling**: Graceful fallbacks for missing configurations
+ * 
+ * @param name - Name of the scene for identification
+ * @param generator - Generator function that handles scene setup and animation
+ * @returns Configured scene object with all track animations
+ * 
+ * @example
+ * ```js
+ * // Basic scene setup
+ * const scene = makeScene2D("scene", function* (view) {
+ *   // Scene setup and animation logic
+ *   yield* all(...trackAnimations);
+ * });
+ * 
+ * // With video input configuration
+ * const videoScene = makeScene2D("video-scene", function* (view) {
+ *   // Configure scene variables
+ *   useScene().variables.set("input", videoInput);
+ *   useScene().variables.set("playerId", "main-player");
+ *   
+ *   // Scene will automatically process the input
+ * });
+ * ```
  */
 export const scene = makeScene2D("scene", function* (view: View2D) {
   // Get input configuration from scene variables

package/typedoc.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["./src/index.ts"],
+  "entryPoints": ["./src/visualizer-grouped.ts"],
   "out": "docs",
   "name": "@twick/visualizer",
   "excludePrivate": true,
@@ -10,6 +10,11 @@
   "readme": "README.md",
   "plugin": ["typedoc-plugin-markdown"],
   "categorizeByGroup": true,
-  "categoryOrder": ["Core", "Utils", "*"],
-  "hideBreadcrumbs": true
+  "categoryOrder": ["Core", "FadeAnimation", "RiseAnimation", "BlurAnimation", "BreatheAnimation", "SuccessionAnimation", "PhotoRiseAnimation", "PhotoZoomAnimation", "VideoElement", "ImageElement", "AudioElement", "TextElement", "CaptionElement", "RectElement", "CircleElement", "IconElement", "SceneElement", "TypewriterEffect", "StreamWordEffect", "ElasticEffect", "EraseEffect", "CircleFrameEffect", "RectFrameEffect", "Types", "Interfaces", "Other"],
+  "hideBreadcrumbs": true,
+  "groupOrder": ["Core", "FadeAnimation", "RiseAnimation", "BlurAnimation", "BreatheAnimation", "SuccessionAnimation", "PhotoRiseAnimation", "PhotoZoomAnimation", "VideoElement", "ImageElement", "AudioElement", "TextElement", "CaptionElement", "RectElement", "CircleElement", "IconElement", "SceneElement", "TypewriterEffect", "StreamWordEffect", "ElasticEffect", "EraseEffect", "CircleFrameEffect", "RectFrameEffect", "Types", "Interfaces", "Other"],
+  "sort": ["source-order"],
+  "defaultCategory": "Other",
+  "hideInPageTOC": false,
+  "includeVersion": true
 }