@redwilly/anima 0.1.0

package/dist/core/animations/keyframes/KeyframeTrack.d.ts

@@ -0,0 +1,31 @@
+import type { EasingFunction } from '../easing';
+import type { Keyframe, KeyframeValue, InterpolatorFn } from './types';
+/**
+ * Manages a sequence of keyframes for animating a single property.
+ * Keyframes are stored sorted by time and interpolated on demand.
+ */
+export declare class KeyframeTrack<T extends KeyframeValue = number> {
+    private keyframes;
+    private readonly interpolator;
+    /**
+     * Creates a new KeyframeTrack with the specified interpolator.
+     * Defaults to linear number interpolation.
+     */
+    constructor(interpolator?: InterpolatorFn<T>);
+    /**
+     * Adds a keyframe at the specified normalized time.
+     * Time must be in [0, 1]. Replaces existing keyframe at same time.
+     */
+    addKeyframe(time: number, value: T, easing?: EasingFunction): this;
+    removeKeyframe(time: number): boolean;
+    /**
+     * Gets the keyframe at the specified time.
+     * Returns undefined if no keyframe exists at that time.
+     */
+    getKeyframe(time: number): Keyframe<T> | undefined;
+    /** All keyframes sorted by time. */
+    getKeyframes(): ReadonlyArray<Keyframe<T>>;
+    /** Interpolated value at normalized time (uses target keyframe easing). */
+    getValueAt(time: number): T;
+    getKeyframeCount(): number;
+}

package/dist/core/animations/keyframes/KeyframeTrack.js

@@ -0,0 +1,83 @@
+import { linear } from '../easing';
+import { lerpNumber } from './types';
+/**
+ * Manages a sequence of keyframes for animating a single property.
+ * Keyframes are stored sorted by time and interpolated on demand.
+ */
+export class KeyframeTrack {
+    keyframes = [];
+    interpolator;
+    /**
+     * Creates a new KeyframeTrack with the specified interpolator.
+     * Defaults to linear number interpolation.
+     */
+    constructor(interpolator) {
+        this.interpolator = interpolator ?? lerpNumber;
+    }
+    /**
+     * Adds a keyframe at the specified normalized time.
+     * Time must be in [0, 1]. Replaces existing keyframe at same time.
+     */
+    addKeyframe(time, value, easing) {
+        if (time < 0 || time > 1) {
+            throw new Error('Keyframe time must be in [0, 1]');
+        }
+        // Remove existing keyframe at same time
+        this.keyframes = this.keyframes.filter((kf) => kf.time !== time);
+        const keyframe = { time, value, easing };
+        this.keyframes.push(keyframe);
+        this.keyframes.sort((a, b) => a.time - b.time);
+        return this;
+    }
+    removeKeyframe(time) {
+        const initialLength = this.keyframes.length;
+        this.keyframes = this.keyframes.filter((kf) => kf.time !== time);
+        return this.keyframes.length < initialLength;
+    }
+    /**
+     * Gets the keyframe at the specified time.
+     * Returns undefined if no keyframe exists at that time.
+     */
+    getKeyframe(time) {
+        return this.keyframes.find((kf) => kf.time === time);
+    }
+    /** All keyframes sorted by time. */
+    getKeyframes() {
+        return this.keyframes;
+    }
+    /** Interpolated value at normalized time (uses target keyframe easing). */
+    getValueAt(time) {
+        if (this.keyframes.length === 0) {
+            throw new Error('KeyframeTrack has no keyframes');
+        }
+        const clampedTime = Math.max(0, Math.min(1, time));
+        // Find keyframes before and after the requested time
+        let prevKeyframe;
+        let nextKeyframe;
+        for (const kf of this.keyframes) {
+            if (kf.time <= clampedTime) {
+                prevKeyframe = kf;
+            }
+            if (kf.time >= clampedTime && nextKeyframe === undefined) {
+                nextKeyframe = kf;
+            }
+        }
+        if (prevKeyframe === undefined) {
+            return this.keyframes[0].value;
+        }
+        if (nextKeyframe === undefined) {
+            return prevKeyframe.value;
+        }
+        if (prevKeyframe === nextKeyframe) {
+            return prevKeyframe.value;
+        }
+        const span = nextKeyframe.time - prevKeyframe.time;
+        const localProgress = (clampedTime - prevKeyframe.time) / span;
+        const easing = nextKeyframe.easing ?? linear;
+        const easedProgress = easing(localProgress);
+        return this.interpolator(prevKeyframe.value, nextKeyframe.value, easedProgress);
+    }
+    getKeyframeCount() {
+        return this.keyframes.length;
+    }
+}

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

