@redwilly/anima 0.1.22 → 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

@@ -358,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;
 }
 
 /**
@@ -416,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;
 }
 
 /**
@@ -916,6 +927,10 @@ declare class Camera {
      */
     isInView(pos: Vector2): boolean;
     reset(): this;
+    /**
+     * Hashes camera config and the CameraFrame's full transform state.
+     */
+    computeHash(): number;
 }
 
 /**
@@ -932,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
@@ -942,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;
@@ -1019,6 +1055,11 @@ 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.
@@ -1039,6 +1080,11 @@ declare class Scene {
      * 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';
@@ -1186,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';
@@ -1239,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 {
@@ -1260,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;
 }
 
@@ -1293,32 +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;
-    /** Override stroke to propagate to all Glyph children. */
+    /** Propagates this Text's fill/stroke to all Glyph children. */
+    private propagate;
     stroke(color: Color, width?: number): this;
-    /** Override fill to propagate to all Glyph children. */
     fill(color: Color, opacity?: number): this;
+    getFontSize(): number;
     getGlyph(index: number): Glyph | undefined;
 }
 
@@ -1968,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.
@@ -1991,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
@@ -2022,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;
 }
 
 /**
@@ -2079,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, 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 };
+/** 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 };

package/dist/index.js

@@ -464,6 +464,44 @@ var Matrix3x3 = class _Matrix3x3 {
   static IDENTITY = new _Matrix3x3(createIdentity());
 };
 
+// src/core/cache/Hashable.ts
+var CRC32_TABLE = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let crc = i;
+  for (let j = 0; j < 8; j++) {
+    crc = crc & 1 ? crc >>> 1 ^ 3988292384 : crc >>> 1;
+  }
+  CRC32_TABLE[i] = crc;
+}
+function crc32(data) {
+  let crc = 4294967295;
+  for (let i = 0; i < data.length; i++) {
+    crc = crc >>> 8 ^ CRC32_TABLE[(crc ^ data[i]) & 255];
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+var FLOAT64_VIEW = new Float64Array(1);
+var FLOAT64_BYTES = new Uint8Array(FLOAT64_VIEW.buffer);
+function hashNumber(n) {
+  FLOAT64_VIEW[0] = n;
+  return crc32(FLOAT64_BYTES);
+}
+function hashString(s) {
+  const encoder = new TextEncoder();
+  return crc32(encoder.encode(s));
+}
+function hashFloat32Array(arr) {
+  return crc32(new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength));
+}
+function hashCompose(...hashes) {
+  const buf = new Uint8Array(hashes.length * 4);
+  const view = new DataView(buf.buffer);
+  for (let i = 0; i < hashes.length; i++) {
+    view.setUint32(i * 4, hashes[i], false);
+  }
+  return crc32(buf);
+}
+
 // src/core/animations/easing/standard.ts
 var linear = (t) => t;
 var easeInQuad = (t) => t * t;
@@ -673,6 +711,20 @@ var Animation = class {
     const easedProgress = this.easingFn(clampedProgress);
     this.interpolate(easedProgress);
   }
+  /**
+   * Hashes the animation type, config, and target state.
+   * Subclass-specific behavior is captured through the target's hash,
+   * since animations mutate the target.
+   */
+  computeHash() {
+    return hashCompose(
+      hashString(this.constructor.name),
+      hashNumber(this.durationSeconds),
+      hashNumber(this.delaySeconds),
+      hashString(this.easingFn.name || "anonymous"),
+      this.target.computeHash()
+    );
+  }
 };
 
 // src/core/animations/categories/IntroductoryAnimation.ts
@@ -1280,6 +1332,16 @@ var Mobject = class {
     this.getQueue().enqueueAnimation(new Parallel(animations));
     return this;
   }
+  /**
+   * Computes a CRC32 hash of this mobject's full state.
+   * Used by the segment cache to detect changes.
+   */
+  computeHash() {
+    return hashCompose(
+      hashFloat32Array(this.localMatrix.values),
+      hashNumber(this.opacityValue)
+    );
+  }
 };
 
 // src/core/camera/types.ts
