@cosmictraveler002/anim-kit 1.2.0 → 1.4.0

package/README.md

@@ -1,7 +1,7 @@
 # anim-kit
 
-A modular, framework-agnostic animation library extracted from
-[dzinrstudio.com](https://dzinrstudio.com/) — GSAP + ScrollTrigger + Lenis
+A modular, framework-agnostic animation library by
+[kalakritico.in](https://kalakritico.in/) — GSAP + ScrollTrigger + Lenis
 effects packaged as independent ES modules.
 
 TypeScript source → compiled ESM + `.d.ts` output. No framework, no virtual DOM,
@@ -78,8 +78,9 @@ inside the published tarball):
 
 | Specifier | Resolves to | Use for |
 |---|---|---|
-| `@cosmictraveler002/anim-kit` | `dist/index.js` + `dist/index.d.ts` | the full barrel — 45 exports |
+| `@cosmictraveler002/anim-kit` | `dist/index.js` + `dist/index.d.ts` | the full barrel — 47 exports |
 | `@cosmictraveler002/anim-kit/effects/<name>` | `dist/effects/<name>.js` + `.d.ts` | one effect in isolation (`marquee`, `lineReveal`, …) |
+| `@cosmictraveler002/anim-kit/three` | `dist/three/index.js` + `.d.ts` | WebGL effects — needs the optional `three` peer (never a core dep) |
 | `@cosmictraveler002/anim-kit/standalone` | `dist/anim-kit.standalone.js` (types → `index.d.ts`) | the self-contained bundle — same API |
 | `@cosmictraveler002/anim-kit/styles` | `dist/styles/anim-kit.css` | untouched plain CSS |
 
@@ -97,7 +98,7 @@ resolves declarations through the same map — no `typesVersions` shim needed.
 
 No build step on the consumer's end: `dist/` is served as-is from the npm
 tarball by any npm CDN. Every URL is **version-pinned** — npm versions are
-immutable, so `@cosmictraveler002/anim-kit@1.2.0` always resolves to exactly that build, forever
+immutable, so `@cosmictraveler002/anim-kit@1.4.0` always resolves to exactly that build, forever
 (only a new version creates a new URL; nothing floats unless you ask for a
 range).
 
@@ -108,12 +109,12 @@ plugins anim-kit uses) and `lenis` **inlined** — no import map, one URL, works
 identically on jsDelivr and unpkg:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/dist/styles/anim-kit.css" />
 
 <script type="module">
   import {
     smoothScroll, lineReveal, marquee,
-  } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/anim-kit.standalone.js";
+  } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/dist/anim-kit.standalone.js";
 
   smoothScroll();
   lineReveal("[data-lines]", { mode: "scroll" });
@@ -121,7 +122,7 @@ identically on jsDelivr and unpkg:
 </script>
 ```
 
-unpkg serves the same file: `https://unpkg.com/@cosmictraveler002/anim-kit@1.2.0/dist/anim-kit.standalone.js`
+unpkg serves the same file: `https://unpkg.com/@cosmictraveler002/anim-kit@1.4.0/dist/anim-kit.standalone.js`
 
 ### Option 2 — jsDelivr `+esm`
 
@@ -130,7 +131,7 @@ per version):
 
 ```html
 <script type="module">
-  import { lineReveal } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/+esm";
+  import { lineReveal } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/+esm";
 </script>
 ```
 
