Lottie Animation Integration

packages/create-motionforge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-motionforge",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI tool to bootstrap MotionForge projects",
   "bin": {
     "create-motionforge": "./bin/index.js"

packages/create-motionforge/templates/hello-world/page.tsx.template

@@ -1,7 +1,7 @@
 'use client';
 
 import React from 'react';
-import { Player, AbsoluteFill, useCurrentFrame, interpolate, spring, useVideoConfig } from 'motionforge';
+import { Player, AbsoluteFill, useCurrentFrame, interpolate, spring, useVideoConfig, LottieAnimation } from 'motionforge';
 
 const HelloWorldComposition = () => {
   const frame = useCurrentFrame();
@@ -20,7 +20,7 @@ const HelloWorldComposition = () => {
   const translateY = interpolate(frame, [0, 30], [50, 0]);
 
   return (
-    <AbsoluteFill className="bg-gradient-to-br from-emerald-900 to-black flex items-center justify-center">
+    <AbsoluteFill className="bg-gradient-to-br from-emerald-950 to-black flex items-center justify-center">
       <div
         style={{
           opacity,
@@ -30,6 +30,16 @@ const HelloWorldComposition = () => {
       >
         <h1 className="text-7xl text-emerald-400 font-black mb-4">Hello MotionForge!</h1>
         <p className="text-2xl text-emerald-600">Your programmatic video journey starts here.</p>
+
+        {/* Lottie Example: Clean, deterministic, and frame-synced */}
+        <div className="flex justify-center mt-12">
+          <div className="w-48 h-48 bg-emerald-500/10 rounded-full flex items-center justify-center p-4 border border-emerald-500/20 shadow-[0_0_50px_-12px_rgba(16,185,129,0.3)]">
+            <LottieAnimation
+              src="https://assets10.lottiefiles.com/packages/lf20_m6cu96.json"
+              loop
+            />
+          </div>
+        </div>
       </div>
     </AbsoluteFill>
   );

packages/create-motionforge/templates/shared/package.json.template

@@ -9,12 +9,13 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "motionforge": "^1.2.0",
+    "motionforge": "^1.3.0",
     "next": "15.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "framer-motion": "^11.13.1",
-    "lucide-react": "^0.468.0"
+    "lucide-react": "^0.468.0",
+    "lottie-web": "^5.12.2"
   },
   "devDependencies": {
     "@types/node": "^20",

packages/motionforge/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to MotionForge will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2024-02-25
+
+### Added
+- Production-grade Lottie animation support with `<LottieAnimation />`
+- Frame-perfect synchronization between Lottie and MotionForge timeline
+- Deterministic Lottie rendering (disabled internal requestAnimationFrame)
+- Support for relative frame contexts in `Sequence`
+- New Lottie demo and sample assets
+- Lottie support in `create-motionforge` CLI templates
+
+### Changed
+- Updated `useRelativeCurrentFrame` to support `null` as default value for better sequence detection
+- Improved CLI template to include `lottie-web` by default
+
 ## [1.2.0] - 2024-01-15
 
 ### Added

packages/motionforge/README.md

@@ -18,6 +18,7 @@
 - 🎬 **Frame-Based Rendering** - Precise control over every frame
 - 🎨 **70+ Effect Components** - Fade, Scale, Slide, 3D transforms, particles, and more
 - 🌊 **Spring Physics** - Natural, physics-based animations
+- 🎬 **Lottie Support** - Full integration with Lottie-web for vector animations
 - 📊 **Interpolation System** - Smooth transitions with 20+ easing functions
 - 🎮 **Interactive Player** - Real-time preview with timeline controls
 - 📦 **Frame Caching** - LRU cache for optimized performance
@@ -42,6 +43,8 @@ bun add motionforge
 
 ## 🚀 Quick Start
 
+### Basic Animation
+
 ```tsx
 import { 
   AbsoluteFill, 
@@ -87,8 +90,38 @@ const MyVideo = () => {
     </AbsoluteFill>
   );
 };
+```
+
+### Using Lottie
+
+MotionForge provides first-class support for Lottie animations, fully synchronized with the frame system.
+
+```tsx
+import { LottieAnimation } from 'motionforge';
+import myAnimation from './animation.json';
+
+const MyComp = () => {
+  return (
+    <LottieAnimation
+      src={myAnimation}
+      loop
+      playbackRate={1}
+    />
+  );
+};
+```
+
+**Properties for `<LottieAnimation />`:**
+- `src`: JSON object or URL to the Lottie file.
+- `frameStart`: Frame to start from (default: 0).
+- `frameEnd`: Frame to end at (default: animation end).
+- `playbackRate`: Speed of playback (default: 1).
+- `loop`: Whether to loop the animation (default: false).
+- `width`/`height`: Dimensions of the container.
 
-// Use with Player
+### Player Integration
+
+```tsx
 const App = () => (
   <Player
     component={MyVideo}
@@ -116,6 +149,15 @@ const App = () => (
 | `Reverse` | Play content backwards |
 | `Series` | Sequential scene management |
 
+### Media Components
+
+| Component | Description |
+|-----------|-------------|
+| `Video` | Frame-synced video playback |
+| `Audio` | Frame-synced audio playback |
+| `Img` | Static image component |
+| `LottieAnimation` | Production-grade, frame-synced Lottie animations |
+
 ### Effect Components
 
 ```tsx

packages/motionforge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionforge",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A React-based framework for creating videos programmatically. Build stunning videos with React components, spring animations, and frame-perfect control.",
   "author": "MotionForge Team",
   "license": "MIT",
@@ -87,5 +87,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "lottie-web": "^5.13.0"
   }
 }

packages/motionforge/src/components/Lottie.tsx

@@ -0,0 +1,127 @@
+'use client';
+
+import React, { useEffect, useRef, useState } from 'react';
+import lottie, { AnimationItem, AnimationConfigWithData, AnimationConfigWithPath } from 'lottie-web';
+import { useCurrentFrame, useVideoConfig } from '../core/context';
+import { useRelativeCurrentFrame } from './Sequence';
+import { LottieAnimationProps } from '../core/types';
+
+/**
+ * LottieAnimation Component
+ *
+ * Renders a Lottie animation synchronized with the MotionForge frame system.
+ * This component is deterministic and does not use requestAnimationFrame for playback.
+ */
+export const LottieAnimation: React.FC<LottieAnimationProps> = ({
+  src,
+  frameStart = 0,
+  frameEnd,
+  playbackRate = 1,
+  loop = false,
+  width,
+  height,
+  style,
+  className,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const animationRef = useRef<AnimationItem | null>(null);
+
+  // Use relative frame if inside a Sequence, otherwise use absolute frame
+  const relativeFrame = useRelativeCurrentFrame();
+  const absoluteFrame = useCurrentFrame();
+  const currentFrame = relativeFrame !== null ? relativeFrame : absoluteFrame;
+
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  // Initialize Lottie instance
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    // Clear container to prevent duplicate renders
+    containerRef.current.innerHTML = '';
+
+    const commonConfig = {
+      container: containerRef.current,
+      renderer: 'svg' as const,
+      loop: false, // We control playback manually
+      autoplay: false, // We control playback manually
+    };
+
+    let anim: AnimationItem;
+
+    if (typeof src === 'string') {
+      anim = lottie.loadAnimation({
+        ...commonConfig,
+        path: src,
+      } as AnimationConfigWithPath);
+    } else {
+      // Create a deep copy of animationData to prevent lottie-web from mutating it
+      anim = lottie.loadAnimation({
+        ...commonConfig,
+        animationData: JSON.parse(JSON.stringify(src)),
+      } as AnimationConfigWithData);
+    }
+
+    animationRef.current = anim;
+
+    const handleLoaded = () => {
+      setIsLoaded(true);
+    };
+
+    // Lottie emits DOMLoaded when the SVG elements are added to the DOM
+    anim.addEventListener('DOMLoaded', handleLoaded);
+
+    return () => {
+      anim.removeEventListener('DOMLoaded', handleLoaded);
+      anim.destroy();
+      animationRef.current = null;
+    };
+  }, [src]);
+
+  // Synchronize Lottie frame with MotionForge frame
+  useEffect(() => {
+    if (!animationRef.current || !isLoaded) return;
+
+    const anim = animationRef.current;
+
+    // totalFrames is the number of frames in the Lottie animation
+    const totalLottieFrames = anim.totalFrames;
+
+    // Determine the effective end frame for the animation window
+    const end = frameEnd !== undefined ? frameEnd : totalLottieFrames;
+    const duration = end - frameStart;
+
+    // Calculate the target frame in the Lottie animation
+    let lottieFrame = (currentFrame * playbackRate) + frameStart;
+
+    if (loop && duration > 0) {
+      // Loop within the specified window [frameStart, end]
+      lottieFrame = frameStart + ((lottieFrame - frameStart) % duration);
+    } else {
+      // Clamp to the end frame if not looping
+      lottieFrame = Math.min(lottieFrame, end);
+    }
+
+    // Go to the calculated frame and stop (prevent internal playback)
+    // The second parameter 'true' indicates we are using frame numbers, not time.
+    anim.goToAndStop(lottieFrame, true);
+  }, [currentFrame, isLoaded, frameStart, frameEnd, playbackRate, loop]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      style={{
+        width: width || '100%',
+        height: height || '100%',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        overflow: 'hidden',
+        ...style,
+      }}
+    />
+  );
+};
+
+export default LottieAnimation;

packages/motionforge/src/components/Media.tsx

@@ -6,7 +6,7 @@ import { interpolate } from '../utils/animation';
 
 // Absolute Fill - Container component
 interface AbsoluteFillProps {
-  children: React.ReactNode;
+  children?: React.ReactNode;
   style?: React.CSSProperties;
   className?: string;
 }
@@ -223,11 +223,6 @@ export const Img: React.FC<ImgProps> = ({
 };
 
 // StaticFile component - for local static assets
-interface StaticFileProps {
-  src: string;
-  style?: React.CSSProperties;
-}
-
 export const staticFile = (path: string): string => {
   // In a real implementation, this would resolve to a static file path
   return `/static/${path}`;

packages/motionforge/src/components/Sequence.tsx

@@ -107,7 +107,7 @@ const SequenceFrameProvider: React.FC<SequenceFrameProviderProps> = ({
 };
 
 // Relative Frame Context
-const RelativeFrameContext = createContext<number>(0);
+const RelativeFrameContext = createContext<number | null>(null);
 
 export const useRelativeCurrentFrame = () => useContext(RelativeFrameContext);
 

packages/motionforge/src/core/types.ts

@@ -59,6 +59,18 @@ export interface TextProps {
   children: React.ReactNode;
 }
 
+export interface LottieAnimationProps {
+  src: string | object;
+  frameStart?: number;
+  frameEnd?: number;
+  playbackRate?: number;
+  loop?: boolean;
+  width?: number | string;
+  height?: number | string;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
 export interface SpringConfig {
   frame: number;
   fps: number;