@@ -0,0 +1,4 @@
+export type { Keyframe, KeyframeValue, InterpolatorFn } from './types';
+export { lerpNumber } from './types';
+export { KeyframeTrack } from './KeyframeTrack';
+export { KeyframeAnimation } from './KeyframeAnimation';

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

@@ -0,0 +1,5 @@
+export { lerpNumber } from './types';
+// Keyframe track
+export { KeyframeTrack } from './KeyframeTrack';
+// Keyframe animation
+export { KeyframeAnimation } from './KeyframeAnimation';

package/dist/core/animations/keyframes/types.d.ts

@@ -0,0 +1,25 @@
+import type { EasingFunction } from '../easing';
+/**
+ * Supported value types for keyframe interpolation.
+ */
+export type KeyframeValue = number;
+/**
+ * A single keyframe with a normalized time position [0,1] and value.
+ */
+export interface Keyframe<T extends KeyframeValue = KeyframeValue> {
+    /** Normalized time position in [0, 1]. */
+    readonly time: number;
+    /** The value at this keyframe. */
+    readonly value: T;
+    /** Optional easing function for interpolation TO this keyframe. */
+    readonly easing?: EasingFunction;
+}
+/**
+ * Interpolation function for a specific value type.
+ * Takes start value, end value, and progress [0,1], returns interpolated value.
+ */
+export type InterpolatorFn<T> = (start: T, end: T, progress: number) => T;
+/**
+ * Default numeric interpolation (linear).
+ */
+export declare function lerpNumber(a: number, b: number, t: number): number;

package/dist/core/animations/keyframes/types.js

@@ -0,0 +1,6 @@
+/**
+ * Default numeric interpolation (linear).
+ */
+export function lerpNumber(a, b, t) {
+    return a + (b - a) * t;
+}

package/dist/core/animations/morph/MorphTo.d.ts

@@ -0,0 +1,22 @@
+import { TransformativeAnimation } from '../categories';
+import { VMobject } from '../../../mobjects/VMobject';
+/**
+ * Animation that morphs a VMobject from its current shape to a target shape.
+ * Uses BezierPath interpolation for smooth path transitions.
+ *
+ * This is a transformative animation - the source must already be in the scene.
+ * The target VMobject is used only as a shape template and is NOT added to the scene.
+ * Source paths are captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(circle);
+ * scene.play(new MorphTo(circle, square));  // circle morphs into square's shape
+ */
+export declare class MorphTo<T extends VMobject = VMobject> extends TransformativeAnimation<T> {
+    private sourcePaths;
+    private readonly targetPaths;
+    constructor(source: T, target: VMobject);
+    protected captureStartState(): void;
+    interpolate(progress: number): void;
+    private getEmptyPath;
+}

package/dist/core/animations/morph/MorphTo.js

@@ -0,0 +1,42 @@
+import { TransformativeAnimation } from '../categories';
+import { BezierPath } from '../../math/bezier/BezierPath';
+/**
+ * Animation that morphs a VMobject from its current shape to a target shape.
+ * Uses BezierPath interpolation for smooth path transitions.
+ *
+ * This is a transformative animation - the source must already be in the scene.
+ * The target VMobject is used only as a shape template and is NOT added to the scene.
+ * Source paths are captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(circle);
+ * scene.play(new MorphTo(circle, square));  // circle morphs into square's shape
+ */
+export class MorphTo extends TransformativeAnimation {
+    sourcePaths;
+    targetPaths;
+    constructor(source, target) {
+        super(source);
+        this.targetPaths = target.paths.map(p => p.clone());
+    }
+    captureStartState() {
+        this.sourcePaths = this.target.paths.map(p => p.clone());
+    }
+    interpolate(progress) {
+        this.ensureInitialized();
+        const maxPaths = Math.max(this.sourcePaths.length, this.targetPaths.length);
+        const newPaths = [];
+        for (let i = 0; i < maxPaths; i++) {
+            const sourcePath = this.sourcePaths[i] ?? this.getEmptyPath();
+            const targetPath = this.targetPaths[i] ?? this.getEmptyPath();
+            const interpolated = BezierPath.interpolate(sourcePath, targetPath, progress);
+            newPaths.push(interpolated);
+        }
+        this.target.paths = newPaths;
+    }
+    getEmptyPath() {
+        const path = new BezierPath();
+        path.moveTo(this.target.position);
+        return path;
+    }
+}

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

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

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

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

