@redwilly/anima 0.1.2 → 0.1.23

package/dist/cli/index.js

@@ -65,6 +65,7 @@ async function listScenes(file) {
 
 // src/cli/commands/render.ts
 import { Renderer, Resolution } from "@redwilly/anima";
+import { join, dirname } from "path";
 async function render(file, options) {
   const loader = new SceneLoader();
   const { scenes, error } = await loader.load(file);
@@ -73,6 +74,7 @@ async function render(file, options) {
     process.exit(1);
   }
   let scene;
+  let sceneName;
   if (options.scene) {
     const found = scenes.get(options.scene);
     if (!found) {
@@ -84,9 +86,12 @@ async function render(file, options) {
       process.exit(1);
     }
     scene = found;
+    sceneName = options.scene;
   } else {
     if (scenes.size === 1) {
-      scene = scenes.values().next().value;
+      const entry = scenes.entries().next().value;
+      sceneName = entry[0];
+      scene = entry[1];
     } else {
       console.error("Error: Multiple scenes found in file. Please specify one with --scene.");
       for (const name of scenes.keys()) {
@@ -99,8 +104,10 @@ async function render(file, options) {
     console.error("Error: No scene found to render.");
     process.exit(1);
   }
+  const format = options.format ?? "mp4";
+  const outputPath = options.output ?? join("media", `${sceneName}.${format}`);
+  const cacheDir = join(dirname(outputPath), ".anima-cache");
   const renderer = new Renderer();
-  const outputPath = options.output ?? `output.${options.format ?? "mp4"}`;
   let width = scene.getWidth();
   let height = scene.getHeight();
   if (options.resolution) {
@@ -113,13 +120,14 @@ async function render(file, options) {
       console.warn(`Warning: Resolution preset '${options.resolution}' not found. Using scene defaults.`);
     }
   }
-  console.log(`Rendering scene to '${outputPath}'...`);
+  console.log(`Rendering scene '${sceneName}' to '${outputPath}'...`);
   await renderer.render(scene, outputPath, {
     width,
     height,
     frameRate: options.fps ? parseInt(options.fps, 10) : void 0,
-    format: options.format,
+    format,
     quality: options.quality,
+    cacheDir,
     onProgress: (progress) => {
       const percent = progress.percentage.toFixed(1);
       const eta = (progress.estimatedRemainingMs / 1e3).toFixed(1);

package/dist/index.d.ts

@@ -275,6 +275,7 @@ declare class AnimationQueue {
     enqueueAnimation(animation: Animation<Mobject>): void;
     setLastDuration(seconds: number): void;
     setLastEasing(easing: EasingFunction): void;
+    setLastDelay(seconds: number): void;
     isEmpty(): boolean;
     popLastAnimation(): Animation<Mobject> | null;
     toAnimation(): Animation<Mobject>;
@@ -343,6 +344,7 @@ declare class Mobject {
     };
     duration(seconds: number): this;
     ease(easing: EasingFunction): this;
+    delay(seconds: number): this;
     toAnimation(): Animation<Mobject>;
     getQueuedDuration(): number;
     hasQueuedAnimations(): boolean;
@@ -356,6 +358,11 @@ declare class Mobject {
      * ).fadeOut(1);
      */
     parallel(...items: (Animation<Mobject> | Mobject)[]): this;
+    /**
+     * Computes a CRC32 hash of this mobject's full state.
+     * Used by the segment cache to detect changes.
+     */
+    computeHash(): number;
 }
 
 /**
@@ -414,6 +421,12 @@ declare abstract class Animation<T extends Mobject = Mobject> {
      */
     reset(): void;
     update(progress: number): void;
+    /**
+     * Hashes the animation type, config, and target state.
+     * Subclass-specific behavior is captured through the target's hash,
+     * since animations mutate the target.
+     */
+    computeHash(): number;
 }
 
 /**
@@ -914,6 +927,10 @@ declare class Camera {
      */
     isInView(pos: Vector2): boolean;
     reset(): this;
+    /**
+     * Hashes camera config and the CameraFrame's full transform state.
+     */
+    computeHash(): number;
 }
 
 /**
@@ -930,6 +947,26 @@ interface SceneConfig {
     readonly frameRate?: number;
 }
 
+/**
+ * A Segment represents one independent rendering unit,
+ * corresponding to a single play() or wait() call.
+ *
+ * Its hash is a holistic CRC32 composition of the camera state,
+ * all current mobjects, and the animations for this segment.
+ */
+interface Segment {
+    /** Zero-based index in the scene's segment list. */
+    readonly index: number;
+    /** Start time in seconds. */
+    readonly startTime: number;
+    /** End time in seconds. */
+    readonly endTime: number;
+    /** Animations scheduled in this segment (empty for wait segments). */
+    readonly animations: readonly Animation[];
+    /** CRC32 hash of camera + mobjects + animations at this point. */
+    readonly hash: number;
+}
+
 /**
  * Scene is the core container that manages Mobjects and coordinates animations.
  * It provides both a simple API for playing animations and access to the
@@ -940,6 +977,7 @@ declare class Scene {
     private readonly mobjects;
     private readonly timeline;
     private readonly _camera;
+    private readonly segmentList;
     private playheadTime;
     constructor(config?: SceneConfig);
     get camera(): Camera;
@@ -1017,16 +1055,36 @@ declare class Scene {
      * Camera calculates Manim-compatible frame dimensions from pixel resolution.
      */
     getCamera(): Camera;
+    /**
+     * Get the list of segments emitted by play() and wait() calls.
+     * Used by the Renderer for cache-aware segmented rendering.
+     */
+    getSegments(): readonly Segment[];
     /**
      * Validates and registers animation targets based on lifecycle.
      * Handles composition animations (Sequence, Parallel) by processing children.
      */
     private validateAndRegisterAnimation;
+    /**
+     * Checks if a Mobject is in the scene.
+     * An object is "in scene" if:
+     * - It's directly registered in this.mobjects, OR
+     * - Any ancestor in its parent chain is registered
+     *
+     * This respects the scene graph hierarchy - children of registered
+     * VGroups are implicitly in scene via their parent.
+     */
+    isInScene(mobject: Mobject): boolean;
     /**
      * Gets children of composition animations (Sequence, Parallel).
      * Returns empty array for non-composition animations.
      */
     private getAnimationChildren;
+    /**
+     * Computes a holistic CRC32 hash for a segment.
+     * Includes camera state, all current mobjects, animations, and timing.
+     */
+    private computeSegmentHash;
 }
 
 type PathCommandType = 'Move' | 'Line' | 'Quadratic' | 'Cubic' | 'Close';
@@ -1174,6 +1232,11 @@ declare class VMobject extends Mobject {
     draw(durationSeconds?: number): this & {
         toAnimation(): Animation<Mobject>;
     };
+    /**
+     * Extends parent hash with VMobject-specific state:
+     * stroke/fill colors, widths, opacity, and path geometry.
+     */
+    computeHash(): number;
 }
 
 type CornerPosition = 'TOP_LEFT' | 'TOP_RIGHT' | 'BOTTOM_LEFT' | 'BOTTOM_RIGHT';
@@ -1227,6 +1290,11 @@ declare class VGroup extends VMobject {
     toCorner(corner: CornerPosition, buff?: number): this;
     arrange(direction?: Direction, buff?: number, shouldCenter?: boolean): this;
     alignTo(target: VMobject, edge: Edge): this;
+    /**
+     * Recursively hashes this VGroup and all children.
+     * Any child state change invalidates segments containing this group.
+     */
+    computeHash(): number;
 }
 
 declare class Arc extends VMobject {
@@ -1248,13 +1316,9 @@ declare class Line extends VMobject {
     private generatePath;
 }
 
-declare class Point extends Circle {
-    constructor(location?: Vector2);
-}
-
 declare class Polygon extends VMobject {
     readonly vertices: Vector2[];
-    constructor(vertices: Vector2[]);
+    constructor(...points: Array<[number, number]>);
     private generatePath;
 }
 
@@ -1281,28 +1345,26 @@ declare class Glyph extends VMobject {
     constructor(fontkitGlyph: Glyph$1, character: string, scale: number, offsetX: number, offsetY: number);
 }
 
-/**
- * Options for configuring Text appearance.
- */
-interface TextStyle {
-    fontSize: number;
-    color: Color;
-}
-
 /**
  * A VGroup of vectorized glyphs created from a text string using fontkit.
  * Each character becomes a Glyph VMobject that can be individually animated.
+ *
+ * Uses VMobject's fill/stroke as the source of truth (same as geometry).
+ * Default: white fill, white stroke width 2.
  */
 declare class Text extends VGroup {
     readonly text: string;
-    private style;
+    private fontSize;
     private fontPath;
-    constructor(text: string, fontPath: string, options?: Partial<TextStyle>);
+    constructor(text: string, fontPath?: string, options?: {
+        fontSize?: number;
+    });
     private buildGlyphs;
-    private getCharacterForGlyph;
-    private applyStyle;
-    setStyle(options: Partial<TextStyle>): this;
-    getStyle(): TextStyle;
+    /** Propagates this Text's fill/stroke to all Glyph children. */
+    private propagate;
+    stroke(color: Color, width?: number): this;
+    fill(color: Color, opacity?: number): this;
+    getFontSize(): number;
     getGlyph(index: number): Glyph | undefined;
 }
 
@@ -1578,66 +1640,61 @@ declare class MorphTo<T extends VMobject = VMobject> extends TransformativeAnima
 }
 
 /**
- * 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.
+ * Animation that first draws the stroke progressively, then fades in the fill.
+ * - First 50%: stroke draws progressively
+ * - Second 50%: fill fades in
  *
- * Supports VGroup (including Text): animates each child's paths progressively.
+ * - Single VMobject: stroke then fill
+ * - VGroup: all children animate together
+ * - Text (VGroup of Glyphs): Glyphs animate sequentially for handwriting effect
  *
  * 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
  */
 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 originalStrokeColor;
+    private readonly originalStrokeWidth;
+    private readonly originalFillColor;
+    private readonly originalFillOpacity;
     private readonly childStates;
+    /** Glyph states for Text children, keyed by the Text VMobject reference. */
+    private readonly glyphStates;
     constructor(target: T);
-    /** Interpolates stroke drawing (0-0.5) and then fill fade (0.5-1). */
+    private createState;
     interpolate(progress: number): void;
-    /** Interpolates a single VMobject (non-VGroup). */
-    private interpolateVMobject;
-    /** Interpolates a VGroup by animating each child's paths. */
     private interpolateVGroup;
+    private interpolateGlyphs;
+    /** Interpolates a single VMobject: stroke (0-0.5), then fill (0.5-1). */
+    private interpolateVMobject;
 }
 
 /**
- * Animation that progressively draws a VMobject's paths from start to end.
- * Preserves both stroke and fill properties - the complete object is visible at the end.
- *
- * This is the canonical animation for progressive path drawing.
- * At progress 0, nothing is shown. At progress 1, the complete path is shown.
+ * Animation that progressively draws VMobject paths from start to end.
  *
- * Supports VGroup (including Text): animates each child's paths progressively.
+ * - Single VMobject: paths draw progressively
+ * - VGroup: all children animate together with same progress
+ * - Text (VGroup of Glyphs): Glyphs animate sequentially for handwriting effect
  *
  * This is an introductory animation - it auto-registers the target with the scene.
- *
- * @example
- * const circle = new Circle(1);
- * scene.play(new Write(circle));  // Circle is drawn progressively
- *
- * const text = new Text('Hello');
- * scene.play(new Write(text));  // Text is written progressively
  */
 declare class Write<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 originalOpacity;
+    private readonly originalStrokeColor;
+    private readonly originalStrokeWidth;
+    private readonly originalFillColor;
     private readonly originalFillOpacity;
-    /** For VGroup targets: original state of each child. */
     private readonly childStates;
+    /** Glyph states for Text children, keyed by the Text VMobject reference. */
+    private readonly glyphStates;
     constructor(target: T);
+    private createState;
     interpolate(progress: number): void;
-    /** Interpolates a single VMobject (non-VGroup). */
-    private interpolateVMobject;
-    /** Interpolates a VGroup by animating each child's paths. */
     private interpolateVGroup;
+    private interpolateGlyphs;
+    /** Applies progress to a single VMobject, updating its paths and style. */
+    private applyProgress;
 }
 
 /**
@@ -1901,21 +1958,6 @@ declare class Shake extends TransformativeAnimation<CameraFrame> {
     private noise;
 }
 
-/**
- * Scene serialization - the main entry point for serializing/deserializing Scenes.
- */
-
-/**
- * Serializes a Scene into a JSON-formatted string.
- *
- * Useful for saving scene state to a file or transmitting it over a network.
- */
-declare function serialize(scene: Scene): string;
-/**
- * Restores a complete Scene from a JSON-formatted string.
- */
-declare function deserialize(json: string): Scene;
-
 /**
  * Supported render output formats.
  * - sprite: PNG sequence (frame_0000.png, frame_0001.png, ...)
@@ -1972,6 +2014,10 @@ interface RenderConfig {
     quality?: RenderQuality;
     /** Progress callback for render updates. */
     onProgress?: ProgressCallback;
+    /** Enable segment caching for incremental rendering. Default: true for video formats. */
+    cache?: boolean;
+    /** Custom cache directory path. Default: '.anima-cache' relative to output. */
+    cacheDir?: string;
 }
 /**
  * Progress information during rendering.
@@ -1995,12 +2041,17 @@ type ProgressCallback = (progress: RenderProgress) => void;
 
 /**
  * Main renderer for producing output from Scenes.
- * Supports multiple output formats and provides progress callbacks.
+ * Supports multiple output formats, progress callbacks, and
+ * segment-level caching for incremental re-renders.
  */
 declare class Renderer {
     /**
      * Renders a scene to the specified output.
      *
+     * For video formats (mp4/webp/gif) with caching enabled, renders
+     * each segment independently and concatenates the results.
+     * Segments whose hash matches a cached file are skipped entirely.
+     *
      * @param scene The scene to render
      * @param outputPath Output file or directory path (depends on format)
      * @param config Optional render configuration
@@ -2026,6 +2077,20 @@ declare class Renderer {
      * Renders a single frame (the last frame of the animation).
      */
     private renderSingleFrame;
+    /**
+     * Cache-aware segmented rendering.
+     *
+     * For each segment:
+     * 1. Check if a cached partial file exists (hash match)
+     * 2. If miss, render that segment's frame range to a partial .mp4
+     * 3. After all segments, concat partial files into final output
+     * 4. Prune orphaned cache entries
+     */
+    private renderSegmented;
+    /**
+     * Renders a single segment's frame range to a video file.
+     */
+    private renderSegmentToFile;
 }
 
 /**
@@ -2083,4 +2148,33 @@ declare class ProgressReporter {
     complete(): void;
 }
 
-export { Animation, type AnimationConfig, Arc, Arrow, Camera, type CameraConfig, CameraFrame, Circle, Color, Draw, type EasingFunction, type EdgeConfig, FadeIn, FadeOut, Follow, FrameRenderer, Glyph, Graph, GraphEdge, GraphNode, type GraphNodeId, type Keyframe, KeyframeAnimation, KeyframeTrack, type LayoutConfig, type LayoutType, Line, Mobject, MorphTo, MoveTo, type NodeConfig, Parallel, Point, Polygon, type ProgressCallback, ProgressReporter, Rectangle, type RenderConfig, type RenderFormat, type RenderProgress, type RenderQuality, Renderer, Resolution, type ResolvedCameraConfig, Rotate, Scale, Scene, type SceneConfig, type ScheduledAnimation, Sequence, Shake, Text, type TextStyle, Timeline, type TimelineConfig, Unwrite, VGroup, VMobject, Vector2, Write, clearRegistry, smooth as defaultEasing, deserialize, doubleSmooth, easeInBack, easeInBounce, easeInCirc, easeInCubic, easeInElastic, easeInExpo, easeInOutBack, easeInOutBounce, easeInOutCirc, easeInOutCubic, easeInOutElastic, easeInOutExpo, easeInOutQuad, easeInOutQuart, easeInOutQuint, easeInOutSine, easeInQuad, easeInQuart, easeInQuint, easeInSine, easeOutBack, easeOutBounce, easeOutCirc, easeOutCubic, easeOutElastic, easeOutExpo, easeOutQuad, easeOutQuart, easeOutQuint, easeOutSine, exponentialDecay, getEasing, hasEasing, linear, lingering, notQuiteThere, registerEasing, runningStart, rushFrom, rushInto, serialize, slowInto, smooth, thereAndBack, thereAndBackWithPause, unregisterEasing, wiggle };
+/** Protocol for objects that contribute to segment hashing. */
+interface Hashable {
+    computeHash(): number;
+}
+
+/**
+ * Manages a disk-based cache of rendered segment partial files.
+ *
+ * Each segment is stored as a video file keyed by its CRC32 hash.
+ * On re-render, segments whose hashes match an existing file are skipped.
+ */
+declare class SegmentCache {
+    private readonly cacheDir;
+    constructor(cacheDir: string);
+    /** Ensure the cache directory exists. */
+    init(): Promise<void>;
+    /** Check if a rendered segment file exists for the given hash. */
+    has(hash: number): boolean;
+    /** Get the absolute file path for a segment hash. */
+    getPath(hash: number): string;
+    /** Get the cache directory path. */
+    getDir(): string;
+    /**
+     * Remove cached files that are not in the active set.
+     * Call after a full render to clean up stale segments.
+     */
+    prune(activeHashes: Set<number>): Promise<void>;
+}
+
+export { Animation, type AnimationConfig, Arc, Arrow, Camera, type CameraConfig, CameraFrame, Circle, Color, Draw, type EasingFunction, type EdgeConfig, FadeIn, FadeOut, Follow, FrameRenderer, Glyph, Graph, GraphEdge, GraphNode, type GraphNodeId, type Hashable, type Keyframe, KeyframeAnimation, KeyframeTrack, type LayoutConfig, type LayoutType, Line, Mobject, MorphTo, MoveTo, type NodeConfig, Parallel, Polygon, type ProgressCallback, ProgressReporter, Rectangle, type RenderConfig, type RenderFormat, type RenderProgress, type RenderQuality, Renderer, Resolution, type ResolvedCameraConfig, Rotate, Scale, Scene, type SceneConfig, type ScheduledAnimation, type Segment, SegmentCache, Sequence, Shake, Text, Timeline, type TimelineConfig, Unwrite, VGroup, VMobject, Vector2, Write, clearRegistry, smooth as defaultEasing, doubleSmooth, easeInBack, easeInBounce, easeInCirc, easeInCubic, easeInElastic, easeInExpo, easeInOutBack, easeInOutBounce, easeInOutCirc, easeInOutCubic, easeInOutElastic, easeInOutExpo, easeInOutQuad, easeInOutQuart, easeInOutQuint, easeInOutSine, easeInQuad, easeInQuart, easeInQuint, easeInSine, easeOutBack, easeOutBounce, easeOutCirc, easeOutCubic, easeOutElastic, easeOutExpo, easeOutQuad, easeOutQuart, easeOutQuint, easeOutSine, exponentialDecay, getEasing, hasEasing, linear, lingering, notQuiteThere, registerEasing, runningStart, rushFrom, rushInto, slowInto, smooth, thereAndBack, thereAndBackWithPause, unregisterEasing, wiggle };