Anima Performance Tuning

Overview

Improve design-to-code throughput without treating cache hits or smaller output as success unless the result still matches the approved design version, accessibility expectations, and project build contract.

Measurement Contract

Record source-fetch, queue, generation, asset, validation, and review durations separately. Establish targets from the team's own representative fixtures and provider agreement; do not present illustrative latency or quota numbers as an Anima service-level objective.

Prerequisites

• A representative staging fixture and a baseline measurement of generation duration, cache hit rate, failure rate, and generated-code validation result.
• A version-aware cache key and retention policy that ties each artifact to Figma source version, node ID, and generation settings.
• Review gates for generated output so performance changes cannot automatically replace approved components or strip required licenses/accessibility content.

Authentication

Load ANIMA_TOKEN and the source-scoped FIGMA_TOKEN only in the backend worker. Performance tests use synthetic allowlisted sources; do not broaden credentials or retry authorization failures to make a benchmark complete.

Instructions

Step 1: File-Based Generation Cache

// src/performance/cache.ts
import crypto from 'crypto';
import fs from 'fs';
import { Anima } from '@animaapp/anima-sdk';

class GenerationCache {
  private dir: string;

  constructor(cacheDir = '.anima-cache') {
    this.dir = cacheDir;
    fs.mkdirSync(cacheDir, { recursive: true });
  }

  private hash(fileKey: string, sourceRevision: string, nodeId: string, settings: object): string {
    return crypto.createHash('sha256').update(`${fileKey}:${sourceRevision}:${nodeId}:${JSON.stringify(settings)}`).digest('hex');
  }

  async getOrGenerate(
    anima: Anima,
    params: Parameters<Anima['generateCode']>[0],
    sourceRevision: string,
    maxAgeMs: number = 3600000, // 1 hour
  ): Promise<Awaited<ReturnType<Anima['generateCode']>>> {
    const key = this.hash(params.fileKey, sourceRevision, params.nodesId[0], params.settings);
    const path = `${this.dir}/${key}.json`;

    if (fs.existsSync(path)) {
      const stat = fs.statSync(path);
      if (Date.now() - stat.mtimeMs < maxAgeMs) {
        return JSON.parse(fs.readFileSync(path, 'utf8'));
      }
    }

    const result = await anima.generateCode(params);
    fs.writeFileSync(path, JSON.stringify(result));
    return result;
  }

  clearOlderThan(maxAgeMs: number): number {
    let cleared = 0;
    for (const file of fs.readdirSync(this.dir)) {
      const path = `${this.dir}/${file}`;
      if (Date.now() - fs.statSync(path).mtimeMs > maxAgeMs) {
        fs.unlinkSync(path);
        cleared++;
      }
    }
    return cleared;
  }
}

export { GenerationCache };

Step 2: Incremental Generation (Only Changed Components)

// src/performance/incremental.ts
// Only regenerate components whose Figma nodes changed

async function getNodeLastModified(fileKey: string, nodeId: string): Promise<string> {
  const res = await fetch(
    `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${nodeId}`,
    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
  );
  const data = await res.json();
  return data.lastModified;
}

async function generateOnlyChanged(
  anima: any,
  fileKey: string,
  nodeIds: string[],
  lastModifiedCache: Map<string, string>,
): Promise<string[]> {
  const changed: string[] = [];

  for (const nodeId of nodeIds) {
    const lastMod = await getNodeLastModified(fileKey, nodeId);
    if (lastMod !== lastModifiedCache.get(nodeId)) {
      changed.push(nodeId);
      lastModifiedCache.set(nodeId, lastMod);
    }
  }

  console.log(`${changed.length}/${nodeIds.length} components changed — regenerating`);
  return changed;
}

Step 3: Validate Output Without Semantic Rewriting

// Preserve generated semantics; measure before applying reviewed transforms.
function recordOutput(fileName: string, content: string) {
  return {
    fileName,
    bytes: Buffer.byteLength(content),
    digest: crypto.createHash('sha256').update(content).digest('hex'),
  };
}

Tool Discipline

Use Read and Grep to inspect the existing integration and generated diff before changing anything. Use Write or Edit only inside the approved generated-code, test, or configuration paths. Use the declared Bash commands only for the explicit install, validation, or diagnostic steps in this workflow; never print tokens, source designs, generated source, or private website captures.

Output

• File-based generation cache with TTL
• Incremental generation (only changed components)
• Output size and digest measurements without destructive rewriting

Examples

Benchmark ten approved staging components once without cache and once with the cache keyed by source version, node ID, and settings. Compare duration, API calls, output size, lint/type results, and visual review rather than just cache hit rate. Regenerate only components whose recorded source version changed, and keep the prior generated artifact available for diff review. If a cache entry cannot prove its source version, post-processing changes required behavior, or rate limits increase, disable the optimization and return to the prior validated generation path while investigating the aggregate measurements.

Error Handling

Failure	Response
Cache artifact lacks valid source/version metadata	Refuse reuse and regenerate the approved component.
Incremental detector cannot determine change state	Treat the affected component as needing controlled regeneration.
Optimizer changes semantics or removes required content	Revert the post-processing rule and restore the reviewed artifact.
Throughput increases provider failures or rate limits	Reduce concurrency, apply bounded backoff, and preserve user-visible job state.

Resources

• Anima API
• Figma API Nodes