@redwilly/anima 0.1.0

package/dist/core/animations/camera/Shake.d.ts

@@ -0,0 +1,90 @@
+import { TransformativeAnimation } from '../categories';
+import { CameraFrame } from '../../camera/CameraFrame';
+/**
+ * Configuration options for the Shake animation.
+ */
+interface ShakeConfig {
+    /**
+     * Maximum displacement distance in world units.
+     * Higher values create more violent shaking.
+     * @default 0.2
+     */
+    intensity?: number;
+    /**
+     * Number of oscillations per second.
+     * Higher values create faster, more frantic shaking.
+     * @default 10
+     */
+    frequency?: number;
+    /**
+     * Controls how quickly the shake diminishes over time.
+     * - 0 = no decay (constant intensity throughout)
+     * - 1 = linear decay
+     * - Higher values = faster decay (shake fades quickly)
+     * @default 1
+     */
+    decay?: number;
+}
+/**
+ * Camera shake effect animation.
+ * Creates procedural displacement using layered sine waves to simulate
+ * impacts, explosions, or earthquakes.
+ *
+ * The shake automatically returns to the original position when complete.
+ *
+ * @example
+ * // Basic shake effect
+ * this.play(new Shake(this.frame).duration(0.5));
+ *
+ * @example
+ * // Intense explosion shake with quick decay
+ * this.play(new Shake(this.frame, {
+ *   intensity: 0.5,
+ *   frequency: 20,
+ *   decay: 2
+ * }).duration(0.3));
+ *
+ * @example
+ * // Subtle earthquake with slow decay
+ * this.play(new Shake(this.frame, {
+ *   intensity: 0.1,
+ *   frequency: 5,
+ *   decay: 0.5
+ * }).duration(3));
+ */
+export declare class Shake extends TransformativeAnimation<CameraFrame> {
+    private originalPosition;
+    private readonly intensity;
+    private readonly frequency;
+    private readonly decay;
+    private readonly seedX;
+    private readonly seedY;
+    /**
+     * Creates a new Shake animation.
+     *
+     * @param frame - The CameraFrame to shake
+     * @param config - Configuration options for intensity, frequency, and decay
+     *
+     * @example
+     * const shake = new Shake(scene.frame, { intensity: 0.3 });
+     * this.play(shake.duration(0.5));
+     */
+    constructor(frame: CameraFrame, config?: ShakeConfig);
+    /**
+     * Captures the original position before shake begins.
+     */
+    protected captureStartState(): void;
+    /**
+     * Applies procedural shake displacement each frame.
+     * @param progress - Animation progress (0 to 1)
+     */
+    interpolate(progress: number): void;
+    /**
+     * Generates pseudo-random noise using layered sine waves.
+     * @param t - Time value
+     * @param seed - Random seed for variation
+     * @returns Noise value between -1 and 1
+     */
+    private noise;
+}
+export {};

package/dist/core/animations/camera/Shake.js

@@ -0,0 +1,87 @@
+import { TransformativeAnimation } from '../categories';
+/**
+ * Camera shake effect animation.
+ * Creates procedural displacement using layered sine waves to simulate
+ * impacts, explosions, or earthquakes.
+ *
+ * The shake automatically returns to the original position when complete.
+ *
+ * @example
+ * // Basic shake effect
+ * this.play(new Shake(this.frame).duration(0.5));
+ *
+ * @example
+ * // Intense explosion shake with quick decay
+ * this.play(new Shake(this.frame, {
+ *   intensity: 0.5,
+ *   frequency: 20,
+ *   decay: 2
+ * }).duration(0.3));
+ *
+ * @example
+ * // Subtle earthquake with slow decay
+ * this.play(new Shake(this.frame, {
+ *   intensity: 0.1,
+ *   frequency: 5,
+ *   decay: 0.5
+ * }).duration(3));
+ */
+export class Shake extends TransformativeAnimation {
+    originalPosition;
+    intensity;
+    frequency;
+    decay;
+    seedX;
+    seedY;
+    /**
+     * Creates a new Shake animation.
+     *
+     * @param frame - The CameraFrame to shake
+     * @param config - Configuration options for intensity, frequency, and decay
+     *
+     * @example
+     * const shake = new Shake(scene.frame, { intensity: 0.3 });
+     * this.play(shake.duration(0.5));
+     */
+    constructor(frame, config = {}) {
+        super(frame);
+        this.intensity = config.intensity ?? 0.2;
+        this.frequency = config.frequency ?? 10;
+        this.decay = config.decay ?? 1;
+        this.seedX = Math.random() * 1000;
+        this.seedY = Math.random() * 1000;
+    }
+    /**
+     * Captures the original position before shake begins.
+     */
+    captureStartState() {
+        this.originalPosition = this.target.position;
+    }
+    /**
+     * Applies procedural shake displacement each frame.
+     * @param progress - Animation progress (0 to 1)
+     */
+    interpolate(progress) {
+        this.ensureInitialized();
+        if (progress >= 1) {
+            this.target.pos(this.originalPosition.x, this.originalPosition.y);
+            return;
+        }
+        const decayFactor = 1 - Math.pow(progress, this.decay);
+        const time = progress * this.durationSeconds * this.frequency;
+        const offsetX = this.noise(time, this.seedX) * this.intensity * decayFactor;
+        const offsetY = this.noise(time, this.seedY) * this.intensity * decayFactor;
+        this.target.pos(this.originalPosition.x + offsetX, this.originalPosition.y + offsetY);
+    }
+    /**
+     * Generates pseudo-random noise using layered sine waves.
+     * @param t - Time value
+     * @param seed - Random seed for variation
+     * @returns Noise value between -1 and 1
+     */
+    noise(t, seed) {
+        return Math.sin(t * 2 + seed) * 0.5 +
+            Math.sin(t * 3.7 + seed * 1.3) * 0.3 +
+            Math.sin(t * 7.1 + seed * 0.7) * 0.2;
+    }
+}

