@redwilly/anima 0.1.0

package/dist/core/scene/Scene.d.ts

@@ -0,0 +1,104 @@
+import { Color } from '../math/color/Color';
+import { Timeline } from '../timeline';
+import { Camera, CameraFrame } from '../camera';
+import { Mobject } from '../../mobjects/Mobject';
+import type { Animation } from '../animations/Animation';
+import type { SceneConfig } from './types';
+/**
+ * Scene is the core container that manages Mobjects and coordinates animations.
+ * It provides both a simple API for playing animations and access to the
+ * underlying Timeline and Camera for advanced control.
+ */
+export declare class Scene {
+    private readonly config;
+    private readonly mobjects;
+    private readonly timeline;
+    private readonly _camera;
+    private playheadTime;
+    constructor(config?: SceneConfig);
+    get camera(): Camera;
+    get frame(): CameraFrame;
+    /** Get scene width in pixels. */
+    getWidth(): number;
+    /** Get scene height in pixels. */
+    getHeight(): number;
+    /** Get scene background color. */
+    getBackgroundColor(): Color;
+    /** Get scene frame rate. */
+    getFrameRate(): number;
+    /**
+     * Add mobjects to the scene and make them immediately visible.
+     * Use this for static elements or backgrounds that should be visible
+     * before any animations begin.
+     */
+    add(...mobjects: Mobject[]): this;
+    /**
+     * Remove mobjects from the scene.
+     */
+    remove(...mobjects: Mobject[]): this;
+    /**
+     * Check if a mobject is registered with this scene.
+     */
+    has(mobject: Mobject): boolean;
+    /**
+     * Get all mobjects in the scene.
+     */
+    getMobjects(): readonly Mobject[];
+    /**
+     * Schedule animations to play at the current playhead position.
+     *
+     * Accepts either Animation objects or Mobjects with queued fluent animations.
+     * When a Mobject is passed, its queued animation chain is automatically extracted.
+     *
+     * - Introductory animations (FadeIn, Create, Draw, Write) auto-register
+     *   their targets with the scene if not already present.
+     * - Transformative animations (MoveTo, Rotate, Scale) require the target
+     *   to already be in the scene, otherwise an error is thrown.
+     *
+     * @example
+     * // ProAPI style
+     * this.play(new FadeIn(circle), new MoveTo(rect, 2, 0));
+     *
+     * // FluentAPI style
+     * circle.fadeIn(1).moveTo(2, 0, 1);
+     * this.play(circle);
+     *
+     * // Mixed
+     * circle.fadeIn(1);
+     * this.play(circle, new FadeIn(rect));
+     */
+    play(...items: Array<Animation | Mobject>): this;
+    /**
+     * Add a delay before the next play() call.
+     * @param seconds Number of seconds to wait
+     */
+    wait(seconds: number): this;
+    /**
+     * Get the current playhead time.
+     */
+    getCurrentTime(): number;
+    /**
+     * Get the total duration of all scheduled animations.
+     */
+    getTotalDuration(): number;
+    /**
+     * Get the underlying Timeline for advanced control.
+     * Use this for direct manipulation of animation timing.
+     */
+    getTimeline(): Timeline;
+    /**
+     * Get the Camera for view control and frame dimensions.
+     * Camera calculates Manim-compatible frame dimensions from pixel resolution.
+     */
+    getCamera(): Camera;
+    /**
+     * Validates and registers animation targets based on lifecycle.
+     * Handles composition animations (Sequence, Parallel) by processing children.
+     */
+    private validateAndRegisterAnimation;
+    /**
+     * Gets children of composition animations (Sequence, Parallel).
+     * Returns empty array for non-composition animations.
+     */
+    private getAnimationChildren;
+}

package/dist/core/scene/Scene.js

