@redwilly/anima 0.1.0

package/dist/core/serialization/index.js

@@ -0,0 +1,29 @@
+/**
+ * Serialization module for the Anima animation engine.
+ *
+ * This module provides functionality to convert Scenes, Mobjects, and Animations
+ * into JSON-compatible objects and back, enabling project persistence, undo/redo,
+ * and cross-process communication.
+ *
+ * Example usage:
+ * ```typescript
+ * import { serialize, deserialize } from './serialization';
+ *
+ * const json = serialize(scene);
+ * const restoredScene = deserialize(json);
+ * ```
+ */
+// Main entry points
+export { serialize, deserialize, serializeScene, deserializeScene } from './scene';
+// Pretty printing
+export { prettyPrint, prettyPrintCompact } from './prettyPrint';
+// Mobject serialization
+export { serializeMobject, deserializeMobject, resetIdCounter } from './mobject';
+// Animation serialization
+export { serializeAnimation, deserializeAnimation } from './animation';
+// Primitive serialization
+export { serializeVector2, deserializeVector2, serializeMatrix3x3, deserializeMatrix3x3, serializeColor, deserializeColor, serializeBezierPath, deserializeBezierPath, } from './primitives';
+// Custom serializer registry
+export { registerSerializer, getSerializer, hasSerializer, unregisterSerializer, clearSerializerRegistry, } from './registry';
+// Easing lookup
+export { getEasingName, getEasingByName } from './easingLookup';

package/dist/core/serialization/mobject.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Mobject and VMobject serialization.
+ */
+import { Mobject } from '../../mobjects/Mobject';
+import type { SerializedMobject } from './types';
+/**
+ * Reset ID counter (useful for testing).
+ */
+export declare function resetIdCounter(): void;
+/**
+ * Serializes a Mobject or any of its subclasses to a plain object.
+ *
+ * This function handles built-in types like Circle, Rectangle, etc.,
+ * and also checks the custom serializer registry for user-defined types.
+ */
+export declare function serializeMobject(m: Mobject): SerializedMobject;
+/**
+ * Restores a Mobject or subclass instance from serialized data.
+ *
+ * Uses the 'type' field to determine the correct class to instantiate
+ * and restores its state including transformations and styles.
+ */
+export declare function deserializeMobject(data: SerializedMobject): Mobject;

package/dist/core/serialization/mobject.js

