Lottie Animation Integration for MotionForge

package.json

@@ -60,6 +60,7 @@
     "embla-carousel-react": "^8.6.0",
     "framer-motion": "^12.23.2",
     "input-otp": "^1.4.2",
+    "lottie-web": "^5.13.0",
     "lucide-react": "^0.525.0",
     "next": "^16.1.1",
     "next-auth": "^4.24.11",

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

@@ -1,7 +1,16 @@
 'use client';
 
 import React from 'react';
-import { Player, AbsoluteFill, useCurrentFrame, interpolate, spring, useVideoConfig } from 'motionforge';
+import {
+  Player,
+  AbsoluteFill,
+  useCurrentFrame,
+  interpolate,
+  spring,
+  useVideoConfig,
+  Lottie,
+  Sequence
+} from 'motionforge';
 
 const HelloWorldComposition = () => {
   const frame = useCurrentFrame();
@@ -25,12 +34,26 @@ const HelloWorldComposition = () => {
         style={{
           opacity,
           transform: `scale(${scale}) translateY(${translateY}px)`,
-          textAlign: 'center'
+          textAlign: 'center',
+          zIndex: 10,
         }}
       >
         <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>
       </div>
+
+      {/* Lottie Animation Example */}
+      <Sequence from={30} durationInFrames={120}>
+        <AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center', opacity: 0.4 }}>
+          <div style={{ width: 600, height: 600 }}>
+            <Lottie
+              src="https://assets.lottiefiles.com/packages/lf20_u4j3X6.json"
+              playbackRate={0.5}
+              loop
+            />
+          </div>
+        </AbsoluteFill>
+      </Sequence>
     </AbsoluteFill>
   );
 };

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

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "motionforge": "^1.2.0",
+    "lottie-web": "^5.13.0",
     "next": "15.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

packages/motionforge/CHANGELOG.md

@@ -5,6 +5,18 @@ 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-03-20
+
+### Added
+- Full Lottie animation integration with `<Lottie />` component
+- Deterministic frame synchronization with MotionForge timeline
+- Support for both remote JSON URLs and local JSON objects
+- Advanced Lottie controls: `frameStart`, `frameEnd`, `playbackRate`, `loop`
+- Automatic relative frame mapping within `<Sequence />`
+- Production-grade performance with memoization and instance cleanup
+- CLI template updates with Lottie support and examples
+- Comprehensive Lottie documentation in README
+
 ## [1.2.0] - 2024-01-15
 
 ### Added

packages/motionforge/README.md