@@ -0,0 +1,225 @@
+import { Color } from '../math/color/Color';
+import { Timeline } from '../timeline';
+import { Camera, CameraFrame } from '../camera';
+import { Mobject } from '../../mobjects/Mobject';
+import { AnimationTargetNotInSceneError } from '../errors';
+/**
+ * Scene is the core container that manages Mobjects and coordinates animations.
+ * It provides both a simple API for playing animations and access to the
+ * underlying Timeline and Camera for advanced control.
+ */
+export class Scene {
+    config;
+    mobjects = new Set();
+    timeline;
+    _camera;
+    playheadTime = 0;
+    constructor(config = {}) {
+        this.config = {
+            width: config.width ?? 1920,
+            height: config.height ?? 1080,
+            backgroundColor: config.backgroundColor ?? Color.BLACK,
+            frameRate: config.frameRate ?? 60,
+        };
+        this.timeline = new Timeline();
+        this._camera = new Camera({
+            pixelWidth: this.config.width,
+            pixelHeight: this.config.height,
+        });
+    }
+    // ========== Camera Shortcuts ==========
+    get camera() {
+        return this._camera;
+    }
+    get frame() {
+        return this._camera.frame;
+    }
+    // ========== Configuration Getters ==========
+    /** Get scene width in pixels. */
+    getWidth() {
+        return this.config.width;
+    }
+    /** Get scene height in pixels. */
+    getHeight() {
+        return this.config.height;
+    }
+    /** Get scene background color. */
+    getBackgroundColor() {
+        return this.config.backgroundColor;
+    }
+    /** Get scene frame rate. */
+    getFrameRate() {
+        return this.config.frameRate;
+    }
+    // ========== Mobject Management ==========
+    /**
+     * Add mobjects to the scene and make them immediately visible.
+     * Use this for static elements or backgrounds that should be visible
+     * before any animations begin.
+     */
+    add(...mobjects) {
+        for (const m of mobjects) {
+            this.mobjects.add(m);
+            m.setOpacity(1); // Immediately visible
+        }
+        return this;
+    }
+    /**
+     * Remove mobjects from the scene.
+     */
+    remove(...mobjects) {
+        for (const m of mobjects) {
+            this.mobjects.delete(m);
+        }
+        return this;
+    }
+    /**
+     * Check if a mobject is registered with this scene.
+     */
+    has(mobject) {
+        return this.mobjects.has(mobject);
+    }
+    /**
+     * Get all mobjects in the scene.
+     */
+    getMobjects() {
+        return [...this.mobjects];
+    }
+    // ========== Animation Scheduling ==========
+    /**
+     * Schedule animations to play at the current playhead position.
+     *
+     * Accepts either Animation objects or Mobjects with queued fluent animations.
+     * When a Mobject is passed, its queued animation chain is automatically extracted.
+     *
+     * - Introductory animations (FadeIn, Create, Draw, Write) auto-register
+     *   their targets with the scene if not already present.
+     * - Transformative animations (MoveTo, Rotate, Scale) require the target
+     *   to already be in the scene, otherwise an error is thrown.
+     *
+     * @example
+     * // ProAPI style
+     * this.play(new FadeIn(circle), new MoveTo(rect, 2, 0));
+     *
+     * // FluentAPI style
+     * circle.fadeIn(1).moveTo(2, 0, 1);
+     * this.play(circle);
+     *
+     * // Mixed
+     * circle.fadeIn(1);
+     * this.play(circle, new FadeIn(rect));
+     */
+    play(...items) {
+        if (items.length === 0) {
+            return this;
+        }
+        // Convert Mobjects to Animations
+        const animations = items.map(item => {
+            if (item instanceof Mobject) {
+                return item.toAnimation();
+            }
+            return item;
+        });
+        // Validate and auto-register based on animation lifecycle
+        for (const anim of animations) {
+            this.validateAndRegisterAnimation(anim);
+        }
+        this.timeline.scheduleParallel(animations, this.playheadTime);
+        // Advance playhead to end of longest animation
+        let maxDuration = 0;
+        for (const anim of animations) {
+            const totalTime = anim.getDuration() + anim.getDelay();
+            if (totalTime > maxDuration) {
+                maxDuration = totalTime;
+            }
+        }
+        this.playheadTime += maxDuration;
+        return this;
+    }
+    /**
+     * Add a delay before the next play() call.
+     * @param seconds Number of seconds to wait
+     */
+    wait(seconds) {
+        if (seconds < 0) {
+            throw new Error('Wait duration must be non-negative');
+        }
+        this.playheadTime += seconds;
+        return this;
+    }
+    /**
+     * Get the current playhead time.
+     */
+    getCurrentTime() {
+        return this.playheadTime;
+    }
+    /**
+     * Get the total duration of all scheduled animations.
+     */
+    getTotalDuration() {
+        return this.timeline.getTotalDuration();
+    }
+    // ========== ProAPI Access ==========
+    /**
+     * Get the underlying Timeline for advanced control.
+     * Use this for direct manipulation of animation timing.
+     */
+    getTimeline() {
+        return this.timeline;
+    }
+    /**
+     * Get the Camera for view control and frame dimensions.
+     * Camera calculates Manim-compatible frame dimensions from pixel resolution.
+     */
+    getCamera() {
+        return this._camera;
+    }
+    // ========== Private Helpers ==========
+    /**
+     * Validates and registers animation targets based on lifecycle.
+     * Handles composition animations (Sequence, Parallel) by processing children.
+     */
+    validateAndRegisterAnimation(anim) {
+        // Check if this is a composition animation with children
+        const children = this.getAnimationChildren(anim);
+        if (children.length > 0) {
+            // For composition animations, process each child
+            for (const child of children) {
+                this.validateAndRegisterAnimation(child);
+            }
+            return;
+        }
+        // Regular animation - validate/register based on lifecycle
+        const target = anim.getTarget();
+        switch (anim.lifecycle) {
+            case 'introductory':
+                // Auto-register if not already in scene
+                if (!this.mobjects.has(target)) {
+                    this.mobjects.add(target);
+                }
+                break;
+            case 'transformative':
+            case 'exit':
+                // CameraFrame is exempt - it's owned by Camera, not added to scene
+                if (target instanceof CameraFrame) {
+                    break;
+                }
+                // Validate object is in scene
+                if (!this.mobjects.has(target)) {
+                    throw new AnimationTargetNotInSceneError(anim, target);
+                }
+                break;
+        }
+    }
+    /**
+     * Gets children of composition animations (Sequence, Parallel).
+     * Returns empty array for non-composition animations.
+     */
+    getAnimationChildren(anim) {
+        // Check for getChildren method (Sequence, Parallel have this)
+        if ('getChildren' in anim && typeof anim.getChildren === 'function') {
+            return anim.getChildren();
+        }
+        return [];
+    }
+}

