@mihirsarya/manim-scroll-next 0.1.5 → 0.2.1

package/README.md

@@ -0,0 +1,265 @@
+# @mihirsarya/manim-scroll-next
+
+Next.js plugin for build-time Manim scroll animation rendering. Automatically scans your source files, extracts `<ManimScroll>` components, and renders animations with smart caching.
+
+## Installation
+
+```bash
+npm install @mihirsarya/manim-scroll-next
+```
+
+Or use the unified package (recommended):
+
+```bash
+npm install @mihirsarya/manim-scroll
+```
+
+## Requirements
+
+- Next.js 13+
+- Python 3.8+ with [Manim](https://www.manim.community/) installed
+
+## Quick Start
+
+### 1. Configure Next.js
+
+```js
+// next.config.js
+const { withManimScroll } = require("@mihirsarya/manim-scroll-next");
+// Or: const { withManimScroll } = require("@mihirsarya/manim-scroll/next");
+
+module.exports = withManimScroll({
+  manimScroll: {
+    pythonPath: "python3",
+    quality: "h",
+  },
+});
+```
+
+### 2. Use ManimScroll Components
+
+```tsx
+// app/page.tsx
+import { ManimScroll } from "@mihirsarya/manim-scroll-react";
+// Or: import { ManimScroll } from "@mihirsarya/manim-scroll";
+
+export default function Home() {
+  return (
+    <ManimScroll
+      scene="TextScene"
+      fontSize={72}
+      color="#ffffff"
+    >
+      Welcome to my site
+    </ManimScroll>
+  );
+}
+```
+
+### 3. Build
+
+```bash
+next build
+```
+
+The plugin:
+1. Scans your source files for `<ManimScroll>` components
+2. Extracts props and children text
+3. Computes a hash for each unique animation
+4. Renders only new/changed animations (cached by hash)
+5. Outputs assets to `public/manim-assets/`
+
+## Configuration
+
+### Combined Config (Recommended)
+
+```js
+module.exports = withManimScroll({
+  // Next.js config
+  reactStrictMode: true,
+  
+  // Manim Scroll config
+  manimScroll: {
+    pythonPath: "python3",
+    quality: "h",
+    fps: 30,
+    resolution: "1920x1080",
+    verbose: true,
+  },
+});
+```
+
+### Separate Configs
+
+```js
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+module.exports = withManimScroll(nextConfig, {
+  pythonPath: "python3",
+  quality: "h",
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pythonPath` | `string` | `"python3"` | Path to Python executable |
+| `cliPath` | `string` | Built-in | Path to render CLI script |
+| `templatesDir` | `string` | Built-in | Path to scene templates |
+| `quality` | `string` | `"h"` | Manim quality preset (`l`, `m`, `h`, `k`) |
+| `fps` | `number` | `30` | Frames per second |
+| `resolution` | `string` | `"1920x1080"` | Output resolution (`WIDTHxHEIGHT`) |
+| `format` | `string` | `"both"` | Output format (`frames`, `video`, `both`) |
+| `concurrency` | `number` | CPU count - 1 | Max parallel renders |
+| `include` | `string[]` | `["**/*.tsx", "**/*.jsx"]` | Glob patterns to scan |
+| `exclude` | `string[]` | `["node_modules/**", ".next/**"]` | Glob patterns to exclude |
+| `cleanOrphans` | `boolean` | `true` | Remove unused cached assets |
+| `verbose` | `boolean` | `false` | Enable verbose logging |
+
+## Exports
+
+### Main Export
+
+- **`withManimScroll(config, manimConfig?)`** - Next.js config wrapper
+
+### Types
+
+- `ManimScrollConfig` - Plugin configuration type
+- `NextConfigWithManimScroll` - Extended Next.js config type
+
+### Utilities (Advanced)
+
+```ts
+import {
+  extractAnimations,
+  renderAnimations,
+  computePropsHash,
+  isCached,
+  getCacheEntry,
+  getAnimationsToRender,
+  writeCacheManifest,
+  readCacheManifest,
+  cleanOrphanedCache,
+  processManimScroll,
+} from "@mihirsarya/manim-scroll-next";
+```
+
+## How It Works
+
+### 1. Extraction
+
+The plugin uses Babel to parse your source files and extract `<ManimScroll>` component usages:
+
+```tsx
+<ManimScroll scene="TextScene" fontSize={72} color="#fff">
+  Hello World
+</ManimScroll>
+```
+
+Becomes:
+
+```ts
+{
+  id: "app/page.tsx:ManimScroll:1",
+  scene: "TextScene",
+  props: { text: "Hello World", fontSize: 72, color: "#fff" }
+}
+```
+
+### 2. Caching
+
+Each animation is hashed based on `scene + props`. The cache manifest at `public/manim-assets/cache-manifest.json` maps hashes to rendered asset directories:
+
+```json
+{
+  "version": 1,
+  "animations": {
+    "abc123...": "/manim-assets/abc123.../manifest.json"
+  }
+}
+```
+
+### 3. Rendering
+
+New animations are rendered using the bundled Python CLI:
+
+```bash
+python render/cli.py \
+  --scene-file render/templates/text_scene.py \
+  --scene-name TextScene \
+  --props '{"text": "Hello World", "fontSize": 72}' \
+  --output-dir public/manim-assets/abc123...
+```
+
+### 4. Asset Structure
+
+```
+public/manim-assets/
+├── cache-manifest.json
+├── abc123.../
+│   ├── manifest.json
+│   ├── media/
+│   │   ├── videos/...
+│   │   └── images/...
+└── def456.../
+    └── ...
+```
+
+## Development Mode
+
+In dev mode (`next dev`), the plugin:
+- Creates an empty cache manifest immediately to prevent 404s
+- Processes animations asynchronously in the background
+- Retries manifest resolution if animations are still rendering
+
+## Custom Build Scripts
+
+For advanced workflows, use the exported utilities:
+
+```ts
+import { extractAnimations, renderAnimations } from "@mihirsarya/manim-scroll-next";
+
+async function customBuild() {
+  const animations = await extractAnimations({
+    rootDir: process.cwd(),
+    include: ["src/**/*.tsx"],
+  });
+
+  const results = await renderAnimations(animations, "./public", {
+    pythonPath: "python3",
+    quality: "h",
+  });
+
+  console.log(`Rendered ${results.filter(r => r.success).length} animations`);
+}
+```
+
+## Troubleshooting
+
+### Manim not found
+
+Ensure Manim is installed and accessible:
+
+```bash
+python3 -c "import manim; print(manim.__version__)"
+```
+
+### Animations not updating
+
+The cache is based on props hash. To force re-render:
+
+1. Delete `public/manim-assets/`
+2. Or change a prop value
+
+### Slow builds
+
+- Reduce `quality` (use `"l"` or `"m"` for development)
+- Increase `concurrency` if you have more CPU cores
+- Use `format: "frames"` to skip video encoding
+
+## License
+
+MIT

package/dist/extractor.js

@@ -189,8 +189,25 @@ function isManimScrollComponent(node) {
     }
     return false;
 }
