@cosmictraveler002/anim-kit 1.1.0 → 1.3.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 — 43 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.1.0` always resolves to exactly that build, forever
+immutable, so `@cosmictraveler002/anim-kit@1.3.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.1.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.3.0/dist/styles/anim-kit.css" />
 
 <script type="module">
   import {
     smoothScroll, lineReveal, marquee,
-  } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.1.0/dist/anim-kit.standalone.js";
+  } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.3.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.1.0/dist/anim-kit.standalone.js`
+unpkg serves the same file: `https://unpkg.com/@cosmictraveler002/anim-kit@1.3.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.1.0/+esm";
+  import { lineReveal } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.3.0/+esm";
 </script>
 ```
 
@@ -142,17 +143,20 @@ 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.1.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.3.0/dist/styles/anim-kit.css" />
 
 <script type="importmap">
   {
     "imports": {
-      "@cosmictraveler002/anim-kit": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.1.0/dist/index.js",
+      "@cosmictraveler002/anim-kit": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.3.0/dist/index.js",
+      "@cosmictraveler002/anim-kit/three": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.3.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",
       "gsap/Draggable": "https://cdn.jsdelivr.net/npm/gsap@3.15.0/Draggable.js",
       "gsap/CustomEase": "https://cdn.jsdelivr.net/npm/gsap@3.15.0/CustomEase.js",
+      "gsap/Flip": "https://cdn.jsdelivr.net/npm/gsap@3.15.0/Flip.js",
       "gsap/ScrollSmoother": "https://cdn.jsdelivr.net/npm/gsap@3.15.0/ScrollSmoother.js",
       "lenis": "https://cdn.jsdelivr.net/npm/lenis@1.3.26/dist/lenis.mjs"
     }
@@ -166,12 +170,42 @@ the rest of your page:
 </script>
 ```
 