package/dist/core/scene/index.d.ts

@@ -0,0 +1,2 @@
+export { Scene } from './Scene';
+export type { SceneConfig, ResolvedSceneConfig } from './types';

package/dist/core/scene/index.js

@@ -0,0 +1 @@
+export { Scene } from './Scene';

package/dist/core/scene/types.d.ts

@@ -0,0 +1,23 @@
+import type { Color } from '../math/color/Color';
+/**
+ * Configuration options for Scene.
+ */
+export interface SceneConfig {
+    /** Pixel width of the scene. Default: 1920 */
+    readonly width?: number;
+    /** Pixel height of the scene. Default: 1080 */
+    readonly height?: number;
+    /** Background color. Default: BLACK */
+    readonly backgroundColor?: Color;
+    /** Frames per second. Default: 60 */
+    readonly frameRate?: number;
+}
+/**
+ * Resolved scene configuration with all defaults applied.
+ */
+export interface ResolvedSceneConfig {
+    readonly width: number;
+    readonly height: number;
+    readonly backgroundColor: Color;
+    readonly frameRate: number;
+}

package/dist/core/serialization/animation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Animation serialization.
+ * Note: Animations reference Mobjects, so we serialize target IDs.
+ */
+import type { Animation } from '../animations/Animation';
+import { Mobject } from '../../mobjects/Mobject';
+import type { SerializedAnimation } from './types';
+type MobjectRegistry = Map<string, Mobject>;
+/**
+ * Serializes an animation instance to a plain object.
+ *
+ * @param anim The animation to serialize
+ * @param getMobjectId Callback to resolve mobject references to stable IDs
+ */
+export declare function serializeAnimation(anim: Animation, getMobjectId: (m: Mobject) => string): SerializedAnimation;
+/**
+ * Restores an animation instance from serialized data.
+ *
+ * @param data The serialized animation data
+ * @param registry Map of mobject IDs to restored instances for resolving targets
+ */
+export declare function deserializeAnimation(data: SerializedAnimation, registry: MobjectRegistry): Animation;
+export {};

