@rafaylabs/animation-mcp 0.0.0-stage → 1.0.0

package/dist/theming/engine.d.ts

@@ -0,0 +1,29 @@
+import { ColorRole } from './classifier.js';
+export interface UserTheme {
+    primary: string;
+    secondary?: string;
+    background?: string;
+    accent?: string;
+}
+export interface ThemingOptions {
+    mode?: 'light' | 'dark';
+}
+export interface ColorMappingResult {
+    role: ColorRole;
+    originalHex: string;
+    themedHex: string;
+    count: number;
+}
+export interface ThemingResult {
+    themedLottie: Record<string, any>;
+    colorMap: ColorMappingResult[];
+    themeableScore: number;
+    hasRasterImages: boolean;
+    totalColorsCount: number;
+}
+/**
+ * Main Theming Engine.
+ * Takes any Lottie JSON and a target theme, returning a cleanly recolored Lottie JSON
+ * that preserves shadows, highlights, and contrast.
+ */
+export declare function applyThemeToLottie(originalLottie: Record<string, any>, theme: UserTheme, options?: ThemingOptions): ThemingResult;

package/dist/theming/engine.js

@@ -0,0 +1,144 @@
+import { rgbToHex, hexToRgb, rgbToOklch, oklchToRgb, clamp, } from './oklch.js';
+import { walkLottieColors, setNestedValue } from './color-walker.js';
+import { clusterAndClassifyColors } from './classifier.js';
+/**
+ * Main Theming Engine.
+ * Takes any Lottie JSON and a target theme, returning a cleanly recolored Lottie JSON
+ * that preserves shadows, highlights, and contrast.
+ */
+export function applyThemeToLottie(originalLottie, theme, options = {}) {
+    // Deep clone to avoid mutating input
+    const lottie = JSON.parse(JSON.stringify(originalLottie));
+    // Check for raster images in assets
+    let hasRasterImages = false;
+    if (Array.isArray(lottie.assets)) {
+        hasRasterImages = lottie.assets.some((a) => a && (a.p?.endsWith?.('.png') || a.p?.endsWith?.('.jpg') || a.e === 1));
+    }
+    // 1. Walk colors
+    const occurrences = walkLottieColors(lottie);
+    if (occurrences.length === 0) {
+        return {
+            themedLottie: lottie,
+            colorMap: [],
+            themeableScore: hasRasterImages ? 0.2 : 0.8,
+            hasRasterImages,
+            totalColorsCount: 0,
+        };
+    }
+    // 2. Cluster & Classify
+    const clusters = clusterAndClassifyColors(occurrences);
+    // 3. Resolve target theme colors into OKLCH
+    const targetPrimaryRgb = hexToRgb(theme.primary);
+    const targetPrimaryLch = rgbToOklch(targetPrimaryRgb);
+    const targetSecondaryLch = theme.secondary
+        ? rgbToOklch(hexToRgb(theme.secondary))
+        : { ...targetPrimaryLch, h: (targetPrimaryLch.h + 30) % 360, c: targetPrimaryLch.c * 0.85 };
+    const targetBackgroundLch = theme.background
+        ? rgbToOklch(hexToRgb(theme.background))
+        : options.mode === 'dark'
+            ? { l: 0.12, c: 0.01, h: targetPrimaryLch.h }
+            : { l: 0.98, c: 0.005, h: targetPrimaryLch.h };
+    const targetAccentLch = theme.accent
+        ? rgbToOklch(hexToRgb(theme.accent))
+        : { ...targetPrimaryLch, h: (targetPrimaryLch.h + 180) % 360, c: targetPrimaryLch.c * 1.1 };
+    // Calculate cluster baseline lightness for relative shading preservation
+    const colorMap = [];
+    for (const cluster of clusters) {
+        const role = cluster.assignedRole || 'neutral';
+        const clusterBaseLch = cluster.representativeLch;
+        // Pick target base based on role
+        let targetBaseLch;
+        switch (role) {
+            case 'primary':
+                targetBaseLch = targetPrimaryLch;
+                break;
+            case 'secondary':
+                targetBaseLch = targetSecondaryLch;
+                break;
+            case 'background':
+                targetBaseLch = targetBackgroundLch;
+                break;
+            case 'accent':
+                targetBaseLch = targetAccentLch;
+                break;
+            case 'neutral':
+            default:
+                // Neutrals preserve their natural lightness; only the designated background role flips in dark mode
+                targetBaseLch = clusterBaseLch;
+                break;
+        }
+        // Process every occurrence in this cluster
+        for (const occ of cluster.occurrences) {
+            const origLch = rgbToOklch(occ.color);
+            // If cluster was assigned 'background' (e.g. canvas is white), but this specific
+            // occurrence is a content shape (e.g. eye whites or highlights) that does not fill the frame:
+            // keep it as a content neutral so it does not turn dark in dark mode.
+            const effectiveBaseLch = role === 'background' && !occ.isBackgroundCandidate
+                ? clusterBaseLch
+                : targetBaseLch;
+            const isEffectiveNeutral = role === 'neutral' || (role === 'background' && !occ.isBackgroundCandidate);
+            // Relative shading offset: How much darker/lighter was this occurrence compared to cluster base?
+            const lightnessDelta = origLch.l - clusterBaseLch.l;
+            // New lightness preserves the delta, clamped to valid ranges
+            let newLightness = effectiveBaseLch.l + lightnessDelta;
+            newLightness = clamp(newLightness, 0.02, 0.98);
+            // Construct new OKLCH color
+            const newLch = {
+                l: newLightness,
+                c: isEffectiveNeutral ? origLch.c : effectiveBaseLch.c,
+                h: isEffectiveNeutral ? origLch.h : effectiveBaseLch.h,
+                a: occ.color.a,
+            };
+            const newRgb = oklchToRgb(newLch);
+            // Write back to cloned JSON
+            if (occ.type === 'solid_layer') {
+                setNestedValue(lottie, occ.path, rgbToHex(newRgb));
+            }
+            else if (occ.type === 'gradient_stop') {
+                // Gradient stops are raw numbers [offset, r, g, b]
+                // path points to red stop index
+                const basePath = occ.path.slice(0, -1);
+                const redIdx = occ.path[occ.path.length - 1];
+                setNestedValue(lottie, [...basePath, redIdx], Number(newRgb.r.toFixed(4)));
+                setNestedValue(lottie, [...basePath, redIdx + 1], Number(newRgb.g.toFixed(4)));
+                setNestedValue(lottie, [...basePath, redIdx + 2], Number(newRgb.b.toFixed(4)));
+            }
+            else {
+                // Fill or Stroke static or keyframed color: [r, g, b, (a)]
+                // Preserve exact original array length (Item 6)
+                const values = [
+                    Number(newRgb.r.toFixed(4)),
+                    Number(newRgb.g.toFixed(4)),
+                    Number(newRgb.b.toFixed(4)),
+                ];
+                if (occ.originalLength >= 4) {
+                    values.push(Number((occ.color.a ?? 1).toFixed(4)));
+                }
+                setNestedValue(lottie, occ.path, values);
+            }
+        }
+        colorMap.push({
+            role,
+            originalHex: rgbToHex(cluster.representativeRgb),
+            themedHex: rgbToHex(oklchToRgb(targetBaseLch)),
+            count: cluster.weight,
+        });
+    }
+    // Calculate themeable score (0 - 1)
+    // Clean recoloring = few clusters, no raster images, reasonable shape count
+    let themeableScore = 1.0;
+    if (hasRasterImages)
+        themeableScore -= 0.5;
+    if (clusters.length > 8)
+        themeableScore -= 0.2;
+    if (clusters.length > 15)
+        themeableScore -= 0.2;
+    themeableScore = Math.max(0.1, Number(themeableScore.toFixed(2)));
+    return {
+        themedLottie: lottie,
+        colorMap,
+        themeableScore,
+        hasRasterImages,
+        totalColorsCount: occurrences.length,
+    };
+}

