@mihirsarya/manim-scroll-runtime 0.2.0 → 0.2.2

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

package/dist/native-player.d.ts

@@ -1,4 +1,4 @@
-import type { NativeAnimationOptions } from "./types";
+import type { NativeAnimationOptions, PlaybackOptions } from "./types";
 /**
  * NativeTextPlayer - Renders text animation natively in the browser
  * using SVG paths, replicating Manim's Write/DrawBorderThenFill animation.
@@ -32,8 +32,61 @@ export declare class NativeTextPlayer {
     private font;
     /** Last known font size, used to detect changes for inherited sizing */
     private lastComputedFontSize;
+    /** Whether time-based animation is currently playing */
+    private _isPlaying;
+    /** RAF ID for playback animation loop */
+    private playbackRafId;
+    /** Start time of the current playback (from performance.now()) */
+    private playbackStartTime;
+    /** Duration of current playback in milliseconds */
+    private playbackDuration;
+    /** Easing function for current playback */
+    private playbackEasing;
+    /** Direction of playback: 1 for forward, -1 for reverse */
+    private playbackDirection;
+    /** Whether to loop the playback */
+    private playbackLoop;
+    /** Callback when playback completes */
+    private playbackOnComplete?;
+    /** Current progress value (0 to 1) - used in controlled mode */
+    private currentProgress;
+    /** Whether we're in controlled/programmatic mode (no scroll binding) */
+    private isControlledMode;
     constructor(options: NativeAnimationOptions);
     init(): Promise<void>;
+    /**
+     * Whether the animation is currently playing (time-based).
+     */
+    get isPlaying(): boolean;
+    /**
+     * Get the current progress value (0 to 1).
+     */
+    get progress(): number;
+    /**
+     * Set the animation progress directly (0 to 1).
+     * This is the primary method for controlled/declarative usage.
+     * Stops any ongoing playback.
+     */
+    setProgress(progress: number): void;
+    /**
+     * Play the animation over a specified duration.
+     * @param options - Playback options (duration, easing, loop, etc.)
+     *                  or just duration in milliseconds
+     */
+    play(options?: PlaybackOptions | number): void;
+    /**
+     * Pause the animation playback.
+     */
+    pause(): void;
+    /**
+     * Seek to a specific progress value (0 to 1).
+     * Unlike setProgress, this doesn't affect the playing state.
+     * If playing, the animation will continue from the new position.
+     */
+    seek(progress: number): void;
+    private startPlayback;
+    private pausePlayback;
+    private playbackTick;
     private createCharacterPaths;
     /**
      * Get the inherited font size from the container's computed style.

package/dist/native-player.js

@@ -72,6 +72,36 @@ function integerInterpolate(start, end, alpha) {
     const subalpha = scaledAlpha - index;
     return [start + index, subalpha];
 }
+// ============================================================================
+// Easing Functions for Playback
+// ============================================================================
+/** Standard ease-in (quadratic) */
+function easeIn(t) {
+    return t * t;
+}
+/** Standard ease-out (quadratic) */
+function easeOut(t) {
+    return 1 - (1 - t) * (1 - t);
+}
+/** Standard ease-in-out (quadratic) */
+function easeInOut(t) {
+    return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+}
+/** Resolve an easing preset to an easing function */
+function resolveEasing(easing) {
+    if (typeof easing === "function") {
+        return easing;
+    }
+    switch (easing) {
+        case "ease-in": return easeIn;
+        case "ease-out": return easeOut;
+        case "ease-in-out": return easeInOut;
+        case "smooth": return smooth;
+        case "linear":
+        default:
+            return linear;
+    }
+}
 /**
  * Parse a relative unit string (e.g., "100vh", "-50%") to pixels.
  */