package/dist/core/serialization/animation.js

@@ -0,0 +1,176 @@
+/**
+ * Animation serialization.
+ * Note: Animations reference Mobjects, so we serialize target IDs.
+ */
+import { FadeIn, FadeOut } from '../animations/fade';
+import { MoveTo, Rotate, Scale } from '../animations/transform';
+import { MorphTo } from '../animations/morph';
+import { Draw, Write, Unwrite } from '../animations/draw';
+import { Sequence, Parallel } from '../animations/composition';
+import { serializeVector2 } from './primitives';
+import { getEasingName, getEasingByName } from './easingLookup';
+// ========== Animation Config Serialization ==========
+function serializeAnimationConfig(anim) {
+    return {
+        durationSeconds: anim.getDuration(),
+        delaySeconds: anim.getDelay(),
+        easingName: getEasingName(anim.getEasing()),
+    };
+}
+/**
+ * Maps animation instance to serializable type name.
+ */
+function getAnimationType(anim) {
+    if (anim instanceof FadeIn)
+        return 'FadeIn';
+    if (anim instanceof FadeOut)
+        return 'FadeOut';
+    if (anim instanceof MoveTo)
+        return 'MoveTo';
+    if (anim instanceof Rotate)
+        return 'Rotate';
+    if (anim instanceof Scale)
+        return 'Scale';
+    if (anim instanceof MorphTo)
+        return 'MorphTo';
+    if (anim instanceof Draw)
+        return 'Draw';
+    if (anim instanceof Write)
+        return 'Write';
+    if (anim instanceof Unwrite)
+        return 'Unwrite';
+    if (anim instanceof Sequence)
+        return 'Sequence';
+    if (anim instanceof Parallel)
+        return 'Parallel';
+    return 'Unknown';
+}
+// ========== Main Serialization ==========
+/**
+ * Serializes an animation instance to a plain object.
+ *
+ * @param anim The animation to serialize
+ * @param getMobjectId Callback to resolve mobject references to stable IDs
+ */
+export function serializeAnimation(anim, getMobjectId) {
+    const baseData = {
+        type: getAnimationType(anim),
+        targetId: getMobjectId(anim.getTarget()),
+        config: serializeAnimationConfig(anim),
+    };
+    // Type-specific data
+    if (anim instanceof MoveTo) {
+        const moveData = {
+            ...baseData,
+            type: 'MoveTo',
+            destination: serializeVector2(anim.getDestination()),
+        };
+        return moveData;
+    }
+    if (anim instanceof Rotate) {
+        const rotateData = {
+            ...baseData,
+            type: 'Rotate',
+            angle: anim.getAngle(),
+        };
+        return rotateData;
+    }
+    if (anim instanceof Scale) {
+        const scaleData = {
+            ...baseData,
+            type: 'Scale',
+            factor: anim.getFactor(),
+        };
+        return scaleData;
+    }
+    if (anim instanceof Sequence) {
+        const seqData = {
+            ...baseData,
+            type: 'Sequence',
+            animations: anim.getChildren().map((a) => serializeAnimation(a, getMobjectId)),
+        };
+        return seqData;
+    }
+    if (anim instanceof Parallel) {
+        const parData = {
+            ...baseData,
+            type: 'Parallel',
+            animations: anim.getChildren().map((a) => serializeAnimation(a, getMobjectId)),
+        };
+        return parData;
+    }
+    return baseData;
+}
+// ========== Deserialization ==========
+function applyConfig(anim, config) {
+    anim.duration(config.durationSeconds);
+    anim.delay(config.delaySeconds);
+    const easing = getEasingByName(config.easingName);
+    if (easing) {
+        anim.ease(easing);
+    }
+}
+/**
+ * Restores an animation instance from serialized data.
+ *
+ * @param data The serialized animation data
+ * @param registry Map of mobject IDs to restored instances for resolving targets
+ */
+export function deserializeAnimation(data, registry) {
+    const target = registry.get(data.targetId);
+    if (!target) {
+        throw new Error(`Mobject not found: ${data.targetId}`);
+    }
+    let anim;
+    switch (data.type) {
+        case 'FadeIn':
+            anim = new FadeIn(target);
+            break;
+        case 'FadeOut':
+            anim = new FadeOut(target);
+            break;
+        case 'MoveTo': {
+            const d = data;
+            anim = new MoveTo(target, d.destination.x, d.destination.y);
+            break;
+        }
+        case 'Rotate': {
+            const d = data;
+            anim = new Rotate(target, d.angle);
+            break;
+        }
+        case 'Scale': {
+            const d = data;
+            anim = new Scale(target, d.factor);
+            break;
+        }
+        case 'Create':
+            anim = new Write(target);
+            break;
+        case 'Draw':
+            anim = new Draw(target);
+            break;
+        case 'Write':
+            anim = new Write(target);
+            break;
+        case 'Unwrite':
+            anim = new Unwrite(target);
+            break;
+        case 'Sequence': {
+            const d = data;
+            const children = d.animations.map(a => deserializeAnimation(a, registry));
+            anim = new Sequence(children);
+            break;
+        }
+        case 'Parallel': {
+            const d = data;
+            const children = d.animations.map(a => deserializeAnimation(a, registry));
+            anim = new Parallel(children);
+            break;
+        }
+        default:
+            throw new Error(`Unknown animation type: ${data.type}`);
+    }
+    applyConfig(anim, data.config);
+    return anim;
+}

