feat: GSAP animation integration support

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!

Start by reading types.ts and the React renderer to understand the existing UIElement and rendering boundaries. Resolve whether animation belongs in core types, a renderer extension, or a standalone package, then define the supported plugins, streaming behavior, dependency strategy, and tests needed to demonstrate the agreed API.