spring-animation

What this skill does

## When to use

Use this skill when creating Remotion video compositions that need **spring physics** -- natural, organic motion with bounce, overshoot, and elastic settling.

**Use spring when you need:**
- Bouncy/elastic entrances (overshoot + settle)
- Organic deceleration (not linear, not eased -- physically modeled)
- Staggered trails with spring physics per element
- Number counters that overshoot then settle
- Scale/rotate with natural weight and inertia
- Enter + exit animations with spring math (`in - out`)
- Multi-property orchestration with different spring configs per property

**Use Remotion native `interpolate()` when:**
- Linear or eased motion with no bounce (fade, slide, wipe)
- Exact timing control (must end at precisely frame N)
- Clip-path animations
- Progress bars / deterministic counters

**Use GSAP (gsap-animation skill) when:**
- Text splitting (SplitText: chars/words/lines with mask)
- SVG stroke drawing (DrawSVG)
- SVG morphing (MorphSVG)
- Complex timeline orchestration with labels and position parameters
- ScrambleText decode effects
- Registered reusable effects

**Note:** `@react-spring/web` is NOT compatible with Remotion (it uses requestAnimationFrame internally). This skill uses Remotion's native `spring()` function which provides the same physics model in a frame-deterministic way.

---

## Core API

### spring()

Returns a value from 0 to 1 (can overshoot past 1 with low damping) based on spring physics simulation.

```tsx
import { spring, useCurrentFrame, useVideoConfig } from 'remotion';

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

const value = spring({
  frame,
  fps,
  config: {
    damping: 10,     // 1-200: higher = less bounce
    stiffness: 100,  // 1-200: higher = faster snap
    mass: 1,         // 0.1-5: higher = more inertia
  },
});
```

### Config Parameters

| Parameter | Range | Default | Effect |
|-----------|-------|---------|--------|
| `damping` | 1-200 | 10 | Resistance. Low = bouncy, high = smooth |
| `stiffness` | 1-200 | 100 | Snap speed. High = fast, low = slow |
| `mass` | 0.1-5 | 1 | Weight/inertia. High = sluggish, low = light |
| `overshootClamping` | bool | false | Clamp at target (no overshoot) |

### Additional Options

| Option | Type | Effect |
|--------|------|--------|
| `delay` | number | Delay start by N frames (returns 0 until delay elapses) |
| `durationInFrames` | number | Force spring to settle within N frames |
| `reverse` | bool | Animate from 1 to 0 |
| `from` | number | Starting value (default 0) |
| `to` | number | Ending value (default 1) |

### measureSpring()

Calculate how many frames a spring config takes to settle. Essential for `<Sequence>` and composition duration.

```tsx
import { measureSpring } from 'remotion';

const frames = measureSpring({
  fps: 30,
  config: { damping: 10, stiffness: 100 },
}); // => number of frames until settled
```

---

## Physics Presets

```tsx
// src/spring-presets.ts
import { SpringConfig } from 'remotion';

export const SPRING = {
  // Smooth, no bounce -- subtle reveals, background motion
  smooth: { damping: 200 } as Partial<SpringConfig>,

  // Snappy, minimal bounce -- UI elements, clean entrances
  snappy: { damping: 20, stiffness: 200 } as Partial<SpringConfig>,

  // Bouncy -- playful entrances, attention-grabbing
  bouncy: { damping: 8 } as Partial<SpringConfig>,

  // Heavy, slow -- dramatic reveals, weighty objects
  heavy: { damping: 15, stiffness: 80, mass: 2 } as Partial<SpringConfig>,

  // Wobbly -- elastic, cartoon-like overshoot
  wobbly: { damping: 4, stiffness: 80 } as Partial<SpringConfig>,

  // Stiff -- fast snap with tiny bounce
  stiff: { damping: 15, stiffness: 300 } as Partial<SpringConfig>,

  // Gentle -- slow, dreamy, organic
  gentle: { damping: 20, stiffness: 40, mass: 1.5 } as Partial<SpringConfig>,

  // Molasses -- very slow, heavy, barely bounces
  molasses: { damping: 25, stiffness: 30, mass: 3 } as Partial<SpringConfig>,

  // Pop -- strong overshoot for scale-in effects
  pop: { damping: 6, stiffness: 150 } as Partial<SpringConfig>,

  // Rubber -- exaggerated elastic bounce
  rubber: { damping: 3, stiffness: 100, mass: 0.5 } as Partial<SpringConfig>,
} as const;
```

