@twick/visualizer 0.14.0 → 0.14.3

package/.eslintrc.json

@@ -1,21 +1,21 @@
-{
-  "root": true,
-  "extends": [
-    "eslint:recommended",
-    "plugin:@typescript-eslint/recommended"
-  ],
-  "parser": "@typescript-eslint/parser",
-  "plugins": ["@typescript-eslint"],
-  "parserOptions": {
-    "ecmaVersion": "latest",
-    "sourceType": "module"
-  },
-  "env": {
-    "es2022": true,
-    "node": true
-  },
-  "rules": {
-    "@typescript-eslint/no-explicit-any": "warn",
-    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
-  }
+{
+  "root": true,
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "env": {
+    "es2022": true,
+    "node": true
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+  }
 } 

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.
-
-## Installation
-```
-pnpm install
-```
-
-## Build
-```
-pnpm build
-```
+# @twick/visualizer
+
+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
+```
+
+## 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);
+```
+
+## 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,20 +1,26 @@
 {
   "name": "@twick/visualizer",
-  "version": "0.14.0",
-  "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/visualizer-grouped.ts",
+    "clean": "rimraf .turbo node_modules dist"
+  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@preact/signals": "^1.2.1",
-    "@twick/2d": "^0.14.0",
-    "@twick/core": "^0.14.0",
-    "@twick/renderer": "^0.14.0",
-    "@twick/vite-plugin": "^0.14.0",
+    "@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.0"
+    "@twick/media-utils": "0.14.3"
   },
   "devDependencies": {
     "@twick/cli": "0.14.0",
@@ -24,11 +30,5 @@
     "typedoc-plugin-markdown": "^3.17.1",
     "vite-plugin-dts": "^3.7.3",
     "vite": "^5.1.4"
-  },
-  "scripts": {
-    "start": "twick editor --projectFile ./src/live.tsx",
-    "build": "tsc && vite build",
-    "docs": "typedoc --out docs src/index.ts",
-    "clean": "rimraf .turbo node_modules dist"
   }
-}
+}

package/package.json.bak

@@ -0,0 +1,34 @@
+{
+  "name": "@twick/visualizer",
+  "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/visualizer-grouped.ts",
+    "clean": "rimraf .turbo node_modules dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@preact/signals": "^1.2.1",
+    "@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.3"
+  },
+  "devDependencies": {
+    "@twick/cli": "0.14.0",
+    "@twick/ui": "0.14.0",
+    "typescript": "5.4.2",
+    "typedoc": "^0.25.8",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "vite-plugin-dts": "^3.7.3",
+    "vite": "^5.1.4"
+  }
+}

package/src/animations/blur.tsx

