@cosmictraveler002/anim-kit 1.3.0 → 1.5.0

package/dist/three/gl-rail.js

@@ -0,0 +1,350 @@
+/**
+ * GL rail — the WebGL overlay rail: physics below, bent cards above.
+ *
+ * `dragRail` owns the motion (intent/pos ticker, tanh rubber-band, throw
+ * momentum, Lenis-safe wheel, auto axis); this effect adds the GPU layer the
+ * flat DOM can't draw: every card re-rendered onto **one fixed canvas** whose
+ * surfaces bend around an invisible cylinder, over a perspective grid floor.
+ * Why it is shaped this way (audit notes):
+ *
+ * - **The DOM stays the source of truth.** Cards keep owning layout, labels,
+ *   hit areas and alt text; each frame reads their viewport rects and the
+ *   shader re-creates the pixels *beneath* the labels. A label never drifts
+ *   off its card, because the card **is** the rect the label sits in — only
+ *   the picture curves.
+ * - **The bend lives in the vertex shader.** Each vertex takes its offset
+ *   along the rail axis (`uOffset + local`), maps it onto a cylinder of
+ *   `uRadius` (`a = o / R`, `x = R·sin a`, `z = −R·(1−cos a)`) and re-centres
+ *   so the card's middle stays glued to its DOM position while its edges
+ *   foreshorten onto the curve. One uniform per card, no per-vertex CPU work
+ *   — and the rotation the cards need arrives free from the bend itself.
+ * - **One renderer for the whole rail.** A single alpha canvas inserted
+ *   *under* the track (the track's transform creates a stacking context that
+ *   paints above it): labels stay DOM, card backgrounds stay transparent, and
+ *   the only pixels the canvas needs are the `<img>`s it hides — each one
+ *   only after its texture has actually loaded.
+ * - **The axis follows the layout.** `axis: "auto"` hands the same
+ *   `resolveRailAxis()` rule to the physics *and* the bend: row overflows →
+ *   horizontal rail + bend around Y, only the column overflows (mobile
+ *   stack) → vertical rail + bend around X. One init serves both.
+ * - **Silent no-op ladder.** Missing target → no-op. No
+ *   `WebGLRenderingContext` (jsdom, SSR, WebGL-disabled browsers) → the flat
+ *   `dragRail` rail alone, *before* any context is requested (a probe call
+ *   would itself log). Renderer construction throws → flat rail. Texture 404
+ *   → that one card's `<img>` stays visible. Under `prefers-reduced-motion`
+ *   nothing mounts at all (the outer `guard` owns that decision). Nothing
+ *   ever logs.
+ * - **Fidelity.** `destroy()` unwinds the physics, then the GPU: ticker,
+ *   observers, geometry, materials, textures and the renderer are disposed,
+ *   the canvas is removed and image opacities + the stage's inline position
+ *   are restored.
+ *
+ *   glRail("[data-rail]", { radius: 1200, grid: true })
+ *
+ * CSS: the stage (viewport) `position: relative; overflow: hidden` — the
+ * canvas covers it; the track `display: flex; width: max-content; gap: 1rem;
+ * cursor: grab; user-select: none; touch-action: pan-y` (flip to a column +
+ * `width: 100%; height: max-content` for the vertical layout). Cards
+ * `position: relative` with a **transparent background** — labels paint above
+ * the canvas for free, the effect hides only the media.
+ */
+import * as THREE from "three";
+import { gsap, initGSAP } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { one, toArray } from "../core/util.js";
+import { dragRail, resolveRailAxis } from "../effects/drag-rail.js";
+/* Card: the cylinder bend in the vertex shader, cover-crop + SDF corners in
+   the fragment — the pixel contract is webglMedia's, bent to the rail. */
+const CARD_VERT = /* glsl */ `
+varying vec2 vUv;
+uniform vec2 uSize;    // card size, px
+uniform float uOffset; // centre offset from the stage centre along the rail axis, px
+uniform float uRadius; // cylinder radius, px
+uniform float uAxis;   // 0 = rail runs x (bend around Y), 1 = rail runs y (bend around X)
+
+void main() {
+  vUv = uv;
+  vec3 p = vec3(position.xy * uSize, 0.0);
+  float along = uAxis < 0.5 ? p.x : p.y;
+  float a = (uOffset + along) / uRadius;
+  // Re-centre on the card's own middle: the centre stays glued to the DOM
+  // rect while the edges foreshorten onto the cylinder.
+  float bent = uRadius * sin(a) - uRadius * sin(uOffset / uRadius) + uOffset;
+  if (uAxis < 0.5) p.x = bent; else p.y = bent;
+  p.z = -uRadius * (1.0 - cos(a));
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
+}
+`;
+const CARD_FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D uTex;
+uniform vec2 uRes;
+uniform vec2 uTexSize;
+uniform float uCorner;
+
+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
+  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;
+  gl_FragColor = vec4(texture2D(uTex, cover).rgb, alpha);
+}
+`;
+/* Floor: one plane lying at the bottom of the stage, lines in world space,
+   fading toward the horizon and the sides, drifting slightly with the rail. */
+const GRID_VERT = /* glsl */ `
+varying vec2 vWorld; // world xz under this fragment
+void main() {
+  vec4 wp = modelMatrix * vec4(position, 1.0);
+  vWorld = wp.xz;
+  gl_Position = projectionMatrix * viewMatrix * wp;
+}
+`;
+const GRID_FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vWorld;
+uniform vec2 uShift;    // parallax drift with the rail position, px
+uniform vec3 uColor;
+uniform float uOpacity;
+uniform float uSpacing;
+
+void main() {
+  vec2 cell = (vWorld + uShift) / uSpacing;
+  vec2 grad = abs(fract(cell - 0.5) - 0.5) / max(fwidth(cell), 1e-5);
+  float line = 1.0 - min(min(grad.x, grad.y), 1.0);
+  float depth = smoothstep(-5200.0, -400.0, vWorld.y); // melt into the horizon
+  float side = 1.0 - smoothstep(1300.0, 3600.0, abs(vWorld.x));
+  gl_FragColor = vec4(uColor, line * uOpacity * depth * side);
+}
+`;
+/** Floor geometry constants — near edge slightly in front of the cards, far
+    edge past the horizon; the stage bottom sits where the z=0 plane ends. */
+const GRID_SPAN = 7200;
+const GRID_DEPTH = 6000;
+const GRID_NEAR_Z = 520;
+export function glRail(target, options = {}) {
+    initGSAP();
+    const track = one(target);
+    if (!track)
+        return () => { };
+    const { viewport, card = ":scope > *", axis = "auto", radius = 1200, corner = 16, grid = true, dpr = 2, lerp, edge, throwScale, wheel, onTick, } = options;
+    return guard(options, () => {
+        const vp = one(viewport) ?? track.parentElement ?? track;
+        /* ---------------- physics first: the rail works with or without a GPU ---------------- */
+        let lastPos = 0;
+        const stopPhysics = dragRail(track, {
+            viewport: vp,
+            axis,
+            lerp,
+            edge,
+            throwScale,
+            wheel,
+            // The outer guard already decided about reduced motion for both of us.
+            force: true,
+            onTick: (pos, velocity) => {
+                lastPos = pos;
+                onTick?.(pos, velocity);
+            },
+        });
+        /* ---------------- availability ladder (silent, no probes) ---------------- */
+        if (typeof window === "undefined" || !("WebGLRenderingContext" in window))
+            return stopPhysics;
+        let renderer;
+        try {
+            renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
+        }
+        catch {
+            return stopPhysics; // context refused — the flat DOM rail is the fallback
+        }
+        /* ---------------- stage + camera ---------------- */
+        const prevPosition = vp.style.position;
+        if (!prevPosition && getComputedStyle(vp).position === "static") {
+            vp.style.position = "relative";
+        }
+        renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, dpr));
+        const scene = new THREE.Scene();
+        const camera = new THREE.PerspectiveCamera(45, 1, 10, 14000);
+        // Pixel-space at z = 0: the z=0 plane exactly fills the stage.
+        const fitCamera = (w, h) => {
+            camera.aspect = w / h;
+            camera.position.set(0, 0, h / 2 / Math.tan((camera.fov * Math.PI) / 360));
+            camera.updateProjectionMatrix();
+        };
+        /* ---------------- grid floor ---------------- */
+        let gridMesh = null;
+        let gridShift = null;
+        if (grid) {
+            gridShift = new THREE.Vector2();
+            const material = new THREE.ShaderMaterial({
+                vertexShader: GRID_VERT,
+                fragmentShader: GRID_FRAG,
+                uniforms: {
+                    uShift: { value: gridShift },
+                    uColor: { value: new THREE.Color(0.66, 0.7, 0.78) },
+                    uOpacity: { value: 0.24 },
+                    uSpacing: { value: 150 },
+                },
+                transparent: true,
+                depthWrite: false,
+                depthTest: false,
+            });
+            gridMesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
+            gridMesh.rotation.x = -Math.PI / 2;
+            gridMesh.renderOrder = -1; // floor first, cards over it
+            scene.add(gridMesh);
+        }
+        const geometry = new THREE.PlaneGeometry(1, 1, 24, 12);
+        const entries = [];
+        const loader = new THREE.TextureLoader();
+        let disposed = false;
+        for (const el of toArray(card, track)) {
+            const img = el.querySelector("img");
+            const src = img?.currentSrc || img?.src;
+            if (!img || !src)
+                continue; // label-only card — nothing to paint
+            const uniforms = {
+                uTex: { value: null },
+                uRes: { value: new THREE.Vector2(1, 1) },
+                uTexSize: { value: new THREE.Vector2(1, 1) },
+                uCorner: { value: corner },
+                uSize: { value: new THREE.Vector2(1, 1) },
+                uOffset: { value: 0 },
+                uRadius: { value: radius },
+                uAxis: { value: 0 },
+            };
+            const material = new THREE.ShaderMaterial({
+                vertexShader: CARD_VERT,
+                fragmentShader: CARD_FRAG,
+                uniforms,
+                transparent: true,
+                depthWrite: false,
+                depthTest: false,
+            });
+            // Positions come from the shader (uOffset/uSize), not the 1×1 geometry —
+            // the default bounding sphere would cull every card off-screen.
+            const mesh = new THREE.Mesh(geometry, material);
+            mesh.frustumCulled = false;
+            mesh.visible = false;
+            scene.add(mesh);
+            const prevOpacity = img.style.opacity;
+            entries.push({ el, img, mesh, material, prevOpacity });
+            loader.load(src, (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 stays an ordinary RGBA8 upload (same contract as
+                // webglMedia — built-in colourSpace 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;
+                img.style.opacity = "0"; // the canvas owns these pixels from here
+            }, undefined, () => {
+                /* 404 / decode failure — this card's <img> was never hidden. */
+            });
+        }
+        if (!entries.length) {
+            // Nothing renderable — plain dragRail is the whole effect.
+            geometry.dispose();
+            gridMesh?.geometry.dispose();
+            gridMesh?.material?.dispose();
+            renderer.dispose();
+            return stopPhysics;
+        }
+        /* ---------------- canvas: under the track, over the stage ---------------- */
+        const canvas = renderer.domElement;
+        canvas.style.cssText =
+            "position:absolute;inset:0;width:100%;height:100%;display:block;pointer-events:none;";
+        vp.insertBefore(canvas, track);
+        vp.dataset.akGlRail = "true";
+        /* ---------------- sizing ---------------- */
+        const resize = () => {
+            const w = Math.max(1, vp.clientWidth);
+            const h = Math.max(1, vp.clientHeight);
+            renderer.setSize(w, h, false);
+            fitCamera(w, h);
+            if (gridMesh) {
+                gridMesh.scale.set(GRID_SPAN, GRID_DEPTH, 1);
+                // Local +y maps to world −z, so centre the plane to span
+                // [GRID_NEAR_Z − GRID_DEPTH, GRID_NEAR_Z] in z.
+                gridMesh.position.set(0, -h / 2 + 2, GRID_NEAR_Z - GRID_DEPTH / 2);
+            }
+        };
+        resize();
+        let ro = null;
+        if (typeof ResizeObserver === "function") {
+            ro = new ResizeObserver(resize);
+            ro.observe(vp);
+        }
+        /* ---------------- loop ---------------- */
+        let visible = true;
+        let io = null;
+        if (typeof IntersectionObserver === "function") {
+            io = new IntersectionObserver(([entry]) => (visible = entry.isIntersecting), {
+                rootMargin: "120px",
+            });
+            io.observe(vp);
+        }
+        const sync = () => {
+            const stage = vp.getBoundingClientRect();
+            const cx = stage.left + stage.width / 2;
+            const cy = stage.top + stage.height / 2;
+            const vertical = resolveRailAxis(track, vp, axis) === "y";
+            for (const entry of entries) {
+                const rect = entry.el.getBoundingClientRect();
+                const u = entry.material.uniforms;
+                u.uOffset.value = vertical
+                    ? cy - (rect.top + rect.height / 2)
+                    : rect.left + rect.width / 2 - cx;
+                u.uSize.value.set(rect.width, rect.height);
+                u.uRes.value.set(rect.width, rect.height);
+                u.uAxis.value = vertical ? 1 : 0;
+            }
+        };
+        const render = () => {
+            if (!visible)
+                return;
+            sync();
+            gridShift?.set(lastPos * 0.1, 0); // subtle parallax: the floor trails the rail
+            renderer.render(scene, camera);
+        };
+        gsap.ticker.add(render);
+        /* ---------------- teardown ---------------- */
+        return () => {
+            disposed = true;
+            stopPhysics();
+            gsap.ticker.remove(render);
+            io?.disconnect();
+            ro?.disconnect();
+            for (const entry of entries) {
+                entry.material.uniforms.uTex.value?.dispose();
+                entry.material.dispose();
+                entry.img.style.opacity = entry.prevOpacity;
+            }
+            geometry.dispose();
+            if (gridMesh) {
+                gridMesh.geometry.dispose();
+                gridMesh.material.dispose();
+            }
+            renderer.dispose();
+            canvas.remove();
+            delete vp.dataset.akGlRail;
+            vp.style.position = prevPosition;
+        };
+    });
+}
+//# sourceMappingURL=gl-rail.js.map

