@redwilly/anima 0.1.25 → 0.1.26

package/dist/index.js

@@ -1,32 +1,32 @@
-// src/core/math/Vector2/Vector2.ts
-var Vector2 = class _Vector2 {
+// src/core/math/vector/Vector.ts
+var Vector = class _Vector {
   x;
   y;
-  constructor(x, y) {
+  z;
+  constructor(x, y, z = 0) {
     this.x = x;
     this.y = y;
+    this.z = z;
   }
   add(other) {
-    return new _Vector2(this.x + other.x, this.y + other.y);
+    return new _Vector(this.x + other.x, this.y + other.y, this.z + other.z);
   }
   subtract(other) {
-    return new _Vector2(this.x - other.x, this.y - other.y);
+    return new _Vector(this.x - other.x, this.y - other.y, this.z - other.z);
   }
   multiply(scalar) {
-    return new _Vector2(this.x * scalar, this.y * scalar);
+    return new _Vector(this.x * scalar, this.y * scalar, this.z * scalar);
   }
   dot(other) {
-    return this.x * other.x + this.y * other.y;
+    return this.x * other.x + this.y * other.y + this.z * other.z;
   }
-  /** Magnitude (length) of the vector. */
   length() {
-    return Math.sqrt(this.x * this.x + this.y * this.y);
+    return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
   }
-  /** Returns a normalized unit vector. Returns ZERO for zero-length vectors. */
   normalize() {
     const len = this.length();
     if (len === 0) {
-      return _Vector2.ZERO;
+      return _Vector.ZERO;
     }
     return this.multiply(1 / len);
   }
@@ -34,164 +34,232 @@ var Vector2 = class _Vector2 {
     return this.multiply(1 - t).add(other.multiply(t));
   }
   equals(other, tolerance = 1e-6) {
-    return Math.abs(this.x - other.x) < tolerance && Math.abs(this.y - other.y) < tolerance;
+    return Math.abs(this.x - other.x) < tolerance && Math.abs(this.y - other.y) < tolerance && Math.abs(this.z - other.z) < tolerance;
   }
-  static ZERO = new _Vector2(0, 0);
-  static UP = new _Vector2(0, -1);
-  static DOWN = new _Vector2(0, 1);
-  static LEFT = new _Vector2(-1, 0);
-  static RIGHT = new _Vector2(1, 0);
+  toPlanar() {
+    return new _Vector(this.x, this.y, 0);
+  }
+  static fromPlanar(v, z = 0) {
+    return new _Vector(v.x, v.y, z);
+  }
+  static ZERO = new _Vector(0, 0, 0);
+  static UP = new _Vector(0, -1, 0);
+  static DOWN = new _Vector(0, 1, 0);
+  static LEFT = new _Vector(-1, 0, 0);
+  static RIGHT = new _Vector(1, 0, 0);
 };
 
-// src/core/math/matrix/factories.ts
-function createIdentity() {
-  return new Float32Array([
-    1,
-    0,
-    0,
-    0,
-    1,
-    0,
-    0,
-    0,
-    1
-  ]);
-}
-function createTranslation(tx, ty) {
-  return new Float32Array([
-    1,
-    0,
-    tx,
-    0,
-    1,
-    ty,
-    0,
-    0,
-    1
-  ]);
-}
-function createRotation(angle) {
-  const c = Math.cos(angle);
-  const s = Math.sin(angle);
-  return new Float32Array([
-    c,
-    -s,
-    0,
-    s,
-    c,
-    0,
-    0,
-    0,
-    1
-  ]);
-}
-function createScale(sx, sy) {
-  return new Float32Array([
-    sx,
-    0,
-    0,
-    0,
-    sy,
-    0,
-    0,
-    0,
-    1
-  ]);
-}
-function createShear(shx, shy) {
-  return new Float32Array([
-    1,
-    shx,
-    0,
-    shy,
-    1,
-    0,
-    0,
-    0,
-    1
-  ]);
-}
-
-// src/core/math/matrix/Matrix3x3.ts
-var Matrix3x3 = class _Matrix3x3 {
+// src/core/math/matrix/Matrix4x4.ts
+var Matrix4x4 = class _Matrix4x4 {
   values;
   constructor(values) {
-    if (values.length !== 9) {
-      throw new Error("Matrix3x3 requires 9 values");
+    if (values.length !== 16) {
+      throw new Error("Matrix4x4 requires 16 values");
     }
     this.values = new Float32Array(values);
   }
   multiply(other) {
     const a = this.values;
     const b = other.values;
-    const out = new Float32Array(9);
-    const a00 = a[0], a01 = a[1], a02 = a[2];
-    const a10 = a[3], a11 = a[4], a12 = a[5];
-    const a20 = a[6], a21 = a[7], a22 = a[8];
-    const b00 = b[0], b01 = b[1], b02 = b[2];
-    const b10 = b[3], b11 = b[4], b12 = b[5];
-    const b20 = b[6], b21 = b[7], b22 = b[8];
-    out[0] = a00 * b00 + a01 * b10 + a02 * b20;
-    out[1] = a00 * b01 + a01 * b11 + a02 * b21;
-    out[2] = a00 * b02 + a01 * b12 + a02 * b22;
-    out[3] = a10 * b00 + a11 * b10 + a12 * b20;
-    out[4] = a10 * b01 + a11 * b11 + a12 * b21;
-    out[5] = a10 * b02 + a11 * b12 + a12 * b22;
-    out[6] = a20 * b00 + a21 * b10 + a22 * b20;
-    out[7] = a20 * b01 + a21 * b11 + a22 * b21;
-    out[8] = a20 * b02 + a21 * b12 + a22 * b22;
-    return new _Matrix3x3(out);
-  }
-  /** Transforms a Vector2 point (assumes z=1). */
+    const out = new Float32Array(16);
+    for (let row = 0; row < 4; row++) {
+      for (let col = 0; col < 4; col++) {
+        let sum = 0;
+        for (let k = 0; k < 4; k++) {
+          sum += a[row * 4 + k] * b[k * 4 + col];
+        }
+        out[row * 4 + col] = sum;
+      }
+    }
+    return new _Matrix4x4(out);
+  }
   transformPoint(point) {
     const m = this.values;
     const x = point.x;
     const y = point.y;
-    const m00 = m[0], m01 = m[1], m02 = m[2];
-    const m10 = m[3], m11 = m[4], m12 = m[5];
-    const tx = m00 * x + m01 * y + m02;
-    const ty = m10 * x + m11 * y + m12;
-    return new Vector2(tx, ty);
+    const z = point.z;
+    const tx = m[0] * x + m[1] * y + m[2] * z + m[3];
+    const ty = m[4] * x + m[5] * y + m[6] * z + m[7];
+    const tz = m[8] * x + m[9] * y + m[10] * z + m[11];
+    const tw = m[12] * x + m[13] * y + m[14] * z + m[15];
+    if (Math.abs(tw) < 1e-10 || Math.abs(tw - 1) < 1e-10) {
+      return new Vector(tx, ty, tz);
+    }
+    return new Vector(tx / tw, ty / tw, tz / tw);
+  }
+  transformPoint2D(point) {
+    const transformed = this.transformPoint(Vector.fromPlanar(point, 0));
+    return transformed.toPlanar();
   }
-  /** @throws Error if the matrix is not invertible. */
   inverse() {
     const m = this.values;
-    const m00 = m[0], m01 = m[1], m02 = m[2];
-    const m10 = m[3], m11 = m[4], m12 = m[5];
-    const m20 = m[6], m21 = m[7], m22 = m[8];
-    const det = m00 * (m11 * m22 - m12 * m21) - m01 * (m10 * m22 - m12 * m20) + m02 * (m10 * m21 - m11 * m20);
+    const out = new Float32Array(16);
+    const m00 = m[0], m01 = m[1], m02 = m[2], m03 = m[3];
+    const m10 = m[4], m11 = m[5], m12 = m[6], m13 = m[7];
+    const m20 = m[8], m21 = m[9], m22 = m[10], m23 = m[11];
+    const m30 = m[12], m31 = m[13], m32 = m[14], m33 = m[15];
+    const b00 = m00 * m11 - m01 * m10;
+    const b01 = m00 * m12 - m02 * m10;
+    const b02 = m00 * m13 - m03 * m10;
+    const b03 = m01 * m12 - m02 * m11;
+    const b04 = m01 * m13 - m03 * m11;
+    const b05 = m02 * m13 - m03 * m12;
+    const b06 = m20 * m31 - m21 * m30;
+    const b07 = m20 * m32 - m22 * m30;
+    const b08 = m20 * m33 - m23 * m30;
+    const b09 = m21 * m32 - m22 * m31;
+    const b10 = m21 * m33 - m23 * m31;
+    const b11 = m22 * m33 - m23 * m32;
+    const det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
     if (Math.abs(det) < 1e-10) {
       throw new Error("Matrix is not invertible");
     }
     const invDet = 1 / det;
-    const out = new Float32Array(9);
-    out[0] = (m11 * m22 - m12 * m21) * invDet;
-    out[1] = (m02 * m21 - m01 * m22) * invDet;
-    out[2] = (m01 * m12 - m02 * m11) * invDet;
-    out[3] = (m12 * m20 - m10 * m22) * invDet;
-    out[4] = (m00 * m22 - m02 * m20) * invDet;
-    out[5] = (m02 * m10 - m00 * m12) * invDet;
-    out[6] = (m10 * m21 - m11 * m20) * invDet;
-    out[7] = (m01 * m20 - m00 * m21) * invDet;
-    out[8] = (m00 * m11 - m01 * m10) * invDet;
-    return new _Matrix3x3(out);
+    out[0] = (m11 * b11 - m12 * b10 + m13 * b09) * invDet;
+    out[1] = (m02 * b10 - m01 * b11 - m03 * b09) * invDet;
+    out[2] = (m31 * b05 - m32 * b04 + m33 * b03) * invDet;
+    out[3] = (m22 * b04 - m21 * b05 - m23 * b03) * invDet;
+    out[4] = (m12 * b08 - m10 * b11 - m13 * b07) * invDet;
+    out[5] = (m00 * b11 - m02 * b08 + m03 * b07) * invDet;
+    out[6] = (m32 * b02 - m30 * b05 - m33 * b01) * invDet;
+    out[7] = (m20 * b05 - m22 * b02 + m23 * b01) * invDet;
+    out[8] = (m10 * b10 - m11 * b08 + m13 * b06) * invDet;
+    out[9] = (m01 * b08 - m00 * b10 - m03 * b06) * invDet;
+    out[10] = (m30 * b04 - m31 * b02 + m33 * b00) * invDet;
+    out[11] = (m21 * b02 - m20 * b04 - m23 * b00) * invDet;
+    out[12] = (m11 * b07 - m10 * b09 - m12 * b06) * invDet;
+    out[13] = (m00 * b09 - m01 * b07 + m02 * b06) * invDet;
+    out[14] = (m31 * b01 - m30 * b03 - m32 * b00) * invDet;
+    out[15] = (m20 * b03 - m21 * b01 + m22 * b00) * invDet;
+    return new _Matrix4x4(out);
   }
   static identity() {
-    return _Matrix3x3.IDENTITY;
+    return _Matrix4x4.IDENTITY;
+  }
+  static translation(tx, ty, tz = 0) {
+    return new _Matrix4x4([
+      1,
+      0,
+      0,
+      tx,
+      0,
+      1,
+      0,
+      ty,
+      0,
+      0,
+      1,
+      tz,
+      0,
+      0,
+      0,
+      1
+    ]);
   }
-  static translation(tx, ty) {
-    return new _Matrix3x3(createTranslation(tx, ty));
+  static rotationX(angle) {
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    return new _Matrix4x4([
+      1,
+      0,
+      0,
+      0,
+      0,
+      c,
+      -s,
+      0,
+      0,
+      s,
+      c,
+      0,
+      0,
+      0,
+      0,
+      1
+    ]);
   }
-  static rotation(angle) {
-    return new _Matrix3x3(createRotation(angle));
+  static rotationY(angle) {
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    return new _Matrix4x4([
+      c,
+      0,
+      s,
+      0,
+      0,
+      1,
+      0,
+      0,
+      -s,
+      0,
+      c,
+      0,
+      0,
+      0,
+      0,
+      1
+    ]);
   }
-  static scale(sx, sy) {
-    return new _Matrix3x3(createScale(sx, sy));
+  static rotationZ(angle) {
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    return new _Matrix4x4([
+      c,
+      -s,
+      0,
+      0,
+      s,
+      c,
+      0,
+      0,
+      0,
+      0,
+      1,
+      0,
+      0,
+      0,
+      0,
+      1
+    ]);
   }
-  static shear(shx, shy) {
-    return new _Matrix3x3(createShear(shx, shy));
+  static scale(sx, sy, sz = 1) {
+    return new _Matrix4x4([
+      sx,
+      0,
+      0,
+      0,
+      0,
+      sy,
+      0,
+      0,
+      0,
+      0,
+      sz,
+      0,
+      0,
+      0,
+      0,
+      1
+    ]);
   }
-  static IDENTITY = new _Matrix3x3(createIdentity());
+  static IDENTITY = new _Matrix4x4([
+    1,
+    0,
+    0,
+    0,
+    0,
+    1,
+    0,
+    0,
+    0,
+    0,
+    1,
+    0,
+    0,
+    0,
+    0,
+    1
+  ]);
 };
 
 // src/core/math/color/conversions.ts
@@ -383,8 +451,8 @@ function getCubicLength(p0, p1, p2, p3) {
 // src/core/math/bezier/sampling.ts
 function getPathLength(commands) {
   let length = 0;
-  let cursor = new Vector2(0, 0);
-  let subpathStart = new Vector2(0, 0);
+  let cursor = new Vector(0, 0);
+  let subpathStart = new Vector(0, 0);
   for (const cmd of commands) {
     switch (cmd.type) {
       case "Move":
@@ -417,12 +485,12 @@ function getPathLength(commands) {
 }
 function getTangentAtPath(commands, t) {
   const totalLength = getPathLength(commands);
-  if (totalLength === 0) return Vector2.RIGHT;
+  if (totalLength === 0) return Vector.RIGHT;
   t = Math.max(0, Math.min(1, t));
   const targetDistance = t * totalLength;
   let currentDistance = 0;
-  let cursor = new Vector2(0, 0);
-  let subpathStart = new Vector2(0, 0);
+  let cursor = new Vector(0, 0);
+  let subpathStart = new Vector(0, 0);
   for (const cmd of commands) {
     let segmentLength = 0;
     switch (cmd.type) {
@@ -473,14 +541,14 @@ function getTangentAtPath(commands, t) {
     }
     currentDistance += segmentLength;
   }
-  return Vector2.RIGHT;
+  return Vector.RIGHT;
 }
 
 // src/core/math/bezier/morphing.ts
 function toCubicCommands(commands) {
   const result = [];
-  let cursor = new Vector2(0, 0);
-  let subpathStart = new Vector2(0, 0);
+  let cursor = new Vector(0, 0);
+  let subpathStart = new Vector(0, 0);
   for (const cmd of commands) {
     switch (cmd.type) {
       case "Move":
@@ -573,7 +641,7 @@ function subdividePath(commands, targetCount) {
       return currentCommands;
     }
     let splitsPerformed = 0;
-    let cursor = new Vector2(0, 0);
+    let cursor = new Vector(0, 0);
     for (let i = 0; i < currentCommands.length; i++) {
       const cmd = currentCommands[i];
       if (cmd.type === "Move") {
@@ -610,8 +678,8 @@ function subdividePath(commands, targetCount) {
 // src/core/math/bezier/BezierPath.ts
 var BezierPath = class _BezierPath {
   commands = [];
-  currentPoint = Vector2.ZERO;
-  startPoint = Vector2.ZERO;
+  currentPoint = Vector.ZERO;
+  startPoint = Vector.ZERO;
   // Caching for O(1) length and O(log N) point sampling
   cachedLength = null;
   segmentLengths = [];
@@ -628,8 +696,8 @@ var BezierPath = class _BezierPath {
     this.segmentLengths = [];
     this.segmentCDF = [];
     let totalLength = 0;
-    let cursor = Vector2.ZERO;
-    let subpathStart = Vector2.ZERO;
+    let cursor = Vector.ZERO;
+    let subpathStart = Vector.ZERO;
     for (const cmd of this.commands) {
       let segmentLength = 0;
       switch (cmd.type) {
@@ -708,7 +776,7 @@ var BezierPath = class _BezierPath {
     this.ensureCache();
     const totalLength = this.cachedLength;
     if (totalLength === 0 || this.commands.length === 0) {
-      return this.commands.length > 0 ? this.commands[this.commands.length - 1].end : Vector2.ZERO;
+      return this.commands.length > 0 ? this.commands[this.commands.length - 1].end : Vector.ZERO;
     }
     t = Math.max(0, Math.min(1, t));
     const targetDistance = t * totalLength;
@@ -724,9 +792,9 @@ var BezierPath = class _BezierPath {
     }
     const segmentIndex = low;
     const cmd = this.commands[segmentIndex];
-    if (!cmd) return Vector2.ZERO;
-    let cursor = Vector2.ZERO;
-    let subpathStart = Vector2.ZERO;
+    if (!cmd) return Vector.ZERO;
+    let cursor = Vector.ZERO;
+    let subpathStart = Vector.ZERO;
     for (let i = 0; i < segmentIndex; i++) {
       const c = this.commands[i];
       if (c.type === "Move") {
@@ -1233,13 +1301,13 @@ var FadeOut = class extends ExitAnimation {
 var MoveTo = class extends TransformativeAnimation {
   startPosition;
   endPosition;
-  constructor(target, xOrDestination, y) {
+  constructor(target, xOrDestination, y, z) {
     super(target);
-    if (xOrDestination instanceof Vector2) {
+    if (typeof xOrDestination !== "number") {
       this.endPosition = xOrDestination;
-    } else {
-      this.endPosition = new Vector2(xOrDestination, y ?? 0);
+      return;
     }
+    this.endPosition = new Vector(xOrDestination, y ?? 0, z ?? 0);
   }
   captureStartState() {
     this.startPosition = this.target.position;
@@ -1247,7 +1315,7 @@ var MoveTo = class extends TransformativeAnimation {
   interpolate(progress) {
     this.ensureInitialized();
     const newPosition = this.startPosition.lerp(this.endPosition, progress);
-    this.target.pos(newPosition.x, newPosition.y);
+    this.target.pos(newPosition.x, newPosition.y, newPosition.z);
   }
   /** Returns the target position of the move animation. */
   getDestination() {
@@ -1287,7 +1355,7 @@ var Scale = class extends TransformativeAnimation {
     super(target);
     const endX = factorX;
     const endY = factorY ?? factorX;
-    this.endScale = new Vector2(endX, endY);
+    this.endScale = new Vector(endX, endY);
   }
   captureStartState() {
     this.startScale = this.target.scale;
@@ -1349,8 +1417,8 @@ function getPartialPath(path, t) {
   const commands = path.getCommands();
   const result = new BezierPath();
   let accumulatedLength = 0;
-  let cursor = Vector2.ZERO;
-  let subpathStart = Vector2.ZERO;
+  let cursor = Vector.ZERO;
+  let subpathStart = Vector.ZERO;
   for (const cmd of commands) {
     const segmentLength = getSegmentLength(cmd, cursor, subpathStart);
     const newAccumulated = accumulatedLength + segmentLength;
@@ -1837,13 +1905,16 @@ function createFadeIn(target, durationSeconds) {
 function createFadeOut(target, durationSeconds) {
   return withDuration(new FadeOut(target), durationSeconds);
 }
-function createMoveTo(target, x, y, durationSeconds) {
-  return withDuration(new MoveTo(target, x, y), durationSeconds);
+function createMoveTo(target, xOrDestination, yOrDuration, durationSeconds) {
+  if (typeof xOrDestination !== "number") {
+    return withDuration(new MoveTo(target, xOrDestination), yOrDuration);
+  }
+  return withDuration(new MoveTo(target, xOrDestination, yOrDuration ?? 0), durationSeconds);
 }
 function createRotate(target, angle, durationSeconds) {
   return withDuration(new Rotate(target, angle), durationSeconds);
 }
-function createScale2(target, factorX, factorY = factorX, durationSeconds) {
+function createScale(target, factorX, factorY = factorX, durationSeconds) {
   return withDuration(new Scale(target, factorX, factorY), durationSeconds);
 }
 function createParallel(animations) {
@@ -1974,10 +2045,18 @@ var Mobject = class {
   localMatrix;
   opacityValue;
   animQueue = null;
+  pointCloud = [];
+  submobjects = [];
   savedStates = [];
+  logicalRotation = 0;
+  logicalScale = new Vector(1, 1);
+  updaters = [];
+  nextUpdaterId = 1;
+  nextUpdaterOrder = 0;
+  updatersEnabled = true;
   parent = null;
   constructor() {
-    this.localMatrix = Matrix3x3.identity();
+    this.localMatrix = Matrix4x4.identity();
     this.opacityValue = 0;
   }
   getQueue() {
@@ -1991,34 +2070,78 @@ var Mobject = class {
     return this.localMatrix;
   }
   getWorldMatrix() {
+    if (this.usesGeometryTransforms()) {
+      return this.localMatrix;
+    }
     if (this.parent === null) {
       return this.localMatrix;
     }
     return this.parent.getWorldMatrix().multiply(this.localMatrix);
   }
+  /**
+   * 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() {
+    if (this.usesGeometryTransforms()) {
+      if (this.parent === null) {
+        return Matrix4x4.identity();
+      }
+      return this.parent.getRenderMatrix();
+    }
+    if (this.parent === null) {
+      return this.localMatrix;
+    }
+    return this.parent.getRenderMatrix().multiply(this.localMatrix);
+  }
   get position() {
+    if (this.usesGeometryTransforms()) {
+      const center = this.getGeometryCenter();
+      if (center) {
+        return center;
+      }
+    }
     const m = this.localMatrix.values;
-    return new Vector2(m[2], m[5]);
+    return new Vector(m[3], m[7], m[11]);
   }
   get rotation() {
+    if (this.usesGeometryTransforms()) {
+      return this.logicalRotation;
+    }
     const m = this.localMatrix.values;
-    return Math.atan2(m[3], m[0]);
+    return Math.atan2(m[4], m[0]);
   }
   get scale() {
+    if (this.usesGeometryTransforms()) {
+      return this.logicalScale;
+    }
     const m = this.localMatrix.values;
-    const sx = Math.sqrt(m[0] * m[0] + m[3] * m[3]);
-    const sy = Math.sqrt(m[1] * m[1] + m[4] * m[4]);
-    return new Vector2(sx, sy);
+    const sx = Math.sqrt(m[0] * m[0] + m[4] * m[4]);
+    const sy = Math.sqrt(m[1] * m[1] + m[5] * m[5]);
+    return new Vector(sx, sy);
   }
   get opacity() {
     return this.opacityValue;
   }
   // ========== Immediate State Setters ==========
-  pos(x, y) {
+  pos(x, y, z) {
+    const targetZ = z ?? this.position.z;
+    if (this.usesGeometryTransforms()) {
+      const current = this.position;
+      const dx = x - current.x;
+      const dy = y - current.y;
+      const dz = targetZ - current.z;
+      if (Math.abs(dx) > 1e-12 || Math.abs(dy) > 1e-12 || Math.abs(dz) > 1e-12) {
+        this.applyMatrix(Matrix4x4.translation(dx, dy, dz));
+      }
+      return this;
+    }
     const newValues = new Float32Array(this.localMatrix.values);
-    newValues[2] = x;
-    newValues[5] = y;
-    this.localMatrix = new Matrix3x3(newValues);
+    newValues[3] = x;
+    newValues[7] = y;
+    newValues[11] = targetZ;
+    this.setLocalMatrix(new Matrix4x4(newValues));
     return this;
   }
   show() {
@@ -2034,52 +2157,227 @@ var Mobject = class {
     return this;
   }
   setRotation(angle) {
+    if (this.usesGeometryTransforms()) {
+      const delta = angle - this.logicalRotation;
+      if (Math.abs(delta) < 1e-12) {
+        return this;
+      }
+      const pivot = this.position;
+      const transform = Matrix4x4.translation(pivot.x, pivot.y, pivot.z).multiply(Matrix4x4.rotationZ(delta)).multiply(Matrix4x4.translation(-pivot.x, -pivot.y, -pivot.z));
+      this.applyMatrix(transform);
+      this.logicalRotation = angle;
+      this.syncLocalMatrixFromGeometry();
+      return this;
+    }
     const m = this.localMatrix.values;
-    const posX = m[2];
-    const posY = m[5];
+    const posX = m[3];
+    const posY = m[7];
+    const posZ = m[11];
     const currentScale = this.scale;
     const cos = Math.cos(angle);
     const sin = Math.sin(angle);
-    const newValues = new Float32Array(9);
+    const newValues = new Float32Array(16);
     newValues[0] = cos * currentScale.x;
     newValues[1] = -sin * currentScale.y;
-    newValues[2] = posX;
-    newValues[3] = sin * currentScale.x;
-    newValues[4] = cos * currentScale.y;
-    newValues[5] = posY;
-    newValues[8] = 1;
-    this.localMatrix = new Matrix3x3(newValues);
+    newValues[3] = posX;
+    newValues[4] = sin * currentScale.x;
+    newValues[5] = cos * currentScale.y;
+    newValues[7] = posY;
+    newValues[10] = 1;
+    newValues[11] = posZ;
+    newValues[15] = 1;
+    this.setLocalMatrix(new Matrix4x4(newValues));
     return this;
   }
   setScale(sx, sy) {
+    if (this.usesGeometryTransforms()) {
+      const current = this.logicalScale;
+      const deltaX = current.x === 0 ? sx : sx / current.x;
+      const deltaY = current.y === 0 ? sy : sy / current.y;
+      if (Math.abs(deltaX - 1) < 1e-12 && Math.abs(deltaY - 1) < 1e-12) {
+        return this;
+      }
+      const pivot = this.position;
+      const transform = Matrix4x4.translation(pivot.x, pivot.y, pivot.z).multiply(Matrix4x4.scale(deltaX, deltaY, 1)).multiply(Matrix4x4.translation(-pivot.x, -pivot.y, -pivot.z));
+      this.applyMatrix(transform);
+      this.logicalScale = new Vector(sx, sy);
+      this.syncLocalMatrixFromGeometry();
+      return this;
+    }
     const m = this.localMatrix.values;
-    const posX = m[2];
-    const posY = m[5];
+    const posX = m[3];
+    const posY = m[7];
+    const posZ = m[11];
     const currentRotation = this.rotation;
     const cos = Math.cos(currentRotation);
     const sin = Math.sin(currentRotation);
-    const newValues = new Float32Array(9);
+    const newValues = new Float32Array(16);
     newValues[0] = cos * sx;
     newValues[1] = -sin * sy;
-    newValues[2] = posX;
-    newValues[3] = sin * sx;
-    newValues[4] = cos * sy;
-    newValues[5] = posY;
-    newValues[8] = 1;
-    this.localMatrix = new Matrix3x3(newValues);
+    newValues[3] = posX;
+    newValues[4] = sin * sx;
+    newValues[5] = cos * sy;
+    newValues[7] = posY;
+    newValues[10] = 1;
+    newValues[11] = posZ;
+    newValues[15] = 1;
+    this.setLocalMatrix(new Matrix4x4(newValues));
     return this;
   }
   applyMatrix(m) {
-    this.localMatrix = m.multiply(this.localMatrix);
+    if (this.usesGeometryTransforms()) {
+      this.applyMatrixToOwnGeometry(m);
+      for (const child of this.submobjects) {
+        child.applyMatrix(m);
+      }
+      this.updateLogicalStateFromMatrix(m);
+      this.syncLocalMatrixFromGeometry();
+      return this;
+    }
+    this.setLocalMatrix(m.multiply(this.localMatrix));
+    return this;
+  }
+  // ========== Scene Graph / Geometry Primitives ==========
+  addSubmobjects(...mobjects) {
+    for (const mob of mobjects) {
+      if (mob === this) continue;
+      if (this.submobjects.includes(mob)) continue;
+      if (mob.parent) {
+        mob.parent.removeSubmobject(mob);
+      }
+      mob.parent = this;
+      this.submobjects.push(mob);
+    }
+    this.syncLocalMatrixFromGeometry();
+    return this;
+  }
+  removeSubmobject(mobject) {
+    const index = this.submobjects.indexOf(mobject);
+    if (index >= 0) {
+      this.submobjects.splice(index, 1);
+      mobject.parent = null;
+    }
+    this.syncLocalMatrixFromGeometry();
+    return this;
+  }
+  clearSubmobjects() {
+    for (const child of this.submobjects) {
+      child.parent = null;
+    }
+    this.submobjects = [];
+    this.syncLocalMatrixFromGeometry();
+    return this;
+  }
+  getSubmobjects() {
+    return [...this.submobjects];
+  }
+  // ========== Updaters ==========
+  addUpdater(fn, options = {}) {
+    if (typeof fn !== "function") {
+      throw new Error("addUpdater() requires a function");
+    }
+    const priority = options.priority ?? 0;
+    if (!Number.isFinite(priority)) {
+      throw new Error("Updater priority must be a finite number");
+    }
+    const record = {
+      id: this.nextUpdaterId++,
+      order: this.nextUpdaterOrder++,
+      name: options.name,
+      fn,
+      priority,
+      enabled: options.enabled ?? true
+    };
+    this.updaters.push(record);
+    return { id: record.id };
+  }
+  removeUpdater(handleOrFn) {
+    if (typeof handleOrFn === "function") {
+      const fn = handleOrFn;
+      this.updaters = this.updaters.filter((u) => u.fn !== fn);
+      return this;
+    }
+    this.updaters = this.updaters.filter((u) => u.id !== handleOrFn.id);
+    return this;
+  }
+  clearUpdaters() {
+    this.updaters = [];
+    return this;
+  }
+  suspendUpdaters() {
+    this.updatersEnabled = false;
+    return this;
+  }
+  resumeUpdaters() {
+    this.updatersEnabled = true;
+    return this;
+  }
+  enableUpdater(handleOrFn) {
+    this.setUpdaterEnabled(handleOrFn, true);
+    return this;
+  }
+  disableUpdater(handleOrFn) {
+    this.setUpdaterEnabled(handleOrFn, false);
     return this;
   }
+  hasActiveUpdaters(recursive = false) {
+    if (this.updatersEnabled && this.updaters.some((u) => u.enabled)) {
+      return true;
+    }
+    if (!recursive) {
+      return false;
+    }
+    return this.submobjects.some((child) => child.hasActiveUpdaters(true));
+  }
+  /**
+   * Internal API used by UpdaterEngine.
+   * Returns a deterministic snapshot for current-frame execution.
+   */
+  getUpdaterRecordsSnapshot() {
+    if (!this.updatersEnabled) {
+      return [];
+    }
+    const active = this.updaters.filter((u) => u.enabled);
+    active.sort((a, b) => {
+      if (a.priority !== b.priority) {
+        return b.priority - a.priority;
+      }
+      return a.order - b.order;
+    });
+    return active.map((u) => ({ ...u }));
+  }
+  setUpdaterEnabled(handleOrFn, enabled) {
+    if (typeof handleOrFn === "function") {
+      const fn = handleOrFn;
+      for (const updater of this.updaters) {
+        if (updater.fn === fn) {
+          updater.enabled = enabled;
+        }
+      }
+      return;
+    }
+    for (const updater of this.updaters) {
+      if (updater.id === handleOrFn.id) {
+        updater.enabled = enabled;
+      }
+    }
+  }
+  setPointCloud(points) {
+    this.pointCloud = points.map(
+      (p) => p instanceof Vector ? new Vector(p.x, p.y, p.z) : Vector.fromPlanar(p, 0)
+    );
+    this.syncLocalMatrixFromGeometry();
+  }
+  getPointCloud() {
+    return this.pointCloud.map((p) => new Vector(p.x, p.y, p.z));
+  }
   // ========== State Save/Restore ==========
   saveState() {
     const pos = this.position;
     const scl = this.scale;
     this.savedStates.push({
-      position: new Vector2(pos.x, pos.y),
-      scale: new Vector2(scl.x, scl.y),
+      position: new Vector(pos.x, pos.y, pos.z),
+      scale: new Vector(scl.x, scl.y),
       rotation: this.rotation
     });
     return this;
@@ -2101,8 +2399,8 @@ var Mobject = class {
     if (!state) {
       throw new Error("restore() called but no state was saved. Call saveState() first.");
     }
-    const moveAnim = createMoveTo(this, state.position.x, state.position.y, durationSeconds);
-    const scaleAnim = createScale2(this, state.scale.x, state.scale.y, durationSeconds);
+    const moveAnim = createMoveTo(this, state.position, durationSeconds);
+    const scaleAnim = createScale(this, state.scale.x, state.scale.y, durationSeconds);
     const rotateAnim = createRotate(this, state.rotation - this.rotation, durationSeconds);
     const parallelAnim = createParallel([moveAnim, scaleAnim, rotateAnim]);
     this.getQueue().enqueueAnimation(parallelAnim);
@@ -2121,8 +2419,20 @@ var Mobject = class {
     this.getQueue().enqueueAnimation(animation);
     return this;
   }
-  moveTo(x, y, durationSeconds) {
-    const animation = createMoveTo(this, x, y, durationSeconds);
+  moveTo(xOrDestination, yOrDuration, zOrDuration, durationSeconds) {
+    let animation;
+    if (typeof xOrDestination !== "number") {
+      animation = createMoveTo(this, xOrDestination, yOrDuration);
+    } else {
+      const x = xOrDestination;
+      const y = yOrDuration ?? 0;
+      if (durationSeconds !== void 0) {
+        const z = zOrDuration ?? this.position.z;
+        animation = createMoveTo(this, new Vector(x, y, z), durationSeconds);
+      } else {
+        animation = createMoveTo(this, x, y, zOrDuration);
+      }
+    }
     this.getQueue().enqueueAnimation(animation);
     return this;
   }
@@ -2132,12 +2442,12 @@ var Mobject = class {
     return this;
   }
   scaleTo(factor, durationSeconds) {
-    const animation = createScale2(this, factor, factor, durationSeconds);
+    const animation = createScale(this, factor, factor, durationSeconds);
     this.getQueue().enqueueAnimation(animation);
     return this;
   }
   scaleToXY(factorX, factorY, durationSeconds) {
-    const animation = createScale2(this, factorX, factorY, durationSeconds);
+    const animation = createScale(this, factorX, factorY, durationSeconds);
     this.getQueue().enqueueAnimation(animation);
     return this;
   }
@@ -2194,223 +2504,561 @@ var Mobject = class {
    * Used by the segment cache to detect changes.
    */
   computeHash() {
+    const pointData = new Float32Array(this.pointCloud.length * 3);
+    for (let i = 0; i < this.pointCloud.length; i++) {
+      const p = this.pointCloud[i];
+      pointData[i * 3] = p.x;
+      pointData[i * 3 + 1] = p.y;
+      pointData[i * 3 + 2] = p.z;
+    }
+    const childHashes = this.submobjects.map((child) => child.computeHash());
     return hashCompose(
       hashFloat32Array(this.localMatrix.values),
-      hashNumber(this.opacityValue)
+      hashNumber(this.opacityValue),
+      hashFloat32Array(pointData),
+      ...childHashes
     );
   }
-};
-
-// src/core/mobjects/VMobject.ts
-var VMobject = class extends Mobject {
-  pathList = [];
-  /** Stroke color. Only rendered if strokeWidth > 0. */
-  strokeColor = Color.WHITE;
-  /** Stroke width. Default 2 for visibility. */
-  strokeWidth = 2;
-  /** Fill color. Only rendered if fillOpacity > 0. */
-  fillColor = Color.TRANSPARENT;
-  /** Fill opacity. Default 0 means no fill is rendered. */
-  fillOpacity = 0;
-  /** Tracks whether stroke() was explicitly called. */
-  strokeExplicitlySet = false;
-  constructor() {
-    super();
+  applyMatrixToOwnGeometry(m) {
+    if (this.pointCloud.length === 0) return;
+    this.pointCloud = this.pointCloud.map((point) => m.transformPoint(point));
   }
-  get paths() {
-    return this.pathList;
+  usesGeometryTransforms() {
+    return this.pointCloud.length > 0 || this.submobjects.length > 0;
   }
-  set paths(value) {
-    this.pathList = value;
+  collectGeometryPoints(out) {
+    out.push(...this.pointCloud);
+    for (const child of this.submobjects) {
+      child.collectGeometryPoints(out);
+    }
   }
-  /**
-   * Gets the stroke color.
-   */
-  getStrokeColor() {
-    return this.strokeColor;
+  getGeometryCenter() {
+    const points = [];
+    this.collectGeometryPoints(points);
+    if (points.length === 0) {
+      return null;
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let minZ = Infinity;
+    let maxZ = -Infinity;
+    for (const p of points) {
+      if (p.x < minX) minX = p.x;
+      if (p.x > maxX) maxX = p.x;
+      if (p.y < minY) minY = p.y;
+      if (p.y > maxY) maxY = p.y;
+      if (p.z < minZ) minZ = p.z;
+      if (p.z > maxZ) maxZ = p.z;
+    }
+    return new Vector((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
+  }
+  syncLocalMatrixFromGeometry() {
+    if (!this.usesGeometryTransforms()) {
+      return;
+    }
+    const center = this.getGeometryCenter() ?? Vector.ZERO;
+    const sx = this.logicalScale.x;
+    const sy = this.logicalScale.y;
+    const cos = Math.cos(this.logicalRotation);
+    const sin = Math.sin(this.logicalRotation);
+    const values = new Float32Array(16);
+    values[0] = cos * sx;
+    values[1] = -sin * sy;
+    values[3] = center.x;
+    values[4] = sin * sx;
+    values[5] = cos * sy;
+    values[7] = center.y;
+    values[10] = 1;
+    values[11] = center.z;
+    values[15] = 1;
+    this.setLocalMatrix(new Matrix4x4(values));
+  }
+  updateLogicalStateFromMatrix(m) {
+    const values = m.values;
+    const sx = Math.sqrt(values[0] * values[0] + values[4] * values[4]);
+    const sy = Math.sqrt(values[1] * values[1] + values[5] * values[5]);
+    const rot = Math.atan2(values[4], values[0]);
+    this.logicalScale = new Vector(this.logicalScale.x * sx, this.logicalScale.y * sy);
+    this.logicalRotation += rot;
+  }
+  setLocalMatrix(m4) {
+    this.localMatrix = m4;
   }
+};
+
+// src/core/animations/composition/Sequence.ts
+var Sequence = class extends Animation {
+  children;
+  childDurations;
+  totalChildDuration;
   /**
-   * Gets the stroke width.
+   * The lifecycle of Sequence is determined by its FIRST child animation.
+   * If the first animation is introductory, it will register the target,
+   * allowing subsequent transformative animations to work.
    */
-  getStrokeWidth() {
-    return this.strokeWidth;
+  lifecycle;
+  constructor(animations) {
+    super(new Mobject());
+    this.children = animations;
+    this.childDurations = animations.map((a) => a.getDuration());
+    this.totalChildDuration = this.childDurations.reduce((sum, d) => sum + d, 0);
+    this.durationSeconds = this.totalChildDuration;
+    const first = animations[0];
+    this.lifecycle = first?.lifecycle === "introductory" ? "introductory" : "transformative";
   }
-  /**
-   * Gets the fill color.
-   */
-  getFillColor() {
-    return this.fillColor;
+  getDuration() {
+    return this.durationSeconds;
   }
-  /**
-   * Gets the fill opacity.
-   */
-  getFillOpacity() {
-    return this.fillOpacity;
+  getChildren() {
+    return this.children;
   }
   /**
-   * Adds a new path to the VMobject.
-   * @param path - The BezierPath to add.
-   * @returns this for chaining.
+   * Initializes only the first child.
+   * Later children are initialized when they become active in interpolate().
    */
-  addPath(path) {
-    this.pathList.push(path);
-    return this;
+  ensureInitialized() {
+    if (this.children.length > 0) {
+      this.children[0].ensureInitialized();
+    }
   }
-  /**
-   * Sets the stroke color and width.
-   * @param color - The stroke color.
-   * @param width - The stroke width. Default is 2.
-   * @returns this for chaining.
-   */
-  stroke(color, width = 2) {
-    this.strokeColor = color;
-    this.strokeWidth = width;
-    this.strokeExplicitlySet = true;
-    return this;
+  reset() {
+    for (const child of this.children) {
+      child.reset();
+    }
   }
   /**
-   * Sets the fill color and opacity.
-   * If stroke was not explicitly set, the default stroke is disabled.
-   * @param color - The fill color.
-   * @param opacity - The fill opacity. Defaults to the color's alpha value.
-   * @returns this for chaining.
+   * Interpolates the sequence at the given progress.
+   * Maps global progress to the correct child animation.
+   * 
+   * IMPORTANT: We only update children that have started or completed.
+   * Children that haven't started yet are NOT updated to avoid
+   * premature initialization with incorrect state.
    */
-  fill(color, opacity) {
-    this.fillColor = color;
-    this.fillOpacity = opacity ?? color.a;
-    if (!this.strokeExplicitlySet) {
-      this.strokeWidth = 0;
+  interpolate(progress) {
+    if (this.children.length === 0 || this.totalChildDuration === 0) {
+      return;
+    }
+    const globalTime = progress * this.totalChildDuration;
+    let accumulatedTime = 0;
+    for (let i = 0; i < this.children.length; i++) {
+      const child = this.children[i];
+      const childDuration = this.childDurations[i];
+      if (child === void 0 || childDuration === void 0) {
+        continue;
+      }
+      const childStart = accumulatedTime;
+      const childEnd = accumulatedTime + childDuration;
+      if (globalTime < childStart) {
+      } else if (globalTime >= childEnd) {
+        child.update(1);
+      } else {
+        const localProgress = (globalTime - childStart) / childDuration;
+        child.update(localProgress);
+      }
+      accumulatedTime = childEnd;
     }
-    return this;
   }
-  getPoints() {
-    const commands = [];
-    for (const path of this.pathList) {
-      commands.push(...path.getCommands());
+  update(progress) {
+    const clampedProgress = Math.max(0, Math.min(1, progress));
+    this.interpolate(clampedProgress);
+  }
+};
+
+// src/core/animations/keyframes/types.ts
+function lerpNumber(a, b, t) {
+  return a + (b - a) * t;
+}
+
+// src/core/animations/keyframes/KeyframeTrack.ts
+var KeyframeTrack = class {
+  keyframes = [];
+  interpolator;
+  /**
+   * Creates a new KeyframeTrack with the specified interpolator.
+   * Defaults to linear number interpolation.
+   */
+  constructor(interpolator) {
+    this.interpolator = interpolator ?? lerpNumber;
+  }
+  /**
+   * Adds a keyframe at the specified normalized time.
+   * Time must be in [0, 1]. Replaces existing keyframe at same time.
+   */
+  addKeyframe(time, value, easing) {
+    if (time < 0 || time > 1) {
+      throw new Error("Keyframe time must be in [0, 1]");
     }
-    return commands;
+    this.keyframes = this.keyframes.filter((kf) => kf.time !== time);
+    const keyframe = { time, value, easing };
+    this.keyframes.push(keyframe);
+    this.keyframes.sort((a, b) => a.time - b.time);
+    return this;
   }
-  setPoints(commands) {
-    if (commands.length === 0) {
-      this.pathList = [];
-      return this;
+  removeKeyframe(time) {
+    const initialLength = this.keyframes.length;
+    this.keyframes = this.keyframes.filter((kf) => kf.time !== time);
+    return this.keyframes.length < initialLength;
+  }
+  /**
+   * Gets the keyframe at the specified time.
+   * Returns undefined if no keyframe exists at that time.
+   */
+  getKeyframe(time) {
+    return this.keyframes.find((kf) => kf.time === time);
+  }
+  /** All keyframes sorted by time. */
+  getKeyframes() {
+    return this.keyframes;
+  }
+  /** Interpolated value at normalized time (uses target keyframe easing). */
+  getValueAt(time) {
+    if (this.keyframes.length === 0) {
+      throw new Error("KeyframeTrack has no keyframes");
     }
-    const path = new BezierPath();
-    for (const cmd of commands) {
-      switch (cmd.type) {
-        case "Move":
-          path.moveTo(cmd.end);
-          break;
-        case "Line":
-          path.lineTo(cmd.end);
-          break;
-        case "Quadratic":
-          if (cmd.control1) {
-            path.quadraticTo(cmd.control1, cmd.end);
-          }
-          break;
-        case "Cubic":
-          if (cmd.control1 && cmd.control2) {
-            path.cubicTo(cmd.control1, cmd.control2, cmd.end);
-          }
-          break;
-        case "Close":
-          path.closePath();
-          break;
+    const clampedTime = Math.max(0, Math.min(1, time));
+    let prevKeyframe;
+    let nextKeyframe;
+    for (const kf of this.keyframes) {
+      if (kf.time <= clampedTime) {
+        prevKeyframe = kf;
+      }
+      if (kf.time >= clampedTime && nextKeyframe === void 0) {
+        nextKeyframe = kf;
       }
     }
-    this.pathList = [path];
-    return this;
-  }
-  getPointsAsVectors() {
-    const points = [];
-    for (const cmd of this.getPoints()) {
-      if (cmd.control1) points.push(cmd.control1);
-      if (cmd.control2) points.push(cmd.control2);
-      points.push(cmd.end);
+    if (prevKeyframe === void 0) {
+      return this.keyframes[0].value;
     }
-    return points;
-  }
-  getBoundingBox() {
-    const points = this.getPointsAsVectors();
-    const worldMatrix = this.getWorldMatrix();
-    if (points.length === 0) {
-      const pos = this.position;
-      return { minX: pos.x, maxX: pos.x, minY: pos.y, maxY: pos.y };
+    if (nextKeyframe === void 0) {
+      return prevKeyframe.value;
     }
-    let minX = Infinity;
-    let maxX = -Infinity;
-    let minY = Infinity;
-    let maxY = -Infinity;
-    for (const point of points) {
-      const transformed = worldMatrix.transformPoint(point);
-      if (transformed.x < minX) minX = transformed.x;
-      if (transformed.x > maxX) maxX = transformed.x;
-      if (transformed.y < minY) minY = transformed.y;
-      if (transformed.y > maxY) maxY = transformed.y;
+    if (prevKeyframe === nextKeyframe) {
+      return prevKeyframe.value;
     }
-    return { minX, maxX, minY, maxY };
+    const span = nextKeyframe.time - prevKeyframe.time;
+    const localProgress = (clampedTime - prevKeyframe.time) / span;
+    const easing = nextKeyframe.easing ?? linear;
+    const easedProgress = easing(localProgress);
+    return this.interpolator(prevKeyframe.value, nextKeyframe.value, easedProgress);
   }
-  // ========== VMobject-Specific Fluent Animation API ==========
+  getKeyframeCount() {
+    return this.keyframes.length;
+  }
+};
+
+// src/core/animations/keyframes/KeyframeAnimation.ts
+var KeyframeAnimation = class extends Animation {
+  tracks = /* @__PURE__ */ new Map();
+  lifecycle = "transformative";
   /**
-   * Progressively draws the VMobject's paths from start to end.
-   * Preserves fill throughout the animation.
-   * @param durationSeconds - Animation duration in seconds.
-   * @returns this for chaining.
+   * Adds a named keyframe track with its property setter.
+   * The setter is called during interpolation to apply values to the target.
    */
-  write(durationSeconds) {
-    const animation = createWrite(this, durationSeconds);
-    this.getQueue().enqueueAnimation(animation);
+  addTrack(name, track, setter) {
+    this.tracks.set(name, {
+      track,
+      setter
+    });
     return this;
   }
+  /** Gets a track by name. */
+  getTrack(name) {
+    const entry = this.tracks.get(name);
+    return entry?.track;
+  }
+  /** All track names. */
+  getTrackNames() {
+    return Array.from(this.tracks.keys());
+  }
   /**
-   * Progressively removes the VMobject's paths (reverse of write).
-   * @param durationSeconds - Animation duration in seconds.
-   * @returns this for chaining.
+   * Interpolates all tracks at the given progress and applies values to target.
    */
-  unwrite(durationSeconds) {
-    const animation = createUnwrite(this, durationSeconds);
-    this.getQueue().enqueueAnimation(animation);
-    return this;
+  interpolate(progress) {
+    for (const entry of this.tracks.values()) {
+      const value = entry.track.getValueAt(progress);
+      entry.setter(this.target, value);
+    }
   }
+};
+
+// src/core/animations/camera/Follow.ts
+var Follow = class _Follow extends Animation {
+  lifecycle = "transformative";
+  followTarget;
+  offset;
+  damping;
   /**
-   * First draws the stroke progressively (0-50%), then fades in the fill (50-100%).
-   * @param durationSeconds - Animation duration in seconds.
-   * @returns this for chaining.
+   * 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));
    */
-  draw(durationSeconds) {
-    const animation = createDraw(this, durationSeconds);
-    this.getQueue().enqueueAnimation(animation);
-    return this;
+  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 = _Follow.normalizeOffset(config.offset);
+    this.damping = config.damping ?? 0;
   }
   /**
-   * Extends parent hash with VMobject-specific state:
-   * stroke/fill colors, widths, opacity, and path geometry.
+   * Updates the camera position each frame to track the target.
+   * @param progress - Animation progress (0 to 1)
    */
-  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
+  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);
+    }
+  }
+  static normalizeOffset(offset) {
+    if (!offset) {
+      return Vector.ZERO;
+    }
+    if (offset instanceof Vector) {
+      return offset;
+    }
+    if (offset.length === 2) {
+      return new Vector(offset[0], offset[1], 0);
+    }
+    return new Vector(offset[0], offset[1], offset[2]);
+  }
+};
+
+// src/core/animations/camera/Shake.ts
+var Shake = class extends TransformativeAnimation {
+  originalPosition;
+  intensity;
+  frequency;
+  decay;
+  seedX;
+  seedY;
+  /**
+   * Creates a new Shake animation.
+   *
+   * @param frame - The CameraFrame to shake
+   * @param config - Configuration options for intensity, frequency, and decay
+   *
+   * @example
+   * const shake = new Shake(scene.frame, { intensity: 0.3 });
+   * this.play(shake.duration(0.5));
+   */
+  constructor(frame, config = {}) {
+    super(frame);
+    this.intensity = config.intensity ?? 0.2;
+    this.frequency = config.frequency ?? 10;
+    this.decay = config.decay ?? 1;
+    this.seedX = Math.random() * 1e3;
+    this.seedY = Math.random() * 1e3;
+  }
+  /**
+   * Captures the original position before shake begins.
+   */
+  captureStartState() {
+    this.originalPosition = this.target.position;
+  }
+  /**
+   * Applies procedural shake displacement each frame.
+   * @param progress - Animation progress (0 to 1)
+   */
+  interpolate(progress) {
+    this.ensureInitialized();
+    if (progress >= 1) {
+      this.target.pos(this.originalPosition.x, this.originalPosition.y);
+      return;
+    }
+    const decayFactor = 1 - Math.pow(progress, this.decay);
+    const time = progress * this.durationSeconds * this.frequency;
+    const offsetX = this.noise(time, this.seedX) * this.intensity * decayFactor;
+    const offsetY = this.noise(time, this.seedY) * this.intensity * decayFactor;
+    this.target.pos(
+      this.originalPosition.x + offsetX,
+      this.originalPosition.y + offsetY
     );
   }
+  /**
+   * Generates pseudo-random noise using layered sine waves.
+   * @param t - Time value
+   * @param seed - Random seed for variation
+   * @returns Noise value between -1 and 1
+   */
+  noise(t, seed) {
+    return Math.sin(t * 2 + seed) * 0.5 + Math.sin(t * 3.7 + seed * 1.3) * 0.3 + Math.sin(t * 7.1 + seed * 0.7) * 0.2;
+  }
+};
+
+// src/core/animations/introspection.ts
+function hasAnimationChildren(animation) {
+  return "getChildren" in animation && typeof animation.getChildren === "function";
+}
+function getAnimationChildren(animation) {
+  if (hasAnimationChildren(animation)) {
+    return animation.getChildren();
+  }
+  return [];
+}
+function getAnimationTotalTime(animation) {
+  return animation.getDuration() + animation.getDelay();
+}
+function getLongestAnimationTotalTime(animations) {
+  let longest = 0;
+  for (const animation of animations) {
+    const totalTime = getAnimationTotalTime(animation);
+    if (totalTime > longest) {
+      longest = totalTime;
+    }
+  }
+  return longest;
+}
+
+// src/core/timeline/Timeline.ts
+var Timeline = class {
+  scheduled = [];
+  config;
+  currentTime = 0;
+  constructor(config = {}) {
+    this.config = {
+      loop: config.loop ?? false
+    };
+  }
+  /**
+   * Schedule an animation to start at a specific time.
+   * @param animation The animation to schedule
+   * @param startTime Start time in seconds (default: 0)
+   */
+  schedule(animation, startTime = 0) {
+    if (startTime < 0) {
+      throw new Error("Start time must be non-negative");
+    }
+    this.scheduled.push({ animation, startTime });
+    return this;
+  }
+  /**
+   * Schedule multiple animations to play in sequence.
+   * First animation starts at the given startTime, subsequent
+   * animations start after the previous one ends.
+   * @param animations Animations to schedule sequentially
+   * @param startTime Start time for the first animation (default: 0)
+   */
+  scheduleSequence(animations, startTime = 0) {
+    let currentStart = startTime;
+    for (const anim of animations) {
+      this.schedule(anim, currentStart);
+      currentStart += getAnimationTotalTime(anim);
+    }
+    return this;
+  }
+  /**
+   * Schedule multiple animations to play in parallel.
+   * All animations start at the same time.
+   * @param animations Animations to schedule in parallel
+   * @param startTime Start time for all animations (default: 0)
+   */
+  scheduleParallel(animations, startTime = 0) {
+    for (const anim of animations) {
+      this.schedule(anim, startTime);
+    }
+    return this;
+  }
+  /**
+   * Get all scheduled animations with resolved timing information.
+   */
+  getResolved() {
+    return this.scheduled.map((s) => {
+      const delay = s.animation.getDelay();
+      const duration = s.animation.getDuration();
+      const effectiveStartTime = s.startTime + delay;
+      return {
+        animation: s.animation,
+        effectiveStartTime,
+        duration,
+        endTime: effectiveStartTime + duration
+      };
+    });
+  }
+  /**
+   * Get total duration of the timeline.
+   * Returns the end time of the last animation to finish.
+   */
+  getTotalDuration() {
+    const resolved = this.getResolved();
+    if (resolved.length === 0) return 0;
+    return Math.max(...resolved.map((r) => r.endTime));
+  }
+  /**
+   * Seek to a specific time and update all animations.
+   * @param time Time in seconds to seek to
+   */
+  seek(time) {
+    const clampedTime = Math.max(0, time);
+    this.currentTime = clampedTime;
+    const resolved = this.getResolved();
+    for (const r of resolved) {
+      const { animation, effectiveStartTime, duration, endTime } = r;
+      if (clampedTime < effectiveStartTime) {
+        continue;
+      } else if (clampedTime >= endTime) {
+        animation.update(1);
+      } else {
+        const elapsed = clampedTime - effectiveStartTime;
+        const progress = duration > 0 ? elapsed / duration : 1;
+        animation.update(progress);
+      }
+    }
+  }
+  /**
+   * Get the timeline state at a specific time without modifying the
+   * current playhead position.
+   * @param time Time in seconds
+   */
+  getStateAt(time) {
+    const savedTime = this.currentTime;
+    this.seek(time);
+    this.currentTime = savedTime;
+  }
+  /**
+   * Get the current time of the timeline.
+   */
+  getCurrentTime() {
+    return this.currentTime;
+  }
+  /**
+   * Get all scheduled animations.
+   */
+  getScheduled() {
+    return this.scheduled;
+  }
+  /**
+   * Check if timeline is configured to loop.
+   */
+  isLooping() {
+    return this.config.loop;
+  }
+  /**
+   * Clear all scheduled animations.
+   */
+  clear() {
+    this.scheduled.length = 0;
+    this.currentTime = 0;
+  }
 };
 
 // src/core/camera/types.ts
@@ -2798,9 +3446,9 @@ var Camera = class {
     const frameRotation = this.frame.rotation;
     const zoomX = 1 / frameScale.x;
     const zoomY = 1 / frameScale.y;
-    const translate = Matrix3x3.translation(-framePos.x, -framePos.y);
-    const rotate = Matrix3x3.rotation(-frameRotation);
-    const scale = Matrix3x3.scale(zoomX, zoomY);
+    const translate = Matrix4x4.translation(-framePos.x, -framePos.y, 0);
+    const rotate = Matrix4x4.rotationZ(-frameRotation);
+    const scale = Matrix4x4.scale(zoomX, zoomY, 1);
     return scale.multiply(rotate).multiply(translate);
   }
   // ========== Coordinate Transforms ==========
@@ -2819,10 +3467,10 @@ var Camera = class {
    */
   worldToScreen(pos) {
     const viewMatrix = this.getViewMatrix();
-    const transformed = viewMatrix.transformPoint(pos);
+    const transformed = viewMatrix.transformPoint2D(pos);
     const screenX = (transformed.x + 1) * 0.5 * this.config.pixelWidth;
     const screenY = (1 - transformed.y) * 0.5 * this.config.pixelHeight;
-    return new Vector2(screenX, screenY);
+    return new Vector(screenX, screenY);
   }
   /**
    * Transforms a screen-space (pixel) position to world coordinates.
@@ -2833,14 +3481,14 @@ var Camera = class {
    *
    * @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) {
     const ndcX = pos.x / this.config.pixelWidth * 2 - 1;
     const ndcY = 1 - pos.y / this.config.pixelHeight * 2;
     const viewMatrix = this.getViewMatrix();
     const inverseView = viewMatrix.inverse();
-    return inverseView.transformPoint(new Vector2(ndcX, ndcY));
+    return inverseView.transformPoint2D(new Vector(ndcX, ndcY));
   }
   /**
    * Checks if a world-space position is currently visible within the camera frame.
@@ -2877,17 +3525,283 @@ var Camera = class {
   }
 };
 
-// src/core/mobjects/VGroup/layout.ts
-var defaultCamera = new Camera();
-function centerGroup(group) {
-  const bounds = group.getBoundingBox();
-  const centerX = (bounds.minX + bounds.maxX) / 2;
-  const centerY = (bounds.minY + bounds.maxY) / 2;
-  const translation = Matrix3x3.translation(-centerX, -centerY);
-  for (const child of group.getChildren()) {
-    child.applyMatrix(translation);
-  }
-  return group;
+// src/core/mobjects/VMobject.ts
+var VMobject = class extends Mobject {
+  pathList = [];
+  /** Stroke color. Only rendered if strokeWidth > 0. */
+  strokeColor = Color.WHITE;
+  /** Stroke width. Default 2 for visibility. */
+  strokeWidth = 2;
+  /** Fill color. Only rendered if fillOpacity > 0. */
+  fillColor = Color.TRANSPARENT;
+  /** Fill opacity. Default 0 means no fill is rendered. */
+  fillOpacity = 0;
+  /** Tracks whether stroke() was explicitly called. */
+  strokeExplicitlySet = false;
+  constructor() {
+    super();
+  }
+  get paths() {
+    return this.pathList;
+  }
+  set paths(value) {
+    this.pathList = value;
+    this.syncPointCloudFromPaths();
+  }
+  /**
+   * Gets the stroke color.
+   */
+  getStrokeColor() {
+    return this.strokeColor;
+  }
+  /**
+   * Gets the stroke width.
+   */
+  getStrokeWidth() {
+    return this.strokeWidth;
+  }
+  /**
+   * Gets the fill color.
+   */
+  getFillColor() {
+    return this.fillColor;
+  }
+  /**
+   * Gets the fill opacity.
+   */
+  getFillOpacity() {
+    return this.fillOpacity;
+  }
+  /**
+   * Adds a new path to the VMobject.
+   * @param path - The BezierPath to add.
+   * @returns this for chaining.
+   */
+  addPath(path) {
+    this.pathList.push(path);
+    this.syncPointCloudFromPaths();
+    return this;
+  }
+  /**
+   * Sets the stroke color and width.
+   * @param color - The stroke color.
+   * @param width - The stroke width. Default is 2.
+   * @returns this for chaining.
+   */
+  stroke(color, width = 2) {
+    this.strokeColor = color;
+    this.strokeWidth = width;
+    this.strokeExplicitlySet = true;
+    return this;
+  }
+  /**
+   * Sets the fill color and opacity.
+   * If stroke was not explicitly set, the default stroke is disabled.
+   * @param color - The fill color.
+   * @param opacity - The fill opacity. Defaults to the color's alpha value.
+   * @returns this for chaining.
+   */
+  fill(color, opacity) {
+    this.fillColor = color;
+    this.fillOpacity = opacity ?? color.a;
+    if (!this.strokeExplicitlySet) {
+      this.strokeWidth = 0;
+    }
+    return this;
+  }
+  getPoints() {
+    const commands = [];
+    for (const path of this.pathList) {
+      commands.push(...path.getCommands());
+    }
+    return commands;
+  }
+  setPoints(commands) {
+    if (commands.length === 0) {
+      this.pathList = [];
+      this.setPointCloud([]);
+      return this;
+    }
+    const path = new BezierPath();
+    for (const cmd of commands) {
+      switch (cmd.type) {
+        case "Move":
+          path.moveTo(cmd.end);
+          break;
+        case "Line":
+          path.lineTo(cmd.end);
+          break;
+        case "Quadratic":
+          if (cmd.control1) {
+            path.quadraticTo(cmd.control1, cmd.end);
+          }
+          break;
+        case "Cubic":
+          if (cmd.control1 && cmd.control2) {
+            path.cubicTo(cmd.control1, cmd.control2, cmd.end);
+          }
+          break;
+        case "Close":
+          path.closePath();
+          break;
+      }
+    }
+    this.pathList = [path];
+    this.syncPointCloudFromPaths();
+    return this;
+  }
+  getPointsAsVectors() {
+    const points = [];
+    for (const cmd of this.getPoints()) {
+      if (cmd.control1) points.push(cmd.control1);
+      if (cmd.control2) points.push(cmd.control2);
+      points.push(cmd.end);
+    }
+    return points;
+  }
+  getBoundingBox() {
+    const points = this.getPointsAsVectors();
+    if (points.length === 0) {
+      const pos = this.position;
+      return { minX: pos.x, maxX: pos.x, minY: pos.y, maxY: pos.y };
+    }
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const point of points) {
+      if (point.x < minX) minX = point.x;
+      if (point.x > maxX) maxX = point.x;
+      if (point.y < minY) minY = point.y;
+      if (point.y > maxY) maxY = point.y;
+    }
+    return { minX, maxX, minY, maxY };
+  }
+  applyMatrixToOwnGeometry(m) {
+    this.pathList = this.pathList.map((path) => {
+      const transformedCommands = path.getCommands().map((cmd) => {
+        const next = {
+          ...cmd,
+          end: m.transformPoint(Vector.fromPlanar(cmd.end, 0)).toPlanar()
+        };
+        if (cmd.control1) {
+          next.control1 = m.transformPoint(Vector.fromPlanar(cmd.control1, 0)).toPlanar();
+        }
+        if (cmd.control2) {
+          next.control2 = m.transformPoint(Vector.fromPlanar(cmd.control2, 0)).toPlanar();
+        }
+        return next;
+      });
+      const transformedPath = new BezierPath();
+      for (const cmd of transformedCommands) {
+        switch (cmd.type) {
+          case "Move":
+            transformedPath.moveTo(cmd.end);
+            break;
+          case "Line":
+            transformedPath.lineTo(cmd.end);
+            break;
+          case "Quadratic":
+            if (cmd.control1) {
+              transformedPath.quadraticTo(cmd.control1, cmd.end);
+            }
+            break;
+          case "Cubic":
+            if (cmd.control1 && cmd.control2) {
+              transformedPath.cubicTo(cmd.control1, cmd.control2, cmd.end);
+            }
+            break;
+          case "Close":
+            transformedPath.closePath();
+            break;
+        }
+      }
+      return transformedPath;
+    });
+    this.syncPointCloudFromPaths();
+  }
+  // ========== VMobject-Specific Fluent Animation API ==========
+  /**
+   * Progressively draws the VMobject's paths from start to end.
+   * Preserves fill throughout the animation.
+   * @param durationSeconds - Animation duration in seconds.
+   * @returns this for chaining.
+   */
+  write(durationSeconds) {
+    const animation = createWrite(this, durationSeconds);
+    this.getQueue().enqueueAnimation(animation);
+    return this;
+  }
+  /**
+   * Progressively removes the VMobject's paths (reverse of write).
+   * @param durationSeconds - Animation duration in seconds.
+   * @returns this for chaining.
+   */
+  unwrite(durationSeconds) {
+    const animation = createUnwrite(this, durationSeconds);
+    this.getQueue().enqueueAnimation(animation);
+    return this;
+  }
+  /**
+   * First draws the stroke progressively (0-50%), then fades in the fill (50-100%).
+   * @param durationSeconds - Animation duration in seconds.
+   * @returns this for chaining.
+   */
+  draw(durationSeconds) {
+    const animation = createDraw(this, durationSeconds);
+    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
+    );
+  }
+  syncPointCloudFromPaths() {
+    const points = [];
+    for (const path of this.pathList) {
+      for (const cmd of path.getCommands()) {
+        if (cmd.control1) points.push(Vector.fromPlanar(cmd.control1, 0));
+        if (cmd.control2) points.push(Vector.fromPlanar(cmd.control2, 0));
+        points.push(Vector.fromPlanar(cmd.end, 0));
+      }
+    }
+    this.setPointCloud(points);
+  }
+};
+
+// src/core/mobjects/VGroup/layout.ts
+var defaultCamera = new Camera();
+function centerGroup(group) {
+  const bounds = group.getBoundingBox();
+  const centerX = (bounds.minX + bounds.maxX) / 2;
+  const centerY = (bounds.minY + bounds.maxY) / 2;
+  const translation = Matrix4x4.translation(-centerX, -centerY, 0);
+  group.applyMatrix(translation);
+  return group;
 }
 function toCorner(group, corner, buff = 0, camera = defaultCamera) {
   const bounds = group.getBoundingBox();
@@ -2919,10 +3833,8 @@ function toCorner(group, corner, buff = 0, camera = defaultCamera) {
   const currentCenterY = (bounds.minY + bounds.maxY) / 2;
   const shiftX = targetX - currentCenterX;
   const shiftY = targetY - currentCenterY;
-  const translation = Matrix3x3.translation(shiftX, shiftY);
-  for (const child of group.getChildren()) {
-    child.applyMatrix(translation);
-  }
+  const translation = Matrix4x4.translation(shiftX, shiftY, 0);
+  group.applyMatrix(translation);
   return group;
 }
 function arrangeChildren(group, direction = "RIGHT", buff = 0.25, shouldCenter = true) {
@@ -2964,7 +3876,7 @@ function arrangeChildren(group, direction = "RIGHT", buff = 0.25, shouldCenter =
       const childCenterX = (childBounds.minX + childBounds.maxX) / 2;
       shiftX = prevCenterX - childCenterX;
     }
-    child.applyMatrix(Matrix3x3.translation(shiftX, shiftY));
+    child.applyMatrix(Matrix4x4.translation(shiftX, shiftY, 0));
     previousChild = child;
   }
   if (shouldCenter) {
@@ -2991,899 +3903,126 @@ function alignToTarget(group, target, edge) {
       shiftX = targetBounds.maxX - myBounds.maxX;
       break;
   }
-  const translation = Matrix3x3.translation(shiftX, shiftY);
-  for (const child of group.getChildren()) {
-    child.applyMatrix(translation);
-  }
+  const translation = Matrix4x4.translation(shiftX, shiftY, 0);
+  group.applyMatrix(translation);
   return group;
 }
 
 // src/core/mobjects/VGroup/VGroup.ts
 var VGroup = class extends VMobject {
-  children = [];
   constructor(...mobjects) {
     super();
     this.add(...mobjects);
   }
-  get length() {
-    return this.children.length;
-  }
-  add(...mobjects) {
-    for (const mob of mobjects) {
-      if (!this.children.includes(mob)) {
-        mob.parent = this;
-        this.children.push(mob);
-      }
-    }
-    return this;
-  }
-  remove(mobject) {
-    const index = this.children.indexOf(mobject);
-    if (index > -1) {
-      mobject.parent = null;
-      this.children.splice(index, 1);
-    }
-    return this;
-  }
-  clear() {
-    for (const child of this.children) {
-      child.parent = null;
-    }
-    this.children = [];
-    return this;
-  }
-  getChildren() {
-    return [...this.children];
-  }
-  get(index) {
-    return this.children[index];
-  }
-  // Note: applyMatrix is NOT overridden - transforms stay on this group's local matrix.
-  // Children inherit via getWorldMatrix() during rendering.
-  pos(x, y) {
-    return super.pos(x, y);
-  }
-  show() {
-    super.show();
-    for (const child of this.children) {
-      child.show();
-    }
-    return this;
-  }
-  hide() {
-    super.hide();
-    for (const child of this.children) {
-      child.hide();
-    }
-    return this;
-  }
-  /**
-   * Sets the opacity for this VGroup and all children.
-   * @param value - The opacity value (0-1).
-   * @returns this for chaining.
-   */
-  setOpacity(value) {
-    super.setOpacity(value);
-    for (const child of this.children) {
-      child.setOpacity(value);
-    }
-    return this;
-  }
-  /**
-   * Sets the stroke color and width for this VGroup and all children.
-   * @param color - The stroke color.
-   * @param width - The stroke width. Default is 2.
-   * @returns this for chaining.
-   */
-  stroke(color, width = 2) {
-    super.stroke(color, width);
-    for (const child of this.children) {
-      child.stroke(color, width);
-    }
-    return this;
-  }
-  /**
-   * Sets the fill color and opacity for this VGroup and all children.
-   * @param color - The fill color.
-   * @param opacity - The fill opacity. Default is 1 (fully opaque).
-   * @returns this for chaining.
-   */
-  fill(color, opacity = 1) {
-    super.fill(color, opacity);
-    for (const child of this.children) {
-      child.fill(color, opacity);
-    }
-    return this;
-  }
-  getBoundingBox() {
-    if (this.children.length === 0) {
-      return super.getBoundingBox();
-    }
-    let minX = Infinity;
-    let maxX = -Infinity;
-    let minY = Infinity;
-    let maxY = -Infinity;
-    for (const child of this.children) {
-      const bounds = child.getBoundingBox();
-      if (bounds.minX < minX) minX = bounds.minX;
-      if (bounds.maxX > maxX) maxX = bounds.maxX;
-      if (bounds.minY < minY) minY = bounds.minY;
-      if (bounds.maxY > maxY) maxY = bounds.maxY;
-    }
-    return { minX, maxX, minY, maxY };
-  }
-  center() {
-    centerGroup(this);
-    return this;
-  }
-  toCorner(corner, buff = 0) {
-    toCorner(this, corner, buff);
-    return this;
-  }
-  arrange(direction = "RIGHT", buff = 0.25, shouldCenter = true) {
-    arrangeChildren(this, direction, buff, shouldCenter);
-    return this;
-  }
-  alignTo(target, edge) {
-    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/core/animations/composition/Sequence.ts
-var Sequence = class extends Animation {
-  children;
-  childDurations;
-  totalChildDuration;
-  /**
-   * The lifecycle of Sequence is determined by its FIRST child animation.
-   * If the first animation is introductory, it will register the target,
-   * allowing subsequent transformative animations to work.
-   */
-  lifecycle;
-  constructor(animations) {
-    super(new Mobject());
-    this.children = animations;
-    this.childDurations = animations.map((a) => a.getDuration());
-    this.totalChildDuration = this.childDurations.reduce((sum, d) => sum + d, 0);
-    this.durationSeconds = this.totalChildDuration;
-    const first = animations[0];
-    this.lifecycle = first?.lifecycle === "introductory" ? "introductory" : "transformative";
-  }
-  getDuration() {
-    return this.durationSeconds;
-  }
-  getChildren() {
-    return this.children;
-  }
-  /**
-   * Initializes only the first child.
-   * Later children are initialized when they become active in interpolate().
-   */
-  ensureInitialized() {
-    if (this.children.length > 0) {
-      this.children[0].ensureInitialized();
-    }
-  }
-  reset() {
-    for (const child of this.children) {
-      child.reset();
-    }
-  }
-  /**
-   * Interpolates the sequence at the given progress.
-   * Maps global progress to the correct child animation.
-   * 
-   * IMPORTANT: We only update children that have started or completed.
-   * Children that haven't started yet are NOT updated to avoid
-   * premature initialization with incorrect state.
-   */
-  interpolate(progress) {
-    if (this.children.length === 0 || this.totalChildDuration === 0) {
-      return;
-    }
-    const globalTime = progress * this.totalChildDuration;
-    let accumulatedTime = 0;
-    for (let i = 0; i < this.children.length; i++) {
-      const child = this.children[i];
-      const childDuration = this.childDurations[i];
-      if (child === void 0 || childDuration === void 0) {
-        continue;
-      }
-      const childStart = accumulatedTime;
-      const childEnd = accumulatedTime + childDuration;
-      if (globalTime < childStart) {
-      } else if (globalTime >= childEnd) {
-        child.update(1);
-      } else {
-        const localProgress = (globalTime - childStart) / childDuration;
-        child.update(localProgress);
-      }
-      accumulatedTime = childEnd;
-    }
-  }
-  update(progress) {
-    const clampedProgress = Math.max(0, Math.min(1, progress));
-    this.interpolate(clampedProgress);
-  }
-};
-
-// src/core/animations/keyframes/types.ts
-function lerpNumber(a, b, t) {
-  return a + (b - a) * t;
-}
-
-// src/core/animations/keyframes/KeyframeTrack.ts
-var KeyframeTrack = class {
-  keyframes = [];
-  interpolator;
-  /**
-   * Creates a new KeyframeTrack with the specified interpolator.
-   * Defaults to linear number interpolation.
-   */
-  constructor(interpolator) {
-    this.interpolator = interpolator ?? lerpNumber;
-  }
-  /**
-   * Adds a keyframe at the specified normalized time.
-   * Time must be in [0, 1]. Replaces existing keyframe at same time.
-   */
-  addKeyframe(time, value, easing) {
-    if (time < 0 || time > 1) {
-      throw new Error("Keyframe time must be in [0, 1]");
-    }
-    this.keyframes = this.keyframes.filter((kf) => kf.time !== time);
-    const keyframe = { time, value, easing };
-    this.keyframes.push(keyframe);
-    this.keyframes.sort((a, b) => a.time - b.time);
-    return this;
-  }
-  removeKeyframe(time) {
-    const initialLength = this.keyframes.length;
-    this.keyframes = this.keyframes.filter((kf) => kf.time !== time);
-    return this.keyframes.length < initialLength;
-  }
-  /**
-   * Gets the keyframe at the specified time.
-   * Returns undefined if no keyframe exists at that time.
-   */
-  getKeyframe(time) {
-    return this.keyframes.find((kf) => kf.time === time);
-  }
-  /** All keyframes sorted by time. */
-  getKeyframes() {
-    return this.keyframes;
-  }
-  /** Interpolated value at normalized time (uses target keyframe easing). */
-  getValueAt(time) {
-    if (this.keyframes.length === 0) {
-      throw new Error("KeyframeTrack has no keyframes");
-    }
-    const clampedTime = Math.max(0, Math.min(1, time));
-    let prevKeyframe;
-    let nextKeyframe;
-    for (const kf of this.keyframes) {
-      if (kf.time <= clampedTime) {
-        prevKeyframe = kf;
-      }
-      if (kf.time >= clampedTime && nextKeyframe === void 0) {
-        nextKeyframe = kf;
-      }
-    }
-    if (prevKeyframe === void 0) {
-      return this.keyframes[0].value;
-    }
-    if (nextKeyframe === void 0) {
-      return prevKeyframe.value;
-    }
-    if (prevKeyframe === nextKeyframe) {
-      return prevKeyframe.value;
-    }
-    const span = nextKeyframe.time - prevKeyframe.time;
-    const localProgress = (clampedTime - prevKeyframe.time) / span;
-    const easing = nextKeyframe.easing ?? linear;
-    const easedProgress = easing(localProgress);
-    return this.interpolator(prevKeyframe.value, nextKeyframe.value, easedProgress);
-  }
-  getKeyframeCount() {
-    return this.keyframes.length;
-  }
-};
-
-// src/core/animations/keyframes/KeyframeAnimation.ts
-var KeyframeAnimation = class extends Animation {
-  tracks = /* @__PURE__ */ new Map();
-  lifecycle = "transformative";
-  /**
-   * Adds a named keyframe track with its property setter.
-   * The setter is called during interpolation to apply values to the target.
-   */
-  addTrack(name, track, setter) {
-    this.tracks.set(name, {
-      track,
-      setter
-    });
-    return this;
-  }
-  /** Gets a track by name. */
-  getTrack(name) {
-    const entry = this.tracks.get(name);
-    return entry?.track;
-  }
-  /** All track names. */
-  getTrackNames() {
-    return Array.from(this.tracks.keys());
-  }
-  /**
-   * Interpolates all tracks at the given progress and applies values to target.
-   */
-  interpolate(progress) {
-    for (const entry of this.tracks.values()) {
-      const value = entry.track.getValueAt(progress);
-      entry.setter(this.target, value);
-    }
-  }
-};
-
-// src/core/animations/camera/Follow.ts
-var Follow = class 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);
-    }
-  }
-};
-
-// src/core/animations/camera/Shake.ts
-var Shake = class extends TransformativeAnimation {
-  originalPosition;
-  intensity;
-  frequency;
-  decay;
-  seedX;
-  seedY;
-  /**
-   * Creates a new Shake animation.
-   *
-   * @param frame - The CameraFrame to shake
-   * @param config - Configuration options for intensity, frequency, and decay
-   *
-   * @example
-   * const shake = new Shake(scene.frame, { intensity: 0.3 });
-   * this.play(shake.duration(0.5));
-   */
-  constructor(frame, config = {}) {
-    super(frame);
-    this.intensity = config.intensity ?? 0.2;
-    this.frequency = config.frequency ?? 10;
-    this.decay = config.decay ?? 1;
-    this.seedX = Math.random() * 1e3;
-    this.seedY = Math.random() * 1e3;
-  }
-  /**
-   * Captures the original position before shake begins.
-   */
-  captureStartState() {
-    this.originalPosition = this.target.position;
-  }
-  /**
-   * Applies procedural shake displacement each frame.
-   * @param progress - Animation progress (0 to 1)
-   */
-  interpolate(progress) {
-    this.ensureInitialized();
-    if (progress >= 1) {
-      this.target.pos(this.originalPosition.x, this.originalPosition.y);
-      return;
-    }
-    const decayFactor = 1 - Math.pow(progress, this.decay);
-    const time = progress * this.durationSeconds * this.frequency;
-    const offsetX = this.noise(time, this.seedX) * this.intensity * decayFactor;
-    const offsetY = this.noise(time, this.seedY) * this.intensity * decayFactor;
-    this.target.pos(
-      this.originalPosition.x + offsetX,
-      this.originalPosition.y + offsetY
-    );
-  }
-  /**
-   * Generates pseudo-random noise using layered sine waves.
-   * @param t - Time value
-   * @param seed - Random seed for variation
-   * @returns Noise value between -1 and 1
-   */
-  noise(t, seed) {
-    return Math.sin(t * 2 + seed) * 0.5 + Math.sin(t * 3.7 + seed * 1.3) * 0.3 + Math.sin(t * 7.1 + seed * 0.7) * 0.2;
-  }
-};
-
-// src/core/animations/introspection.ts
-function hasAnimationChildren(animation) {
-  return "getChildren" in animation && typeof animation.getChildren === "function";
-}
-function getAnimationChildren(animation) {
-  if (hasAnimationChildren(animation)) {
-    return animation.getChildren();
-  }
-  return [];
-}
-function getAnimationTotalTime(animation) {
-  return animation.getDuration() + animation.getDelay();
-}
-function getLongestAnimationTotalTime(animations) {
-  let longest = 0;
-  for (const animation of animations) {
-    const totalTime = getAnimationTotalTime(animation);
-    if (totalTime > longest) {
-      longest = totalTime;
-    }
-  }
-  return longest;
-}
-
-// src/core/timeline/Timeline.ts
-var Timeline = class {
-  scheduled = [];
-  config;
-  currentTime = 0;
-  constructor(config = {}) {
-    this.config = {
-      loop: config.loop ?? false
-    };
-  }
-  /**
-   * Schedule an animation to start at a specific time.
-   * @param animation The animation to schedule
-   * @param startTime Start time in seconds (default: 0)
-   */
-  schedule(animation, startTime = 0) {
-    if (startTime < 0) {
-      throw new Error("Start time must be non-negative");
-    }
-    this.scheduled.push({ animation, startTime });
-    return this;
-  }
-  /**
-   * Schedule multiple animations to play in sequence.
-   * First animation starts at the given startTime, subsequent
-   * animations start after the previous one ends.
-   * @param animations Animations to schedule sequentially
-   * @param startTime Start time for the first animation (default: 0)
-   */
-  scheduleSequence(animations, startTime = 0) {
-    let currentStart = startTime;
-    for (const anim of animations) {
-      this.schedule(anim, currentStart);
-      currentStart += getAnimationTotalTime(anim);
-    }
-    return this;
-  }
-  /**
-   * Schedule multiple animations to play in parallel.
-   * All animations start at the same time.
-   * @param animations Animations to schedule in parallel
-   * @param startTime Start time for all animations (default: 0)
-   */
-  scheduleParallel(animations, startTime = 0) {
-    for (const anim of animations) {
-      this.schedule(anim, startTime);
-    }
-    return this;
-  }
-  /**
-   * Get all scheduled animations with resolved timing information.
-   */
-  getResolved() {
-    return this.scheduled.map((s) => {
-      const delay = s.animation.getDelay();
-      const duration = s.animation.getDuration();
-      const effectiveStartTime = s.startTime + delay;
-      return {
-        animation: s.animation,
-        effectiveStartTime,
-        duration,
-        endTime: effectiveStartTime + duration
-      };
-    });
-  }
-  /**
-   * Get total duration of the timeline.
-   * Returns the end time of the last animation to finish.
-   */
-  getTotalDuration() {
-    const resolved = this.getResolved();
-    if (resolved.length === 0) return 0;
-    return Math.max(...resolved.map((r) => r.endTime));
-  }
-  /**
-   * Seek to a specific time and update all animations.
-   * @param time Time in seconds to seek to
-   */
-  seek(time) {
-    const clampedTime = Math.max(0, time);
-    this.currentTime = clampedTime;
-    const resolved = this.getResolved();
-    for (const r of resolved) {
-      const { animation, effectiveStartTime, duration, endTime } = r;
-      if (clampedTime < effectiveStartTime) {
-        continue;
-      } else if (clampedTime >= endTime) {
-        animation.update(1);
-      } else {
-        const elapsed = clampedTime - effectiveStartTime;
-        const progress = duration > 0 ? elapsed / duration : 1;
-        animation.update(progress);
-      }
-    }
-  }
-  /**
-   * Get the timeline state at a specific time without modifying the
-   * current playhead position.
-   * @param time Time in seconds
-   */
-  getStateAt(time) {
-    const savedTime = this.currentTime;
-    this.seek(time);
-    this.currentTime = savedTime;
-  }
-  /**
-   * Get the current time of the timeline.
-   */
-  getCurrentTime() {
-    return this.currentTime;
-  }
-  /**
-   * Get all scheduled animations.
-   */
-  getScheduled() {
-    return this.scheduled;
-  }
-  /**
-   * Check if timeline is configured to loop.
-   */
-  isLooping() {
-    return this.config.loop;
-  }
-  /**
-   * Clear all scheduled animations.
-   */
-  clear() {
-    this.scheduled.length = 0;
-    this.currentTime = 0;
-  }
-};
-
-// src/core/errors/AnimationErrors.ts
-var AnimationTargetNotInSceneError = class extends Error {
-  animationName;
-  targetType;
-  constructor(animation, target) {
-    const animName = animation.constructor.name;
-    const targetType = target.constructor.name;
-    super(
-      `Cannot apply '${animName}' animation to ${targetType}: target is not in scene.
-
-This animation requires the target to already exist in the scene because it transforms an existing object rather than introducing a new one.
-
-Solutions:
-  1. Call scene.add(target) before this animation
-  2. Use an introductory animation first:
-     - FadeIn: Fades the object in from transparent
-     - Create: Draws the object's path progressively
-     - Draw: Draws border then fills
-     - Write: Draws text progressively
-
-Example:
-  // Option 1: Use add() for immediate visibility
-  scene.add(circle);
-  scene.play(new MoveTo(circle, 2, 0));
-
-  // Option 2: Use introductory animation
-  scene.play(new FadeIn(circle));
-  scene.play(new MoveTo(circle, 2, 0));`
-    );
-    this.name = "AnimationTargetNotInSceneError";
-    this.animationName = animName;
-    this.targetType = targetType;
-  }
-};
-
-// src/core/scene/Scene.ts
-var Scene = class {
-  config;
-  mobjects = /* @__PURE__ */ new Set();
-  timeline;
-  _camera;
-  segmentList = [];
-  playheadTime = 0;
-  constructor(config = {}) {
-    this.config = {
-      width: config.width ?? 1920,
-      height: config.height ?? 1080,
-      backgroundColor: config.backgroundColor ?? Color.BLACK,
-      frameRate: config.frameRate ?? 60
-    };
-    this.timeline = new Timeline();
-    this._camera = new Camera({
-      pixelWidth: this.config.width,
-      pixelHeight: this.config.height
-    });
-  }
-  // ========== Camera Shortcuts ==========
-  get camera() {
-    return this._camera;
-  }
-  get frame() {
-    return this._camera.frame;
-  }
-  // ========== Configuration Getters ==========
-  /** Get scene width in pixels. */
-  getWidth() {
-    return this.config.width;
-  }
-  /** Get scene height in pixels. */
-  getHeight() {
-    return this.config.height;
-  }
-  /** Get scene background color. */
-  getBackgroundColor() {
-    return this.config.backgroundColor;
-  }
-  /** Get scene frame rate. */
-  getFrameRate() {
-    return this.config.frameRate;
+  get length() {
+    return this.getSubmobjects().length;
   }
-  // ========== Mobject Management ==========
-  /**
-   * Add mobjects to the scene and make them immediately visible.
-   * Use this for static elements or backgrounds that should be visible
-   * before any animations begin.
-   */
   add(...mobjects) {
-    for (const m of mobjects) {
-      this.mobjects.add(m);
-      m.setOpacity(1);
-    }
+    this.addSubmobjects(...mobjects);
     return this;
   }
-  /**
-   * Remove mobjects from the scene.
-   */
-  remove(...mobjects) {
-    for (const m of mobjects) {
-      this.mobjects.delete(m);
-    }
+  remove(mobject) {
+    this.removeSubmobject(mobject);
     return this;
   }
-  /**
-   * Check if a mobject is registered with this scene.
-   */
-  has(mobject) {
-    return this.mobjects.has(mobject);
+  clear() {
+    this.clearSubmobjects();
+    return this;
   }
-  /**
-   * Get all mobjects in the scene.
-   */
-  getMobjects() {
-    return [...this.mobjects];
+  getChildren() {
+    return this.getSubmobjects().filter((m) => m instanceof VMobject);
   }
-  // ========== Animation Scheduling ==========
-  /**
-   * Schedule animations to play at the current playhead position.
-   * 
-   * Accepts either Animation objects or Mobjects with queued fluent animations.
-   * When a Mobject is passed, its queued animation chain is automatically extracted.
-   * 
-   * - Introductory animations (FadeIn, Create, Draw, Write) auto-register
-   *   their targets with the scene if not already present.
-   * - Transformative animations (MoveTo, Rotate, Scale) require the target
-   *   to already be in the scene, otherwise an error is thrown.
-   * 
-   * @example
-   * // ProAPI style
-   * this.play(new FadeIn(circle), new MoveTo(rect, 2, 0));
-   * 
-   * // FluentAPI style
-   * circle.fadeIn(1).moveTo(2, 0, 1);
-   * this.play(circle);
-   * 
-   * // Mixed
-   * circle.fadeIn(1);
-   * this.play(circle, new FadeIn(rect));
-   */
-  play(...items) {
-    if (items.length === 0) {
-      return this;
+  get(index) {
+    return this.getChildren()[index];
+  }
+  show() {
+    super.show();
+    for (const child of this.getChildren()) {
+      child.show();
     }
-    const animations = items.map((item) => {
-      if (item instanceof Mobject) {
-        return item.toAnimation();
-      }
-      return item;
-    });
-    for (const anim of animations) {
-      this.validateAndRegisterAnimation(anim);
+    return this;
+  }
+  hide() {
+    super.hide();
+    for (const child of this.getChildren()) {
+      child.hide();
     }
-    this.timeline.scheduleParallel(animations, this.playheadTime);
-    const maxDuration = getLongestAnimationTotalTime(animations);
-    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;
   }
   /**
-   * Add a delay before the next play() call.
-   * @param seconds Number of seconds to wait
+   * Sets the opacity for this VGroup and all children.
+   * @param value - The opacity value (0-1).
+   * @returns this for chaining.
    */
-  wait(seconds) {
-    if (seconds < 0) {
-      throw new Error("Wait duration must be non-negative");
+  setOpacity(value) {
+    super.setOpacity(value);
+    for (const child of this.getChildren()) {
+      child.setOpacity(value);
     }
-    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;
   }
   /**
-   * Get the current playhead time.
+   * Sets the stroke color and width for this VGroup and all children.
+   * @param color - The stroke color.
+   * @param width - The stroke width. Default is 2.
+   * @returns this for chaining.
    */
-  getCurrentTime() {
-    return this.playheadTime;
+  stroke(color, width = 2) {
+    super.stroke(color, width);
+    for (const child of this.getChildren()) {
+      child.stroke(color, width);
+    }
+    return this;
   }
   /**
-   * Get the total duration of all scheduled animations.
+   * Sets the fill color and opacity for this VGroup and all children.
+   * @param color - The fill color.
+   * @param opacity - The fill opacity. Default is 1 (fully opaque).
+   * @returns this for chaining.
    */
-  getTotalDuration() {
-    return this.timeline.getTotalDuration();
+  fill(color, opacity = 1) {
+    super.fill(color, opacity);
+    for (const child of this.getChildren()) {
+      child.fill(color, opacity);
+    }
+    return this;
   }
-  // ========== ProAPI Access ==========
-  /**
-   * Get the underlying Timeline for advanced control.
-   * Use this for direct manipulation of animation timing.
-   */
-  getTimeline() {
-    return this.timeline;
+  getBoundingBox() {
+    const children = this.getChildren();
+    if (children.length === 0) {
+      return super.getBoundingBox();
+    }
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const child of children) {
+      const bounds = child.getBoundingBox();
+      if (bounds.minX < minX) minX = bounds.minX;
+      if (bounds.maxX > maxX) maxX = bounds.maxX;
+      if (bounds.minY < minY) minY = bounds.minY;
+      if (bounds.maxY > maxY) maxY = bounds.maxY;
+    }
+    return { minX, maxX, minY, maxY };
   }
-  /**
-   * Get the Camera for view control and frame dimensions.
-   * Camera calculates Manim-compatible frame dimensions from pixel resolution.
-   */
-  getCamera() {
-    return this._camera;
+  center() {
+    centerGroup(this);
+    return this;
   }
-  /**
-   * Get the list of segments emitted by play() and wait() calls.
-   * Used by the Renderer for cache-aware segmented rendering.
-   */
-  getSegments() {
-    return this.segmentList;
+  toCorner(corner, buff = 0) {
+    toCorner(this, corner, buff);
+    return this;
   }
-  // ========== Private Helpers ==========
-  /**
-   * Validates and registers animation targets based on lifecycle.
-   * Handles composition animations (Sequence, Parallel) by processing children.
-   */
-  validateAndRegisterAnimation(anim) {
-    const children = getAnimationChildren(anim);
-    if (children.length > 0) {
-      for (const child of children) {
-        this.validateAndRegisterAnimation(child);
-      }
-      return;
-    }
-    const target = anim.getTarget();
-    switch (anim.lifecycle) {
-      case "introductory":
-        if (!this.mobjects.has(target)) {
-          this.mobjects.add(target);
-        }
-        break;
-      case "transformative":
-      case "exit":
-        if (target instanceof CameraFrame) {
-          break;
-        }
-        if (!this.isInScene(target)) {
-          throw new AnimationTargetNotInSceneError(anim, target);
-        }
-        break;
-    }
+  arrange(direction = "RIGHT", buff = 0.25, shouldCenter = true) {
+    arrangeChildren(this, direction, buff, shouldCenter);
+    return this;
   }
-  /**
-   * 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) {
-    if (this.mobjects.has(mobject)) {
-      return true;
-    }
-    let current = mobject.parent;
-    while (current !== null) {
-      if (this.mobjects.has(current)) {
-        return true;
-      }
-      current = current.parent;
-    }
-    return false;
+  alignTo(target, edge) {
+    alignToTarget(this, target, edge);
+    return this;
   }
-  /**
-   * 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)
-    );
+  computeHash() {
+    return super.computeHash();
   }
 };
 
@@ -3907,27 +4046,39 @@ var Arc = class extends VMobject {
     let currentAngle = this.startAngle;
     const startX = this.radius * Math.cos(currentAngle);
     const startY = this.radius * Math.sin(currentAngle);
-    path.moveTo(new Vector2(startX, startY));
+    path.moveTo(new Vector(startX, startY));
     for (let i = 0; i < numSegments; i++) {
       const alpha = currentAngle;
       const nextAngle = currentAngle + stepAngle;
-      const p3 = new Vector2(
+      const p3 = new Vector(
         this.radius * Math.cos(nextAngle),
         this.radius * Math.sin(nextAngle)
       );
-      const cp1 = new Vector2(
+      const cp1 = new Vector(
         this.radius * Math.cos(alpha),
         this.radius * Math.sin(alpha)
       ).add(
-        new Vector2(-Math.sin(alpha), Math.cos(alpha)).multiply(this.radius * k)
+        new Vector(-Math.sin(alpha), Math.cos(alpha)).multiply(this.radius * k)
       );
       const cp2 = p3.subtract(
-        new Vector2(-Math.sin(nextAngle), Math.cos(nextAngle)).multiply(this.radius * k)
+        new Vector(-Math.sin(nextAngle), Math.cos(nextAngle)).multiply(this.radius * k)
       );
       path.cubicTo(cp1, cp2, p3);
       currentAngle += stepAngle;
     }
-    this.pathList = [path];
+    this.paths = [path];
+  }
+};
+
+// src/core/mobjects/geometry/Circle.ts
+var Circle = class extends Arc {
+  constructor(radius = 1) {
+    super(radius, 0, Math.PI * 2);
+    const firstPath = this.paths[0];
+    if (firstPath) {
+      firstPath.closePath();
+      this.paths = [firstPath];
+    }
   }
 };
 
@@ -3937,51 +4088,15 @@ var Line = class extends VMobject {
   end;
   constructor(x1 = 0, y1 = 0, x2 = 1, y2 = 0) {
     super();
-    this.start = new Vector2(x1, y1);
-    this.end = new Vector2(x2, y2);
+    this.start = new Vector(x1, y1);
+    this.end = new Vector(x2, y2);
     this.generatePath();
   }
   generatePath() {
     const path = new BezierPath();
     path.moveTo(this.start);
     path.lineTo(this.end);
-    this.pathList = [path];
-  }
-};
-
-// src/core/mobjects/geometry/Arrow.ts
-var Arrow = class extends Line {
-  constructor(x1 = 0, y1 = 0, x2 = 1, y2 = 0, tipLength = 0.25, tipAngle = Math.PI / 6) {
-    super(x1, y1, x2, y2);
-    this.tipLength = tipLength;
-    this.tipAngle = tipAngle;
-    this.addTip();
-  }
-  addTip() {
-    const direction = this.end.subtract(this.start);
-    if (direction.length() === 0) return;
-    const normalizedDir = direction.normalize();
-    const angle = Math.atan2(normalizedDir.y, normalizedDir.x);
-    const angle1 = angle + Math.PI - this.tipAngle;
-    const angle2 = angle + Math.PI + this.tipAngle;
-    const p1 = this.end.add(new Vector2(Math.cos(angle1), Math.sin(angle1)).multiply(this.tipLength));
-    const p2 = this.end.add(new Vector2(Math.cos(angle2), Math.sin(angle2)).multiply(this.tipLength));
-    const tipPath = new BezierPath();
-    tipPath.moveTo(this.end);
-    tipPath.lineTo(p1);
-    tipPath.lineTo(p2);
-    tipPath.closePath();
-    this.addPath(tipPath);
-  }
-};
-
-// src/core/mobjects/geometry/Circle.ts
-var Circle = class extends Arc {
-  constructor(radius = 1) {
-    super(radius, 0, Math.PI * 2);
-    if (this.pathList.length > 0) {
-      this.pathList[0].closePath();
-    }
+    this.paths = [path];
   }
 };
 
@@ -3990,7 +4105,7 @@ var Polygon = class extends VMobject {
   vertices;
   constructor(...points) {
     super();
-    this.vertices = points.map(([x, y]) => new Vector2(x, y));
+    this.vertices = points.map(([x, y]) => new Vector(x, y));
     this.generatePath();
   }
   generatePath() {
@@ -4001,7 +4116,7 @@ var Polygon = class extends VMobject {
       path.lineTo(this.vertices[i]);
     }
     path.closePath();
-    this.pathList = [path];
+    this.paths = [path];
   }
 };
 
@@ -4025,6 +4140,32 @@ var Rectangle = class extends Polygon {
   }
 };
 
+// src/core/mobjects/geometry/Arrow.ts
+var Arrow = class extends Line {
+  constructor(x1 = 0, y1 = 0, x2 = 1, y2 = 0, tipLength = 0.25, tipAngle = Math.PI / 6) {
+    super(x1, y1, x2, y2);
+    this.tipLength = tipLength;
+    this.tipAngle = tipAngle;
+    this.addTip();
+  }
+  addTip() {
+    const direction = this.end.subtract(this.start);
+    if (direction.length() === 0) return;
+    const normalizedDir = direction.normalize();
+    const angle = Math.atan2(normalizedDir.y, normalizedDir.x);
+    const angle1 = angle + Math.PI - this.tipAngle;
+    const angle2 = angle + Math.PI + this.tipAngle;
+    const p1 = this.end.add(new Vector(Math.cos(angle1), Math.sin(angle1)).multiply(this.tipLength));
+    const p2 = this.end.add(new Vector(Math.cos(angle2), Math.sin(angle2)).multiply(this.tipLength));
+    const tipPath = new BezierPath();
+    tipPath.moveTo(this.end);
+    tipPath.lineTo(p1);
+    tipPath.lineTo(p2);
+    tipPath.closePath();
+    this.addPath(tipPath);
+  }
+};
+
 // src/core/mobjects/text/Text.ts
 import * as fontkit from "fontkit";
 import { join as join2, resolve } from "path";
@@ -4041,18 +4182,18 @@ function convertFontkitPath(fontkitPath, scale, offsetX, offsetY) {
     if (type === "moveTo" && args.length >= 2) {
       const x = args[0] ?? 0;
       const y = args[1] ?? 0;
-      path.moveTo(new Vector2(transformX(x), transformY(y)));
+      path.moveTo(new Vector(transformX(x), transformY(y)));
     } else if (type === "lineTo" && args.length >= 2) {
       const x = args[0] ?? 0;
       const y = args[1] ?? 0;
-      path.lineTo(new Vector2(transformX(x), transformY(y)));
+      path.lineTo(new Vector(transformX(x), transformY(y)));
     } else if (type === "quadraticCurveTo" && args.length >= 4) {
       const cpx = args[0] ?? 0;
       const cpy = args[1] ?? 0;
       const x = args[2] ?? 0;
       const y = args[3] ?? 0;
-      const cp = new Vector2(transformX(cpx), transformY(cpy));
-      const end = new Vector2(transformX(x), transformY(y));
+      const cp = new Vector(transformX(cpx), transformY(cpy));
+      const end = new Vector(transformX(x), transformY(y));
       path.quadraticTo(cp, end);
     } else if (type === "bezierCurveTo" && args.length >= 6) {
       const cp1x = args[0] ?? 0;
@@ -4061,9 +4202,9 @@ function convertFontkitPath(fontkitPath, scale, offsetX, offsetY) {
       const cp2y = args[3] ?? 0;
       const x = args[4] ?? 0;
       const y = args[5] ?? 0;
-      const cp1 = new Vector2(transformX(cp1x), transformY(cp1y));
-      const cp2 = new Vector2(transformX(cp2x), transformY(cp2y));
-      const end = new Vector2(transformX(x), transformY(y));
+      const cp1 = new Vector(transformX(cp1x), transformY(cp1y));
+      const cp2 = new Vector(transformX(cp2x), transformY(cp2y));
+      const end = new Vector(transformX(x), transformY(y));
       path.cubicTo(cp1, cp2, end);
     } else if (type === "closePath") {
       path.closePath();
@@ -4160,9 +4301,6 @@ var GraphNode = class extends VMobject {
     super();
     this.id = id;
     this.nodeRadius = config.radius ?? DEFAULT_RADIUS;
-    if (config.position) {
-      this.pos(config.position.x, config.position.y);
-    }
     if (config.strokeColor !== void 0) {
       this.strokeColor = config.strokeColor;
     }
@@ -4176,6 +4314,9 @@ var GraphNode = class extends VMobject {
       this.fillOpacity = config.fillOpacity;
     }
     this.generateCirclePath();
+    if (config.position) {
+      this.pos(config.position.x, config.position.y);
+    }
   }
   get radius() {
     return this.nodeRadius;
@@ -4188,29 +4329,29 @@ var GraphNode = class extends VMobject {
     const path = new BezierPath();
     const r = this.nodeRadius;
     const k = 0.5522847498;
-    path.moveTo(new Vector2(r, 0));
+    path.moveTo(new Vector(r, 0));
     path.cubicTo(
-      new Vector2(r, r * k),
-      new Vector2(r * k, r),
-      new Vector2(0, r)
+      new Vector(r, r * k),
+      new Vector(r * k, r),
+      new Vector(0, r)
     );
     path.cubicTo(
-      new Vector2(-r * k, r),
-      new Vector2(-r, r * k),
-      new Vector2(-r, 0)
+      new Vector(-r * k, r),
+      new Vector(-r, r * k),
+      new Vector(-r, 0)
     );
     path.cubicTo(
-      new Vector2(-r, -r * k),
-      new Vector2(-r * k, -r),
-      new Vector2(0, -r)
+      new Vector(-r, -r * k),
+      new Vector(-r * k, -r),
+      new Vector(0, -r)
     );
     path.cubicTo(
-      new Vector2(r * k, -r),
-      new Vector2(r, -r * k),
-      new Vector2(r, 0)
+      new Vector(r * k, -r),
+      new Vector(r, -r * k),
+      new Vector(r, 0)
     );
     path.closePath();
-    this.pathList = [path];
+    this.paths = [path];
   }
   getCenter() {
     return this.position;
@@ -4249,14 +4390,14 @@ var GraphEdge = class extends VMobject {
     if (this.curved) {
       const mid = startPos.lerp(endPos, 0.5);
       const direction = endPos.subtract(startPos);
-      const perpendicular = new Vector2(-direction.y, direction.x).normalize();
+      const perpendicular = new Vector(-direction.y, direction.x).normalize();
       const curveOffset = direction.length() * 0.2;
       const controlPoint = mid.add(perpendicular.multiply(curveOffset));
       path.quadraticTo(controlPoint, endPos);
     } else {
       path.lineTo(endPos);
     }
-    this.pathList = [path];
+    this.paths = [path];
   }
   getPath() {
     return this.pathList[0];
@@ -4284,7 +4425,7 @@ function circularLayout(nodes, config = {}) {
     const y = radius * Math.sin(angle);
     const node = nodes[i];
     if (node) {
-      positions.set(node.id, new Vector2(x, y));
+      positions.set(node.id, new Vector(x, y));
     }
   }
   return positions;
@@ -4344,7 +4485,7 @@ function assignPositions(node, leftBound, spacing) {
   }
 }
 function collectPositions(node, levelHeight, positions) {
-  positions.set(node.id, new Vector2(node.x, node.depth * levelHeight));
+  positions.set(node.id, new Vector(node.x, node.depth * levelHeight));
   for (const child of node.children) {
     collectPositions(child, levelHeight, positions);
   }
@@ -4362,7 +4503,7 @@ function treeLayout(nodes, edges, config = {}) {
   const maxX = Math.max(...allX);
   const centerOffset = (minX + maxX) / 2;
   for (const [id, pos] of positions) {
-    positions.set(id, new Vector2(pos.x - centerOffset, pos.y));
+    positions.set(id, new Vector(pos.x - centerOffset, pos.y));
   }
   return positions;
 }
@@ -4388,13 +4529,13 @@ function forceDirectedLayout(nodes, edges, config = {}) {
     const node = nodes[i];
     if (node) {
       const angle = 2 * Math.PI * i / nodes.length;
-      const initialPos = new Vector2(
+      const initialPos = new Vector(
         Math.cos(angle) * 2,
         Math.sin(angle) * 2
       );
       states.set(node.id, {
         position: initialPos,
-        velocity: Vector2.ZERO
+        velocity: Vector.ZERO
       });
     }
   }
@@ -4406,7 +4547,7 @@ function forceDirectedLayout(nodes, edges, config = {}) {
   for (let iter = 0; iter < iterations; iter++) {
     const forces = /* @__PURE__ */ new Map();
     for (const node of nodes) {
-      forces.set(node.id, Vector2.ZERO);
+      forces.set(node.id, Vector.ZERO);
     }
     for (let i = 0; i < nodes.length; i++) {
       for (let j = i + 1; j < nodes.length; j++) {
@@ -4419,8 +4560,8 @@ function forceDirectedLayout(nodes, edges, config = {}) {
         const delta = stateA.position.subtract(stateB.position);
         const distance = Math.max(delta.length(), minDistance);
         const force = delta.normalize().multiply(repulsion / (distance * distance));
-        const forceA = forces.get(nodeA.id) ?? Vector2.ZERO;
-        const forceB = forces.get(nodeB.id) ?? Vector2.ZERO;
+        const forceA = forces.get(nodeA.id) ?? Vector.ZERO;
+        const forceB = forces.get(nodeB.id) ?? Vector.ZERO;
         forces.set(nodeA.id, forceA.add(force));
         forces.set(nodeB.id, forceB.subtract(force));
       }
@@ -4433,8 +4574,8 @@ function forceDirectedLayout(nodes, edges, config = {}) {
       const distance = delta.length();
       const displacement = distance - springLength;
       const force = delta.normalize().multiply(displacement * attraction);
-      const forceA = forces.get(edge.source) ?? Vector2.ZERO;
-      const forceB = forces.get(edge.target) ?? Vector2.ZERO;
+      const forceA = forces.get(edge.source) ?? Vector.ZERO;
+      const forceB = forces.get(edge.target) ?? Vector.ZERO;
       forces.set(edge.source, forceA.add(force));
       forces.set(edge.target, forceB.subtract(force));
     }
@@ -4483,87 +4624,448 @@ var Graph = class extends VGroup {
     for (const edge of connectedEdges) {
       this.removeEdgeInternal(edge);
     }
-    this.nodes.delete(id);
-    this.remove(node);
+    this.nodes.delete(id);
+    this.remove(node);
+    return this;
+  }
+  getNode(id) {
+    return this.nodes.get(id);
+  }
+  getNodes() {
+    return Array.from(this.nodes.values());
+  }
+  addEdge(sourceId, targetId, config = {}) {
+    const sourceNode = this.nodes.get(sourceId);
+    const targetNode = this.nodes.get(targetId);
+    if (!sourceNode || !targetNode) {
+      return void 0;
+    }
+    const existing = this.edges.find(
+      (e) => e.source === sourceId && e.target === targetId || e.source === targetId && e.target === sourceId
+    );
+    if (existing) return existing;
+    const edge = new GraphEdge(sourceNode, targetNode, config);
+    this.edges.push(edge);
+    this.add(edge);
+    return edge;
+  }
+  removeEdge(sourceId, targetId) {
+    const edge = this.edges.find(
+      (e) => e.source === sourceId && e.target === targetId || e.source === targetId && e.target === sourceId
+    );
+    if (edge) {
+      this.removeEdgeInternal(edge);
+    }
+    return this;
+  }
+  removeEdgeInternal(edge) {
+    const index = this.edges.indexOf(edge);
+    if (index > -1) {
+      this.edges.splice(index, 1);
+      this.remove(edge);
+    }
+  }
+  getEdgePath(sourceId, targetId) {
+    const edge = this.edges.find(
+      (e) => e.source === sourceId && e.target === targetId || e.source === targetId && e.target === sourceId
+    );
+    return edge?.getPath();
+  }
+  getEdges() {
+    return [...this.edges];
+  }
+  /** Applies a layout algorithm to reposition all nodes. */
+  layout(type, config = {}) {
+    const nodeArray = this.getNodes();
+    let positions;
+    switch (type) {
+      case "circular":
+        positions = circularLayout(nodeArray, config);
+        break;
+      case "tree":
+        positions = treeLayout(nodeArray, this.edges, config);
+        break;
+      case "force-directed":
+        positions = forceDirectedLayout(nodeArray, this.edges, config);
+        break;
+      default:
+        positions = /* @__PURE__ */ new Map();
+    }
+    for (const [id, position] of positions) {
+      const node = this.nodes.get(id);
+      if (node) {
+        node.pos(position.x, position.y);
+      }
+    }
+    this.updateEdges();
+    return this;
+  }
+  updateEdges() {
+    for (const edge of this.edges) {
+      edge.updatePath();
+    }
+    return this;
+  }
+};
+
+// src/core/updaters/UpdaterEngine.ts
+var UpdaterEngine = class {
+  lastTime = null;
+  frame = 0;
+  reset() {
+    this.lastTime = null;
+    this.frame = 0;
+  }
+  run(scene, roots, time) {
+    const clampedTime = Math.max(0, time);
+    const rawDelta = this.lastTime === null ? 0 : clampedTime - this.lastTime;
+    const discontinuous = this.lastTime === null || rawDelta < 0;
+    const dt = discontinuous ? 0 : rawDelta;
+    const ctx = {
+      time: clampedTime,
+      dt,
+      frame: this.frame,
+      scene,
+      discontinuous
+    };
+    const visited = /* @__PURE__ */ new Set();
+    for (const root of roots) {
+      this.runMobjectTree(root, ctx, visited);
+    }
+    this.lastTime = clampedTime;
+    this.frame += 1;
+  }
+  runMobjectTree(mobject, ctx, visited) {
+    if (visited.has(mobject)) {
+      return;
+    }
+    visited.add(mobject);
+    const updaters = mobject.getUpdaterRecordsSnapshot();
+    for (const updater of updaters) {
+      updater.fn(mobject, ctx);
+    }
+    const children = mobject.getSubmobjects();
+    for (const child of children) {
+      this.runMobjectTree(child, ctx, visited);
+    }
+  }
+};
+
+// src/core/errors/AnimationErrors.ts
+var AnimationTargetNotInSceneError = class extends Error {
+  animationName;
+  targetType;
+  constructor(animation, target) {
+    const animName = animation.constructor.name;
+    const targetType = target.constructor.name;
+    super(
+      `Cannot apply '${animName}' animation to ${targetType}: target is not in scene.
+
+This animation requires the target to already exist in the scene because it transforms an existing object rather than introducing a new one.
+
+Solutions:
+  1. Call scene.add(target) before this animation
+  2. Use an introductory animation first:
+     - FadeIn: Fades the object in from transparent
+     - Create: Draws the object's path progressively
+     - Draw: Draws border then fills
+     - Write: Draws text progressively
+
+Example:
+  // Option 1: Use add() for immediate visibility
+  scene.add(circle);
+  scene.play(new MoveTo(circle, 2, 0));
+
+  // Option 2: Use introductory animation
+  scene.play(new FadeIn(circle));
+  scene.play(new MoveTo(circle, 2, 0));`
+    );
+    this.name = "AnimationTargetNotInSceneError";
+    this.animationName = animName;
+    this.targetType = targetType;
+  }
+};
+
+// src/core/scene/Scene.ts
+var Scene = class {
+  config;
+  mobjects = /* @__PURE__ */ new Set();
+  timeline;
+  _camera;
+  updaterEngine;
+  segmentList = [];
+  playheadTime = 0;
+  constructor(config = {}) {
+    this.config = {
+      width: config.width ?? 1920,
+      height: config.height ?? 1080,
+      backgroundColor: config.backgroundColor ?? Color.BLACK,
+      frameRate: config.frameRate ?? 60
+    };
+    this.timeline = new Timeline();
+    this._camera = new Camera({
+      pixelWidth: this.config.width,
+      pixelHeight: this.config.height
+    });
+    this.updaterEngine = new UpdaterEngine();
+  }
+  // ========== Camera Shortcuts ==========
+  get camera() {
+    return this._camera;
+  }
+  get frame() {
+    return this._camera.frame;
+  }
+  // ========== Configuration Getters ==========
+  /** Get scene width in pixels. */
+  getWidth() {
+    return this.config.width;
+  }
+  /** Get scene height in pixels. */
+  getHeight() {
+    return this.config.height;
+  }
+  /** Get scene background color. */
+  getBackgroundColor() {
+    return this.config.backgroundColor;
+  }
+  /** Get scene frame rate. */
+  getFrameRate() {
+    return this.config.frameRate;
+  }
+  // ========== Mobject Management ==========
+  /**
+   * Add mobjects to the scene and make them immediately visible.
+   * Use this for static elements or backgrounds that should be visible
+   * before any animations begin.
+   */
+  add(...mobjects) {
+    for (const m of mobjects) {
+      this.mobjects.add(m);
+      m.setOpacity(1);
+    }
     return this;
   }
-  getNode(id) {
-    return this.nodes.get(id);
+  /**
+   * Remove mobjects from the scene.
+   */
+  remove(...mobjects) {
+    for (const m of mobjects) {
+      this.mobjects.delete(m);
+    }
+    return this;
   }
-  getNodes() {
-    return Array.from(this.nodes.values());
+  /**
+   * Check if a mobject is registered with this scene.
+   */
+  has(mobject) {
+    return this.mobjects.has(mobject);
   }
-  addEdge(sourceId, targetId, config = {}) {
-    const sourceNode = this.nodes.get(sourceId);
-    const targetNode = this.nodes.get(targetId);
-    if (!sourceNode || !targetNode) {
-      return void 0;
+  /**
+   * Get all mobjects in the scene.
+   */
+  getMobjects() {
+    return [...this.mobjects];
+  }
+  // ========== Animation Scheduling ==========
+  /**
+   * Schedule animations to play at the current playhead position.
+   * 
+   * Accepts either Animation objects or Mobjects with queued fluent animations.
+   * When a Mobject is passed, its queued animation chain is automatically extracted.
+   * 
+   * - Introductory animations (FadeIn, Create, Draw, Write) auto-register
+   *   their targets with the scene if not already present.
+   * - Transformative animations (MoveTo, Rotate, Scale) require the target
+   *   to already be in the scene, otherwise an error is thrown.
+   * 
+   * @example
+   * // ProAPI style
+   * this.play(new FadeIn(circle), new MoveTo(rect, 2, 0));
+   * 
+   * // FluentAPI style
+   * circle.fadeIn(1).moveTo(2, 0, 1);
+   * this.play(circle);
+   * 
+   * // Mixed
+   * circle.fadeIn(1);
+   * this.play(circle, new FadeIn(rect));
+   */
+  play(...items) {
+    if (items.length === 0) {
+      return this;
     }
-    const existing = this.edges.find(
-      (e) => e.source === sourceId && e.target === targetId || e.source === targetId && e.target === sourceId
-    );
-    if (existing) return existing;
-    const edge = new GraphEdge(sourceNode, targetNode, config);
-    this.edges.push(edge);
-    this.add(edge);
-    return edge;
+    const animations = items.map((item) => {
+      if (item instanceof Mobject) {
+        return item.toAnimation();
+      }
+      return item;
+    });
+    for (const anim of animations) {
+      this.validateAndRegisterAnimation(anim);
+    }
+    this.timeline.scheduleParallel(animations, this.playheadTime);
+    const maxDuration = getLongestAnimationTotalTime(animations);
+    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;
   }
-  removeEdge(sourceId, targetId) {
-    const edge = this.edges.find(
-      (e) => e.source === sourceId && e.target === targetId || e.source === targetId && e.target === sourceId
-    );
-    if (edge) {
-      this.removeEdgeInternal(edge);
+  /**
+   * Add a delay before the next play() call.
+   * @param seconds Number of seconds to wait
+   */
+  wait(seconds) {
+    if (seconds < 0) {
+      throw new Error("Wait duration must be non-negative");
     }
+    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;
   }
-  removeEdgeInternal(edge) {
-    const index = this.edges.indexOf(edge);
-    if (index > -1) {
-      this.edges.splice(index, 1);
-      this.remove(edge);
+  /**
+   * Get the current playhead time.
+   */
+  getCurrentTime() {
+    return this.playheadTime;
+  }
+  /**
+   * Get the total duration of all scheduled animations.
+   */
+  getTotalDuration() {
+    return this.timeline.getTotalDuration();
+  }
+  /**
+   * Evaluates scene state at an absolute time.
+   * Execution order is deterministic:
+   * 1) timeline animations
+   * 2) mobject updaters
+   */
+  evaluateFrame(time) {
+    const clampedTime = Math.max(0, time);
+    this.timeline.seek(clampedTime);
+    const roots = [...this.mobjects];
+    roots.push(this._camera.frame);
+    this.updaterEngine.run(this, roots, clampedTime);
+  }
+  /**
+   * Returns true if any scene mobject (or camera frame) has active updaters.
+   * Used by renderer to disable unsafe segment caching.
+   */
+  hasActiveUpdaters() {
+    if (this._camera.frame.hasActiveUpdaters(true)) {
+      return true;
     }
+    for (const mobject of this.mobjects) {
+      if (mobject.hasActiveUpdaters(true)) {
+        return true;
+      }
+    }
+    return false;
   }
-  getEdgePath(sourceId, targetId) {
-    const edge = this.edges.find(
-      (e) => e.source === sourceId && e.target === targetId || e.source === targetId && e.target === sourceId
-    );
-    return edge?.getPath();
+  // ========== ProAPI Access ==========
+  /**
+   * Get the underlying Timeline for advanced control.
+   * Use this for direct manipulation of animation timing.
+   */
+  getTimeline() {
+    return this.timeline;
   }
-  getEdges() {
-    return [...this.edges];
+  /**
+   * Get the Camera for view control and frame dimensions.
+   * Camera calculates Manim-compatible frame dimensions from pixel resolution.
+   */
+  getCamera() {
+    return this._camera;
   }
-  /** Applies a layout algorithm to reposition all nodes. */
-  layout(type, config = {}) {
-    const nodeArray = this.getNodes();
-    let positions;
-    switch (type) {
-      case "circular":
-        positions = circularLayout(nodeArray, config);
-        break;
-      case "tree":
-        positions = treeLayout(nodeArray, this.edges, config);
+  /**
+   * 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.
+   * Handles composition animations (Sequence, Parallel) by processing children.
+   */
+  validateAndRegisterAnimation(anim) {
+    const children = getAnimationChildren(anim);
+    if (children.length > 0) {
+      for (const child of children) {
+        this.validateAndRegisterAnimation(child);
+      }
+      return;
+    }
+    const target = anim.getTarget();
+    switch (anim.lifecycle) {
+      case "introductory":
+        if (!this.mobjects.has(target)) {
+          this.mobjects.add(target);
+        }
         break;
-      case "force-directed":
-        positions = forceDirectedLayout(nodeArray, this.edges, config);
+      case "transformative":
+      case "exit":
+        if (target instanceof CameraFrame) {
+          break;
+        }
+        if (!this.isInScene(target)) {
+          throw new AnimationTargetNotInSceneError(anim, target);
+        }
         break;
-      default:
-        positions = /* @__PURE__ */ new Map();
     }
-    for (const [id, position] of positions) {
-      const node = this.nodes.get(id);
-      if (node) {
-        node.pos(position.x, position.y);
+  }
+  /**
+   * 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) {
+    if (this.mobjects.has(mobject)) {
+      return true;
+    }
+    let current = mobject.parent;
+    while (current !== null) {
+      if (this.mobjects.has(current)) {
+        return true;
       }
+      current = current.parent;
     }
-    this.updateEdges();
-    return this;
+    return false;
   }
-  updateEdges() {
-    for (const edge of this.edges) {
-      edge.updatePath();
-    }
-    return this;
+  /**
+   * 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)
+    );
   }
 };
 
@@ -4573,17 +5075,12 @@ import { createCanvas } from "@napi-rs/canvas";
 // src/core/renderer/drawMobject.ts
 function drawMobject(ctx, mobject, worldToScreen) {
   if (mobject.opacity <= 0) return;
-  if (mobject instanceof VGroup) {
-    drawVGroup(ctx, mobject, worldToScreen);
-  } else if (mobject instanceof VMobject) {
+  ctx.save();
+  ctx.globalAlpha *= mobject.opacity;
+  if (mobject instanceof VMobject) {
     drawVMobject(ctx, mobject, worldToScreen);
   }
-}
-function drawVGroup(ctx, vgroup, worldToScreen) {
-  if (vgroup.opacity <= 0) return;
-  ctx.save();
-  ctx.globalAlpha *= vgroup.opacity;
-  for (const child of vgroup.getChildren()) {
+  for (const child of mobject.getSubmobjects()) {
     drawMobject(ctx, child, worldToScreen);
   }
   ctx.restore();
@@ -4591,10 +5088,7 @@ function drawVGroup(ctx, vgroup, worldToScreen) {
 function drawVMobject(ctx, vmobject, worldToScreen) {
   const paths = vmobject.paths;
   if (paths.length === 0) return;
-  const mobjectWorld = vmobject.getWorldMatrix();
-  const transform = worldToScreen.multiply(mobjectWorld);
-  ctx.save();
-  ctx.globalAlpha *= vmobject.opacity;
+  const transform = worldToScreen.multiply(vmobject.getRenderMatrix());
   for (const path of paths) {
     const commands = path.getCommands();
     if (commands.length === 0) continue;
@@ -4614,34 +5108,33 @@ function drawVMobject(ctx, vmobject, worldToScreen) {
       ctx.stroke();
     }
   }
-  ctx.restore();
 }
 function applyPathCommands(ctx, commands, transform) {
   for (const cmd of commands) {
     switch (cmd.type) {
       case "Move": {
-        const p = transform.transformPoint(cmd.end);
+        const p = transform.transformPoint2D(cmd.end);
         ctx.moveTo(p.x, p.y);
         break;
       }
       case "Line": {
-        const p = transform.transformPoint(cmd.end);
+        const p = transform.transformPoint2D(cmd.end);
         ctx.lineTo(p.x, p.y);
         break;
       }
       case "Quadratic": {
         if (cmd.control1) {
-          const cp = transform.transformPoint(cmd.control1);
-          const ep = transform.transformPoint(cmd.end);
+          const cp = transform.transformPoint2D(cmd.control1);
+          const ep = transform.transformPoint2D(cmd.end);
           ctx.quadraticCurveTo(cp.x, cp.y, ep.x, ep.y);
         }
         break;
       }
       case "Cubic": {
         if (cmd.control1 && cmd.control2) {
-          const cp1 = transform.transformPoint(cmd.control1);
-          const cp2 = transform.transformPoint(cmd.control2);
-          const ep = transform.transformPoint(cmd.end);
+          const cp1 = transform.transformPoint2D(cmd.control1);
+          const cp2 = transform.transformPoint2D(cmd.control2);
+          const ep = transform.transformPoint2D(cmd.end);
           ctx.bezierCurveTo(cp1.x, cp1.y, cp2.x, cp2.y, ep.x, ep.y);
         }
         break;
@@ -4681,10 +5174,11 @@ var FrameRenderer = class {
     const camera = this.scene.getCamera();
     const viewMatrix = camera.getViewMatrix();
     const scale = this.height / MANIM_FRAME_HEIGHT;
-    const scaleMatrix = Matrix3x3.scale(scale, -scale);
-    const translateToCenter = Matrix3x3.translation(
+    const scaleMatrix = Matrix4x4.scale(scale, -scale, 1);
+    const translateToCenter = Matrix4x4.translation(
       this.width / 2,
-      this.height / 2
+      this.height / 2,
+      0
     );
     return translateToCenter.multiply(scaleMatrix).multiply(viewMatrix);
   }
@@ -4694,8 +5188,7 @@ var FrameRenderer = class {
   renderFrame(time) {
     const canvas = createCanvas(this.width, this.height);
     const ctx = canvas.getContext("2d");
-    const timeline = this.scene.getTimeline();
-    timeline.seek(time);
+    this.scene.evaluateFrame(time);
     const bgColor = this.scene.getBackgroundColor();
     ctx.fillStyle = `rgb(${bgColor.r}, ${bgColor.g}, ${bgColor.b})`;
     ctx.fillRect(0, 0, this.width, this.height);
@@ -4927,7 +5420,7 @@ var Renderer = class {
     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;
+    const useCache = resolved.cache && isVideoFormat && segments.length > 0 && !scene.hasActiveUpdaters();
     if (useCache) {
       await this.renderSegmented(
         scene,
@@ -5144,6 +5637,7 @@ export {
   FadeIn,
   FadeOut,
   Follow,
+  FrameRenderer,
   Glyph,
   Graph,
   GraphEdge,
@@ -5156,12 +5650,14 @@ export {
   MoveTo,
   Parallel,
   Polygon,
+  ProgressReporter,
   Rectangle,
   Renderer,
   Resolution,
   Rotate,
   Scale,
   Scene,
+  SegmentCache,
   Sequence,
   Shake,
   Text,
@@ -5169,7 +5665,7 @@ export {
   Unwrite,
   VGroup,
   VMobject,
-  Vector2,
+  Vector,
   Write,
   clearRegistry,
   smooth as defaultEasing,