package/dist/core/animations/transform/MoveTo.d.ts

@@ -0,0 +1,24 @@
+import { TransformativeAnimation } from '../categories';
+import { Mobject } from '../../../mobjects/Mobject';
+import { Vector2 } from '../../math/Vector2/Vector2';
+/**
+ * Animation that moves a Mobject from its current position to a destination.
+ * Uses linear interpolation between start and end positions.
+ *
+ * This is a transformative animation - the target must already be in the scene.
+ * Start position is captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(circle);  // or use FadeIn first
+ * scene.play(new MoveTo(circle, 2, 0));  // Move to (2, 0)
+ */
+export declare class MoveTo<T extends Mobject = Mobject> extends TransformativeAnimation<T> {
+    private startPosition;
+    private readonly endPosition;
+    constructor(target: T, destination: Vector2);
+    constructor(target: T, x: number, y: number);
+    protected captureStartState(): void;
+    interpolate(progress: number): void;
+    /** Returns the target position of the move animation. */
+    getDestination(): Vector2;
+}

package/dist/core/animations/transform/MoveTo.js

@@ -0,0 +1,38 @@
+import { TransformativeAnimation } from '../categories';
+import { Vector2 } from '../../math/Vector2/Vector2';
+/**
+ * Animation that moves a Mobject from its current position to a destination.
+ * Uses linear interpolation between start and end positions.
+ *
+ * This is a transformative animation - the target must already be in the scene.
+ * Start position is captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(circle);  // or use FadeIn first
+ * scene.play(new MoveTo(circle, 2, 0));  // Move to (2, 0)
+ */
+export class MoveTo extends TransformativeAnimation {
+    startPosition;
+    endPosition;
+    constructor(target, xOrDestination, y) {
+        super(target);
+        if (xOrDestination instanceof Vector2) {
+            this.endPosition = xOrDestination;
+        }
+        else {
+            this.endPosition = new Vector2(xOrDestination, y ?? 0);
+        }
+    }
+    captureStartState() {
+        this.startPosition = this.target.position;
+    }
+    interpolate(progress) {
+        this.ensureInitialized();
+        const newPosition = this.startPosition.lerp(this.endPosition, progress);
+        this.target.pos(newPosition.x, newPosition.y);
+    }
+    /** Returns the target position of the move animation. */
+    getDestination() {
+        return this.endPosition;
+    }
+}

package/dist/core/animations/transform/Rotate.d.ts

@@ -0,0 +1,23 @@
+import { TransformativeAnimation } from '../categories';
+import type { Mobject } from '../../../mobjects/Mobject';
+/**
+ * Animation that rotates a Mobject by a specified angle.
+ * Uses linear interpolation between start and end rotation.
+ *
+ * This is a transformative animation - the target must already be in the scene.
+ * Start rotation is captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(square);
+ * scene.play(new Rotate(square, Math.PI / 4));  // Rotate 45 degrees
+ */
+export declare class Rotate<T extends Mobject = Mobject> extends TransformativeAnimation<T> {
+    private startRotation;
+    private endRotation;
+    private readonly angle;
+    constructor(target: T, angle: number);
+    protected captureStartState(): void;
+    interpolate(progress: number): void;
+    /** Returns the total rotation angle in radians. */
+    getAngle(): number;
+}

package/dist/core/animations/transform/Rotate.js

@@ -0,0 +1,34 @@
+import { TransformativeAnimation } from '../categories';
+/**
+ * Animation that rotates a Mobject by a specified angle.
+ * Uses linear interpolation between start and end rotation.
+ *
+ * This is a transformative animation - the target must already be in the scene.
+ * Start rotation is captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(square);
+ * scene.play(new Rotate(square, Math.PI / 4));  // Rotate 45 degrees
+ */
+export class Rotate extends TransformativeAnimation {
+    startRotation;
+    endRotation;
+    angle;
+    constructor(target, angle) {
+        super(target);
+        this.angle = angle;
+    }
+    captureStartState() {
+        this.startRotation = this.target.rotation;
+        this.endRotation = this.startRotation + this.angle;
+    }
+    interpolate(progress) {
+        this.ensureInitialized();
+        const newRotation = this.startRotation + (this.endRotation - this.startRotation) * progress;
+        this.target.setRotation(newRotation);
+    }
+    /** Returns the total rotation angle in radians. */
+    getAngle() {
+        return this.angle;
+    }
+}