package/dist/core/animations/camera/index.d.ts

@@ -0,0 +1,2 @@
+export { Follow } from './Follow';
+export { Shake } from './Shake';

package/dist/core/animations/camera/index.js

@@ -0,0 +1,2 @@
+export { Follow } from './Follow';
+export { Shake } from './Shake';

package/dist/core/animations/categories/ExitAnimation.d.ts

@@ -0,0 +1,17 @@
+import { Animation } from '../Animation';
+import type { AnimationLifecycle } from '../types';
+import type { Mobject } from '../../../mobjects/Mobject';
+/**
+ * Abstract base class for animations that exit/remove an object from the scene.
+ *
+ * Exit animations:
+ * - Require the target to already be registered with the scene
+ * - Throw an error if the target is not in the scene
+ * - Typically animate opacity or scale to 0
+ * - May optionally auto-remove the target from the scene after completion
+ *
+ * Examples: FadeOut, ShrinkToCenter, Uncreate
+ */
+export declare abstract class ExitAnimation<T extends Mobject = Mobject> extends Animation<T> {
+    readonly lifecycle: AnimationLifecycle;
+}

package/dist/core/animations/categories/ExitAnimation.js

@@ -0,0 +1,15 @@
+import { Animation } from '../Animation';
+/**
+ * Abstract base class for animations that exit/remove an object from the scene.
+ *
+ * Exit animations:
+ * - Require the target to already be registered with the scene
+ * - Throw an error if the target is not in the scene
+ * - Typically animate opacity or scale to 0
+ * - May optionally auto-remove the target from the scene after completion
+ *
+ * Examples: FadeOut, ShrinkToCenter, Uncreate
+ */
+export class ExitAnimation extends Animation {
+    lifecycle = 'exit';
+}

package/dist/core/animations/categories/IntroductoryAnimation.d.ts

@@ -0,0 +1,16 @@
+import { Animation } from '../Animation';
+import type { AnimationLifecycle } from '../types';
+import type { Mobject } from '../../../mobjects/Mobject';
+/**
+ * Abstract base class for animations that introduce an object to the scene.
+ *
+ * Introductory animations:
+ * - Automatically register the target with the scene if not already present
+ * - Do not require the target to be in the scene beforehand
+ * - Typically animate opacity or drawing from 0 to visible
+ *
+ * Examples: FadeIn, Write, Draw, GrowFromCenter, SpinIn
+ */
+export declare abstract class IntroductoryAnimation<T extends Mobject = Mobject> extends Animation<T> {
+    readonly lifecycle: AnimationLifecycle;
+}

package/dist/core/animations/categories/IntroductoryAnimation.js

@@ -0,0 +1,14 @@
+import { Animation } from '../Animation';
+/**
+ * Abstract base class for animations that introduce an object to the scene.
+ *
+ * Introductory animations:
+ * - Automatically register the target with the scene if not already present
+ * - Do not require the target to be in the scene beforehand
+ * - Typically animate opacity or drawing from 0 to visible
+ *
+ * Examples: FadeIn, Write, Draw, GrowFromCenter, SpinIn
+ */
+export class IntroductoryAnimation extends Animation {
+    lifecycle = 'introductory';
+}

