@cosmictraveler002/anim-kit 1.0.0

package/dist/styles/anim-kit.css

@@ -0,0 +1,361 @@
+/**
+ * anim-kit — companion stylesheet.
+ *
+ * Most of the studio's motion is JS-driven, but a handful of effects are pure
+ * CSS (liquid button, underline sweep, marquee masks) and every effect needs a
+ * resting state that is safe with `prefers-reduced-motion`.
+ */
+
+/* ------------------------------------------------------------------ */
+/* Design tokens                                                       */
+/* ------------------------------------------------------------------ */
+
+:root {
+  --ak-primary: #6c5ce7;
+  --ak-curtain: cubic-bezier(0.76, 0, 0.24, 1);
+  --ak-reveal: cubic-bezier(0.165, 0.84, 0.44, 1);
+  --ak-out: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* ------------------------------------------------------------------ */
+/* Text splitting — masks                                              */
+/* ------------------------------------------------------------------ */
+
+/* SplitText / split() output: one mask per line so lines can slide up. */
+.ak-line,
+.ak-line-mask {
+  overflow: hidden;
+  display: block;
+  /* Negate the descender clipping every masked-line setup has to fight. */
+  padding-bottom: 0.12em;
+  margin-bottom: -0.12em;
+}
+
+.ak-line > *,
+.ak-line-mask > * {
+  display: block;
+  will-change: transform;
+}
+
+.ak-char,
+.ak-word {
+  display: inline-block;
+  will-change: transform;
+}
+
+.ak-space {
+  display: inline-block;
+  white-space: pre;
+}
+
+/* ------------------------------------------------------------------ */
+/* Mask reveal (heading lines)                                         */
+/* ------------------------------------------------------------------ */
+
+.ak-mask {
+  display: block;
+  overflow: hidden;
+}
+
+.ak-mask__inner {
+  display: block;
+  will-change: transform;
+}
+
+/* ------------------------------------------------------------------ */
+/* Liquid button                                                       */
+/* ------------------------------------------------------------------ */
+
+.ak-liquid {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  isolation: isolate;
+  padding: 0.4em 1em;
+  border: 0;
+  background: var(--ak-foreground, #111);
+  color: var(--ak-background, #fff);
+  cursor: pointer;
+  transition: color 700ms ease-out;
+}
+
+.ak-liquid__wave {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  height: 160%;
+  width: 160%;
+  pointer-events: none;
+  transform: translate(-50%, 120%);
+  transition-property: transform;
+  transition-timing-function: ease-out;
+  transition-duration: var(--ak-liquid-duration, 900ms);
+}
+
+/* Rising from the bottom → the curved edge peaks on the way up. */
+[data-ak-liquid="up"] .ak-liquid__wave {
+  transform: translate(-50%, 120%);
+}
+[data-ak-liquid="up"]:hover .ak-liquid__wave,
+[data-ak-liquid="up"]:focus-visible .ak-liquid__wave {
+  transform: translate(-50%, -66.666%);
+}
+
+/* Falling in from the top. */
+[data-ak-liquid="down"] .ak-liquid__wave {
+  transform: translate(-50%, -120%);
+}
+[data-ak-liquid="down"]:hover .ak-liquid__wave,
+[data-ak-liquid="down"]:focus-visible .ak-liquid__wave {
+  transform: translate(-50%, -66.666%);
+}
+
+.ak-liquid__wave path {
+  fill: var(--ak-liquid-fill, var(--ak-primary));
+}
+
+.ak-liquid:hover,
+.ak-liquid:focus-visible {
+  color: var(--ak-liquid-label, #fff);
+}
+
+.ak-liquid__label {
+  position: relative;
+  z-index: 10;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5em;
+  white-space: nowrap;
+}
+
+/* ------------------------------------------------------------------ */
+/* Underline sweep                                                     */
+/* ------------------------------------------------------------------ */
+
+.ak-underline {
+  position: relative;
+  display: inline-block;
+  cursor: pointer;
+}
+
+.ak-underline::after {
+  content: "";
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  height: 1px;
+  width: 0;
+  background: currentColor;
+  transition: width 300ms var(--ak-out);
+}
+
+.ak-underline:hover::after,
+.ak-underline:focus-visible::after {
+  width: 100%;
+}
+
+/* ------------------------------------------------------------------ */
+/* Marquee                                                             */
+/* ------------------------------------------------------------------ */
+
+.ak-marquee {
+  position: relative;
+  overflow: hidden;
+  width: 100%;
+}
+
+.ak-marquee__viewport {
+  overflow: hidden;
+}
+
+.ak-marquee__track {
+  display: flex;
+  width: max-content;
+  will-change: transform;
+  backface-visibility: hidden;
+}
+
+/* Fade the first/last 10vw into the page background. */
+.ak-marquee::before,
+.ak-marquee::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 10vw;
+  z-index: 2;
+  pointer-events: none;
+}
+.ak-marquee::before {
+  left: 0;
+  background: linear-gradient(to right, var(--ak-background, #fff) 0%, transparent 100%);
+}
+.ak-marquee::after {
+  right: 0;
+  background: linear-gradient(to left, var(--ak-background, #fff) 0%, transparent 100%);
+}
+
+/* ------------------------------------------------------------------ */
+/* Drag strip                                                          */
+/* ------------------------------------------------------------------ */
+
+.ak-drag-track {
+  display: flex;
+  gap: 1rem;
+  width: max-content;
+  cursor: grab;
+  user-select: none;
+  touch-action: pan-y;
+  will-change: transform;
+}
+.ak-drag-track:active {
+  cursor: grabbing;
+}
+.ak-drag-track > * {
+  transform-origin: 50% 100%;
+  will-change: transform;
+}
+
+/* ------------------------------------------------------------------ */
+/* Menu overlay                                                        */
+/* ------------------------------------------------------------------ */
+
+.menu-overlay {
+  position: fixed;
+  inset: 0;
+  width: 100vw;
+  height: 100svh;
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  background: var(--ak-primary);
+  z-index: 9999;
+  pointer-events: none;
+  will-change: clip-path;
+  /* Matches the collapsed-at-bottom resting state JS sets first. */
+  clip-path: polygon(0 100%, 100% 100%, 100% 100%, 0 100%);
+}
+
+.menu-overlay-bar {
+  position: fixed;
+  top: 0;
+  left: 0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100vw;
+  padding: 20px;
+}
+
+.menu-link {
+  overflow: hidden;
+  padding-left: 20px;
+}
+
+.menu-overlay .menu-link h1,
+.menu-overlay .menu-link a {
+  display: block;
+  text-transform: uppercase;
+  font-size: 5vw;
+  font-weight: 400;
+  line-height: 0.9;
+  will-change: transform;
+}
+
+@media (max-width: 767px) {
+  .menu-overlay .menu-link h1,
+  .menu-overlay .menu-link a {
+    font-size: 16vw;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Stacked cards                                                       */
+/* ------------------------------------------------------------------ */
+
+.ak-stack-viewport {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+}
+
+.ak-stack-cards {
+  display: flex;
+  gap: 1rem;
+  height: 100vh;
+  width: 100%;
+  align-items: center;
+  justify-content: center;
+}
+
+.ak-card {
+  will-change: transform;
+}
+
+/* ------------------------------------------------------------------ */
+/* Counter                                                             */
+/* ------------------------------------------------------------------ */
+
+.ak-counter {
+  font-variant-numeric: tabular-nums;
+  font-feature-settings: "tnum" 1;
+}
+
+/* ------------------------------------------------------------------ */
+/* Equaliser                                                           */
+/* ------------------------------------------------------------------ */
+
+.ak-eq {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  height: 18px;
+  width: 100%;
+}
+
+.ak-eq > * {
+  width: 1px;
+  height: 4px;
+  border-radius: 999px;
+  background: currentColor;
+}
+
+/* ------------------------------------------------------------------ */
+/* Reduced motion — show final states, never animate                   */
+/* ------------------------------------------------------------------ */
+
+@media (prefers-reduced-motion: reduce) {
+  .ak-line,
+  .ak-line-mask,
+  .ak-mask {
+    overflow: visible;
+  }
+
+  .ak-liquid__wave,
+  .ak-underline::after,
+  .ak-marquee__track,
+  .ak-drag-track,
+  .ak-card,
+  .menu-overlay {
+    transition: none !important;
+    animation: none !important;
+  }
+
+  .ak-liquid__wave {
+    transform: translate(-50%, 120%) !important;
+  }
+
+  [data-ak-liquid]:hover .ak-liquid__wave {
+    transform: translate(-50%, -66.666%) !important;
+  }
+
+  .menu-overlay {
+    display: none;
+  }
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@cosmictraveler002/anim-kit",
+  "version": "1.0.0",
+  "description": "Modular, framework-agnostic animation library inspired by dzinrstudio.com — GSAP + ScrollTrigger + Lenis effects packaged as composable ES modules.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./standalone": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/anim-kit.standalone.js",
+      "default": "./dist/anim-kit.standalone.js"
+    },
+    "./effects/*": {
+      "types": "./dist/effects/*.d.ts",
+      "import": "./dist/effects/*.js",
+      "default": "./dist/effects/*.js"
+    },
+    "./effects/*.js": {
+      "types": "./dist/effects/*.d.ts",
+      "import": "./dist/effects/*.js",
+      "default": "./dist/effects/*.js"
+    },
+    "./styles": "./dist/styles/anim-kit.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs && tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "demo": "node scripts/serve.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"
+  },
+  "keywords": [
+    "animation",
+    "gsap",
+    "scrolltrigger",
+    "lenis",
+    "smooth-scroll",
+    "marquee",
+    "parallax",
+    "preloader"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cosmictraveler002/Ani-Kit.git"
+  },
+  "homepage": "https://github.com/Cosmictraveler002/Ani-Kit#readme",
+  "bugs": {
+    "url": "https://github.com/Cosmictraveler002/Ani-Kit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gsap": "^3.13.0",
+    "lenis": "^1.3.11"
+  },
+  "devDependencies": {
+    "jsdom": "^30.1.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.3"
+  }
+}

package/src/core/gsap.ts

@@ -0,0 +1,79 @@
+/**
+ * Central GSAP bootstrap: registers every plugin anim-kit touches, and the
+ * custom eases that give the DZ!NR feel.
+ *
+ * Importing this module twice is safe — registration is idempotent.
+ */
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { SplitText } from "gsap/SplitText";
+import { Draggable } from "gsap/Draggable";
+import { CustomEase } from "gsap/CustomEase";
+import { ScrollSmoother } from "gsap/ScrollSmoother";
+import { toArray } from "./util.js";
+import type { TargetLike } from "./types.js";
+
+export { gsap, ScrollTrigger, SplitText, Draggable, CustomEase, ScrollSmoother };
+
+/** Named eases recovered from dzinrstudio.com's bundles. */
+export const EASES = {
+  /** `.76,0,.2,1` — the studio's signature menu / nav curtain ease. */
+  curtain: "ak-curtain",
+  /** SVG path used for the stacked service-card cascade. */
+  cardStack: "ak-card-stack",
+  /** `.165,.84,.44,1` — their headline mask reveal. */
+  reveal: "ak-reveal",
+  /** `.895,.03,.685,.22` — preloader logo scale-out. */
+  preloadOut: "ak-preload-out",
+} as const;
+
+let initted = false;
+
+/** Register all plugins + custom eases exactly once. */
+export function initGSAP(): void {
+  if (initted || typeof window === "undefined") return;
+  initted = true;
+
+  gsap.registerPlugin(ScrollTrigger, SplitText, Draggable, CustomEase);
+
+  // ScrollSmoother is a bonus for people who prefer it over Lenis; it is only
+  // registered so `ScrollSmoother.create()` works if you call it yourself.
+  try {
+    gsap.registerPlugin(ScrollSmoother);
+  } catch {
+    /* not fatal — smoother is optional */
+  }
+
+  if (!CustomEase.get(EASES.curtain)) {
+    CustomEase.create(EASES.curtain, ".76,0,.2,1");
+    CustomEase.create(EASES.cardStack, "M0,0 C0,0 0.098,0.613 0.5,0.5 0.899,0.386 1,1 1,1");
+    CustomEase.create(EASES.reveal, ".165,.84,.44,1");
+    CustomEase.create(EASES.preloadOut, ".895,.03,.685,.22");
+  }
+
+  // Keep ScrollTrigger honest when images/fonts land late.
+  ScrollTrigger.config({ ignoreMobileResize: true });
+}
+
+initGSAP();
+
+/**
+ * Kill every tween that animates `target`.
+ *
+ * Deliberately **not** `gsap.killTweensOf()`. That forwards to
+ * `tween.kill(targets, …)`, which walks each tween's *initialised*
+ * prop-tween lookup — but a tween created between ticker frames is still
+ * lazy (`_initted === false`), its lookup is empty, and the kill silently
+ * no-ops. Such a tween then fires *after* teardown (e.g. an equaliser batch
+ * rewriting `height` post-destroy). The no-arg `tween.kill()` takes the
+ * full-kill path and removes both initialised and lazy tweens from the
+ * timeline.
+ *
+ * Internal helper — effects import it from `core/gsap.js`; it is not part of
+ * the public barrel.
+ */
+export function killTweens(target: TargetLike | Array<Element | null | undefined>): void {
+  const raw: Array<Element | null | undefined> = Array.isArray(target) ? target : toArray(target);
+  const list = raw.filter((el): el is Element => el instanceof Element);
+  gsap.getTweensOf(list).forEach((t) => t.kill());
+}

package/src/core/guard.ts

@@ -0,0 +1,18 @@
+/**
+ * Reduced-motion helper.
+ *
+ * Every effect calls `guard(options, run)`.
+ *  - normal motion  -> runs `run()` and returns its destroy fn
+ *  - reduced motion -> returns a no-op so nothing animates. Effects that need
+ *                      content visible in both states should render the final
+ *                      state in CSS (see styles/anim-kit.css).
+ */
+import { initGSAP } from "./gsap.js";
+import { prefersReducedMotion } from "./util.js";
+import type { CommonOptions, Destroy } from "./types.js";
+
+export function guard(options: CommonOptions, run: () => Destroy): Destroy {
+  initGSAP();
+  if (prefersReducedMotion() && !options.force) return () => {};
+  return run();
+}

package/src/core/smooth-scroll.ts

@@ -0,0 +1,143 @@
+/**
+ * Lenis smooth scrolling wired into GSAP ScrollTrigger.
+ *
+ * Uses the canonical Lenis + GSAP recipe:
+ *   lenis.on("scroll", ScrollTrigger.update)
+ *   gsap.ticker.add(t => lenis.raf(t * 1000))
+ *   gsap.ticker.lagSmoothing(0)
+ *
+ * Driving Lenis from GSAP's ticker (rather than its own rAF) keeps both
+ * 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
+ * element instead of the window.
+ */
+import Lenis from "lenis";
+import { gsap, ScrollTrigger, initGSAP } from "./gsap.js";
+import { prefersReducedMotion } from "./util.js";
+import type { CommonOptions, Destroy } from "./types.js";
+
+export interface SmoothScrollOptions extends CommonOptions {
+  /** Interpolation factor — lower = floatier. @default 0.08 */
+  lerp?: number;
+  /** Smooth mouse-wheel input. @default true */
+  smoothWheel?: boolean;
+  /** Smooth touch input (can fight native scrolling). @default false */
+  smoothTouch?: boolean;
+  /** Direction to smooth. @default "vertical" */
+  orientation?: "vertical" | "horizontal";
+  /** Initial scroll position in px. @default 0 */
+  initialScroll?: number;
+  /** Proxy documentElement through ScrollTrigger (nested scrollers). @default false */
+  useScrollerProxy?: boolean;
+}
+
+export interface SmoothScrollHandle {
+  /** The Lenis instance, or null when smooth scrolling was skipped. */
+  lenis: Lenis | null;
+  /** Programmatic scroll that respects the smooth scroller. */
+  scrollTo: (target: number | string | HTMLElement, opts?: { duration?: number; immediate?: boolean }) => void;
+  /** True when Lenis is actually driving the page. */
+  active: boolean;
+  destroy: Destroy;
+}
+
+const INERT: SmoothScrollHandle = {
+  lenis: null,
+  scrollTo: () => {},
+  active: false,
+  destroy: () => {},
+};
+
+export function smoothScroll(options: SmoothScrollOptions = {}): SmoothScrollHandle {
+  initGSAP();
+
+  const {
+    force = false,
+    lerp = 0.08,
+    smoothWheel = true,
+    smoothTouch = false,
+    orientation = "vertical",
+    initialScroll = 0,
+    useScrollerProxy = false,
+  } = options;
+
+  if (typeof window === "undefined") return INERT;
+
+  // Honour the OS-level preference: fall back to native scrolling.
+  if (prefersReducedMotion() && !force) return INERT;
+
+  const lenis = new Lenis({
+    lerp,
+    smoothWheel,
+    syncTouch: smoothTouch,
+    orientation,
+    autoRaf: false,
+  });
+
+  if (initialScroll) lenis.scrollTo(initialScroll, { immediate: true });
+
+  // 1. Let ScrollTrigger know whenever Lenis moves.
+  const onScroll = () => ScrollTrigger.update();
+  lenis.on("scroll", onScroll);
+
+  // 2. Run Lenis off GSAP's ticker so both share one frame clock.
+  const tick = (time: number) => lenis.raf(time * 1000);
+  gsap.ticker.add(tick);
+  gsap.ticker.lagSmoothing(0);
+
+  // 3. Optional: proxy the scroller (for nested/element scrollers).
+  if (useScrollerProxy) {
+    ScrollTrigger.scrollerProxy(document.documentElement, {
+      scrollTop(value?: number) {
+        if (arguments.length && typeof value === "number") {
+          lenis.scrollTo(value, { immediate: true });
+          return value;
+        }
+        return lenis.scroll;
+      },
+      getBoundingClientRect: () => ({
+        top: 0,
+        left: 0,
+        width: window.innerWidth,
+        height: window.innerHeight,
+      }),
+      // Lenis drives the window, so the documentElement is always visible.
+      pinType: "fixed",
+    });
+    ScrollTrigger.defaults({ scroller: document.documentElement });
+  }
+
+  const onResize = () => {
+    lenis.resize();
+    ScrollTrigger.refresh();
+  };
+  window.addEventListener("resize", onResize);
+
+  // Fonts and late images change layout; refresh once they land.
+  const refresh = () => ScrollTrigger.refresh();
+  window.addEventListener("load", refresh);
+
+  lenis.resize();
+  ScrollTrigger.refresh();
+
+  const destroy: Destroy = () => {
+    window.removeEventListener("resize", onResize);
+    window.removeEventListener("load", refresh);
+    gsap.ticker.remove(tick);
+    lenis.off("scroll", onScroll);
+    if (useScrollerProxy) {
+      ScrollTrigger.scrollerProxy(document.documentElement, {} as never);
+      ScrollTrigger.defaults({ scroller: window });
+    }
+    lenis.destroy();
+  };
+
+  return {
+    lenis,
+    active: true,
+    scrollTo: (target, opts) => lenis.scrollTo(target as never, opts),
+    destroy,
+  };
+}