@cosmictraveler002/anim-kit 1.1.0 → 1.3.0

package/dist/three/webgl-media.d.ts

@@ -0,0 +1,21 @@
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+export interface WebglMediaOptions extends CommonOptions {
+    /** Image source — defaults to the wrapper's first `<img>`. */
+    src?: string;
+    /** Corner radius, px. @default 16 */
+    corner?: number;
+    /** Dent depth pressed into the card on hover, px. @default 70 */
+    dent?: number;
+    /** Chromatic split at full hover, px. @default 2 */
+    chroma?: number;
+    /** Wipe the card in when its texture loads. @default true */
+    reveal?: boolean;
+    /** Reveal duration, seconds. @default 1.1 */
+    revealDuration?: number;
+    /** Hover response duration, seconds. @default 0.6 */
+    hoverDuration?: number;
+    /** Device-pixel-ratio cap. @default 2 */
+    dpr?: number;
+}
+export declare function webglMedia(target: TargetLike, options?: WebglMediaOptions): Destroy;
+//# sourceMappingURL=webgl-media.d.ts.map

package/dist/three/webgl-media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl-media.d.ts","sourceRoot":"","sources":["../../src/three/webgl-media.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE3E,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAyED,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAiMvF"}

package/dist/three/webgl-media.js

@@ -0,0 +1,268 @@
+/**
+ * WebGL media — the shader card: a DOM `<img>` re-rendered as a rounded,
+ * hover-reactive GL plane.
+ *
+ * The image keeps owning layout and alt text; the effect paints it onto a
+ * canvas that covers the wrapper, so the card can do what CSS can't: press a
+ * *dent* into the picture on hover (sample squeeze + fake dome lighting),
+ * split its channels (chroma), and wipe in on reveal — all inside one
+ * fragment shader. This is the media-card pattern from three.js portfolios,
+ * kept dependency-honest:
+ *
+ * - **Optional peer.** Lives behind the `@cosmictraveler002/anim-kit/three`
+ *   subpath; the core barrel stays gsap+lenis only. `three` is an optional
+ *   peer — install it to use this entry, the core never imports it.
+ * - **Silent no-op ladder.** Missing target → no-op. No
+ *   `WebGLRenderingContext` (jsdom, SSR, WebGL-disabled browsers) → no-op
+ *   *before* a context is ever requested (a probe call would itself log).
+ *   Renderer construction throws → no-op. Texture 404s → the plain `<img>`
+ *   stays visible. Under `prefers-reduced-motion` the canvas never mounts.
+ * - **Cover crop in-shader.** The texture is sampled with `object-fit: cover`
+ *   maths (`scale = uRes / uTexSize`, windowed around the centre), so any
+ *   source aspect fills the card without letterboxing.
+ * - **Rounded corners are shader-true.** A rounded-box SDF with a 1px smooth
+ *   edge — not `border-radius` on the canvas — so the dent/chroma never bleed
+ *   into the corner.
+ * - **Fidelity.** `destroy()` kills ticker + tweens + observers/listeners,
+ *   disposes geometry/material/texture/renderer, removes the canvas and
+ *   restores the `<img>` opacity and wrapper position it changed.
+ *
+ *   webglMedia("[data-gl]", { corner: 18, dent: 70, chroma: 2 })
+ *
+ * Markup: a wrapper element containing `<img>` (or pass `src` explicitly):
+ *
+ *   <figure class="gl-card" data-gl><img src="photo.jpg" alt="" /></figure>
+ */
+import * as THREE from "three";
+import { gsap, initGSAP } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { one } from "../core/util.js";
+const VERT = /* glsl */ `
+varying vec2 vUv;
+uniform float uHover;
+uniform float uDent;
+uniform float uTime;
+
+void main() {
+  vUv = uv;
+  vec3 p = position;
+  float dome = max(cos(uv.x * 3.14159265) * cos(uv.y * 3.14159265), 0.0);
+  dome *= 0.94 + 0.06 * sin(uTime * 1.6);
+  // Pressed-in curvature while hovered — the fragment does the visible work.
+  p.z -= uHover * uDent * dome;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
+}
+`;
+const FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D uTex;
+uniform vec2 uRes;
+uniform vec2 uTexSize;
+uniform float uCorner;
+uniform float uHover;
+uniform float uDent;
+uniform float uChroma;
+uniform float uProgress;
+uniform float uTime;
+
+float sdRoundBox(vec2 p, vec2 b, float r) {
+  vec2 q = abs(p) - b + r;
+  return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - r;
+}
+
+void main() {
+  vec2 px = (vUv - 0.5) * uRes;
+  float d = sdRoundBox(px, uRes * 0.5, uCorner);
+  float alpha = 1.0 - smoothstep(-1.0, 1.0, d); // 1px-ish AA on the corner
+
+  // Entrance wipe: grows from the bottom with a soft leading edge.
+  if (uProgress < 1.0) {
+    alpha *= 1.0 - smoothstep(uProgress - 0.05, uProgress, vUv.y);
+  }
+  if (alpha < 0.003) discard;
+
+  // object-fit: cover — window the texture around its centre.
+  vec2 scale = uRes / max(uTexSize, vec2(1.0));
+  vec2 cover = (vUv - 0.5) * (scale / max(scale.x, scale.y)) + 0.5;
+
+  // Hover dent: squeeze the sample toward the centre (breathing slightly).
+  vec2 c = cover - 0.5;
+  float dome = max(cos(vUv.x * 3.14159265) * cos(vUv.y * 3.14159265), 0.0);
+  dome *= 0.94 + 0.06 * sin(uTime * 1.6);
+  vec2 suv = 0.5 + c * (1.0 - uHover * uDent * 0.0016 * dome);
+
+  float chroma = uChroma * uHover * dome / max(uRes.x, 1.0);
+  vec3 col;
+  col.r = texture2D(uTex, suv + vec2(chroma, 0.0)).r;
+  col.g = texture2D(uTex, suv).g;
+  col.b = texture2D(uTex, suv - vec2(chroma, 0.0)).b;
+
+  // Fake lighting off the dome slope: sheen at the crest, shade at the rim.
+  float light = dome * uHover;
+  col += light * 0.12;
+  col *= 1.0 - 0.12 * uHover * (1.0 - dome);
+
+  gl_FragColor = vec4(col, alpha);
+}
+`;
+export function webglMedia(target, options = {}) {
+    initGSAP();
+    const host = one(target);
+    if (!host)
+        return () => { };
+    const { src, corner = 16, dent = 70, chroma = 2, reveal = true, revealDuration = 1.1, hoverDuration = 0.6, dpr = 2, } = options;
+    return guard(options, () => {
+        /* ---------------- availability ladder (silent, no probes) ---------------- */
+        if (typeof window === "undefined" || !("WebGLRenderingContext" in window))
+            return () => { };
+        let renderer;
+        try {
+            renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
+        }
+        catch {
+            return () => { }; // context refused (disabled/blacklisted) — plain img stays
+        }
+        const img = host.tagName === "IMG" ? null : host.querySelector("img");
+        const textureSrc = src || img?.currentSrc || img?.src;
+        if (!textureSrc) {
+            renderer.dispose();
+            return () => { };
+        }
+        /* ---------------- layout + styles we must restore ---------------- */
+        const prevPosition = host.style.position;
+        if (!prevPosition && getComputedStyle(host).position === "static") {
+            host.style.position = "relative";
+        }
+        const prevImgOpacity = img?.style.opacity ?? "";
+        host.dataset.akGl = "true";
+        const w = Math.max(1, host.clientWidth);
+        const h = Math.max(1, host.clientHeight);
+        renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, dpr));
+        renderer.setSize(w, h, false);
+        const canvas = renderer.domElement;
+        canvas.style.cssText =
+            "position:absolute;inset:0;width:100%;height:100%;display:block;pointer-events:none;";
+        const scene = new THREE.Scene();
+        const camera = new THREE.OrthographicCamera(-w / 2, w / 2, h / 2, -h / 2, -100, 100);
+        camera.position.z = 10;
+        const geometry = new THREE.PlaneGeometry(1, 1, 1, 1);
+        const uniforms = {
+            uTex: { value: null },
+            uRes: { value: new THREE.Vector2(w, h) },
+            uTexSize: { value: new THREE.Vector2(1, 1) },
+            uCorner: { value: corner },
+            uHover: { value: 0 },
+            uDent: { value: dent },
+            uChroma: { value: chroma },
+            uProgress: { value: reveal ? 0 : 1 },
+            uTime: { value: 0 },
+        };
+        const material = new THREE.ShaderMaterial({
+            vertexShader: VERT,
+            fragmentShader: FRAG,
+            uniforms,
+            transparent: true,
+        });
+        const mesh = new THREE.Mesh(geometry, material);
+        mesh.scale.set(w, h, 1);
+        mesh.visible = false;
+        scene.add(mesh);
+        host.appendChild(canvas);
+        /* ---------------- texture ---------------- */
+        let disposed = false;
+        const loader = new THREE.TextureLoader();
+        let revealTween = null;
+        loader.load(textureSrc, (texture) => {
+            if (disposed) {
+                texture.dispose();
+                return;
+            }
+            texture.minFilter = THREE.LinearFilter;
+            texture.magFilter = THREE.LinearFilter;
+            // No sRGB decode: the raw shader passes sampled values through, so the
+            // texture must stay an ordinary RGBA8 upload (built-in colorSpace
+            // conversion only happens inside three's own material chunks).
+            uniforms.uTex.value = texture;
+            uniforms.uTexSize.value.set(texture.image.width || 1, texture.image.height || 1);
+            mesh.visible = true;
+            if (img)
+                img.style.opacity = "0"; // canvas owns the pixels from here
+            if (reveal) {
+                revealTween = gsap.fromTo(uniforms.uProgress, { value: 0 }, { value: 1, duration: revealDuration, ease: "power2.inOut" });
+            }
+        }, undefined, () => {
+            /* 404 / decode failure — the plain <img> was never hidden. */
+        });
+        /* ---------------- hover ---------------- */
+        let hoverTween = null;
+        const hoverTo = (value) => {
+            hoverTween = gsap.to(uniforms.uHover, {
+                value,
+                duration: hoverDuration,
+                ease: "power3.out",
+                overwrite: "auto",
+            });
+        };
+        const onEnter = () => hoverTo(1);
+        const onLeave = () => hoverTo(0);
+        host.addEventListener("pointerenter", onEnter);
+        host.addEventListener("pointerleave", onLeave);
+        /* ---------------- loop / observers ---------------- */
+        let visible = true;
+        let io = null;
+        if (typeof IntersectionObserver === "function") {
+            io = new IntersectionObserver(([entry]) => (visible = entry.isIntersecting), {
+                rootMargin: "120px",
+            });
+            io.observe(host);
+        }
+        let ro = null;
+        const resize = () => {
+            const rw = Math.max(1, host.clientWidth);
+            const rh = Math.max(1, host.clientHeight);
+            renderer.setSize(rw, rh, false);
+            camera.left = -rw / 2;
+            camera.right = rw / 2;
+            camera.top = rh / 2;
+            camera.bottom = -rh / 2;
+            camera.updateProjectionMatrix();
+            mesh.scale.set(rw, rh, 1);
+            uniforms.uRes.value.set(rw, rh);
+        };
+        if (typeof ResizeObserver === "function") {
+            ro = new ResizeObserver(resize);
+            ro.observe(host);
+        }
+        const render = () => {
+            if (!visible || !mesh.visible)
+                return;
+            uniforms.uTime.value = gsap.ticker.time;
+            renderer.render(scene, camera);
+        };
+        gsap.ticker.add(render);
+        /* ---------------- teardown ---------------- */
+        return () => {
+            disposed = true;
+            gsap.ticker.remove(render);
+            hoverTween?.kill();
+            revealTween?.kill();
+            gsap.killTweensOf(uniforms.uHover);
+            gsap.killTweensOf(uniforms.uProgress);
+            host.removeEventListener("pointerenter", onEnter);
+            host.removeEventListener("pointerleave", onLeave);
+            io?.disconnect();
+            ro?.disconnect();
+            uniforms.uTex.value?.dispose();
+            geometry.dispose();
+            material.dispose();
+            renderer.dispose();
+            canvas.remove();
+            delete host.dataset.akGl;
+            host.style.position = prevPosition;
+            if (img)
+                img.style.opacity = prevImgOpacity;
+        };
+    });
+}
+//# sourceMappingURL=webgl-media.js.map

package/dist/three/webgl-media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl-media.js","sourceRoot":"","sources":["../../src/three/webgl-media.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmictraveler002/anim-kit",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Modular, framework-agnostic animation library — GSAP + ScrollTrigger + Lenis effects packaged as composable ES modules.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,11 @@
       "import": "./dist/anim-kit.standalone.js",
       "default": "./dist/anim-kit.standalone.js"
     },
+    "./three": {
+      "types": "./dist/three/index.d.ts",
+      "import": "./dist/three/index.js",
+      "default": "./dist/three/index.js"
+    },
     "./effects/*": {
       "types": "./dist/effects/*.d.ts",
       "import": "./dist/effects/*.js",
@@ -42,6 +47,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch",
     "demo": "node scripts/serve.mjs",
+    "sync:live": "node scripts/sync-demo-live.mjs",
     "test": "npm run build && node scripts/smoke.mjs && node scripts/demo-smoke.mjs",
     "smoke": "node scripts/smoke.mjs && node scripts/demo-smoke.mjs",
     "prepublishOnly": "npm run build && npm run smoke"
@@ -75,8 +81,18 @@
     "gsap": "^3.13.0",
     "lenis": "^1.3.11"
   },
+  "peerDependencies": {
+    "three": ">=0.160.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/three": "^0.186.0",
     "jsdom": "^25.0.1",
+    "three": "^0.186.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3"
   }

package/src/core/gsap.ts

@@ -10,12 +10,13 @@ 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. */
+/** Named eases from kalakritico.in's bundles. */
 export const EASES = {
   /** `.76,0,.2,1` — the studio's signature menu / nav curtain ease. */
   curtain: "ak-curtain",
@@ -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/core/smooth-scroll.ts

@@ -10,7 +10,7 @@
  * clocks on the same frame, which is what stops ScrollTrigger from stuttering.
  *
  * `useScrollerProxy: true` additionally proxies `document.documentElement`,
- * matching dzinrstudio.com's setup — only needed if you scroll a nested
+ * matching kalakritico.in's setup — only needed if you scroll a nested
  * element instead of the window.
  */
 import Lenis from "lenis";

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" });
     };