package/dist/three/gl-rail.js.map

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

package/dist/three/index.d.ts

@@ -6,8 +6,10 @@
  * The core barrel (`@cosmictraveler002/anim-kit`) never imports three, so
  * plain DOM/scroll users keep a gsap+lenis-only dependency tree.
  *
- *   import { webglMedia } from "@cosmictraveler002/anim-kit/three";
+ *   import { webglMedia, glRail } from "@cosmictraveler002/anim-kit/three";
  */
 export { webglMedia } from "./webgl-media.js";
 export type { WebglMediaOptions } from "./webgl-media.js";
+export { glRail } from "./gl-rail.js";
+export type { GlRailOptions } from "./gl-rail.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/three/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/three/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/three/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/three/index.js

@@ -6,7 +6,8 @@
  * The core barrel (`@cosmictraveler002/anim-kit`) never imports three, so
  * plain DOM/scroll users keep a gsap+lenis-only dependency tree.
  *
- *   import { webglMedia } from "@cosmictraveler002/anim-kit/three";
+ *   import { webglMedia, glRail } from "@cosmictraveler002/anim-kit/three";
  */
 export { webglMedia } from "./webgl-media.js";
+export { glRail } from "./gl-rail.js";
 //# sourceMappingURL=index.js.map

package/dist/three/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/three/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/three/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmictraveler002/anim-kit",
-  "version": "1.3.0",
+  "version": "1.5.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/smooth-scroll.ts