package/dist/core/animations/categories/TransformativeAnimation.d.ts

@@ -0,0 +1,25 @@
+import { Animation } from '../Animation';
+import type { AnimationLifecycle } from '../types';
+import type { Mobject } from '../../../mobjects/Mobject';
+/**
+ * Abstract base class for animations that transform an existing scene object.
+ *
+ * Transformative animations:
+ * - Require the target to already be registered with the scene
+ * - Throw an error if the target is not in the scene
+ * - Operate on objects that are already visible or have been introduced
+ * - Use lazy initialization to capture start state when animation becomes active
+ *
+ * Examples: MoveTo, Rotate, Scale, MorphTo, Transform
+ */
+export declare abstract class TransformativeAnimation<T extends Mobject = Mobject> extends Animation<T> {
+    readonly lifecycle: AnimationLifecycle;
+    protected initialized: boolean;
+    /**
+     * Captures the start state from the target.
+     * Called once when the animation first becomes active.
+     */
+    protected abstract captureStartState(): void;
+    ensureInitialized(): void;
+    reset(): void;
+}

package/dist/core/animations/categories/TransformativeAnimation.js

@@ -0,0 +1,25 @@
+import { Animation } from '../Animation';
+/**
+ * Abstract base class for animations that transform an existing scene object.
+ *
+ * Transformative animations:
+ * - Require the target to already be registered with the scene
+ * - Throw an error if the target is not in the scene
+ * - Operate on objects that are already visible or have been introduced
+ * - Use lazy initialization to capture start state when animation becomes active
+ *
+ * Examples: MoveTo, Rotate, Scale, MorphTo, Transform
+ */
+export class TransformativeAnimation extends Animation {
+    lifecycle = 'transformative';
+    initialized = false;
+    ensureInitialized() {
+        if (!this.initialized) {
+            this.captureStartState();
+            this.initialized = true;
+        }
+    }
+    reset() {
+        this.initialized = false;
+    }
+}

package/dist/core/animations/categories/index.d.ts

@@ -0,0 +1,3 @@
+export { IntroductoryAnimation } from './IntroductoryAnimation';
+export { TransformativeAnimation } from './TransformativeAnimation';
+export { ExitAnimation } from './ExitAnimation';

package/dist/core/animations/categories/index.js

@@ -0,0 +1,3 @@
+export { IntroductoryAnimation } from './IntroductoryAnimation';
+export { TransformativeAnimation } from './TransformativeAnimation';
+export { ExitAnimation } from './ExitAnimation';

package/dist/core/animations/composition/Parallel.d.ts

@@ -0,0 +1,37 @@
+import { Mobject } from '../../../mobjects/Mobject';
+import { Animation } from '../Animation';
+import type { AnimationLifecycle } from '../types';
+/**
+ * Executes animations in parallel, all starting at the same time.
+ * Total duration equals the maximum of all child animation durations.
+ *
+ * This is a composition animation - its lifecycle is determined by its children.
+ * By default, uses 'transformative' lifecycle if children are mixed.
+ *
+ * All children are initialized together before any interpolation begins,
+ * ensuring they all capture state at the same moment.
+ */
+export declare class Parallel extends Animation<Mobject> {
+    private readonly children;
+    private readonly maxChildDuration;
+    /**
+     * The lifecycle of Parallel is 'introductory' only if ALL children are introductory.
+     * Otherwise, it defaults to 'transformative'.
+     */
+    readonly lifecycle: AnimationLifecycle;
+    constructor(animations: Animation[]);
+    getDuration(): number;
+    getChildren(): readonly Animation[];
+    /**
+     * Ensures all children are initialized together.
+     * This captures start state for all parallel animations at the same moment.
+     */
+    ensureInitialized(): void;
+    reset(): void;
+    /**
+     * Interpolates all child animations at the given progress.
+     * Each child's progress is scaled based on its duration relative to the container.
+     */
+    interpolate(progress: number): void;
+    update(progress: number): void;
+}

package/dist/core/animations/composition/Parallel.js