@@ -1734,6 +1796,16 @@ var Camera = class {
     this.frame.setRotation(0);
     return this;
   }
+  /**
+   * Hashes camera config and the CameraFrame's full transform state.
+   */
+  computeHash() {
+    return hashCompose(
+      hashNumber(this.config.pixelWidth),
+      hashNumber(this.config.pixelHeight),
+      hashFloat32Array(this.frame.matrix.values)
+    );
+  }
 };
 
 // src/core/errors/AnimationErrors.ts
@@ -1777,6 +1849,7 @@ var Scene = class {
   mobjects = /* @__PURE__ */ new Set();
   timeline;
   _camera;
+  segmentList = [];
   playheadTime = 0;
   constructor(config = {}) {
     this.config = {
@@ -1894,7 +1967,15 @@ var Scene = class {
         maxDuration = totalTime;
       }
     }
-    this.playheadTime += maxDuration;
+    const endTime = this.playheadTime + maxDuration;
+    this.segmentList.push({
+      index: this.segmentList.length,
+      startTime: this.playheadTime,
+      endTime,
+      animations,
+      hash: this.computeSegmentHash(animations, this.playheadTime, endTime)
+    });
+    this.playheadTime = endTime;
     return this;
   }
   /**
@@ -1905,7 +1986,15 @@ var Scene = class {
     if (seconds < 0) {
       throw new Error("Wait duration must be non-negative");
     }
-    this.playheadTime += seconds;
+    const endTime = this.playheadTime + seconds;
+    this.segmentList.push({
+      index: this.segmentList.length,
+      startTime: this.playheadTime,
+      endTime,
+      animations: [],
+      hash: this.computeSegmentHash([], this.playheadTime, endTime)
+    });
+    this.playheadTime = endTime;
     return this;
   }
   /**
@@ -1935,6 +2024,13 @@ var Scene = class {
   getCamera() {
     return this._camera;
   }
+  /**
+   * Get the list of segments emitted by play() and wait() calls.
+   * Used by the Renderer for cache-aware segmented rendering.
+   */
+  getSegments() {
+    return this.segmentList;
+  }
   // ========== Private Helpers ==========
   /**
    * Validates and registers animation targets based on lifecycle.
@@ -1998,6 +2094,22 @@ var Scene = class {
     }
     return [];
   }
+  /**
+   * Computes a holistic CRC32 hash for a segment.
+   * Includes camera state, all current mobjects, animations, and timing.
+   */
+  computeSegmentHash(animations, startTime, endTime) {
+    const cameraHash = this._camera.computeHash();
+    const mobjectHashes = [...this.mobjects].map((m) => m.computeHash());
+    const animHashes = animations.map((a) => a.computeHash());
+    return hashCompose(
+      cameraHash,
+      ...mobjectHashes,
+      ...animHashes,
+      hashNumber(startTime),
+      hashNumber(endTime)
+    );
+  }
 };
 
 // src/core/math/bezier/evaluators.ts
@@ -3159,6 +3271,34 @@ var VMobject = class extends Mobject {
     this.getQueue().enqueueAnimation(animation);
     return this;
   }
+  /**
+   * Extends parent hash with VMobject-specific state:
+   * stroke/fill colors, widths, opacity, and path geometry.
+   */
+  computeHash() {
+    const parentHash = super.computeHash();
+    const pathHash = hashString(
+      this.pathList.map(
+        (p) => p.getCommands().map(
+          (c) => `${c.type}:${c.end.x},${c.end.y}` + (c.control1 ? `:${c.control1.x},${c.control1.y}` : "") + (c.control2 ? `:${c.control2.x},${c.control2.y}` : "")
+        ).join("|")
+      ).join("||")
+    );
+    return hashCompose(
+      parentHash,
+      hashNumber(this.strokeColor.r),
+      hashNumber(this.strokeColor.g),
+      hashNumber(this.strokeColor.b),
+      hashNumber(this.strokeColor.a),
+      hashNumber(this.strokeWidth),
+      hashNumber(this.fillColor.r),
+      hashNumber(this.fillColor.g),
+      hashNumber(this.fillColor.b),
+      hashNumber(this.fillColor.a),
+      hashNumber(this.fillOpacity),
+      pathHash
+    );
+  }
 };
 
 // src/mobjects/VGroup/layout.ts