@@ -142,12 +143,14 @@ locally, with CDN URLs — and the way to share one GSAP between anim-kit and
 the rest of your page:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/dist/styles/anim-kit.css" />
 
 <script type="importmap">
   {
     "imports": {
-      "@cosmictraveler002/anim-kit": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/index.js",
+      "@cosmictraveler002/anim-kit": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/dist/index.js",
+      "@cosmictraveler002/anim-kit/three": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/dist/three/index.js",
+      "three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js",
       "gsap": "https://cdn.jsdelivr.net/npm/gsap@3.15.0/index.js",
       "gsap/ScrollTrigger": "https://cdn.jsdelivr.net/npm/gsap@3.15.0/ScrollTrigger.js",
       "gsap/SplitText": "https://cdn.jsdelivr.net/npm/gsap@3.15.0/SplitText.js",
@@ -167,12 +170,42 @@ the rest of your page:
 </script>
 ```
 
-Swap the host for unpkg (`https://unpkg.com/@cosmictraveler002/anim-kit@1.2.0/dist/index.js`, …) —
+Swap the host for unpkg (`https://unpkg.com/@cosmictraveler002/anim-kit@1.4.0/dist/index.js`, …) —
 the file layout is identical. GSAP subpaths are listed one by one because
 import maps match specifiers literally: a trailing-slash prefix map would
 produce extension-less URLs, which CDNs don't serve. The `gsap`/`lenis` pins
 match `package-lock.json`.
 
+### Version discipline — the pin must match the code
+
+The pin is a contract between the URL and the importing code: a bundle older
+than the names your code imports fails at **module instantiation**, before a
+single line runs —
+
+```text
+SyntaxError: The requested module '…/anim-kit@<old-version>/dist/anim-kit.standalone.js'
+does not provide an export named 'clipWipe'
+```
+
+On a page with a preloader that reads as **frozen on the loader**: the script
+that would dismiss it never executed. Whenever a loader won't clear, open the
+console first — an `… does not provide an export named 'X'` error is version
+skew, not an effect bug.
+
+Rules that keep it from happening:
+
+- **Never hand-copy the demo or hand-edit CDN URLs.** Regenerate the
+  deployable copy with `npm run sync:live` — it rewrites every pin from
+  `CDN_VERSION` in `scripts/prompts.mjs`, the single source, and
+  `demo-smoke` fails CI if `demo/`, `demo_live/` or this README drift from
+  the release version.
+- **On a release bump**, change `version` and `CDN_VERSION` together (the
+  smoke enforces it); every copy prompt, the docs page and `demo_live/`
+  follow automatically.
+- **In your own project**, every CDN URL you ship must carry the *same*
+  version — mixing a new JS pin with an old CSS pin (or vice versa) is the
+  same bug in slow motion.
+
 ---
 
 ## Quick start
@@ -280,15 +313,16 @@ prompt dock, and backs the `category` / `subcategory` fields on
 | Text animations | Line & mask reveals | `lineReveal`, `maskReveal` |
 | Text animations | Per-character scatter | `scatterText` |
 | Text animations | Decode & scramble | `scrambleText` |
-| Text animations | Rolling text | `rollText` |
+| Text animations | Rolling text | `rollText`, `reelText` |
 | Text animations | Counters | `counter` |
 | Text animations | Layout transfers | `flipWords` |
 | Scroll & media | Pinned galleries | `horizontalScroll`, `stackedCards`, `stackedCardsPinned` |
 | Scroll & media | Parallax & depth | `parallax` |
 | Scroll & media | Heroes & media | `heroShrink`, `mediaSettle` |
 | Scroll & media | Enter reveals | `revealRule`, `unfoldReveal`, `clipWipe` |
+| WebGL | Shader media | `webglMedia`, `glRail` |
 | Loops & marquees | Marquees | `marquee` |
-| Loops & marquees | Infinite draggables | `dragStrip` |
+| Loops & marquees | Draggables & rails | `dragStrip`, `dragRail` |
 | Loops & marquees | Equalizers | `audioBars` |
 | Buttons & links | Liquid fills | `liquidButton` |
 | Buttons & links | Underlines | `underlineLink` |
@@ -352,7 +386,7 @@ Central reduced-motion gate. If the user prefers reduced motion and
 ### Text animations
 
 Typography in motion — masked lines, rising masks, per-character scatter,
-decode reveals, rolling words, tickers, layout transfers.
+decode reveals, rolling words and reels, tickers, layout transfers.
 
 #### `lineReveal(target, options?) => destroy`
 
@@ -481,6 +515,40 @@ rollText("[data-roll-rev]", { direction: "down" }); // walk rows in reverse
 blocks itself. `destroy()` unwraps the rows, removes the clone and restores
 every inline style — markup comes back byte-identical.
 
+#### `reelText(target, options?) => destroy`
+
+Per-character odometer roll — the DOM slot-machine decode. Every alphanumeric
+character gets a masked cell holding a vertical strip of same-case ghost
+glyphs; the strip rolls upward and lands on the real text, staggered left to
+right. Spaces and punctuation pass through untouched.
+
+```html
+<p data-reel>Every character rolls into place.</p>
+```
+
+```ts
+reelText("[data-reel]", { mode: "scroll", frames: 4, stagger: 0.05 }); // roll on enter
+reelText("[data-immediate]");                                          // roll at init
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `mode` | `"immediate"` | `"scroll"` rolls on viewport enter instead |
+| `start` | `"top 85%"` | ScrollTrigger start (scroll mode) |
+| `frames` | `4` | ghost glyphs per character before the final one |
+| `duration` | `0.8` | roll time per character, seconds |
+| `stagger` | `0.05` | delay between characters, seconds |
+| `ease` | `"power4.out"` | GSAP ease for the roll |
+| `replay` | `false` | re-arm on every scroll re-entry instead of once |
+| `force` | `false` | run even under `prefers-reduced-motion` |
+
+**DOM:** targets must be plain text — the effect snapshots `innerHTML`, wraps
+each character in a measured mask (width taken from the *final* glyph, so the
+line never jitters while spinning) and restores the original markup byte for
+byte when the roll completes and on `destroy()`. Scroll-mode registration
+happens once and is killed on teardown; reduced motion leaves the target
+completely untouched. No stylesheet required — masks are inline.
+
 #### `flipWords(target, { to }, options?) => destroy`
 
 Words measured in one layout, moved into another and animated from where
@@ -727,9 +795,125 @@ the entrance.
 
 ---
 
+### WebGL
+
+GPU media — three.js re-renders your images as shader cards. This is the only
+category behind the `@cosmictraveler002/anim-kit/three` subpath: `three` is an
+**optional peer** (see [Subpath exports](#subpath-exports)), so the core
+barrel and the standalone bundle stay three-free.
+
+#### `webglMedia(target, options?) => destroy`
+
+> From `@cosmictraveler002/anim-kit/three`, not the core barrel.
+
+Re-renders a plain `<img>` as a rounded GL plane: hover presses a dent into
+the picture (the sample UV is squeezed toward the cursor, with a fake dome
+lighting term and a chroma split), and the card wipes in bottom-up on reveal.
+Corners are shader-true (rounded-box SDF with a 1px AA edge) and the cover
+crop runs in-shader (`object-fit: cover` maths), so any source aspect fills
+any card aspect without letterboxing.
+
+```html
+<figure data-gl><img src="photo.jpg" alt="" /></figure>
+```
+
+```ts
+import { webglMedia } from "@cosmictraveler002/anim-kit/three";
+
+webglMedia("[data-gl]", { corner: 18, dent: 70, chroma: 2 });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `src` | first `<img>` | image source override when the wrapper has none |
+| `corner` | `16` | corner radius, px (SDF, not `border-radius`) |
+| `dent` | `70` | dent depth pressed into the card on hover, px |
+| `chroma` | `2` | rgb split at full hover, px |
+| `reveal` | `true` | wipe the card in bottom-up when its texture loads |
+| `revealDuration` | `1.1` | reveal duration, seconds |
+| `hoverDuration` | `0.6` | hover response duration, seconds |
+| `dpr` | `2` | device-pixel-ratio cap |
+| `force` | `false` | run even under `prefers-reduced-motion` |
+
+**Silent no-op ladder.** Missing target → no-op; no `WebGLRenderingContext`
+(SSR, jsdom, WebGL disabled) → no-op *before* any context probe (a probe
+itself logs an error in jsdom); renderer refused → no-op; texture 404 → the
+plain `<img>` stays visible. Nothing ever logs. Reduced motion → the canvas
+never mounts; the static image is the resting state.
+
+**DOM.** The wrapper gets inline `position: relative` if it was static (so
+the canvas can cover it — restored on destroy) and keeps layout, sizing and
+alt text in its `<img>`; the canvas takes over only after the texture has
+loaded. `destroy()` kills ticker + tweens + resize observer and disposes
+geometry, material, texture and renderer.
+
+#### `glRail(track, options?) => destroy`
+
+> From `@cosmictraveler002/anim-kit/three`, not the core barrel.
+
+The bounded drag rail drawn as a **WebGL overlay**: one fixed alpha canvas
+covers the stage and re-creates every card's picture from its DOM rect each
+frame, with the surface bent around an invisible cylinder — `dragRail`'s
+physics (intent/pos ticker, tanh rubber-band, throw momentum, Lenis-safe
+wheel) underneath, and a perspective grid floor that fades into the horizon
+and drifts with the rail. The DOM keeps layout, labels and hit areas: the
+canvas paints *under* the track, so a caption sits over the GL media for
+free, and only each `<img>` gets hidden — after its texture has loaded.
+
+The bend is one uniform per card in the vertex shader: each vertex maps its
+offset onto the cylinder (`a = o / R`, `x = R·sin a`, `z = −R·(1−cos a)`)
+re-centred on the card's own middle — the centre stays glued to the DOM
+position while the edges foreshorten, and the rotation arrives free from the
+curve. `axis: "auto"` hands the same rule to physics *and* bend: a row
+overflows → horizontal, only the column overflows → vertical, so one init
+serves the desktop row and the mobile stack.
+
+```html
+<div class="rail-screen"> <!-- position: relative; overflow: hidden -->
+  <div data-rail>
+    <article class="rail-card"><img src="card-01.jpg" alt="" /><p>Night Atlas</p></article>
+    <article class="rail-card"><img src="card-02.jpg" alt="" /><p>Signal Bloom</p></article>
+  </div>
+</div>
+```
+
+```ts
+import { glRail } from "@cosmictraveler002/anim-kit/three";
+
+glRail("[data-rail]", { radius: 1200, grid: true, throwScale: 14 });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `viewport` | track's parent | the stage the canvas covers — keep it `overflow: hidden` |
+| `card` | `":scope > *"` | cards re-rendered — each needs an `<img>` |
+| `axis` | `"auto"` | `"x"` / `"y"` / `"auto"` — picks motion **and** bend axis |
+| `radius` | `1200` | cylinder radius the cards bend around, px |
+| `corner` | `16` | corner radius, px (SDF, not `border-radius`) |
+| `grid` | `true` | perspective grid floor under the cards |
+| `dpr` | `2` | device-pixel-ratio cap |
+| `lerp` / `edge` / `throwScale` / `wheel` / `onTick` | `0.1` / `140` / `14` / `true` / — | `dragRail` physics passthrough |
+| `force` | `false` | run even under `prefers-reduced-motion` |
+
+**Silent no-op ladder.** Missing target → no-op; no `WebGLRenderingContext`
+(SSR, jsdom, WebGL disabled) → the **flat `dragRail` rail** still runs
+(plain `<img>`s, full motion) *before* any context probe; renderer refused
+→ flat rail; texture 404 → that one card keeps its image; reduced motion →
+nothing mounts. Nothing ever logs. `destroy()` unwinds physics + GPU
+together (listeners, ticker, observers, geometry, materials, textures,
+renderer, canvas) and restores image opacities + the stage's inline
+position.
+
+**DOM.** Stage `position: relative; overflow: hidden` with a transparent
+card background; the track is a flex row (or `flex-direction: column; width:
+100%; height: max-content` for the vertical layout) with `cursor: grab;
+user-select: none`.
+
+---
+
 ### Loops & marquees
 
-Continuous motion — marquees, infinite draggables, equaliser bars.
+Continuous motion — marquees, draggable rails, equaliser bars.
 
 #### `marquee(track, options?) => destroy`
 
@@ -798,6 +982,60 @@ cursor/user-select/touch-action.
 `touch-action: pan-y` inline and restores them on destroy); items keep
 `transform-origin: 50% 100%` so they pivot from their base.
 
+#### `dragRail(track, options?) => destroy`
+
+Bounded drag rail with real physics — the finite counterpart to
+`dragStrip()`'s infinite loop. Pointer, wheel and trackpad all feed one
+*intent* value; a single ticker lerps the track toward it (`lerp` scaled by
+GSAP's `deltaRatio`, so the settle rate is framerate-independent), past
+either end the intent squashes through a tanh rubber-band
+(`edge * tanh(overshoot / edge)` — pull further, gain less, never a hard
+stop), and a release coasts on velocity sampled over the last few frames.
+Horizontal by default; `axis: "auto"` flips the rail vertical when only the
+column overflows, so a mobile card stack needs no re-init.
+
+```ts
+dragRail("[data-rail]", { tilt: 0.05, throwScale: 14, wheel: true, axis: "auto" });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `viewport` | track's parent | scroll viewport around the track |
+| `axis` | `"x"` | `"x"` / `"y"` / `"auto"` — auto follows the layout (`pan-y` / `pan-x` claims the rail's own gesture) |
+| `item` | `":scope > *"` | children that tilt with velocity |
+| `lerp` | `0.1` | follow speed toward intent, per 60fps frame (0..1) |
+| `edge` | `140` | rubber-band resistance distance past the ends, px |
+| `throwScale` | `14` | momentum multiplier on release |
+| `wheel` | `true` | wheel/trackpad drives the rail too |
+| `tilt` | `0` | degrees of tilt per px/frame of velocity (`0` = off) |
+| `tiltMax` | `8` | tilt clamp, degrees |
+| `onTick` | — | `(pos, velocity) => {}` every rendered frame |
+| `force` | `false` | run even under `prefers-reduced-motion` |
+
+**Single writer.** Pointer, wheel and release handlers only ever touch
+*intent*; the ticker is the sole writer of the track transform — that
+separation is what gives a hard throw its buttery settle (the v1 stutter
+came from letting every input path write `x` directly).
+
+**Wheel is Lenis-safe.** While the rail can still move in that direction the
+event gets `preventDefault` **and** `stopPropagation` (Lenis listens above us
+and would scroll the page in parallel). Once over-extended a full `edge`, the
+wheel passes through to the page — the section never traps the reader. When
+input stops, a restore force springs any overscrolled intent home while the
+lerp chases it.
+
+**Two axes.** `axis: "auto"` re-resolves on every measure (only the column
+overflows → vertical) and re-keys the transform on a flip instead of leaving
+the stale axis behind — resize across the breakpoint and the rail just
+follows. **vs `glRail`**: the identical physics runs beneath `glRail`'s
+WebGL overlay (bent cards + grid floor, `/three` subpath) — use plain
+`dragRail` for DOM media, `glRail` when the pictures should curve.
+
+**DOM:** same shape as `dragStrip` — `overflow: hidden` viewport, flex track
+of `width: max-content`; the effect sets inline `cursor` / `user-select` /
+`touch-action` and clears them plus the transform/tilt on `destroy()`. Feed
+`onTick(pos, velocity)` a shader or skew effect to drive along with the rail.
+
 #### `audioBars(target, options?) => handle`
 
 Equaliser visualiser — returns `{ start, stop, destroy }`.
@@ -1126,6 +1364,7 @@ destroy on teardown. Route changes and HMR are why `destroy()` exists.
 ```bash
 npm run build     # tsc → dist/ (ESM + .d.ts) + CSS copy + tsup standalone bundle
 npm run demo      # static server on http://localhost:4321/demo/
+npm run sync:live # regenerate demo_live/ (static deploy) from demo/
 npm test          # build + unit smoke + demo integration smoke
 npm run smoke     # both smokes (expects dist/ to exist)
 npm run typecheck # tsc --noEmit (what CI runs)
@@ -1136,18 +1375,24 @@ The demo page wires the whole effect set against one document —
 an on-page *copy prompt* chip (the demo smoke enforces the two-way mapping).
 (`split()` is exercised by the unit smoke instead.)
 
-Two pages share that wiring:
-
-- **`demo/index.html`** (default — `npm run demo` → `/demo/`) — import map on
-  local files (`/node_modules/...`, `/dist/index.js`): fast iteration, works
-  offline, and the page `demo-smoke` drives.
-- **`demo/anim_kit_live.html`** (`/demo/anim_kit_live.html`) — byte-for-byte
-  the same page wired to the **version-pinned CDN** (jsdelivr `@<version>` for
-  the package, `gsap@3.15.0`, `lenis@1.3.26`): the exact path visitors copy
-  from the prompts and docs, so CDN wiring gets the same manual QA as the
-  local build. `demo-smoke` fails if the two files drift apart or the pin
-  stops matching the release version, and the page only loads once that
-  version is published to npm.
+Two trees share that wiring:
+
+- **`demo/`** (default — `npm run demo` → `/demo/`) — import map on local
+  files (`/node_modules/...`, `/dist/index.js`): fast iteration, works
+  offline, and the pages `demo-smoke` drives.
+- **`demo_live/`** (`npm run sync:live` regenerates it from `demo/`) — a
+  deploy-anywhere copy: the **version-pinned CDN** import map and stylesheet
+  (jsdelivr `@<version>` for the package — the `/three` subpath included —
+  plus `three@0.186.1`, `gsap@3.15.0`, `lenis@1.3.26`: the exact URLs the
+  prompts teach), a byte-copied `assets/` folder, relative internal links, a
+  generated
+  `prompts.json`, and agent crawler files (`robots.txt`, `sitemap.xml`,
+  `llms.txt` with absolute URLs from `SITE_URL`), so the dock and docs run on
+  any static host with no Node server (`/api/prompts` first, `prompts.json`
+  fallback) and agents reach the full catalogue in one fetch instead of
+  scraping HTML. Upload the folder as-is (Vercel, GitHub Pages, Netlify, S3).
+  `demo-smoke` re-runs the generator and fails if the folder goes stale or a
+  pin stops matching the release version.
 
 ### Copy-prompt API
 
@@ -1174,7 +1419,7 @@ and slotting the effect into a subcategory.
 **Unit smoke** (`scripts/smoke.mjs`) runs the built bundle in **jsdom** and
 asserts:
 
-1. all 45 exports are present;
+1. all 47 exports are present;
 2. plugins (`ScrollTrigger`, `SplitText`, `Draggable`, `CustomEase`,
    `Flip`, `ScrollSmoother`) and the 4 custom eases are registered;
 3. every effect no-ops safely on missing targets;
@@ -1219,7 +1464,7 @@ anim-kit/
 │  │  └─ types.ts          TargetLike / Destroy / CommonOptions
 │  ├─ effects/             one file per effect (24 files, 28 effect functions)
 │  ├─ styles/anim-kit.css  companion stylesheet
-│  └─ index.ts             barrel — 45 exports
+│  └─ index.ts             barrel — 47 exports
 ├─ demo/                   visual demo (import map, no bundler)
 ├─ scripts/
 │  ├─ serve.mjs            static server + /api/prompts (:4321)
@@ -1250,8 +1495,7 @@ Each effect is an independent module — if you only need the marquee, import
 
 ## Credits
 
-Effects extracted and reimplemented from the animation patterns of
-[dzinrstudio.com](https://dzinrstudio.com/). Built on
+Effects by [kalakritico.in](https://kalakritico.in/). Built on
 [GSAP](https://gsap.com/) (free plugins only) and
 [Lenis](https://lenis.darkroom.engineering/).