@@ -0,0 +1,79 @@
+import { Mobject } from '../../../mobjects/Mobject';
+import { Animation } from '../Animation';
+/**
+ * Executes animations in parallel, all starting at the same time.
+ * Total duration equals the maximum of all child animation durations.
+ *
+ * This is a composition animation - its lifecycle is determined by its children.
+ * By default, uses 'transformative' lifecycle if children are mixed.
+ *
+ * All children are initialized together before any interpolation begins,
+ * ensuring they all capture state at the same moment.
+ */
+export class Parallel extends Animation {
+    children;
+    maxChildDuration;
+    /**
+     * The lifecycle of Parallel is 'introductory' only if ALL children are introductory.
+     * Otherwise, it defaults to 'transformative'.
+     */
+    lifecycle;
+    constructor(animations) {
+        super(new Mobject());
+        this.children = animations;
+        this.maxChildDuration = animations.reduce((max, a) => Math.max(max, a.getDuration()), 0);
+        this.durationSeconds = this.maxChildDuration;
+        // Lifecycle is introductory only if ALL children are introductory
+        this.lifecycle = animations.every(a => a.lifecycle === 'introductory')
+            ? 'introductory'
+            : 'transformative';
+    }
+    getDuration() {
+        return this.durationSeconds;
+    }
+    getChildren() {
+        return this.children;
+    }
+    /**
+     * Ensures all children are initialized together.
+     * This captures start state for all parallel animations at the same moment.
+     */
+    ensureInitialized() {
+        for (const child of this.children) {
+            child.ensureInitialized();
+        }
+    }
+    reset() {
+        for (const child of this.children) {
+            child.reset();
+        }
+    }
+    /**
+     * Interpolates all child animations at the given progress.
+     * Each child's progress is scaled based on its duration relative to the container.
+     */
+    interpolate(progress) {
+        if (this.children.length === 0 || this.maxChildDuration === 0) {
+            return;
+        }
+        const globalTime = progress * this.maxChildDuration;
+        for (const child of this.children) {
+            const childDuration = child.getDuration();
+            if (childDuration === 0) {
+                child.update(1);
+                continue;
+            }
+            // Calculate local progress for this child
+            const localProgress = Math.min(1, globalTime / childDuration);
+            child.update(localProgress);
+        }
+    }
+    update(progress) {
+        // Pre-initialize ALL children before ANY interpolation
+        // This ensures parallel animations capture state at the same moment
+        this.ensureInitialized();
+        const clampedProgress = Math.max(0, Math.min(1, progress));
+        // Composition animations should not apply easing to their children
+        this.interpolate(clampedProgress);
+    }
+}

package/dist/core/animations/composition/Sequence.d.ts

@@ -0,0 +1,41 @@
+import { Mobject } from '../../../mobjects/Mobject';
+import { Animation } from '../Animation';
+import type { AnimationLifecycle } from '../types';
+/**
+ * Executes animations in sequence, one after another.
+ * Total duration equals the sum of all child animation durations.
+ *
+ * This is a composition animation - its lifecycle is determined by its children.
+ * Only the first child is initialized when the sequence starts; subsequent
+ * children are initialized when they become active.
+ */
+export declare class Sequence extends Animation<Mobject> {
+    private readonly children;
+    private readonly childDurations;
+    private readonly totalChildDuration;
+    /**
+     * The lifecycle of Sequence is determined by its FIRST child animation.
+     * If the first animation is introductory, it will register the target,
+     * allowing subsequent transformative animations to work.
+     */
+    readonly lifecycle: AnimationLifecycle;
+    constructor(animations: Animation[]);
+    getDuration(): number;
+    getChildren(): readonly Animation[];
+    /**
+     * Initializes only the first child.
+     * Later children are initialized when they become active in interpolate().
+     */
+    ensureInitialized(): void;
+    reset(): void;
+    /**
+     * Interpolates the sequence at the given progress.
+     * Maps global progress to the correct child animation.
+     *
+     * IMPORTANT: We only update children that have started or completed.
+     * Children that haven't started yet are NOT updated to avoid
+     * premature initialization with incorrect state.
+     */
+    interpolate(progress: number): void;
+    update(progress: number): void;
+}

package/dist/core/animations/composition/Sequence.js

