@mihirsarya/manim-scroll-runtime 0.2.1 → 0.2.2

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.1",
+  "version": "0.2.2",
   "description": "Scroll-driven playback runtime for pre-rendered Manim animations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",