@mihirsarya/manim-scroll-runtime 0.1.2 → 0.2.1

package/README.md

@@ -0,0 +1,231 @@
+# @mihirsarya/manim-scroll-runtime
+
+Core scroll-driven playback runtime for pre-rendered Manim animations. Works in any JavaScript environment—use directly in vanilla JS or as the foundation for framework integrations.
+
+## Installation
+
+```bash
+npm install @mihirsarya/manim-scroll-runtime
+```
+
+Or use the unified package (recommended for React/Next.js):
+
+```bash
+npm install @mihirsarya/manim-scroll
+```
+
+## Features
+
+- **Video or frame-by-frame playback** with automatic fallback
+- **Flexible scroll ranges** via presets, relative units, or pixels
+- **Native text animation** using SVG (no pre-rendered assets needed)
+- **Zero framework dependencies** for the core runtime
+
+## Quick Start
+
+### Pre-rendered Animation (Video/Frames)
+
+```ts
+import { registerScrollAnimation } from "@mihirsarya/manim-scroll-runtime";
+
+const container = document.querySelector("#hero") as HTMLElement;
+
+const cleanup = await registerScrollAnimation({
+  container,
+  manifestUrl: "/assets/scene/manifest.json",
+  scrollRange: "viewport",
+  onReady: () => console.log("Animation ready"),
+  onProgress: (progress) => console.log(`Progress: ${progress}`),
+});
+
+// Call cleanup() when done to remove listeners
+```
+
+### Native Text Animation
+
+```ts
+import { registerNativeAnimation } from "@mihirsarya/manim-scroll-runtime";
+
+const container = document.querySelector("#text") as HTMLElement;
+
+const cleanup = await registerNativeAnimation({
+  container,
+  text: "Hello World",
+  fontSize: 48,
+  color: "#ffffff",
+  scrollRange: "viewport",
+  onReady: () => console.log("Ready"),
+});
+```
+
+## Exports
+
+### Functions
+
+- **`registerScrollAnimation(options)`** - Register a scroll-driven animation with pre-rendered assets
+- **`registerNativeAnimation(options)`** - Register a native SVG text animation
+
+### Classes
+
+- **`NativeTextPlayer`** - Low-level native text animation player
+
+### Types
+
+- `RenderManifest` - Animation manifest schema
+- `ScrollAnimationOptions` - Options for `registerScrollAnimation`
+- `NativeAnimationOptions` - Options for `registerNativeAnimation`
+- `ScrollRange`, `ScrollRangePreset`, `ScrollRangeValue` - Scroll range types
+
+## API Reference
+
+### registerScrollAnimation(options)
+
+Registers a scroll-driven animation using pre-rendered video or frame assets.
+
+```ts
+interface ScrollAnimationOptions {
+  /** Container element for the animation */
+  container: HTMLElement;
+  /** URL to the animation manifest.json */
+  manifestUrl: string;
+  /** Playback mode (default: "auto") */
+  mode?: "auto" | "frames" | "video";
+  /** Optional canvas element (created automatically if not provided) */
+  canvas?: HTMLCanvasElement;
+  /** Scroll range configuration */
+  scrollRange?: ScrollRangeValue;
+  /** Called when animation is loaded and ready */
+  onReady?: () => void;
+  /** Called on scroll progress updates (0 to 1) */
+  onProgress?: (progress: number) => void;
+}
+```
+
+**Returns:** `Promise<() => void>` - Cleanup function to remove listeners
+
+### registerNativeAnimation(options)
+
+Registers a native text animation that renders in the browser using SVG, replicating Manim's Write/DrawBorderThenFill effect.
+
+```ts
+interface NativeAnimationOptions {
+  /** Container element for the animation */
+  container: HTMLElement;
+  /** Text to animate */
+  text: string;
+  /** Font size in pixels (inherits from parent if not specified) */
+  fontSize?: number;
+  /** Text color (hex or CSS color) */
+  color?: string;
+  /** URL to a font file (woff, woff2, ttf, otf) */
+  fontUrl?: string;
+  /** Stroke width for the drawing phase (default: 2) */
+  strokeWidth?: number;
+  /** Scroll range configuration */
+  scrollRange?: ScrollRangeValue;
+  /** Called when animation is loaded and ready */
+  onReady?: () => void;
+  /** Called on scroll progress updates (0 to 1) */
+  onProgress?: (progress: number) => void;
+}
+```
+
+**Returns:** `Promise<() => void>` - Cleanup function to remove listeners
+
+## Scroll Range Configuration
+
+The `scrollRange` option controls when the animation plays relative to scroll position.
+
+### Presets
+
+```ts
+// Animation plays as element crosses the viewport (most common)
+scrollRange: "viewport"
+
+// Animation tied to element's own scroll position
+scrollRange: "element"
+
+// Animation spans entire document scroll
+scrollRange: "full"
+```
+
+### Relative Units
+
+Use viewport height (`vh`) or element percentage (`%`):
+
+```ts
+// Start when element is 100vh from top, end at -50% of element height
+scrollRange: ["100vh", "-50%"]
+
+// Mix units as needed
+scrollRange: ["80vh", "-100%"]
+```
+
+### Pixel Values
+
+For precise control:
+
+```ts
+// As a tuple
+scrollRange: [800, -400]
+
+// As an object (legacy format)
+scrollRange: { start: 800, end: -400 }
+```
+
+## Manifest Schema
+
+The `manifest.json` file describes a pre-rendered animation:
+
+```ts
+interface RenderManifest {
+  /** Scene name */
+  scene: string;
+  /** Frames per second */
+  fps: number;
+  /** Canvas width */
+  width: number;
+  /** Canvas height */
+  height: number;
+  /** Array of frame image URLs */
+  frames: string[];
+  /** Video URL (null if not available) */
+  video: string | null;
+  /** Whether rendered with transparent background */
+  transparent?: boolean;
+  /** Whether this is an inline animation */
+  inline?: boolean;
+  /** Aspect ratio for inline sizing */
+  aspectRatio?: number | null;
+}
+```
+
+## Playback Modes
+
+| Mode | Description |
+|------|-------------|
+| `"auto"` | Uses video if available, falls back to frames |
+| `"video"` | Forces video playback (fails if no video) |
+| `"frames"` | Forces frame-by-frame playback |
+
+## Browser Usage (CDN)
+
+```html
+<script type="module">
+  import { registerScrollAnimation } from "https://esm.sh/@mihirsarya/manim-scroll-runtime";
+  
+  registerScrollAnimation({
+    container: document.querySelector("#hero"),
+    manifestUrl: "/assets/scene/manifest.json",
+    scrollRange: "viewport",
+  });
+</script>
+```
+
+## Dependencies
+
+- [opentype.js](https://opentype.js.org/) - For native text animation font parsing
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { NativeTextPlayer, registerNativeAnimation } from "./native-player";
 import type { ScrollAnimationOptions } from "./types";
-export type { RenderManifest, ScrollAnimationOptions, ScrollRange, ScrollRangePreset, ScrollRangeValue, } from "./types";
+export type { RenderManifest, ScrollAnimationOptions, ScrollRange, ScrollRangePreset, ScrollRangeValue, NativeAnimationOptions, } from "./types";
+export { NativeTextPlayer, registerNativeAnimation };
 export declare function registerScrollAnimation(options: ScrollAnimationOptions): Promise<() => void>;

package/dist/index.js

@@ -1,4 +1,6 @@
 import { ScrollPlayer } from "./player";
+import { NativeTextPlayer, registerNativeAnimation } from "./native-player";
+export { NativeTextPlayer, registerNativeAnimation };
 export async function registerScrollAnimation(options) {
     const player = new ScrollPlayer(options);
     await player.init();

package/dist/loader.d.ts

@@ -4,7 +4,10 @@ export declare class FrameCache {
     private readonly frameUrls;
     private frames;
     private loading;
+    private preloadAhead;
     constructor(frameUrls: string[]);
     get length(): number;
     load(index: number): Promise<HTMLImageElement>;
+    private loadFrame;
+    private preloadNearby;
 }

package/dist/loader.js

@@ -1,10 +1,17 @@
+/**
+ * Resolve an asset URL relative to the manifest URL.
+ * Handles both absolute manifest URLs (with protocol) and path-only URLs.
+ */
 function resolveAssetUrl(asset, manifestUrl) {
-    try {
-        return new URL(asset, manifestUrl).toString();
-    }
-    catch {
+    // If asset is already absolute, return as-is
+    if (asset.startsWith("http://") || asset.startsWith("https://") || asset.startsWith("/")) {
         return asset;
     }
+    // Get the directory of the manifest
+    const lastSlash = manifestUrl.lastIndexOf("/");
+    const baseDir = lastSlash >= 0 ? manifestUrl.substring(0, lastSlash + 1) : "";
+    // Resolve relative path
+    return baseDir + asset;
 }
 export async function loadManifest(url) {
     const response = await fetch(url);
@@ -23,17 +30,26 @@ export class FrameCache {
         this.frameUrls = frameUrls;
         this.frames = new Map();
         this.loading = new Map();
+        this.preloadAhead = 5; // Number of frames to preload ahead
     }
     get length() {
         return this.frameUrls.length;
     }
     async load(index) {
+        // Start preloading nearby frames
+        this.preloadNearby(index);
         if (this.frames.has(index)) {
             return this.frames.get(index);
         }
         if (this.loading.has(index)) {
             return this.loading.get(index);
         }
+        return this.loadFrame(index);
+    }
+    async loadFrame(index) {
+        if (index < 0 || index >= this.frameUrls.length) {
+            throw new Error(`Frame index out of bounds: ${index}`);
+        }
         const url = this.frameUrls[index];
         const promise = new Promise((resolve, reject) => {
             const img = new Image();
@@ -51,4 +67,17 @@ export class FrameCache {
         this.loading.set(index, promise);
         return promise;
     }
+    preloadNearby(currentIndex) {
+        // Preload frames ahead and behind
+        for (let offset = 1; offset <= this.preloadAhead; offset++) {
+            const ahead = currentIndex + offset;
+            const behind = currentIndex - offset;
+            if (ahead < this.frameUrls.length && !this.frames.has(ahead) && !this.loading.has(ahead)) {
+                this.loadFrame(ahead).catch(() => { }); // Silently ignore preload failures
+            }
+            if (behind >= 0 && !this.frames.has(behind) && !this.loading.has(behind)) {
+                this.loadFrame(behind).catch(() => { }); // Silently ignore preload failures
+            }
+        }
+    }
 }

package/dist/native-player.d.ts

@@ -0,0 +1,65 @@
+import type { NativeAnimationOptions } from "./types";
+/**
+ * NativeTextPlayer - Renders text animation natively in the browser
+ * using SVG paths, replicating Manim's Write/DrawBorderThenFill animation.
+ *
+ * Phase 1 (progress 0 to 0.5): Draw the stroke progressively
+ * Phase 2 (progress 0.5 to 1.0): Fill in the text
+ *
+ * Key difference from naive implementations: we split each character into
+ * individual contours (sub-paths) and apply the lag_ratio to ALL contours
+ * across all characters. This matches Manim's behavior where outlines
+ * appear progressively rather than all at once.
+ */
+export declare class NativeTextPlayer {
+    private readonly container;
+    private readonly options;
+    private svg;
+    private fallbackWrapper;
+    /** All sub-paths (segments) across all characters, for stroke animation */
+    private subPaths;
+    /** Fill paths (original closed contours) for the filled state */
+    private fillPaths;
+    private isActive;
+    private rafId;
+    private observer?;
+    private resizeObserver?;
+    private lastProgress;
+    private scrollHandler?;
+    private resizeHandler?;
+    private pendingDraw;
+    private pendingResize;
+    private font;
+    /** Last known font size, used to detect changes for inherited sizing */
+    private lastComputedFontSize;
+    constructor(options: NativeAnimationOptions);
+    init(): Promise<void>;
+    private createCharacterPaths;
+    /**
+     * Get the inherited font size from the container's computed style.
+     */
+    private getInheritedFontSize;
+    private createFallbackTextAnimation;
+    private render;
+    destroy(): void;
+    private setupObserver;
+    /**
+     * Set up resize handling for responsive behavior:
+     * 1. Window resize - recalculate scroll progress (viewport height changes)
+     * 2. Container resize - detect font-size changes when using inherited sizing
+     */
+    private setupResizeHandling;
+    /**
+     * Rebuild the animation when font size changes (for inherited sizing).
+     * This clears and recreates all character paths with the new size.
+     */
+    private rebuildAnimation;
+    private start;
+    private stop;
+    private tick;
+}
+/**
+ * Register a native text animation on a container element.
+ * This creates scroll-driven text animation without pre-rendered assets.
+ */
+export declare function registerNativeAnimation(options: NativeAnimationOptions): Promise<() => void>;