@@ -259,6 +259,62 @@ MotionForge uses a dark theme by default with emerald green accents. Customize c
 }
 ```
 
+## 🎭 Using Lottie in MotionForge
+
+MotionForge provides first-class, production-grade Lottie support. Animations are synchronized with the frame system for deterministic, frame-perfect rendering.
+
+### Basic Usage
+
+```tsx
+import { Lottie, AbsoluteFill } from 'motionforge';
+
+const MyComposition = () => {
+  return (
+    <AbsoluteFill>
+      <Lottie
+        src="https://assets.lottiefiles.com/packages/lf20_u4j3X6.json"
+        width={400}
+        height={400}
+      />
+    </AbsoluteFill>
+  );
+};
+```
+
+### Advanced Configuration
+
+The `Lottie` component supports several props to control playback and appearance:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string \| object` | - | URL to JSON or imported JSON object |
+| `frameStart` | `number` | `0` | The frame at which the Lottie starts |
+| `frameEnd` | `number` | - | The frame at which the Lottie ends |
+| `playbackRate` | `number` | `1` | Speed of the animation |
+| `loop` | `boolean` | `false` | Whether to loop the animation |
+| `width` | `number \| string` | `100%` | Width of the container |
+| `height` | `number \| string` | `100%` | Height of the container |
+
+### Syncing with Sequences
+
+`Lottie` automatically detects if it's inside a `Sequence` and adjusts its internal timing to match the relative frame.
+
+```tsx
+<Sequence from={30} durationInFrames={120}>
+  <Lottie
+    src={myAnimationData}
+    playbackRate={1.5}
+    loop
+  />
+</Sequence>
+```
+
+### Performance Tips
+
+1. **Pre-loading**: For imported JSON objects, Lottie initializes instantly. For URLs, it fetches the data once and memoizes the instance.
+2. **SSR Support**: The component handles server-side rendering gracefully by only initializing the Lottie engine on the client.
+3. **Memoization**: Internal animation instances are memoized and properly cleaned up to prevent memory leaks.
+
 ## 📖 Documentation
 
 - [Getting Started](https://motionforge.dev/docs/getting-started)

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",
@@ -73,6 +73,9 @@
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
+  "dependencies": {
+    "lottie-web": "^5.13.0"
+  },
   "devDependencies": {
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

packages/motionforge/src/components/Lottie.tsx

@@ -0,0 +1,182 @@
+'use client';
+
+import React, { useEffect, useRef, useState, useMemo } from 'react';
+import lottie, { AnimationItem } from 'lottie-web';
+import { useCurrentFrame } from '../core/context';
+import { useRelativeCurrentFrame } from './Sequence';
+
+export interface LottieProps {
+  /**
+   * Source of the Lottie animation. Can be a URL to a JSON file or an imported JSON object.
+   */
+  src: string | object;
+  /**
+   * The frame at which the Lottie animation should start playing.
+   * Default is 0.
+   */
+  frameStart?: number;
+  /**
+   * The frame at which the Lottie animation should end playing.
+   * Default is the last frame of the Lottie animation.
+   */
+  frameEnd?: number;
+  /**
+   * Playback rate of the Lottie animation.
+   * Default is 1.
+   */
+  playbackRate?: number;
+  /**
+   * Whether the Lottie animation should loop.
+   * Default is false.
+   */
+  loop?: boolean;
+  /**
+   * Width of the Lottie container.
+   */
+  width?: number | string;
+  /**
+   * Height of the Lottie container.
+   */
+  height?: number | string;
+  /**
+   * Style overrides for the Lottie container.
+   */
+  style?: React.CSSProperties;
+  /**
+   * CSS class name for the Lottie container.
+   */
+  className?: string;
+}
+
+/**
+ * Lottie Component for MotionForge.
+ *
+ * Provides production-grade Lottie support with deterministic frame synchronization.
+ * Synchronizes with the MotionForge frame system instead of using time-based playback.
+ */
+export const Lottie: React.FC<LottieProps> = ({
+  src,
+  frameStart = 0,
+  frameEnd,
+  playbackRate = 1,
+  loop = false,
+  width,
+  height,
+  style,
+  className,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const animationRef = useRef<AnimationItem | null>(null);
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const absoluteFrame = useCurrentFrame();
+  const relativeFrame = useRelativeCurrentFrame();
+
+  // Use relative frame if inside a Sequence, otherwise use absolute frame
+  const currentFrame = relativeFrame !== null ? relativeFrame : absoluteFrame;
+
+  // Handle initialization
+  useEffect(() => {
+    if (typeof window === 'undefined' || !containerRef.current) return;
+
+    let isCancelled = false;
+
+    const params: any = {
+      container: containerRef.current,
+      renderer: 'svg',
+      loop: false,
+      autoplay: false,
+      rendererSettings: {
+        progressiveLoad: false,
+        hideOnTransparent: true,
+      }
+    };
+
+    if (typeof src === 'string') {
+      params.path = src;
+    } else {
+      params.animationData = src;
+    }
+
+    try {
+      const anim = lottie.loadAnimation(params);
+      animationRef.current = anim;
+
+      const onLoaded = () => {
+        if (!isCancelled) {
+          setIsLoaded(true);
+        }
+      };
+
+      // Both events can be useful depending on how Lottie is loaded
+      anim.addEventListener('DOMLoaded', onLoaded);
+      anim.addEventListener('data_ready', onLoaded);
+
+      return () => {
+        isCancelled = true;
+        anim.destroy();
+        animationRef.current = null;
+      };
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+      return () => {};
+    }
+  }, [src]);
+
+  // Handle frame synchronization
+  useEffect(() => {
+    if (!animationRef.current || !isLoaded) return;
+
+    const anim = animationRef.current;
+
+    // totalFrames is available once loaded
+    const totalLottieFrames = anim.totalFrames;
+
+    // Determine the range of frames to play
+    const start = frameStart;
+    const end = frameEnd ?? totalLottieFrames;
+    const duration = end - start;
+
+    if (duration <= 0) return;
+
+    // Map MotionForge currentFrame to Lottie frame
+    // playbackRate affects how fast we move through the Lottie timeline
+    let targetFrame = currentFrame * playbackRate;
+
+    if (loop) {
+      targetFrame = targetFrame % duration;
+    } else {
+      targetFrame = Math.min(targetFrame, duration - 0.01);
+    }
+
+    // finalFrame is relative to the Lottie's original timeline
+    const finalFrame = start + targetFrame;
+
+    // goToAndStop(value, isFrame) - second arg true means it's a frame number, not time
+    anim.goToAndStop(finalFrame, true);
+  }, [currentFrame, isLoaded, frameStart, frameEnd, playbackRate, loop]);
+
+  const containerStyle: React.CSSProperties = useMemo(() => ({
+    width: width ?? '100%',
+    height: height ?? '100%',
+    ...style,
+  }), [width, height, style]);
+
+  if (error) {
+    return (
+      <div style={{ color: 'red', border: '1px solid red', padding: '10px' }}>
+        <strong>Lottie Error:</strong> {error}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      style={containerStyle}
+      className={className}
+      data-lottie-loaded={isLoaded}
+    />
+  );
+};

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;
 }