package/dist/core/serialization/easingLookup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Easing function lookup for serialization.
+ * Maps easing functions to names and vice versa.
+ */
+import type { EasingFunction } from '../animations/easing';
+/**
+ * Resolves the name of an easing function for serialization.
+ */
+export declare function getEasingName(fn: EasingFunction): string;
+/**
+ * Resolves an easing function by its serialized name.
+ */
+export declare function getEasingByName(name: string): EasingFunction | undefined;

package/dist/core/serialization/easingLookup.js

@@ -0,0 +1,65 @@
+/**
+ * Easing function lookup for serialization.
+ * Maps easing functions to names and vice versa.
+ */
+import { linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeInQuint, easeOutQuint, easeInOutQuint, easeInSine, easeOutSine, easeInOutSine, easeInExpo, easeOutExpo, easeInOutExpo, easeInCirc, easeOutCirc, easeInOutCirc, easeInBack, easeOutBack, easeInOutBack, easeInElastic, easeOutElastic, easeInOutElastic, easeInBounce, easeOutBounce, easeInOutBounce, smooth, doubleSmooth, rushInto, rushFrom, slowInto, thereAndBack, wiggle, lingering, runningStart, } from '../animations/easing';
+// Mapping from function reference to name
+const easingToName = new Map();
+const nameToEasing = new Map();
+function register(name, fn) {
+    easingToName.set(fn, name);
+    nameToEasing.set(name, fn);
+}
+// Register all built-in easing functions
+register('linear', linear);
+register('easeInQuad', easeInQuad);
+register('easeOutQuad', easeOutQuad);
+register('easeInOutQuad', easeInOutQuad);
+register('easeInCubic', easeInCubic);
+register('easeOutCubic', easeOutCubic);
+register('easeInOutCubic', easeInOutCubic);
+register('easeInQuart', easeInQuart);
+register('easeOutQuart', easeOutQuart);
+register('easeInOutQuart', easeInOutQuart);
+register('easeInQuint', easeInQuint);
+register('easeOutQuint', easeOutQuint);
+register('easeInOutQuint', easeInOutQuint);
+register('easeInSine', easeInSine);
+register('easeOutSine', easeOutSine);
+register('easeInOutSine', easeInOutSine);
+register('easeInExpo', easeInExpo);
+register('easeOutExpo', easeOutExpo);
+register('easeInOutExpo', easeInOutExpo);
+register('easeInCirc', easeInCirc);
+register('easeOutCirc', easeOutCirc);
+register('easeInOutCirc', easeInOutCirc);
+register('easeInBack', easeInBack);
+register('easeOutBack', easeOutBack);
+register('easeInOutBack', easeInOutBack);
+register('easeInElastic', easeInElastic);
+register('easeOutElastic', easeOutElastic);
+register('easeInOutElastic', easeInOutElastic);
+register('easeInBounce', easeInBounce);
+register('easeOutBounce', easeOutBounce);
+register('easeInOutBounce', easeInOutBounce);
+register('smooth', smooth);
+register('doubleSmooth', doubleSmooth);
+register('rushInto', rushInto);
+register('rushFrom', rushFrom);
+register('slowInto', slowInto);
+register('thereAndBack', thereAndBack);
+register('wiggle', wiggle);
+register('lingering', lingering());
+register('runningStart', runningStart());
+/**
+ * Resolves the name of an easing function for serialization.
+ */
+export function getEasingName(fn) {
+    return easingToName.get(fn) ?? 'smooth';
+}
+/**
+ * Resolves an easing function by its serialized name.
+ */
+export function getEasingByName(name) {
+    return nameToEasing.get(name);
+}

