@mihirsarya/manim-scroll-react 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,230 @@
+# @mihirsarya/manim-scroll-react
+
+React components and hooks for scroll-driven Manim animations.
+
+## Installation
+
+```bash
+npm install @mihirsarya/manim-scroll-react
+```
+
+Or use the unified package (recommended):
+
+```bash
+npm install @mihirsarya/manim-scroll
+```
+
+## Requirements
+
+- React 18+
+- `@mihirsarya/manim-scroll-runtime` (peer dependency, installed automatically)
+
+## Quick Start
+
+### With Next.js Plugin (Recommended)
+
+When using with `@mihirsarya/manim-scroll-next`, animations are automatically resolved:
+
+```tsx
+import { ManimScroll } from "@mihirsarya/manim-scroll-react";
+
+export default function Page() {
+  return (
+    <ManimScroll
+      scene="TextScene"
+      fontSize={72}
+      color="#ffffff"
+      scrollRange="viewport"
+    >
+      Welcome to my site
+    </ManimScroll>
+  );
+}
+```
+
+### Manual Mode
+
+Without the Next.js plugin, provide an explicit manifest URL:
+
+```tsx
+import { ManimScroll } from "@mihirsarya/manim-scroll-react";
+
+export default function Page() {
+  return (
+    <ManimScroll
+      manifestUrl="/assets/scene/manifest.json"
+      scrollRange="viewport"
+    >
+      Scroll-driven text
+    </ManimScroll>
+  );
+}
+```
+
+### Native Mode
+
+For text animations without pre-rendered assets:
+
+```tsx
+<ManimScroll mode="native" fontSize={48} color="#ffffff">
+  Animate this text
+</ManimScroll>
+```
+
+## Exports
+
+### Components
+
+- **`ManimScroll`** - Scroll-driven animation component
+
+### Hooks
+
+- **`useManimScroll`** - Hook for custom integrations with pre-rendered assets
+- **`useNativeAnimation`** - Hook for native SVG text animation
+
+### Utilities
+
+- **`computePropsHash`** - Compute hash for animation props
+- **`extractChildrenText`** - Extract text from React children
+
+### Types
+
+- `ManimScrollProps`, `ManimAnimationProps`
+- `UseManimScrollOptions`, `UseManimScrollResult`
+- `UseNativeAnimationOptions`, `UseNativeAnimationResult`
+
+## ManimScroll Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `scene` | `string` | `"TextScene"` | Manim scene name |
+| `fontSize` | `number` | - | Font size for text animations |
+| `color` | `string` | - | Color as hex string |
+| `font` | `string` | - | Font family |
+| `inline` | `boolean` | `false` | Enable inline mode |
+| `padding` | `number` | `0.2` | Padding in inline mode (Manim units) |
+| `mode` | `"auto" \| "video" \| "frames" \| "native"` | `"auto"` | Playback mode |
+| `scrollRange` | `ScrollRangeValue` | `"viewport"` | Scroll range configuration |
+| `manifestUrl` | `string` | - | Explicit manifest URL |
+| `fontUrl` | `string` | - | Font file URL for native mode |
+| `strokeWidth` | `number` | `2` | Stroke width for native mode |
+| `onReady` | `() => void` | - | Called when animation is loaded |
+| `onProgress` | `(progress: number) => void` | - | Called on scroll progress |
+| `canvas` | `{ width?, height? }` | - | Canvas dimensions |
+| `className` | `string` | - | CSS class |
+| `style` | `CSSProperties` | - | Inline styles |
+| `children` | `ReactNode` | - | Text content |
+
+## useManimScroll Hook
+
+For advanced use cases requiring custom control:
+
+```tsx
+import { useRef } from "react";
+import { useManimScroll } from "@mihirsarya/manim-scroll-react";
+
+function CustomAnimation() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const { progress, isReady, error, pause, resume, seek } = useManimScroll({
+    ref: containerRef,
+    manifestUrl: "/assets/scene/manifest.json",
+    scrollRange: "viewport",
+  });
+
+  return (
+    <div ref={containerRef} style={{ height: "100vh" }}>
+      {!isReady && <div>Loading...</div>}
+      {error && <div>Error: {error.message}</div>}
+      <div>Progress: {Math.round(progress * 100)}%</div>
+      <button onClick={pause}>Pause</button>
+      <button onClick={resume}>Resume</button>
+    </div>
+  );
+}
+```
+
+### Hook Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `ref` | `RefObject<HTMLElement>` | Container element ref (required) |
+| `manifestUrl` | `string` | Explicit manifest URL |
+| `scene` | `string` | Scene name for auto-resolution |
+| `animationProps` | `Record<string, unknown>` | Props for auto-resolution |
+| `mode` | `"auto" \| "frames" \| "video"` | Playback mode |
+| `scrollRange` | `ScrollRangeValue` | Scroll range configuration |
+| `canvasDimensions` | `{ width?, height? }` | Canvas size |
+| `enabled` | `boolean` | Whether the hook is active |
+
+### Hook Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `progress` | `number` | Current scroll progress (0 to 1) |
+| `isReady` | `boolean` | Whether animation is loaded |
+| `error` | `Error \| null` | Loading error, if any |
+| `canvasRef` | `RefObject<HTMLCanvasElement>` | Canvas element ref |
+| `seek` | `(progress: number) => void` | Seek to specific progress |
+| `pause` | `() => void` | Pause scroll-driven updates |
+| `resume` | `() => void` | Resume scroll-driven updates |
+| `isPaused` | `boolean` | Whether updates are paused |
+
+## useNativeAnimation Hook
+
+For native SVG text animation without pre-rendered assets:
+
+```tsx
+import { useRef } from "react";
+import { useNativeAnimation } from "@mihirsarya/manim-scroll-react";
+
+function NativeTextAnimation() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const { progress, isReady } = useNativeAnimation({
+    ref: containerRef,
+    text: "Hello World",
+    fontSize: 48,
+    color: "#ffffff",
+  });
+
+  return (
+    <div ref={containerRef} style={{ height: "100vh" }}>
+      {!isReady && <div>Loading...</div>}
+    </div>
+  );
+}
+```
+
+### Hook Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `ref` | `RefObject<HTMLElement>` | Container element ref (required) |
+| `text` | `string` | Text to animate (required) |
+| `fontSize` | `number` | Font size in pixels (inherits from parent if not set) |
+| `color` | `string` | Text color |
+| `fontUrl` | `string` | URL to font file for opentype.js |
+| `strokeWidth` | `number` | Stroke width for drawing phase |
+| `scrollRange` | `ScrollRangeValue` | Scroll range configuration |
+| `enabled` | `boolean` | Whether the hook is active |
+
+## Scroll Range Configuration
+
+```tsx
+// Presets
+scrollRange="viewport"  // Animation plays as element crosses viewport
+scrollRange="element"   // Tied to element's own scroll position
+scrollRange="full"      // Spans entire document scroll
+
+// Relative units
+scrollRange={["100vh", "-50%"]}
+
+// Pixel values
+scrollRange={[800, -400]}
+scrollRange={{ start: 800, end: -400 }}
+```
+
+## License
+
+MIT

