@mihirsarya/manim-scroll-runtime 0.1.1

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,6 @@
+import { ScrollPlayer } from "./player";
+export async function registerScrollAnimation(options) {
+    const player = new ScrollPlayer(options);
+    await player.init();
+    return () => player.destroy();
+}

package/dist/loader.d.ts

@@ -0,0 +1,10 @@
+import type { RenderManifest } from "./types";
+export declare function loadManifest(url: string): Promise<RenderManifest>;
+export declare class FrameCache {
+    private readonly frameUrls;
+    private frames;
+    private loading;
+    constructor(frameUrls: string[]);
+    get length(): number;
+    load(index: number): Promise<HTMLImageElement>;
+}

package/dist/loader.js

@@ -0,0 +1,54 @@
+function resolveAssetUrl(asset, manifestUrl) {
+    try {
+        return new URL(asset, manifestUrl).toString();
+    }
+    catch {
+        return asset;
+    }
+}
+export async function loadManifest(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to load manifest: ${response.status}`);
+    }
+    const manifest = (await response.json());
+    return {
+        ...manifest,
+        frames: manifest.frames.map((frame) => resolveAssetUrl(frame, url)),
+        video: manifest.video ? resolveAssetUrl(manifest.video, url) : null,
+    };
+}
+export class FrameCache {
+    constructor(frameUrls) {
+        this.frameUrls = frameUrls;
+        this.frames = new Map();
+        this.loading = new Map();
+    }
+    get length() {
+        return this.frameUrls.length;
+    }
+    async load(index) {
+        if (this.frames.has(index)) {
+            return this.frames.get(index);
+        }
+        if (this.loading.has(index)) {
+            return this.loading.get(index);
+        }
+        const url = this.frameUrls[index];
+        const promise = new Promise((resolve, reject) => {
+            const img = new Image();
+            img.onload = () => {
+                this.frames.set(index, img);
+                this.loading.delete(index);
+                resolve(img);
+            };
+            img.onerror = () => {
+                this.loading.delete(index);
+                reject(new Error(`Failed to load frame: ${url}`));
+            };
+            img.src = url;
+        });
+        this.loading.set(index, promise);
+        return promise;
+    }
+}

package/dist/loader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/loader.test.js

@@ -0,0 +1,185 @@
+import { describe, it, expect } from "vitest";
+// Test the FrameCache class logic
+describe("FrameCache", () => {
+    // Simulate the FrameCache class for testing
+    class TestFrameCache {
+        constructor(frameUrls) {
+            this.frameUrls = frameUrls;
+            this.frames = new Map();
+            this.loading = new Map();
+        }
+        get length() {
+            return this.frameUrls.length;
+        }
+        async load(index) {
+            if (this.frames.has(index)) {
+                return this.frames.get(index);
+            }
+            if (this.loading.has(index)) {
+                return this.loading.get(index);
+            }
+            const url = this.frameUrls[index];
+            const frame = { url };
+            const promise = Promise.resolve(frame).then((f) => {
+                this.frames.set(index, f);
+                this.loading.delete(index);
+                return f;
+            });
+            this.loading.set(index, promise);
+            return promise;
+        }
+        // Helper for testing
+        isCached(index) {
+            return this.frames.has(index);
+        }
+    }
+    it("should return correct length", () => {
+        const cache = new TestFrameCache(["frame1.png", "frame2.png", "frame3.png"]);
+        expect(cache.length).toBe(3);
+    });
+    it("should return 0 for empty array", () => {
+        const cache = new TestFrameCache([]);
+        expect(cache.length).toBe(0);
+    });
+    it("should load and cache frames", async () => {
+        const cache = new TestFrameCache(["frame1.png", "frame2.png"]);
+        expect(cache.isCached(0)).toBe(false);
+        const frame = await cache.load(0);
+        expect(frame.url).toBe("frame1.png");
+        expect(cache.isCached(0)).toBe(true);
+    });
+    it("should return cached frames on subsequent loads", async () => {
+        const cache = new TestFrameCache(["frame1.png"]);
+        const frame1 = await cache.load(0);
+        const frame2 = await cache.load(0);
+        expect(frame1).toBe(frame2);
+    });
+    it("should deduplicate concurrent loads", async () => {
+        let loadCount = 0;
+        class TrackingCache {
+            constructor(frameUrls) {
+                this.frameUrls = frameUrls;
+                this.frames = new Map();
+                this.loading = new Map();
+            }
+            async load(index) {
+                if (this.frames.has(index)) {
+                    return this.frames.get(index);
+                }
+                if (this.loading.has(index)) {
+                    return this.loading.get(index);
+                }
+                loadCount++;
+                const url = this.frameUrls[index];
+                const frame = { url };
+                const promise = new Promise((resolve) => {
+                    setTimeout(() => {
+                        this.frames.set(index, frame);
+                        this.loading.delete(index);
+                        resolve(frame);
+                    }, 10);
+                });
+                this.loading.set(index, promise);
+                return promise;
+            }
+        }
+        const cache = new TrackingCache(["frame1.png"]);
+        // Start multiple concurrent loads
+        const [frame1, frame2, frame3] = await Promise.all([
+            cache.load(0),
+            cache.load(0),
+            cache.load(0),
+        ]);
+        // Should only have loaded once
+        expect(loadCount).toBe(1);
+        // All should be the same frame
+        expect(frame1.url).toBe("frame1.png");
+        expect(frame2.url).toBe("frame1.png");
+        expect(frame3.url).toBe("frame1.png");
+    });
+});
+describe("resolveAssetUrl", () => {
+    // Clone of the resolveAssetUrl function
+    function resolveAssetUrl(asset, manifestUrl) {
+        try {
+            return new URL(asset, manifestUrl).toString();
+        }
+        catch {
+            return asset;
+        }
+    }
+    it("should resolve relative URLs", () => {
+        const url = resolveAssetUrl("frames/0001.png", "https://example.com/assets/scene/manifest.json");
+        expect(url).toBe("https://example.com/assets/scene/frames/0001.png");
+    });
+    it("should resolve URLs with parent traversal", () => {
+        const url = resolveAssetUrl("../shared/frame.png", "https://example.com/assets/scene/manifest.json");
+        expect(url).toBe("https://example.com/assets/shared/frame.png");
+    });
+    it("should preserve absolute URLs", () => {
+        const url = resolveAssetUrl("https://cdn.example.com/frame.png", "https://example.com/assets/manifest.json");
+        expect(url).toBe("https://cdn.example.com/frame.png");
+    });
+    it("should handle file:// URLs", () => {
+        const url = resolveAssetUrl("frames/0001.png", "file:///Users/test/project/manifest.json");
+        expect(url).toBe("file:///Users/test/project/frames/0001.png");
+    });
+    it("should return original asset for invalid URLs", () => {
+        const url = resolveAssetUrl("frame.png", "not-a-valid-url");
+        expect(url).toBe("frame.png");
+    });
+    it("should handle root-relative paths", () => {
+        const url = resolveAssetUrl("/assets/frame.png", "https://example.com/manifest.json");
+        expect(url).toBe("https://example.com/assets/frame.png");
+    });
+});
+describe("loadManifest", () => {
+    // Test the manifest loading logic
+    it("should handle valid manifest structure", () => {
+        const rawManifest = {
+            scene: "TextScene",
+            fps: 30,
+            width: 1920,
+            height: 1080,
+            frames: ["frames/0001.png", "frames/0002.png"],
+            video: "video.mp4",
+        };
+        // Simulate processing
+        const manifestUrl = "https://example.com/assets/manifest.json";
+        function resolveAssetUrl(asset, url) {
+            try {
+                return new URL(asset, url).toString();
+            }
+            catch {
+                return asset;
+            }
+        }
+        const processed = {
+            ...rawManifest,
+            frames: rawManifest.frames.map((frame) => resolveAssetUrl(frame, manifestUrl)),
+            video: rawManifest.video ? resolveAssetUrl(rawManifest.video, manifestUrl) : null,
+        };
+        expect(processed.scene).toBe("TextScene");
+        expect(processed.fps).toBe(30);
+        expect(processed.width).toBe(1920);
+        expect(processed.height).toBe(1080);
+        expect(processed.frames).toHaveLength(2);
+        expect(processed.frames[0]).toBe("https://example.com/assets/frames/0001.png");
+        expect(processed.video).toBe("https://example.com/assets/video.mp4");
+    });
+    it("should handle manifest without video", () => {
+        const rawManifest = {
+            scene: "CustomScene",
+            fps: 60,
+            width: 1280,
+            height: 720,
+            frames: ["frame.png"],
+            video: null,
+        };
+        const processed = {
+            ...rawManifest,
+            video: rawManifest.video ? rawManifest.video : null,
+        };
+        expect(processed.video).toBeNull();
+    });
+});

package/dist/player.d.ts

@@ -0,0 +1,22 @@
+import type { ScrollAnimationOptions } from "./types";
+export declare class ScrollPlayer {
+    private readonly options;
+    private readonly container;
+    private readonly canvas;
+    private readonly ctx;
+    private manifest?;
+    private frameCache?;
+    private videoEl?;
+    private mode;
+    private isActive;
+    private rafId;
+    private observer?;
+    constructor(options: ScrollAnimationOptions);
+    init(): Promise<void>;
+    destroy(): void;
+    private selectMode;
+    private setupObserver;
+    private start;
+    private stop;
+    private tick;
+}

package/dist/player.js

@@ -0,0 +1,179 @@
+import { FrameCache, loadManifest } from "./loader";
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+ * Parse a relative unit string (e.g., "100vh", "-50%") to pixels.
+ * - "vh" units are relative to viewport height
+ * - "%" units are relative to element height
+ * - Numbers without units are treated as pixels
+ */
+function parseRelativeUnit(value, viewportHeight, elementHeight) {
+    if (typeof value === "number") {
+        return value;
+    }
+    const trimmed = value.trim();
+    // Handle viewport height units
+    if (trimmed.endsWith("vh")) {
+        const num = parseFloat(trimmed.slice(0, -2));
+        return (num / 100) * viewportHeight;
+    }
+    // Handle percentage (relative to element height)
+    if (trimmed.endsWith("%")) {
+        const num = parseFloat(trimmed.slice(0, -1));
+        return (num / 100) * elementHeight;
+    }
+    // Handle pixel units or plain numbers
+    if (trimmed.endsWith("px")) {
+        return parseFloat(trimmed.slice(0, -2));
+    }
+    return parseFloat(trimmed);
+}
+/**
+ * Resolve a ScrollRangeValue to a normalized { start, end } object in pixels.
+ * Supports presets, tuple format, and legacy object format.
+ */
+function resolveScrollRange(range, viewportHeight, elementHeight, documentHeight) {
+    var _a, _b;
+    // Default: viewport preset behavior
+    if (range === undefined || range === "viewport") {
+        return {
+            start: viewportHeight,
+            end: -elementHeight,
+        };
+    }
+    // Element preset: animation tied to element's scroll position
+    if (range === "element") {
+        return {
+            start: viewportHeight * 0.8,
+            end: viewportHeight * 0.2 - elementHeight,
+        };
+    }
+    // Full preset: spans entire document scroll
+    if (range === "full") {
+        return {
+            start: documentHeight - viewportHeight,
+            end: 0,
+        };
+    }
+    // Tuple format: [start, end] with relative units
+    if (Array.isArray(range)) {
+        const [startVal, endVal] = range;
+        return {
+            start: parseRelativeUnit(startVal, viewportHeight, elementHeight),
+            end: parseRelativeUnit(endVal, viewportHeight, elementHeight),
+        };
+    }
+    // Legacy object format
+    return {
+        start: (_a = range.start) !== null && _a !== void 0 ? _a : viewportHeight,
+        end: (_b = range.end) !== null && _b !== void 0 ? _b : -elementHeight,
+    };
+}
+function resolveScrollProgress(rect, viewportHeight, range) {
+    var _a, _b;
+    const documentHeight = document.documentElement.scrollHeight;
+    const resolved = resolveScrollRange(range, viewportHeight, rect.height, documentHeight);
+    const start = (_a = resolved.start) !== null && _a !== void 0 ? _a : viewportHeight;
+    const end = (_b = resolved.end) !== null && _b !== void 0 ? _b : -rect.height;
+    const progress = (start - rect.top) / (start - end);
+    return clamp(progress, 0, 1);
+}
+export class ScrollPlayer {
+    constructor(options) {
+        var _a;
+        this.options = options;
+        this.mode = "video";
+        this.isActive = false;
+        this.rafId = null;
+        this.container = options.container;
+        this.canvas = (_a = options.canvas) !== null && _a !== void 0 ? _a : document.createElement("canvas");
+        this.ctx = this.canvas.getContext("2d");
+        if (!options.canvas) {
+            this.container.appendChild(this.canvas);
+        }
+    }
+    async init() {
+        var _a, _b;
+        this.manifest = await loadManifest(this.options.manifestUrl);
+        this.frameCache = new FrameCache(this.manifest.frames);
+        this.mode = this.selectMode(this.manifest, this.options.mode);
+        this.canvas.width = this.manifest.width;
+        this.canvas.height = this.manifest.height;
+        if (this.mode === "video" && this.manifest.video) {
+            const video = document.createElement("video");
+            video.src = this.manifest.video;
+            video.muted = true;
+            video.playsInline = true;
+            await new Promise((resolve) => {
+                video.addEventListener("loadedmetadata", () => resolve(), { once: true });
+            });
+            this.videoEl = video;
+        }
+        this.setupObserver();
+        (_b = (_a = this.options).onReady) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    destroy() {
+        var _a;
+        this.stop();
+        (_a = this.observer) === null || _a === void 0 ? void 0 : _a.disconnect();
+        if (!this.options.canvas) {
+            this.canvas.remove();
+        }
+    }
+    selectMode(manifest, mode) {
+        if (mode === "frames")
+            return "frames";
+        if (mode === "video" && manifest.video)
+            return "video";
+        if (mode === "video" && !manifest.video)
+            return "frames";
+        return manifest.video ? "video" : "frames";
+    }
+    setupObserver() {
+        this.observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting) {
+                    this.start();
+                }
+                else {
+                    this.stop();
+                }
+            }
+        }, { root: null, threshold: 0 });
+        this.observer.observe(this.container);
+    }
+    start() {
+        if (this.isActive)
+            return;
+        this.isActive = true;
+        const loop = () => {
+            this.tick();
+            this.rafId = requestAnimationFrame(loop);
+        };
+        this.rafId = requestAnimationFrame(loop);
+    }
+    stop() {
+        if (!this.isActive)
+            return;
+        this.isActive = false;
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+        }
+    }
+    async tick() {
+        var _a, _b;
+        if (!this.manifest || !this.frameCache)
+            return;
+        const rect = this.container.getBoundingClientRect();
+        const progress = resolveScrollProgress(rect, window.innerHeight, this.options.scrollRange);
+        (_b = (_a = this.options).onProgress) === null || _b === void 0 ? void 0 : _b.call(_a, progress);
+        if (this.mode === "video" && this.videoEl) {
+            const duration = this.videoEl.duration || 0;
+            this.videoEl.currentTime = duration * progress;
+            this.ctx.drawImage(this.videoEl, 0, 0, this.canvas.width, this.canvas.height);
+            return;
+        }
+        const index = Math.round(progress * (this.frameCache.length - 1));
+        const frame = await this.frameCache.load(index);
+        this.ctx.drawImage(frame, 0, 0, this.canvas.width, this.canvas.height);
+    }
+}

package/dist/player.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/player.test.js

@@ -0,0 +1,210 @@
+import { describe, it, expect } from "vitest";
+// We need to test the internal functions, so we'll extract them for testing
+// The player module doesn't export these, so we'll create unit tests for the logic
+/**
+ * Clone of parseRelativeUnit for testing
+ */
+function parseRelativeUnit(value, viewportHeight, elementHeight) {
+    if (typeof value === "number") {
+        return value;
+    }
+    const trimmed = value.trim();
+    if (trimmed.endsWith("vh")) {
+        const num = parseFloat(trimmed.slice(0, -2));
+        return (num / 100) * viewportHeight;
+    }
+    if (trimmed.endsWith("%")) {
+        const num = parseFloat(trimmed.slice(0, -1));
+        return (num / 100) * elementHeight;
+    }
+    if (trimmed.endsWith("px")) {
+        return parseFloat(trimmed.slice(0, -2));
+    }
+    return parseFloat(trimmed);
+}
+function resolveScrollRange(range, viewportHeight, elementHeight, documentHeight) {
+    var _a, _b;
+    if (range === undefined || range === "viewport") {
+        return {
+            start: viewportHeight,
+            end: -elementHeight,
+        };
+    }
+    if (range === "element") {
+        return {
+            start: viewportHeight * 0.8,
+            end: viewportHeight * 0.2 - elementHeight,
+        };
+    }
+    if (range === "full") {
+        return {
+            start: documentHeight - viewportHeight,
+            end: 0,
+        };
+    }
+    if (Array.isArray(range)) {
+        const [startVal, endVal] = range;
+        return {
+            start: parseRelativeUnit(startVal, viewportHeight, elementHeight),
+            end: parseRelativeUnit(endVal, viewportHeight, elementHeight),
+        };
+    }
+    return {
+        start: (_a = range.start) !== null && _a !== void 0 ? _a : viewportHeight,
+        end: (_b = range.end) !== null && _b !== void 0 ? _b : -elementHeight,
+    };
+}
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+function resolveScrollProgress(rectTop, rectHeight, viewportHeight, documentHeight, range) {
+    var _a, _b;
+    const resolved = resolveScrollRange(range, viewportHeight, rectHeight, documentHeight);
+    const start = (_a = resolved.start) !== null && _a !== void 0 ? _a : viewportHeight;
+    const end = (_b = resolved.end) !== null && _b !== void 0 ? _b : -rectHeight;
+    const progress = (start - rectTop) / (start - end);
+    return clamp(progress, 0, 1);
+}
+describe("parseRelativeUnit", () => {
+    const viewportHeight = 1000;
+    const elementHeight = 500;
+    it("should return number values directly", () => {
+        expect(parseRelativeUnit(100, viewportHeight, elementHeight)).toBe(100);
+        expect(parseRelativeUnit(-50, viewportHeight, elementHeight)).toBe(-50);
+        expect(parseRelativeUnit(0, viewportHeight, elementHeight)).toBe(0);
+    });
+    it("should parse viewport height units (vh)", () => {
+        expect(parseRelativeUnit("100vh", viewportHeight, elementHeight)).toBe(1000);
+        expect(parseRelativeUnit("50vh", viewportHeight, elementHeight)).toBe(500);
+        expect(parseRelativeUnit("0vh", viewportHeight, elementHeight)).toBe(0);
+        expect(parseRelativeUnit("-25vh", viewportHeight, elementHeight)).toBe(-250);
+    });
+    it("should parse percentage units (relative to element height)", () => {
+        expect(parseRelativeUnit("100%", viewportHeight, elementHeight)).toBe(500);
+        expect(parseRelativeUnit("50%", viewportHeight, elementHeight)).toBe(250);
+        expect(parseRelativeUnit("-50%", viewportHeight, elementHeight)).toBe(-250);
+    });
+    it("should parse pixel units", () => {
+        expect(parseRelativeUnit("100px", viewportHeight, elementHeight)).toBe(100);
+        expect(parseRelativeUnit("-200px", viewportHeight, elementHeight)).toBe(-200);
+    });
+    it("should parse plain numbers as strings", () => {
+        expect(parseRelativeUnit("100", viewportHeight, elementHeight)).toBe(100);
+        expect(parseRelativeUnit("-50", viewportHeight, elementHeight)).toBe(-50);
+    });
+    it("should handle whitespace", () => {
+        expect(parseRelativeUnit("  100vh  ", viewportHeight, elementHeight)).toBe(1000);
+        expect(parseRelativeUnit("  50%  ", viewportHeight, elementHeight)).toBe(250);
+    });
+});
+describe("resolveScrollRange", () => {
+    const viewportHeight = 1000;
+    const elementHeight = 500;
+    const documentHeight = 3000;
+    it("should handle undefined (defaults to viewport preset)", () => {
+        const result = resolveScrollRange(undefined, viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(1000);
+        expect(result.end).toBe(-500);
+    });
+    it("should handle viewport preset", () => {
+        const result = resolveScrollRange("viewport", viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(1000);
+        expect(result.end).toBe(-500);
+    });
+    it("should handle element preset", () => {
+        const result = resolveScrollRange("element", viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(800); // viewportHeight * 0.8
+        expect(result.end).toBe(-300); // viewportHeight * 0.2 - elementHeight
+    });
+    it("should handle full preset", () => {
+        const result = resolveScrollRange("full", viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(2000); // documentHeight - viewportHeight
+        expect(result.end).toBe(0);
+    });
+    it("should handle tuple format with relative units", () => {
+        const result = resolveScrollRange(["100vh", "-50%"], viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(1000);
+        expect(result.end).toBe(-250);
+    });
+    it("should handle tuple format with numbers", () => {
+        const result = resolveScrollRange([800, -400], viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(800);
+        expect(result.end).toBe(-400);
+    });
+    it("should handle tuple format with mixed values", () => {
+        const result = resolveScrollRange(["80vh", -200], viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(800);
+        expect(result.end).toBe(-200);
+    });
+    it("should handle legacy object format", () => {
+        const result = resolveScrollRange({ start: 600, end: -300 }, viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(600);
+        expect(result.end).toBe(-300);
+    });
+    it("should handle partial legacy object format", () => {
+        const result = resolveScrollRange({ start: 600 }, viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(600);
+        expect(result.end).toBe(-500); // defaults to -elementHeight
+    });
+    it("should handle empty legacy object format", () => {
+        const result = resolveScrollRange({}, viewportHeight, elementHeight, documentHeight);
+        expect(result.start).toBe(1000); // defaults to viewportHeight
+        expect(result.end).toBe(-500); // defaults to -elementHeight
+    });
+});
+describe("resolveScrollProgress", () => {
+    const viewportHeight = 1000;
+    const elementHeight = 500;
+    const documentHeight = 3000;
+    it("should return 0 when element is below viewport", () => {
+        // Element top is at viewport height (just entering from bottom)
+        const progress = resolveScrollProgress(viewportHeight, // rectTop at bottom of viewport
+        elementHeight, viewportHeight, documentHeight, "viewport");
+        expect(progress).toBe(0);
+    });
+    it("should return 1 when element is above viewport", () => {
+        // Element top is at -elementHeight (fully exited top)
+        const progress = resolveScrollProgress(-elementHeight, elementHeight, viewportHeight, documentHeight, "viewport");
+        expect(progress).toBe(1);
+    });
+    it("should return 0.5 when element is halfway through", () => {
+        // Halfway between start (1000) and end (-500) is 250
+        const progress = resolveScrollProgress(250, elementHeight, viewportHeight, documentHeight, "viewport");
+        expect(progress).toBe(0.5);
+    });
+    it("should clamp progress to 0-1 range", () => {
+        // Way below viewport
+        const progressBelow = resolveScrollProgress(2000, // far below
+        elementHeight, viewportHeight, documentHeight, "viewport");
+        expect(progressBelow).toBe(0);
+        // Way above viewport
+        const progressAbove = resolveScrollProgress(-2000, // far above
+        elementHeight, viewportHeight, documentHeight, "viewport");
+        expect(progressAbove).toBe(1);
+    });
+    it("should work with different scroll range presets", () => {
+        // Test with element preset
+        const progressElement = resolveScrollProgress(viewportHeight * 0.5, // middle
+        elementHeight, viewportHeight, documentHeight, "element");
+        expect(progressElement).toBeGreaterThan(0);
+        expect(progressElement).toBeLessThan(1);
+    });
+});
+describe("clamp", () => {
+    it("should clamp values within range", () => {
+        expect(clamp(0.5, 0, 1)).toBe(0.5);
+        expect(clamp(0, 0, 1)).toBe(0);
+        expect(clamp(1, 0, 1)).toBe(1);
+    });
+    it("should clamp values below minimum", () => {
+        expect(clamp(-1, 0, 1)).toBe(0);
+        expect(clamp(-100, 0, 1)).toBe(0);
+    });
+    it("should clamp values above maximum", () => {
+        expect(clamp(2, 0, 1)).toBe(1);
+        expect(clamp(100, 0, 1)).toBe(1);
+    });
+    it("should work with different ranges", () => {
+        expect(clamp(50, 0, 100)).toBe(50);
+        expect(clamp(-10, 0, 100)).toBe(0);
+        expect(clamp(150, 0, 100)).toBe(100);
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+export type RenderManifest = {
+    scene: string;
+    fps: number;
+    width: number;
+    height: number;
+    frames: string[];
+    video: string | null;
+};
+/**
+ * Legacy scroll range format (pixels).
+ */
+export type ScrollRange = {
+    start?: number;
+    end?: number;
+};
+/**
+ * Preset scroll range behaviors.
+ * - "viewport": Animation plays as element crosses the viewport (most common)
+ * - "element": Animation tied to element's own scroll position
+ * - "full": Animation spans entire document scroll
+ */
+export type ScrollRangePreset = "viewport" | "element" | "full";
+/**
+ * Flexible scroll range value that supports:
+ * - Presets: "viewport" | "element" | "full"
+ * - Tuple with relative units: ["100vh", "-50%"] or [100, -200]
+ * - Legacy object format: { start?: number, end?: number }
+ */
+export type ScrollRangeValue = ScrollRangePreset | [start: string | number, end: string | number] | ScrollRange;
+export type ScrollAnimationOptions = {
+    container: HTMLElement;
+    manifestUrl: string;
+    mode?: "auto" | "frames" | "video";
+    canvas?: HTMLCanvasElement;
+    scrollRange?: ScrollRangeValue;
+    onReady?: () => void;
+    onProgress?: (progress: number) => void;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@mihirsarya/manim-scroll-runtime",
+  "version": "0.1.1",
+  "description": "Scroll-driven playback runtime for pre-rendered Manim animations.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}