@@ -0,0 +1,248 @@
+/**
+ * Mobject and VMobject serialization.
+ */
+import { VMobject } from '../../mobjects/VMobject';
+import { VGroup } from '../../mobjects/VGroup/VGroup';
+import { Circle, Rectangle, Line, Arrow, Arc, Polygon, Point } from '../../mobjects/geometry';
+import { serializeMatrix3x3, deserializeMatrix3x3, serializeColor, deserializeColor, serializeBezierPath, deserializeBezierPath, serializeVector2, deserializeVector2, } from './primitives';
+import { getSerializer } from './registry';
+// ID generation - uses a simple incrementing counter
+let idCounter = 0;
+const mobjectIdMap = new WeakMap();
+function getMobjectId(m) {
+    let id = mobjectIdMap.get(m);
+    if (!id) {
+        id = `mob_${idCounter++}`;
+        mobjectIdMap.set(m, id);
+    }
+    return id;
+}
+/**
+ * Reset ID counter (useful for testing).
+ */
+export function resetIdCounter() {
+    idCounter = 0;
+}
+/**
+ * Get the type name for a mobject instance.
+ */
+function getMobjectType(m) {
+    if (m instanceof Circle)
+        return 'Circle';
+    if (m instanceof Rectangle)
+        return 'Rectangle';
+    if (m instanceof Arrow)
+        return 'Arrow';
+    if (m instanceof Line)
+        return 'Line';
+    if (m instanceof Arc)
+        return 'Arc';
+    if (m instanceof Polygon)
+        return 'Polygon';
+    if (m instanceof Point)
+        return 'Point';
+    if (m instanceof VGroup)
+        return 'VGroup';
+    if (m instanceof VMobject)
+        return 'VMobject';
+    return 'Mobject';
+}
+// ========== Base Mobject Serialization ==========
+function serializeMobjectBase(m) {
+    return {
+        type: getMobjectType(m),
+        id: getMobjectId(m),
+        matrix: serializeMatrix3x3(m.matrix),
+        opacity: m.opacity,
+    };
+}
+// ========== VMobject Serialization ==========
+function serializeVMobjectBase(v) {
+    const base = serializeMobjectBase(v);
+    return {
+        ...base,
+        paths: v.paths.map(serializeBezierPath),
+        strokeColor: serializeColor(v.getStrokeColor()),
+        strokeWidth: v.getStrokeWidth(),
+        fillColor: serializeColor(v.getFillColor()),
+        fillOpacity: v.getFillOpacity(),
+    };
+}
+// ========== Primitive-Specific Serialization ==========
+function serializeCircle(c) {
+    const base = serializeVMobjectBase(c);
+    // Circle extends Arc, extract radius from the path bounding
+    const arc = c;
+    return { ...base, type: 'Circle', radius: arc.radius };
+}
+function serializeRectangle(r) {
+    const base = serializeVMobjectBase(r);
+    return { ...base, type: 'Rectangle', width: r.width, height: r.height };
+}
+function serializeLine(l) {
+    const base = serializeVMobjectBase(l);
+    return {
+        ...base,
+        type: 'Line',
+        start: serializeVector2(l.start),
+        end: serializeVector2(l.end),
+    };
+}
+function serializeArc(a) {
+    const base = serializeVMobjectBase(a);
+    return {
+        ...base,
+        type: 'Arc',
+        radius: a.radius,
+        startAngle: a.startAngle,
+        endAngle: a.endAngle,
+    };
+}
+function serializePolygon(p) {
+    const base = serializeVMobjectBase(p);
+    return {
+        ...base,
+        type: 'Polygon',
+        vertices: p.vertices.map(serializeVector2),
+    };
+}
+function serializePoint(p) {
+    // Point extends Circle, serialize as VMobject with Point type
+    const base = serializeVMobjectBase(p);
+    return { ...base, type: 'Point' };
+}
+// ========== VGroup Serialization ==========
+function serializeVGroup(g) {
+    const base = serializeMobjectBase(g);
+    return {
+        ...base,
+        type: 'VGroup',
+        children: g.getChildren().map(serializeMobject),
+    };
+}
+// ========== Main Serialization Entry Point ==========
+/**
+ * Serializes a Mobject or any of its subclasses to a plain object.
+ *
+ * This function handles built-in types like Circle, Rectangle, etc.,
+ * and also checks the custom serializer registry for user-defined types.
+ */
+export function serializeMobject(m) {
+    // Check for custom serializer first
+    const typeName = m.constructor.name;
+    const customSerializer = getSerializer(typeName);
+    if (customSerializer) {
+        return customSerializer.serialize(m);
+    }
+    // Handle built-in types
+    if (m instanceof Circle)
+        return serializeCircle(m);
+    if (m instanceof Rectangle)
+        return serializeRectangle(m);
+    if (m instanceof Arrow)
+        return serializeLine(m);
+    if (m instanceof Line)
+        return serializeLine(m);
+    if (m instanceof Arc)
+        return serializeArc(m);
+    if (m instanceof Polygon)
+        return serializePolygon(m);
+    if (m instanceof Point)
+        return serializePoint(m);
+    if (m instanceof VGroup)
+        return serializeVGroup(m);
+    if (m instanceof VMobject)
+        return serializeVMobjectBase(m);
+    return serializeMobjectBase(m);
+}
+// ========== Deserialization ==========
+function applyMobjectBase(m, data) {
+    const matrix = deserializeMatrix3x3(data.matrix);
+    m.applyMatrix(matrix);
+    m.setOpacity(data.opacity);
+}
+function applyVMobjectBase(v, data) {
+    applyMobjectBase(v, data);
+    v.paths = data.paths.map(deserializeBezierPath);
+    v.stroke(deserializeColor(data.strokeColor), data.strokeWidth);
+    v.fill(deserializeColor(data.fillColor), data.fillOpacity);
+}
+/**
+ * Restores a Mobject or subclass instance from serialized data.
+ *
+ * Uses the 'type' field to determine the correct class to instantiate
+ * and restores its state including transformations and styles.
+ */
+export function deserializeMobject(data) {
+    // Check for custom serializer first
+    const customSerializer = getSerializer(data.type);
+    if (customSerializer) {
+        return customSerializer.deserialize(data);
+    }
+    switch (data.type) {
+        case 'Circle': {
+            const d = data;
+            const circle = new Circle(d.radius);
+            applyVMobjectBase(circle, d);
+            return circle;
+        }
+        case 'Rectangle': {
+            const d = data;
+            const rect = new Rectangle(d.width, d.height);
+            applyVMobjectBase(rect, d);
+            return rect;
+        }
+        case 'Line': {
+            const d = data;
+            const start = deserializeVector2(d.start);
+            const end = deserializeVector2(d.end);
+            const line = new Line(start.x, start.y, end.x, end.y);
+            applyVMobjectBase(line, d);
+            return line;
+        }
+        case 'Arc': {
+            const d = data;
+            const arc = new Arc(d.radius, d.startAngle, d.endAngle);
+            applyVMobjectBase(arc, d);
+            return arc;
+        }
+        case 'Polygon': {
+            const d = data;
+            const vertices = d.vertices.map(deserializeVector2);
+            const polygon = new Polygon(vertices);
+            applyVMobjectBase(polygon, d);
+            return polygon;
+        }
+        case 'Point': {
+            // Point constructor takes location, but we restore state via matrix
+            const d = data;
+            const point = new Point();
+            applyVMobjectBase(point, d);
+            return point;
+        }
+        case 'VGroup': {
+            const d = data;
+            const children = d.children.map(deserializeMobject);
+            const group = new VGroup(...children);
+            applyMobjectBase(group, d);
+            return group;
+        }
+        case 'VMobject': {
+            const d = data;
+            const vmob = new VMobject();
+            applyVMobjectBase(vmob, d);
+            return vmob;
+        }
+        default: {
+            // Generic Mobject fallback
+            const mob = new VMobject();
+            if ('paths' in data) {
+                applyVMobjectBase(mob, data);
+            }
+            else {
+                applyMobjectBase(mob, data);
+            }
+            return mob;
+        }
+    }
+}

