Gsap Framer Scroll Animation

# Framer Motion (Motion v12) — Full Reference

> Framer Motion was renamed to **Motion** in mid-2025. The npm package is now `motion`,
> the import path is `motion/react`. All APIs are identical. `framer-motion` still works.

## Table of Contents
1. [Package & Import Paths](#package--import-paths)
2. [Two Types of Scroll Animation](#two-types-of-scroll-animation)
3. [useScroll — Options Reference](#usescroll--options-reference)
4. [useTransform — Full Reference](#usetransform--full-reference)
5. [useSpring for Smoothing](#usespring-for-smoothing)
6. [Recipes with Copilot Prompts](#recipes-with-copilot-prompts)
   - Scroll progress bar
   - Reusable ScrollReveal wrapper
   - Parallax layers
   - Horizontal scroll section
   - Image reveal with clipPath
   - Scroll-linked navbar (hide/show)
   - Staggered card grid
   - 3D tilt on scroll
7. [Variants Pattern for Stagger](#variants-pattern-for-stagger)
8. [Motion Value Events](#motion-value-events)
9. [Next.js & App Router Notes](#nextjs--app-router-notes)
10. [Accessibility](#accessibility)
11. [Common Copilot Pitfalls](#common-copilot-pitfalls)

---

## Package & Import Paths

```bash
npm install motion          # recommended (renamed 2025)
npm install framer-motion   # still works — same API
```

```js
// Recommended (Motion v12+)
import { motion, useScroll, useTransform, useSpring, useMotionValueEvent } from 'motion/react';

// Legacy — still valid
import { motion, useScroll, useTransform } from 'framer-motion';
```

**Motion v12 new features (2025):**
- Hardware-accelerated scroll via browser ScrollTimeline API
- `useScroll` and `scroll()` now GPU-accelerated by default
- New color types: `oklch`, `oklab`, `color-mix` animatable directly
- Full React 19 + concurrent rendering support

---

## Two Types of Scroll Animation

### Scroll-triggered (fires once when element enters viewport)

```jsx
<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: '-80px' }}
  transition={{ duration: 0.6, ease: [0.21, 0.47, 0.32, 0.98] }}
>
  Content
</motion.div>
```

`viewport.margin` — negative value triggers animation before element fully enters view.
`viewport.once` — `true` means animate once, never reverse.

### Scroll-linked (continuous, tied to scroll position)

```jsx
const { scrollYProgress } = useScroll();
const opacity = useTransform(scrollYProgress, [0, 1], [0, 1]);
return <motion.div style={{ opacity }}>Content</motion.div>;
```

The value updates on every scroll frame — must use `style` prop, not `animate`.

---

## useScroll — Options Reference

```js
const {
  scrollX,          // Absolute horizontal scroll (pixels)
  scrollY,          // Absolute vertical scroll (pixels)
  scrollXProgress,  // Horizontal progress 0→1 between offsets
  scrollYProgress,  // Vertical progress 0→1 between offsets
} = useScroll({
  // Track a scrollable element instead of the viewport
  container: containerRef,

  // Track an element's position within the container
  target: targetRef,

  // Define when tracking starts and ends
  // Format: ["target position container position", "target position container position"]
  offset: ['start end', 'end start'],
  // Common offset pairs:
  // ['start end', 'end start']    = track while element is anywhere in view
  // ['start end', 'end end']      = track from element entering to bottom of page
  // ['start start', 'end start']  = track while element exits top
  // ['center center', 'end start']= track from center-center to exit

  // Update when content size changes (small perf cost, false by default)
  trackContentSize: false,
});
```

**Offset string values:**
- `start` = `0` = top/left edge
- `center` = `0.5` = middle
- `end` = `1` = bottom/right edge
- Numbers 0–1 also work: `[0, 1]` = `['start', 'end']`

---

## useTransform — Full Reference

```js
// Map a motion value from one range to another
const y = useTransform(scrollYProgress, [0, 1], [0, -200]);

// Multi-stop interpolation
cons