@redwilly/anima 0.1.0

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

@@ -0,0 +1,152 @@
+/**
+ * Serialization types and interfaces.
+ *
+ * All serialized types are plain JSON-compatible objects that represent
+ * the state of a component in a format that can be persisted or transmitted.
+ */
+import type { PathCommandType } from '../math/bezier/types';
+/** Serialized 2D vector */
+export interface SerializedVector2 {
+    readonly x: number;
+    readonly y: number;
+}
+/** Serialized RGBA color */
+export interface SerializedColor {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+/** Serialized 3x3 transformation matrix */
+export interface SerializedMatrix3x3 {
+    readonly values: readonly number[];
+}
+/** Serialized Bezier path command */
+export interface SerializedPathCommand {
+    readonly type: PathCommandType;
+    readonly end: SerializedVector2;
+    readonly control1?: SerializedVector2;
+    readonly control2?: SerializedVector2;
+}
+/** Serialized Bezier path composed of multiple commands */
+export interface SerializedBezierPath {
+    readonly commands: readonly SerializedPathCommand[];
+}
+/** Type discriminator for polymorphic deserialization */
+export type MobjectType = 'Mobject' | 'VMobject' | 'VGroup' | 'Circle' | 'Rectangle' | 'Line' | 'Arrow' | 'Arc' | 'Polygon' | 'Point' | 'Text' | 'Glyph' | 'Graph' | 'GraphNode' | 'GraphEdge' | string;
+/** Base properties for all serialized Mobjects */
+export interface SerializedMobject {
+    readonly type: MobjectType;
+    readonly id: string;
+    readonly matrix: SerializedMatrix3x3;
+    readonly opacity: number;
+}
+/** Serialized properties for Vector Mobjects (VMobjects) */
+export interface SerializedVMobject extends SerializedMobject {
+    readonly paths: readonly SerializedBezierPath[];
+    readonly strokeColor: SerializedColor;
+    readonly strokeWidth: number;
+    readonly fillColor: SerializedColor;
+    readonly fillOpacity: number;
+}
+export interface SerializedVGroup extends SerializedMobject {
+    readonly children: readonly SerializedMobject[];
+}
+export interface SerializedCircle extends SerializedVMobject {
+    readonly type: 'Circle';
+    readonly radius: number;
+}
+export interface SerializedRectangle extends SerializedVMobject {
+    readonly type: 'Rectangle';
+    readonly width: number;
+    readonly height: number;
+}
+export interface SerializedLine extends SerializedVMobject {
+    readonly type: 'Line';
+    readonly start: SerializedVector2;
+    readonly end: SerializedVector2;
+}
+export interface SerializedArc extends SerializedVMobject {
+    readonly type: 'Arc';
+    readonly radius: number;
+    readonly startAngle: number;
+    readonly endAngle: number;
+}
+export interface SerializedPolygon extends SerializedVMobject {
+    readonly type: 'Polygon';
+    readonly vertices: readonly SerializedVector2[];
+}
+export interface SerializedPoint extends SerializedVMobject {
+    readonly type: 'Point';
+    readonly position: SerializedVector2;
+}
+export type AnimationType = 'FadeIn' | 'FadeOut' | 'MoveTo' | 'Rotate' | 'Scale' | 'MorphTo' | 'Create' | 'Draw' | 'Write' | 'Unwrite' | 'Sequence' | 'Parallel' | 'KeyframeAnimation' | string;
+export interface SerializedAnimationConfig {
+    readonly durationSeconds: number;
+    readonly delaySeconds: number;
+    readonly easingName: string;
+}
+/** Base properties for all serialized animations */
+export interface SerializedAnimation {
+    readonly type: AnimationType;
+    readonly targetId: string;
+    readonly config: SerializedAnimationConfig;
+}
+export interface SerializedMoveTo extends SerializedAnimation {
+    readonly type: 'MoveTo';
+    readonly destination: SerializedVector2;
+}
+export interface SerializedRotate extends SerializedAnimation {
+    readonly type: 'Rotate';
+    readonly angle: number;
+}
+export interface SerializedScale extends SerializedAnimation {
+    readonly type: 'Scale';
+    readonly factor: number;
+}
+export interface SerializedMorphTo extends SerializedAnimation {
+    readonly type: 'MorphTo';
+    readonly targetShapeId: string;
+}
+export interface SerializedSequence extends SerializedAnimation {
+    readonly type: 'Sequence';
+    readonly animations: readonly SerializedAnimation[];
+}
+export interface SerializedParallel extends SerializedAnimation {
+    readonly type: 'Parallel';
+    readonly animations: readonly SerializedAnimation[];
+}
+export interface SerializedScheduledAnimation {
+    readonly animation: SerializedAnimation;
+    readonly startTime: number;
+}
+/** Serialized timeline state including all scheduled animations */
+export interface SerializedTimeline {
+    readonly loop: boolean;
+    readonly scheduled: readonly SerializedScheduledAnimation[];
+}
+export interface SerializedSceneConfig {
+    readonly width: number;
+    readonly height: number;
+    readonly backgroundColor: SerializedColor;
+    readonly frameRate: number;
+}
+/** Top-level serialized scene container */
+export interface SerializedScene {
+    readonly version: string;
+    readonly config: SerializedSceneConfig;
+    readonly mobjects: readonly SerializedMobject[];
+    readonly timeline: SerializedTimeline;
+}
+/**
+ * Interface for custom serializers.
+ *
+ * Allows extending the serialization system to support user-defined Mobject types.
+ */
+export interface CustomSerializer<T> {
+    readonly typeName: string;
+    /** Serialize an instance to a plain object */
+    serialize(instance: T): SerializedMobject;
+    /** Restore an instance from a plain object */
+    deserialize(data: SerializedMobject): T;
+}

package/dist/core/serialization/types.js

@@ -0,0 +1,6 @@
+/**
+ * Serialization types and interfaces.
+ *
+ * All serialized types are plain JSON-compatible objects that represent
+ * the state of a component in a format that can be persisted or transmitted.
+ */

package/dist/core/timeline/Timeline.d.ts

@@ -0,0 +1,70 @@
+import type { Animation } from '../animations/Animation';
+import type { ScheduledAnimation, TimelineConfig } from './types';
+/**
+ * Timeline schedules and controls playback of animations.
+ * Animations can be scheduled at specific times and the timeline
+ * provides seek/state access for non-linear playback.
+ */
+export declare class Timeline {
+    private readonly scheduled;
+    private readonly config;
+    private currentTime;
+    constructor(config?: TimelineConfig);
+    /**
+     * Schedule an animation to start at a specific time.
+     * @param animation The animation to schedule
+     * @param startTime Start time in seconds (default: 0)
+     */
+    schedule(animation: Animation, startTime?: number): this;
+    /**
+     * Schedule multiple animations to play in sequence.
+     * First animation starts at the given startTime, subsequent
+     * animations start after the previous one ends.
+     * @param animations Animations to schedule sequentially
+     * @param startTime Start time for the first animation (default: 0)
+     */
+    scheduleSequence(animations: Animation[], startTime?: number): this;
+    /**
+     * Schedule multiple animations to play in parallel.
+     * All animations start at the same time.
+     * @param animations Animations to schedule in parallel
+     * @param startTime Start time for all animations (default: 0)
+     */
+    scheduleParallel(animations: Animation[], startTime?: number): this;
+    /**
+     * Get all scheduled animations with resolved timing information.
+     */
+    private getResolved;
+    /**
+     * Get total duration of the timeline.
+     * Returns the end time of the last animation to finish.
+     */
+    getTotalDuration(): number;
+    /**
+     * Seek to a specific time and update all animations.
+     * @param time Time in seconds to seek to
+     */
+    seek(time: number): void;
+    /**
+     * Get the timeline state at a specific time without modifying the
+     * current playhead position.
+     * @param time Time in seconds
+     */
+    getStateAt(time: number): void;
+    /**
+     * Get the current time of the timeline.
+     */
+    getCurrentTime(): number;
+    /**
+     * Get all scheduled animations.
+     */
+    getScheduled(): readonly ScheduledAnimation[];
+    /**
+     * Check if timeline is configured to loop.
+     */
+    isLooping(): boolean;
+    /**
+     * Clear all scheduled animations.
+     */
+    clear(): void;
+}

package/dist/core/timeline/Timeline.js

@@ -0,0 +1,144 @@
+/**
+ * Timeline schedules and controls playback of animations.
+ * Animations can be scheduled at specific times and the timeline
+ * provides seek/state access for non-linear playback.
+ */
+export class Timeline {
+    scheduled = [];
+    config;
+    currentTime = 0;
+    constructor(config = {}) {
+        this.config = {
+            loop: config.loop ?? false,
+        };
+    }
+    /**
+     * Schedule an animation to start at a specific time.
+     * @param animation The animation to schedule
+     * @param startTime Start time in seconds (default: 0)
+     */
+    schedule(animation, startTime = 0) {
+        if (startTime < 0) {
+            throw new Error('Start time must be non-negative');
+        }
+        this.scheduled.push({ animation, startTime });
+        return this;
+    }
+    /**
+     * Schedule multiple animations to play in sequence.
+     * First animation starts at the given startTime, subsequent
+     * animations start after the previous one ends.
+     * @param animations Animations to schedule sequentially
+     * @param startTime Start time for the first animation (default: 0)
+     */
+    scheduleSequence(animations, startTime = 0) {
+        let currentStart = startTime;
+        for (const anim of animations) {
+            this.schedule(anim, currentStart);
+            currentStart += anim.getDuration() + anim.getDelay();
+        }
+        return this;
+    }
+    /**
+     * Schedule multiple animations to play in parallel.
+     * All animations start at the same time.
+     * @param animations Animations to schedule in parallel
+     * @param startTime Start time for all animations (default: 0)
+     */
+    scheduleParallel(animations, startTime = 0) {
+        for (const anim of animations) {
+            this.schedule(anim, startTime);
+        }
+        return this;
+    }
+    /**
+     * Get all scheduled animations with resolved timing information.
+     */
+    getResolved() {
+        return this.scheduled.map((s) => {
+            const delay = s.animation.getDelay();
+            const duration = s.animation.getDuration();
+            const effectiveStartTime = s.startTime + delay;
+            return {
+                animation: s.animation,
+                effectiveStartTime,
+                duration,
+                endTime: effectiveStartTime + duration,
+            };
+        });
+    }
+    /**
+     * Get total duration of the timeline.
+     * Returns the end time of the last animation to finish.
+     */
+    getTotalDuration() {
+        const resolved = this.getResolved();
+        if (resolved.length === 0)
+            return 0;
+        return Math.max(...resolved.map((r) => r.endTime));
+    }
+    /**
+     * Seek to a specific time and update all animations.
+     * @param time Time in seconds to seek to
+     */
+    seek(time) {
+        const clampedTime = Math.max(0, time);
+        this.currentTime = clampedTime;
+        const resolved = this.getResolved();
+        for (const r of resolved) {
+            const { animation, effectiveStartTime, duration, endTime } = r;
+            if (clampedTime < effectiveStartTime) {
+                // Before animation starts - do NOT update the animation.
+                // This prevents future animations from overwriting state
+                // that earlier animations have already set.
+                // The animation will be initialized when it first becomes active.
+                continue;
+            }
+            else if (clampedTime >= endTime) {
+                // Animation completed - set to final state
+                animation.update(1);
+            }
+            else {
+                // Animation is active - calculate progress
+                const elapsed = clampedTime - effectiveStartTime;
+                const progress = duration > 0 ? elapsed / duration : 1;
+                animation.update(progress);
+            }
+        }
+    }
+    /**
+     * Get the timeline state at a specific time without modifying the
+     * current playhead position.
+     * @param time Time in seconds
+     */
+    getStateAt(time) {
+        const savedTime = this.currentTime;
+        this.seek(time);
+        this.currentTime = savedTime;
+    }
+    /**
+     * Get the current time of the timeline.
+     */
+    getCurrentTime() {
+        return this.currentTime;
+    }
+    /**
+     * Get all scheduled animations.
+     */
+    getScheduled() {
+        return this.scheduled;
+    }
+    /**
+     * Check if timeline is configured to loop.
+     */
+    isLooping() {
+        return this.config.loop;
+    }
+    /**
+     * Clear all scheduled animations.
+     */
+    clear() {
+        this.scheduled.length = 0;
+        this.currentTime = 0;
+    }
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Timeline module for scheduling and controlling animation playback.
+ */
+export { Timeline } from './Timeline';
+export type { ScheduledAnimation, TimelineConfig, ResolvedScheduledAnimation, } from './types';

package/dist/core/timeline/index.js

@@ -0,0 +1,4 @@
+/**
+ * Timeline module for scheduling and controlling animation playback.
+ */
+export { Timeline } from './Timeline';

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

@@ -0,0 +1,29 @@
+import type { Animation } from '../animations/Animation';
+/**
+ * Represents an animation scheduled at a specific time on the Timeline.
+ */
+export interface ScheduledAnimation {
+    /** The animation to play */
+    readonly animation: Animation;
+    /** Start time in seconds from timeline beginning */
+    readonly startTime: number;
+}
+/**
+ * Configuration options for Timeline.
+ */
+export interface TimelineConfig {
+    /** Whether the timeline loops. Default: false */
+    readonly loop?: boolean;
+}
+/**
+ * Internal representation of a scheduled animation with computed timing.
+ */
+export interface ResolvedScheduledAnimation {
+    readonly animation: Animation;
+    /** Effective start time including animation delay */
+    readonly effectiveStartTime: number;
+    /** Duration of the animation */
+    readonly duration: number;
+    /** End time = effectiveStartTime + duration */
+    readonly endTime: number;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { Scene } from './core/scene';
+export type { SceneConfig } from './core/scene';
+export { Mobject, VMobject, VGroup } from './mobjects';
+export { Camera, CameraFrame } from './core/camera';
+export type { CameraConfig, ResolvedCameraConfig } from './core/camera';
+export { Circle, Rectangle, Line, Arrow, Arc, Polygon, Point } from './mobjects/geometry';
+export { Text, Glyph } from './mobjects/text';
+export type { TextStyle } from './mobjects/text';
+export { Graph, GraphNode, GraphEdge } from './mobjects/graph';
+export type { GraphNodeId, NodeConfig, EdgeConfig, LayoutType, LayoutConfig } from './mobjects/graph';
+export { Animation, FadeIn, FadeOut, MoveTo, Rotate, Scale, MorphTo, Draw, Write, Unwrite, Sequence, Parallel, KeyframeTrack, KeyframeAnimation, Follow, Shake } from './core/animations';
+export type { AnimationConfig, Keyframe } from './core/animations';
+export { Color, Vector2 } from './core/math';
+export { serialize, deserialize } from './core/serialization';
+export { Timeline } from './core/timeline';
+export type { ScheduledAnimation, TimelineConfig } from './core/timeline';
+export { Renderer, FrameRenderer, ProgressReporter, Resolution } from './core/renderer';
+export * from './core/animations/easing';

package/dist/index.js

@@ -0,0 +1,22 @@
+// Core Classes - Essential for all users
+export { Scene } from './core/scene';
+// Mobjects - Visual objects that can be animated
+export { Mobject, VMobject, VGroup } from './mobjects';
+// Camera
+export { Camera, CameraFrame } from './core/camera';
+// Geometric Primitives
+export { Circle, Rectangle, Line, Arrow, Arc, Polygon, Point } from './mobjects/geometry';
+// Text and Graph - Advanced visualization
+export { Text, Glyph } from './mobjects/text';
+export { Graph, GraphNode, GraphEdge } from './mobjects/graph';
+// FluentAPI - Chainable animations (built into mobjects above)
+// No exports needed - methods are available on mobject instances
+// ProAPI - Explicit animation objects for advanced users
+export { Animation, FadeIn, FadeOut, MoveTo, Rotate, Scale, MorphTo, Draw, Write, Unwrite, Sequence, Parallel, KeyframeTrack, KeyframeAnimation, Follow, Shake } from './core/animations';
+export { Color, Vector2 } from './core/math';
+// Serialization - For saving/loading animations
+export { serialize, deserialize } from './core/serialization';
+export { Timeline } from './core/timeline';
+export { Renderer, FrameRenderer, ProgressReporter, Resolution } from './core/renderer';
+// Easing Functions - Essential for animation control
+export * from './core/animations/easing';

package/dist/mobjects/Mobject.d.ts

@@ -0,0 +1,98 @@
+import { Matrix3x3 } from '../core/math/matrix/Matrix3x3';
+import { Vector2 } from '../core/math/Vector2/Vector2';
+import { Animation } from '../core/animations/Animation';
+import type { EasingFunction } from '../core/animations/easing';
+/**
+ * Manages a queue of animations for fluent chaining.
+ * This is an internal implementation detail of Mobject's fluent API.
+ */
+declare class AnimationQueue {
+    private readonly target;
+    private readonly queue;
+    constructor(target: Mobject);
+    enqueueAnimation(animation: Animation<Mobject>): void;
+    setLastDuration(seconds: number): void;
+    setLastEasing(easing: EasingFunction): void;
+    isEmpty(): boolean;
+    popLastAnimation(): Animation<Mobject> | null;
+    toAnimation(): Animation<Mobject>;
+    getTotalDuration(): number;
+}
+interface MobjectState {
+    position: Vector2;
+    scale: Vector2;
+    rotation: number;
+}
+/**
+ * Base class for all mathematical objects.
+ * Manages position, rotation, scale, and opacity via a local transformation matrix.
+ * Includes fluent animation API for chainable animations.
+ */
+export declare class Mobject {
+    protected localMatrix: Matrix3x3;
+    protected opacityValue: number;
+    protected animQueue: AnimationQueue | null;
+    private savedStates;
+    parent: Mobject | null;
+    constructor();
+    protected getQueue(): AnimationQueue;
+    get matrix(): Matrix3x3;
+    getWorldMatrix(): Matrix3x3;
+    get position(): Vector2;
+    get rotation(): number;
+    get scale(): Vector2;
+    get opacity(): number;
+    pos(x: number, y: number): this;
+    show(): this;
+    hide(): this;
+    setOpacity(value: number): this;
+    setRotation(angle: number): this;
+    setScale(sx: number, sy: number): this;
+    applyMatrix(m: Matrix3x3): this;
+    saveState(): this;
+    getSavedState(): MobjectState | undefined;
+    clearSavedStates(): this;
+    /**
+     * Animates back to the last saved state.
+     * Pops the saved state from the stack.
+     * @throws Error if no state was previously saved
+     */
+    restore(durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    private createAnimation;
+    fadeIn(durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    fadeOut(durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    moveTo(x: number, y: number, durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    rotate(angle: number, durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    scaleTo(factor: number, durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    scaleToXY(factorX: number, factorY: number, durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    duration(seconds: number): this;
+    ease(easing: EasingFunction): this;
+    toAnimation(): Animation<Mobject>;
+    getQueuedDuration(): number;
+    hasQueuedAnimations(): boolean;
+    /**
+     * Queues multiple animations to run in parallel (simultaneously).
+     * Automatically handles both Animation objects and mobject method calls.
+     * @example
+     * circle.fadeIn(1).parallel(
+     *     circle.moveTo(100, 50),
+     *     circle.rotate(Math.PI)
+     * ).fadeOut(1);
+     */
+    parallel(...items: (Animation<Mobject> | Mobject)[]): this;
+}
+export {};