@redwilly/anima 0.1.25 → 0.1.26

package/dist/index.d.ts

@@ -1,50 +1,51 @@
 import { Glyph as Glyph$1 } from 'fontkit';
+import { Canvas } from '@napi-rs/canvas';
 
 /**
- * A 2D vector class representing a point or direction in 2D space.
+ * Unified vector type for both 2D and 3D usage.
+ * - 2D vectors use z = 0
+ * - 3D vectors use non-zero z when needed
  */
-declare class Vector2 {
+declare class Vector {
     readonly x: number;
     readonly y: number;
-    constructor(x: number, y: number);
-    add(other: Vector2): Vector2;
-    subtract(other: Vector2): Vector2;
-    multiply(scalar: number): Vector2;
-    dot(other: Vector2): number;
-    /** Magnitude (length) of the vector. */
+    readonly z: number;
+    constructor(x: number, y: number, z?: number);
+    add(other: Vector): Vector;
+    subtract(other: Vector): Vector;
+    multiply(scalar: number): Vector;
+    dot(other: Vector): number;
     length(): number;
-    /** Returns a normalized unit vector. Returns ZERO for zero-length vectors. */
-    normalize(): Vector2;
-    lerp(other: Vector2, t: number): Vector2;
-    equals(other: Vector2, tolerance?: number): boolean;
-    static readonly ZERO: Vector2;
-    static readonly UP: Vector2;
-    static readonly DOWN: Vector2;
-    static readonly LEFT: Vector2;
-    static readonly RIGHT: Vector2;
+    normalize(): Vector;
+    lerp(other: Vector, t: number): Vector;
+    equals(other: Vector, tolerance?: number): boolean;
+    toPlanar(): Vector;
+    static fromPlanar(v: Vector, z?: number): Vector;
+    static readonly ZERO: Vector;
+    static readonly UP: Vector;
+    static readonly DOWN: Vector;
+    static readonly LEFT: Vector;
+    static readonly RIGHT: Vector;
 }
 
 /**
- * A 3x3 matrix class for 2D affine transformations.
- * Stored in row-major order:
- * [ 0  1  2 ]
- * [ 3  4  5 ]
- * [ 6  7  8 ]
+ * A 4x4 matrix class for 3D affine transforms and projection.
+ * Stored in row-major order.
  */
-declare class Matrix3x3 {
+declare class Matrix4x4 {
     readonly values: Float32Array;
     constructor(values: number[] | Float32Array);
-    multiply(other: Matrix3x3): Matrix3x3;
-    /** Transforms a Vector2 point (assumes z=1). */
-    transformPoint(point: Vector2): Vector2;
-    /** @throws Error if the matrix is not invertible. */
-    inverse(): Matrix3x3;
-    static identity(): Matrix3x3;
-    static translation(tx: number, ty: number): Matrix3x3;
-    static rotation(angle: number): Matrix3x3;
-    static scale(sx: number, sy: number): Matrix3x3;
-    static shear(shx: number, shy: number): Matrix3x3;
-    static readonly IDENTITY: Matrix3x3;
+    multiply(other: Matrix4x4): Matrix4x4;
+    transformPoint(point: Vector): Vector;
+    transformPoint2D(point: Vector): Vector;
+    inverse(): Matrix4x4;
+    static identity(): Matrix4x4;
+    static translation(tx: number, ty: number, tz?: number): Matrix4x4;
+    static rotationX(angle: number): Matrix4x4;
+    static rotationY(angle: number): Matrix4x4;
+    static rotationZ(angle: number): Matrix4x4;
+    static scale(sx: number, sy: number, sz?: number): Matrix4x4;
+    static readonly IDENTITY: Matrix4x4;
 }
 
 /**
@@ -79,9 +80,9 @@ declare class Color {
 type PathCommandType = 'Move' | 'Line' | 'Quadratic' | 'Cubic' | 'Close';
 interface PathCommand {
     type: PathCommandType;
-    end: Vector2;
-    control1?: Vector2;
-    control2?: Vector2;
+    end: Vector;
+    control1?: Vector;
+    control2?: Vector;
 }
 
 /**
@@ -100,17 +101,17 @@ declare class BezierPath {
     /** Builds the cache if not already valid. */
     private ensureCache;
     /** Starts a new subpath at the specified point. */
-    moveTo(point: Vector2): void;
-    lineTo(point: Vector2): void;
-    quadraticTo(control: Vector2, end: Vector2): void;
-    cubicTo(control1: Vector2, control2: Vector2, end: Vector2): void;
+    moveTo(point: Vector): void;
+    lineTo(point: Vector): void;
+    quadraticTo(control: Vector, end: Vector): void;
+    cubicTo(control1: Vector, control2: Vector, end: Vector): void;
     closePath(): void;
     getCommands(): PathCommand[];
     getLength(): number;
     /** Returns the point on the path at the normalized position t (0-1). */
-    getPointAt(t: number): Vector2;
-    getTangentAt(t: number): Vector2;
-    getPoints(count: number): Vector2[];
+    getPointAt(t: number): Vector;
+    getTangentAt(t: number): Vector;
+    getPoints(count: number): Vector[];
     getPointCount(): number;
     clone(): BezierPath;
     /** Returns a new BezierPath where all segments are converted to Cubic curves. */
@@ -121,6 +122,60 @@ declare class BezierPath {
     private static fromCommands;
 }
 
+/**
+ * Context provided to updater functions on each frame evaluation.
+ */
+interface UpdaterContext {
+    /** Absolute scene time in seconds. */
+    readonly time: number;
+    /** Time delta from previous evaluated frame (seconds). */
+    readonly dt: number;
+    /** Monotonic frame index produced by the updater engine. */
+    readonly frame: number;
+    /** The scene currently being evaluated. */
+    readonly scene: Scene;
+    /**
+     * True when evaluation is discontinuous (first frame or backward seek).
+     * Updaters using integrators can use this to reset internal accumulators.
+     */
+    readonly discontinuous: boolean;
+}
+/**
+ * A function that mutates a mobject every evaluated frame.
+ */
+type UpdaterFunction<T extends Mobject = Mobject> = (mobject: T, context: UpdaterContext) => void;
+/**
+ * Public options accepted by Mobject.addUpdater.
+ */
+interface UpdaterOptions {
+    /**
+     * Higher priority runs first. Default: 0.
+     * Ties are resolved by insertion order.
+     */
+    priority?: number;
+    /** Whether this updater starts enabled. Default: true. */
+    enabled?: boolean;
+    /** Optional descriptive label for debugging/introspection. */
+    name?: string;
+}
+/**
+ * Opaque handle returned from addUpdater for later removal/toggling.
+ */
+interface UpdaterHandle {
+    readonly id: number;
+}
+/**
+ * Internal normalized representation stored by each mobject.
+ */
+interface MobjectUpdaterRecord {
+    readonly id: number;
+    readonly order: number;
+    readonly name?: string;
+    readonly fn: UpdaterFunction<Mobject>;
+    priority: number;
+    enabled: boolean;
+}
+
 /**
  * Type signature for an easing function.
  * Maps a progress value t ∈ [0, 1] to an eased value.
@@ -561,12 +616,12 @@ declare class FadeOut<T extends Mobject = Mobject> extends ExitAnimation<T> {
 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);
+    constructor(target: T, destination: Vector);
+    constructor(target: T, x: number, y: number, z?: number);
     protected captureStartState(): void;
     interpolate(progress: number): void;
     /** Returns the target position of the move animation. */
-    getDestination(): Vector2;
+    getDestination(): Vector;
 }
 
 /**
@@ -631,8 +686,8 @@ declare class AnimationQueue {
     getTotalDuration(): number;
 }
 interface MobjectState {
-    position: Vector2;
-    scale: Vector2;
+    position: Vector;
+    scale: Vector;
     rotation: number;
 }
 /**
@@ -641,26 +696,60 @@ interface MobjectState {
  * Includes fluent animation API for chainable animations.
  */
 declare class Mobject {
-    protected localMatrix: Matrix3x3;
+    protected localMatrix: Matrix4x4;
     protected opacityValue: number;
     protected animQueue: AnimationQueue | null;
+    protected pointCloud: Vector[];
+    protected submobjects: Mobject[];
     private savedStates;
+    private logicalRotation;
+    private logicalScale;
+    private updaters;
+    private nextUpdaterId;
+    private nextUpdaterOrder;
+    private updatersEnabled;
     parent: Mobject | null;
     constructor();
     protected getQueue(): AnimationQueue;
-    get matrix(): Matrix3x3;
-    getWorldMatrix(): Matrix3x3;
-    get position(): Vector2;
+    get matrix(): Matrix4x4;
+    getWorldMatrix(): Matrix4x4;
+    /**
+     * Matrix used by renderer.
+     * Geometry-driven mobjects bake their own transform into points,
+     * so only ancestor matrix transforms should be applied at draw time.
+     */
+    getRenderMatrix(): Matrix4x4;
+    get position(): Vector;
     get rotation(): number;
-    get scale(): Vector2;
+    get scale(): Vector;
     get opacity(): number;
-    pos(x: number, y: number): this;
+    pos(x: number, y: number, z?: number): this;
     show(): this;
     hide(): this;
     setOpacity(value: number): this;
     setRotation(angle: number): this;
     setScale(sx: number, sy: number): this;
-    applyMatrix(m: Matrix3x3): this;
+    applyMatrix(m: Matrix4x4): this;
+    addSubmobjects(...mobjects: Mobject[]): this;
+    removeSubmobject(mobject: Mobject): this;
+    clearSubmobjects(): this;
+    getSubmobjects(): Mobject[];
+    addUpdater(fn: UpdaterFunction<this>, options?: UpdaterOptions): UpdaterHandle;
+    removeUpdater(handleOrFn: UpdaterHandle | UpdaterFunction<this>): this;
+    clearUpdaters(): this;
+    suspendUpdaters(): this;
+    resumeUpdaters(): this;
+    enableUpdater(handleOrFn: UpdaterHandle | UpdaterFunction<this>): this;
+    disableUpdater(handleOrFn: UpdaterHandle | UpdaterFunction<this>): this;
+    hasActiveUpdaters(recursive?: boolean): boolean;
+    /**
+     * Internal API used by UpdaterEngine.
+     * Returns a deterministic snapshot for current-frame execution.
+     */
+    getUpdaterRecordsSnapshot(): MobjectUpdaterRecord[];
+    private setUpdaterEnabled;
+    protected setPointCloud(points: Array<Vector>): void;
+    protected getPointCloud(): Vector[];
     saveState(): this;
     getSavedState(): MobjectState | undefined;
     clearSavedStates(): this;
@@ -678,9 +767,15 @@ declare class Mobject {
     fadeOut(durationSeconds?: number): this & {
         toAnimation(): Animation<Mobject>;
     };
+    moveTo(destination: Vector, durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
     moveTo(x: number, y: number, durationSeconds?: number): this & {
         toAnimation(): Animation<Mobject>;
     };
+    moveTo(x: number, y: number, z: number, durationSeconds?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
     rotate(angle: number, durationSeconds?: number): this & {
         toAnimation(): Animation<Mobject>;
     };
@@ -711,6 +806,13 @@ declare class Mobject {
      * Used by the segment cache to detect changes.
      */
     computeHash(): number;
+    protected applyMatrixToOwnGeometry(m: Matrix4x4): void;
+    protected usesGeometryTransforms(): boolean;
+    private collectGeometryPoints;
+    private getGeometryCenter;
+    private syncLocalMatrixFromGeometry;
+    private updateLogicalStateFromMatrix;
+    private setLocalMatrix;
 }
 
 /**
@@ -788,6 +890,7 @@ declare class VMobject extends Mobject {
         minY: number;
         maxY: number;
     };
+    protected applyMatrixToOwnGeometry(m: Matrix4x4): void;
     /**
      * Progressively draws the VMobject's paths from start to end.
      * Preserves fill throughout the animation.
@@ -818,6 +921,7 @@ declare class VMobject extends Mobject {
      * stroke/fill colors, widths, opacity, and path geometry.
      */
     computeHash(): number;
+    private syncPointCloudFromPaths;
 }
 
 /**
@@ -1086,7 +1190,7 @@ interface ResolvedCameraConfig {
  * @example
  * // Instant camera manipulation
  * camera.zoomTo(2);
- * camera.panTo(new Vector2(5, 3));
+ * camera.panTo(new Vector(5, 3));
  *
  * @example
  * // Animated camera movement via frame
@@ -1111,14 +1215,14 @@ declare class Camera {
     get frameXRadius(): number;
     get pixelWidth(): number;
     get pixelHeight(): number;
-    get position(): Vector2;
+    get position(): Vector;
     get zoom(): number;
     get rotation(): number;
-    pan(delta: Vector2): this;
-    panTo(position: Vector2): this;
+    pan(delta: Vector): this;
+    panTo(position: Vector): this;
     zoomTo(level: number): this;
     rotateTo(angle: number): this;
-    getViewMatrix(): Matrix3x3;
+    getViewMatrix(): Matrix4x4;
     /**
      * Transforms a world-space position to screen-space (pixel) coordinates.
      *
@@ -1132,7 +1236,7 @@ declare class Camera {
      * const screenPos = camera.worldToScreen(circle.position);
      * console.log(`Circle is at pixel (${screenPos.x}, ${screenPos.y})`);
      */
-    worldToScreen(pos: Vector2): Vector2;
+    worldToScreen(pos: Vector): Vector;
     /**
      * Transforms a screen-space (pixel) position to world coordinates.
      * This is the inverse of worldToScreen.
@@ -1142,9 +1246,9 @@ declare class Camera {
      *
      * @example
      * // Convert a mouse click position to world coordinates
-     * const worldPos = camera.screenToWorld(new Vector2(mouseX, mouseY));
+     * const worldPos = camera.screenToWorld(new Vector(mouseX, mouseY));
      */
-    screenToWorld(pos: Vector2): Vector2;
+    screenToWorld(pos: Vector): Vector;
     /**
      * Checks if a world-space position is currently visible within the camera frame.
      *
@@ -1156,7 +1260,7 @@ declare class Camera {
      *   console.log('Object is visible');
      * }
      */
-    isInView(pos: Vector2): boolean;
+    isInView(pos: Vector): boolean;
     reset(): this;
     /**
      * Hashes camera config and the CameraFrame's full transform state.
@@ -1170,11 +1274,9 @@ type Edge = 'TOP' | 'BOTTOM' | 'LEFT' | 'RIGHT';
 
 /**
  * A collection of VMobjects that can be manipulated as a single unit.
- * Uses Scene Graph hierarchy: transforms on parent are inherited by children
- * via getWorldMatrix() calculation, not by mutating child matrices.
+ * Uses Mobject's submobject hierarchy and recursive geometry transforms.
  */
 declare class VGroup extends VMobject {
-    protected children: VMobject[];
     constructor(...mobjects: VMobject[]);
     get length(): number;
     add(...mobjects: VMobject[]): this;
@@ -1182,7 +1284,6 @@ declare class VGroup extends VMobject {
     clear(): this;
     getChildren(): VMobject[];
     get(index: number): VMobject | undefined;
-    pos(x: number, y: number): this;
     show(): this;
     hide(): this;
     /**
@@ -1215,11 +1316,178 @@ 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;
+    computeHash(): number;
+}
+
+declare class Arc extends VMobject {
+    readonly radius: number;
+    readonly startAngle: number;
+    readonly endAngle: number;
+    constructor(radius?: number, startAngle?: number, endAngle?: number);
+    private generatePath;
+}
+
+declare class Circle extends Arc {
+    constructor(radius?: number);
+}
+
+declare class Line extends VMobject {
+    readonly start: Vector;
+    readonly end: Vector;
+    constructor(x1?: number, y1?: number, x2?: number, y2?: number);
+    private generatePath;
+}
+
+declare class Polygon extends VMobject {
+    readonly vertices: Vector[];
+    constructor(...points: Array<[number, number]>);
+    private generatePath;
+}
+
+declare class Rectangle extends Polygon {
+    readonly width: number;
+    readonly height: number;
+    constructor(width?: number, height?: number);
+}
+
+declare class Arrow extends Line {
+    readonly tipLength: number;
+    readonly tipAngle: number;
+    constructor(x1?: number, y1?: number, x2?: number, y2?: number, tipLength?: number, tipAngle?: number);
+    private addTip;
+}
+
+/**
+ * A VMobject representing a single glyph character.
+ * Converts fontkit glyph path to BezierPath for rendering.
+ */
+declare class Glyph extends VMobject {
+    readonly character: string;
+    readonly glyphId: number;
+    constructor(fontkitGlyph: Glyph$1, character: string, scale: number, offsetX: number, offsetY: number);
+}
+
+/**
+ * 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 fontSize;
+    private fontPath;
+    constructor(text: string, fontPath?: string, options?: {
+        fontSize?: number;
+    });
+    private buildGlyphs;
+    /** 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;
+}
+
+/** Unique identifier for graph nodes. */
+type GraphNodeId = string;
+/** Configuration for creating a graph node. */
+interface NodeConfig {
+    position?: {
+        x: number;
+        y: number;
+    };
+    radius?: number;
+    strokeColor?: Color;
+    strokeWidth?: number;
+    fillColor?: Color;
+    fillOpacity?: number;
+}
+/** Configuration for creating a graph edge. */
+interface EdgeConfig {
+    strokeColor?: Color;
+    strokeWidth?: number;
+    curved?: boolean;
+}
+/** Supported layout algorithms. */
+type LayoutType = 'force-directed' | 'tree' | 'circular';
+/** Configuration for graph layout algorithms. */
+interface LayoutConfig {
+    radius?: number;
+    levelHeight?: number;
+    siblingSpacing?: number;
+    iterations?: number;
+    springLength?: number;
+    repulsion?: number;
+    attraction?: number;
+    damping?: number;
+    minDistance?: number;
+}
+
+/**
+ * A graph node represented as a circular VMobject.
+ * Supports customizable radius, stroke, and fill styling.
+ */
+declare class GraphNode extends VMobject {
+    readonly id: GraphNodeId;
+    private nodeRadius;
+    constructor(id: GraphNodeId, config?: NodeConfig);
+    get radius(): number;
     /**
-     * Recursively hashes this VGroup and all children.
-     * Any child state change invalidates segments containing this group.
+     * Generates a circular BezierPath approximation using cubic Bezier curves.
+     * Uses the standard 4-point circle approximation with control point factor ~0.5523.
      */
-    computeHash(): number;
+    private generateCirclePath;
+    getCenter(): Vector;
+}
+
+/**
+ * A graph edge represented as a BezierPath connecting two nodes.
+ * Supports straight or curved edges with customizable styling.
+ */
+declare class GraphEdge extends VMobject {
+    readonly source: GraphNodeId;
+    readonly target: GraphNodeId;
+    private sourceNode;
+    private targetNode;
+    private curved;
+    constructor(sourceNode: GraphNode, targetNode: GraphNode, config?: EdgeConfig);
+    /**
+     * Recalculates the edge path based on current node positions.
+     * Call this when nodes move to update the edge connection.
+     */
+    updatePath(): void;
+    getPath(): BezierPath | undefined;
+    /**
+     * Updates node references (used when nodes are replaced).
+     */
+    setNodes(sourceNode: GraphNode, targetNode: GraphNode): void;
+}
+
+/**
+ * A graph structure containing nodes and edges.
+ * Manages nodes as VMobjects and edges as BezierPath curves.
+ * Supports multiple layout algorithms for automatic positioning.
+ */
+declare class Graph extends VGroup {
+    private nodes;
+    private edges;
+    constructor();
+    /** Adds a node to the graph. */
+    addNode(id: GraphNodeId, config?: NodeConfig): GraphNode;
+    /** Removes a node and all connected edges from the graph. */
+    removeNode(id: GraphNodeId): this;
+    getNode(id: GraphNodeId): GraphNode | undefined;
+    getNodes(): GraphNode[];
+    addEdge(sourceId: GraphNodeId, targetId: GraphNodeId, config?: EdgeConfig): GraphEdge | undefined;
+    removeEdge(sourceId: GraphNodeId, targetId: GraphNodeId): this;
+    private removeEdgeInternal;
+    getEdgePath(sourceId: GraphNodeId, targetId: GraphNodeId): ReturnType<GraphEdge['getPath']>;
+    getEdges(): GraphEdge[];
+    /** Applies a layout algorithm to reposition all nodes. */
+    layout(type: LayoutType, config?: LayoutConfig): this;
+    updateEdges(): this;
 }
 
 /**
@@ -1367,6 +1635,7 @@ declare class KeyframeAnimation<T extends Mobject = Mobject> extends Animation<T
     interpolate(progress: number): void;
 }
 
+type FollowOffsetInput = Vector | readonly [number, number] | readonly [number, number, number];
 /**
  * Configuration options for the Follow animation.
  */
@@ -1374,9 +1643,16 @@ interface FollowConfig {
     /**
      * Offset from the target's position. The camera will track
      * (target.position + offset) instead of the exact target position.
-     * @default Vector2.ZERO
+     * Accepts:
+     * - `Vector`
+     * - `[x, y]`
+     * - `[x, y, z]`
+     *
+     * Note: camera follow movement is planar, so only x/y affect the CameraFrame position.
+     * If provided, z is accepted for API consistency but ignored by this animation.
+     * @default Vector.ZERO
      */
-    offset?: Vector2;
+    offset?: FollowOffsetInput;
     /**
      * Damping factor for smooth following (0 to 1).
      * - 0 = instant snap to target (no smoothing)
@@ -1402,7 +1678,14 @@ interface FollowConfig {
  * @example
  * // Follow with offset (camera leads the target)
  * this.play(new Follow(this.frame, car, {
- *   offset: new Vector2(2, 0),  // Camera 2 units ahead
+ *   offset: [2, 0],  // Camera 2 units ahead
+ *   damping: 0.5
+ * }).duration(10));
+ *
+ * @example
+ * // 3D tuple offset is accepted for consistency, but z is ignored by camera follow
+ * this.play(new Follow(this.frame, car, {
+ *   offset: [2, 0, 1],
  *   damping: 0.5
  * }).duration(10));
  */
@@ -1430,6 +1713,7 @@ declare class Follow extends Animation<CameraFrame> {
      * @param progress - Animation progress (0 to 1)
      */
     interpolate(progress: number): void;
+    private static normalizeOffset;
 }
 
 /**
@@ -1620,6 +1904,11 @@ interface SceneConfig {
     readonly frameRate?: number;
 }
 
+/** Protocol for objects that contribute to segment hashing. */
+interface Hashable {
+    computeHash(): number;
+}
+
 /**
  * A Segment represents one independent rendering unit,
  * corresponding to a single play() or wait() call.
@@ -1640,6 +1929,30 @@ interface Segment {
     readonly hash: 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>;
+}
+
 /**
  * Scene is the core container that manages Mobjects and coordinates animations.
  * It provides both a simple API for playing animations and access to the
@@ -1650,6 +1963,7 @@ declare class Scene {
     private readonly mobjects;
     private readonly timeline;
     private readonly _camera;
+    private readonly updaterEngine;
     private readonly segmentList;
     private playheadTime;
     constructor(config?: SceneConfig);
@@ -1718,6 +2032,18 @@ declare class Scene {
      * Get the total duration of all scheduled animations.
      */
     getTotalDuration(): number;
+    /**
+     * Evaluates scene state at an absolute time.
+     * Execution order is deterministic:
+     * 1) timeline animations
+     * 2) mobject updaters
+     */
+    evaluateFrame(time: number): void;
+    /**
+     * Returns true if any scene mobject (or camera frame) has active updaters.
+     * Used by renderer to disable unsafe segment caching.
+     */
+    hasActiveUpdaters(): boolean;
     /**
      * Get the underlying Timeline for advanced control.
      * Use this for direct manipulation of animation timing.
@@ -1755,177 +2081,6 @@ declare class Scene {
     private computeSegmentHash;
 }
 
-declare class Arc extends VMobject {
-    readonly radius: number;
-    readonly startAngle: number;
-    readonly endAngle: number;
-    constructor(radius?: number, startAngle?: number, endAngle?: number);
-    private generatePath;
-}
-
-declare class Line extends VMobject {
-    readonly start: Vector2;
-    readonly end: Vector2;
-    constructor(x1?: number, y1?: number, x2?: number, y2?: number);
-    private generatePath;
-}
-
-declare class Arrow extends Line {
-    readonly tipLength: number;
-    readonly tipAngle: number;
-    constructor(x1?: number, y1?: number, x2?: number, y2?: number, tipLength?: number, tipAngle?: number);
-    private addTip;
-}
-
-declare class Circle extends Arc {
-    constructor(radius?: number);
-}
-
-declare class Polygon extends VMobject {
-    readonly vertices: Vector2[];
-    constructor(...points: Array<[number, number]>);
-    private generatePath;
-}
-
-declare class Rectangle extends Polygon {
-    readonly width: number;
-    readonly height: number;
-    constructor(width?: number, height?: number);
-}
-
-/**
- * A VMobject representing a single glyph character.
- * Converts fontkit glyph path to BezierPath for rendering.
- */
-declare class Glyph extends VMobject {
-    readonly character: string;
-    readonly glyphId: number;
-    constructor(fontkitGlyph: Glyph$1, character: string, scale: number, offsetX: number, offsetY: number);
-}
-
-/**
- * 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 fontSize;
-    private fontPath;
-    constructor(text: string, fontPath?: string, options?: {
-        fontSize?: number;
-    });
-    private buildGlyphs;
-    /** 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;
-}
-
-/** Unique identifier for graph nodes. */
-type GraphNodeId = string;
-/** Configuration for creating a graph node. */
-interface NodeConfig {
-    position?: {
-        x: number;
-        y: number;
-    };
-    radius?: number;
-    strokeColor?: Color;
-    strokeWidth?: number;
-    fillColor?: Color;
-    fillOpacity?: number;
-}
-/** Configuration for creating a graph edge. */
-interface EdgeConfig {
-    strokeColor?: Color;
-    strokeWidth?: number;
-    curved?: boolean;
-}
-/** Supported layout algorithms. */
-type LayoutType = 'force-directed' | 'tree' | 'circular';
-/** Configuration for graph layout algorithms. */
-interface LayoutConfig {
-    radius?: number;
-    levelHeight?: number;
-    siblingSpacing?: number;
-    iterations?: number;
-    springLength?: number;
-    repulsion?: number;
-    attraction?: number;
-    damping?: number;
-    minDistance?: number;
-}
-
-/**
- * A graph node represented as a circular VMobject.
- * Supports customizable radius, stroke, and fill styling.
- */
-declare class GraphNode extends VMobject {
-    readonly id: GraphNodeId;
-    private nodeRadius;
-    constructor(id: GraphNodeId, config?: NodeConfig);
-    get radius(): number;
-    /**
-     * Generates a circular BezierPath approximation using cubic Bezier curves.
-     * Uses the standard 4-point circle approximation with control point factor ~0.5523.
-     */
-    private generateCirclePath;
-    getCenter(): Vector2;
-}
-
-/**
- * A graph edge represented as a BezierPath connecting two nodes.
- * Supports straight or curved edges with customizable styling.
- */
-declare class GraphEdge extends VMobject {
-    readonly source: GraphNodeId;
-    readonly target: GraphNodeId;
-    private sourceNode;
-    private targetNode;
-    private curved;
-    constructor(sourceNode: GraphNode, targetNode: GraphNode, config?: EdgeConfig);
-    /**
-     * Recalculates the edge path based on current node positions.
-     * Call this when nodes move to update the edge connection.
-     */
-    updatePath(): void;
-    getPath(): BezierPath | undefined;
-    /**
-     * Updates node references (used when nodes are replaced).
-     */
-    setNodes(sourceNode: GraphNode, targetNode: GraphNode): void;
-}
-
-/**
- * A graph structure containing nodes and edges.
- * Manages nodes as VMobjects and edges as BezierPath curves.
- * Supports multiple layout algorithms for automatic positioning.
- */
-declare class Graph extends VGroup {
-    private nodes;
-    private edges;
-    constructor();
-    /** Adds a node to the graph. */
-    addNode(id: GraphNodeId, config?: NodeConfig): GraphNode;
-    /** Removes a node and all connected edges from the graph. */
-    removeNode(id: GraphNodeId): this;
-    getNode(id: GraphNodeId): GraphNode | undefined;
-    getNodes(): GraphNode[];
-    addEdge(sourceId: GraphNodeId, targetId: GraphNodeId, config?: EdgeConfig): GraphEdge | undefined;
-    removeEdge(sourceId: GraphNodeId, targetId: GraphNodeId): this;
-    private removeEdgeInternal;
-    getEdgePath(sourceId: GraphNodeId, targetId: GraphNodeId): ReturnType<GraphEdge['getPath']>;
-    getEdges(): GraphEdge[];
-    /** Applies a layout algorithm to reposition all nodes. */
-    layout(type: LayoutType, config?: LayoutConfig): this;
-    updateEdges(): this;
-}
-
 /**
  * Supported render output formats.
  * - sprite: PNG sequence (frame_0000.png, frame_0001.png, ...)
@@ -2061,4 +2216,59 @@ declare class Renderer {
     private renderSegmentToFile;
 }
 
-export { Animation, type AnimationConfig, Arc, Arrow, Camera, type CameraConfig, CameraFrame, Circle, Color, Draw, type EasingFunction, type EdgeConfig, FadeIn, FadeOut, Follow, Glyph, Graph, GraphEdge, GraphNode, type GraphNodeId, type Keyframe, KeyframeAnimation, KeyframeTrack, type LayoutConfig, type LayoutType, Line, Mobject, MorphTo, MoveTo, type NodeConfig, Parallel, Polygon, type ProgressCallback, Rectangle, type RenderConfig, type RenderFormat, type RenderProgress, type RenderQuality, Renderer, Resolution, type ResolvedCameraConfig, Rotate, Scale, Scene, type SceneConfig, type ScheduledAnimation, 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 };
+/**
+ * Renders individual frames from a Scene.
+ * Responsible for drawing mobjects to a canvas at a specific point in time.
+ */
+declare class FrameRenderer {
+    private readonly scene;
+    private readonly width;
+    private readonly height;
+    constructor(scene: Scene, width: number, height: number);
+    /**
+     * Calculates the matrix that transforms Manim world coordinates to screen pixels.
+     *
+     * Manim coordinate system:
+     * - Origin at center of screen
+     * - Y-axis points up
+     * - frameHeight = 8.0 units
+     *
+     * Screen coordinate system:
+     * - Origin at top-left
+     * - Y-axis points down
+     * - Width x Height pixels
+     */
+    private calculateWorldToScreenMatrix;
+    /**
+     * Renders a single frame at the specified time.
+     */
+    renderFrame(time: number): Canvas;
+    /**
+     * Gets the canvas dimensions.
+     */
+    getDimensions(): {
+        width: number;
+        height: number;
+    };
+}
+
+/**
+ * Tracks rendering progress and reports updates via callback.
+ */
+declare class ProgressReporter {
+    private readonly totalFrames;
+    private readonly onProgress?;
+    private readonly startTime;
+    private currentFrame;
+    constructor(totalFrames: number, onProgress?: ProgressCallback);
+    /**
+     * Report progress for the current frame.
+     */
+    reportFrame(frameIndex: number): void;
+    /**
+     * Report rendering complete.
+     */
+    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 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, type UpdaterContext, type UpdaterFunction, type UpdaterHandle, type UpdaterOptions, VGroup, VMobject, Vector, 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 };