### Preset Visual Reference

| Preset | Bounce | Speed | Feel | Best For |
|--------|--------|-------|------|----------|
| `smooth` | None | Medium | Butter | Background, subtle reveals |
| `snappy` | Minimal | Fast | Crisp | UI elements, buttons |
| `bouncy` | Strong | Medium | Playful | Titles, icons, attention |
| `heavy` | Small | Slow | Weighty | Dramatic reveals, large objects |
| `wobbly` | Extreme | Medium | Cartoon | Playful, humorous |
| `stiff` | Tiny | Very fast | Mechanical | Data viz, precise motion |
| `gentle` | Minimal | Slow | Dreamy | Luxury, calm, organic |
| `molasses` | Almost none | Very slow | Heavy | Cinematic, suspense |
| `pop` | Strong | Fast | Punchy | Scale-in, badge, icon pop |
| `rubber` | Extreme | Fast | Elastic | Exaggerated, cartoon, fun |

---

## 1. Spring Entrance Patterns

### Basic Spring Entrance

```tsx
import { spring, interpolate, useCurrentFrame, useVideoConfig, AbsoluteFill } from 'remotion';
import { SPRING } from './spring-presets';

const SpringEntrance: React.FC<{
  children: React.ReactNode;
  preset?: keyof typeof SPRING;
  delay?: number;
}> = ({ children, preset = 'bouncy', delay = 0 }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const progress = spring({ frame, fps, delay, config: SPRING[preset] });
  const translateY = interpolate(progress, [0, 1], [60, 0]);

  return (
    <AbsoluteFill style={{
      opacity: progress,
      transform: `translateY(${translateY}px)`,
    }}>
      {children}
    </AbsoluteFill>
  );
};
```

### Scale Pop

```tsx
const ScalePop: React.FC<{
  children: React.ReactNode;
  delay?: number;
}> = ({ children, delay = 0 }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  // pop preset overshoots past 1, creating natural scale bounce
  const scale = spring({ frame, fps, delay, config: SPRING.pop });
  const opacity = spring({ frame, fps, delay, config: SPRING.smooth });

  return (
    <div style={{
      transform: `scale(${scale})`,
      opacity,
    }}>
      {children}
    </div>
  );
};
```

### Enter + Exit (Spring Math)

```tsx
const EnterExit: React.FC<{
  children: React.ReactNode;
  enterDelay?: number;
  exitBeforeEnd?: number; // frames before composition end to start exit
}> = ({ children, enterDelay = 0, exitBeforeEnd = 30 }) => {
  const frame = useCurrentFrame();
  const { fps, durationInFrames } = useVideoConfig();

  const enter = spring({ frame, fps, delay: enterDelay, config: SPRING.bouncy });
  const exit = spring({
    frame, fps,
    delay: durationInFrames - exitBeforeEnd,
    config: SPRING.snappy,
  });

  const scale = enter - exit; // 0 -> 1 -> 0
  const opacity = enter - exit;

  return (
    <div style={{ transform: `scale(${scale})`, opacity }}>
      {children}
    </div>
  );
};
```

---

## 2. Trail / Stagger Patterns

### Spring Trail (staggered entrance)

Mimics React Spring's `useTrail` -- each element enters with a frame delay.

```tsx
const SpringTrail: React.FC<{
  items: React.ReactNode[];
  staggerFrames?: number;
  preset?: keyof typeof SPRING;
  direction?: 'up' | 'down' | 'left' | 'right';
}> = ({ items, staggerFrames = 4, preset = 'bouncy', direction = 'up' }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const getOffset = (progress: number) => {
    const distance = 50;
    const remaining = interpolate(progress, [0, 1], [distance, 0]);
    switch (direction) {
      case 'up': return { transform: `translateY(${remaining}px)` };
      case 'down': return { transform: `translateY(${-remaining}px)` };
      case 'left': return { transform: `translateX(${remaining}px)` };
      case 'right': return { transform: `translateX(${-remaining}px)` };
    }
  };

  return (
    <>