@@ -486,6 +516,7 @@ function splitPathIntoSegments(pathData) {
  */
 export class NativeTextPlayer {
     constructor(options) {
+        var _a;
         this.svg = null;
         this.fallbackWrapper = null;
         /** All sub-paths (segments) across all characters, for stroke animation */
@@ -500,6 +531,57 @@ export class NativeTextPlayer {
         this.font = null;
         /** Last known font size, used to detect changes for inherited sizing */
         this.lastComputedFontSize = 0;
+        // ==================== Playback State ====================
+        /** Whether time-based animation is currently playing */
+        this._isPlaying = false;
+        /** RAF ID for playback animation loop */
+        this.playbackRafId = null;
+        /** Start time of the current playback (from performance.now()) */
+        this.playbackStartTime = 0;
+        /** Duration of current playback in milliseconds */
+        this.playbackDuration = 0;
+        /** Easing function for current playback */
+        this.playbackEasing = linear;
+        /** Direction of playback: 1 for forward, -1 for reverse */
+        this.playbackDirection = 1;
+        /** Whether to loop the playback */
+        this.playbackLoop = false;
+        /** Current progress value (0 to 1) - used in controlled mode */
+        this.currentProgress = 0;
+        /** Whether we're in controlled/programmatic mode (no scroll binding) */
+        this.isControlledMode = false;
+        this.playbackTick = () => {
+            var _a, _b, _c;
+            if (!this._isPlaying)
+                return;
+            const elapsed = performance.now() - this.playbackStartTime;
+            let rawProgress = elapsed / this.playbackDuration;
+            if (rawProgress >= 1) {
+                if (this.playbackLoop) {
+                    // Loop: reset and continue
+                    this.playbackStartTime = performance.now();
+                    rawProgress = 0;
+                }
+                else {
+                    // Complete
+                    rawProgress = 1;
+                    this._isPlaying = false;
+                }
+            }
+            // Apply easing and direction
+            const easedProgress = this.playbackEasing(rawProgress);
+            this.currentProgress = this.playbackDirection === 1
+                ? easedProgress
+                : 1 - easedProgress;
+            this.render(this.currentProgress);
+            (_b = (_a = this.options).onProgress) === null || _b === void 0 ? void 0 : _b.call(_a, this.currentProgress);
+            if (this._isPlaying) {
+                this.playbackRafId = requestAnimationFrame(this.playbackTick);
+            }
+            else {
+                (_c = this.playbackOnComplete) === null || _c === void 0 ? void 0 : _c.call(this);
+            }
+        };
         // Manim defaults: DrawBorderThenFill stroke_width = 2
         // fontSize: undefined means inherit from parent element
         this.options = {
@@ -508,6 +590,9 @@ export class NativeTextPlayer {
             ...options,
         };
         this.container = options.container;
+        // If progress is provided, we're in controlled mode
+        this.isControlledMode = options.progress !== undefined;
+        this.currentProgress = (_a = options.progress) !== null && _a !== void 0 ? _a : 0;
     }
     async init() {
         var _a, _b;
@@ -535,14 +620,115 @@ export class NativeTextPlayer {
         if (this.svg) {
             this.container.appendChild(this.svg);
         }
-        // Setup intersection observer
-        this.setupObserver();
-        // Setup resize handling for responsiveness
-        this.setupResizeHandling();
-        // Draw initial state (progress = 0)
-        this.render(0);
+        // Only setup scroll-based animation if not in controlled mode
+        if (!this.isControlledMode) {
+            // Setup intersection observer
+            this.setupObserver();
+            // Setup resize handling for responsiveness
+            this.setupResizeHandling();
+        }
+        // Draw initial state
+        this.render(this.currentProgress);
         (_b = (_a = this.options).onReady) === null || _b === void 0 ? void 0 : _b.call(_a);
     }
+    // ==================== Public Playback API ====================
+    /**
+     * Whether the animation is currently playing (time-based).
+     */
+    get isPlaying() {
+        return this._isPlaying;
+    }
+    /**
+     * Get the current progress value (0 to 1).
+     */
+    get progress() {
+        return this.currentProgress;
+    }
+    /**
+     * Set the animation progress directly (0 to 1).
+     * This is the primary method for controlled/declarative usage.
+     * Stops any ongoing playback.
+     */
+    setProgress(progress) {
+        var _a, _b;
+        this.pausePlayback();
+        this.currentProgress = clamp(progress, 0, 1);
+        this.render(this.currentProgress);
+        (_b = (_a = this.options).onProgress) === null || _b === void 0 ? void 0 : _b.call(_a, this.currentProgress);
+    }
+    /**
+     * Play the animation over a specified duration.
+     * @param options - Playback options (duration, easing, loop, etc.)
+     *                  or just duration in milliseconds
+     */
+    play(options) {
+        var _a, _b, _c, _d;
+        this.pausePlayback();
+        // Parse options
+        const opts = typeof options === "number"
+            ? { duration: options }
+            : (options !== null && options !== void 0 ? options : {});
+        const duration = (_a = opts.duration) !== null && _a !== void 0 ? _a : 1000;
+        const delay = (_b = opts.delay) !== null && _b !== void 0 ? _b : 0;
+        this.playbackDuration = duration;
+        this.playbackEasing = resolveEasing(opts.easing);
+        this.playbackDirection = (_c = opts.direction) !== null && _c !== void 0 ? _c : 1;
+        this.playbackLoop = (_d = opts.loop) !== null && _d !== void 0 ? _d : false;
+        this.playbackOnComplete = opts.onComplete;
+        // Set initial progress based on direction
+        if (this.playbackDirection === 1 && this.currentProgress >= 1) {
+            this.currentProgress = 0;
+        }
+        else if (this.playbackDirection === -1 && this.currentProgress <= 0) {
+            this.currentProgress = 1;
+        }
+        // Start playback with optional delay
+        if (delay > 0) {
+            setTimeout(() => this.startPlayback(), delay);
+        }
+        else {
+            this.startPlayback();
+        }
+    }
+    /**
+     * Pause the animation playback.
+     */
+    pause() {
+        this.pausePlayback();
+    }
+    /**
+     * Seek to a specific progress value (0 to 1).
+     * Unlike setProgress, this doesn't affect the playing state.
+     * If playing, the animation will continue from the new position.
+     */
+    seek(progress) {
+        var _a, _b;
+        this.currentProgress = clamp(progress, 0, 1);
+        this.render(this.currentProgress);
+        (_b = (_a = this.options).onProgress) === null || _b === void 0 ? void 0 : _b.call(_a, this.currentProgress);
+        // If playing, reset the start time to continue from current position
+        if (this._isPlaying) {
+            const rawProgress = this.playbackDirection === 1
+                ? this.currentProgress
+                : 1 - this.currentProgress;
+            // Invert the easing to find approximate time offset
+            // For simplicity, use linear approximation
+            this.playbackStartTime = performance.now() - (rawProgress * this.playbackDuration);
+        }
+    }
+    // ==================== Private Playback Helpers ====================
+    startPlayback() {
+        this._isPlaying = true;
+        this.playbackStartTime = performance.now();
+        this.playbackTick();
+    }
+    pausePlayback() {
+        this._isPlaying = false;
+        if (this.playbackRafId !== null) {
+            cancelAnimationFrame(this.playbackRafId);
+            this.playbackRafId = null;
+        }
+    }
     async createCharacterPaths() {
         var _a, _b;
         if (!this.svg)
@@ -834,6 +1020,7 @@ export class NativeTextPlayer {
     destroy() {
         var _a, _b;
         this.stop();
+        this.pausePlayback(); // Clean up playback animation
         (_a = this.observer) === null || _a === void 0 ? void 0 : _a.disconnect();
         (_b = this.resizeObserver) === null || _b === void 0 ? void 0 : _b.disconnect();
         if (this.resizeHandler) {

package/dist/types.d.ts

@@ -46,6 +46,25 @@ export type ScrollAnimationOptions = {
  * Options for native text animation (no pre-rendered assets).
  * Replicates Manim's Write/DrawBorderThenFill animation in the browser.
  */
+/** Easing function type: takes a progress value (0 to 1) and returns eased progress */
+export type EasingFunction = (t: number) => number;
+/** Pre-built easing presets */
+export type EasingPreset = "linear" | "ease-in" | "ease-out" | "ease-in-out" | "smooth";
+/** Options for duration-based animation playback */
+export type PlaybackOptions = {
+    /** Animation duration in milliseconds */
+    duration?: number;
+    /** Delay before starting in milliseconds */
+    delay?: number;
+    /** Easing function or preset */
+    easing?: EasingPreset | EasingFunction;
+    /** Whether to loop the animation */
+    loop?: boolean;
+    /** Play direction: 1 for forward, -1 for reverse */
+    direction?: 1 | -1;
+    /** Callback when playback completes (not called if loop is true) */
+    onComplete?: () => void;
+};
 export type NativeAnimationOptions = {
     /** The container element to render the animation into */
     container: HTMLElement;
@@ -59,8 +78,13 @@ export type NativeAnimationOptions = {
     fontUrl?: string;
     /** Stroke width for the drawing phase (default: 2, matches Manim's DrawBorderThenFill) */
     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.
+     */
+    progress?: number;
     /** Called when animation is loaded and ready */
     onReady?: () => void;
     /** Called on scroll progress updates */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mihirsarya/manim-scroll-runtime",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Scroll-driven playback runtime for pre-rendered Manim animations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",