@@ -0,0 +1,95 @@
+import { Mobject } from '../../../mobjects/Mobject';
+import { Animation } from '../Animation';
+/**
+ * Executes animations in sequence, one after another.
+ * Total duration equals the sum of all child animation durations.
+ *
+ * This is a composition animation - its lifecycle is determined by its children.
+ * Only the first child is initialized when the sequence starts; subsequent
+ * children are initialized when they become active.
+ */
+export class Sequence extends Animation {
+    children;
+    childDurations;
+    totalChildDuration;
+    /**
+     * The lifecycle of Sequence is determined by its FIRST child animation.
+     * If the first animation is introductory, it will register the target,
+     * allowing subsequent transformative animations to work.
+     */
+    lifecycle;
+    constructor(animations) {
+        super(new Mobject());
+        this.children = animations;
+        this.childDurations = animations.map((a) => a.getDuration());
+        this.totalChildDuration = this.childDurations.reduce((sum, d) => sum + d, 0);
+        this.durationSeconds = this.totalChildDuration;
+        // Lifecycle is determined by FIRST animation in the sequence
+        // If first is introductory, it registers the target for subsequent animations
+        const first = animations[0];
+        this.lifecycle = first?.lifecycle === 'introductory' ? 'introductory' : 'transformative';
+    }
+    getDuration() {
+        return this.durationSeconds;
+    }
+    getChildren() {
+        return this.children;
+    }
+    /**
+     * Initializes only the first child.
+     * Later children are initialized when they become active in interpolate().
+     */
+    ensureInitialized() {
+        if (this.children.length > 0) {
+            this.children[0].ensureInitialized();
+        }
+    }
+    reset() {
+        for (const child of this.children) {
+            child.reset();
+        }
+    }
+    /**
+     * Interpolates the sequence at the given progress.
+     * Maps global progress to the correct child animation.
+     *
+     * IMPORTANT: We only update children that have started or completed.
+     * Children that haven't started yet are NOT updated to avoid
+     * premature initialization with incorrect state.
+     */
+    interpolate(progress) {
+        if (this.children.length === 0 || this.totalChildDuration === 0) {
+            return;
+        }
+        const globalTime = progress * this.totalChildDuration;
+        let accumulatedTime = 0;
+        for (let i = 0; i < this.children.length; i++) {
+            const child = this.children[i];
+            const childDuration = this.childDurations[i];
+            if (child === undefined || childDuration === undefined) {
+                continue;
+            }
+            const childStart = accumulatedTime;
+            const childEnd = accumulatedTime + childDuration;
+            if (globalTime < childStart) {
+                // Before this child starts - DO NOT UPDATE
+                // Updating would prematurely initialize with wrong state
+            }
+            else if (globalTime >= childEnd) {
+                // This child is complete
+                child.update(1);
+            }
+            else {
+                // This child is active
+                const localProgress = (globalTime - childStart) / childDuration;
+                child.update(localProgress);
+            }
+            accumulatedTime = childEnd;
+        }
+    }
+    update(progress) {
+        const clampedProgress = Math.max(0, Math.min(1, progress));
+        // Composition animations should not apply easing to their children
+        this.interpolate(clampedProgress);
+    }
+}

package/dist/core/animations/composition/index.d.ts

@@ -0,0 +1,2 @@
+export { Sequence } from './Sequence';
+export { Parallel } from './Parallel';

package/dist/core/animations/composition/index.js

@@ -0,0 +1,3 @@
+// Animation composition containers
+export { Sequence } from './Sequence';
+export { Parallel } from './Parallel';

package/dist/core/animations/draw/Draw.d.ts

@@ -0,0 +1,30 @@
+import { IntroductoryAnimation } from '../categories';
+import { VMobject } from '../../../mobjects/VMobject';
+/**
+ * Animation that first draws the border progressively, then fills the shape.
+ * The first 50% of the animation draws the stroke, the second 50% fades in the fill.
+ *
+ * Supports VGroup (including Text): animates each child's paths progressively.
+ *
+ * This is an introductory animation - it auto-registers the target with the scene.
+ *
+ * @example
+ * const rect = new Rectangle(2, 1);
+ * scene.play(new Draw(rect));  // Border draws, then fill fades in
+ */
+export declare class Draw<T extends VMobject = VMobject> extends IntroductoryAnimation<T> {
+    private readonly isVGroup;
+    /** For non-VGroup targets: original paths on the target itself. */
+    private readonly originalPaths;
+    private readonly originalFillOpacity;
+    private readonly originalOpacity;
+    /** For VGroup targets: original state of each child. */
+    private readonly childStates;
+    constructor(target: T);
+    /** Interpolates stroke drawing (0-0.5) and then fill fade (0.5-1). */
+    interpolate(progress: number): void;
+    /** Interpolates a single VMobject (non-VGroup). */
+    private interpolateVMobject;
+    /** Interpolates a VGroup by animating each child's paths. */
+    private interpolateVGroup;
+}