package/dist/core/serialization/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Serialization module for the Anima animation engine.
+ *
+ * This module provides functionality to convert Scenes, Mobjects, and Animations
+ * into JSON-compatible objects and back, enabling project persistence, undo/redo,
+ * and cross-process communication.
+ *
+ * Example usage:
+ * ```typescript
+ * import { serialize, deserialize } from './serialization';
+ *
+ * const json = serialize(scene);
+ * const restoredScene = deserialize(json);
+ * ```
+ */
+export { serialize, deserialize, serializeScene, deserializeScene } from './scene';
+export { prettyPrint, prettyPrintCompact } from './prettyPrint';
+export { serializeMobject, deserializeMobject, resetIdCounter } from './mobject';
+export { serializeAnimation, deserializeAnimation } from './animation';
+export { serializeVector2, deserializeVector2, serializeMatrix3x3, deserializeMatrix3x3, serializeColor, deserializeColor, serializeBezierPath, deserializeBezierPath, } from './primitives';
+export { registerSerializer, getSerializer, hasSerializer, unregisterSerializer, clearSerializerRegistry, } from './registry';
+export { getEasingName, getEasingByName } from './easingLookup';
+export type { SerializedVector2, SerializedColor, SerializedMatrix3x3, SerializedPathCommand, SerializedBezierPath, SerializedMobject, SerializedVMobject, SerializedVGroup, SerializedCircle, SerializedRectangle, SerializedLine, SerializedArc, SerializedPolygon, SerializedAnimation, SerializedAnimationConfig, SerializedMoveTo, SerializedRotate, SerializedScale, SerializedSequence, SerializedParallel, SerializedScheduledAnimation, SerializedTimeline, SerializedSceneConfig, SerializedScene, MobjectType, AnimationType, CustomSerializer, } from './types';