manim-web 0.22.0 → 0.23.0

package/dist/mobjects/lottie/LottieMobject.d.ts

@@ -0,0 +1,211 @@
+import { Vector3Tuple } from '../../core/Mobject';
+import { TexturedMobject } from '../../core/TexturedMobject';
+import * as THREE from 'three';
+/**
+ * LottieMobject - display a Lottie (Bodymovin JSON) animation as a mobject.
+ *
+ * ManimCE cannot import After Effects / Lottie vector animations. The browser
+ * can: `lottie-web` renders the JSON into an offscreen `<canvas>`, which this
+ * mobject presents through a `THREE.CanvasTexture` on a plane - exactly how
+ * {@link VideoMobject} and {@link ImageMobject} draw their frames. The plane
+ * then participates in the standard mobject transforms (shift, scale, rotate),
+ * z-index/depth, opacity, and `scene.add`.
+ *
+ * The animation is time-driven: call {@link syncToTime} on scrub/seek so the
+ * displayed frame follows the Player clock, or {@link play} for live playback
+ * via the updater. `lottie-web` is pulled in through a lazy dynamic `import()`
+ * so the base bundle and SSR never load it. Tests inject a player (via the
+ * `player` option or {@link setLottiePlayerFactory}) to avoid the real library
+ * and any DOM/canvas - mirroring ModelMobject's loader-injection seam.
+ *
+ * @example
+ * ```typescript
+ * const anim = await LottieMobject.fromUrl('spinner.json', { width: 4, loop: true });
+ * scene.add(anim);
+ * anim.play();
+ * ```
+ */
+/**
+ * Parsed Bodymovin JSON. Only `w`, `h` and `fr` are read here (for the natural
+ * size and frame rate); the whole object is handed to the player unchanged.
+ */
+export interface LottieAnimationData {
+    /** Composition width in pixels. */
+    w?: number;
+    /** Composition height in pixels. */
+    h?: number;
+    /** Frame rate in frames per second. */
+    fr?: number;
+    [key: string]: unknown;
+}
+/**
+ * The subset of a `lottie-web` AnimationItem this mobject drives. The real
+ * AnimationItem satisfies it structurally; tests implement it with a stub.
+ */
+export interface LottieAnimation {
+    /** Total number of frames in the composition. */
+    totalFrames: number;
+    /** Frame rate in frames per second. */
+    frameRate: number;
+    /** Seek to a frame (`isFrame` true) or a time, and stop there. */
+    goToAndStop(value: number, isFrame?: boolean): void;
+    /** Set the live-playback speed multiplier. */
+    setSpeed?(speed: number): void;
+    /** Release the player's resources. */
+    destroy(): void;
+}
+/** Parameters passed to the player's `loadAnimation`. */
+export interface LottieLoadParams {
+    /** The canvas element that backs the texture. */
+    container: unknown;
+    /** Always `'canvas'`: this mobject renders into an offscreen canvas. */
+    renderer: 'canvas';
+    /** Loop the composition during live playback. */
+    loop: boolean;
+    /** Never autoplay: playback is driven by the updater or by seeks. */
+    autoplay: boolean;
+    /** The parsed Bodymovin JSON. */
+    animationData: LottieAnimationData;
+    /** Canvas renderer settings (the 2D context to draw into). */
+    rendererSettings: {
+        context?: unknown;
+        canvas?: unknown;
+        clearCanvas?: boolean;
+    };
+}
+/**
+ * The minimal player contract. `lottie-web`'s default export satisfies it.
+ */
+export interface LottiePlayer {
+    loadAnimation(params: LottieLoadParams): LottieAnimation;
+}
+/** Builds a player. The DI seam set by {@link setLottiePlayerFactory}. */
+export type LottiePlayerFactory = () => LottiePlayer | Promise<LottiePlayer>;
+/**
+ * Inject a player factory, replacing the lazy-loaded `lottie-web`. Pass `null`
+ * to restore the default. Tests use this to avoid the real library.
+ */
+export declare function setLottiePlayerFactory(factory: LottiePlayerFactory | null): void;
+/** Options for creating a {@link LottieMobject}. */
+export interface LottieMobjectOptions {
+    /** Parsed Bodymovin JSON. Required unless using {@link LottieMobject.fromUrl}. */
+    animationData?: LottieAnimationData;
+    /** Loop the composition during live playback and time wrapping. Default: false. */
+    loop?: boolean;
+    /** Playback speed multiplier (1 = normal). Default: 1. */
+    speed?: number;
+    /** Width in scene units. Default: auto from the composition aspect ratio. */
+    width?: number;
+    /** Height in scene units. Default: auto from the composition aspect ratio. */
+    height?: number;
+    /** If both width and height given, fit inside the box preserving aspect. Default: true. */
+    scaleToFit?: boolean;
+    /** Center position [x, y, z]. Default: [0, 0, 0]. */
+    center?: Vector3Tuple;
+    /** Opacity from 0 to 1. Default: 1. */
+    opacity?: number;
+    /** Render both sides of the plane. Default: false. */
+    doubleSided?: boolean;
+    /** Inject a player directly (bypasses the factory and the network). */
+    player?: LottiePlayer;
+}
+/** Options for {@link LottieMobject.fromUrl}. */
+export interface LottieFromUrlOptions extends Omit<LottieMobjectOptions, 'animationData'> {
+    /** Inject a `fetch` implementation (bypasses the global; used by tests). */
+    fetchImpl?: typeof fetch;
+}
+export declare class LottieMobject extends TexturedMobject {
+    protected _animationData: LottieAnimationData | undefined;
+    protected _loop: boolean;
+    protected _speed: number;
+    protected _width: number | undefined;
+    protected _height: number | undefined;
+    protected _scaleToFit: boolean;
+    protected _centerPoint: Vector3Tuple;
+    protected _doubleSided: boolean;
+    protected _injectedPlayer: LottiePlayer | undefined;
+    protected _canvas: HTMLCanvasElement | null;
+    protected _texture: THREE.CanvasTexture | null;
+    protected _animation: LottieAnimation | null;
+    protected _totalFrames: number;
+    protected _frameRate: number;
+    protected _naturalWidth: number;
+    protected _naturalHeight: number;
+    protected _loaded: boolean;
+    protected _loadError: Error | null;
+    protected _playing: boolean;
+    protected _playhead: number;
+    private _mesh;
+    private _loadPromise;
+    private _loadResolve;
+    private _loadReject;
+    constructor(options: LottieMobjectOptions);
+    /**
+     * Load a Lottie JSON from a URL and return a ready LottieMobject.
+     *
+     * The JSON is fetched and parsed, then handed to the player. Inject a player
+     * (via the `player` option or {@link setLottiePlayerFactory}) and a `fetchImpl`
+     * to avoid the network, e.g. in tests.
+     */
+    static fromUrl(url: string, options?: LottieFromUrlOptions): Promise<LottieMobject>;
+    /**
+     * Create the offscreen canvas and its CanvasTexture. Node/SSR-safe: when
+     * `document` is missing, the load fails gracefully instead of throwing.
+     */
+    private _createCanvasTexture;
+    /** Resolve the player, load the animation, and show the first frame. */
+    private _load;
+    /** Record a load error and reject the ready promise once. */
+    private _failLoad;
+    /** Promise that resolves when the animation is ready and rejects on error. */
+    waitForLoad(): Promise<void>;
+    /** The captured load error, or null when no error occurred. */
+    getLoadError(): Error | null;
+    /** Whether the animation is loaded and seekable. */
+    isLoaded(): boolean;
+    /** Total number of frames in the composition (0 until loaded). */
+    getTotalFrames(): number;
+    /** Frame rate in frames per second. */
+    getFrameRate(): number;
+    /** Natural duration of one loop in seconds (0 until loaded). */
+    get duration(): number;
+    /** The frame index for a scene time, honoring speed and loop. */
+    private _frameForTime;
+    /** Seek the player to a frame and flag the texture for upload. */
+    private _seekFrame;
+    /** Show the frame for a scene time without moving the live playhead. */
+    private _applyTime;
+    /**
+     * Follow the Player clock: show the frame at `sceneTime` seconds. Use this on
+     * scrub and seek so the displayed frame tracks the timeline position.
+     */
+    syncToTime(sceneTime: number): this;
+    /** Seek to a progress fraction in [0, 1] of the composition. */
+    seekToProgress(progress: number): this;
+    /** Start live playback from the current playhead (advanced by the updater). */
+    play(): this;
+    /** Pause live playback. */
+    pause(): this;
+    /** Set the playback speed multiplier. */
+    setSpeed(speed: number): this;
+    /** Enable or disable looping. */
+    setLoop(loop: boolean): this;
+    /** Display dimensions from width/height options and the natural size. */
+    private _calculateDimensions;
+    protected _createThreeObject(): THREE.Object3D;
+    getDisplayMeshLength(): number;
+    getDisplayMeshes(): THREE.Mesh[];
+    applyTextureFrom(other: TexturedMobject): void;
+    applyVisualSize(width: number, height: number): void;
+    applyContentFrom(other: TexturedMobject): void;
+    protected _updateGeometry(): void;
+    protected _syncMaterialToThree(): void;
+    getBoundingBox(): {
+        width: number;
+        height: number;
+        depth: number;
+    };
+    copy(): LottieMobject;
+    dispose(): void;
+}
+//# sourceMappingURL=LottieMobject.d.ts.map

package/dist/mobjects/lottie/LottieMobject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LottieMobject.d.ts","sourceRoot":"","sources":["../../../src/mobjects/lottie/LottieMobject.ts"],"names":[],"mappings":"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"}

package/dist/mobjects/lottie/index.d.ts

@@ -0,0 +1,2 @@
+export { LottieMobject, setLottiePlayerFactory, type LottieMobjectOptions, type LottieFromUrlOptions, type LottieAnimationData, type LottieAnimation, type LottiePlayer, type LottiePlayerFactory, type LottieLoadParams, } from './LottieMobject';
+//# sourceMappingURL=index.d.ts.map

package/dist/mobjects/lottie/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/lottie/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC"}