package/dist/core/serialization/prettyPrint.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pretty printer for serialized scenes.
+ */
+import type { SerializedScene } from './types';
+/**
+ * Formats a serialized scene as a JSON string with 2-space indentation.
+ */
+export declare function prettyPrint(scene: SerializedScene): string;
+/**
+ * Formats a serialized scene as a JSON string using a compact yet readable format.
+ */
+export declare function prettyPrintCompact(scene: SerializedScene): string;

package/dist/core/serialization/prettyPrint.js

@@ -0,0 +1,16 @@
+/**
+ * Pretty printer for serialized scenes.
+ */
+/**
+ * Formats a serialized scene as a JSON string with 2-space indentation.
+ */
+export function prettyPrint(scene) {
+    return JSON.stringify(scene, null, 2);
+}
+/**
+ * Formats a serialized scene as a JSON string using a compact yet readable format.
+ */
+export function prettyPrintCompact(scene) {
+    // Current implementation uses 2-space indentation; could be adjusted for more compactness.
+    return JSON.stringify(scene, null, 2);
+}

package/dist/core/serialization/primitives.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Serializers for primitive math types.
+ */
+import { Vector2 } from '../math/Vector2/Vector2';
+import { Matrix3x3 } from '../math/matrix/Matrix3x3';
+import { Color } from '../math/color/Color';
+import { BezierPath } from '../math/bezier/BezierPath';
+import type { SerializedVector2, SerializedMatrix3x3, SerializedColor, SerializedBezierPath } from './types';
+/** Converts a Vector2 to a plain object for serialization. */
+export declare function serializeVector2(v: Vector2): SerializedVector2;
+/** Restores a Vector2 from serialized data. */
+export declare function deserializeVector2(data: SerializedVector2): Vector2;
+/** Converts a Matrix3x3 to a plain object for serialization. */
+export declare function serializeMatrix3x3(m: Matrix3x3): SerializedMatrix3x3;
+/** Restores a Matrix3x3 from serialized data. */
+export declare function deserializeMatrix3x3(data: SerializedMatrix3x3): Matrix3x3;
+/** Converts a Color to a plain object for serialization. */
+export declare function serializeColor(c: Color): SerializedColor;
+/** Restores a Color from serialized data. */
+export declare function deserializeColor(data: SerializedColor): Color;
+/** Converts a BezierPath to a plain object for serialization. */
+export declare function serializeBezierPath(path: BezierPath): SerializedBezierPath;
+/** Restores a BezierPath from serialized data. */
+export declare function deserializeBezierPath(data: SerializedBezierPath): BezierPath;