-Swap the host for unpkg (`https://unpkg.com/@cosmictraveler002/anim-kit@1.1.0/dist/index.js`, …) —
+Swap the host for unpkg (`https://unpkg.com/@cosmictraveler002/anim-kit@1.3.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
@@ -279,17 +313,20 @@ 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` |
 | 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` |
+| Buttons & links | Magnetic hover | `magnetic` |
 | Navigation & overlays | Menus & nav | `navHide`, `menuOverlay` |
 | Navigation & overlays | Cursors | `cursorFollower` |
 | Intros & transitions | Preloaders | `preloader` |
@@ -310,7 +347,7 @@ that does not exist.
 #### `initGSAP()`
 
 Registers the plugins anim-kit relies on (`ScrollTrigger`, `SplitText`,
-`Draggable`, `CustomEase`, `ScrollSmoother`) and the studio's custom eases.
+`Draggable`, `CustomEase`, `Flip`, `ScrollSmoother`) and the studio's custom eases.
 Idempotent; called for you by every effect.
 
 #### `EASES`
@@ -349,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.
+decode reveals, rolling words and reels, tickers, layout transfers.
 
 #### `lineReveal(target, options?) => destroy`
 
@@ -478,6 +515,73 @@ 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
+they stood — the FLIP technique: a column of words fans out into a row,
+driven by scroll progress or played once.
+
+```ts
+// Both blocks share one grid cell so the stage never reflows mid-flight:
+flipWords("[data-flip-from]", { to: "[data-flip-to]", scrub: 0.6 });
+
+// One-shot on enter (reverses on leave-back), or immediately:
+flipWords("[data-flip-from]", { to: "[data-flip-to]", mode: "scroll" });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `to` | — (required) | destination block; every word is moved into it |
+| `words` | source children | `[data-flip-word]` matches, else the source's element children |
+| `duration` | `1.4` | seconds for one word's travel |
+| `ease` | `"power4.inOut"` | GSAP ease |
+| `stagger` | `0.2` | seconds between word starts |
+| `scale` | `0.2` | mid-flight squash each word pops through (`0` disables) |
+| `mode` | `"scroll"` | or `"immediate"` to play at once |
+| `scrub` | unset | number = scrub smoothing seconds, `true` = immediate |
+| `start / end` | `"top 75%"` / `"bottom 45%"` | ScrollTrigger positions |
+
+**DOM:** put the source and destination blocks in the same grid cell
+(`grid-area: 1 / 1`, a `min-height` on both keeps the stage stable). The words
+live in the destination from init but render at their source positions until
+the timeline runs, so scrubbing reverses perfectly. `destroy()` kills the
+timeline, puts every word back in its original parent and restores the
+inline transform.
+
 #### `counter(target, options?) => destroy`
 
 Tabular number ticker.
@@ -545,23 +649,28 @@ as authored.
 
 #### `clipWipe(target, options?) => destroy`
 
-A `clip-path: inset()` reveal: the element is collapsed behind one edge (or
-inside a frame margin) and the inset animates to zero so it wipes into view.
+A `clip-path: inset()` reveal: the element is collapsed behind one edge,
+corner (or inside a frame margin) and the inset animates to zero so it wipes
+into view.
 
 ```ts
 clipWipe("[data-clip]", { from: "left" });                    // inset(0 100% 0 0) → 0
 clipWipe("[data-frame]", { from: "frame", inset: 12 });       // opens out of a frame
+clipWipe("[data-corner]", { from: "bottom-right" });          // opens toward the opposite corner
+clipWipe("[data-scrub]", { from: "frame", scrub: 0.5 });      // bound to scroll progress
 ```
 
 | Option | Default | Notes |
 | --- | --- | --- |
-| `from` | `"left"` | `"left"` / `"right"` / `"top"` / `"bottom"` / `"frame"` |
+| `from` | `"left"` | `"left"` / `"right"` / `"top"` / `"bottom"`, a corner (`"top-left"` / `"top-right"` / `"bottom-left"` / `"bottom-right"`), or `"frame"` |
 | `inset` | `15` | frame margin in % (`from: "frame"`) |
 | `duration` | `1` | seconds |
 | `ease` | `"power3.out"` | GSAP ease |
 | `stagger` | `0.08` | seconds between targets |
 | `mode` | `"scroll"` | or `"immediate"` to play at once |
 | `start` | `"top 85%"` | ScrollTrigger start |
+| `end` | `"top 20%"` | ScrollTrigger end (scrub mode) |
+| `scrub` | unset | number = scrub smoothing seconds, `true` = immediate: tie the wipe to scroll progress |
 | `replay` | `false` | re-wipe when leaving / re-entering |
 
 Works on images, video, blocks and text. `destroy()` removes the inline
@@ -660,7 +769,8 @@ heroShrink("[data-hero-media]", { offsetY: "49vh", scale: 0.23, scrub: 1 });
 
 Images and video that arrive slightly oversized and ease down to size as the
 section enters — content lands instead of popping in. Set `scrub` to bind the
-settle to scroll progress instead of playing it once.
+settle to scroll progress, or `replay: true` to reverse back to `from` on
+leave-back and replay on every re-enter.
 
 ```ts
 mediaSettle("[data-settle]", { from: 1.15, duration: 1.5 });  // on enter
@@ -677,6 +787,7 @@ mediaSettle("[data-settle-scrub]", { scrub: 0.5, from: 1.2 }); // scroll-bound
 | `mode` | `"scroll"` | or `"immediate"` to play at once |
 | `start` / `end` | `"top 75%"` / `"bottom top"` | ScrollTrigger positions |
 | `scrub` | unset | number = scrub smoothing seconds, `true` = immediate |
+| `replay` | `false` | re-settle when leaving / re-entering (enter mode) |
 
 `destroy()` clears `transform` — media returns to its authored scale. Unlike
 `heroShrink()` (which scrubs media down as it *leaves*), `mediaSettle()` plays
@@ -684,9 +795,63 @@ 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.
+
+---
+
 ### Loops & marquees
 
-Continuous motion — marquees, infinite draggables, equaliser bars.
+Continuous motion — marquees, draggable rails, equaliser bars.
 
 #### `marquee(track, options?) => destroy`
 
@@ -755,6 +920,50 @@ 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.
+
+```ts
+dragRail("[data-rail]", { tilt: 0.05, throwScale: 14, wheel: true });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `viewport` | track's parent | scroll viewport around the track |
+| `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.
+
+**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 }`.
@@ -774,7 +983,7 @@ would rewrite `height` *after* teardown) and clears the inline height.
 
 ### Buttons & links
 
-Hover affordances for CTAs and inline links.
+Hover affordances for CTAs and inline links — fills, underlines, magnetic pulls.
 
 #### `liquidButton(target, options?) => destroy`
 
@@ -818,6 +1027,29 @@ Pure CSS under the hood — it just adds/removes the `.ak-underline` class whose
 `::after` sweep is styled by the companion stylesheet, and `destroy()` removes
 the class again.
 
