Gsap AnimationSAFE

Professional slash commands for Claude Code that provide structured workflows for software development tasks including code review, feature creation, security auditing, and architectural analysis.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

## Table of Contents

1. [Installation & TypeScript Setup](#installation--typescript-setup)
2. [Core Concepts](#core-concepts)
3. [Tweens](#tweens)
4. [Timelines](#timelines)
5. [Easing](#easing)
6. [Staggers](#staggers)
7. [Control Methods](#control-methods)
8. [Utility Methods](#utility-methods)
9. [Context & Cleanup](#context--cleanup)
10. [Responsive Animations — matchMedia()](#responsive-animations--matchmedia)
11. [Plugins Overview](#plugins-overview)
12. [ScrollTrigger](#scrolltrigger)
13. [ScrollSmoother](#scrollsmoother)
14. [Flip Plugin](#flip-plugin)
15. [SplitText Plugin](#splittext-plugin)
16. [React Integration — useGSAP()](#react-integration--usegsap)
17. [Performance Tips & Best Practices](#performance-tips--best-practices)
18. [Helper Functions](#helper-functions)

---

## Installation & TypeScript Setup

```bash
npm install gsap
```

TypeScript definitions are bundled with the package. If you need to point your compiler to them explicitly:

```json
// tsconfig.json
{
  "compilerOptions": { ... },
  "files": [
    "node_modules/gsap/types/index.d.ts"
  ]
}
```

**Basic import:**

```ts
import { gsap } from "gsap";
```

**Importing plugins:**

```ts
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { Flip } from "gsap/Flip";
import { SplitText } from "gsap/SplitText";
import { ScrollSmoother } from "gsap/ScrollSmoother";
import { DrawSVGPlugin } from "gsap/DrawSVGPlugin";

// Register all plugins once, before use
gsap.registerPlugin(ScrollTrigger, Flip, SplitText, ScrollSmoother);
```

**Recommended: single `gsap.ts` barrel file** to avoid duplicate registrations in large projects:

```ts
// gsap.ts
export * from "gsap";
export * from "gsap/ScrollTrigger";
export * from "gsap/Flip";

import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { Flip } from "gsap/Flip";

gsap.registerPlugin(ScrollTrigger, Flip);
```

Then in other files:

```ts
import { gsap, ScrollTrigger } from "../gsap";
```

**UMD/dist format** (for older build tools that don't support ES modules):

```ts
import { gsap } from "gsap/dist/gsap";
import { ScrollTrigger } from "gsap/dist/ScrollTrigger";
```

> **Tree shaking:** Always call `gsap.registerPlugin(...)` to prevent build tools from dropping plugins during tree shaking. It's safe to register the same plugin multiple times.

---

## Core Concepts

GSAP has two primary animation primitives:

**Tween** — animates properties on target(s). Created with `gsap.to()`, `gsap.from()`, or `gsap.fromTo()`.

**Timeline** — a container for sequencing multiple tweens and other timelines. Created with `gsap.timeline()`.

Both extend an `Animation` base class and share the same control methods (`play`, `pause`, `reverse`, `seek`, `timeScale`, etc.).

GSAP can animate **any numeric property** of any JavaScript object — not just CSS. DOM elements, canvas contexts, WebGL uniforms, plain objects — anything works.

**Transform shorthand** — GSAP provides shorthand properties that map to CSS transforms:

| GSAP property               | CSS equivalent                   |
| --------------------------- | -------------------------------- |
| `x`, `y`                    | `translateX`, `translateY`       |
| `xPercent`, `yPercent`      | `translateX(%)`, `translateY(%)` |
| `rotation`                  | `rotate` (degrees)               |
| `rotationX`, `rotationY`    | `rotateX`, `rotateY`             |
| `scale`, `scaleX`, `scaleY` | `scale`                          |
| `skewX`, `skewY`            | `skew`                           |

---

## Tweens

```ts
// Animate TO values
gsap.to(".selector", {
  x: 100,
  y: 50,
  rotation: 360,
  backgroundColor: "red", // camelCase CSS
  duration: 1, // seconds (default: 0.5)
  delay: 0.5,
  ease: "power2.inOut",
  stagger: 0.1, // offset start per target
  paused: false,
  overwrite: "auto", // "auto" | true | false
  repeat: 2, // -1 = infinite
  repeatDelay: 1,
  repeatRefresh: true, // re-evaluate dynamic values each repeat
  yoyo: true, // A→B→A ping-pong
  yoyoEase: "power1.in", // separate ease for reverse
  immediateRender: false,
  onStart: () => {},
  onUpdate: () => {},
  onComplete: () => {},
  onRepeat: () => {},
  onReverseComplete: () => {},
});

// Animate FROM values (immediateRender: true by default)
gsap.from(".selector", { x: -200, opacity: 0, duration: 1 });

// Animate from → to (define both explicitly)
gsap.fromTo(
  ".selector",
  { x: -200, opacity: 0 },
  { x: 0, opacity: 1, duration: 1 },
);

// Set immediately (no animation)
gsap.set(".selector", { x: 100, opacity: 0 });
```

**Function-based values** — called once per target, returning the value to use:

```ts
gsap.to(".box", {
  x: (index, target, targets) => index * 100,
  duration: 1,
});
```

**Random values:**

```ts
gsap.to(".box", {
  x: "random(-100, 100)", // random number in range
  x: "random(-100, 100, 5)", // rounded to nearest 5
  x: "random([0, 100, 200])", // random from array
});
```

**Relative values:**

```ts
gsap.to(".box", { x: "+=50", rotation: "-=30" });
```

**Keyframes:**

```ts
gsap.to(".box", {
  keyframes: [
    { x: 100, duration: 1 },
    { y: 50, duration: 0.5 },
    { opacity: 0, duration: 0.5 },
  ],
});
```

**Special properties:**

| Property            | Description                                 |
| ------------------- | ------------------------------------------- |
| `duration`          | Duration in seconds (default `0.5`)         |
| `delay`             | Delay before start (seconds)                |
| `ease`              | Easing function name or function            |
| `stagger`           | Start time offset per target                |
| `repeat`            | Number of repeats (`-1` = infinite)         |
| `repeatDelay`       | Pause between repeats                       |
| `yoyo`              | Ping-pong direction on repeat               |
| `paused`            | Start paused                                |
| `overwrite`         | Kill confl

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

Gates applied: no_behavioural_pass, no_license.