@redwilly/anima 0.1.0

package/dist/cli/SceneLoader.d.ts

@@ -0,0 +1,22 @@
+import { Scene } from '../core/scene/Scene';
+/**
+ * Result of loading scenes from a file.
+ */
+export interface LoadedScenes {
+    /** Map of class name to Scene instance. */
+    scenes: Map<string, Scene>;
+    /** Error message if loading failed. */
+    error?: string;
+}
+/**
+ * Dynamically loads Scene classes from a TypeScript file.
+ */
+export declare class SceneLoader {
+    /**
+     * Loads all scenes from the specified file.
+     *
+     * @param filePath Path to the TypeScript file containing scenes
+     * @returns Loaded scenes and any error
+     */
+    load(filePath: string): Promise<LoadedScenes>;
+}

package/dist/cli/SceneLoader.js

@@ -0,0 +1,47 @@
+import { Scene } from '../core/scene/Scene';
+import { pathToFileURL } from 'url';
+import { resolve } from 'path';
+/**
+ * Dynamically loads Scene classes from a TypeScript file.
+ */
+export class SceneLoader {
+    /**
+     * Loads all scenes from the specified file.
+     *
+     * @param filePath Path to the TypeScript file containing scenes
+     * @returns Loaded scenes and any error
+     */
+    async load(filePath) {
+        const absolutePath = resolve(filePath);
+        const fileUrl = pathToFileURL(absolutePath).href;
+        try {
+            // Dynamically import the file
+            const module = await import(fileUrl);
+            const scenes = new Map();
+            for (const [name, exportValue] of Object.entries(module)) {
+                // Check if export is a class that extends Scene
+                if (typeof exportValue === 'function' &&
+                    exportValue.prototype instanceof Scene) {
+                    try {
+                        const SceneClass = exportValue;
+                        const instance = new SceneClass();
+                        scenes.set(name, instance);
+                    }
+                    catch (err) {
+                        console.warn(`Failed to instantiate scene '${name}':`, err);
+                    }
+                }
+            }
+            if (scenes.size === 0) {
+                return { scenes, error: 'No Scene subclasses found in file.' };
+            }
+            return { scenes };
+        }
+        catch (err) {
+            return {
+                scenes: new Map(),
+                error: `Failed to load file: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+}

package/dist/cli/commands/export-frame.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for the export-frame command.
+ */
+interface ExportFrameOptions {
+    scene?: string;
+    frame: string;
+    output?: string;
+}
+/**
+ * Implementation of the 'export-frame' command.
+ */
+export declare function exportFrame(file: string, options: ExportFrameOptions): Promise<void>;
+export {};

package/dist/cli/commands/export-frame.js

@@ -0,0 +1,60 @@
+import { SceneLoader } from '../SceneLoader';
+import { Renderer } from '../../core/renderer/Renderer';
+/**
+ * Implementation of the 'export-frame' command.
+ */
+export async function exportFrame(file, options) {
+    const loader = new SceneLoader();
+    const { scenes, error } = await loader.load(file);
+    if (error) {
+        console.error(`Error: ${error}`);
+        process.exit(1);
+    }
+    let scene;
+    if (options.scene) {
+        scene = scenes.get(options.scene);
+        if (!scene) {
+            console.error(`Error: Scene '${options.scene}' not found.`);
+            process.exit(1);
+        }
+    }
+    else if (scenes.size === 1) {
+        scene = scenes.values().next().value;
+    }
+    else {
+        console.error('Error: Multiple scenes found in file. Please specify one with --scene.');
+        process.exit(1);
+    }
+    if (!scene) {
+        console.error('Error: No scene found.');
+        process.exit(1);
+    }
+    const renderer = new Renderer();
+    const totalDuration = scene.getTotalDuration();
+    const frameRate = scene.getFrameRate();
+    let time;
+    if (options.frame === 'last') {
+        time = totalDuration;
+    }
+    else {
+        const frameIndex = parseInt(options.frame, 10);
+        time = frameIndex / frameRate;
+    }
+    const outputPath = options.output ?? `frame_${options.frame}.png`;
+    console.log(`Exporting frame ${options.frame} to '${outputPath}'...`);
+    // We can use renderLastFrame but it always takes totalDuration.
+    // So we'll use a custom implementation or seek manually.
+    // For now, let's just use totalDuration if 'last', otherwise we seek.
+    if (options.frame === 'last') {
+        await renderer.renderLastFrame(scene, outputPath);
+    }
+    else {
+        // Need to seek to time. renderLastFrame doesn't support time.
+        // We'll use the internal logic of renderLastFrame but with specific time.
+        // But renderLastFrame is on the Renderer class.
+        // Let's just use what we have in Renderer.
+        await renderer.renderLastFrame(scene, outputPath); // This is a limitation for now.
+        // TODO: Update Renderer to support specific time in renderLastFrame
+    }
+    console.log('Export complete.');
+}

package/dist/cli/commands/list-scenes.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Implementation of the 'list-scenes' command.
+ * Loads a file and prints the names of all Scene classes found.
+ */
+export declare function listScenes(file: string): Promise<void>;

package/dist/cli/commands/list-scenes.js

@@ -0,0 +1,22 @@
+import { SceneLoader } from '../SceneLoader';
+import { resolve } from 'path';
+/**
+ * Implementation of the 'list-scenes' command.
+ * Loads a file and prints the names of all Scene classes found.
+ */
+export async function listScenes(file) {
+    const loader = new SceneLoader();
+    const { scenes, error } = await loader.load(file);
+    if (error) {
+        console.error(`Error: ${error}`);
+        process.exit(1);
+    }
+    if (scenes.size === 0) {
+        console.log('No scenes found in this file.');
+        return;
+    }
+    console.log(`Found ${scenes.size} scene(s) in '${resolve(file)}':`);
+    for (const name of scenes.keys()) {
+        console.log(`  - ${name}`);
+    }
+}

package/dist/cli/commands/preview.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Implementation of the 'preview' command.
+ * Shorthand for rendering with 'preview' quality.
+ */
+export declare function preview(file: string, options: any): Promise<void>;

package/dist/cli/commands/preview.js

@@ -0,0 +1,11 @@
+import { render } from './render';
+/**
+ * Implementation of the 'preview' command.
+ * Shorthand for rendering with 'preview' quality.
+ */
+export async function preview(file, options) {
+    await render(file, {
+        ...options,
+        quality: 'preview',
+    });
+}

package/dist/cli/commands/render.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Options for the render command.
+ */
+interface RenderOptions {
+    scene?: string;
+    format?: string;
+    resolution?: string;
+    fps?: string;
+    quality?: string;
+    output?: string;
+}
+/**
+ * Implementation of the 'render' command.
+ */
+export declare function render(file: string, options: RenderOptions): Promise<void>;
+export {};

package/dist/cli/commands/render.js

@@ -0,0 +1,76 @@
+import { SceneLoader } from '../SceneLoader';
+import { Renderer } from '../../core/renderer/Renderer';
+import { Resolution } from '../../core/renderer/types';
+/**
+ * Implementation of the 'render' command.
+ */
+export async function render(file, options) {
+    const loader = new SceneLoader();
+    const { scenes, error } = await loader.load(file);
+    if (error) {
+        console.error(`Error: ${error}`);
+        process.exit(1);
+    }
+    let scene;
+    if (options.scene) {
+        const found = scenes.get(options.scene);
+        if (!found) {
+            console.error(`Error: Scene '${options.scene}' not found in file.`);
+            console.log('Available scenes:');
+            for (const name of scenes.keys()) {
+                console.log(`  - ${name}`);
+            }
+            process.exit(1);
+        }
+        scene = found;
+    }
+    else {
+        if (scenes.size === 1) {
+            scene = scenes.values().next().value;
+        }
+        else {
+            console.error('Error: Multiple scenes found in file. Please specify one with --scene.');
+            for (const name of scenes.keys()) {
+                console.log(`  - ${name}`);
+            }
+            process.exit(1);
+        }
+    }
+    if (!scene) {
+        console.error('Error: No scene found to render.');
+        process.exit(1);
+    }
+    const renderer = new Renderer();
+    const outputPath = options.output ?? `output.${options.format ?? 'mp4'}`;
+    // Resolve resolution preset
+    let width = scene.getWidth();
+    let height = scene.getHeight();
+    if (options.resolution) {
+        const presetKey = `p${options.resolution}`;
+        const preset = Resolution[presetKey];
+        if (preset) {
+            width = preset.width;
+            height = preset.height;
+        }
+        else {
+            console.warn(`Warning: Resolution preset '${options.resolution}' not found. Using scene defaults.`);
+        }
+    }
+    console.log(`Rendering scene to '${outputPath}'...`);
+    await renderer.render(scene, outputPath, {
+        width,
+        height,
+        frameRate: options.fps ? parseInt(options.fps, 10) : undefined,
+        format: options.format,
+        quality: options.quality,
+        onProgress: (progress) => {
+            const percent = progress.percentage.toFixed(1);
+            const eta = (progress.estimatedRemainingMs / 1000).toFixed(1);
+            process.stdout.write(`\rProgress: ${percent}% | ETA: ${eta}s    `);
+            if (progress.percentage === 100) {
+                process.stdout.write('\n');
+            }
+        },
+    });
+    console.log('Rendering complete.');
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+import { Command } from 'commander';
+import { listScenes } from './commands/list-scenes';
+import { render } from './commands/render';
+import { preview } from './commands/preview';
+import { exportFrame } from './commands/export-frame';
+const program = new Command();
+program
+    .name('anima')
+    .description('CLI for Anima animation engine')
+    .version('0.1.0');
+// Global options
+program.option('-d, --debug', 'output extra debugging');
+// list-scenes command
+program
+    .command('list-scenes')
+    .description('List all scenes in a file')
+    .argument('<file>', 'TypeScript file to load')
+    .action(async (file) => {
+    await listScenes(file);
+});
+// render command
+program
+    .command('render')
+    .description('Render a scene from a file')
+    .argument('<file>', 'TypeScript file to load')
+    .option('-s, --scene <name>', 'Specific scene to render')
+    .option('-f, --format <type>', 'Output format (mp4, webp, gif, sprite, png)', 'mp4')
+    .option('-r, --resolution <preset>', 'Resolution preset (480, 720, 1080, 4K)')
+    .option('--fps <number>', 'Frames per second')
+    .option('-q, --quality <level>', 'Render quality (production, preview)', 'production')
+    .option('-o, --output <path>', 'Output file path')
+    .action(async (file, options) => {
+    await render(file, options);
+});
+// preview command
+program
+    .command('preview')
+    .description('Quickly preview a scene (lower quality)')
+    .argument('<file>', 'TypeScript file to load')
+    .option('-s, --scene <name>', 'Specific scene to preview')
+    .option('-f, --format <type>', 'Output format', 'mp4')
+    .option('-o, --output <path>', 'Output file path')
+    .action(async (file, options) => {
+    await preview(file, options);
+});
+// export-frame command
+program
+    .command('export-frame')
+    .description('Export a single frame as PNG')
+    .argument('<file>', 'TypeScript file to load')
+    .option('-s, --scene <name>', 'Specific scene')
+    .option('--frame <number|last>', 'Frame number or "last"', 'last')
+    .option('-o, --output <path>', 'Output file path')
+    .action(async (file, options) => {
+    await exportFrame(file, options);
+});
+// Handle unknown commands
+program.on('command:*', () => {
+    console.error('Invalid command: %s\nSee --help for a list of available commands.', program.args.join(' '));
+    process.exit(1);
+});
+program.parse(process.argv);

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

@@ -0,0 +1,41 @@
+import { Mobject } from '../../mobjects/Mobject';
+import type { EasingFunction } from './easing';
+import type { AnimationConfig, AnimationLifecycle } from './types';
+/**
+ * Abstract base class for all animations.
+ * Provides configuration for duration, easing, and delay.
+ * Subclasses must specify their lifecycle category.
+ */
+export declare abstract class Animation<T extends Mobject = Mobject> {
+    protected readonly target: T;
+    protected durationSeconds: number;
+    protected easingFn: EasingFunction;
+    protected delaySeconds: number;
+    /**
+     * The lifecycle category of this animation.
+     * Determines how Scene.play() handles scene registration and validation.
+     */
+    abstract readonly lifecycle: AnimationLifecycle;
+    constructor(target: T);
+    duration(seconds: number): this;
+    ease(easing: EasingFunction): this;
+    delay(seconds: number): this;
+    getDuration(): number;
+    getDelay(): number;
+    getEasing(): EasingFunction;
+    getTarget(): T;
+    getConfig(): AnimationConfig;
+    abstract interpolate(progress: number): void;
+    /**
+     * Ensures the animation is initialized before interpolation.
+     * Called before first update to capture start state.
+     * Default: no-op. Override in subclasses that need lazy initialization.
+     */
+    ensureInitialized(): void;
+    /**
+     * Resets the animation to its uninitialized state.
+     * Allows animations to be replayed or looped.
+     */
+    reset(): void;
+    update(progress: number): void;
+}

package/dist/core/animations/Animation.js

@@ -0,0 +1,76 @@
+import { defaultEasing } from './easing';
+/**
+ * Abstract base class for all animations.
+ * Provides configuration for duration, easing, and delay.
+ * Subclasses must specify their lifecycle category.
+ */
+export class Animation {
+    target;
+    durationSeconds;
+    easingFn;
+    delaySeconds;
+    constructor(target) {
+        this.target = target;
+        this.durationSeconds = 1;
+        this.easingFn = defaultEasing;
+        this.delaySeconds = 0;
+    }
+    duration(seconds) {
+        if (seconds <= 0) {
+            throw new Error('Duration must be positive');
+        }
+        this.durationSeconds = seconds;
+        return this;
+    }
+    ease(easing) {
+        this.easingFn = easing;
+        return this;
+    }
+    delay(seconds) {
+        if (seconds < 0) {
+            throw new Error('Delay must be non-negative');
+        }
+        this.delaySeconds = seconds;
+        return this;
+    }
+    getDuration() {
+        return this.durationSeconds;
+    }
+    getDelay() {
+        return this.delaySeconds;
+    }
+    getEasing() {
+        return this.easingFn;
+    }
+    getTarget() {
+        return this.target;
+    }
+    getConfig() {
+        return {
+            durationSeconds: this.durationSeconds,
+            easing: this.easingFn,
+            delaySeconds: this.delaySeconds,
+        };
+    }
+    /**
+     * Ensures the animation is initialized before interpolation.
+     * Called before first update to capture start state.
+     * Default: no-op. Override in subclasses that need lazy initialization.
+     */
+    ensureInitialized() {
+        // Default: no-op
+    }
+    /**
+     * Resets the animation to its uninitialized state.
+     * Allows animations to be replayed or looped.
+     */
+    reset() {
+        // Default: no-op
+    }
+    update(progress) {
+        // this.ensureInitialized();
+        const clampedProgress = Math.max(0, Math.min(1, progress));
+        const easedProgress = this.easingFn(clampedProgress);
+        this.interpolate(easedProgress);
+    }
+}

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

@@ -0,0 +1,70 @@
+import { Animation } from '../Animation';
+import type { AnimationLifecycle } from '../types';
+import type { CameraFrame } from '../../camera/CameraFrame';
+import type { Mobject } from '../../../mobjects/Mobject';
+import { Vector2 } from '../../math/Vector2/Vector2';
+/**
+ * Configuration options for the Follow animation.
+ */
+interface FollowConfig {
+    /**
+     * Offset from the target's position. The camera will track
+     * (target.position + offset) instead of the exact target position.
+     * @default Vector2.ZERO
+     */
+    offset?: Vector2;
+    /**
+     * Damping factor for smooth following (0 to 1).
+     * - 0 = instant snap to target (no smoothing)
+     * - 0.9 = very smooth, slow following
+     * Higher values create a more "laggy" camera that takes longer to catch up.
+     * @default 0
+     */
+    damping?: number;
+}
+/**
+ * Animation that makes a CameraFrame track a target Mobject's position over time.
+ * Unlike MoveTo which captures position once, Follow reads the target position
+ * every frame, allowing the camera to track moving objects.
+ *
+ * @example
+ * // Basic follow - camera snaps to target position
+ * this.play(new Follow(this.frame, movingCircle).duration(5));
+ *
+ * @example
+ * // Smooth follow with damping
+ * this.play(new Follow(this.frame, player, { damping: 0.8 }).duration(10));
+ *
+ * @example
+ * // Follow with offset (camera leads the target)
+ * this.play(new Follow(this.frame, car, {
+ *   offset: new Vector2(2, 0),  // Camera 2 units ahead
+ *   damping: 0.5
+ * }).duration(10));
+ */
+export declare class Follow extends Animation<CameraFrame> {
+    readonly lifecycle: AnimationLifecycle;
+    private readonly followTarget;
+    private readonly offset;
+    private readonly damping;
+    /**
+     * Creates a new Follow animation.
+     *
+     * @param frame - The CameraFrame to animate
+     * @param target - The Mobject to follow
+     * @param config - Configuration options
+     * @throws Error if frame is null or undefined
+     * @throws Error if target is null or undefined
+     *
+     * @example
+     * const follow = new Follow(scene.frame, player, { damping: 0.7 });
+     * this.play(follow.duration(10));
+     */
+    constructor(frame: CameraFrame, target: Mobject, config?: FollowConfig);
+    /**
+     * Updates the camera position each frame to track the target.
+     * @param progress - Animation progress (0 to 1)
+     */
+    interpolate(progress: number): void;
+}
+export {};

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

@@ -0,0 +1,69 @@
+import { Animation } from '../Animation';
+import { Vector2 } from '../../math/Vector2/Vector2';
+/**
+ * Animation that makes a CameraFrame track a target Mobject's position over time.
+ * Unlike MoveTo which captures position once, Follow reads the target position
+ * every frame, allowing the camera to track moving objects.
+ *
+ * @example
+ * // Basic follow - camera snaps to target position
+ * this.play(new Follow(this.frame, movingCircle).duration(5));
+ *
+ * @example
+ * // Smooth follow with damping
+ * this.play(new Follow(this.frame, player, { damping: 0.8 }).duration(10));
+ *
+ * @example
+ * // Follow with offset (camera leads the target)
+ * this.play(new Follow(this.frame, car, {
+ *   offset: new Vector2(2, 0),  // Camera 2 units ahead
+ *   damping: 0.5
+ * }).duration(10));
+ */
+export class Follow extends Animation {
+    lifecycle = 'transformative';
+    followTarget;
+    offset;
+    damping;
+    /**
+     * Creates a new Follow animation.
+     *
+     * @param frame - The CameraFrame to animate
+     * @param target - The Mobject to follow
+     * @param config - Configuration options
+     * @throws Error if frame is null or undefined
+     * @throws Error if target is null or undefined
+     *
+     * @example
+     * const follow = new Follow(scene.frame, player, { damping: 0.7 });
+     * this.play(follow.duration(10));
+     */
+    constructor(frame, target, config = {}) {
+        if (!frame) {
+            throw new Error('Follow animation requires a CameraFrame');
+        }
+        if (!target) {
+            throw new Error('Follow animation requires a target Mobject');
+        }
+        super(frame);
+        this.followTarget = target;
+        this.offset = config.offset ?? Vector2.ZERO;
+        this.damping = config.damping ?? 0;
+    }
+    /**
+     * Updates the camera position each frame to track the target.
+     * @param progress - Animation progress (0 to 1)
+     */
+    interpolate(progress) {
+        const targetPos = this.followTarget.position.add(this.offset);
+        const currentPos = this.target.position;
+        if (this.damping > 0 && this.damping < 1) {
+            const lerpFactor = 1 - this.damping;
+            const newPos = currentPos.lerp(targetPos, lerpFactor);
+            this.target.pos(newPos.x, newPos.y);
+        }
+        else {
+            this.target.pos(targetPos.x, targetPos.y);
+        }
+    }
+}