@cosmictraveler002/anim-kit 1.2.0 → 1.4.0

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.2.0",
+  "version": "1.4.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

@@ -16,7 +16,7 @@ import type { TargetLike } from "./types.js";
 
 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",

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/drag-rail.ts

@@ -0,0 +1,285 @@
+/**
+ * Drag rail — the bounded, inertia-driven rail (horizontal or vertical).
+ *
+ * A grab-and-throw rail with real physics, extracted from the drag-driven
+ * portfolio rail pattern: pointer drag, wheel and trackpad all feed one
+ * *intent* value, and the track follows it with a per-frame lerp. Why it is
+ * shaped this way (audit notes):
+ *
+ * - **Two values, not one.** `intent` is where the rail wants to be (drag
+ *   delta, wheel delta, throw momentum); `pos` is what is rendered. The tick
+ *   lerps intent → pos (`lerp * deltaRatio`), which is what gives the
+ *   buttery catch-up after a hard throw. Writing the transform directly from
+ *   pointermove (v1) felt like dragging a brick.
+ * - **tanh rubber-band.** Past either end, intent is squashed through
+ *   `edge * tanh(overshoot / edge)` — the further you pull, the less each
+ *   pixel buys you, but it never hard-stops. On release a restore force pulls
+ *   the overscrolled intent back inside the bounds while the lerp chases it,
+ *   producing the settle. This is the same soft-edge maths as the original
+ *   rail's `a.t = a.a + tanh(l / t) * t`.
+ * - **Release throw.** Velocity is sampled as a smoothed per-frame pointer
+ *   delta (0.7 smoothing) and multiplied by `throwScale` into intent — a flick
+ *   coasts, a slow release barely moves. No InertiaPlugin dependency; the
+ *   ticker *is* the inertia.
+ * - **Wheel coexistence.** While the rail can still move in the wheel's
+ *   direction the event is consumed (`preventDefault` + `stopPropagation` —
+ *   the stop matters: Lenis listens above us and would scroll the page in
+ *   parallel). Once overscrolled a full `edge`, the wheel passes through to
+ *   the page again, so the section never traps the reader.
+ * - **Velocity-reactive items.** `tilt` rotates children proportionally to the
+ *   rendered per-frame velocity (the cards lean into motion and spring flat at
+ *   rest); `onTick` exposes pos/velocity for WebGL or custom consumers.
+ * - **Two axes.** `axis: "x"` (default), `"y"`, or `"auto"` — under `auto`
+ *   the *layout* decides via `resolveRailAxis()` (only the column overflows →
+ *   vertical, otherwise horizontal; the same rule glRail uses to pick its
+ *   bend axis). touch-action claims the rail's own gesture axis (`pan-y` for
+ *   a horizontal rail, `pan-x` for a vertical one) so the page never fights
+ *   the rail for a swipe, and a mid-life flip re-keys the transform instead
+ *   of leaving the stale axis behind.
+ * - **Fidelity.** `destroy()` removes every listener + the ticker, kills the
+ *   tilt state and restores the inline cursor/user-select/touch-action the
+ *   effect had overwritten.
+ *
+ *   dragRail(".ak-rail-track", { tilt: 0.05, axis: "auto" })
+ *
+ * CSS: viewport `overflow: hidden`; track `display: flex; width: max-content;
+ * gap: 1rem; cursor: grab; user-select: none; touch-action: pan-y`.
+ */
+import { gsap, initGSAP } 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 DragRailOptions extends CommonOptions {
+  /** Scroll viewport around the track — defaults to `track.parentElement`. */
+  viewport?: TargetLike;
+  /** Motion axis — `"auto"` flips vertical when only the column overflows. @default `"x"` */
+  axis?: "x" | "y" | "auto";
+  /** Children that tilt with velocity. @default `":scope > *"` */
+  item?: string;
+  /** Follow speed toward the intent, per 60fps frame (0..1). @default 0.1 */
+  lerp?: number;
+  /** Rubber-band resistance distance past the ends, px. @default 140 */
+  edge?: number;
+  /** Momentum multiplier on release (px of coast per px/frame of flick). @default 14 */
+  throwScale?: number;
+  /** Wheel / trackpad drives the rail (consumed while it can still move). @default true */
+  wheel?: boolean;
+  /** Degrees of tilt per px/frame of velocity — `0` disables. @default 0 */
+  tilt?: number;
+  /** Tilt clamp, degrees. @default 8 */
+  tiltMax?: number;
+  /** `(pos, velocity) => {}` called every rendered frame while mounted (pos along the active axis). */
+  onTick?: (pos: number, velocity: number) => void;
+}
+
+/**
+ * The axis rule shared by `dragRail` and `glRail`: fixed when asked, otherwise
+ * the layout decides — a rail only runs vertical when the *column* overflows
+ * and the row doesn't (a mobile stack), everything else is horizontal.
+ */
+export function resolveRailAxis(
+  track: HTMLElement,
+  viewport: HTMLElement,
+  pref: "x" | "y" | "auto",
+): "x" | "y" {
+  if (pref !== "auto") return pref;
+  const overflowY = track.scrollHeight - viewport.clientHeight;
+  const overflowX = track.scrollWidth - viewport.clientWidth;
+  return overflowY > 0 && overflowX <= 0 ? "y" : "x";
+}
+
+export function dragRail(target: TargetLike, options: DragRailOptions = {}): Destroy {
+  initGSAP();
+
+  const track = one<HTMLElement>(target);
+  if (!track) return () => {};
+
+  const {
+    viewport,
+    axis: axisOpt = "x",
+    item = ":scope > *",
+    lerp = 0.1,
+    edge = 140,
+    throwScale = 14,
+    wheel = true,
+    tilt = 0,
+    tiltMax = 8,
+    onTick,
+  } = options;
+
+  return guard(options, () => {
+    const vp = one<HTMLElement>(viewport) ?? track.parentElement ?? track;
+    const prevStyle = {
+      cursor: track.style.cursor,
+      userSelect: track.style.userSelect,
+      touchAction: track.style.touchAction,
+    };
+
+    /* ---------------- bounds ---------------- */
+
+    let axis: "x" | "y" = resolveRailAxis(track, vp, axisOpt);
+    let flipped = false; // axis changed mid-life → force a transform re-key
+    let min = 0; // most-negative resting position (content overflows)
+    let max = 0; // start of the rail
+    let pos = 0; // rendered position
+    let intent = 0; // wanted position (drag/wheel/throw feed this)
+
+    const measure = () => {
+      const next = resolveRailAxis(track, vp, axisOpt);
+      if (next !== axis) {
+        axis = next;
+        flipped = true;
+        // Claim the rail's own gesture axis; the other one belongs to the page.
+        track.style.touchAction = axis === "x" ? "pan-y" : "pan-x";
+      }
+      const overflow =
+        axis === "x"
+          ? track.scrollWidth - vp.clientWidth
+          : track.scrollHeight - vp.clientHeight;
+      min = -Math.max(0, overflow);
+      max = 0;
+      // Fold an out-of-range position back through the soft edge (no jump).
+      intent = soft(intent);
+      pos = soft(pos);
+    };
+
+    /** tanh soft-edge: unbounded input, saturating output around [min, max]. */
+    function soft(v: number): number {
+      if (v > max) return max + edge * Math.tanh((v - max) / edge);
+      if (v < min) return min + edge * Math.tanh((v - min) / edge);
+      return v;
+    }
+
+    /* ---------------- pointer drag ---------------- */
+
+    let dragging = false;
+    let last = 0; // last pointer coordinate along the active axis
+    let velocity = 0; // smoothed pointer delta (px/frame-ish)
+    let renderedVel = 0; // rendered per-frame velocity (drives tilt/onTick)
+
+    const along = (e: { clientX: number; clientY: number }) =>
+      axis === "x" ? e.clientX : e.clientY;
+
+    const onPointerDown = (e: PointerEvent) => {
+      if (e.pointerType === "mouse" && e.button !== 0) return;
+      dragging = true;
+      last = along(e);
+      velocity = 0;
+      try {
+        vp.setPointerCapture(e.pointerId);
+      } catch {
+        /* capture is best-effort — moves still land while the pointer is down */
+      }
+      track.style.cursor = "grabbing";
+    };
+
+    const onPointerMove = (e: PointerEvent) => {
+      if (!dragging) return;
+      const delta = along(e) - last;
+      last = along(e);
+      velocity = velocity * 0.7 + delta * 0.3; // smooth out event-rate jitter
+      intent = soft(intent + delta);
+    };
+
+    const endDrag = (e?: PointerEvent) => {
+      if (!dragging) return;
+      dragging = false;
+      track.style.cursor = prevStyle.cursor || "grab";
+      if (e) {
+        try {
+          vp.releasePointerCapture(e.pointerId);
+        } catch {
+          /* already released */
+        }
+      }
+      // A flick coasts on its sampled momentum, then the soft edge reclaims it.
+      intent = soft(intent + velocity * throwScale);
+    };
+
+    const onPointerUp = (e: PointerEvent) => endDrag(e);
+    const onPointerCancel = (e: PointerEvent) => endDrag(e);
+    const onDragStart = (e: Event) => e.preventDefault(); // no native img drag
+
+    /* ---------------- wheel / trackpad ---------------- */
+
+    const onWheel = (e: WheelEvent) => {
+      if (!wheel) return;
+      const delta =
+        axis === "x"
+          ? Math.abs(e.deltaX) > Math.abs(e.deltaY)
+            ? e.deltaX
+            : e.deltaY
+          : e.deltaY;
+      if (!delta) return;
+      const bound = delta > 0 ? max : min;
+      const outward = (intent - bound) * (delta > 0 ? 1 : -1);
+      if (outward > edge) return; // over-extended — hand the scroll back to the page
+      e.preventDefault();
+      e.stopPropagation(); // Lenis listens above us; it must not scroll in parallel
+      intent = soft(intent + delta);
+    };
+
+    /* ---------------- tick ---------------- */
+
+    const items = tilt ? toArray<HTMLElement>(item, track) : [];
+    if (items.length) gsap.set(items, { transformOrigin: "50% 50%" });
+
+    const tick = () => {
+      const ratio = gsap.ticker.deltaRatio(60); // frames since last tick, clamped
+      // Release restore: once input stops, overscrolled intent springs home.
+      if (!dragging) {
+        const bound = intent < min ? min : intent > max ? max : null;
+        if (bound !== null) intent += (bound - intent) * Math.min(1, 0.18 * ratio);
+      }
+      const prev = pos;
+      pos += (intent - pos) * Math.min(1, lerp * ratio);
+      renderedVel = pos - prev;
+      if (renderedVel === 0 && pos === intent && !flipped) return; // idle: skip the write
+      flipped = false;
+      // Re-key both axes: a flip must clear the stale one, never leave it behind.
+      gsap.set(track, axis === "x" ? { x: pos, y: 0 } : { x: 0, y: pos });
+      if (items.length) {
+        gsap.set(items, {
+          rotation: gsap.utils.clamp(-tiltMax, tiltMax, renderedVel * tilt),
+        });
+      }
+      onTick?.(pos, renderedVel);
+    };
+
+    /* ---------------- wiring ---------------- */
+
+    measure();
+    track.dataset.akRail = "true";
+    track.style.cursor = "grab";
+    track.style.userSelect = "none";
+    track.style.touchAction = axis === "x" ? "pan-y" : "pan-x";
+
+    vp.addEventListener("pointerdown", onPointerDown);
+    vp.addEventListener("pointermove", onPointerMove);
+    vp.addEventListener("pointerup", onPointerUp);
+    vp.addEventListener("pointercancel", onPointerCancel);
+    vp.addEventListener("wheel", onWheel, { passive: false });
+    track.addEventListener("dragstart", onDragStart);
+    const onResize = () => measure();
+    window.addEventListener("resize", onResize);
+    gsap.ticker.add(tick);
+
+    return () => {
+      window.removeEventListener("resize", onResize);
+      vp.removeEventListener("pointerdown", onPointerDown);
+      vp.removeEventListener("pointermove", onPointerMove);
+      vp.removeEventListener("pointerup", onPointerUp);
+      vp.removeEventListener("pointercancel", onPointerCancel);
+      vp.removeEventListener("wheel", onWheel);
+      track.removeEventListener("dragstart", onDragStart);
+      gsap.ticker.remove(tick);
+      delete track.dataset.akRail;
+      track.style.cursor = prevStyle.cursor;
+      track.style.userSelect = prevStyle.userSelect;
+      track.style.touchAction = prevStyle.touchAction;
+      gsap.set(track, { clearProps: "transform" });
+      if (items.length) gsap.set(items, { clearProps: "rotation,transformOrigin" });
+    };
+  });
+}

package/src/effects/preloader.ts

@@ -1,5 +1,5 @@
 /**
- * Preloader — the full-screen intro from dzinrstudio.com.
+ * Preloader — the full-screen intro from kalakritico.in.
  *
  * What it does on the real site:
  *   1. A big number counts 0 → 100 in the bottom-left corner (steps of 5,