package/dist/core/serialization/primitives.js

@@ -0,0 +1,98 @@
+/**
+ * Serializers for primitive math types.
+ */
+import { Vector2 } from '../math/Vector2/Vector2';
+import { Matrix3x3 } from '../math/matrix/Matrix3x3';
+import { Color } from '../math/color/Color';
+import { BezierPath } from '../math/bezier/BezierPath';
+// ========== Vector2 ==========
+/** Converts a Vector2 to a plain object for serialization. */
+export function serializeVector2(v) {
+    return { x: v.x, y: v.y };
+}
+/** Restores a Vector2 from serialized data. */
+export function deserializeVector2(data) {
+    return new Vector2(data.x, data.y);
+}
+// ========== Matrix3x3 ==========
+/** Converts a Matrix3x3 to a plain object for serialization. */
+export function serializeMatrix3x3(m) {
+    return { values: Array.from(m.values) };
+}
+/** Restores a Matrix3x3 from serialized data. */
+export function deserializeMatrix3x3(data) {
+    const values = new Float32Array(data.values);
+    return new Matrix3x3(values);
+}
+// ========== Color ==========
+/** Converts a Color to a plain object for serialization. */
+export function serializeColor(c) {
+    return { r: c.r, g: c.g, b: c.b, a: c.a };
+}
+/** Restores a Color from serialized data. */
+export function deserializeColor(data) {
+    return new Color(data.r, data.g, data.b, data.a);
+}
+// ========== PathCommand ==========
+function serializePathCommand(cmd) {
+    const result = {
+        type: cmd.type,
+        end: serializeVector2(cmd.end),
+    };
+    // Add control points if they exist
+    const withControl1 = cmd.control1
+        ? { ...result, control1: serializeVector2(cmd.control1) }
+        : result;
+    const withControl2 = cmd.control2
+        ? { ...withControl1, control2: serializeVector2(cmd.control2) }
+        : withControl1;
+    return withControl2;
+}
+function deserializePathCommand(data) {
+    const result = {
+        type: data.type,
+        end: deserializeVector2(data.end),
+    };
+    if (data.control1) {
+        return { ...result, control1: deserializeVector2(data.control1) };
+    }
+    if (data.control2) {
+        return { ...result, control2: deserializeVector2(data.control2) };
+    }
+    return result;
+}
+// ========== BezierPath ==========
+/** Converts a BezierPath to a plain object for serialization. */
+export function serializeBezierPath(path) {
+    const commands = path.getCommands().map(serializePathCommand);
+    return { commands };
+}
+/** Restores a BezierPath from serialized data. */
+export function deserializeBezierPath(data) {
+    const path = new BezierPath();
+    for (const cmd of data.commands) {
+        const end = deserializeVector2(cmd.end);
+        switch (cmd.type) {
+            case 'Move':
+                path.moveTo(end);
+                break;
+            case 'Line':
+                path.lineTo(end);
+                break;
+            case 'Quadratic':
+                if (cmd.control1) {
+                    path.quadraticTo(deserializeVector2(cmd.control1), end);
+                }
+                break;
+            case 'Cubic':
+                if (cmd.control1 && cmd.control2) {
+                    path.cubicTo(deserializeVector2(cmd.control1), deserializeVector2(cmd.control2), end);
+                }
+                break;
+            case 'Close':
+                path.closePath();
+                break;
+        }
+    }
+    return path;
+}