@@ -1,60 +1,96 @@
-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.
- *
- * Available animation modes:
- * - "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").
- */
-export const BlurAnimation = {
-  name: "blur",
-
-  /**
-   * Generator function controlling the blur animation.
-   */
-  *run({
-    elementRef,
-    containerRef,
-    interval,
-    duration,
-    intensity = 25,
-    animate,
-  }: AnimationParams) {
-    // Choose containerRef if provided; otherwise, fallback to elementRef
-    const ref = containerRef ?? elementRef;
-
-    let animationInterval = Math.min(interval, duration);
-    if (animate === "enter") {
-      // Start fully blurred
-      ref().filters.blur(intensity);
-      // Animate to no blur over 'interval'
-      yield* ref().filters.blur(0, animationInterval);
-    } else if (animate === "exit") {
-      // Wait for the time before exit animation starts
-      yield* waitFor(duration - animationInterval);
-      // Animate from no blur to full blur over 'interval'
-      yield* ref().filters.blur(intensity, animationInterval);
-    } else if (animate === "both") {
-      animationInterval = Math.min(interval, duration/2);
-      // Start fully blurred
-      ref().filters.blur(intensity);
-      // Animate to no blur
-      yield* ref().filters.blur(0, animationInterval);
-      // Wait until exit animation
-      yield* waitFor(duration - animationInterval);
-      // Animate to full blur again
-      yield* ref().filters.blur(intensity, animationInterval);
-    }
-  },
-};
+import { waitFor } from "@twick/core";
+import { AnimationParams } from "../helpers/types";
+
+/**
+ * @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
+ *
+ * @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,
+    containerRef,
+    interval,
+    duration,
+    intensity = 25,
+    animate,
+  }: AnimationParams) {
+    // Choose containerRef if provided; otherwise, fallback to elementRef
+    const ref = containerRef ?? elementRef;
+
+    let animationInterval = Math.min(interval, duration);
+    if (animate === "enter") {
+      // Start fully blurred
+      ref().filters.blur(intensity);
+      // Animate to no blur over 'interval'
+      yield* ref().filters.blur(0, animationInterval);
+    } else if (animate === "exit") {
+      // Wait for the time before exit animation starts
+      yield* waitFor(duration - animationInterval);
+      // Animate from no blur to full blur over 'interval'
+      yield* ref().filters.blur(intensity, animationInterval);
+    } else if (animate === "both") {
+      animationInterval = Math.min(interval, duration/2);
+      // Start fully blurred
+      ref().filters.blur(intensity);
+      // Animate to no blur
+      yield* ref().filters.blur(0, animationInterval);
+      // Wait until exit animation
+      yield* waitFor(duration - animationInterval);
+      // Animate to full blur again
+      yield* ref().filters.blur(intensity, animationInterval);
+    }
+  },
+};

package/src/animations/breathe.tsx

@@ -1,60 +1,95 @@
-import { Vector2 } from "@twick/core";
-import { AnimationParams } from "../helpers/types";
-import { getTimingFunction } from "../helpers/timing.utils";
-
-/**
- * BreatheAnimation applies a smooth scale in/out effect to simulate
- * a "breathing" motion.
- *
- * Available modes:
- * - "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).
- */
-export const BreatheAnimation = {
-  name: "breathe",
-
-  /**
-   * Generator function controlling the breathing scale animation.
-   */
-  *run({
-    elementRef,
-    containerRef,
-    mode,
-    duration,
-    intensity = 0.5,
-  }: AnimationParams) {
-    // Use containerRef if provided, otherwise fallback to elementRef
-    const ref = containerRef ?? elementRef;
-
-    // Get the current scale of the element
-    const scale = ref().scale();
-
-    if (mode === "in") {
-      // Animate scaling down to (original scale * intensity)
-      yield* ref().scale(
-        new Vector2(scale.x * intensity, scale.y * intensity),
-        duration,
-        getTimingFunction("easeInSine")
-      );
-    }
-
-    if (mode === "out") {
-      // Immediately set to scaled down size
-      ref().scale(
-        new Vector2(scale.x * intensity, scale.y * intensity)
-      );
-      // Animate scaling back up to original size
-      yield* ref().scale(
-        new Vector2(scale.x, scale.y),
-        duration,
-        getTimingFunction("easeOutSine")
-      );
-    }
-  },
-};
+import { Vector2 } from "@twick/core";
+import { AnimationParams } from "../helpers/types";
+import { getTimingFunction } from "../helpers/timing.utils";
+
+/**
+ * @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
+ *
+ * @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,
+    containerRef,
+    mode,
+    duration,
+    intensity = 0.5,
+  }: AnimationParams) {
+    // Use containerRef if provided, otherwise fallback to elementRef
+    const ref = containerRef ?? elementRef;
+
+    // Get the current scale of the element
+    const scale = ref().scale();
+
+    if (mode === "in") {
+      // Animate scaling down to (original scale * intensity)
+      yield* ref().scale(
+        new Vector2(scale.x * intensity, scale.y * intensity),
+        duration,
+        getTimingFunction("easeInSine")
+      );
+    }
+
+    if (mode === "out") {
+      // Immediately set to scaled down size
+      ref().scale(
+        new Vector2(scale.x * intensity, scale.y * intensity)
+      );
+      // Animate scaling back up to original size
+      yield* ref().scale(
+        new Vector2(scale.x, scale.y),
+        duration,
+        getTimingFunction("easeOutSine")
+      );
+    }
+  },
+};