@mihirsarya/manim-scroll-react 0.1.1 → 0.2.0

package/dist/ManimScroll.d.ts

@@ -7,20 +7,33 @@ import type { ScrollRangeValue } from "@mihirsarya/manim-scroll-runtime";
 export interface ManimAnimationProps {
     /** Scene name (default: "TextScene") */
     scene?: string;
-    /** Font size for text animations */
+    /** Font size for text animations. If not specified in native mode, inherits from parent. */
     fontSize?: number;
     /** Color for the animation (hex string) */
     color?: string;
     /** Font family for text animations */
     font?: string;
+    /**
+     * Enable inline mode for text that flows with surrounding content.
+     * When true, renders with transparent background and tight bounds.
+     */
+    inline?: boolean;
+    /** Padding around the text in inline mode (Manim units, default: 0.2) */
+    padding?: number;
     /** Additional custom props for the scene */
     [key: string]: unknown;
 }
 export type ManimScrollProps = ManimAnimationProps & {
     /** Explicit manifest URL (overrides auto-resolution) */
     manifestUrl?: string;
-    /** Playback mode */
-    mode?: "auto" | "frames" | "video";
+    /**
+     * Playback mode:
+     * - "auto": Uses pre-rendered video or frames
+     * - "frames": Forces frame-by-frame playback
+     * - "video": Forces video playback
+     * - "native": Uses native SVG animation (no pre-rendered assets)
+     */
+    mode?: "auto" | "frames" | "video" | "native";
     /** Scroll range configuration (preset, tuple, or legacy object) */
     scrollRange?: ScrollRangeValue;
     /** Called when animation is loaded and ready */
@@ -32,6 +45,10 @@ export type ManimScrollProps = ManimAnimationProps & {
         width?: number;
         height?: number;
     };
+    /** URL to a font file for native mode (woff, woff2, ttf, otf) */
+    fontUrl?: string;
+    /** Stroke width for native mode drawing phase */
+    strokeWidth?: number;
     className?: string;
     style?: React.CSSProperties;
     children?: React.ReactNode;
@@ -41,6 +58,7 @@ export type ManimScrollProps = ManimAnimationProps & {
  *
  * Automatically resolves pre-rendered animation assets based on props,
  * or use an explicit `manifestUrl` for manual control.
+ * Use `mode="native"` for native SVG animation without pre-rendered assets.
  *
  * @example
  * ```tsx
@@ -53,6 +71,11 @@ export type ManimScrollProps = ManimAnimationProps & {
  * <ManimScroll manifestUrl="/assets/scene/manifest.json">
  *   Scroll-driven text
  * </ManimScroll>
+ *
+ * // Native mode (no pre-rendered assets)
+ * <ManimScroll mode="native" fontSize={48} color="#ffffff">
+ *   Animate this text
+ * </ManimScroll>
  * ```
  */
-export declare function ManimScroll({ className, style, children, canvas, manifestUrl, mode, scrollRange, onReady, onProgress, scene, fontSize, color, font, ...customProps }: ManimScrollProps): JSX.Element;
+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;

package/dist/ManimScroll.js

@@ -1,12 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef, useMemo, useEffect } from "react";
-import { useManimScroll } from "./hooks";
+import { useManimScroll, useNativeAnimation } from "./hooks";
 import { extractChildrenText } from "./hash";
 /**
  * Scroll-driven Manim animation component.
  *
  * Automatically resolves pre-rendered animation assets based on props,
  * or use an explicit `manifestUrl` for manual control.
+ * Use `mode="native"` for native SVG animation without pre-rendered assets.
  *
  * @example
  * ```tsx
@@ -19,15 +20,22 @@ import { extractChildrenText } from "./hash";
  * <ManimScroll manifestUrl="/assets/scene/manifest.json">
  *   Scroll-driven text
  * </ManimScroll>
+ *
+ * // Native mode (no pre-rendered assets)
+ * <ManimScroll mode="native" fontSize={48} color="#ffffff">
+ *   Animate this text
+ * </ManimScroll>
  * ```
  */
-export function ManimScroll({ className, style, children, canvas, manifestUrl, mode, scrollRange, onReady, onProgress, 
+export function ManimScroll({ className, style, children, canvas, manifestUrl, mode, scrollRange, onReady, onProgress, fontUrl, strokeWidth, 
 // Animation props
-scene = "TextScene", fontSize, color, font, ...customProps }) {
+scene = "TextScene", fontSize, color, font, inline, padding, ...customProps }) {
     const containerRef = useRef(null);
     // Extract text from children
     const childrenText = useMemo(() => extractChildrenText(children), [children]);
-    // Build animation props for hashing
+    // Determine if we're using native mode
+    const isNativeMode = mode === "native";
+    // Build animation props for hashing (used for pre-rendered mode)
     const animationProps = useMemo(() => {
         const props = { ...customProps };
         if (childrenText)
@@ -38,18 +46,36 @@ scene = "TextScene", fontSize, color, font, ...customProps }) {
             props.color = color;
         if (font !== undefined)
             props.font = font;
+        if (inline !== undefined)
+            props.inline = inline;
+        if (padding !== undefined)
+            props.padding = padding;
         return props;
-    }, [childrenText, fontSize, color, font, customProps]);
-    // Use the hook for all animation logic
-    const { isReady, error, progress } = useManimScroll({
+    }, [childrenText, fontSize, color, font, inline, padding, customProps]);
+    // Use appropriate hook based on mode
+    // Only one hook will be active at a time based on the enabled flag
+    const preRenderedResult = useManimScroll({
         ref: containerRef,
         manifestUrl,
         scene,
         animationProps,
-        mode,
+        mode: isNativeMode ? undefined : mode,
         scrollRange,
         canvasDimensions: canvas,
+        enabled: !isNativeMode,
+    });
+    const nativeResult = useNativeAnimation({
+        ref: containerRef,
+        text: childrenText || "",
+        fontSize, // undefined means inherit from parent
+        color: color !== null && color !== void 0 ? color : "#ffffff",
+        fontUrl,
+        strokeWidth,
+        scrollRange,
+        enabled: isNativeMode,
     });
+    // Select the appropriate result based on mode
+    const { isReady, error, progress } = isNativeMode ? nativeResult : preRenderedResult;
     // Forward callbacks
     useEffect(() => {
         if (isReady) {
@@ -59,7 +85,32 @@ scene = "TextScene", fontSize, color, font, ...customProps }) {
     useEffect(() => {
         onProgress === null || onProgress === void 0 ? void 0 : onProgress(progress);
     }, [progress, onProgress]);
-    return (_jsxs("div", { className: className, style: { position: "relative", ...style }, ref: containerRef, children: [_jsx("span", { style: { position: "absolute", opacity: 0 }, children: children }), error && process.env.NODE_ENV === "development" && (_jsx("div", { style: {
+    // Compute container styles based on inline mode and native mode
+    const containerStyle = useMemo(() => {
+        const baseStyle = {
+            position: "relative",
+            ...style,
+        };
+        if (inline || isNativeMode) {
+            return {
+                ...baseStyle,
+                // Use inline display for natural text flow
+                display: "inline",
+                // Align with surrounding text baseline for seamless integration
+                verticalAlign: "baseline",
+                // Ensure background is transparent for inline mode
+                background: "transparent",
+                // Inherit font properties for seamless text flow
+                fontFamily: "inherit",
+                lineHeight: "inherit",
+            };
+        }
+        return baseStyle;
+    }, [inline, isNativeMode, style]);
+    // Use span for inline mode or native mode to avoid invalid HTML (div inside p)
+    // Native mode typically flows inline with text, so use span for proper semantics
+    const Container = inline || isNativeMode ? "span" : "div";
+    return (_jsxs(Container, { className: className, style: containerStyle, ref: containerRef, children: [!isNativeMode && (_jsx("span", { style: { position: "absolute", opacity: 0 }, children: children })), error && process.env.NODE_ENV === "development" && (_jsx("span", { style: {
                     position: "absolute",
                     inset: 0,
                     display: "flex",

package/dist/hooks.d.ts

@@ -5,12 +5,14 @@ interface CacheManifest {
 }
 /**
  * Load the cache manifest from the public directory.
+ * In dev mode, refreshes the manifest periodically to pick up newly rendered animations.
  */
-declare function loadCacheManifest(): Promise<CacheManifest | null>;
+declare function loadCacheManifest(forceRefresh?: boolean): Promise<CacheManifest | null>;
 /**
  * Resolve the manifest URL for the given animation props.
+ * In dev mode, retries with manifest refresh if animation not found.
  */
-declare function resolveManifestUrl(scene: string, props: Record<string, unknown>): Promise<string | null>;
+declare function resolveManifestUrl(scene: string, props: Record<string, unknown>, retryCount?: number): Promise<string | null>;
 /**
  * Options for the useManimScroll hook.
  */
@@ -32,6 +34,8 @@ export interface UseManimScrollOptions {
         width?: number;
         height?: number;
     };
+    /** Whether the hook is enabled (default: true) */
+    enabled?: boolean;
 }
 /**
  * Result returned by the useManimScroll hook.
@@ -80,3 +84,68 @@ export interface UseManimScrollResult {
  */
 export declare function useManimScroll(options: UseManimScrollOptions): UseManimScrollResult;
 export { loadCacheManifest, resolveManifestUrl };
+/**
+ * Options for the useNativeAnimation hook.
+ */
+export interface UseNativeAnimationOptions {
+    /** Ref to the container element */
+    ref: React.RefObject<HTMLElement | null>;
+    /** The text to animate */
+    text: string;
+    /** Font size in pixels. If not specified, inherits from parent element. */
+    fontSize?: number;
+    /** Text color (hex or CSS color) */
+    color?: string;
+    /** URL to a font file (woff, woff2, ttf, otf) for opentype.js */
+    fontUrl?: string;
+    /** Stroke width for the drawing phase */
+    strokeWidth?: number;
+    /** Scroll range configuration */
+    scrollRange?: ScrollRangeValue;
+    /** Whether the hook is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Result returned by the useNativeAnimation hook.
+ */
+export interface UseNativeAnimationResult {
+    /** Current scroll 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: () => void;
+    /** Resume scroll-driven updates */
+    resume: () => void;
+    /** Whether scroll updates are paused */
+    isPaused: boolean;
+}
+/**
+ * Hook for native text animation that renders directly in the browser
+ * using SVG, replicating Manim's Write/DrawBorderThenFill effect.
+ *
+ * This hook bypasses the manifest resolution and pre-rendered assets,
+ * instead animating text natively using opentype.js and SVG.
+ *
+ * @example
+ * ```tsx
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+export declare function useNativeAnimation(options: UseNativeAnimationOptions): UseNativeAnimationResult;

package/dist/hooks.js

@@ -1,36 +1,68 @@
 import { useEffect, useRef, useState, useMemo, useCallback } from "react";
-import { registerScrollAnimation } from "@mihirsarya/manim-scroll-runtime";
+import { registerScrollAnimation, registerNativeAnimation } from "@mihirsarya/manim-scroll-runtime";
 import { computePropsHash } from "./hash";
-// Global cache manifest (loaded once)
-let cacheManifestPromise = null;
+// Global cache manifest state
+let cachedManifest = null;
+let manifestFetchPromise = null;
+let lastFetchTime = 0;
+// In dev mode, allow manifest to be refreshed every 2 seconds
+const MANIFEST_CACHE_TTL = process.env.NODE_ENV === "development" ? 2000 : Infinity;
 /**
  * Load the cache manifest from the public directory.
+ * In dev mode, refreshes the manifest periodically to pick up newly rendered animations.
  */
-async function loadCacheManifest() {
-    if (cacheManifestPromise) {
-        return cacheManifestPromise;
+async function loadCacheManifest(forceRefresh = false) {
+    const now = Date.now();
+    const isStale = now - lastFetchTime > MANIFEST_CACHE_TTL;
+    // Return cached manifest if fresh
+    if (cachedManifest && !isStale && !forceRefresh) {
+        return cachedManifest;
     }
-    cacheManifestPromise = fetch("/manim-assets/cache-manifest.json")
+    // If already fetching, wait for that
+    if (manifestFetchPromise && !forceRefresh) {
+        return manifestFetchPromise;
+    }
+    lastFetchTime = now;
+    manifestFetchPromise = fetch("/manim-assets/cache-manifest.json", {
+        cache: forceRefresh ? "no-store" : "default",
+    })
         .then((response) => {
         if (!response.ok) {
             return null;
         }
         return response.json();
     })
-        .catch(() => null);
-    return cacheManifestPromise;
+        .then((manifest) => {
+        cachedManifest = manifest;
+        manifestFetchPromise = null;
+        return manifest;
+    })
+        .catch(() => {
+        manifestFetchPromise = null;
+        return null;
+    });
+    return manifestFetchPromise;
 }
 /**
  * Resolve the manifest URL for the given animation props.
+ * In dev mode, retries with manifest refresh if animation not found.
  */
-async function resolveManifestUrl(scene, props) {
-    var _a;
-    const manifest = await loadCacheManifest();
+async function resolveManifestUrl(scene, props, retryCount = 0) {
+    const manifest = await loadCacheManifest(retryCount > 0);
     if (!manifest) {
         return null;
     }
     const hash = computePropsHash(scene, props);
-    return (_a = manifest.animations[hash]) !== null && _a !== void 0 ? _a : null;
+    const url = manifest.animations[hash];
+    if (url) {
+        return url;
+    }
+    // In dev mode, retry a few times as animations might still be rendering
+    if (process.env.NODE_ENV === "development" && retryCount < 5) {
+        await new Promise((resolve) => setTimeout(resolve, 1000 * (retryCount + 1)));
+        return resolveManifestUrl(scene, props, retryCount + 1);
+    }
+    return null;
 }
 /**
  * Hook for advanced scroll-driven Manim animation control.
@@ -57,7 +89,7 @@ async function resolveManifestUrl(scene, props) {
  * ```
  */
 export function useManimScroll(options) {
-    const { ref, manifestUrl: explicitManifestUrl, scene = "TextScene", animationProps = {}, mode, scrollRange, canvasDimensions, } = options;
+    const { ref, manifestUrl: explicitManifestUrl, scene = "TextScene", animationProps = {}, mode, scrollRange, canvasDimensions, enabled = true, } = options;
     const [progress, setProgress] = useState(0);
     const [isReady, setIsReady] = useState(false);
     const [error, setError] = useState(null);
@@ -76,6 +108,8 @@ export function useManimScroll(options) {
     [JSON.stringify(animationProps)]);
     // Resolve manifest URL if not explicitly provided
     useEffect(() => {
+        if (!enabled)
+            return;
         if (explicitManifestUrl) {
             setResolvedManifestUrl(explicitManifestUrl);
             setError(null);
@@ -91,7 +125,7 @@ export function useManimScroll(options) {
                     `Make sure to run the build with @mihirsarya/manim-scroll-next.`));
             }
         });
-    }, [explicitManifestUrl, scene, memoizedAnimationProps]);
+    }, [enabled, explicitManifestUrl, scene, memoizedAnimationProps]);
     // Handle progress updates (respects pause state)
     const handleProgress = useCallback((p) => {
         if (!pausedRef.current) {
@@ -105,6 +139,8 @@ export function useManimScroll(options) {
     // Register scroll animation
     useEffect(() => {
         var _a;
+        if (!enabled)
+            return;
         const container = ref.current;
         if (!container || !resolvedManifestUrl)
             return;
@@ -115,8 +151,18 @@ export function useManimScroll(options) {
             canvasEl.width = canvasDimensions.width;
         if (canvasDimensions === null || canvasDimensions === void 0 ? void 0 : canvasDimensions.height)
             canvasEl.height = canvasDimensions.height;
+        // Check if inline mode
+        const isInline = animationProps.inline === true;
         // Only append if we created the canvas
         if (!canvasRef.current) {
+            if (!isInline) {
+                // Block mode: fill container
+                canvasEl.style.width = "100%";
+                canvasEl.style.height = "100%";
+                canvasEl.style.objectFit = "contain";
+                canvasEl.style.display = "block";
+            }
+            // For inline mode, let the player set styles based on manifest data
             container.appendChild(canvasEl);
         }
         registerScrollAnimation({
@@ -145,6 +191,7 @@ export function useManimScroll(options) {
             setIsReady(false);
         };
     }, [
+        enabled,
         ref,
         resolvedManifestUrl,
         mode,
@@ -180,3 +227,107 @@ export function useManimScroll(options) {
 }
 // Re-export helper functions for use by the component
 export { loadCacheManifest, resolveManifestUrl };
+/**
+ * Hook for native text animation that renders directly in the browser
+ * using SVG, replicating Manim's Write/DrawBorderThenFill effect.
+ *
+ * This hook bypasses the manifest resolution and pre-rendered assets,
+ * instead animating text natively using opentype.js and SVG.
+ *
+ * @example
+ * ```tsx
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+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);
+    const [isReady, setIsReady] = useState(false);
+    const [error, setError] = useState(null);
+    const [isPaused, setIsPaused] = useState(false);
+    const cleanupRef = useRef(null);
+    const pausedRef = useRef(isPaused);
+    // Keep pausedRef in sync
+    useEffect(() => {
+        pausedRef.current = isPaused;
+    }, [isPaused]);
+    // Handle progress updates (respects pause state)
+    const handleProgress = useCallback((p) => {
+        if (!pausedRef.current) {
+            setProgress(p);
+        }
+    }, []);
+    // Handle ready callback
+    const handleReady = useCallback(() => {
+        setIsReady(true);
+    }, []);
+    // Register native animation
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const container = ref.current;
+        if (!container || !text)
+            return;
+        let isMounted = true;
+        const nativeOptions = {
+            container,
+            text,
+            fontSize,
+            color,
+            fontUrl,
+            strokeWidth,
+            scrollRange,
+            onReady: handleReady,
+            onProgress: handleProgress,
+        };
+        registerNativeAnimation(nativeOptions)
+            .then((dispose) => {
+            if (!isMounted) {
+                dispose();
+                return;
+            }
+            cleanupRef.current = dispose;
+        })
+            .catch((err) => {
+            if (isMounted) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        return () => {
+            var _a;
+            isMounted = false;
+            (_a = cleanupRef.current) === null || _a === void 0 ? void 0 : _a.call(cleanupRef);
+            setIsReady(false);
+        };
+    }, [enabled, ref, text, fontSize, color, fontUrl, strokeWidth, scrollRange, handleProgress, handleReady]);
+    const pause = useCallback(() => {
+        setIsPaused(true);
+    }, []);
+    const resume = useCallback(() => {
+        setIsPaused(false);
+    }, []);
+    return {
+        progress,
+        isReady,
+        error,
+        pause,
+        resume,
+        isPaused,
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ManimScroll } from "./ManimScroll";
 export type { ManimScrollProps, ManimAnimationProps } from "./ManimScroll";
-export { useManimScroll } from "./hooks";
-export type { UseManimScrollOptions, UseManimScrollResult } from "./hooks";
+export { useManimScroll, useNativeAnimation } from "./hooks";
+export type { UseManimScrollOptions, UseManimScrollResult, UseNativeAnimationOptions, UseNativeAnimationResult, } from "./hooks";
 export { computePropsHash, extractChildrenText } from "./hash";

package/dist/index.js

@@ -1,3 +1,3 @@
 export { ManimScroll } from "./ManimScroll";
-export { useManimScroll } from "./hooks";
+export { useManimScroll, useNativeAnimation } from "./hooks";
 export { computePropsHash, extractChildrenText } from "./hash";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mihirsarya/manim-scroll-react",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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.1.1"
+    "@mihirsarya/manim-scroll-runtime": "0.2.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.61",