@rafaylabs/animation-mcp 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,262 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { handleSearchAnimations } from './tools/search.js';
+import { handleGetAnimation } from './tools/get.js';
+import { executeApplyTheme } from './tools/theme.js';
+import { saveAnimationToProject } from './tools/save.js';
+import { generateFrameworkCode } from './tools/code.js';
+import { SearchAnimationsArgsSchema, GetAnimationArgsSchema, ApplyThemeArgsSchema, SaveAnimationArgsSchema, GetCodeArgsSchema, } from './tools/schemas.js';
+/**
+ * Creates and initializes the Animation MCP Server
+ */
+export async function startMcpServer() {
+    const server = new Server({
+        name: 'rafaylabs-animation-mcp',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // 1. List Available Tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                {
+                    name: 'search_animations',
+                    description: 'Search the RafayLabs catalogue of 11,000+ production Lottie animations using plain language (e.g. "success checkmark with confetti", "pulsing order delivery truck", "loading skeleton shimmer"). Returns short structured JSON with preview URLs, style, size, and category. Never returns raw Lottie JSON to save context window.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'Search keywords in plain words (e.g. "checkmark", "loading spinner", "checkout success")',
+                            },
+                            style: {
+                                type: 'string',
+                                description: 'Optional visual style: flat, 3d, minimal, gradient, outline',
+                            },
+                            category: {
+                                type: 'string',
+                                description: 'Optional category: success, loading, error, empty state, onboarding, ecommerce',
+                            },
+                            loop: {
+                                type: 'boolean',
+                                description: 'Whether the animation should continuously loop',
+                            },
+                            max_size_kb: {
+                                type: 'number',
+                                description: 'Maximum file size in KB',
+                            },
+                            limit: {
+                                type: 'number',
+                                description: 'Maximum number of results to return (default 5)',
+                                default: 5,
+                            },
+                        },
+                        required: ['query'],
+                    },
+                },
+                {
+                    name: 'get_animation',
+                    description: 'Fetch the complete original Lottie JSON and metadata for a specific animation ID found via search_animations.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'The animation ID (e.g. "success-checkmark" or "pulse-loader")',
+                            },
+                        },
+                        required: ['id'],
+                    },
+                },
+                {
+                    name: 'apply_theme',
+                    description: 'Automatically recolor any Lottie animation into the user brand colors without breaking shadows, highlights, or contrast. Writes the themed file directly to output_path if provided, avoiding dumping large JSON into AI context.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Optional catalogue animation ID',
+                            },
+                            file_path: {
+                                type: 'string',
+                                description: 'Optional path to a local .json or .lottie file in the user project to recolor',
+                            },
+                            lottie_json: {
+                                type: 'object',
+                                description: 'Optional direct Lottie JSON object to recolor',
+                            },
+                            output_path: {
+                                type: 'string',
+                                description: 'Recommended destination path in your project (e.g. "assets/hero.json" or "assets/hero.lottie"). Saves directly to file without polluting AI context.',
+                            },
+                            format: {
+                                type: 'string',
+                                enum: ['json', 'lottie'],
+                                description: 'File format when saving: "json" (standard) or "lottie" (dotLottie compressed zip). Inferred from output_path extension if omitted.',
+                            },
+                            overwrite: {
+                                type: 'boolean',
+                                description: 'Whether to overwrite existing file if output_path exists (default: false)',
+                            },
+                            theme: {
+                                type: 'object',
+                                description: 'Target theme hex colors',
+                                properties: {
+                                    primary: {
+                                        type: 'string',
+                                        description: 'Primary brand hex color (e.g. "#0476FF")',
+                                    },
+                                    secondary: {
+                                        type: 'string',
+                                        description: 'Optional secondary brand hex color (e.g. "#00C2FF")',
+                                    },
+                                    background: {
+                                        type: 'string',
+                                        description: 'Optional background hex color (e.g. "#FFFFFF" or "#010712")',
+                                    },
+                                    accent: {
+                                        type: 'string',
+                                        description: 'Optional accent highlight hex color (e.g. "#10B981")',
+                                    },
+                                },
+                                required: ['primary'],
+                            },
+                            mode: {
+                                type: 'string',
+                                enum: ['light', 'dark'],
+                                description: 'Optional light or dark mode palette adjustment',
+                            },
+                        },
+                        required: ['theme'],
+                    },
+                },
+                {
+                    name: 'save_animation',
+                    description: 'Save an existing Lottie JSON animation directly to a file path inside the user project (e.g. "assets/animations/checkout-success.json" or ".lottie"). Creates parent directories automatically.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            themed_json: {
+                                type: 'object',
+                                description: 'The Lottie JSON object to save',
+                            },
+                            path: {
+                                type: 'string',
+                                description: 'Relative or absolute project destination path (e.g. "assets/animations/success.json")',
+                            },
+                            format: {
+                                type: 'string',
+                                enum: ['json', 'lottie'],
+                                description: 'File format: "json" or "lottie" (dotLottie v1 zip). Default: "json"',
+                                default: 'json',
+                            },
+                            overwrite: {
+                                type: 'boolean',
+                                description: 'Whether to overwrite an existing file (default: false)',
+                                default: false,
+                            },
+                        },
+                        required: ['themed_json', 'path'],
+                    },
+                },
+                {
+                    name: 'get_code',
+                    description: 'Generate clean, production-ready framework component code and package install instructions for displaying the animation in React, React Native (Expo), Next.js, or plain HTML.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            framework: {
+                                type: 'string',
+                                enum: ['react', 'react-native', 'nextjs', 'html'],
+                                description: 'Target frontend framework',
+                            },
+                            file_path: {
+                                type: 'string',
+                                description: 'Relative path where the animation was saved (e.g. "assets/animations/success.json")',
+                            },
+                            options: {
+                                type: 'object',
+                                description: 'Optional display options',
+                                properties: {
+                                    loop: { type: 'boolean', description: 'Enable looping (default: true)' },
+                                    autoplay: { type: 'boolean', description: 'Enable autoplay (default: true)' },
+                                    size: { type: 'number', description: 'Width and height in px (default: 200)' },
+                                    componentName: { type: 'string', description: 'React component name' },
+                                },
+                            },
+                        },
+                        required: ['framework', 'file_path'],
+                    },
+                },
+            ],
+        };
+    });
+    // 2. Call Tool Handlers
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: rawArgs } = request.params;
+        try {
+            switch (name) {
+                case 'search_animations': {
+                    const validated = SearchAnimationsArgsSchema.parse(rawArgs);
+                    const result = await handleSearchAnimations(validated);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                case 'get_animation': {
+                    const validated = GetAnimationArgsSchema.parse(rawArgs);
+                    const result = await handleGetAnimation(validated);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                case 'apply_theme': {
+                    const validated = ApplyThemeArgsSchema.parse(rawArgs);
+                    const result = await executeApplyTheme(validated, server);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                case 'save_animation': {
+                    const validated = SaveAnimationArgsSchema.parse(rawArgs);
+                    const result = await saveAnimationToProject(validated, server);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                case 'get_code': {
+                    const validated = GetCodeArgsSchema.parse(rawArgs);
+                    const result = generateFrameworkCode(validated.framework, validated.file_path, validated.options);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                default:
+                    throw new Error(`Unknown MCP tool name: ${name}`);
+            }
+        }
+        catch (err) {
+            const errorMessage = err instanceof z.ZodError
+                ? `Invalid arguments for tool ${name}: ${err.errors.map((e) => `${e.path.join('.') || 'param'}: ${e.message}`).join('; ')}`
+                : err.message || 'Tool execution failed';
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: errorMessage }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    // Connect stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/theming/classifier.d.ts

@@ -0,0 +1,16 @@
+import { RGB, OKLCH } from './oklch.js';
+import { ColorOccurrence } from './color-walker.js';
+export type ColorRole = 'primary' | 'secondary' | 'background' | 'accent' | 'neutral';
+export interface ColorCluster {
+    id: string;
+    representativeRgb: RGB;
+    representativeLch: OKLCH;
+    occurrences: ColorOccurrence[];
+    weight: number;
+    isNeutral: boolean;
+    assignedRole?: ColorRole;
+}
+/**
+ * Groups colors into perceptual clusters and assigns design roles (primary, secondary, background, etc.)
+ */
+export declare function clusterAndClassifyColors(occurrences: ColorOccurrence[]): ColorCluster[];

package/dist/theming/classifier.js

@@ -0,0 +1,74 @@
+import { rgbToOklch, oklabDistance, isNeutral } from './oklch.js';
+const MERGE_DISTANCE_THRESHOLD = 0.045; // in OKLAB space
+/**
+ * Groups colors into perceptual clusters and assigns design roles (primary, secondary, background, etc.)
+ */
+export function clusterAndClassifyColors(occurrences) {
+    const clusters = [];
+    for (const occ of occurrences) {
+        const lch = rgbToOklch(occ.color);
+        let matchedCluster = null;
+        // Check if this color fits an existing cluster
+        for (const cluster of clusters) {
+            const dist = oklabDistance(occ.color, cluster.representativeRgb);
+            if (dist < MERGE_DISTANCE_THRESHOLD) {
+                matchedCluster = cluster;
+                break;
+            }
+        }
+        if (matchedCluster) {
+            matchedCluster.occurrences.push(occ);
+            matchedCluster.weight += 1;
+        }
+        else {
+            clusters.push({
+                id: `cluster_${clusters.length + 1}`,
+                representativeRgb: occ.color,
+                representativeLch: lch,
+                occurrences: [occ],
+                weight: 1,
+                isNeutral: isNeutral(lch),
+            });
+        }
+    }
+    // Sort by weight descending
+    clusters.sort((a, b) => b.weight - a.weight);
+    // Assign roles
+    assignRoles(clusters);
+    return clusters;
+}
+function assignRoles(clusters) {
+    // 1. Separate neutrals vs chromatic (saturated) colors
+    const neutrals = clusters.filter((c) => c.isNeutral);
+    const saturated = clusters.filter((c) => !c.isNeutral);
+    // 2. Identify potential background:
+    // A colour can ONLY be background when it fills the frame (a solid layer, or a rectangle covering >= 80% of w × h).
+    // Eye whites, teeth, highlights or character neutrals do NOT fill the frame and must stay neutral!
+    let backgroundCluster = null;
+    const frameFillingClusters = clusters.filter((c) => c.occurrences.some((occ) => occ.isBackgroundCandidate === true));
+    if (frameFillingClusters.length > 0) {
+        // Pick the largest frame-filling neutral first, or failing that, the largest frame-filling cluster
+        const neutralBgs = frameFillingClusters.filter((c) => c.isNeutral);
+        backgroundCluster = neutralBgs.length > 0 ? neutralBgs[0] : frameFillingClusters[0];
+        backgroundCluster.assignedRole = 'background';
+    }
+    // 3. Assign Saturated Colors (Primary, Secondary, Accent)
+    // Exclude backgroundCluster if it was saturated
+    const availableSaturated = saturated.filter((c) => c !== backgroundCluster);
+    availableSaturated.sort((a, b) => b.weight - a.weight);
+    if (availableSaturated.length > 0) {
+        availableSaturated[0].assignedRole = 'primary';
+    }
+    if (availableSaturated.length > 1) {
+        availableSaturated[1].assignedRole = 'secondary';
+    }
+    for (let i = 2; i < availableSaturated.length; i++) {
+        availableSaturated[i].assignedRole = 'accent';
+    }
+    // 4. Remaining neutrals remain neutral (preserved, never inverted into dark background)
+    for (const n of neutrals) {
+        if (!n.assignedRole) {
+            n.assignedRole = 'neutral';
+        }
+    }
+}

package/dist/theming/color-walker.d.ts

@@ -0,0 +1,19 @@
+import { RGB } from './oklch.js';
+export interface ColorOccurrence {
+    path: (string | number)[];
+    type: 'fill' | 'stroke' | 'gradient_stop' | 'solid_layer';
+    color: RGB;
+    originalLength: number;
+    isKeyframed: boolean;
+    keyframeIndex?: number;
+    gradientIndex?: number;
+    isBackgroundCandidate?: boolean;
+}
+/**
+ * Traverses a Lottie JSON tree and extracts all color references with their exact paths.
+ */
+export declare function walkLottieColors(lottie: Record<string, any>): ColorOccurrence[];
+/**
+ * Sets a value at a nested path inside a clone of the Lottie JSON
+ */
+export declare function setNestedValue(obj: any, path: (string | number)[], value: any): void;

package/dist/theming/color-walker.js

@@ -0,0 +1,303 @@
+import { hexToRgb } from './oklch.js';
+/**
+ * Traverses a Lottie JSON tree and extracts all color references with their exact paths.
+ */
+export function walkLottieColors(lottie) {
+    const occurrences = [];
+    const width = lottie.w || 500;
+    const height = lottie.h || 500;
+    // 1. Process layers in root
+    if (Array.isArray(lottie.layers)) {
+        walkLayers(lottie.layers, ['layers'], occurrences, width, height);
+    }
+    // 2. Process layers inside precomps in assets[]
+    if (Array.isArray(lottie.assets)) {
+        lottie.assets.forEach((asset, assetIdx) => {
+            if (asset && Array.isArray(asset.layers)) {
+                walkLayers(asset.layers, ['assets', assetIdx, 'layers'], occurrences, asset.w || width, asset.h || height);
+            }
+        });
+    }
+    return occurrences;
+}
+function walkLayers(layers, basePath, occurrences, docWidth, docHeight) {
+    layers.forEach((layer, layerIdx) => {
+        if (!layer)
+            return;
+        const layerPath = [...basePath, layerIdx];
+        // Solid layer color: layer.sc (Hex string)
+        if (layer.ty === 1 && typeof layer.sc === 'string') {
+            const sw = layer.sw || 0;
+            const sh = layer.sh || 0;
+            const isFullFrame = sw >= docWidth * 0.8 && sh >= docHeight * 0.8;
+            occurrences.push({
+                path: [...layerPath, 'sc'],
+                type: 'solid_layer',
+                color: hexToRgb(layer.sc),
+                originalLength: 1,
+                isKeyframed: false,
+                isBackgroundCandidate: isFullFrame,
+            });
+        }
+        // Text layer (ty: 5): colors in t.d.k[].s.fc (fill) and sc (stroke)
+        if (layer.ty === 5 && layer.t?.d) {
+            walkTextLayer(layer.t.d, [...layerPath, 't', 'd'], occurrences);
+        }
+        // Layer Effects (ef): Fill (ty: 21) or Tint (ty: 20)
+        if (Array.isArray(layer.ef)) {
+            walkLayerEffects(layer.ef, [...layerPath, 'ef'], occurrences);
+        }
+        // Shape layer (ty: 4) shapes array
+        if (Array.isArray(layer.shapes)) {
+            walkShapes(layer.shapes, [...layerPath, 'shapes'], occurrences, docWidth, docHeight);
+        }
+    });
+}
+function walkTextLayer(tDoc, basePath, occurrences) {
+    if (!tDoc)
+        return;
+    // Keyframed text document
+    if (Array.isArray(tDoc.k)) {
+        tDoc.k.forEach((item, idx) => {
+            if (!item)
+                return;
+            const docData = item.s || item;
+            extractTextDocColors(docData, [...basePath, 'k', idx, item.s ? 's' : ''], occurrences);
+        });
+        return;
+    }
+    // Static text document
+    if (tDoc.k && typeof tDoc.k === 'object') {
+        const docData = tDoc.k.s || tDoc.k;
+        extractTextDocColors(docData, [...basePath, 'k', tDoc.k.s ? 's' : ''], occurrences);
+    }
+}
+function extractTextDocColors(docData, basePath, occurrences) {
+    if (!docData)
+        return;
+    const cleanPath = basePath.filter((p) => p !== '');
+    // Fill color (fc): [r, g, b, (a)]
+    if (Array.isArray(docData.fc) && typeof docData.fc[0] === 'number') {
+        occurrences.push({
+            path: [...cleanPath, 'fc'],
+            type: 'fill',
+            color: {
+                r: docData.fc[0],
+                g: docData.fc[1],
+                b: docData.fc[2],
+                a: docData.fc.length > 3 ? docData.fc[3] : 1,
+            },
+            originalLength: docData.fc.length,
+            isKeyframed: false,
+        });
+    }
+    // Stroke color (sc): [r, g, b, (a)]
+    if (Array.isArray(docData.sc) && typeof docData.sc[0] === 'number') {
+        occurrences.push({
+            path: [...cleanPath, 'sc'],
+            type: 'stroke',
+            color: {
+                r: docData.sc[0],
+                g: docData.sc[1],
+                b: docData.sc[2],
+                a: docData.sc.length > 3 ? docData.sc[3] : 1,
+            },
+            originalLength: docData.sc.length,
+            isKeyframed: false,
+        });
+    }
+}
+function walkLayerEffects(effects, basePath, occurrences) {
+    effects.forEach((effect, efIdx) => {
+        if (!effect)
+            return;
+        const efPath = [...basePath, efIdx];
+        // After Effects Fill Effect (ty: 21) or Tint Effect (ty: 20)
+        if (Array.isArray(effect.ef)) {
+            effect.ef.forEach((prop, propIdx) => {
+                if (!prop)
+                    return;
+                const propPath = [...efPath, 'ef', propIdx];
+                // Property value containing color (ty: 2 indicates color property)
+                if (prop.v && prop.v.k !== undefined) {
+                    extractColorProperty(prop.v, [...propPath, 'v'], 'fill', occurrences);
+                }
+            });
+        }
+    });
+}
+function walkShapes(shapes, basePath, occurrences, docWidth, docHeight) {
+    // Check if this shapes group contains a rectangle covering the frame
+    let hasFullFrameRect = false;
+    for (const s of shapes) {
+        if (s && s.ty === 'rc' && s.s?.k) {
+            const size = Array.isArray(s.s.k) ? s.s.k : (s.s.k?.k || []);
+            if (Array.isArray(size) && size[0] >= docWidth * 0.8 && size[1] >= docHeight * 0.8) {
+                hasFullFrameRect = true;
+                break;
+            }
+        }
+    }
+    shapes.forEach((shape, shapeIdx) => {
+        if (!shape)
+            return;
+        const shapePath = [...basePath, shapeIdx];
+        // Shape Group (ty: "gr") containing sub-items
+        if (shape.ty === 'gr' && Array.isArray(shape.it)) {
+            walkShapes(shape.it, [...shapePath, 'it'], occurrences, docWidth, docHeight);
+            return;
+        }
+        // Fill (ty: "fl")
+        if (shape.ty === 'fl' && shape.c) {
+            extractColorProperty(shape.c, [...shapePath, 'c'], 'fill', occurrences, hasFullFrameRect);
+        }
+        // Stroke (ty: "st")
+        if (shape.ty === 'st' && shape.c) {
+            extractColorProperty(shape.c, [...shapePath, 'c'], 'stroke', occurrences, false);
+        }
+        // Gradient Fill (ty: "gf") or Gradient Stroke (ty: "gs")
+        if ((shape.ty === 'gf' || shape.ty === 'gs') && shape.g) {
+            const stopCount = shape.g.p !== undefined ? shape.g.p : (shape.p !== undefined ? shape.p : 0);
+            extractGradientProperty(shape.g, [...shapePath, 'g'], stopCount, occurrences);
+        }
+    });
+}
+/**
+ * Extracts colors from Lottie animated/static color property (c)
+ */
+function extractColorProperty(cProp, cPath, type, occurrences, isBackgroundCandidate = false) {
+    if (!cProp || cProp.k === undefined)
+        return;
+    // Static color: c.k is [r, g, b, (a)]
+    if (Array.isArray(cProp.k) && typeof cProp.k[0] === 'number') {
+        const raw = cProp.k;
+        occurrences.push({
+            path: [...cPath, 'k'],
+            type,
+            color: {
+                r: raw[0],
+                g: raw[1],
+                b: raw[2],
+                a: raw.length > 3 ? raw[3] : 1,
+            },
+            originalLength: raw.length,
+            isKeyframed: false,
+            isBackgroundCandidate,
+        });
+        return;
+    }
+    // Keyframed color: c.k is array of keyframe objects { s: [r, g, b, (a)], e?: ... }
+    if (Array.isArray(cProp.k)) {
+        cProp.k.forEach((kf, kfIdx) => {
+            // Start keyframe color (s)
+            if (kf && Array.isArray(kf.s) && typeof kf.s[0] === 'number') {
+                const raw = kf.s;
+                occurrences.push({
+                    path: [...cPath, 'k', kfIdx, 's'],
+                    type,
+                    color: {
+                        r: raw[0],
+                        g: raw[1],
+                        b: raw[2],
+                        a: raw.length > 3 ? raw[3] : 1,
+                    },
+                    originalLength: raw.length,
+                    isKeyframed: true,
+                    keyframeIndex: kfIdx,
+                    isBackgroundCandidate,
+                });
+            }
+            // End keyframe color (e) - Fix for older Lottie exports (Item 5)
+            if (kf && Array.isArray(kf.e) && typeof kf.e[0] === 'number') {
+                const raw = kf.e;
+                occurrences.push({
+                    path: [...cPath, 'k', kfIdx, 'e'],
+                    type,
+                    color: {
+                        r: raw[0],
+                        g: raw[1],
+                        b: raw[2],
+                        a: raw.length > 3 ? raw[3] : 1,
+                    },
+                    originalLength: raw.length,
+                    isKeyframed: true,
+                    keyframeIndex: kfIdx,
+                    isBackgroundCandidate,
+                });
+            }
+        });
+    }
+}
+/**
+ * Extracts gradient stops from Lottie gradient property (shape.g)
+ * Structure:
+ * - Color stops count: shape.g.p
+ * - First p * 4 numbers are color stops: [offset, r, g, b, ...]
+ * - Remaining numbers are opacity stops: [offset, alpha, ...] - left UNTOUCHED!
+ * - Handles both static gradients and animated gradients (g.k.a === 1 with keyframes).
+ */
+function extractGradientProperty(gProp, gPath, numStops, occurrences) {
+    if (!gProp || !gProp.k)
+        return;
+    const isAnimated = gProp.k.a === 1 || (Array.isArray(gProp.k) && gProp.k[0] && typeof gProp.k[0] === 'object' && 's' in gProp.k[0]);
+    // Case 1: Animated gradient (g.k.a === 1)
+    if (isAnimated) {
+        const keyframes = Array.isArray(gProp.k) ? gProp.k : (Array.isArray(gProp.k.k) ? gProp.k.k : []);
+        const kPrefix = Array.isArray(gProp.k) ? [...gPath, 'k'] : [...gPath, 'k', 'k'];
+        keyframes.forEach((kf, kfIdx) => {
+            if (!kf)
+                return;
+            if (Array.isArray(kf.s)) {
+                walkGradientArray(kf.s, [...kPrefix, kfIdx, 's'], numStops, occurrences, true, kfIdx);
+            }
+            if (Array.isArray(kf.e)) {
+                walkGradientArray(kf.e, [...kPrefix, kfIdx, 'e'], numStops, occurrences, true, kfIdx);
+            }
+        });
+        return;
+    }
+    // Case 2: Static gradient
+    const rawStops = Array.isArray(gProp.k) ? gProp.k : (Array.isArray(gProp.k?.k) ? gProp.k.k : null);
+    if (!Array.isArray(rawStops))
+        return;
+    const pathPrefix = Array.isArray(gProp.k) ? [...gPath, 'k'] : [...gPath, 'k', 'k'];
+    walkGradientArray(rawStops, pathPrefix, numStops, occurrences, false);
+}
+function walkGradientArray(stopsArray, pathPrefix, numStops, occurrences, isKeyframed, keyframeIndex) {
+    // If stop count not explicitly set in shape.g.p, infer from array length
+    const count = numStops > 0 ? numStops : Math.floor(stopsArray.length / 4);
+    for (let i = 0; i < count; i++) {
+        const offsetIdx = i * 4;
+        if (offsetIdx + 3 < stopsArray.length) {
+            occurrences.push({
+                path: [...pathPrefix, offsetIdx + 1], // points to red index
+                type: 'gradient_stop',
+                color: {
+                    r: stopsArray[offsetIdx + 1],
+                    g: stopsArray[offsetIdx + 2],
+                    b: stopsArray[offsetIdx + 3],
+                    a: 1,
+                },
+                originalLength: 4,
+                isKeyframed,
+                keyframeIndex,
+                gradientIndex: i,
+            });
+        }
+    }
+}
+/**
+ * Sets a value at a nested path inside a clone of the Lottie JSON
+ */
+export function setNestedValue(obj, path, value) {
+    let curr = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        if (curr[key] === undefined || curr[key] === null) {
+            return;
+        }
+        curr = curr[key];
+    }
+    const lastKey = path[path.length - 1];
+    curr[lastKey] = value;
+}