package/dist/theming/oklch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Ultra-fast, zero-dependency OKLCH color math & conversion.
+ * Implements Björn Ottosson's Oklab/Oklch specification for perceptual color theming.
+ */
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+export interface OKLCH {
+    l: number;
+    c: number;
+    h: number;
+    a?: number;
+}
+export interface OKLAB {
+    l: number;
+    a: number;
+    b: number;
+    alpha?: number;
+}
+export declare function clamp(v: number, min?: number, max?: number): number;
+/**
+ * Convert RGB (0..1) to OKLAB
+ */
+export declare function rgbToOklab(rgb: RGB): OKLAB;
+/**
+ * Convert OKLAB to RGB (0..1)
+ */
+export declare function oklabToRgb(lab: OKLAB): RGB;
+/**
+ * Convert OKLAB to OKLCH
+ */
+export declare function oklabToOklch(lab: OKLAB): OKLCH;
+/**
+ * Convert OKLCH to OKLAB
+ */
+export declare function oklchToOklab(lch: OKLCH): OKLAB;
+/**
+ * Convert RGB (0..1) directly to OKLCH
+ */
+export declare function rgbToOklch(rgb: RGB): OKLCH;
+/**
+ * Convert OKLCH directly to RGB (0..1)
+ */
+export declare function oklchToRgb(lch: OKLCH): RGB;
+/**
+ * Perceptual color distance Delta E in OKLAB
+ */
+export declare function oklabDistance(a: RGB, b: RGB): number;
+/**
+ * Parse hex string (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) into RGB (0..1)
+ */
+export declare function hexToRgb(hex: string): RGB;
+/**
+ * Convert RGB (0..1) to #RRGGBB hex string
+ */
+export declare function rgbToHex(rgb: RGB, includeAlpha?: boolean): string;
+/**
+ * Check if a color is considered neutral (near grey/white/black)
+ */
+export declare function isNeutral(lch: OKLCH, threshold?: number): boolean;