@@ -4,10 +4,14 @@
  * 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.
+ * Those ticker callbacks receive the *same* adjusted clock the tweens run on,
+ * so GSAP's lag smoothing is deliberately left on: a stalled frame (GC pause,
+ * buffer tick) advances one short step everywhere instead of snapping the
+ * scroll and every scroll-linked tween to a new time at once. See
+ * SmoothScrollOptions.lagSmoothing to retune it or restore the old opt-out.
  *
  * `useScrollerProxy: true` additionally proxies `document.documentElement`,
  * matching kalakritico.in's setup — only needed if you scroll a nested
@@ -31,6 +35,27 @@ export interface SmoothScrollOptions extends CommonOptions {
   initialScroll?: number;
   /** Proxy documentElement through ScrollTrigger (nested scrollers). @default false */
   useScrollerProxy?: boolean;
+  /** Touch-drag sensitivity — forwarded to Lenis `touchMultiplier`. @default 1 */
+  touchMultiplier?: number;
+  /** Mouse-wheel sensitivity — forwarded to Lenis `wheelMultiplier`. @default 1 */
+  wheelMultiplier?: number;
+  /**
+   * GSAP lag smoothing on the shared ticker: a frame longer than `threshold`
+   * advances only `adjustedLag` ms, so a hitch can't teleport the scroll and
+   * every scroll-linked tween in one jump.
+   *
+   * - `undefined` — leave GSAP's setup alone; its built-in compensation
+   *   (500ms → 33ms) stays active.
+   * - `false` — disable lag smoothing (anim-kit ≤1.4 behaviour, what the
+   *   Lenis README recipe asks for): timing stays exactly wall-clock, but
+   *   every frame longer than the threshold snaps.
+   * - `{ threshold, adjustedLag }` — retune it. Lower the threshold (e.g.
+   *   `150`) to smooth short mobile hitches; raise it if slow devices should
+   *   keep real-time speed instead of briefly running slow-motion.
+   *
+   * `destroy()` restores GSAP's default (500/33) whenever this was set.
+   */
+  lagSmoothing?: false | { threshold?: number; adjustedLag?: number };
 }
 
 export interface SmoothScrollHandle {
@@ -61,6 +86,9 @@ export function smoothScroll(options: SmoothScrollOptions = {}): SmoothScrollHan
     orientation = "vertical",
     initialScroll = 0,
     useScrollerProxy = false,
+    touchMultiplier,
+    wheelMultiplier,
+    lagSmoothing,
   } = options;
 
   if (typeof window === "undefined") return INERT;
