akili-specs 2.7.0 → 2.8.0

package/.claude/skills/gsap-animation/references/frameworks.md

@@ -0,0 +1,137 @@
+# GSAP with Vue, Svelte, and Other Frameworks
+
+Read when writing or reviewing GSAP in Vue (or Nuxt), Svelte (or SvelteKit), or other component frameworks with a mounted/unmounted lifecycle. For **React** use `references/react.md` (useGSAP, contextSafe).
+
+## Principles (All Frameworks)
+
+- **Create** tweens and ScrollTriggers **after** the component's DOM is available (e.g. onMounted, onMount).
+- **Kill or revert** them on **unmount** so nothing runs on detached nodes and there are no leaks.
+- **Scope selectors** to the component root so `.box` matches only elements inside that component.
+
+## Vue 3 (Composition API)
+
+Use **onMounted** to run GSAP after the component is in the DOM; **onUnmounted** to clean up.
+
+```javascript
+import { onMounted, onUnmounted, ref } from "vue";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+gsap.registerPlugin(ScrollTrigger); // once per app, e.g. in main.js
+
+export default {
+  setup() {
+    const container = ref(null);
+    let ctx;
+
+    onMounted(() => {
+      if (!container.value) return;
+      ctx = gsap.context(() => {
+        gsap.to(".box", { x: 100, duration: 0.6 });
+        gsap.from(".item", { autoAlpha: 0, y: 20, stagger: 0.1 });
+      }, container.value);
+    });
+
+    onUnmounted(() => {
+      ctx?.revert();
+    });
+
+    return { container };
+  }
+};
+```
+
+- ✅ **gsap.context(callback, scope)** — pass the container ref (`container.value`) so selectors like `.item` are scoped to that root. All animations and ScrollTriggers created inside are tracked and reverted on **ctx.revert()**.
+- ✅ **onUnmounted** — always call **ctx.revert()**.
+
+## Vue 3 (script setup)
+
+```javascript
+<script setup>
+import { onMounted, onUnmounted, ref } from "vue";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+const container = ref(null);
+let ctx;
+
+onMounted(() => {
+  if (!container.value) return;
+  ctx = gsap.context(() => {
+    gsap.to(".box", { x: 100 });
+    gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
+  }, container.value);
+});
+
+onUnmounted(() => {
+  ctx?.revert();
+});
+</script>
+
+<template>
+  <div ref="container">
+    <div class="box">Box</div>
+    <div class="item">Item</div>
+  </div>
+</template>
+```
+
+## Svelte
+
+Use **onMount** to run GSAP after the DOM is ready; return a cleanup that reverts. Svelte 5 uses a different lifecycle, but the principle is the same: create in "mounted", revert in "destroyed".
+
+```javascript
+<script>
+  import { onMount } from "svelte";
+  import { gsap } from "gsap";
+  import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+  let container;
+
+  onMount(() => {
+    if (!container) return;
+    const ctx = gsap.context(() => {
+      gsap.to(".box", { x: 100 });
+      gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
+    }, container);
+    return () => ctx.revert();
+  });
+</script>
+
+<div bind:this={container}>
+  <div class="box">Box</div>
+  <div class="item">Item</div>
+</div>
+```
+
+- ✅ **bind:this={container}** — reference the root element to pass to **gsap.context(scope)**.
+- ✅ **return () => ctx.revert()** — onMount's returned cleanup runs when the component is destroyed.
+
+## Scoping Selectors
+
+Do not use global selectors that can match elements outside the current component. Always pass the **scope** (container element or ref) as the second argument to **gsap.context(callback, scope)**.
+
+- ✅ **gsap.context(() => { gsap.to(".box", ...) }, containerRef)** — `.box` is only searched inside `containerRef`.
+- ❌ Running **gsap.to(".box", ...)** without a context scope can affect other instances or the rest of the page.
+
+## ScrollTrigger Cleanup
+
+ScrollTrigger instances (via the `scrollTrigger` config on a tween/timeline or **ScrollTrigger.create()**) are **included** in **gsap.context()** and reverted on **ctx.revert()**. So:
+
+- Create ScrollTriggers inside the same **gsap.context()** callback you use for tweens.
+- Call **ScrollTrigger.refresh()** after layout changes that affect trigger positions — often after DOM updates (nextTick in Vue, tick in Svelte, or after async content load).
+
+## When to Create vs Kill
+
+| Lifecycle | Action |
+|-----------|--------|
+| **Mounted** | Create tweens and ScrollTriggers inside **gsap.context(scope)**. |
+| **Unmount / Destroy** | Call **ctx.revert()** so all animations and ScrollTriggers in that context are killed and inline styles reverted. |
+
+Do not create GSAP animations in setup or a synchronous top-level script that runs before the root element exists. Wait for **onMounted** / **onMount**.
+
+## Do Not
+
+- ❌ Create tweens or ScrollTriggers before the component is mounted; the DOM nodes may not exist yet.
+- ❌ Use selector strings without a **scope** (pass the container to gsap.context()).
+- ❌ Skip cleanup; always call **ctx.revert()** in onUnmounted / onMount's return.
+- ❌ Register plugins inside a component body that runs every render (wasteful); register once at app level.