+#### `magnetic(target, options?) => destroy`
+
+Buttons and links that lean toward the pointer while hovered — following a
+fraction of the pull with a tilt — then spring back to rest with an elastic
+snap on leave.
+
+```ts
+magnetic("[data-magnet]", { strength: 0.5, rotation: 10, scale: 1.04 });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `strength` | `0.4` | how far the element follows the pointer — fraction of its own box |
+| `rotation` | `8` | max tilt in degrees at full pull (`0` disables) |
+| `scale` | `1` | scale held while the pointer is over the element (`1` = none) |
+| `duration` | `1.2` | spring-back duration, seconds |
+| `ease` | `"elastic.out(1, 0.35)"` | spring-back ease |
+
+**DOM:** pass a list (selector, array, NodeList) — each element gets its own
+listeners and its own pull. Keep CSS transitions off `transform` for magnetic
+elements (GSAP animates transform directly). `destroy()` removes the
+listeners, kills in-flight tweens and restores the inline transform.
+
 ---
 
 ### Navigation & overlays
@@ -861,7 +1093,12 @@ Curtain uses `EASES.curtain` (`.76,0,.24,1`).
 
 #### `cursorFollower(zone, options?) => destroy`
 
-Spring-followed cursor tag, e.g. "▶ Play Showreel" over a video.
+Spring-followed cursor tag, e.g. "▶ Play Showreel" over a video. The tag is
+pinned `position: fixed` and driven in viewport space (`clientX/Y + offset`),
+so it can live anywhere in the DOM — it only reacts while the pointer is over
+the zone. Style it with `opacity: 0` and light text (`color: #fff`): the
+`exclusion` blend inverts the tag against whatever is behind it, which only
+reads with a light source colour.
 
 ```ts
 cursorFollower("[data-showreel]", {
@@ -1055,22 +1292,43 @@ 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)
 ```
 
 The demo page wires the whole effect set against one document —
-`demo/index.html` + `demo/demo.js`. (`stackedCardsPinned`, the
-sibling-viewport variant, plus `split()` are exercised by the unit smoke
-instead.)
+`demo/index.html` + `demo/demo.js` — and every effect in the catalogue has
+an on-page *copy prompt* chip (the demo smoke enforces the two-way mapping).
+(`split()` is exercised by the unit smoke instead.)
+
+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
 
 The demo server doubles as a **prompt server**: every effect has a ready-to-
-paste *"how to implement this with anim-kit"* prompt — markup, import, CDN
-usage (version-pinned, no build step), initialisation call, options table,
-teardown and gotchas:
+paste *"how to implement this with anim-kit"* prompt — markup, a numbered
+copy-paste procedure that runs straight from the version-pinned CDN (no
+build step, plus the npm import for bundlers), initialisation call, options
+table, teardown and gotchas:
 
 ```bash
 curl http://localhost:4321/api/prompts          # { count, categories, prompts: [{ id, title, summary, category, subcategory, text }] }
@@ -1078,7 +1336,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 (27)** button at the bottom right opens the full
+floating **⧉ prompts (29)** 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`:
@@ -1089,11 +1347,11 @@ and slotting the effect into a subcategory.
 **Unit smoke** (`scripts/smoke.mjs`) runs the built bundle in **jsdom** and
 asserts:
 
-1. all 43 exports are present;
+1. all 47 exports are present;
 2. plugins (`ScrollTrigger`, `SplitText`, `Draggable`, `CustomEase`,
-   `ScrollSmoother`) and the 4 custom eases are registered;
+   `Flip`, `ScrollSmoother`) and the 4 custom eases are registered;
 3. every effect no-ops safely on missing targets;
-4. 22 effects mount on real markup and unmount cleanly;
+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
    with `split: "chars"`) and restores markup on destroy;
@@ -1132,9 +1390,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 (22 files, 26 effect functions)
+│  ├─ effects/             one file per effect (24 files, 28 effect functions)
 │  ├─ styles/anim-kit.css  companion stylesheet
-│  └─ index.ts             barrel — 43 exports
+│  └─ index.ts             barrel — 47 exports
 ├─ demo/                   visual demo (import map, no bundler)
 ├─ scripts/
 │  ├─ serve.mjs            static server + /api/prompts (:4321)
@@ -1165,8 +1423,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/).