+/**
+ * Props that should NOT be included in the animation hash.
+ * These are display/scroll-related props, not animation-specific props.
+ * This list must stay in sync with what ManimScroll.tsx excludes from animationProps.
+ */
+const EXCLUDED_PROPS = new Set([
+    "manifestUrl",
+    "mode",
+    "scrollRange",
+    "onReady",
+    "onProgress",
+    "canvas",
+    "className",
+    "style",
+    "children", // children is handled separately as "text"
+]);
 /**
  * Extract ManimScroll component data from a JSX element.
+ * Returns null if the component uses native mode (no pre-rendering needed).
  */
 function extractManimScroll(jsxElement, filePath) {
     var _a, _b;
@@ -200,6 +217,7 @@ function extractManimScroll(jsxElement, filePath) {
     }
     const props = {};
     let scene = "TextScene";
+    let mode;
     // Extract attributes
     for (const attr of openingElement.attributes) {
         if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name)) {
@@ -208,8 +226,11 @@ function extractManimScroll(jsxElement, filePath) {
             if (name === "scene" && typeof value === "string") {
                 scene = value;
             }
-            else if (name === "manifestUrl") {
-                // Skip manifestUrl - this is for explicit mode
+            else if (name === "mode" && typeof value === "string") {
+                mode = value;
+            }
+            else if (EXCLUDED_PROPS.has(name)) {
+                // Skip display/scroll-related props - only include animation-specific props
                 continue;
             }
             else if (value !== undefined) {
@@ -217,6 +238,10 @@ function extractManimScroll(jsxElement, filePath) {
             }
         }
     }
+    // Skip native mode components - they render in the browser without pre-rendering
+    if (mode === "native") {
+        return null;
+    }
     // Extract children as text prop
     const childrenText = extractChildrenText(jsxElement.children);
     if (childrenText) {

package/dist/extractor.test.js

@@ -237,6 +237,38 @@ vitest_1.vi.mock("glob", () => ({
         (0, vitest_1.expect)(result).toHaveLength(1);
         (0, vitest_1.expect)(result[0].props.data).toEqual({ "123": "value" });
     });
+    (0, vitest_1.it)("should exclude display/scroll-related props from animation props", () => {
+        vitest_1.vi.mocked(fs.existsSync).mockReturnValue(true);
+        vitest_1.vi.mocked(fs.readFileSync).mockReturnValue(`
+      <ManimScroll
+        fontSize={72}
+        color="#ffffff"
+        scrollRange="viewport"
+        style={{ width: "100%", height: "100%" }}
+        className="animation-container"
+        mode="frames"
+        onReady={() => {}}
+        onProgress={(p) => console.log(p)}
+        canvas={{ width: 1920, height: 1080 }}
+      >
+        Hello World
+      </ManimScroll>
+    `);
+        const result = (0, extractor_1.extractAnimationsFromFile)("/app/page.tsx");
+        (0, vitest_1.expect)(result).toHaveLength(1);
+        // Animation props should be included
+        (0, vitest_1.expect)(result[0].props.fontSize).toBe(72);
+        (0, vitest_1.expect)(result[0].props.color).toBe("#ffffff");
+        (0, vitest_1.expect)(result[0].props.text).toBe("Hello World");
+        // Display/scroll props should be excluded
+        (0, vitest_1.expect)(result[0].props.scrollRange).toBeUndefined();
+        (0, vitest_1.expect)(result[0].props.style).toBeUndefined();
+        (0, vitest_1.expect)(result[0].props.className).toBeUndefined();
+        (0, vitest_1.expect)(result[0].props.mode).toBeUndefined();
+        (0, vitest_1.expect)(result[0].props.onReady).toBeUndefined();
+        (0, vitest_1.expect)(result[0].props.onProgress).toBeUndefined();
+        (0, vitest_1.expect)(result[0].props.canvas).toBeUndefined();
+    });
 });
 (0, vitest_1.describe)("extractChildrenText (via extractor)", () => {
     (0, vitest_1.beforeEach)(() => {

package/dist/index.d.ts

@@ -35,9 +35,11 @@ declare function processManimScroll(projectDir: string, config: ManimScrollConfi
 /**
  * Wrap a Next.js config with ManimScroll build-time processing.
  *
+ * Supports two calling patterns:
+ *
  * @example
  * ```js
- * // next.config.js
+ * // Pattern 1: Combined config (recommended)
  * const { withManimScroll } = require("@mihirsarya/manim-scroll-next");
  *
  * module.exports = withManimScroll({
@@ -47,8 +49,17 @@ declare function processManimScroll(projectDir: string, config: ManimScrollConfi
  *   },
  * });
  * ```
+ *
+ * @example
+ * ```js
+ * // Pattern 2: Separate configs
+ * module.exports = withManimScroll(nextConfig, {
+ *   pythonPath: "python3",
+ *   quality: "h",
+ * });
+ * ```
  */
-export declare function withManimScroll(nextConfig?: NextConfigWithManimScroll): NextConfig;
+export declare function withManimScroll(nextConfig?: NextConfigWithManimScroll, manimScrollConfig?: ManimScrollConfig): NextConfig;
 export { extractAnimations, type ExtractedAnimation } from "./extractor";
 export { computePropsHash, isCached, getCacheEntry, getAnimationsToRender, writeCacheManifest, readCacheManifest, cleanOrphanedCache, } from "./cache";
 export { renderAnimations, type RenderResult, type RenderOptions } from "./renderer";

package/dist/index.js

@@ -36,10 +36,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderAnimations = exports.cleanOrphanedCache = exports.readCacheManifest = exports.writeCacheManifest = exports.getAnimationsToRender = exports.getCacheEntry = exports.isCached = exports.computePropsHash = exports.extractAnimations = void 0;
 exports.withManimScroll = withManimScroll;
 exports.processManimScroll = processManimScroll;
+const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const extractor_1 = require("./extractor");
 const cache_1 = require("./cache");
 const renderer_1 = require("./renderer");
+/**
+ * Ensure a cache manifest file exists (preserving existing entries).
+ * This is called synchronously so the file exists before the page loads.
+ */
+function ensureCacheManifestExists(publicDir) {
+    const manifestPath = path.join(publicDir, "manim-assets", "cache-manifest.json");
+    // If manifest already exists, leave it alone
+    if (fs.existsSync(manifestPath)) {
+        return;
+    }
+    // Create the directory and an empty manifest
+    (0, cache_1.ensureAssetDir)(publicDir);
+    fs.writeFileSync(manifestPath, JSON.stringify({ version: 1, animations: {} }, null, 2));
+}
 let hasProcessed = false;
 /**
  * Process ManimScroll components: extract, cache, and render.
@@ -74,6 +89,11 @@ async function processManimScroll(projectDir, config) {
             console.log(`  - ${animation.id} (hash: ${hash})`);
         }
     }
+    // Write the cache manifest IMMEDIATELY after extraction, before rendering.
+    // This ensures the manifest is available when the page loads, even if
+    // rendering is still in progress. The runtime will gracefully handle
+    // missing animation files.
+    (0, cache_1.writeCacheManifest)(animations, publicDir);
     // Determine which need rendering
     const { cached, toRender } = (0, cache_1.getAnimationsToRender)(animations, publicDir);
     if (verbose && cached.length > 0) {
@@ -101,8 +121,6 @@ async function processManimScroll(projectDir, config) {
     else if (verbose) {
         console.log("[manim-scroll] All animations are cached, skipping render.");
     }
-    // Write the cache manifest for runtime lookup
-    (0, cache_1.writeCacheManifest)(animations, publicDir);
     // Clean up orphaned cache entries
     if (config.cleanOrphans !== false) {
         (0, cache_1.cleanOrphanedCache)(animations, publicDir);
@@ -112,9 +130,11 @@ async function processManimScroll(projectDir, config) {
 /**
  * Wrap a Next.js config with ManimScroll build-time processing.
  *
+ * Supports two calling patterns:
+ *
  * @example
  * ```js
- * // next.config.js
+ * // Pattern 1: Combined config (recommended)
  * const { withManimScroll } = require("@mihirsarya/manim-scroll-next");
  *
  * module.exports = withManimScroll({
@@ -124,10 +144,22 @@ async function processManimScroll(projectDir, config) {
  *   },
  * });
  * ```
+ *
+ * @example
+ * ```js
+ * // Pattern 2: Separate configs
+ * module.exports = withManimScroll(nextConfig, {
+ *   pythonPath: "python3",
+ *   quality: "h",
+ * });
+ * ```
  */
-function withManimScroll(nextConfig = {}) {
+function withManimScroll(nextConfig = {}, manimScrollConfig) {
     var _a;
-    const manimConfig = (_a = nextConfig.manimScroll) !== null && _a !== void 0 ? _a : {};
+    // Support both calling patterns:
+    // 1. withManimScroll({ manimScroll: {...} })
+    // 2. withManimScroll(nextConfig, { pythonPath: ... })
+    const manimConfig = (_a = manimScrollConfig !== null && manimScrollConfig !== void 0 ? manimScrollConfig : nextConfig.manimScroll) !== null && _a !== void 0 ? _a : {};
     // Remove manimScroll from the config passed to Next.js
     const { manimScroll: _, ...restConfig } = nextConfig;
     return {
@@ -153,7 +185,13 @@ function withManimScroll(nextConfig = {}) {
             }
             // Run in dev mode on first build
             if (context.dev && context.isServer) {
-                processManimScroll(context.dir, manimConfig).catch((error) => {
+                const projectDir = context.dir;
+                const publicDir = path.join(projectDir, "public");
+                // Ensure a cache manifest exists SYNCHRONOUSLY before the page loads.
+                // This prevents 404 errors while async processing is running.
+                // The manifest will be updated with actual animations once extraction completes.
+                ensureCacheManifestExists(publicDir);
+                processManimScroll(projectDir, manimConfig).catch((error) => {
                     console.error("[manim-scroll] Error during dev processing:", error);
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mihirsarya/manim-scroll-next",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Next.js plugin for build-time Manim scroll animation rendering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,11 +8,6 @@
     "dist",
     "render"
   ],
-  "scripts": {
-    "prebuild": "rm -rf render && cp -r ../render .",
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "rm -rf render && cp -r ../render . && npm run build"
-  },
   "peerDependencies": {
     "next": ">=13.0.0"
   },
@@ -26,5 +21,9 @@
     "@types/babel__traverse": "^7.20.5",
     "@types/node": "^20.11.0",
     "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "prebuild": "rm -rf render && cp -r ../render .",
+    "build": "tsc -p tsconfig.json"
   }
-}
+}

package/render/cli.py

@@ -6,7 +6,7 @@ import json
 import os
 import subprocess
 import sys
-from dataclasses import dataclass, asdict
+from dataclasses import dataclass, asdict, field
 from pathlib import Path
 from typing import List, Optional
 
@@ -19,6 +19,9 @@ class RenderManifest:
     height: int
     frames: List[str]
     video: Optional[str]
+    transparent: bool = False
+    inline: bool = False
+    aspectRatio: Optional[float] = None
 
 
 def _parse_resolution(value: str) -> tuple[int, int]:
@@ -51,6 +54,16 @@ def _run_manim(cmd: List[str], env: dict[str, str]) -> None:
         raise RuntimeError("Manim render failed. Check the command and logs.")
 
 
+def _load_props_file(props_path: Optional[str]) -> dict:
+    """Load props from a JSON file."""
+    if not props_path:
+        return {}
+    path = Path(props_path)
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text())
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description="Render Manim scenes for scroll playback.")
     parser.add_argument("--scene-file", required=True, help="Path to Manim scene file.")
@@ -65,11 +78,20 @@ def main() -> int:
         "--props",
         help="Path to JSON props for the scene (exposed as MANIM_SCROLL_PROPS).",
     )
+    parser.add_argument(
+        "--transparent",
+        action="store_true",
+        help="Render with transparent background (for inline mode).",
+    )
 
     args = parser.parse_args()
     output_dir = Path(args.output_dir).resolve()
     output_dir.mkdir(parents=True, exist_ok=True)
 
+    # Load props to check for inline mode
+    props = _load_props_file(args.props)
+    inline = props.get("inline", False) or args.transparent
+
     width, height = args.resolution
     base_cmd = [
         "manim",
@@ -84,18 +106,38 @@ def main() -> int:
         args.scene_name,
     ]
 
+    # Add transparent flag for inline mode
+    if inline or args.transparent:
+        base_cmd.insert(1, "--transparent")
+
     env = os.environ.copy()
     if args.props:
         props_path = Path(args.props).resolve()
         env["MANIM_SCROLL_PROPS"] = str(props_path)
 
+    # Set up bounds output file for inline mode
+    bounds_path = output_dir / "bounds.json"
+    env["MANIM_SCROLL_BOUNDS_OUT"] = str(bounds_path)
+
     if args.format in ("frames", "both"):
         _run_manim(base_cmd + ["--write_all", "--format", "png"], env)
 
     if args.format in ("video", "both"):
-        _run_manim(base_cmd + ["--format", args.video_format], env)
+        # For transparent video, use webm which supports alpha
+        video_format = "webm" if (inline or args.transparent) else args.video_format
+        _run_manim(base_cmd + ["--format", video_format], env)
 
     frames, video = _collect_assets(output_dir)
+    
+    # For inline mode, try to read bounds info to get aspect ratio
+    aspect_ratio = None
+    if bounds_path.exists():
+        try:
+            bounds_data = json.loads(bounds_path.read_text())
+            aspect_ratio = bounds_data.get("aspectRatio")
+        except Exception:
+            pass
+    
     manifest = RenderManifest(
         scene=args.scene_name,
         fps=args.fps,
@@ -103,6 +145,9 @@ def main() -> int:
         height=height,
         frames=frames,
         video=video,
+        transparent=inline or args.transparent,
+        inline=inline,
+        aspectRatio=aspect_ratio,
     )
     manifest_path = output_dir / "manifest.json"
     manifest_path.write_text(json.dumps(asdict(manifest), indent=2))

package/render/templates/text_scene.py

@@ -4,7 +4,7 @@ import json
 import os
 from pathlib import Path
 
-from manim import ORIGIN, Scene, Text, Write
+from manim import ORIGIN, Scene, Text, Write, config
 
 
 def _load_props() -> dict:
@@ -18,6 +18,21 @@ def _load_props() -> dict:
         return json.load(handle)
 
 
+def _write_bounds_info(width: float, height: float, aspect_ratio: float, props: dict) -> None:
+    """Write text bounds info to a file for the manifest generator."""
+    bounds_path = os.environ.get("MANIM_SCROLL_BOUNDS_OUT")
+    if not bounds_path:
+        return
+    bounds = {
+        "textWidth": width,
+        "textHeight": height,
+        "aspectRatio": aspect_ratio,
+        "inline": props.get("inline", False),
+        "padding": props.get("padding", 0),
+    }
+    Path(bounds_path).write_text(json.dumps(bounds))
+
+
 class TextScene(Scene):
     def construct(self) -> None:
         props = _load_props()
@@ -25,12 +40,35 @@ class TextScene(Scene):
         font_size = props.get("fontSize", props.get("font_size", 64))
         color = props.get("color", "#FFFFFF")
         font = props.get("font")
+        inline = props.get("inline", False)
+        padding = props.get("padding", 0.1)  # Small padding in Manim units
 
         if font:
             text_mob = Text(text_value, font_size=font_size, color=color, font=font)
         else:
             text_mob = Text(text_value, font_size=font_size, color=color)
 
+        if inline:
+            # For inline mode, adjust the camera frame to fit the text tightly
+            # This makes the text fill the entire frame
+            text_width = text_mob.width
+            text_height = text_mob.height
+
+            # Add minimal padding
+            padded_width = text_width + padding * 2
+            padded_height = text_height + padding * 2
+
+            # Calculate aspect ratio
+            aspect_ratio = padded_width / padded_height if padded_height > 0 else 1
+
+            # Adjust the Manim frame to match text bounds
+            # This sets the "virtual" frame size in Manim units
+            config.frame_width = padded_width
+            config.frame_height = padded_height
+
+            # Write bounds info for the manifest
+            _write_bounds_info(text_width, text_height, aspect_ratio, props)
+
         text_mob.move_to(ORIGIN)
         self.play(Write(text_mob))
         self.wait(0.5)