package/.claude/skills/{gsap-performance/SKILL.md → gsap-animation/references/performance.md}

@@ -1,25 +1,15 @@
----
-name: gsap-performance
-description: Official GSAP skill for performance — prefer transforms, avoid layout thrashing, will-change, batching. Use when optimizing GSAP animations, reducing jank, or when the user asks about animation performance, FPS, or smooth 60fps.
-license: MIT
----
-
 # GSAP Performance
 
-## When to Use This Skill
-
-Apply when optimizing GSAP animations for smooth 60fps, reducing layout/paint cost, or when the user asks about performance, jank, or best practices for fast animations.
-
-**Related skills:** Build animations with **gsap-core** (transforms, autoAlpha) and **gsap-timeline**; for ScrollTrigger performance see **gsap-scrolltrigger**.
+Read when optimizing GSAP animations for smooth 60fps, reducing jank/dropped frames, avoiding layout thrashing, or when /akili-validate routes a performance issue here.
 
 ## Prefer Transform and Opacity
 
-Animating **transform** (`x`, `y`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`) and **opacity** keeps work on the compositor and avoids layout and most paint. Avoid animating layout-heavy properties when a transform can achieve the same effect.
+Animating **transform** (`x`, `y`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`) and **opacity** keeps work on the compositor and avoids layout and most paint.
 
 - ✅ Prefer: **x**, **y**, **scale**, **rotation**, **opacity**.
 - ❌ Avoid when possible: **width**, **height**, **top**, **left**, **margin**, **padding** (they trigger layout and can cause jank).
 
-GSAP’s **x** and **y** use transforms (translate) by default; use them instead of **left**/**top** for movement.
+GSAP's **x** and **y** use transforms (translate) by default; use them instead of **left**/**top** for movement.
 
 ## will-change
 
@@ -35,13 +25,13 @@ GSAP batches updates internally. When mixing GSAP with direct DOM reads/writes o
 
 ## Many Elements (Stagger, Lists)
 
-- Use **stagger** instead of many separate tweens with manual delays when the animation is the same; it’s more efficient.
-- For long lists, consider **virtualization** or animating only visible items; avoid creating hundreds of simultaneous tweens if it causes jank.
+- Use **stagger** instead of many separate tweens with manual delays when the animation is the same; it's more efficient.
+- For long lists, consider **virtualization** or animating only visible items; avoid hundreds of simultaneous tweens if it causes jank.
 - Reuse timelines where possible; avoid creating new timelines every frame.
 
 ## Frequently updated properties (e.g. mouse followers)
 
