@twick/visualizer 0.14.2 → 0.14.3

package/README.md

@@ -1,13 +1,113 @@
 # @twick/visualizer
 
-A visualization library built on top of [@twick/2d](https://github.com/re-video/2d) for creating interactive visualizations.
+A visualization library built on top of [@twick/2d](https://github.com/re-video/2d) for creating interactive visualizations and animations.
+
+## Overview
+
+This package provides advanced visualization capabilities for creating interactive animations, effects, and visual elements in video editing applications. Built on top of a 2D graphics engine, it offers powerful tools for creating professional visual content.
 
 ## Installation
+
+```bash
+npm install @twick/visualizer
+# or
+pnpm add @twick/visualizer
 ```
-pnpm install
+
+## Quick Start
+
+```typescript
+import { 
+  createVisualization,
+  addAnimation,
+  renderScene 
+} from '@twick/visualizer';
+
+// Create a new visualization
+const viz = createVisualization({
+  width: 1920,
+  height: 1080,
+  duration: 10
+});
+
+// Add animations and effects
+addAnimation(viz, {
+  type: 'fade',
+  startTime: 0,
+  duration: 2
+});
+
+// Render the scene
+const output = await renderScene(viz);
 ```
 
-## Build
+## Key Features
+
+- **Interactive Visualizations**: Create dynamic visual content
+- **Animation Engine**: Powerful animation system with keyframes
+- **Effect Library**: Built-in effects and transitions
+- **Performance Optimized**: Efficient rendering for real-time applications
+- **Extensible**: Plugin system for custom effects
+- **2D Graphics**: Full 2D graphics capabilities
+
+## Development
+
+### Installation
+
+```bash
+pnpm install
 ```
+
+### Build
+
+```bash
 pnpm build
-```
+```
+
+### Development Server
+
+```bash
+pnpm dev
+```
+
+## API Reference
+
+### Core Functions
+
+- `createVisualization`: Create a new visualization instance
+- `addAnimation`: Add animations to the scene
+- `renderScene`: Render the visualization to output
+- `addEffect`: Apply visual effects
+- `exportAnimation`: Export animations in various formats
+
+### Types
+
+- `VisualizationConfig`: Configuration for visualizations
+- `AnimationOptions`: Animation configuration options
+- `EffectConfig`: Effect configuration interface
+- `RenderOptions`: Rendering options
+
+For complete API documentation, refer to the generated documentation.
+
+## Browser Support
+
+This package requires a browser environment with support for:
+- WebGL or Canvas 2D
+- Modern JavaScript features (ES2020+)
+- RequestAnimationFrame API
+
+## Documentation
+
+For complete documentation, refer to the project documentation site.
+
+## License
+
+This package is licensed under the **Sustainable Use License (SUL) Version 1.0**.
+
+- Free for use in commercial and non-commercial apps
+- Can be modified and self-hosted
+- Cannot be sold, rebranded, or distributed as a standalone SDK
+
+For commercial licensing inquiries, contact: contact@kifferai.com
+
+For full license terms, see the main LICENSE.md file in the project root.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@twick/visualizer",
-  "version": "0.14.2",
-  "license": "Apache-2.0",
+  "version": "0.14.3",
+  "license": "SEE LICENSE IN LICENSE.md",
   "scripts": {
     "start": "twick editor --projectFile ./src/live.tsx",
     "build": "tsc && vite build",
-    "docs": "typedoc --out docs src/index.ts",
+    "docs": "typedoc --out docs src/visualizer-grouped.ts",
     "clean": "rimraf .turbo node_modules dist"
   },
   "publishConfig": {
@@ -13,14 +13,14 @@
   },
   "dependencies": {
     "@preact/signals": "^1.2.1",
-    "@twick/2d": "0.14.2",
-    "@twick/core": "0.14.2",
-    "@twick/renderer": "0.14.2",
-    "@twick/vite-plugin": "0.14.2",
+    "@twick/2d": "0.14.3",
+    "@twick/core": "0.14.3",
+    "@twick/renderer": "0.14.3",
+    "@twick/vite-plugin": "0.14.3",
     "date-fns": "^4.1.0",
     "preact": "^10.19.2",
     "crelt": "^1.0.6",
-    "@twick/media-utils": "0.14.2"
+    "@twick/media-utils": "0.14.3"
   },
   "devDependencies": {
     "@twick/cli": "0.14.0",

package/package.json.bak

@@ -1,11 +1,11 @@
 {
   "name": "@twick/visualizer",
-  "version": "0.14.2",
-  "license": "Apache-2.0",
+  "version": "0.14.3",
+  "license": "SEE LICENSE IN LICENSE.md",
   "scripts": {
     "start": "twick editor --projectFile ./src/live.tsx",
     "build": "tsc && vite build",
-    "docs": "typedoc --out docs src/index.ts",
+    "docs": "typedoc --out docs src/visualizer-grouped.ts",
     "clean": "rimraf .turbo node_modules dist"
   },
   "publishConfig": {
@@ -13,14 +13,14 @@
   },
   "dependencies": {
     "@preact/signals": "^1.2.1",
-    "@twick/2d": "0.14.2",
-    "@twick/core": "0.14.2",
-    "@twick/renderer": "0.14.2",
-    "@twick/vite-plugin": "0.14.2",
+    "@twick/2d": "0.14.3",
+    "@twick/core": "0.14.3",
+    "@twick/renderer": "0.14.3",
+    "@twick/vite-plugin": "0.14.3",
     "date-fns": "^4.1.0",
     "preact": "^10.19.2",
     "crelt": "^1.0.6",
-    "@twick/media-utils": "0.14.2"
+    "@twick/media-utils": "0.14.3"
   },
   "devDependencies": {
     "@twick/cli": "0.14.0",

package/src/animations/blur.tsx

@@ -2,26 +2,62 @@ import { waitFor } from "@twick/core";
 import { AnimationParams } from "../helpers/types";
 
 /**
- * BlurAnimation applies a blur effect to an element or its container
- * during enter, exit, or both animations.
+ * @group BlurAnimation
+ * BlurAnimation applies a blur effect to an element or its container during enter,
+ * exit, or both animations. Creates smooth blur transitions for professional
+ * visual effects that can focus attention or create depth.
  *
  * Available animation modes:
- * - "enter": Starts blurred and gradually becomes clear.
- * - "exit": Starts clear and gradually becomes blurred.
- * - "both": Blurs in, clears, then blurs out.
+ * - "enter": Starts blurred and gradually becomes clear
+ * - "exit": Starts clear and gradually becomes blurred
+ * - "both": Blurs in, clears, then blurs out
  *
- * @param elementRef - Reference to the main element.
- * @param containerRef - Optional reference to a container element.
- * @param interval - Duration (in frames or ms) of each blur transition.
- * @param duration - Total duration of the animation.
- * @param intensity - Maximum blur strength (default: 25).
- * @param animate - Animation phase ("enter" | "exit" | "both").
+ * @param elementRef - Reference to the main element to animate
+ * @param containerRef - Optional reference to a container element
+ * @param interval - Duration of blur transitions in seconds
+ * @param duration - Total duration of the animation in seconds
+ * @param intensity - Maximum blur strength (default: 25)
+ * @param animate - Animation phase ("enter" | "exit" | "both")
+ *
+ * @example
+ * ```js
+ * // Basic blur-in animation
+ * animation: {
+ *   name: "blur",
+ *   animate: "enter",
+ *   duration: 2,
+ *   intensity: 15
+ * }
+ *
+ * // Blur out effect
+ * animation: {
+ *   name: "blur",
+ *   animate: "exit",
+ *   duration: 1.5,
+ *   intensity: 30
+ * }
+ * ```
  */
 export const BlurAnimation = {
   name: "blur",
 
   /**
    * Generator function controlling the blur animation.
+   * Handles blur transitions based on the specified animation mode and intensity.
+   *
+   * @param params - Animation parameters including element references and timing
+   * @returns Generator that controls the blur animation timeline
+   *
+   * @example
+   * ```js
+   * yield* BlurAnimation.run({
+   *   elementRef: myElement,
+   *   interval: 0.5,
+   *   duration: 2,
+   *   intensity: 25,
+   *   animate: "enter"
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/animations/breathe.tsx

@@ -3,24 +3,59 @@ import { AnimationParams } from "../helpers/types";
 import { getTimingFunction } from "../helpers/timing.utils";
 
 /**
- * BreatheAnimation applies a smooth scale in/out effect to simulate
- * a "breathing" motion.
+ * @group BreatheAnimation
+ * BreatheAnimation applies a smooth scale in/out effect to simulate a "breathing" motion.
+ * Creates gentle pulsing animations that add life and movement to static elements.
+ * Perfect for subtle background animations and attention-grabbing effects.
  *
  * Available modes:
- * - "in": Gradually scales down (shrinks) to the target intensity.
- * - "out": Starts scaled down, then grows back to original size.
+ * - "in": Gradually scales down (shrinks) to the target intensity
+ * - "out": Starts scaled down, then grows back to original size
  *
- * @param elementRef - Reference to the main element to animate.
- * @param containerRef - Optional reference to a container element.
- * @param mode - Animation phase ("in" | "out").
- * @param duration - Duration of the scaling animation.
- * @param intensity - Target scale factor (default: 0.5).
+ * @param elementRef - Reference to the main element to animate
+ * @param containerRef - Optional reference to a container element
+ * @param mode - Animation phase ("in" | "out")
+ * @param duration - Duration of the scaling animation in seconds
+ * @param intensity - Target scale factor (default: 0.5)
+ * 
+ * @example
+ * ```js
+ * // Gentle breathing in effect
+ * animation: {
+ *   name: "breathe",
+ *   mode: "in",
+ *   duration: 2,
+ *   intensity: 0.8
+ * }
+ * 
+ * // Breathing out animation
+ * animation: {
+ *   name: "breathe",
+ *   mode: "out",
+ *   duration: 1.5,
+ *   intensity: 0.6
+ * }
+ * ```
  */
 export const BreatheAnimation = {
   name: "breathe",
 
   /**
    * Generator function controlling the breathing scale animation.
+   * Handles smooth scaling transitions to create natural breathing motion.
+   *
+   * @param params - Animation parameters including element references and timing
+   * @returns Generator that controls the breathing animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* BreatheAnimation.run({
+   *   elementRef: myElement,
+   *   mode: "in",
+   *   duration: 2,
+   *   intensity: 0.8
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/animations/fade.tsx

@@ -2,25 +2,138 @@ import { waitFor } from "@twick/core";
 import { AnimationParams } from "../helpers/types";
 
 /**
- * FadeAnimation applies a simple fade-in and fade-out effect
- * by adjusting opacity.
- *
- * Available animation modes:
- * - "enter": Starts transparent and fades in to fully opaque.
- * - "exit": Waits, then fades out to transparent.
- * - "both": Fades in, waits, then fades out.
- *
- * @param elementRef - Reference to the main element to animate.
- * @param containerRef - Optional reference to a container element.
- * @param interval - Duration of the fade transition (in frames or ms).
- * @param duration - Total duration of the animation.
- * @param animate - Animation phase ("enter" | "exit" | "both").
+ * @group FadeAnimation
+ * @description Simple fade-in and fade-out effects for smooth element transitions
+ * 
+ * FadeAnimation applies a simple fade-in and fade-out effect by adjusting opacity.
+ * Creates smooth opacity transitions for elements entering or exiting the scene.
+ * Perfect for subtle, professional animations that don't distract from content.
+ * 
+ * ## Animation Modes
+ * 
+ * - **"enter"**: Starts transparent and fades in to fully opaque
+ * - **"exit"**: Waits, then fades out to transparent  
+ * - **"both"**: Fades in, waits, then fades out
+ * 
+ * ## Use Cases
+ * 
+ * - **Text overlays**: Smooth introduction of captions and titles
+ * - **Background elements**: Subtle scene transitions
+ * - **UI components**: Professional interface animations
+ * - **Content reveals**: Gentle disclosure of information
+ * 
+ * ## Best Practices
+ * 
+ * - **Duration**: 1-3 seconds for most use cases
+ * - **Timing**: Use "enter" for introductions, "exit" for conclusions
+ * - **Combination**: Pair with other animations for complex effects
+ * - **Performance**: Lightweight and efficient for multiple elements
+ * 
+ * ## Integration Examples
+ * 
+ * ### Basic Text Fade
+ * ```js
+ * {
+ *   id: "welcome-text",
+ *   type: "text",
+ *   s: 0, e: 5,
+ *   t: "Welcome!",
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   }
+ * }
+ * ```
+ * 
+ * ### Video with Fade Transition
+ * ```js
+ * {
+ *   id: "intro-video",
+ *   type: "video",
+ *   s: 0, e: 10,
+ *   props: { src: "intro.mp4" },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "both",
+ *     duration: 3,
+ *     interval: 1
+ *   }
+ * }
+ * ```
+ * 
+ * ### Multi-Element Fade Sequence
+ * ```js
+ * // Fade in multiple elements with staggered timing
+ * const elements = [
+ *   {
+ *     id: "title",
+ *     type: "text",
+ *     s: 0, e: 8,
+ *     t: "Main Title",
+ *     animation: { name: "fade", animate: "enter", duration: 2 }
+ *   },
+ *   {
+ *     id: "subtitle", 
+ *     type: "text",
+ *     s: 1, e: 8,
+ *     t: "Subtitle",
+ *     animation: { name: "fade", animate: "enter", duration: 2 }
+ *   },
+ *   {
+ *     id: "background",
+ *     type: "rect",
+ *     s: 0, e: 10,
+ *     props: { fill: "#000000", opacity: 0.5 },
+ *     animation: { name: "fade", animate: "enter", duration: 1.5 }
+ *   }
+ * ];
+ * ```
+ * 
+ * @param elementRef - Reference to the main element to animate
+ * @param containerRef - Optional reference to a container element
+ * @param duration - Duration of the fade transition in seconds
+ * @param totalDuration - Total duration of the animation in seconds
+ * @param animate - Animation phase ("enter" | "exit" | "both")
+ * 
+ * @example
+ * ```js
+ * // Basic fade-in animation
+ * animation: {
+ *   name: "fade",
+ *   animate: "enter",
+ *   duration: 2,
+ *   direction: "center"
+ * }
+ * 
+ * // Fade in and out
+ * animation: {
+ *   name: "fade",
+ *   animate: "both",
+ *   duration: 3,
+ *   interval: 1
+ * }
+ * ```
  */
 export const FadeAnimation = {
   name: "fade",
 
   /**
    * Generator function controlling the fade animation.
+   * Handles opacity transitions based on the specified animation mode.
+   *
+   * @param params - Animation parameters including element references and timing
+   * @returns Generator that controls the fade animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* FadeAnimation.run({
+   *   elementRef: myElement,
+   *   interval: 1,
+   *   duration: 3,
+   *   animate: "enter"
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/animations/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @group Animations
+ * @description Motion effects and transitions for elements
+ */
+
+export { FadeAnimation } from './fade';
+export { RiseAnimation } from './rise';
+export { BlurAnimation } from './blur';
+export { BreatheAnimation } from './breathe';
+export { SuccessionAnimation } from './succession';
+export { PhotoRiseAnimation } from './photo-rise';
+export { PhotoZoomAnimation } from './photo-zoom';

package/src/animations/photo-rise.tsx

@@ -1,29 +1,66 @@
 import { AnimationParams } from "../helpers/types";
 
 /**
+ * @group PhotoRiseAnimation
  * PhotoRiseAnimation applies a smooth directional movement to a photo element.
+ * Creates elegant slide-in animations that bring photos into view from any direction.
+ * Perfect for photo galleries, presentations, and content reveals.
  *
  * Behavior:
- * - Starts offset in a given direction (up, down, left, or right).
- * - Animates back to the original position over the specified duration.
+ * - Starts offset in a given direction (up, down, left, or right)
+ * - Animates back to the original position over the specified duration
  *
  * Available directions:
- * - "up": Starts below and moves upward.
- * - "down": Starts above and moves downward.
- * - "left": Starts to the right and moves leftward.
- * - "right": Starts to the left and moves rightward.
+ * - "up": Starts below and moves upward
+ * - "down": Starts above and moves downward
+ * - "left": Starts to the right and moves leftward
+ * - "right": Starts to the left and moves rightward
  *
- * @param elementRef - Reference to the photo element to animate.
- * @param containerRef - Optional reference to a container element (required for this animation).
- * @param direction - Direction of the movement ("up" | "down" | "left" | "right").
- * @param duration - Duration of the movement animation.
- * @param intensity - Offset distance in pixels (default: 200).
+ * @param elementRef - Reference to the photo element to animate
+ * @param containerRef - Optional reference to a container element (required for this animation)
+ * @param direction - Direction of the movement ("up" | "down" | "left" | "right")
+ * @param duration - Duration of the movement animation in seconds
+ * @param intensity - Offset distance in pixels (default: 200)
+ * 
+ * @example
+ * ```js
+ * // Slide in from bottom
+ * animation: {
+ *   name: "photo-rise",
+ *   direction: "up",
+ *   duration: 1.5,
+ *   intensity: 300
+ * }
+ * 
+ * // Slide in from left
+ * animation: {
+ *   name: "photo-rise",
+ *   direction: "left",
+ *   duration: 2,
+ *   intensity: 400
+ * }
+ * ```
  */
 export const PhotoRiseAnimation = {
   name: "photo-rise",
 
   /**
    * Generator function controlling the photo rise animation.
+   * Handles directional movement animations for photo elements.
+   *
+   * @param params - Animation parameters including element references and direction
+   * @returns Generator that controls the photo rise animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* PhotoRiseAnimation.run({
+   *   elementRef: photoElement,
+   *   containerRef: container,
+   *   direction: "up",
+   *   duration: 1.5,
+   *   intensity: 200
+   * });
+   * ```
    */
   *run({
     elementRef,

package/src/animations/photo-zoom.tsx

@@ -2,24 +2,60 @@ import { Vector2 } from "@twick/core";
 import { AnimationParams } from "../helpers/types";
 
 /**
- * PhotoZoomAnimation applies a smooth zoom-in or zoom-out effect
- * on a photo element.
+ * @group PhotoZoomAnimation
+ * PhotoZoomAnimation applies a smooth zoom-in or zoom-out effect on a photo element.
+ * Creates dynamic zoom effects that add depth and focus to photo content.
+ * Perfect for highlighting details or creating cinematic photo presentations.
  *
  * Available animation modes:
- * - "in": Starts zoomed in and smoothly scales back to the original size.
- * - "out": Starts at normal size and smoothly scales up to the target zoom level.
+ * - "in": Starts zoomed in and smoothly scales back to the original size
+ * - "out": Starts at normal size and smoothly scales up to the target zoom level
  *
- * @param elementRef - Reference to the photo element to animate.
- * @param containerRef - Optional reference to a container element (required for this animation).
- * @param mode - Animation phase ("in" | "out").
- * @param duration - Duration of the zoom animation.
- * @param intensity - Zoom scale multiplier (default: 1.5).
+ * @param elementRef - Reference to the photo element to animate
+ * @param containerRef - Optional reference to a container element (required for this animation)
+ * @param mode - Animation phase ("in" | "out")
+ * @param duration - Duration of the zoom animation in seconds
+ * @param intensity - Zoom scale multiplier (default: 1.5)
+ * 
+ * @example
+ * ```js
+ * // Zoom in effect
+ * animation: {
+ *   name: "photo-zoom",
+ *   mode: "in",
+ *   duration: 2,
+ *   intensity: 1.8
+ * }
+ * 
+ * // Zoom out effect
+ * animation: {
+ *   name: "photo-zoom",
+ *   mode: "out",
+ *   duration: 1.5,
+ *   intensity: 2.0
+ * }
+ * ```
  */
 export const PhotoZoomAnimation = {
   name: "photo-zoom",
 
   /**
    * Generator function controlling the photo zoom animation.
+   * Handles smooth scaling transitions for zoom effects on photo elements.
+   *
+   * @param params - Animation parameters including element references and zoom settings
+   * @returns Generator that controls the photo zoom animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* PhotoZoomAnimation.run({
+   *   elementRef: photoElement,
+   *   containerRef: container,
+   *   mode: "in",
+   *   duration: 2,
+   *   intensity: 1.5
+   * });
+   * ```
    */
   *run({
     elementRef,