@cosmictraveler002/anim-kit 1.1.0 → 1.2.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,oBAAoB;AACpB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAExH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAExC,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3F,8BAA8B;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGlD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAG9E,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,qBAAqB;AACrB,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG/C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGpD,2BAA2B;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,kCAAkC;AAClC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,oBAAoB;AACpB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAExH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAExC,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3F,8BAA8B;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGlD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAG9E,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,qBAAqB;AACrB,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG/C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGpD,2BAA2B;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGpD,kCAAkC;AAClC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmictraveler002/anim-kit",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Modular, framework-agnostic animation library — GSAP + ScrollTrigger + Lenis effects packaged as composable ES modules.",
   "type": "module",
   "main": "./dist/index.js",

package/src/core/gsap.ts

@@ -10,10 +10,11 @@ import { SplitText } from "gsap/SplitText";
 import { Draggable } from "gsap/Draggable";
 import { CustomEase } from "gsap/CustomEase";
 import { ScrollSmoother } from "gsap/ScrollSmoother";
+import { Flip } from "gsap/Flip";
 import { toArray } from "./util.js";
 import type { TargetLike } from "./types.js";
 
-export { gsap, ScrollTrigger, SplitText, Draggable, CustomEase, ScrollSmoother };
+export { gsap, ScrollTrigger, SplitText, Draggable, CustomEase, ScrollSmoother, Flip };
 
 /** Named eases recovered from dzinrstudio.com's bundles. */
 export const EASES = {
@@ -34,7 +35,7 @@ export function initGSAP(): void {
   if (initted || typeof window === "undefined") return;
   initted = true;
 
-  gsap.registerPlugin(ScrollTrigger, SplitText, Draggable, CustomEase);
+  gsap.registerPlugin(ScrollTrigger, SplitText, Draggable, CustomEase, Flip);
 
   // ScrollSmoother is a bonus for people who prefer it over Lenis; it is only
   // registered so `ScrollSmoother.create()` works if you call it yourself.

package/src/effects/clip-wipe.ts

@@ -1,14 +1,22 @@
 /**
  * Clip wipe — a `clip-path: inset()` reveal.
  *
- * The element is collapsed behind one edge (or inside a frame margin) and
- * the inset animates to zero, wiping it into view:
+ * The element is collapsed behind one edge, corner (or inside a frame margin)
+ * and the inset animates to zero, wiping it into view:
  *
- *   from: "left"   inset(0 100% 0 0)   → grows rightward from the left edge
- *   from: "right"  inset(0 0 0 100%)   → grows leftward from the right edge
- *   from: "top"    inset(0 0 100% 0)   → grows downward from the top edge
- *   from: "bottom" inset(100% 0 0 0)   → grows upward from the bottom edge
- *   from: "frame"  inset(15% 15% 15% 15%) → opens out of a centered frame
+ *   from: "left"         inset(0 100% 0 0)   → grows rightward from the left edge
+ *   from: "right"        inset(0 0 0 100%)   → grows leftward from the right edge
+ *   from: "top"          inset(0 0 100% 0)   → grows downward from the top edge
+ *   from: "bottom"       inset(100% 0 0 0)   → grows upward from the bottom edge
+ *   from: "top-left"     inset(0 100% 100% 0)   → opens toward the bottom-right corner
+ *   from: "top-right"    inset(0 0 100% 100%)   → opens toward the bottom-left corner
+ *   from: "bottom-left"  inset(100% 100% 0 0)   → opens toward the top-right corner
+ *   from: "bottom-right" inset(100% 0 0 100%)   → opens toward the top-left corner
+ *   from: "frame"        inset(15% 15% 15% 15%) → opens out of a centered frame
+ *
+ * The wipe can also be bound to scroll progress (`scrub`), so the inset
+ * opens as the element travels through the viewport — the reveal then
+ * reverses with the scroll instead of playing once.
  *
  * Works on images, videos, blocks and text. destroy() kills the tween and
  * removes the inline clip-path.
@@ -18,9 +26,20 @@ import { guard } from "../core/guard.js";
 import { toArray } from "../core/util.js";
 import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
 
+export type ClipWipeFrom =
+  | "left"
+  | "right"
+  | "top"
+  | "bottom"
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right"
+  | "frame";
+
 export interface ClipWipeOptions extends CommonOptions {
-  /** Which edge the wipe starts from. @default "left" */
-  from?: "left" | "right" | "top" | "bottom" | "frame";
+  /** Which edge or corner the wipe starts from. @default "left" */
+  from?: ClipWipeFrom;
   /** Frame margin in % (only used when `from: "frame"`). @default 15 */
   inset?: number;
   /** Animation duration, seconds. @default 1 */
@@ -35,8 +54,15 @@ export interface ClipWipeOptions extends CommonOptions {
   mode?: "scroll" | "immediate";
   /** ScrollTrigger start position. @default "top 85%" */
   start?: string;
+  /** ScrollTrigger end position (scrub mode). @default "top 20%" */
+  end?: string;
   /** Re-wipe when leaving / re-entering the viewport. @default false */
   replay?: boolean;
+  /**
+   * Bind the wipe to scroll progress instead of playing it on enter —
+   * number = scrub smoothing seconds, `true` = immediate. unset = one-shot.
+   */
+  scrub?: number | boolean;
 }
 
 const FROM: Record<string, string> = {
@@ -44,6 +70,10 @@ const FROM: Record<string, string> = {
   right: "inset(0% 0% 0% 100%)",
   top: "inset(0% 0% 100% 0%)",
   bottom: "inset(100% 0% 0% 0%)",
+  "top-left": "inset(0% 100% 100% 0%)",
+  "top-right": "inset(0% 0% 100% 100%)",
+  "bottom-left": "inset(100% 100% 0% 0%)",
+  "bottom-right": "inset(100% 0% 0% 100%)",
 };
 const TO = "inset(0% 0% 0% 0%)";
 
@@ -59,7 +89,9 @@ export function clipWipe(target: TargetLike, options: ClipWipeOptions = {}): Des
     delay = 0,
     mode = "scroll",
     start = "top 85%",
+    end = "top 20%",
     replay = false,
+    scrub,
   } = options;
 
   const els = toArray<HTMLElement>(target);
@@ -80,7 +112,15 @@ export function clipWipe(target: TargetLike, options: ClipWipeOptions = {}): Des
       delay,
       overwrite: "auto",
     };
-    if (mode === "scroll") {
+    if (scrub !== undefined) {
+      vars.ease = "none";
+      vars.scrollTrigger = {
+        trigger: els[0],
+        start,
+        end,
+        scrub: scrub === true ? true : scrub,
+      };
+    } else if (mode === "scroll") {
       vars.scrollTrigger = {
         trigger: els[0],
         start,

package/src/effects/cursor-follower.ts

@@ -5,6 +5,10 @@
  * whole thing fades/blurs in when the pointer enters the hot zone. The label
  * uses `mix-blend-mode: exclusion` so it inverts over any background.
  *
+ * The tag is pinned `position: fixed` and driven in VIEWPORT space
+ * (clientX/clientY + offset), so it can live anywhere in the DOM — it only
+ * reacts while the pointer is over the zone.
+ *
  *   cursorFollower(zone, { follower: ".ak-cursor" })
  */
 import { gsap, initGSAP, killTweens } from "../core/gsap.js";
@@ -51,7 +55,11 @@ export function cursorFollower(
     };
 
     el.style.mixBlendMode = blendMode as never;
-    el.style.position = "absolute";
+    // Viewport space: position:fixed + clientX/clientY keeps the tag at the
+    // pointer wherever it sits in the DOM. (The old position:absolute +
+    // zone-relative math only lined up when the tag was a child of the zone —
+    // a body-level tag landed near the document origin instead, off-screen.)
+    el.style.position = "fixed";
     el.style.left = "0";
     el.style.top = "0";
     el.style.pointerEvents = "none";
@@ -61,10 +69,19 @@ export function cursorFollower(
     const xTo = gsap.quickTo(el, "x", { ...spring, duration: 0.4, ease: "power3" });
     const yTo = gsap.quickTo(el, "y", { ...spring, duration: 0.4, ease: "power3" });
 
+    // First move lands on the pointer; later moves spring after it — starting
+    // from (0,0), the spring would otherwise carry the tag in from the corner.
+    let snapped = false;
     const onMove = (e: PointerEvent) => {
-      const r = area.getBoundingClientRect();
-      xTo(e.clientX - r.left + offset);
-      yTo(e.clientY - r.top + offset);
+      const x = e.clientX + offset;
+      const y = e.clientY + offset;
+      if (snapped) {
+        xTo(x);
+        yTo(y);
+      } else {
+        gsap.set(el, { x, y });
+        snapped = true;
+      }
       if (fade) gsap.to(el, { opacity: 1, duration: 0.25, overwrite: "auto" });
     };
 

package/src/effects/flip-words.ts

@@ -0,0 +1,148 @@
+/**
+ * Flip word transfer — words glide from one layout into another (FLIP).
+ *
+ * The source block holds the words; `to` is the block they land in. Both
+ * blocks should share one grid cell so the page never reflows when the
+ * words move:
+ *
+ *     .flip-stage     { display: grid; }
+ *     .flip-stage > div { grid-area: 1 / 1; }  // source + destination overlap
+ *
+ * On trigger every word is measured where it stands, moved into the
+ * destination, and animated from its old position (the classic FLIP
+ * technique), with a mid-flight squash so the words pop as they travel.
+ * Because the measurement happens up front, the words *look* like they are
+ * still in the source at scroll progress 0 even though they already live in
+ * the destination — so a scrubbed transfer reverses perfectly.
+ *
+ *   flipWords("[data-flip-from]", { to: "[data-flip-to]", scrub: 1 });
+ *
+ * destroy() kills the timeline, puts every word back in its original
+ * parent (in the original order) and restores its inline transform.
+ */
+import { gsap, Flip, ScrollTrigger, initGSAP, killTweens } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { one, toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface FlipWordsOptions extends CommonOptions {
+  /** Destination block — every word is moved into it. */
+  to: TargetLike;
+  /**
+   * The words inside the source.
+   * @default `[data-flip-word]` matches, else the source's element children
+   */
+  words?: TargetLike;
+  /** Seconds for one word's travel. @default 1.4 */
+  duration?: number;
+  /** GSAP ease. @default "power4.inOut" */
+  ease?: string;
+  /** Seconds between word starts. @default 0.2 */
+  stagger?: number;
+  /** Mid-flight scale a word squashes to (0 disables the squash). @default 0.2 */
+  scale?: number;
+  /** "scroll" plays on enter (reverses on leave-back), "immediate" plays now. @default "scroll" */
+  mode?: "scroll" | "immediate";
+  /**
+   * Bind the transfer to scroll progress instead of playing it on enter —
+   * number = scrub smoothing seconds, `true` = immediate. unset = one-shot.
+   */
+  scrub?: number | boolean;
+  /** ScrollTrigger start. @default "top 75%" */
+  start?: string;
+  /** ScrollTrigger end (scrub mode). @default "bottom 45%" */
+  end?: string;
+}
+
+export function flipWords(from: TargetLike, options: FlipWordsOptions): Destroy {
+  initGSAP();
+
+  const src = one<HTMLElement>(from);
+  const dest = one<HTMLElement>(options?.to);
+  if (!src || !dest) return () => {};
+
+  const {
+    words,
+    duration = 1.4,
+    ease = "power4.inOut",
+    stagger = 0.2,
+    scale = 0.2,
+    mode = "scroll",
+    scrub,
+    start = "top 75%",
+    end = "bottom 45%",
+  } = options;
+
+  const marked = toArray<HTMLElement>(src.querySelectorAll("[data-flip-word]"));
+  const wordEls = words
+    ? toArray<HTMLElement>(words, src)
+    : marked.length
+      ? marked
+      : [...src.children] as HTMLElement[];
+  if (!wordEls.length) return () => {};
+
+  return guard(options, () => {
+    // Remember each word's home so destroy() can put everything back in order.
+    const home = wordEls.map((w) => ({ parent: w.parentNode, next: w.nextSibling }));
+    const prevTransform = wordEls.map((w) => w.style.transform);
+
+    // Measure in the source, move into the destination, then animate from
+    // the measurement — the FLIP. The wrapper timeline owns the flight so
+    // ScrollTrigger can scrub it and the scale accents can share its clock.
+    const state = Flip.getState(wordEls);
+    wordEls.forEach((w) => dest.appendChild(w));
+
+    const tl = gsap.timeline({ paused: true });
+    // The wrapper is paused, and `add` is synchronous, so the Flip child
+    // never renders on the global timeline before the wrapper owns it.
+    tl.add(Flip.from(state, { duration, ease, stagger: { each: stagger } }), 0);
+
+    if (scale > 0) {
+      wordEls.forEach((w, i) => {
+        const at = i * stagger;
+        tl.to(w, { scale, duration: duration * 0.5, ease }, at);
+        tl.to(w, { scale: 1, duration: duration * 0.5, ease }, at + duration * 0.5);
+      });
+    }
+
+    let st: ScrollTrigger | undefined;
+    if (mode === "immediate") {
+      tl.play(0);
+    } else if (scrub !== undefined) {
+      st = ScrollTrigger.create({
+        trigger: src,
+        start,
+        end,
+        scrub: scrub === true ? true : scrub,
+        animation: tl,
+      });
+    } else {
+      st = ScrollTrigger.create({
+        trigger: src,
+        start,
+        animation: tl,
+        toggleActions: "play none none reverse",
+      });
+    }
+    ScrollTrigger.refresh();
+
+    return () => {
+      st?.kill();
+      tl.kill();
+      killTweens(wordEls);
+      // Reparent home. A stored `next` sibling that has moved with the words
+      // is not in the parent anymore — fall back to appending in order.
+      wordEls.forEach((w, i) => {
+        const h = home[i];
+        if (!h.parent) return;
+        const ref = h.next && h.next.parentNode === h.parent ? h.next : null;
+        h.parent.insertBefore(w, ref);
+      });
+      gsap.set(wordEls, { clearProps: "transform" });
+      wordEls.forEach((w, i) => {
+        w.style.transform = prevTransform[i];
+      });
+      ScrollTrigger.refresh();
+    };
+  });
+}

package/src/effects/magnetic.ts

@@ -0,0 +1,87 @@
+/**
+ * Magnetic hover — buttons and links that pull toward the pointer.
+ *
+ * While the pointer is over the element it follows the cursor (a fraction
+ * of its own box), tilts toward the pull, and optionally grows a touch.
+ * On leave it springs back to rest with an elastic snap:
+ *
+ *   magnetic("[data-magnet]", { strength: 0.5, rotation: 10 });
+ *
+ * Attach it to individual buttons/links (or a container's children — pass
+ * the list). destroy() removes the listeners, kills in-flight tweens and
+ * restores the inline transform.
+ */
+import { gsap, initGSAP, killTweens } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface MagneticOptions extends CommonOptions {
+  /** How far the element follows the pointer — fraction of its own box. @default 0.4 */
+  strength?: number;
+  /** Max tilt in degrees at full pull (0 disables rotation). @default 8 */
+  rotation?: number;
+  /** Scale held while the pointer is over the element (1 = none). @default 1 */
+  scale?: number;
+  /** Spring-back duration, seconds. @default 1.2 */
+  duration?: number;
+  /** Spring-back ease. @default "elastic.out(1, 0.35)" */
+  ease?: string;
+}
+
+export function magnetic(target: TargetLike, options: MagneticOptions = {}): Destroy {
+  initGSAP();
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  const {
+    strength = 0.4,
+    rotation = 8,
+    scale = 1,
+    duration = 1.2,
+    ease = "elastic.out(1, 0.35)",
+  } = options;
+
+  return guard(options, () => {
+    const prevTransform = els.map((el) => el.style.transform);
+    const listeners: Array<{ el: HTMLElement; type: string; fn: EventListener }> = [];
+
+    els.forEach((el) => {
+      const onMove = (e: Event) => {
+        const ptr = e as PointerEvent;
+        const r = el.getBoundingClientRect();
+        const dx = ptr.clientX - (r.left + r.width / 2);
+        const dy = ptr.clientY - (r.top + r.height / 2);
+        const nx = r.width ? dx / (r.width / 2) : 0; // -1 … 1 across the box
+        gsap.to(el, {
+          x: dx * strength,
+          y: dy * strength,
+          rotation: rotation ? nx * rotation : 0,
+          scale,
+          duration: 0.4,
+          ease: "power3.out",
+          overwrite: "auto",
+        });
+      };
+      const onLeave = () => {
+        gsap.to(el, { x: 0, y: 0, rotation: 0, scale: 1, duration, ease, overwrite: "auto" });
+      };
+
+      el.addEventListener("pointermove", onMove);
+      el.addEventListener("pointerleave", onLeave);
+      listeners.push(
+        { el, type: "pointermove", fn: onMove },
+        { el, type: "pointerleave", fn: onLeave },
+      );
+    });
+
+    return () => {
+      listeners.forEach(({ el, type, fn }) => el.removeEventListener(type, fn));
+      killTweens(els);
+      els.forEach((el, i) => {
+        el.style.transform = prevTransform[i];
+      });
+    };
+  });
+}

package/src/effects/media-settle.ts

@@ -7,6 +7,7 @@
  *
  *   mediaSettle("[data-settle]", { from: 1.3 });            // on enter
  *   mediaSettle("[data-settle]", { scrub: 0.5 });           // scroll-bound
+ *   mediaSettle("[data-settle]", { replay: true });         // reverse on leave-back, replay on re-enter
  *
  * destroy() kills the tween and restores the original scale.
  */
@@ -34,6 +35,8 @@ export interface MediaSettleOptions extends CommonOptions {
   start?: string;
   /** ScrollTrigger end position (scrub mode). @default "bottom top" */
   end?: string;
+  /** Re-settle when leaving / re-entering the viewport (enter mode). @default false */
+  replay?: boolean;
   /**
    * Bind the settle to scroll progress instead of playing it on enter —
    * number = scrub smoothing seconds, `true` = immediate. unset = one-shot.
@@ -54,6 +57,7 @@ export function mediaSettle(target: TargetLike, options: MediaSettleOptions = {}
     mode = "scroll",
     start = "top 75%",
     end = "bottom top",
+    replay = false,
     scrub,
   } = options;
 
@@ -79,7 +83,9 @@ export function mediaSettle(target: TargetLike, options: MediaSettleOptions = {}
       vars.duration = duration;
       vars.ease = ease;
       if (mode === "scroll") {
-        vars.scrollTrigger = { trigger: els[0], start, once: true };
+        vars.scrollTrigger = replay
+          ? { trigger: els[0], start, toggleActions: "play reverse play reverse" }
+          : { trigger: els[0], start, once: true };
       }
     }
 

package/src/index.ts

@@ -28,11 +28,13 @@
  *
  * Text extras:
  *   scrambleText()   decode / cipher reveal per character
+ *   flipWords()      words that glide between two layouts (FLIP)
  *
  * Micro-interactions:
  *   liquidButton()   SVG wave flood on hover
  *   underlineLink()  underline wipe on hover
  *   cursorFollower() spring-follow cursor tag
+ *   magnetic()       elements that pull toward the pointer and spring back
  *   counter()        tabular number ticker (timed or scroll-progress)
  *   audioBars()      equaliser visualiser
  *   themeReveal()    View Transitions circular wipe
@@ -61,7 +63,7 @@ export { unfoldReveal } from "./effects/unfold-reveal.js";
 export type { UnfoldRevealOptions } from "./effects/unfold-reveal.js";
 
 export { clipWipe } from "./effects/clip-wipe.js";
-export type { ClipWipeOptions } from "./effects/clip-wipe.js";
+export type { ClipWipeOptions, ClipWipeFrom } from "./effects/clip-wipe.js";
 
 export { parallax } from "./effects/parallax.js";
 export type { ParallaxOptions } from "./effects/parallax.js";
@@ -101,6 +103,9 @@ export type { DragStripOptions } from "./effects/drag-strip.js";
 export { scrambleText } from "./effects/scramble-text.js";
 export type { ScrambleTextOptions } from "./effects/scramble-text.js";
 
+export { flipWords } from "./effects/flip-words.js";
+export type { FlipWordsOptions } from "./effects/flip-words.js";
+
 /* ---- micro-interactions ---- */
 export { liquidButton, underlineLink } from "./effects/liquid-button.js";
 export type { LiquidButtonOptions } from "./effects/liquid-button.js";
@@ -108,6 +113,9 @@ export type { LiquidButtonOptions } from "./effects/liquid-button.js";
 export { cursorFollower } from "./effects/cursor-follower.js";
 export type { CursorFollowerOptions } from "./effects/cursor-follower.js";
 
+export { magnetic } from "./effects/magnetic.js";
+export type { MagneticOptions } from "./effects/magnetic.js";
+
 export { counter, audioBars } from "./effects/counter.js";
 export type { CounterOptions, AudioBarsOptions, AudioBarsHandle } from "./effects/counter.js";