@@ -3412,6 +3552,14 @@ var VGroup = class extends VMobject {
     alignToTarget(this, target, edge);
     return this;
   }
+  /**
+   * Recursively hashes this VGroup and all children.
+   * Any child state change invalidates segments containing this group.
+   */
+  computeHash() {
+    const childHashes = this.children.map((c) => c.computeHash());
+    return hashCompose(super.computeHash(), ...childHashes);
+  }
 };
 
 // src/mobjects/geometry/Arc.ts
@@ -3486,21 +3634,12 @@ var Line = class extends VMobject {
   }
 };
 
-// src/mobjects/geometry/Point.ts
-var Point = class extends Circle {
-  constructor(location = Vector2.ZERO) {
-    super(0.05);
-    this.fill(Color.WHITE, 1);
-    this.stroke(Color.WHITE, 0);
-    this.pos(location.x, location.y);
-  }
-};
-
 // src/mobjects/geometry/Polygon.ts
 var Polygon = class extends VMobject {
-  constructor(vertices) {
+  vertices;
+  constructor(...points) {
     super();
-    this.vertices = vertices;
+    this.vertices = points.map(([x, y]) => new Vector2(x, y));
     this.generatePath();
   }
   generatePath() {
@@ -3520,16 +3659,16 @@ var Rectangle = class extends Polygon {
   constructor(width = 2, height = 1) {
     const halfW = width / 2;
     const halfH = height / 2;
-    super([
-      new Vector2(-halfW, -halfH),
+    super(
+      [-halfW, -halfH],
       // Top-Left
-      new Vector2(halfW, -halfH),
+      [halfW, -halfH],
       // Top-Right
-      new Vector2(halfW, halfH),
+      [halfW, halfH],
       // Bottom-Right
-      new Vector2(-halfW, halfH)
+      [-halfW, halfH]
       // Bottom-Left
-    ]);
+    );
     this.width = width;
     this.height = height;
   }
@@ -3558,10 +3697,13 @@ var Arrow = class extends Line {
     tipPath.lineTo(p2);
     tipPath.closePath();
     this.addPath(tipPath);
-    this.fillOpacity = 1;
   }
 };
 
+// src/mobjects/text/Text.ts
+import * as fontkit from "fontkit";
+import { join, resolve } from "path";
+
 // src/mobjects/text/Glyph.ts
 function convertFontkitPath(fontkitPath, scale, offsetX, offsetY) {
   const path = new BezierPath();
@@ -3619,30 +3761,20 @@ var Glyph = class extends VMobject {
   }
 };
 
-// src/mobjects/text/Text.ts
-import * as fontkit from "fontkit";
-import { join, resolve } from "path";
-
-// src/mobjects/text/types.ts
-var DEFAULT_TEXT_STYLE = {
-  fontSize: 1,
-  color: Color.WHITE
-};
-
 // src/mobjects/text/Text.ts
 var DEFAULT_FONT_PATH = resolve(join(__dirname, "..", "..", "fonts", "ComicSansMS3.ttf"));
 var Text = class extends VGroup {
   text;
-  style;
+  fontSize;
   fontPath;
   constructor(text, fontPath, options = {}) {
     super();
     this.text = text;
     this.fontPath = fontPath ?? DEFAULT_FONT_PATH;
-    this.style = { ...DEFAULT_TEXT_STYLE, ...options };
+    this.fontSize = options.fontSize ?? 1;
     this.buildGlyphs();
     centerGroup(this);
-    this.applyStyle();
+    this.propagate();
   }
   buildGlyphs() {
     const fontOrCollection = fontkit.openSync(this.fontPath);
@@ -3651,26 +3783,23 @@ var Text = class extends VGroup {
       throw new Error(`Could not load font from ${this.fontPath}`);
     }
     const run = font.layout(this.text);
-    const scale = this.style.fontSize / font.unitsPerEm;
+    const scale = this.fontSize / font.unitsPerEm;
     let penX = 0;
     let penY = 0;
     for (let i = 0; i < run.glyphs.length; i++) {
       const glyph = run.glyphs[i];
       const pos = run.positions[i];
       if (glyph === void 0 || pos === void 0) continue;
-      const char = this.getCharacterForGlyph(i);
+      const char = this.text.charAt(i) || "";
       const glyphX = penX + pos.xOffset * scale;
       const glyphY = penY + pos.yOffset * scale;
-      const glyphMobject = new Glyph(glyph, char, scale, glyphX, glyphY);
-      this.add(glyphMobject);
+      this.add(new Glyph(glyph, char, scale, glyphX, glyphY));
       penX += pos.xAdvance * scale;
       penY += pos.yAdvance * scale;
     }
   }
-  getCharacterForGlyph(index) {
-    return this.text.charAt(index) || "";
-  }
-  applyStyle() {
+  /** Propagates this Text's fill/stroke to all Glyph children. */
+  propagate() {
     for (const child of this.getChildren()) {
       if (child instanceof Glyph) {
         child.stroke(this.getStrokeColor(), this.getStrokeWidth());
@@ -3678,26 +3807,19 @@ var Text = class extends VGroup {
       }
     }
   }
-  setStyle(options) {
-    this.style = { ...this.style, ...options };
-    this.applyStyle();
-    return this;
-  }
-  getStyle() {
-    return { ...this.style };
-  }
-  /** Override stroke to propagate to all Glyph children. */
   stroke(color, width = 2) {
     super.stroke(color, width);
-    this.applyStyle();
+    this.propagate();
     return this;
   }
-  /** Override fill to propagate to all Glyph children. */
   fill(color, opacity) {
     super.fill(color, opacity);
-    this.applyStyle();
+    this.propagate();
     return this;
   }
+  getFontSize() {
+    return this.fontSize;
+  }
   getGlyph(index) {
     const child = this.get(index);
     return child instanceof Glyph ? child : void 0;
@@ -4671,13 +4793,104 @@ async function renderVideo(frameRenderer, outputPath, format, frameRate, totalDu
   progressReporter.complete();
 }
 
+// src/core/renderer/formats/concat.ts
+import { dirname, join as join3, resolve as resolve2 } from "path";
+async function concatSegments(segmentPaths, outputPath) {
+  if (segmentPaths.length === 0) {
+    throw new Error("No segments to concatenate");
+  }
+  if (segmentPaths.length === 1) {
+    const src = Bun.file(segmentPaths[0]);
+    await Bun.write(outputPath, src);
+    return;
+  }
+  const listContent = segmentPaths.map((p) => `file '${resolve2(p).replace(/\\/g, "/")}'`).join("\n");
+  const listPath = join3(dirname(outputPath), ".concat_list.txt");
+  await Bun.write(listPath, listContent);
+  try {
+    const process = Bun.spawn([
+      "ffmpeg",
+      "-y",
+      "-f",
+      "concat",
+      "-safe",
+      "0",
+      "-i",
+      listPath,
+      "-c",
+      "copy",
+      outputPath
+    ]);
+    const status = await process.exited;
+    if (status !== 0) {
+      throw new Error(`FFmpeg concat exited with code ${status}`);
+    }
+  } finally {
+    try {
+      const { unlink: unlink2 } = await import("fs/promises");
+      await unlink2(listPath);
+    } catch {
+    }
+  }
+}
+
+// src/core/cache/SegmentCache.ts
+import { existsSync } from "fs";
+import { mkdir, readdir, unlink } from "fs/promises";
+import { join as join4 } from "path";
+var SegmentCache = class {
+  cacheDir;
+  constructor(cacheDir) {
+    this.cacheDir = cacheDir;
+  }
+  /** Ensure the cache directory exists. */
+  async init() {
+    await mkdir(this.cacheDir, { recursive: true });
+  }
+  /** Check if a rendered segment file exists for the given hash. */
+  has(hash) {
+    return existsSync(this.getPath(hash));
+  }
+  /** Get the absolute file path for a segment hash. */
+  getPath(hash) {
+    const name = `segment_${hash.toString(16).padStart(8, "0")}.mp4`;
+    return join4(this.cacheDir, name);
+  }
+  /** Get the cache directory path. */
+  getDir() {
+    return this.cacheDir;
+  }
+  /**
+   * Remove cached files that are not in the active set.
+   * Call after a full render to clean up stale segments.
+   */
+  async prune(activeHashes) {
+    if (!existsSync(this.cacheDir)) return;
+    const entries = await readdir(this.cacheDir);
+    const removals = [];
+    for (const entry of entries) {
+      if (!entry.startsWith("segment_") || !entry.endsWith(".mp4")) continue;
+      const hexStr = entry.slice(8, 16);
+      const hash = parseInt(hexStr, 16);
+      if (!activeHashes.has(hash)) {
+        removals.push(unlink(join4(this.cacheDir, entry)));
+      }
+    }
+    await Promise.all(removals);
+  }
+};
+
 // src/core/renderer/Renderer.ts
-import { mkdir } from "fs/promises";
-import { dirname } from "path";
+import { mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname2, join as join5 } from "path";
 var Renderer = class {
   /**
    * 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
@@ -4690,6 +4903,20 @@ var Renderer = class {
     const frameRenderer = new FrameRenderer(scene, width, height);
     const totalFrames = Math.max(1, Math.floor(totalDuration * resolved.frameRate) + 1);
     const progressReporter = new ProgressReporter(totalFrames, resolved.onProgress);
+    const segments = scene.getSegments();
+    const isVideoFormat = resolved.format === "mp4" || resolved.format === "webp" || resolved.format === "gif";
+    const useCache = resolved.cache && isVideoFormat && segments.length > 0;
+    if (useCache) {
+      await this.renderSegmented(
+        scene,
+        frameRenderer,
+        outputPath,
+        resolved,
+        segments,
+        progressReporter
+      );
+      return;
+    }
     switch (resolved.format) {
       case "sprite":
         await this.ensureDirectory(outputPath);
@@ -4702,13 +4929,13 @@ var Renderer = class {
         );
         break;
       case "png":
-        await this.ensureDirectory(dirname(outputPath));
+        await this.ensureDirectory(dirname2(outputPath));
         await this.renderSingleFrame(frameRenderer, outputPath, totalDuration, progressReporter);
         break;
       case "mp4":
       case "webp":
       case "gif":
-        await this.ensureDirectory(dirname(outputPath));
+        await this.ensureDirectory(dirname2(outputPath));
         await renderVideo(
           frameRenderer,
           outputPath,
@@ -4736,7 +4963,7 @@ var Renderer = class {
     const height = resolved.quality === "preview" ? Math.floor(resolved.height / 2) : resolved.height;
     const frameRenderer = new FrameRenderer(scene, width, height);
     const progressReporter = new ProgressReporter(1, resolved.onProgress);
-    await this.ensureDirectory(dirname(outputPath));
+    await this.ensureDirectory(dirname2(outputPath));
     const canvas = frameRenderer.renderFrame(totalDuration);
     await writePng(canvas, outputPath);
     progressReporter.complete();
@@ -4745,21 +4972,25 @@ var Renderer = class {
    * Resolves partial config with scene defaults.
    */
   resolveConfig(scene, config) {
+    const format = config.format ?? "sprite";
+    const isVideoFormat = format === "mp4" || format === "webp" || format === "gif";
     return {
       width: config.width ?? scene.getWidth(),
       height: config.height ?? scene.getHeight(),
       frameRate: config.frameRate ?? scene.getFrameRate(),
-      format: config.format ?? "sprite",
+      format,
       quality: config.quality ?? "production",
-      onProgress: config.onProgress
+      onProgress: config.onProgress,
+      cache: config.cache ?? isVideoFormat,
+      cacheDir: config.cacheDir
     };
   }
   /**
    * Ensures the directory exists.
    */
   async ensureDirectory(dirPath) {
-    if (!dirPath) return;
-    await mkdir(dirPath, { recursive: true });
+    if (!dirPath || dirPath === ".") return;
+    await mkdir2(dirPath, { recursive: true });
   }
   /**
    * Renders a single frame (the last frame of the animation).
@@ -4769,6 +5000,103 @@ var Renderer = class {
     await writePng(canvas, outputPath);
     progressReporter.complete();
   }
+  /**
+   * 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
+   */
+  async renderSegmented(scene, frameRenderer, outputPath, config, segments, progressReporter) {
+    const cacheDir = config.cacheDir ?? join5(dirname2(outputPath), ".anima-cache");
+    const cache = new SegmentCache(cacheDir);
+    await cache.init();
+    await this.ensureDirectory(dirname2(outputPath));
+    const segmentPaths = [];
+    let framesRendered = 0;
+    for (const segment of segments) {
+      const segmentPath = cache.getPath(segment.hash);
+      if (cache.has(segment.hash)) {
+        const segmentFrames2 = Math.max(
+          1,
+          Math.floor((segment.endTime - segment.startTime) * config.frameRate) + 1
+        );
+        framesRendered += segmentFrames2;
+        progressReporter.reportFrame(framesRendered - 1);
+        segmentPaths.push(segmentPath);
+        continue;
+      }
+      await this.renderSegmentToFile(
+        frameRenderer,
+        segmentPath,
+        config.format,
+        config.frameRate,
+        segment,
+        progressReporter,
+        framesRendered
+      );
+      const segmentFrames = Math.max(
+        1,
+        Math.floor((segment.endTime - segment.startTime) * config.frameRate) + 1
+      );
+      framesRendered += segmentFrames;
+      segmentPaths.push(segmentPath);
+    }
+    await concatSegments(segmentPaths, outputPath);
+    const activeHashes = new Set(segments.map((s) => s.hash));
+    await cache.prune(activeHashes);
+    progressReporter.complete();
+  }
+  /**
+   * Renders a single segment's frame range to a video file.
+   */
+  async renderSegmentToFile(frameRenderer, outputPath, format, frameRate, segment, progressReporter, frameOffset) {
+    const segmentDuration = segment.endTime - segment.startTime;
+    const totalFrames = Math.max(1, Math.floor(segmentDuration * frameRate) + 1);
+    const { width, height } = frameRenderer.getDimensions();
+    const ffmpegArgs = [
+      "-y",
+      "-f",
+      "image2pipe",
+      "-vcodec",
+      "png",
+      "-r",
+      frameRate.toString(),
+      "-i",
+      "-"
+    ];
+    ffmpegArgs.push(
+      "-c:v",
+      "libx264",
+      "-pix_fmt",
+      "yuv420p",
+      "-crf",
+      "18"
+    );
+    ffmpegArgs.push(outputPath);
+    const process = Bun.spawn(["ffmpeg", ...ffmpegArgs], {
+      stdin: "pipe"
+    });
+    try {
+      for (let i = 0; i < totalFrames; i++) {
+        const time = segment.startTime + i / frameRate;
+        const canvas = frameRenderer.renderFrame(time);
+        const pngBuffer = await canvas.toBuffer("image/png");
+        process.stdin.write(pngBuffer);
+        progressReporter.reportFrame(frameOffset + i);
+      }
+      process.stdin.end();
+      const status = await process.exited;
+      if (status !== 0) {
+        throw new Error(`FFmpeg segment render exited with code ${status}`);
+      }
+    } catch (error) {
+      process.kill();
+      throw error;
+    }
+  }
 };
 
 // src/core/renderer/types.ts
@@ -4806,7 +5134,6 @@ export {
   MorphTo,
   MoveTo,
   Parallel,
-  Point,
   Polygon,
   ProgressReporter,
   Rectangle,
@@ -4815,6 +5142,7 @@ export {
   Rotate,
   Scale,
   Scene,
+  SegmentCache,
   Sequence,
   Shake,
   Text,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redwilly/anima",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Animation library for mathematical visualizations",
   "repository": {
     "type": "git",
@@ -58,4 +58,4 @@
     "commander": "^14.0.2",
     "fontkit": "^2.0.4"
   }
-}
+}