@mihirsarya/manim-scroll-react 0.2.1 → 0.2.2

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.1",
+  "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.1"
+    "@mihirsarya/manim-scroll-runtime": "0.2.2"
   },
   "devDependencies": {
     "@types/react": "^18.2.61",