package/dist/core/animations/transform/Scale.d.ts

@@ -0,0 +1,23 @@
+import { TransformativeAnimation } from '../categories';
+import { Mobject } from '../../../mobjects/Mobject';
+/**
+ * Animation that scales a Mobject to a target scale factor.
+ * Uses linear interpolation between start and end scale.
+ *
+ * This is a transformative animation - the target must already be in the scene.
+ * Start scale is captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(circle);
+ * scene.play(new Scale(circle, 2));  // Scale to 2x
+ */
+export declare class Scale<T extends Mobject = Mobject> extends TransformativeAnimation<T> {
+    private startScale;
+    private readonly endScale;
+    constructor(target: T, factor: number);
+    constructor(target: T, factorX: number, factorY: number);
+    protected captureStartState(): void;
+    interpolate(progress: number): void;
+    /** Returns the scale factor. */
+    getFactor(): number;
+}

package/dist/core/animations/transform/Scale.js

@@ -0,0 +1,35 @@
+import { TransformativeAnimation } from '../categories';
+import { Vector2 } from '../../math/Vector2/Vector2';
+/**
+ * Animation that scales a Mobject to a target scale factor.
+ * Uses linear interpolation between start and end scale.
+ *
+ * This is a transformative animation - the target must already be in the scene.
+ * Start scale is captured lazily when animation becomes active.
+ *
+ * @example
+ * scene.add(circle);
+ * scene.play(new Scale(circle, 2));  // Scale to 2x
+ */
+export class Scale extends TransformativeAnimation {
+    startScale;
+    endScale;
+    constructor(target, factorX, factorY) {
+        super(target);
+        const endX = factorX;
+        const endY = factorY ?? factorX;
+        this.endScale = new Vector2(endX, endY);
+    }
+    captureStartState() {
+        this.startScale = this.target.scale;
+    }
+    interpolate(progress) {
+        this.ensureInitialized();
+        const newScale = this.startScale.lerp(this.endScale, progress);
+        this.target.setScale(newScale.x, newScale.y);
+    }
+    /** Returns the scale factor. */
+    getFactor() {
+        return this.endScale.x;
+    }
+}

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

@@ -0,0 +1,3 @@
+export { MoveTo } from './MoveTo';
+export { Rotate } from './Rotate';
+export { Scale } from './Scale';

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

@@ -0,0 +1,3 @@
+export { MoveTo } from './MoveTo';
+export { Rotate } from './Rotate';
+export { Scale } from './Scale';

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

@@ -0,0 +1,52 @@
+import type { EasingFunction } from './easing';
+import type { Animation } from './Animation';
+import type { Mobject } from '../../mobjects/Mobject';
+/**
+ * Configuration options for animations.
+ */
+export interface AnimationConfig {
+    /** Duration of the animation in seconds. Default: 1 */
+    readonly durationSeconds: number;
+    /** Easing function to apply. Default: smooth */
+    readonly easing: EasingFunction;
+    /** Delay before animation starts in seconds. Default: 0 */
+    readonly delaySeconds: number;
+}
+/**
+ * Animation lifecycle category determines how Scene.play() handles the target.
+ * - 'introductory': Auto-registers target with scene (FadeIn, Create, Draw, Write)
+ * - 'transformative': Requires target to already be in scene (MoveTo, Rotate, Scale)
+ * - 'exit': Requires target in scene, may auto-remove after (FadeOut)
+ */
+export type AnimationLifecycle = 'introductory' | 'transformative' | 'exit';
+/**
+ * Configuration for a queued animation in the fluent API.
+ */
+export interface FluentConfig {
+    durationSeconds: number;
+    easing?: EasingFunction;
+    delaySeconds?: number;
+}
+/**
+ * Factory function that creates an Animation for a given target.
+ */
+export type AnimationFactory = (target: Mobject) => Animation<Mobject>;
+/**
+ * A queued animation descriptor storing the factory and configuration.
+ */
+export interface QueuedAnimation {
+    factory: AnimationFactory;
+    config: FluentConfig;
+}
+/**
+ * A pre-built animation that's already configured (e.g., from parallel()).
+ */
+export interface QueuedPrebuilt {
+    animation: Animation<Mobject>;
+}
+/** Union type for queue entries */
+export type QueueEntry = QueuedAnimation | QueuedPrebuilt;
+/** Type guard to check if entry is a pre-built animation */
+export declare function isPrebuilt(entry: QueueEntry): entry is QueuedPrebuilt;
+/** Default animation duration in seconds. */
+export declare const DEFAULT_DURATION = 1;

