@cosmictraveler002/anim-kit 1.4.0 → 1.6.0

package/README.md

@@ -30,6 +30,7 @@ destroy();
   - [Core](#core)
   - [Text animations](#text-animations)
   - [Scroll & media](#scroll--media)
+  - [WebGL](#webgl)
   - [Loops & marquees](#loops--marquees)
   - [Buttons & links](#buttons--links)
   - [Navigation & overlays](#navigation--overlays)
@@ -78,7 +79,7 @@ inside the published tarball):
 
 | Specifier | Resolves to | Use for |
 |---|---|---|
-| `@cosmictraveler002/anim-kit` | `dist/index.js` + `dist/index.d.ts` | the full barrel — 47 exports |
+| `@cosmictraveler002/anim-kit` | `dist/index.js` + `dist/index.d.ts` | the full barrel — 48 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 |
@@ -98,7 +99,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.4.0` always resolves to exactly that build, forever
+immutable, so `@cosmictraveler002/anim-kit@1.6.0` always resolves to exactly that build, forever
 (only a new version creates a new URL; nothing floats unless you ask for a
 range).
 
@@ -109,12 +110,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.4.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.6.0/dist/styles/anim-kit.css" />
 
 <script type="module">
   import {
     smoothScroll, lineReveal, marquee,
-  } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/dist/anim-kit.standalone.js";
+  } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.6.0/dist/anim-kit.standalone.js";
 
   smoothScroll();
   lineReveal("[data-lines]", { mode: "scroll" });
@@ -122,7 +123,7 @@ identically on jsDelivr and unpkg:
 </script>
 ```
 
-unpkg serves the same file: `https://unpkg.com/@cosmictraveler002/anim-kit@1.4.0/dist/anim-kit.standalone.js`
+unpkg serves the same file: `https://unpkg.com/@cosmictraveler002/anim-kit@1.6.0/dist/anim-kit.standalone.js`
 
 ### Option 2 — jsDelivr `+esm`
 
@@ -131,7 +132,7 @@ per version):
 
 ```html
 <script type="module">
-  import { lineReveal } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.4.0/+esm";
+  import { lineReveal } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.6.0/+esm";
 </script>
 ```
 
@@ -143,13 +144,13 @@ 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.4.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.6.0/dist/styles/anim-kit.css" />
 
 <script type="importmap">
   {
     "imports": {
-      "@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",
+      "@cosmictraveler002/anim-kit": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.6.0/dist/index.js",
+      "@cosmictraveler002/anim-kit/three": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.6.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",
@@ -170,7 +171,7 @@ the rest of your page:
 </script>
 ```
 
-Swap the host for unpkg (`https://unpkg.com/@cosmictraveler002/anim-kit@1.4.0/dist/index.js`, …) —
+Swap the host for unpkg (`https://unpkg.com/@cosmictraveler002/anim-kit@1.6.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
@@ -276,8 +277,12 @@ configured before first paint.
 ## Smooth scroll
 
 Lenis is wired to ScrollTrigger the canonical way: Lenis drives the scroll,
-`lenis.on("scroll", ScrollTrigger.update)` keeps triggers in sync, `lenis.raf`
-is ticked from `gsap.ticker`, and `lagSmoothing(0)` is disabled.
+`lenis.on("scroll", ScrollTrigger.update)` keeps triggers in sync, and
+`lenis.raf` is ticked from `gsap.ticker` so scroll and tweens run off one
+clock. GSAP's lag smoothing stays **on**: ticker listeners receive the same
+adjusted clock the tweens use, so 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 in a single jump.
 
 ```ts
 const scroller = smoothScroll({
@@ -287,6 +292,11 @@ const scroller = smoothScroll({
   orientation: "vertical",
   initialScroll: 0,
   useScrollerProxy: false, // opt-in scrollerProxy for nested scrollers
+  touchMultiplier: 1,  // touch-drag sensitivity (Lenis default 1)
+  wheelMultiplier: 1,  // mouse-wheel sensitivity (Lenis default 1)
+  // Lag smoothing: leave unset for GSAP's built-in 500ms → 33ms compensation,
+  // false to disable it (the old behaviour), or retune for short hitches:
+  lagSmoothing: { threshold: 150 },
 });
 
 scroller.scrollTo("#work", { duration: 1.2 }); // programmatic, smoothed
@@ -320,7 +330,9 @@ prompt dock, and backs the `category` / `subcategory` fields on
 | Scroll & media | Parallax & depth | `parallax` |
 | Scroll & media | Heroes & media | `heroShrink`, `mediaSettle` |
 | Scroll & media | Enter reveals | `revealRule`, `unfoldReveal`, `clipWipe` |
-| WebGL | Shader media | `webglMedia`, `glRail` |
+| WebGL | Shader media | `webglMedia`, `glRail`, `coverflowWheel` |
+| WebGL | Scenes & overlays | `tearReveal`, `ditherReveal` |
+| WebGL | Kinetic type | `wordmarkWave` |
 | Loops & marquees | Marquees | `marquee` |
 | Loops & marquees | Draggables & rails | `dragStrip`, `dragRail` |
 | Loops & marquees | Equalizers | `audioBars` |
@@ -331,6 +343,7 @@ prompt dock, and backs the `category` / `subcategory` fields on
 | Navigation & overlays | Cursors | `cursorFollower` |
 | Intros & transitions | Preloaders | `preloader` |
 | Intros & transitions | Theme wipes | `themeReveal` |
+| Intros & transitions | Page transitions | `inkWipe` |
 | Logos & SVG | Path reveals | `logoReveal` |
 
 **Growing the library:** a subcategory is the slot sibling effects land in —
@@ -797,7 +810,8 @@ the entrance.
 
 ### WebGL
 
-GPU media — three.js re-renders your images as shader cards. This is the only
+GPU media — three.js re-renders your content as shader cards, kinetic type
+and reveal scenes. 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.
@@ -911,6 +925,183 @@ user-select: none`.
 
 ---
 
+#### `coverflowWheel(target, options?) => handle`
+
+Media cards on a flattened vertical wheel: each card bends along the arc in
+the vertex shader instead of staying a rigid plane, fronts face you bright
+while the backs show mirrored, one mip blurrier and half-lit, and the strip
+dissolves into the floor below instead of ending on a hard edge. Drag to
+scrub — a release within 5 % of a slot commits to the neighbouring card,
+smaller drags spring back — and while idle the wheel creeps a slot's lead-in
+and then advances on its own.
+
+```ts
+import { coverflowWheel } from "@cosmictraveler002/anim-kit/three";
+
+const wheel = coverflowWheel("#deck", { idle: 5 });
+wheel.goTo(3); // jump to a card (wraps)
+wheel.next(); // one card on, 0.5 s
+wheel.destroy();
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `index` | `0` | first card on show (wraps) |
+| `autoplay` / `idle` | `true` / `5` | idle advance — seconds of stillness (with a 1/8-slot lead-in creep) |
+| `duration` | `1.15` | `goTo()` tween, seconds (`next()` / `prev()` use 0.5) |
+| `margin` | `0.1` | gap between cards, as a fraction of one slot |
+| `dpr` | `2` | device-pixel-ratio cap |
+
+Cards are the host's own `<img>`s — cover-cropped into textures at mount (a
+failed decode drops that card; fewer than two survivors → inert) and restored
+from their inline opacity on teardown. Pointer capture keeps the drag over the
+deck wherever the pointer is and native image-dragging is blocked so a card
+never swallows the stream; the host claims `cursor: grab` + `touch-action:
+pan-y` and a `data-ak-coverflow` stamp, all restored by `destroy()`. Card
+backs reuse the front texture (mirrored, half light, bottom-faded in-shader) —
+no second texture, no extra pass.
+
+**Silent no-op ladder.** Missing target → inert handle; no
+`WebGLRenderingContext` (SSR, jsdom, WebGL disabled) → inert *before* any
+context probe; renderer refused → inert; reduced motion → inert, nothing
+mounts. Every call on an inert handle is a safe no-op — nothing ever logs.
+`destroy()` kills the tween + ticker, disconnects the observers, removes the
+canvas and restores the images, host styles and dataset.
+
+---
+
+#### `tearReveal(target, options?) => destroy`
+
+A torn-edge sheet that sweeps a section in (or out): a noise-displaced
+boundary travels across the overlay — the fbm joins the field *before*
+thresholding, so patches tear away ahead of the front and ride across as
+separate shards — while a barrel warp bows the edge into an arriving curve
+instead of a straight line wobbling in place.
+
+```ts
+tearReveal("[data-tear]", {
+  color: ["#ff8a1e", "#ff5252"], // [foot, top] gradient stops (or one colour)
+  blend: "multiply",             // tint the section instead of covering it
+  direction: "up",               // up | down | left | right
+  mode: "scroll",                // play on enter — or "immediate"
+  duration: 1,                   // seconds for the timed run
+});
+// …or bind it to scroll instead:
+tearReveal("[data-tall]", { scrub: 0.4, start: "top 90%", end: "top 30%" });
+tearReveal(document.body, { fixed: true }); // page-sized sweep over the viewport
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `color` | `"#111111"` | one colour or `[foot, top]` gradient stops |
+| `blend` | `"none"` | CSS `mix-blend-mode` — `multiply` tints what is under the sheet |
+| `direction` | `"up"` | `up` / `down` / `left` / `right` |
+| `dispAmp` / `dispScale` / `dispDetail` / `dispDrift` | `0.175` / `12.2` / `5` / `0` | tear shape — how far, how big, how gritty, how fast it crawls |
+| `soft` | `0.001` | threshold half-width — small keeps shards crisp |
+| `lens` | `-0.275` | barrel warp — negative bows the middle of the boundary up |
+| `duration` / `ease` | `1` / `"power2.inOut"` | timed run (`mode: "scroll"` or `"immediate"`) |
+| `scrub` | — | smoothing seconds (or `true`) — progress follows the scroll, both ways |
+| `start` / `end` | `"top 85%"` / `"top 25%"` | ScrollTrigger positions |
+| `replay` | `false` | re-run on every viewport entry |
+| `fixed` / `z` / `dpr` | `false` / `1` / `2` | viewport-sized canvas, stacking, pixel-ratio cap |
+
+Both ends of the travel are **sealed**: the displaced boundary reaches the
+far side with its deepest tear at exactly zero, so the last half-covered
+pixels never read as speckle or leftover haze.
+
+**Silent no-op ladder.** Missing target → no-op; no `WebGLRenderingContext`
+(SSR, jsdom, WebGL disabled) → no-op *before* any context probe; renderer
+refused → no-op; reduced motion → nothing mounts. Nothing ever logs.
+`destroy()` kills the tween + ScrollTrigger, removes the canvas and restores
+the host's styles.
+
+**DOM.** `position: relative; overflow: hidden` on the target — or skip the
+target box entirely with `fixed: true` for a page-sized sweep.
+
+---
+
+#### `ditherReveal(target, options?) => destroy`
+
+A photo punches through its placeholder in a hard-edged, fbm-speckled ring
+expanding from the centre outward — no soft dissolve, no crossfade: every
+pixel on the boundary flips between hole and not-hole. The noise spread
+ramps to zero at both ends of the travel, so progress 0 is exactly empty
+and progress 1 exactly solid.
+
+```ts
+ditherReveal("[data-reveal]", {
+  plate: "#14140f", // flat placeholder where the mask has not opened yet
+  duration: 1.15,   // seconds, ease "power4.out"
+  maskScale: 50,    // fbm frequency across the element — lump scale of the edge
+  hard: true,       // the signature speckle (false = a soft dissolve)
+  play: "visible",  // fire on first viewport entry ("load" = when the texture decodes)
+});
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `src` | first `<img>` | image source override when the wrapper has no image |
+| `duration` / `ease` | `1.15` / `"power4.out"` | the reveal clock |
+| `plate` | — | flat placeholder colour (omit → the wrapper's own background shows through) |
+| `maskScale` / `spread` / `detail` | `50` / `0.35` / `4` | edge shape — frequency, reach, fbm octaves |
+| `hard` | `true` | hard speckle vs soft dissolve |
+| `play` | `"visible"` | `"visible"` fires on first viewport entry, `"load"` on texture decode |
+| `dpr` | `2` | device-pixel-ratio cap |
+
+The `<img>` keeps layout and alt text: the canvas covers the wrapper and
+only takes over its pixels once the texture has decoded — with a plate the
+placeholder covers from load, without one the image only steps aside when
+the reveal actually starts. The cover-crop runs in-shader (`object-fit:
+cover` maths), so any source aspect fills any card aspect.
+
+**Silent no-op ladder.** Missing target → no-op; no `WebGLRenderingContext`
+(SSR, jsdom, WebGL disabled) → no-op *before* any context probe; renderer
+refused → no-op; texture 404 → the plain `<img>` stays untouched; reduced
+motion → the canvas never mounts and the static image is the resting state.
+Nothing ever logs. `destroy()` kills the tween + observers, disposes
+geometry/material/texture/renderer, removes the canvas and restores the
+image opacity and wrapper position.
+
+---
+
+#### `wordmarkWave(target, options?) => destroy`
+
+The target's own headline rendered to a texture and simulated as a spring
+lattice: the pointer shears the letters like thick liquid, red and cyan split
+out of the colour while the surface deforms, and every vertex springs back to
+exact rest. Text, font and colour come from the element itself — nothing to
+export, nothing to align.
+
+```ts
+import { wordmarkWave } from "@cosmictraveler002/anim-kit/three";
+
+const destroy = wordmarkWave("#mark", {
+  drag: 1, // pointer-velocity term — how hard the letters smear
+  push: 0, // radial push — vertices flee the cursor while it sits still
+  chroma: true, // red/cyan fringes while deforming
+});
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `text` / `font` / `color` | target's own | override what is drawn (the host's colour is hidden while mounted) |
+| `outline` / `tracking` | `0` / `0` | stroke width, px (0 = filled) and extra letter spacing, px |
+| `drag` / `push` | `1` / `0` | pointer-velocity and radial-push terms of the simulation |
+| `chroma` | `true` | red/cyan chromatic split while deforming |
+| `segments` | `0` | grid columns — auto (≈10 px cells, ~5 k vertices) |
+| `opacity` / `z` / `dpr` | `1` / `1` / `2` | canvas opacity, stacking order, pixel-ratio cap |
+
+The simulation steps at a fixed 60 Hz (max 4 steps per frame; a gap over
+0.2 s counts as one step) so a backgrounded tab resumes where it left instead
+of exploding, and the ticker idles while the host is off-screen. **Silent
+no-op ladder**: missing target → no-op; no `WebGLRenderingContext` (SSR,
+jsdom, WebGL disabled) → no-op *before* any context probe; renderer refused →
+no-op; reduced motion → nothing mounts, the real text simply stays. Nothing
+ever logs. `destroy()` stops the ticker + observers, disposes the renderer,
+removes the canvas and restores the host colour it hid.
+
+---
+
 ### Loops & marquees
 
 Continuous motion — marquees, draggable rails, equaliser bars.
@@ -1236,6 +1427,46 @@ theme.set("dark"); theme.toggle(); theme.current(); theme.destroy();
 
 ---
 
+#### `inkWipe(options?) => handle`
+
+A brush-loaded ink sheet sweeps across the whole page: `cover()` paints it
+over, the swap happens at full cover, `unveil()` lets the new page arrive
+behind the *same* stroke — one continuous left→right travel whose edge is
+seeded, so it never boils between frames. Bristle spurs and flecks run
+ahead of the front.
+
+```ts
+const wipe = inkWipe({ links: "[data-wipe]" }); // intercepts links; next page auto-unveils
+
+await wipe.cover();   // resolves at full cover — swap your DOM here
+await wipe.unveil();  // the new page arrives behind the same stroke
+wipe.destroy();
+
+// Options-object form or target-first form both work:
+inkWipe({ host: "#overlay", color: "#111" });
+inkWipe(document.body, { coverMs: 700 });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `host` | `document.body` | overlay host the canvas is appended to (target arg also works) |
+| `color` | `"#0b0b0b"` | ink colour |
+| `coverMs` / `unveilMs` | `550` / `650` | sweep durations |
+| `ease` | `"power2.inOut"` | GSAP ease for both halves |
+| `tilt` / `rough` / `bristle` | `0.35` / `44` / `180` | edge lean (× height), noise amplitude px, longest spur px |
+| `links` | — | selectors intercepted — a click runs the wipe before navigating |
+| `sessionKey` / `autoUnveil` | `"ak-ink-wipe"` / `true` | cross-page handoff flag + the page-load unveil |
+| `z` | `9998` | overlay z-index |
+
+**The MPA handoff** is a sessionStorage flag: a covered navigation stores
+`sessionKey`, the next page reads it, covers instantly and unveils — no
+flash between documents. Reduced motion snaps both halves instantly to a
+solid sheet, so navigation still never flashes the swap; without a 2D
+context (SSR, jsdom) both promises resolve immediately and nothing paints.
+`destroy()` removes the canvas, its listeners and the link interception.
+
+---
+
 ### Logos & SVG
 
 Vector reveals for brand marks.
@@ -1408,7 +1639,7 @@ curl http://localhost:4321/api/prompts/marquee  # one prompt, text/plain
 ```
 
 On the page, every labelled section carries a **copy prompt** chip, and the
-floating **⧉ prompts (29)** button at the bottom right opens the full
+floating **⧉ prompts (38)** button at the bottom right opens the full
 catalogue grouped by [effect category](#effect-categories) — one click copies
 an effect's prompt (the prompt states its category), *copy all* puts the
 entire set on the clipboard. The catalogue lives in `scripts/prompts.mjs`:
@@ -1419,17 +1650,19 @@ and slotting the effect into a subcategory.
 **Unit smoke** (`scripts/smoke.mjs`) runs the built bundle in **jsdom** and
 asserts:
 
-1. all 47 exports are present;
+1. all 48 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;
-4. 24 effects mount on real markup and unmount cleanly;
-5. `preloader` ticks in both the positional and options-object call forms;
-6. `lineReveal` actually splits into masked lines (and per-character masks
+4. 27 effects mount on real markup and unmount cleanly;
+5. pinning effects claim `refreshPriority: 1`, so ScrollTrigger refresh
+   measures in document order (root README bug class E);
+6. `preloader` ticks in both the positional and options-object call forms;
+7. `lineReveal` actually splits into masked lines (and per-character masks
    with `split: "chars"`) and restores markup on destroy;
-7. `scrambleText` restores its text, `rollText` wraps/unwraps its rows, and
+8. `scrambleText` restores its text, `rollText` wraps/unwraps its rows, and
    `counter({ progress: true })` renders a scrubbed readout;
-8. `utils`, `compose` and `guard` behave per contract.
+9. `utils`, `compose` and `guard` behave per contract.
 
 **Demo smoke** (`scripts/demo-smoke.mjs`) loads the real `demo/index.html` and
 executes the real `demo/demo.js` wiring against it, then asserts the effects
@@ -1462,9 +1695,9 @@ anim-kit/
 │  │  ├─ guard.ts          reduced-motion gate
 │  │  ├─ util.ts           toArray/one/onReady/compose/raf
 │  │  └─ types.ts          TargetLike / Destroy / CommonOptions
-│  ├─ effects/             one file per effect (24 files, 28 effect functions)
+│  ├─ effects/             one file per effect (27 files, 31 effect functions)
 │  ├─ styles/anim-kit.css  companion stylesheet
-│  └─ index.ts             barrel — 47 exports
+│  └─ index.ts             barrel — 48 exports
 ├─ demo/                   visual demo (import map, no bundler)
 ├─ scripts/
 │  ├─ serve.mjs            static server + /api/prompts (:4321)