feat: GSAP animation integration support

[lucianfialho]

Summary

Add GSAP (GreenSock Animation Platform) integration to enable declarative animations in JSON specs. This would allow AI-generated UIs to include rich, performant animations defined in the JSON spec format.

Motivation

Currently, json-render has no built-in animation system. Animations are deferred entirely to the underlying framework (Tailwind CSS transitions, etc.). GSAP is the industry standard for web animations — performant, cross-browser, and widely adopted. Integrating it would unlock a whole new dimension for generative UIs.

Proposed API

Option A: Animation props on UIElement (recommended)

Add an optional animation field to the element spec:

{
  "type": "Card",
  "props": { "title": "Hello" },
  "animation": {
    "enter": { "from": { "opacity": 0, "y": 50 }, "duration": 0.6, "ease": "power2.out" },
    "exit": { "to": { "opacity": 0 }, "duration": 0.3 },
    "scroll": { "trigger": true, "start": "top 80%", "end": "top 20%" }
  }
}

Each renderer would interpret the animation spec using its platform's best tool (GSAP for web, Animated API for React Native, etc.).

Option B: Animation as actions/watch

Leverage the existing watch system to trigger animations on state changes:

{
  "watch": {
    "/isVisible": {
      "action": "animate",
      "params": { "target": "card-1", "to": { "opacity": 1, "y": 0 }, "duration": 0.5 }
    }
  }
}

Option C: AnimationProvider wrapper (simplest)

A React-only HOC/wrapper that intercepts elements and applies GSAP based on animation props, without touching core types.

Implementation Considerations

• Core: Add optional animation field to UIElement in types.ts
• React renderer: Use @gsap/react (useGSAP hook) to apply animations
• GSAP plugins: Support for ScrollTrigger, Flip, and other popular plugins
• Other renderers: Vue/Svelte/Solid could use GSAP directly; React Native would use react-native-reanimated or Animated API
• Streaming: Animations should work gracefully with progressive rendering — elements animate in as they stream
• Tree-shaking: GSAP should be an optional peer dependency, not bundled by default

Questions for Discussion

1. Should animation be a core concept (UIElement.animation) or a renderer-specific extension?
2. Which GSAP plugins should be supported out of the box (ScrollTrigger, Flip, TextPlugin)?
3. Should we start with a standalone @json-render/gsap package or bake it into the React renderer?
4. How should animations interact with the streaming/progressive rendering model?

Would love to hear thoughts from maintainers and the community!