package/dist/ManimScroll.d.ts

@@ -34,7 +34,7 @@ export type ManimScrollProps = ManimAnimationProps & {
      * - "native": Uses native SVG animation (no pre-rendered assets)
      */
     mode?: "auto" | "frames" | "video" | "native";
-    /** Scroll range configuration (preset, tuple, or legacy object) */
+    /** Scroll range configuration (preset, tuple, or legacy object). Ignored when progress is provided. */
     scrollRange?: ScrollRangeValue;
     /** Called when animation is loaded and ready */
     onReady?: () => void;
@@ -49,6 +49,12 @@ export type ManimScrollProps = ManimAnimationProps & {
     fontUrl?: string;
     /** Stroke width for native mode drawing phase */
     strokeWidth?: number;
+    /**
+     * Explicit progress value (0 to 1). When provided, disables scroll-based control
+     * and renders the animation at this exact progress (controlled mode).
+     * Works with native mode. For advanced control, use useNativeAnimation hook.
+     */
+    progress?: number;
     className?: string;
     style?: React.CSSProperties;
     children?: React.ReactNode;
@@ -78,4 +84,4 @@ export type ManimScrollProps = ManimAnimationProps & {
  * </ManimScroll>
  * ```
  */
-export declare function ManimScroll({ className, style, children, canvas, manifestUrl, mode, scrollRange, onReady, onProgress, fontUrl, strokeWidth, scene, fontSize, color, font, inline, padding, ...customProps }: ManimScrollProps): JSX.Element;
+export declare function ManimScroll({ className, style, children, canvas, manifestUrl, mode, scrollRange, onReady, onProgress, fontUrl, strokeWidth, progress: controlledProgress, scene, fontSize, color, font, inline, padding, ...customProps }: ManimScrollProps): JSX.Element;

package/dist/ManimScroll.js

@@ -27,7 +27,7 @@ import { extractChildrenText } from "./hash";
  * </ManimScroll>
  * ```
  */
-export function ManimScroll({ className, style, children, canvas, manifestUrl, mode, scrollRange, onReady, onProgress, fontUrl, strokeWidth, 
+export function ManimScroll({ className, style, children, canvas, manifestUrl, mode, scrollRange, onReady, onProgress, fontUrl, strokeWidth, progress: controlledProgress, 
 // Animation props
 scene = "TextScene", fontSize, color, font, inline, padding, ...customProps }) {
     const containerRef = useRef(null);
@@ -72,6 +72,7 @@ scene = "TextScene", fontSize, color, font, inline, padding, ...customProps }) {
         fontUrl,
         strokeWidth,
         scrollRange,
+        progress: controlledProgress, // Pass progress for controlled mode
         enabled: isNativeMode,
     });
     // Select the appropriate result based on mode

package/dist/hooks.d.ts

@@ -100,27 +100,60 @@ export interface UseNativeAnimationOptions {
     fontUrl?: string;
     /** Stroke width for the drawing phase */
     strokeWidth?: number;
-    /** Scroll range configuration */
+    /** Scroll range configuration. Ignored when progress is provided. */
     scrollRange?: ScrollRangeValue;
+    /**
+     * Explicit progress value (0 to 1). When provided, disables scroll-based control
+     * and renders the animation at this exact progress (controlled mode).
+     */
+    progress?: number;
     /** Whether the hook is enabled (default: true) */
     enabled?: boolean;
 }
+/**
+ * Playback options for the play() method.
+ */
+export interface NativePlaybackOptions {
+    /** Animation duration in milliseconds */
+    duration?: number;
+    /** Delay before starting in milliseconds */
+    delay?: number;
+    /** Easing preset or custom function */
+    easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "smooth" | ((t: number) => number);
+    /** Whether to loop the animation */
+    loop?: boolean;
+    /** Play direction: 1 for forward, -1 for reverse */
+    direction?: 1 | -1;
+    /** Callback when playback completes */
+    onComplete?: () => void;
+}
 /**
  * Result returned by the useNativeAnimation hook.
  */
 export interface UseNativeAnimationResult {
-    /** Current scroll progress (0 to 1) */
+    /** Current animation progress (0 to 1) */
     progress: number;
     /** Whether the animation is loaded and ready */
     isReady: boolean;
     /** Error if initialization failed */
     error: Error | null;
-    /** Pause scroll-driven updates */
+    /** Pause scroll-driven updates (legacy, use pause() for playback) */
     pause: () => void;
-    /** Resume scroll-driven updates */
+    /** Resume scroll-driven updates (legacy) */
     resume: () => void;
     /** Whether scroll updates are paused */
     isPaused: boolean;
+    /**
+     * Play animation over a duration.
+     * @param options - Duration in ms, or PlaybackOptions object
+     */
+    play: (options?: NativePlaybackOptions | number) => void;
+    /** Seek to specific progress (0-1). Doesn't affect playing state. */
+    seek: (progress: number) => void;
+    /** Set progress and stop any playback. For controlled mode. */
+    setProgress: (progress: number) => void;
+    /** Whether time-based animation is currently playing */
+    isPlaying: boolean;
 }
 /**
  * Hook for native text animation that renders directly in the browser
@@ -129,23 +162,34 @@ export interface UseNativeAnimationResult {
  * This hook bypasses the manifest resolution and pre-rendered assets,
  * instead animating text natively using opentype.js and SVG.
  *
+ * Supports three usage modes:
+ * 1. Scroll-driven (default): Animation driven by scroll position
+ * 2. Controlled: Pass progress prop for React-style controlled components
+ * 3. Imperative: Use play(), seek(), setProgress() for programmatic control
+ *
  * @example
  * ```tsx
- * function NativeTextAnimation() {
- *   const containerRef = useRef<HTMLDivElement>(null);
- *   const { progress, isReady } = useNativeAnimation({
- *     ref: containerRef,
- *     text: "Hello World",
- *     fontSize: 48,
- *     color: "#ffffff",
- *   });
+ * // Scroll-driven mode (default)
+ * const { progress, isReady } = useNativeAnimation({
+ *   ref: containerRef,
+ *   text: "Hello World",
+ *   fontSize: 48,
+ * });
  *
- *   return (
- *     <div ref={containerRef} style={{ height: "100vh" }}>
- *       {!isReady && <div>Loading...</div>}
- *     </div>
- *   );
- * }
+ * // Controlled mode
+ * const [progress, setProgress] = useState(0);
+ * useNativeAnimation({
+ *   ref: containerRef,
+ *   text: "Hello World",
+ *   progress, // Animation renders at this exact progress
+ * });
+ *
+ * // Imperative mode
+ * const { play, isReady } = useNativeAnimation({
+ *   ref: containerRef,
+ *   text: "Hello World",
+ * });
+ * useEffect(() => { if (isReady) play(2000); }, [isReady]); // Play over 2s
  * ```
  */
 export declare function useNativeAnimation(options: UseNativeAnimationOptions): UseNativeAnimationResult;

package/dist/hooks.js

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState, useMemo, useCallback } from "react";
-import { registerScrollAnimation, registerNativeAnimation } from "@mihirsarya/manim-scroll-runtime";
+import { registerScrollAnimation, NativeTextPlayer } from "@mihirsarya/manim-scroll-runtime";
 import { computePropsHash } from "./hash";
 // Global cache manifest state
 let cachedManifest = null;
@@ -234,43 +234,55 @@ export { loadCacheManifest, resolveManifestUrl };
  * This hook bypasses the manifest resolution and pre-rendered assets,
  * instead animating text natively using opentype.js and SVG.
  *
+ * Supports three usage modes:
+ * 1. Scroll-driven (default): Animation driven by scroll position
+ * 2. Controlled: Pass progress prop for React-style controlled components
+ * 3. Imperative: Use play(), seek(), setProgress() for programmatic control
+ *
  * @example
  * ```tsx
- * function NativeTextAnimation() {
- *   const containerRef = useRef<HTMLDivElement>(null);
- *   const { progress, isReady } = useNativeAnimation({
- *     ref: containerRef,
- *     text: "Hello World",
- *     fontSize: 48,
- *     color: "#ffffff",
- *   });
+ * // Scroll-driven mode (default)
+ * const { progress, isReady } = useNativeAnimation({
+ *   ref: containerRef,
+ *   text: "Hello World",
+ *   fontSize: 48,
+ * });
  *
- *   return (
- *     <div ref={containerRef} style={{ height: "100vh" }}>
- *       {!isReady && <div>Loading...</div>}
- *     </div>
- *   );
- * }
+ * // Controlled mode
+ * const [progress, setProgress] = useState(0);
+ * useNativeAnimation({
+ *   ref: containerRef,
+ *   text: "Hello World",
+ *   progress, // Animation renders at this exact progress
+ * });
+ *
+ * // Imperative mode
+ * const { play, isReady } = useNativeAnimation({
+ *   ref: containerRef,
+ *   text: "Hello World",
+ * });
+ * useEffect(() => { if (isReady) play(2000); }, [isReady]); // Play over 2s
  * ```
  */
 export function useNativeAnimation(options) {
     const { ref, text, fontSize, // undefined means inherit from parent
     color = "#ffffff", fontUrl, strokeWidth = 2, // Manim's DrawBorderThenFill default
-    scrollRange, enabled = true, } = options;
-    const [progress, setProgress] = useState(0);
+    scrollRange, progress: controlledProgress, enabled = true, } = options;
+    const [progress, setProgressState] = useState(controlledProgress !== null && controlledProgress !== void 0 ? controlledProgress : 0);
     const [isReady, setIsReady] = useState(false);
     const [error, setError] = useState(null);
     const [isPaused, setIsPaused] = useState(false);
-    const cleanupRef = useRef(null);
+    const [isPlaying, setIsPlaying] = useState(false);
+    const playerRef = useRef(null);
     const pausedRef = useRef(isPaused);
     // Keep pausedRef in sync
     useEffect(() => {
         pausedRef.current = isPaused;
     }, [isPaused]);
-    // Handle progress updates (respects pause state)
+    // Handle progress updates (respects pause state for scroll-driven mode)
     const handleProgress = useCallback((p) => {
         if (!pausedRef.current) {
-            setProgress(p);
+            setProgressState(p);
         }
     }, []);
     // Handle ready callback
@@ -285,7 +297,7 @@ export function useNativeAnimation(options) {
         if (!container || !text)
             return;
         let isMounted = true;
-        const nativeOptions = {
+        const player = new NativeTextPlayer({
             container,
             text,
             fontSize,
@@ -293,16 +305,17 @@ export function useNativeAnimation(options) {
             fontUrl,
             strokeWidth,
             scrollRange,
+            progress: controlledProgress,
             onReady: handleReady,
             onProgress: handleProgress,
-        };
-        registerNativeAnimation(nativeOptions)
-            .then((dispose) => {
+        });
+        player.init()
+            .then(() => {
             if (!isMounted) {
-                dispose();
+                player.destroy();
                 return;
             }
-            cleanupRef.current = dispose;
+            playerRef.current = player;
         })
             .catch((err) => {
             if (isMounted) {
@@ -310,18 +323,60 @@ export function useNativeAnimation(options) {
             }
         });
         return () => {
-            var _a;
             isMounted = false;
-            (_a = cleanupRef.current) === null || _a === void 0 ? void 0 : _a.call(cleanupRef);
+            player.destroy();
+            playerRef.current = null;
             setIsReady(false);
         };
-    }, [enabled, ref, text, fontSize, color, fontUrl, strokeWidth, scrollRange, handleProgress, handleReady]);
+    }, [enabled, ref, text, fontSize, color, fontUrl, strokeWidth, scrollRange, controlledProgress, handleProgress, handleReady]);
+    // Update progress when controlled prop changes
+    useEffect(() => {
+        if (controlledProgress !== undefined && playerRef.current) {
+            playerRef.current.setProgress(controlledProgress);
+            setProgressState(controlledProgress);
+        }
+    }, [controlledProgress]);
+    // Legacy pause/resume for scroll-driven mode
     const pause = useCallback(() => {
         setIsPaused(true);
     }, []);
     const resume = useCallback(() => {
         setIsPaused(false);
     }, []);
+    // Playback controls
+    const play = useCallback((playOptions) => {
+        const player = playerRef.current;
+        if (!player)
+            return;
+        setIsPlaying(true);
+        if (typeof playOptions === "number") {
+            player.play({
+                duration: playOptions,
+                onComplete: () => setIsPlaying(false),
+            });
+        }
+        else {
+            player.play({
+                ...playOptions,
+                onComplete: () => {
+                    var _a;
+                    (_a = playOptions === null || playOptions === void 0 ? void 0 : playOptions.onComplete) === null || _a === void 0 ? void 0 : _a.call(playOptions);
+                    setIsPlaying(false);
+                },
+            });
+        }
+    }, []);
+    const seek = useCallback((targetProgress) => {
+        var _a;
+        (_a = playerRef.current) === null || _a === void 0 ? void 0 : _a.seek(targetProgress);
+        setProgressState(targetProgress);
+    }, []);
+    const setProgress = useCallback((targetProgress) => {
+        var _a;
+        (_a = playerRef.current) === null || _a === void 0 ? void 0 : _a.setProgress(targetProgress);
+        setProgressState(targetProgress);
+        setIsPlaying(false);
+    }, []);
     return {
         progress,
         isReady,
@@ -329,5 +384,9 @@ export function useNativeAnimation(options) {
         pause,
         resume,
         isPaused,
+        play,
+        seek,
+        setProgress,
+        isPlaying,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mihirsarya/manim-scroll-react",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "React wrapper for scroll-driven Manim animations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@mihirsarya/manim-scroll-runtime": "0.2.0"
+    "@mihirsarya/manim-scroll-runtime": "0.2.2"
   },
   "devDependencies": {
     "@types/react": "^18.2.61",