package/dist/theming/oklch.js

@@ -0,0 +1,147 @@
+/**
+ * Ultra-fast, zero-dependency OKLCH color math & conversion.
+ * Implements Björn Ottosson's Oklab/Oklch specification for perceptual color theming.
+ */
+// Convert sRGB (0-1) to linear sRGB
+function srgbToLinear(c) {
+    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+// Convert linear sRGB to sRGB (0-1)
+function linearToSrgb(c) {
+    return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(Math.max(0, c), 1 / 2.4) - 0.055;
+}
+// Clamp number between min and max
+export function clamp(v, min = 0, max = 1) {
+    return Math.min(Math.max(v, min), max);
+}
+/**
+ * Convert RGB (0..1) to OKLAB
+ */
+export function rgbToOklab(rgb) {
+    const lr = srgbToLinear(clamp(rgb.r));
+    const lg = srgbToLinear(clamp(rgb.g));
+    const lb = srgbToLinear(clamp(rgb.b));
+    const l_ = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m_ = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s_ = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    return {
+        l: 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_,
+        a: 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_,
+        b: 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_,
+        alpha: rgb.a ?? 1,
+    };
+}
+/**
+ * Convert OKLAB to RGB (0..1)
+ */
+export function oklabToRgb(lab) {
+    const l_ = lab.l + 0.3963377774 * lab.a + 0.2158037573 * lab.b;
+    const m_ = lab.l - 0.1055613458 * lab.a - 0.0638541728 * lab.b;
+    const s_ = lab.l - 0.0894841775 * lab.a - 1.2914855480 * lab.b;
+    const l = l_ * l_ * l_;
+    const m = m_ * m_ * m_;
+    const s = s_ * s_ * s_;
+    const r = +4.0767439362 * l - 3.3077115913 * m + 0.2309699292 * s;
+    const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+    const b = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
+    return {
+        r: clamp(linearToSrgb(r)),
+        g: clamp(linearToSrgb(g)),
+        b: clamp(linearToSrgb(b)),
+        a: lab.alpha ?? 1,
+    };
+}
+/**
+ * Convert OKLAB to OKLCH
+ */
+export function oklabToOklch(lab) {
+    const c = Math.sqrt(lab.a * lab.a + lab.b * lab.b);
+    let h = (Math.atan2(lab.b, lab.a) * 180) / Math.PI;
+    if (h < 0)
+        h += 360;
+    return {
+        l: lab.l,
+        c,
+        h,
+        a: lab.alpha,
+    };
+}
+/**
+ * Convert OKLCH to OKLAB
+ */
+export function oklchToOklab(lch) {
+    const rad = (lch.h * Math.PI) / 180;
+    return {
+        l: lch.l,
+        a: lch.c * Math.cos(rad),
+        b: lch.c * Math.sin(rad),
+        alpha: lch.a,
+    };
+}
+/**
+ * Convert RGB (0..1) directly to OKLCH
+ */
+export function rgbToOklch(rgb) {
+    return oklabToOklch(rgbToOklab(rgb));
+}
+/**
+ * Convert OKLCH directly to RGB (0..1)
+ */
+export function oklchToRgb(lch) {
+    return oklabToRgb(oklchToOklab(lch));
+}
+/**
+ * Perceptual color distance Delta E in OKLAB
+ */
+export function oklabDistance(a, b) {
+    const la = rgbToOklab(a);
+    const lb = rgbToOklab(b);
+    const dl = la.l - lb.l;
+    const da = la.a - lb.a;
+    const db = la.b - lb.b;
+    return Math.sqrt(dl * dl + da * da + db * db);
+}
+/**
+ * Parse hex string (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) into RGB (0..1)
+ */
+export function hexToRgb(hex) {
+    let cleaned = hex.trim().replace(/^#/, '');
+    if (cleaned.length === 3) {
+        cleaned = cleaned.split('').map((c) => c + c).join('') + 'ff';
+    }
+    else if (cleaned.length === 4) {
+        cleaned = cleaned.split('').map((c) => c + c).join('');
+    }
+    else if (cleaned.length === 6) {
+        cleaned += 'ff';
+    }
+    const num = parseInt(cleaned, 16);
+    if (isNaN(num) || cleaned.length !== 8) {
+        // Fallback to black if invalid
+        return { r: 0, g: 0, b: 0, a: 1 };
+    }
+    const r = ((num >> 24) & 255) / 255;
+    const g = ((num >> 16) & 255) / 255;
+    const b = ((num >> 8) & 255) / 255;
+    const a = (num & 255) / 255;
+    return { r, g, b, a };
+}
+/**
+ * Convert RGB (0..1) to #RRGGBB hex string
+ */
+export function rgbToHex(rgb, includeAlpha = false) {
+    const r = Math.round(clamp(rgb.r) * 255).toString(16).padStart(2, '0');
+    const g = Math.round(clamp(rgb.g) * 255).toString(16).padStart(2, '0');
+    const b = Math.round(clamp(rgb.b) * 255).toString(16).padStart(2, '0');
+    if (includeAlpha && rgb.a !== undefined && rgb.a < 1) {
+        const a = Math.round(clamp(rgb.a) * 255).toString(16).padStart(2, '0');
+        return `#${r}${g}${b}${a}`;
+    }
+    return `#${r}${g}${b}`;
+}
+/**
+ * Check if a color is considered neutral (near grey/white/black)
+ */
+export function isNeutral(lch, threshold = 0.035) {
+    return lch.c < threshold;
+}

package/dist/tools/code.d.ts

@@ -0,0 +1,20 @@
+export type SupportedFramework = 'react' | 'react-native' | 'nextjs' | 'html';
+export interface GetCodeOptions {
+    loop?: boolean;
+    autoplay?: boolean;
+    size?: number | {
+        width: number;
+        height: number;
+    };
+    componentName?: string;
+}
+export interface GeneratedCodeResult {
+    framework: SupportedFramework;
+    installCommand: string;
+    componentCode: string;
+    filePath: string;
+}
+/**
+ * Generates ready-to-paste framework code for displaying a Lottie animation
+ */
+export declare function generateFrameworkCode(framework: SupportedFramework, filePath: string, options?: GetCodeOptions): GeneratedCodeResult;

package/dist/tools/code.js

@@ -0,0 +1,104 @@
+/**
+ * Generates ready-to-paste framework code for displaying a Lottie animation
+ */
+export function generateFrameworkCode(framework, filePath, options = {}) {
+    const loop = options.loop !== false;
+    const autoplay = options.autoplay !== false;
+    const size = options.size || 200;
+    const width = typeof size === 'number' ? size : size.width;
+    const height = typeof size === 'number' ? size : size.height;
+    const compName = options.componentName || 'AnimatedIcon';
+    switch (framework) {
+        case 'react-native': {
+            const installCommand = 'npx expo install lottie-react-native || npm install lottie-react-native';
+            const componentCode = `import React, { useRef } from 'react';
+import { View, StyleSheet } from 'react-native';
+import LottieView from 'lottie-react-native';
+import animationData from './${filePath.replace(/^(\.\/|\/)/, '')}';
+
+export default function ${compName}() {
+  const animationRef = useRef<LottieView>(null);
+
+  return (
+    <View style={styles.container}>
+      <LottieView
+        ref={animationRef}
+        source={animationData}
+        autoPlay={${autoplay}}
+        loop={${loop}}
+        style={{ width: ${width}, height: ${height} }}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});
+`;
+            return { framework, installCommand, componentCode, filePath };
+        }
+        case 'nextjs': {
+            const installCommand = 'npm install lottie-react';
+            const componentCode = `"use client";
+
+import React from 'react';
+import dynamic from 'next/dynamic';
+import animationData from './${filePath.replace(/^(\.\/|\/)/, '')}';
+
+// Client-side dynamic import prevents SSR hydration mismatch
+const Lottie = dynamic(() => import('lottie-react'), { ssr: false });
+
+export default function ${compName}() {
+  return (
+    <div style={{ width: ${width}, height: ${height}, display: 'inline-flex', alignItems: 'center', justifyContent: 'center' }}>
+      <Lottie
+        animationData={animationData}
+        loop={${loop}}
+        autoPlay={${autoplay}}
+        style={{ width: '100%', height: '100%' }}
+      />
+    </div>
+  );
+}
+`;
+            return { framework, installCommand, componentCode, filePath };
+        }
+        case 'react': {
+            const installCommand = 'npm install lottie-react';
+            const componentCode = `import React from 'react';
+import Lottie from 'lottie-react';
+import animationData from './${filePath.replace(/^(\.\/|\/)/, '')}';
+
+export default function ${compName}() {
+  return (
+    <div style={{ width: ${width}, height: ${height} }}>
+      <Lottie
+        animationData={animationData}
+        loop={${loop}}
+        autoPlay={${autoplay}}
+        style={{ width: '100%', height: '100%' }}
+      />
+    </div>
+  );
+}
+`;
+            return { framework, installCommand, componentCode, filePath };
+        }
+        case 'html': {
+            const installCommand = '<!-- Include dotLottie player script in <head> -->\n<script src="https://unpkg.com/@lottiefiles/dotlottie-wc@latest/dist/dotlottie-wc.js" type="module"></script>';
+            const componentCode = `<!-- Ready-to-paste DotLottie Web Component -->
+<dotlottie-wc
+  src="./${filePath.replace(/^(\.\/|\/)/, '')}"
+  style="width: ${width}px; height: ${height}px;"
+  ${autoplay ? 'autoplay' : ''}
+  ${loop ? 'loop' : ''}
+></dotlottie-wc>
+`;
+            return { framework, installCommand, componentCode, filePath };
+        }
+    }
+}

package/dist/tools/get.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const GetAnimationSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export type GetAnimationInput = z.infer<typeof GetAnimationSchema>;
+export declare function handleGetAnimation(input: GetAnimationInput): Promise<{
+    id: string;
+    lottie_json: Record<string, any>;
+}>;

package/dist/tools/get.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { fetchAnimationById } from '../api/catalog-client.js';
+export const GetAnimationSchema = z.object({
+    id: z.string().min(1, 'Animation ID is required, e.g. "checkmark-success" or "loader-spinner"'),
+});
+export async function handleGetAnimation(input) {
+    // Sign-in, plan and daily limits are enforced by the server.
+    const lottieJson = await fetchAnimationById(input.id);
+    return { id: input.id, lottie_json: lottieJson };
+}

package/dist/tools/save.d.ts

@@ -0,0 +1,22 @@
+export interface SaveAnimationInput {
+    themed_json: Record<string, any> | string;
+    path: string;
+    format?: 'json' | 'lottie';
+    overwrite?: boolean;
+}
+export interface SaveAnimationResult {
+    success: boolean;
+    savedPath: string;
+    absolutePath: string;
+    sizeBytes: number;
+    sizeKb: string;
+    format: 'json' | 'lottie';
+}
+/**
+ * Builds a valid dotLottie v1 ZIP container containing manifest.json and animations/<id>.json
+ */
+export declare function buildDotLottieZip(json: Record<string, any>, animationId?: string): Uint8Array;
+/**
+ * Saves themed animation into the developer's project directory
+ */
+export declare function saveAnimationToProject(input: SaveAnimationInput, server?: any): Promise<SaveAnimationResult>;

package/dist/tools/save.js

@@ -0,0 +1,78 @@
+import fs from 'fs';
+import path from 'path';
+import { zipSync, strToU8 } from 'fflate';
+import { resolveSafePath } from '../utils/workspace.js';
+/**
+ * Builds a valid dotLottie v1 ZIP container containing manifest.json and animations/<id>.json
+ */
+export function buildDotLottieZip(json, animationId = 'animation') {
+    const manifest = {
+        version: '1',
+        generator: '@rafaylabs/animation-mcp',
+        animations: [
+            {
+                id: animationId,
+                speed: 1,
+                loop: true,
+                autoplay: true,
+            },
+        ],
+    };
+    const jsonStr = typeof json === 'string' ? json : JSON.stringify(json);
+    const manifestStr = JSON.stringify(manifest);
+    return zipSync({
+        'manifest.json': strToU8(manifestStr),
+        [`animations/${animationId}.json`]: strToU8(jsonStr),
+    }, { level: 9 });
+}
+/**
+ * Saves themed animation into the developer's project directory
+ */
+export async function saveAnimationToProject(input, server) {
+    let targetPath = input.path.trim();
+    const lower = targetPath.toLowerCase();
+    const pathFormat = lower.endsWith('.lottie')
+        ? 'lottie'
+        : lower.endsWith('.json')
+            ? 'json'
+            : null;
+    // Explicit `format` wins; otherwise infer from the extension; default json.
+    const format = input.format ?? pathFormat ?? 'json';
+    // Make the file extension always match the real content (never a ZIP named .json).
+    if (pathFormat && pathFormat !== format) {
+        targetPath = targetPath.slice(0, targetPath.lastIndexOf('.'));
+    }
+    if (!targetPath.toLowerCase().endsWith(`.${format === 'lottie' ? 'lottie' : 'json'}`)) {
+        targetPath += format === 'lottie' ? '.lottie' : '.json';
+    }
+    // Resolve safe path against MCP workspace root
+    const { absolutePath } = await resolveSafePath(targetPath, { server });
+    // Overwrite check (Item 10)
+    if (fs.existsSync(absolutePath) && !input.overwrite) {
+        throw new Error(`File already exists at "${targetPath}". To replace it, pass "overwrite: true".`);
+    }
+    // Ensure target directory exists
+    const targetDir = path.dirname(absolutePath);
+    if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+    const parsedJson = typeof input.themed_json === 'string' ? JSON.parse(input.themed_json) : input.themed_json;
+    const baseId = path.basename(absolutePath, path.extname(absolutePath)) || 'animation';
+    if (format === 'lottie') {
+        const zipBytes = buildDotLottieZip(parsedJson, baseId);
+        fs.writeFileSync(absolutePath, Buffer.from(zipBytes));
+    }
+    else {
+        const jsonStr = JSON.stringify(parsedJson, null, 2);
+        fs.writeFileSync(absolutePath, jsonStr, 'utf-8');
+    }
+    const stats = fs.statSync(absolutePath);
+    return {
+        success: true,
+        savedPath: targetPath,
+        absolutePath,
+        sizeBytes: stats.size,
+        sizeKb: `${(stats.size / 1024).toFixed(1)} KB`,
+        format,
+    };
+}