@@ -74,6 +102,9 @@ export function smoothScroll(options: SmoothScrollOptions = {}): SmoothScrollHan
     syncTouch: smoothTouch,
     orientation,
     autoRaf: false,
+    // undefined falls through to Lenis's own defaults (1 / 1).
+    touchMultiplier,
+    wheelMultiplier,
   });
 
   if (initialScroll) lenis.scrollTo(initialScroll, { immediate: true });
@@ -85,7 +116,17 @@ export function smoothScroll(options: SmoothScrollOptions = {}): SmoothScrollHan
   // 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);
+
+  // Lag smoothing drives *one* clock — the tweens' and this ticker's alike —
+  // so leaving GSAP's compensation on turns a stalled frame into one short
+  // step everywhere instead of a snap. Only touch the ticker when asked, so a
+  // host page's own setup is never clobbered.
+  let lagTouched = false;
+  if (lagSmoothing !== undefined) {
+    lagTouched = true;
+    if (lagSmoothing === false) gsap.ticker.lagSmoothing(0);
+    else gsap.ticker.lagSmoothing(lagSmoothing.threshold ?? 500, lagSmoothing.adjustedLag ?? 33);
+  }
 
   // 3. Optional: proxy the scroller (for nested/element scrollers).
   if (useScrollerProxy) {
@@ -126,6 +167,7 @@ export function smoothScroll(options: SmoothScrollOptions = {}): SmoothScrollHan
     window.removeEventListener("resize", onResize);
     window.removeEventListener("load", refresh);
     gsap.ticker.remove(tick);
+    if (lagTouched) gsap.ticker.lagSmoothing(500, 33); // undo our change — GSAP's default
     lenis.off("scroll", onScroll);
     if (useScrollerProxy) {
       ScrollTrigger.scrollerProxy(document.documentElement, {} as never);