package/dist/core/serialization/registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Registry for custom serializers to support user-defined VMobject subclasses.
+ */
+import type { CustomSerializer } from './types';
+/**
+ * Register a custom serializer for a type.
+ * @param serializer The serializer implementation
+ */
+export declare function registerSerializer<T>(serializer: CustomSerializer<T>): void;
+/**
+ * Get a registered serializer by type name.
+ * @param typeName The type name to look up
+ * @returns The serializer or undefined if not registered
+ */
+export declare function getSerializer(typeName: string): CustomSerializer<unknown> | undefined;
+/**
+ * Check if a serializer is registered for a type.
+ * @param typeName The type name to check
+ */
+export declare function hasSerializer(typeName: string): boolean;
+/**
+ * Unregister a serializer.
+ * @param typeName The type name to unregister
+ */
+export declare function unregisterSerializer(typeName: string): boolean;
+/**
+ * Clear all registered serializers.
+ */
+export declare function clearSerializerRegistry(): void;

package/dist/core/serialization/registry.js

@@ -0,0 +1,39 @@
+/**
+ * Registry for custom serializers to support user-defined VMobject subclasses.
+ */
+const registry = new Map();
+/**
+ * Register a custom serializer for a type.
+ * @param serializer The serializer implementation
+ */
+export function registerSerializer(serializer) {
+    registry.set(serializer.typeName, serializer);
+}
+/**
+ * Get a registered serializer by type name.
+ * @param typeName The type name to look up
+ * @returns The serializer or undefined if not registered
+ */
+export function getSerializer(typeName) {
+    return registry.get(typeName);
+}
+/**
+ * Check if a serializer is registered for a type.
+ * @param typeName The type name to check
+ */
+export function hasSerializer(typeName) {
+    return registry.has(typeName);
+}
+/**
+ * Unregister a serializer.
+ * @param typeName The type name to unregister
+ */
+export function unregisterSerializer(typeName) {
+    return registry.delete(typeName);
+}
+/**
+ * Clear all registered serializers.
+ */
+export function clearSerializerRegistry() {
+    registry.clear();
+}

package/dist/core/serialization/scene.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scene serialization - the main entry point for serializing/deserializing Scenes.
+ */
+import { Scene } from '../scene';
+import type { SerializedScene } from './types';
+/**
+ * Serializes a Scene into a plain object format.
+ *
+ * This captures all added Mobjects, their hierarchical structure,
+ * and the entire timeline of scheduled animations.
+ */
+export declare function serializeScene(scene: Scene): SerializedScene;
+/**
+ * Serializes a Scene into a JSON-formatted string.
+ *
+ * Useful for saving scene state to a file or transmitting it over a network.
+ */
+export declare function serialize(scene: Scene): string;
+/**
+ * Restores a complete Scene from a serialized object.
+ *
+ * Reconstructs all Mobjects and reschedules all animations onto the timeline.
+ */
+export declare function deserializeScene(data: SerializedScene): Scene;
+/**
+ * Restores a complete Scene from a JSON-formatted string.
+ */
+export declare function deserialize(json: string): Scene;

package/dist/core/serialization/scene.js

