@polymorphism-tech/morph-spec 4.16.0 → 4.17.0

package/framework/standards/frontend/gsap/gsap-plugins.md

@@ -0,0 +1,294 @@
+---
+scope: frontend-nextjs-gsap
+layer: 3
+keywords: flip, splittext, morphsvg, drawsvg, motionpath, draggable, observer, scrollto, gsap-plugins
+load_when: gsap-animator active
+---
+
+# GSAP Plugins
+
+Reference guide for GSAP's plugin ecosystem in Next.js. Covers free plugins (Flip, Observer, ScrollToPlugin) and Club GreenSock premium plugins (SplitText, MorphSVG, DrawSVG, MotionPath, Draggable, InertiaPlugin).
+
+## Plugin Registration & Licensing
+
+Free plugins (included in gsap 3.12+): Flip, Observer, ScrollToPlugin
+
+Premium (Club GreenSock): SplitText, MorphSVG, DrawSVG, MotionPath, Draggable, InertiaPlugin, ScrambleText, CustomEase, CustomWiggle, CustomBounce, Physics2D, PhysicsProps
+
+```bash
+# Free plugins — included with gsap
+npm install gsap
+
+# Premium plugins — requires Club GreenSock license
+npm install gsap@npm:@gsap/shockingly
+```
+
+Registration pattern (do ONCE at app init):
+
+```typescript
+'use client';
+import gsap from 'gsap';
+import { Flip } from 'gsap/Flip';
+import { SplitText } from 'gsap/SplitText';
+import { ScrollToPlugin } from 'gsap/ScrollToPlugin';
+
+gsap.registerPlugin(Flip, SplitText, ScrollToPlugin);
+```
+
+## Flip Plugin (Free)
+
+Layout transition animations using the FLIP technique (First, Last, Invert, Play):
+
+```typescript
+'use client';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+import { Flip } from 'gsap/Flip';
+
+function FilterableGrid({ items, filter }: { items: Item[]; filter: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const applyFilter = (newFilter: string) => {
+    // 1. Capture current state
+    const state = Flip.getState('.grid-item');
+
+    // 2. Make DOM changes (reorder, show/hide)
+    setFilter(newFilter);
+
+    // 3. Animate from old positions to new
+    Flip.from(state, {
+      duration: 0.6,
+      ease: 'power2.out',
+      stagger: 0.04,
+      absolute: true,       // prevents layout jumping during animation
+      onEnter: (elements) => gsap.fromTo(elements, { opacity: 0, scale: 0.8 }, { opacity: 1, scale: 1, duration: 0.4 }),
+      onLeave: (elements) => gsap.to(elements, { opacity: 0, scale: 0.8, duration: 0.3 }),
+    });
+  };
+}
+```
+
+Use cases: filterable grids, list reordering, expanding cards, shared element transitions.
+
+## SplitText (Premium)
+
+Split text into chars, words, or lines for staggered reveals:
+
+```typescript
+useGSAP(() => {
+  const split = SplitText.create('.hero-title', {
+    type: 'chars,words',
+    autoSplit: true,         // re-splits on resize
+    onSplit: () => {
+      // Animate after split is ready
+      gsap.from(split.chars, {
+        y: 30,
+        opacity: 0,
+        stagger: 0.03,
+        duration: 0.5,
+        ease: 'power2.out',
+      });
+    },
+  });
+
+  // Cleanup: revert split on unmount (handled by useGSAP context)
+}, { scope: containerRef });
+```
+
+Key points:
+- Use `autoSplit: true` for responsive -- re-splits when container resizes
+- Use `onSplit` callback to animate AFTER split completes
+- The split creates `<div>` wrappers -- this affects layout. Test carefully.
+- useGSAP automatically reverts the split on unmount
+
+## MorphSVG (Premium)
+
+Morph between SVG shapes:
+
+```typescript
+gsap.to('#circle', {
+  morphSVG: {
+    shape: '#star',
+    type: 'rotational',    // smoother for complex shapes
+    shapeIndex: 'auto',     // auto-aligns anchor points
+  },
+  duration: 1.2,
+  ease: 'power2.inOut',
+});
+
+// Convert non-path SVG elements to paths first
+MorphSVGPlugin.convertToPath('circle, rect, ellipse, polygon, polyline, line');
+```
+
+Rules:
+- Both shapes must be `<path>` elements (use convertToPath for others)
+- Match point counts for smoother morphs
+- `type: "rotational"` is smoother for most shapes
+
+## DrawSVG (Premium)
+
+Animate SVG stroke drawing:
+
+```typescript
+// Draw stroke from 0% to 100%
+gsap.fromTo('.svg-path',
+  { drawSVG: '0%' },
+  { drawSVG: '100%', duration: 2, ease: 'power2.inOut' }
+);
+
+// Partial draws
+gsap.to('.line', { drawSVG: '20% 80%', duration: 1 }); // middle section only
+
+// Line drawing reveal pattern
+const paths = gsap.utils.toArray<SVGPathElement>('.icon path');
+gsap.from(paths, {
+  drawSVG: '0%',
+  stagger: 0.2,
+  duration: 1,
+  ease: 'power1.out',
+});
+```
+
+Requires SVG elements with visible `stroke` and `stroke-width`. Does not work on `fill`.
+
+## MotionPath (Premium)
+
+Animate elements along SVG paths:
+
+```typescript
+gsap.to('.rocket', {
+  motionPath: {
+    path: '#flight-path',
+    align: '#flight-path',
+    autoRotate: true,        // element rotates to follow path direction
+    alignOrigin: [0.5, 0.5], // center of element on path
+  },
+  duration: 3,
+  ease: 'power1.inOut',
+});
+```
+
+Use MotionPathHelper (dev tool) to visually edit paths: `MotionPathHelper.create('.rocket')`.
+
+## ScrollToPlugin (Free)
+
+Smooth scroll to elements or positions:
+
+```typescript
+// Scroll to element
+gsap.to(window, {
+  scrollTo: { y: '#contact-section', offsetY: 80 }, // 80px offset for header
+  duration: 1,
+  ease: 'power2.inOut',
+});
+
+// Scroll to position
+gsap.to(window, { scrollTo: { y: 500 }, duration: 0.8 });
+
+// Auto-kill on user scroll (prevents fighting user input)
+gsap.to(window, {
+  scrollTo: { y: '#section', autoKill: true },
+  duration: 1.5,
+});
+```
+
+## Draggable (Premium)
+
+Make elements draggable with optional physics:
+
+```typescript
+'use client';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+import { Draggable } from 'gsap/Draggable';
+
+function DraggableCard() {
+  const cardRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    Draggable.create(cardRef.current, {
+      type: 'x,y',
+      bounds: '.container',
+      edgeResistance: 0.65,
+      throwProps: true,        // momentum (requires InertiaPlugin)
+      snap: {
+        x: (value) => Math.round(value / 100) * 100, // snap to 100px grid
+        y: (value) => Math.round(value / 100) * 100,
+      },
+      onDrag() { /* called every frame during drag */ },
+      onDragEnd() { /* called when drag completes */ },
+    });
+  }, { scope: cardRef });
+}
+```
+
+## Observer (Free)
+
+Normalize pointer, scroll, touch, and wheel events:
+
+```typescript
+import { Observer } from 'gsap/Observer';
+
+Observer.create({
+  target: window,
+  type: 'wheel,touch,pointer',
+  onUp: () => goToSection(currentIndex - 1),
+  onDown: () => goToSection(currentIndex + 1),
+  tolerance: 10,           // minimum distance before triggering
+  preventDefault: true,     // prevent native scroll
+  wheelSpeed: -1,          // invert direction
+});
+```
+
+Use cases: custom scroll-jacking, swipe detection, directional gestures, fullpage scroll experiences.
+
+## Combining Plugins — Real-World Recipes
+
+**Recipe 1: Scroll-triggered text reveal**
+
+```typescript
+useGSAP(() => {
+  const split = SplitText.create('.reveal-text', { type: 'words', autoSplit: true });
+
+  gsap.from(split.words, {
+    y: 20,
+    opacity: 0,
+    stagger: 0.05,
+    duration: 0.5,
+    ease: 'power2.out',
+    scrollTrigger: {
+      trigger: '.reveal-text',
+      start: 'top 80%',
+      toggleActions: 'play none none none',
+    },
+  });
+}, { scope: containerRef });
+```
+
+**Recipe 2: Filterable grid with Flip + ScrollTrigger.refresh()**
+
+```typescript
+const handleFilter = (category: string) => {
+  const state = Flip.getState('.item');
+  setActiveCategory(category);
+
+  Flip.from(state, {
+    duration: 0.5,
+    stagger: 0.03,
+    absolute: true,
+    onComplete: () => ScrollTrigger.refresh(), // recalculate positions after layout change
+  });
+};
+```
+
+**Recipe 3: SVG icon draw + morph sequence**
+
+```typescript
+const tl = gsap.timeline({ scrollTrigger: { trigger: '.icon-section', start: 'top center' } });
+tl.from('.icon path', { drawSVG: '0%', stagger: 0.1, duration: 0.8 })
+  .to('.icon path', { morphSVG: '#final-shape', duration: 1, ease: 'power2.inOut' }, '+=0.3');
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/gsap/gsap-scrolltrigger.md

@@ -0,0 +1,318 @@
+---
+scope: frontend-nextjs-gsap
+layer: 3
+keywords: scrolltrigger, scroll-animation, pinning, scrubbing, parallax, scroll-driven, gsap
+load_when: gsap-animator active
+---
+
+# GSAP ScrollTrigger — Next.js
+
+Reference guide for implementing scroll-driven animations in Next.js projects using GSAP ScrollTrigger. Covers plugin setup, scrubbing, pinning, batch processing, responsive breakpoints, SSR considerations, and mandatory cleanup patterns.
+
+---
+
+## Section 1: Plugin Registration
+
+```typescript
+'use client';
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+
+gsap.registerPlugin(ScrollTrigger);
+```
+
+Register ONCE at app init. In Next.js, do this in a client-side providers file or at the top of client components. Never register inside `useEffect` or loops — repeated registration is wasted work and can cause subtle timing issues.
+
+---
+
+## Section 2: Basic ScrollTrigger
+
+The fundamental pattern: attach a `scrollTrigger` object to any GSAP tween.
+
+```typescript
+useGSAP(() => {
+  gsap.from('.card', {
+    y: 60,
+    opacity: 0,
+    duration: 0.8,
+    ease: 'power2.out',
+    stagger: 0.15,
+    scrollTrigger: {
+      trigger: '.cards-container',
+      start: 'top 80%',    // trigger-top hits viewport-80%
+      end: 'bottom 20%',
+      toggleActions: 'play none none none', // onEnter onLeave onEnterBack onLeaveBack
+      markers: false,       // true for debugging only
+    },
+  });
+}, { scope: containerRef });
+```
+
+**start/end syntax:** `"triggerPosition viewportPosition"`.
+
+| Value | Meaning |
+|-------|---------|
+| `"top center"` | Trigger element's top reaches viewport center |
+| `"top 80%"` | Trigger element's top reaches 80% down the viewport |
+| `"top top"` | Trigger element's top reaches viewport top |
+| `"bottom top"` | Trigger element's bottom reaches viewport top |
+
+**toggleActions** accepts four space-separated values for `onEnter`, `onLeave`, `onEnterBack`, `onLeaveBack`. Each value can be: `play`, `pause`, `resume`, `reverse`, `restart`, `reset`, `complete`, `none`.
+
+---
+
+## Section 3: Scrubbing
+
+Link animation progress directly to scroll position instead of playing on a timeline.
+
+```typescript
+gsap.to('.parallax-bg', {
+  y: -200,
+  ease: 'none', // linear for scrub
+  scrollTrigger: {
+    trigger: '.hero-section',
+    start: 'top top',
+    end: 'bottom top',
+    scrub: true,        // direct link (can feel jumpy)
+    // scrub: 0.5,      // smooth scrub with 0.5s delay
+  },
+});
+```
+
+**Rule:** Use `ease: "none"` with scrub for linear scroll-to-progress mapping. Non-linear eases with scrub cause unexpected acceleration/deceleration that fights the user's scroll intent.
+
+- `scrub: true` — instant 1:1 link between scroll and progress.
+- `scrub: 0.5` — smoothed with 0.5 second catch-up delay. Use values between 0.3 and 1 for production.
+- `scrub: 3` — heavy smoothing, good for background parallax layers.
+
+---
+
+## Section 4: Pinning
+
+Pin an element in place while the user scrolls through content.
+
+```typescript
+gsap.to('.pinned-content', {
+  x: '-300%', // horizontal scroll simulation
+  ease: 'none',
+  scrollTrigger: {
+    trigger: '.horizontal-section',
+    start: 'top top',
+    end: '+=3000',        // pin for 3000px of scroll
+    pin: true,
+    scrub: 1,
+    anticipatePin: 1,     // prevents jank on pin start
+    // pinSpacing: true,  // default: adds space for pinned section
+  },
+});
+```
+
+**Horizontal scroll pattern:** Pin the outer container, then translate an inner track of panels by `-100% * (panelCount - 1)` using scrub. The `end: "+=Npx"` controls how much vertical scroll maps to the horizontal distance.
+
+```typescript
+useGSAP(() => {
+  const panels = gsap.utils.toArray<HTMLElement>('.panel');
+
+  gsap.to(panels, {
+    xPercent: -100 * (panels.length - 1),
+    ease: 'none',
+    scrollTrigger: {
+      trigger: '.horizontal-wrapper',
+      start: 'top top',
+      end: () => `+=${panels.length * window.innerWidth}`,
+      pin: true,
+      scrub: 1,
+      snap: 1 / (panels.length - 1),
+      anticipatePin: 1,
+    },
+  });
+}, { scope: containerRef });
+```
+
+**Pinning rules:**
+- Set `anticipatePin: 1` to avoid visual jank when pinning starts.
+- `pinSpacing: false` prevents the extra space insertion — use only when the pinned section overlaps subsequent content intentionally.
+- Never nest pinned elements inside other pinned elements.
+
+---
+
+## Section 5: Batch Processing
+
+For staggered reveals on lists and grids, use `ScrollTrigger.batch` instead of individual triggers.
+
+```typescript
+ScrollTrigger.batch('.grid-item', {
+  onEnter: (elements) => {
+    gsap.from(elements, {
+      y: 40,
+      opacity: 0,
+      stagger: 0.08,
+      duration: 0.6,
+      ease: 'power2.out',
+    });
+  },
+  start: 'top 85%',
+});
+```
+
+Use batch instead of individual ScrollTriggers for performance — one IntersectionObserver watches all matched elements instead of creating dozens of separate scroll listeners. This matters significantly for grids with 20+ items.
+
+Batch also supports `onLeave`, `onEnterBack`, and `onLeaveBack` callbacks with the same signature.
+
+---
+
+## Section 6: Scroll-linked Progress
+
+Use `onUpdate` for custom progress-based effects that go beyond simple tweens.
+
+```typescript
+ScrollTrigger.create({
+  trigger: '.progress-section',
+  start: 'top center',
+  end: 'bottom center',
+  onUpdate: (self) => {
+    // self.progress is 0-1
+    gsap.set('.progress-bar', { scaleX: self.progress });
+    gsap.set('.counter', { innerText: Math.round(self.progress * 100) + '%' });
+  },
+});
+```
+
+**Parallax layers pattern:** Assign different scroll speeds to layered elements using a `data-depth` attribute.
+
+```typescript
+gsap.utils.toArray<HTMLElement>('.parallax-layer').forEach((layer) => {
+  const depth = parseFloat(layer.dataset.depth || '0.5');
+  gsap.to(layer, {
+    y: -200 * depth,
+    ease: 'none',
+    scrollTrigger: {
+      trigger: layer.parentElement,
+      start: 'top bottom',
+      end: 'bottom top',
+      scrub: true,
+    },
+  });
+});
+```
+
+Layers with `data-depth="1"` move the full -200px, while `data-depth="0.2"` moves only -40px, creating natural depth.
+
+---
+
+## Section 7: Snap
+
+Snap scrolling to discrete sections for a full-page slide experience.
+
+```typescript
+ScrollTrigger.create({
+  trigger: '.sections-container',
+  start: 'top top',
+  end: 'bottom bottom',
+  snap: {
+    snapTo: 1 / (sectionCount - 1), // snap to each section
+    duration: { min: 0.2, max: 0.6 },
+    ease: 'power1.inOut',
+  },
+});
+```
+
+- `snapTo` accepts a number (interval), an array of progress values, or a function `(value) => snappedValue`.
+- `duration` can be a fixed number or `{ min, max }` range — GSAP picks based on scroll velocity.
+- Keep snap durations short (under 0.8s) to avoid fighting user intent.
+- Combine with `pin: true` for pinned section snapping.
+
+---
+
+## Section 8: Responsive
+
+Use `ScrollTrigger.matchMedia()` for breakpoint-aware animations.
+
+```typescript
+ScrollTrigger.matchMedia({
+  // desktop
+  '(min-width: 768px)': () => {
+    gsap.to('.sidebar', {
+      scrollTrigger: { trigger: '.content', pin: true, scrub: true },
+      y: -100,
+    });
+  },
+  // mobile — different or no animation
+  '(max-width: 767px)': () => {
+    gsap.set('.sidebar', { clearProps: 'all' });
+  },
+  // all: always active
+  all: () => {
+    // common setup shared across breakpoints
+  },
+});
+```
+
+Animations created inside each breakpoint callback are automatically reverted when the media query no longer matches, then re-created if the query matches again. This prevents stale transforms from desktop persisting on mobile after a resize.
+
+**Rules:**
+- Always define both desktop and mobile cases explicitly. Omitting mobile leaves desktop transforms applied.
+- Place `matchMedia` inside `useGSAP` so it is cleaned up on unmount.
+- Avoid overlapping breakpoint ranges — use exclusive boundaries (767px / 768px, not both at 768px).
+
+---
+
+## Section 9: Next.js SSR Considerations
+
+ScrollTrigger relies on the DOM, `window`, and scroll position — it cannot run server-side.
+
+**Mandatory rules for Next.js:**
+
+1. All ScrollTrigger code must live in `'use client'` components.
+2. Use the `useGSAP()` hook, which only executes client-side after mount. Never use bare `useEffect` for GSAP unless wrapping in `gsap.context()`.
+3. Call `ScrollTrigger.refresh()` after any event that changes layout dimensions:
+   - Dynamic content loads (API data arriving, skeleton replaced with real content)
+   - Layout shifts (accordion opens, tab changes, collapsible sections)
+   - Route changes in Next.js App Router
+   - Images finishing load
+4. For Next.js Image components, use the `onLoad` callback to trigger a refresh:
+
+```typescript
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  onLoad={() => ScrollTrigger.refresh()}
+/>
+```
+
+5. Use `ScrollTrigger.normalizeScroll(true)` for consistent cross-browser scroll behavior. This is particularly useful on iOS Safari where elastic bouncing and address bar resizing interfere with scroll calculations.
+6. Avoid `ScrollTrigger.create()` at module scope — always place it inside `useGSAP` or a `useEffect` to guarantee the DOM exists.
+
+---
+
+## Section 10: Cleanup
+
+```typescript
+// Automatic with useGSAP — kills all animations and ScrollTriggers created in scope
+useGSAP(() => {
+  // all ScrollTriggers here are auto-cleaned on unmount
+}, { scope: containerRef });
+
+// Manual cleanup (if not using useGSAP):
+useEffect(() => {
+  const ctx = gsap.context(() => {
+    // animations + ScrollTriggers
+  }, containerRef);
+  return () => ctx.revert(); // kills everything
+}, []);
+```
+
+**CRITICAL:** Always clean up ScrollTriggers on unmount. Orphaned ScrollTriggers cause memory leaks, stale callbacks, and broken scroll behavior on subsequent route navigations.
+
+**Refresh priority** for ordered triggers — higher priority triggers refresh first:
+
+```typescript
+ScrollTrigger.create({ trigger: '.first', refreshPriority: 1 });
+ScrollTrigger.create({ trigger: '.second', refreshPriority: -1 });
+```
+
+Use `refreshPriority` when one trigger's position depends on another's pinning or layout effect. The default priority is 0; higher values refresh first.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/motion-patterns.md

@@ -299,6 +299,7 @@ This CSS fallback catches animations outside Framer Motion (Tailwind `animate-*`
 | Forgetting `animation-fill-mode: backwards` in stagger | Will cause a flash before the animation starts |
 | `AnimatePresence` without `key` changes | Exit animations will never fire |
 | Using `framer-motion` for skeleton loaders | Use CSS `animate-pulse` — lower performance cost |
+| Need ScrollTrigger, SVG morph, or complex timelines | Use GSAP — see `frontend/gsap/gsap-core.md` |
 
 ---