package/dist/core/animations/types.js

@@ -0,0 +1,6 @@
+/** Type guard to check if entry is a pre-built animation */
+export function isPrebuilt(entry) {
+    return 'animation' in entry;
+}
+/** Default animation duration in seconds. */
+export const DEFAULT_DURATION = 1;

package/dist/core/camera/Camera.d.ts

@@ -0,0 +1,87 @@
+import { Vector2 } from '../math/Vector2/Vector2';
+import { Matrix3x3 } from '../math/matrix/Matrix3x3';
+import { CameraFrame } from './CameraFrame';
+import { type CameraConfig } from './types';
+/**
+ * Camera manages the view into the scene.
+ * Uses CameraFrame (a Mobject) to store transform state, enabling camera animations.
+ *
+ * The Camera provides both instant manipulation methods (panTo, zoomTo) and
+ * access to the CameraFrame for fluent animation APIs.
+ *
+ * @example
+ * // Instant camera manipulation
+ * camera.zoomTo(2);
+ * camera.panTo(new Vector2(5, 3));
+ *
+ * @example
+ * // Animated camera movement via frame
+ * this.play(this.frame.zoomIn(2).duration(1));
+ * this.play(this.frame.centerOn(circle).duration(0.5));
+ */
+export declare class Camera {
+    private readonly config;
+    /** The CameraFrame that stores the camera's transform state. Use this for animations. */
+    readonly frame: CameraFrame;
+    /**
+     * Creates a new Camera with the specified viewport dimensions.
+     *
+     * @param config - Configuration options
+     * @param config.pixelWidth - Width of the viewport in pixels (default: 1920)
+     * @param config.pixelHeight - Height of the viewport in pixels (default: 1080)
+     */
+    constructor(config?: CameraConfig);
+    get frameHeight(): number;
+    get frameWidth(): number;
+    get frameYRadius(): number;
+    get frameXRadius(): number;
+    get pixelWidth(): number;
+    get pixelHeight(): number;
+    get position(): Vector2;
+    get zoom(): number;
+    get rotation(): number;
+    pan(delta: Vector2): this;
+    panTo(position: Vector2): this;
+    zoomTo(level: number): this;
+    rotateTo(angle: number): this;
+    getViewMatrix(): Matrix3x3;
+    /**
+     * Transforms a world-space position to screen-space (pixel) coordinates.
+     *
+     * Screen coordinates have origin at top-left, with x increasing right
+     * and y increasing downward.
+     *
+     * @param pos - Position in world coordinates
+     * @returns Position in screen coordinates (pixels)
+     *
+     * @example
+     * const screenPos = camera.worldToScreen(circle.position);
+     * console.log(`Circle is at pixel (${screenPos.x}, ${screenPos.y})`);
+     */
+    worldToScreen(pos: Vector2): Vector2;
+    /**
+     * Transforms a screen-space (pixel) position to world coordinates.
+     * This is the inverse of worldToScreen.
+     *
+     * @param pos - Position in screen coordinates (pixels, origin at top-left)
+     * @returns Position in world coordinates
+     *
+     * @example
+     * // Convert a mouse click position to world coordinates
+     * const worldPos = camera.screenToWorld(new Vector2(mouseX, mouseY));
+     */
+    screenToWorld(pos: Vector2): Vector2;
+    /**
+     * Checks if a world-space position is currently visible within the camera frame.
+     *
+     * @param pos - Position in world coordinates to check
+     * @returns True if the position is within the visible frame bounds
+     *
+     * @example
+     * if (camera.isInView(object.position)) {
+     *   console.log('Object is visible');
+     * }
+     */
+    isInView(pos: Vector2): boolean;
+    reset(): this;
+}