@@ -0,0 +1,114 @@
+/**
+ * Scene serialization - the main entry point for serializing/deserializing Scenes.
+ */
+import { Scene } from '../scene';
+import { serializeMobject, deserializeMobject, resetIdCounter } from './mobject';
+import { serializeAnimation, deserializeAnimation } from './animation';
+import { serializeColor, deserializeColor } from './primitives';
+const SERIALIZATION_VERSION = '1.0.0';
+// Track mobject IDs during serialization
+const serializationIdMap = new Map();
+let serializationIdCounter = 0;
+function getSerializationId(m) {
+    let id = serializationIdMap.get(m);
+    if (!id) {
+        id = `mob_${serializationIdCounter++}`;
+        serializationIdMap.set(m, id);
+    }
+    return id;
+}
+function resetSerializationState() {
+    serializationIdMap.clear();
+    serializationIdCounter = 0;
+    resetIdCounter();
+}
+// ========== Scene Serialization ==========
+function serializeSceneConfig(scene) {
+    return {
+        width: scene.getWidth(),
+        height: scene.getHeight(),
+        backgroundColor: serializeColor(scene.getBackgroundColor()),
+        frameRate: scene.getFrameRate(),
+    };
+}
+function serializeTimeline(scene) {
+    const timeline = scene.getTimeline();
+    const scheduled = timeline.getScheduled();
+    const serializedScheduled = scheduled.map(s => ({
+        animation: serializeAnimation(s.animation, getSerializationId),
+        startTime: s.startTime,
+    }));
+    return {
+        loop: timeline.isLooping(),
+        scheduled: serializedScheduled,
+    };
+}
+/**
+ * Serializes a Scene into a plain object format.
+ *
+ * This captures all added Mobjects, their hierarchical structure,
+ * and the entire timeline of scheduled animations.
+ */
+export function serializeScene(scene) {
+    resetSerializationState();
+    const mobjects = scene.getMobjects();
+    const serializedMobjects = mobjects.map(m => serializeMobject(m));
+    return {
+        version: SERIALIZATION_VERSION,
+        config: serializeSceneConfig(scene),
+        mobjects: serializedMobjects,
+        timeline: serializeTimeline(scene),
+    };
+}
+/**
+ * Serializes a Scene into a JSON-formatted string.
+ *
+ * Useful for saving scene state to a file or transmitting it over a network.
+ */
+export function serialize(scene) {
+    const data = serializeScene(scene);
+    return JSON.stringify(data);
+}
+// ========== Scene Deserialization ==========
+/**
+ * Restores a complete Scene from a serialized object.
+ *
+ * Reconstructs all Mobjects and reschedules all animations onto the timeline.
+ */
+export function deserializeScene(data) {
+    // Verify version compatibility
+    if (!data.version) {
+        throw new Error('Missing serialization version');
+    }
+    // Create scene with config
+    const scene = new Scene({
+        width: data.config.width,
+        height: data.config.height,
+        backgroundColor: deserializeColor(data.config.backgroundColor),
+        frameRate: data.config.frameRate,
+    });
+    // Build mobject registry for animation deserialization
+    const mobjectRegistry = new Map();
+    const mobjects = [];
+    for (const serializedMob of data.mobjects) {
+        const mob = deserializeMobject(serializedMob);
+        mobjectRegistry.set(serializedMob.id, mob);
+        mobjects.push(mob);
+    }
+    // Add mobjects to scene
+    scene.add(...mobjects);
+    // Deserialize and schedule animations
+    const timeline = scene.getTimeline();
+    for (const scheduled of data.timeline.scheduled) {
+        const animation = deserializeAnimation(scheduled.animation, mobjectRegistry);
+        timeline.schedule(animation, scheduled.startTime);
+    }
+    return scene;
+}
+/**
+ * Restores a complete Scene from a JSON-formatted string.
+ */
+export function deserialize(json) {
+    const data = JSON.parse(json);
+    return deserializeScene(data);
+}