-Prefer **gsap.quickTo()** for properties that are updated often (e.g. mouse-follower x/y). It reuses a single tween instead of creating new tweens on each update. 
+Prefer **gsap.quickTo()** for properties updated often (e.g. mouse-follower x/y). It reuses a single tween instead of creating a new one on each update.
 
 ```javascript
 let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
@@ -55,13 +45,13 @@ document.querySelector("#container").addEventListener("mousemove", (e) => {
 
 ## ScrollTrigger and Performance
 
-- **pin: true** promotes the pinned element; pin only what’s needed.
+- **pin: true** promotes the pinned element; pin only what's needed.
 - **scrub** with a small value (e.g. `scrub: 1`) can reduce work during scroll; test on low-end devices.
 - Call **ScrollTrigger.refresh()** only when layout actually changes (e.g. after content load), not on every resize; debounce when possible.
 
 ## Reduce Simultaneous Work
 
-- Pause or kill off-screen or inactive animations when they’re not visible (e.g. when the user navigates away).
+- Pause or kill off-screen or inactive animations when not visible (e.g. when the user navigates away).
 - Avoid animating huge numbers of properties on many elements at once; simplify or sequence if needed.
 
 ## Best practices
@@ -73,7 +63,7 @@ document.querySelector("#container").addEventListener("mousemove", (e) => {
 
 ## Do Not
 
-- ❌ Animate **width**/ **height**/ **top**/ **left** for movement when **x**/ **y**/ **scale** can achieve the same look.
-- ❌ Set **will-change** or **force3D** on every element “just in case”; use for elements that are actually animating.
+- ❌ Animate **width**/**height**/**top**/**left** for movement when **x**/**y**/**scale** can achieve the same look.
+- ❌ Set **will-change** or **force3D** on every element "just in case"; use for elements that are actually animating.
 - ❌ Create hundreds of overlapping tweens or ScrollTriggers without testing on low-end devices.
 - ❌ Ignore cleanup; stray tweens and ScrollTriggers keep running and can hurt performance and correctness.

package/.claude/skills/gsap-animation/references/plugins.md

@@ -0,0 +1,390 @@
+# GSAP Plugins
+
+Read when using any GSAP plugin: scroll-to, ScrollSmoother, Flip/FLIP, Draggable, Inertia, Observer, SplitText, ScrambleText, DrawSVG, MorphSVG, MotionPath, physics, easing plugins (CustomEase, EasePack, CustomWiggle, CustomBounce), GSDevTools, or Pixi. (ScrollTrigger has its own file: `references/scrolltrigger.md`.)
+
+## Registering Plugins
+
+Register each plugin once before first use (see SKILL.md for the shared pattern):
+
+```javascript
+import gsap from "gsap";
+import { ScrollToPlugin } from "gsap/ScrollToPlugin";
+import { Flip } from "gsap/Flip";
+import { Draggable } from "gsap/Draggable";
+
+gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);
+```
+
+- ✅ Register before using the plugin in any tween or API call.
+- ✅ In React, register at top level or once in the app (before first `useGSAP`); do not register inside a component that re-renders. `useGSAP` is itself a plugin that needs registration.
+
+## Scroll
+
+### ScrollToPlugin
+
+Animates scroll position (window or a scrollable element). Use for "scroll to element/position" without ScrollTrigger.
+
+```javascript
+gsap.registerPlugin(ScrollToPlugin);
+
+gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
+gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
+gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });
+```
+
+| Option | Description |
+|--------|-------------|
+| `x`, `y` | Target scroll position (number), or `"max"` for maximum |
+| `element` | Selector or element to scroll to (scroll-into-view) |
+| `offsetX`, `offsetY` | Offset in pixels from the target position |
+
+### ScrollSmoother
+
+Smooth scroll wrapper (smooths native scroll). Requires ScrollTrigger and a specific DOM structure. Register after ScrollTrigger.
+
+```html
+<body>
+  <div id="smooth-wrapper">
+    <div id="smooth-content">
+      <!-- ALL YOUR CONTENT HERE -->
+    </div>
+  </div>
+  <!-- position: fixed elements can go outside -->
+</body>
+```
+
+## DOM / UI
+
+### Flip
+
+Capture state with `Flip.getState()`, change the DOM (layout/classes), then `Flip.from()` animates from the previous state to the new state (FLIP: First, Last, Invert, Play). Use when animating between two layout states (lists, grids, expand/collapse).
+
+```javascript
+gsap.registerPlugin(Flip);
+
+const state = Flip.getState(".item");
+// change DOM (reorder, add/remove, change classes)
+Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
+```
+
+| Option | Description |
+|--------|-------------|
+| `absolute` | Use `position: absolute` during the flip (default `false`) |
+| `nested` | When true, only the first level of children is measured (better for nested transforms) |
+| `scale` | When true, scale elements to fit (avoids stretch); default `true` |
+| `simple` | When true, only position/scale animated (faster, less accurate) |
+| `duration`, `ease` | Standard tween options |
+
+Docs: https://gsap.com/docs/v3/Plugins/Flip
+
+### Draggable
+
+Makes elements draggable, spinnable, or throwable. Use for sliders, cards, reorderable lists, or any drag interaction.
+
+```javascript
+gsap.registerPlugin(Draggable, InertiaPlugin);
+
+Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
+Draggable.create(".knob", { type: "rotation" });
+```
+
+| Option | Description |
+|--------|-------------|
+| `type` | `"x"`, `"y"`, `"x,y"`, `"rotation"`, `"scroll"` |
+| `bounds` | Element, selector, or `{ minX, maxX, minY, maxY }` to constrain drag |
+| `inertia` | `true` for throw/momentum (requires InertiaPlugin) |
+| `edgeResistance` | 0–1; resistance when dragging past bounds |
+| `cursor` | CSS cursor during drag |
+| `onDragStart`, `onDrag`, `onDragEnd` | Callbacks; receive event and target |
+| `onThrowUpdate`, `onThrowComplete` | Callbacks when inertia is active |
+
+### Inertia (InertiaPlugin)
+
+Works with Draggable for momentum after release, or tracks the velocity of any property so it can glide to a stop. Register with Draggable when using `inertia: true`:
+
+```javascript
+gsap.registerPlugin(Draggable, InertiaPlugin);
+Draggable.create(".box", { type: "x,y", inertia: true });
+```
+
+Track velocity of a property, then use `"auto"` to continue current velocity and glide to a stop:
+
+```javascript
+InertiaPlugin.track(".box", "x");
+gsap.to(obj, { inertia: { x: "auto" } });
+```
+
+### Observer
+
+Normalizes pointer and scroll input across devices. Use for swipe, scroll direction, or custom gesture logic without tying to scroll position.
+
+```javascript
+gsap.registerPlugin(Observer);
+
+Observer.create({
+  target: "#area",
+  onUp: () => {},
+  onDown: () => {},
+  onLeft: () => {},
+  onRight: () => {},
+  tolerance: 10
+});
+```
+
+| Option | Description |
+|--------|-------------|
+| `target` | Element or selector to observe |
+| `onUp`, `onDown`, `onLeft`, `onRight` | Callbacks when swipe/scroll passes tolerance in that direction |
+| `tolerance` | Pixels before direction is detected; default 10 |
+| `type` | `"touch"`, `"pointer"`, or `"wheel"` (default `"touch,pointer"`) |
+
+## Text
+
+### SplitText
+
+Splits an element's text into characters, words, and/or lines (each in its own element) for staggered animation. Returns an instance with **chars**, **words**, **lines** (and **masks** when `mask` is set). Restore original markup with **revert()** or let **gsap.context()** revert. Integrates with **gsap.context()**, **matchMedia()**, and **useGSAP()**. API: **SplitText.create(target, vars)**.
+
+```javascript
+gsap.registerPlugin(SplitText);
+
+const split = SplitText.create(".heading", { type: "words, chars" });
+gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
+// later: split.revert() or let gsap.context() cleanup revert
+```
+
+With **onSplit()** (3.13.0+), animations run on each split and on re-split when **autoSplit** is used; returning a tween/timeline from **onSplit()** lets SplitText clean up and sync progress on re-split:
+
+```javascript
+SplitText.create(".split", {
+  type: "lines",
+  autoSplit: true,
+  onSplit(self) {
+    return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
+  }
+});
+```
+
+| Option | Description |
+|--------|-------------|
+| **type** | Comma-separated: `"chars"`, `"words"`, `"lines"`. Default `"chars,words,lines"`. Split only what's needed for performance. Avoid chars-only without words/lines, or use **smartWrap: true**. |
+| **charsClass**, **wordsClass**, **linesClass** | CSS class on each split element. Append `"++"` for an incremented class (e.g. `linesClass: "line++"` → `line1`, `line2`, …). |
+| **aria** | `"auto"` (default), `"hidden"`, or `"none"`. `"auto"` adds `aria-label` on the element and `aria-hidden` on split units; `"hidden"` hides all from readers; `"none"` leaves aria unchanged. |
+| **autoSplit** | When `true`, reverts and re-splits when fonts load or element width changes (lines split), avoiding wrong line breaks. **Animations must be created inside onSplit()**; **return** the animation for automatic cleanup and time-sync on re-split. |
+| **onSplit(self)** | Callback when split completes (and on each re-split if **autoSplit**). Returning a tween/timeline enables automatic revert/sync on re-split. |
+| **mask** | `"lines"`, `"words"`, or `"chars"`. Wraps each unit with `overflow: clip` for mask/reveal effects. Access wrappers on the instance's **masks** array. |
+| **tag** | Wrapper tag; default `"div"`. Use `"span"` for inline (transforms like rotation/scale may not render on inline elements in some browsers). |
+| **deepSlice** | When `true` (default), nested elements spanning multiple lines are subdivided so lines don't stretch vertically. Line-splitting only. |
+| **ignore** | Selector or element(s) to leave unsplit (e.g. `ignore: "sup"`). |
+| **smartWrap** | When splitting **chars** only, wraps words in `white-space: nowrap` to avoid mid-word breaks. Ignored if words/lines are split. Default `false`. |
+| **wordDelimiter** | Word boundary: string (default `" "`), RegExp, or `{ delimiter: RegExp, replaceWith: string }`. |
+| **prepareText(text, parent)** | Function returning modified text before splitting (e.g. insert break markers for languages without spaces). |
+| **propIndex** | When `true`, adds a CSS variable with index on each split element (`--word: 1`, `--char: 2`). |
+| **reduceWhiteSpace** | Collapse consecutive spaces; default `true`. From 3.13.0 also honors line breaks / `<pre>`. |
+| **onRevert** | Callback when the instance is reverted. |
+
+**Tips:** Split only what is animated. For custom fonts, split after they load (`document.fonts.ready.then(...)`) or use **autoSplit: true** with **onSplit()**. To avoid kerning shift when splitting chars, use CSS `font-kerning: none; text-rendering: optimizeSpeed;`. Avoid `text-wrap: balance`. SplitText does not support SVG `<text>`.
+
+Docs: [SplitText](https://gsap.com/docs/v3/Plugins/SplitText/)
+
+### ScrambleText
+
+Animates text with a scramble/glitch effect.
+
+```javascript
+gsap.registerPlugin(ScrambleTextPlugin);
+
+gsap.to(".text", {
+  duration: 1,
+  scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
+});
+```
+
+## SVG
+
+### DrawSVG (DrawSVGPlugin)
+
+Reveals/hides the stroke of SVG elements by animating `stroke-dashoffset` / `stroke-dasharray`. Works on `<path>`, `<line>`, `<polyline>`, `<polygon>`, `<rect>`, `<ellipse>`. Use for "drawing"/"erasing" strokes.
+
+**drawSVG value:** Describes the **visible segment** of the stroke (`"start end"` in percent or length), not "A to B over time." `"0% 100%"` = full stroke; `"20% 80%"` = stroke only between 20% and 80%. The tween animates from the element's **current** segment to the **target** segment. Single value (e.g. `0`, `"100%"`) means start is 0.
+
+**Required:** The element must have a visible stroke (`stroke` + `stroke-width`), else nothing draws.
+
+```javascript
+gsap.registerPlugin(DrawSVGPlugin);
+
+gsap.from("#path", { duration: 1, drawSVG: 0 });                       // nothing → full stroke
+gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
+gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });                 // middle only
+```
+
+**Caveats:** Only affects stroke (not fill). Prefer single-segment `<path>` elements. Contents of `<use>` cannot be visually changed. **DrawSVGPlugin.getLength(element)** and **DrawSVGPlugin.getPosition(element)** return stroke length/position.
+
+Docs: [DrawSVG](https://gsap.com/docs/v3/Plugins/DrawSVGPlugin)
+
+### MorphSVG (MorphSVGPlugin)
+
+Morphs one SVG shape into another by animating the `d` attribute. Start/end shapes need not share point counts. Works on `<path>`, `<polyline>`, `<polygon>`; primitives are converted internally or via **MorphSVGPlugin.convertToPath()**.
+
+**morphSVG value:** a **selector**, **element**, **raw path data**, or (for polygon/polyline) a **points string**. Full config uses the **object form** with **shape** required.
+
+```javascript
+gsap.registerPlugin(MorphSVGPlugin);
+
+MorphSVGPlugin.convertToPath("circle, rect, ellipse, line"); // if needed
+
+gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
+gsap.to("#diamond", {
+  duration: 1,
+  morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 }
+});
+```
+
+| Option | Description |
+|--------|-------------|
+| **shape** | _(Required.)_ Target shape: selector, element, or raw path string. |
+| **type** | `"linear"` (default) or `"rotational"`. Rotational uses angle/length interpolation and can avoid mid-morph kinks. |
+| **map** | Segment matching: `"size"` (default), `"position"`, or `"complexity"`. |
+| **shapeIndex** | Offsets which start point maps to the first end point (avoids crossing/inverting). Number for single-segment; **array** for multi-segment (negative reverses that segment). Use **shapeIndex: "log"** once to log the auto value; **findShapeIndex(start, end)** gives an interactive UI. Closed paths only. |
+| **smooth** | (3.14+). Smoothing points. Number, `"auto"`, or object `{ points, redraw, persist }`. `redraw: false` keeps original anchors; `persist: false` removes added points on end. |
+| **curveMode** | Boolean (3.14+). Interpolates control-handle angle/length instead of raw x/y to avoid kinks. |
+| **origin** | Rotation origin for **type: "rotational"**. `"50% 50%"` (default) or `"20% 60%, 35% 90%"` for different start/end origins. |
+| **precision** | Decimal places for output path data; default `2`. |
+| **precompile** | Array of precomputed path strings (or `"log"` once, copy from console). Skips startup calc for complex morphs; `<path>` only. |
+| **render** | Function(rawPath, target) each update — e.g. draw to canvas. |
+| **updateTarget** | Set `false` (with **render**, e.g. canvas-only) so the original `<path>` isn't updated. |
+
+**Utilities:** **convertToPath(selector | element)**, **rawPathToString(rawPath)**, **stringToRawPath(d)**. The plugin stores the original `d` for tweening back.
+
+**Tips:** For twisted/inverted morphs set **shapeIndex** (`"log"` or findShapeIndex()). Precompile only when the first frame is slow; it doesn't fix jank during the tween.
+
+Docs: [MorphSVG](https://gsap.com/docs/v3/Plugins/MorphSVGPlugin)
+
+### MotionPath (MotionPathPlugin)
+
+Animates an element along an SVG path.
+
+```javascript
+gsap.registerPlugin(MotionPathPlugin);
+
+gsap.to(".dot", {
+  duration: 2,
+  motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5] }
+});
+```
+
+| Option | Description |
+|--------|-------------|
+| `path` | SVG path element, selector, or path data string |
+| `align` | Path element or selector to align the target to |
+| `alignOrigin` | `[x, y]` origin (0–1); default `[0.5, 0.5]` |
+| `autoRotate` | Rotate element to follow path tangent |
+| `curviness` | 0–2; path smoothing |
+
+### MotionPathHelper
+
+Visual editor for MotionPath (alignment, offset). Development only.
+
+```javascript
+gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);
+
+const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
+```
+
+## Easing
+
+### CustomEase
+
+Custom easing curves (cubic-bezier or SVG path) — use when a built-in ease is not enough. Register when using:
+
+```javascript
+gsap.registerPlugin(CustomEase);
+
+// Simple cubic-bezier (same values as CSS cubic-bezier())
+const myEase = CustomEase.create("my-ease", ".17,.67,.83,.67");
+gsap.to(".item", { x: 100, ease: myEase, duration: 1 });
+
+// Complex curve with any number of control points, as normalized SVG path data
+const hop = CustomEase.create("hop", "M0,0 C0,0 0.056,0.442 0.175,0.442 0.294,0.442 0.332,0 0.332,0 0.332,0 0.414,1 0.671,1 0.991,1 1,0 1,0");
+gsap.to(".item", { x: 100, ease: hop, duration: 1 });
+```
+
+### EasePack
+
+Adds more named eases (SlowMo, RoughEase, ExpoScaleEase). Register and use by name in tweens.
+
+### CustomWiggle
+
+Wiggle/shake easing — a value oscillates multiple times.
+
+### CustomBounce
+
+Bounce-style easing with configurable strength.
+
+## Physics
+
+### Physics2D (Physics2DPlugin)
+
+2D physics (velocity, angle, gravity). Use for projectiles, bouncing.
+
+```javascript
+gsap.registerPlugin(Physics2DPlugin);
+
+gsap.to(".ball", {
+  duration: 2,
+  physics2D: { velocity: 250, angle: 80, gravity: 500 }
+});
+```
+
+### PhysicsProps (PhysicsPropsPlugin)
+
+Applies physics to property values.
+
+```javascript
+gsap.registerPlugin(PhysicsPropsPlugin);
+
+gsap.to(".obj", {
+  duration: 2,
+  physicsProps: {
+    x: { velocity: 100, end: 300 },
+    y: { velocity: -50, acceleration: 200 }
+  }
+});
+```
+
+## Development
+
+### GSDevTools
+
+UI for scrubbing timelines, toggling, and debugging. **Development only — do not ship.**
+
+```javascript
+gsap.registerPlugin(GSDevTools);
+GSDevTools.create({ animation: tl });
+```
+
+## Other
+
+### Pixi (PixiPlugin)
+
+Integrates GSAP with PixiJS for animating Pixi display objects.
+
+```javascript
+gsap.registerPlugin(PixiPlugin);
+
+const sprite = new PIXI.Sprite(texture);
+gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 });
+```
+
+## Best practices
+
+- ✅ Register every plugin used with **gsap.registerPlugin()** before first use.
+- ✅ Use **Flip.getState()** → DOM change → **Flip.from()** for layout transitions; use **Draggable** + **InertiaPlugin** for drag with momentum.
+- ✅ Revert plugin instances (e.g. `splitInstance.revert()`) when components unmount or elements are removed.
+
+## Do Not
+
+- ❌ Use a plugin in a tween or API without registering it first.
+- ❌ Ship GSDevTools or development-only plugins to production.
+
+### Learn More
+https://gsap.com/docs/v3/Plugins/