@cosmictraveler002/anim-kit 1.0.0 → 1.2.0

package/README.md

@@ -9,7 +9,7 @@ no components: every effect resolves plain DOM selectors, so it works with
 **React, Vue, Next, Svelte, Astro or plain HTML**.
 
 ```ts
-import { lineReveal, marquee, menuOverlay } from "anim-kit";
+import { lineReveal, marquee, menuOverlay } from "@cosmictraveler002/anim-kit";
 
 const destroy = lineReveal("[data-lines]", { mode: "scroll" });
 // …later (route change, HMR, teardown):
@@ -48,12 +48,12 @@ destroy();
 ## Install
 
 ```bash
-npm install anim-kit
+npm install @cosmictraveler002/anim-kit
 ```
 
 ```ts
-import { smoothScroll, horizontalScroll } from "anim-kit";
-import "anim-kit/styles";   // companion stylesheet (plain .css, optional but recommended)
+import { smoothScroll, horizontalScroll } from "@cosmictraveler002/anim-kit";
+import "@cosmictraveler002/anim-kit/styles";   // companion stylesheet (plain .css, optional but recommended)
 ```
 
 `anim-kit` ships **ESM only** with generated `.d.ts` declarations — no CJS
@@ -78,14 +78,14 @@ inside the published tarball):
 
 | Specifier | Resolves to | Use for |
 |---|---|---|
-| `anim-kit` | `dist/index.js` + `dist/index.d.ts` | the full barrel — 38 exports |
-| `anim-kit/effects/<name>` | `dist/effects/<name>.js` + `.d.ts` | one effect in isolation (`marquee`, `lineReveal`, …) |
-| `anim-kit/standalone` | `dist/anim-kit.standalone.js` (types → `index.d.ts`) | the self-contained bundle — same API |
-| `anim-kit/styles` | `dist/styles/anim-kit.css` | untouched plain CSS |
+| `@cosmictraveler002/anim-kit` | `dist/index.js` + `dist/index.d.ts` | the full barrel — 45 exports |
+| `@cosmictraveler002/anim-kit/effects/<name>` | `dist/effects/<name>.js` + `.d.ts` | one effect in isolation (`marquee`, `lineReveal`, …) |
+| `@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 |
 
 ```ts
-import { marquee } from "anim-kit/effects/marquee";  // deep import, no barrel
-import "anim-kit/styles";
+import { marquee } from "@cosmictraveler002/anim-kit/effects/marquee";  // deep import, no barrel
+import "@cosmictraveler002/anim-kit/styles";
 ```
 
 TypeScript ≥ 4.7 with `moduleResolution: "bundler"` or `"node16"`/`"nodenext"`
@@ -97,7 +97,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 `anim-kit@1.0.0` always resolves to exactly that build, forever
+immutable, so `@cosmictraveler002/anim-kit@1.2.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 +108,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/anim-kit@1.0.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/styles/anim-kit.css" />
 
 <script type="module">
   import {
     smoothScroll, lineReveal, marquee,
-  } from "https://cdn.jsdelivr.net/npm/anim-kit@1.0.0/dist/anim-kit.standalone.js";
+  } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/anim-kit.standalone.js";
 
   smoothScroll();
   lineReveal("[data-lines]", { mode: "scroll" });
@@ -121,7 +121,7 @@ identically on jsDelivr and unpkg:
 </script>
 ```
 
-unpkg serves the same file: `https://unpkg.com/anim-kit@1.0.0/dist/anim-kit.standalone.js`
+unpkg serves the same file: `https://unpkg.com/@cosmictraveler002/anim-kit@1.2.0/dist/anim-kit.standalone.js`
 
 ### Option 2 — jsDelivr `+esm`
 
@@ -130,7 +130,7 @@ per version):
 
 ```html
 <script type="module">
-  import { lineReveal } from "https://cdn.jsdelivr.net/npm/anim-kit@1.0.0/+esm";
+  import { lineReveal } from "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/+esm";
 </script>
 ```
 
@@ -142,17 +142,18 @@ 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/anim-kit@1.0.0/dist/styles/anim-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/styles/anim-kit.css" />
 
 <script type="importmap">
   {
     "imports": {
-      "anim-kit": "https://cdn.jsdelivr.net/npm/anim-kit@1.0.0/dist/index.js",
+      "@cosmictraveler002/anim-kit": "https://cdn.jsdelivr.net/npm/@cosmictraveler002/anim-kit@1.2.0/dist/index.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"
     }
@@ -160,13 +161,13 @@ the rest of your page:
 </script>
 
 <script type="module">
-  import { smoothScroll, lineReveal } from "anim-kit";
+  import { smoothScroll, lineReveal } from "@cosmictraveler002/anim-kit";
   // per-effect deep imports work here too:
-  // import { dragStrip } from "anim-kit/effects/dragStrip";
+  // import { dragStrip } from "@cosmictraveler002/anim-kit/effects/dragStrip";
 </script>
 ```
 
-Swap the host for unpkg (`https://unpkg.com/anim-kit@1.0.0/dist/index.js`, …) —
+Swap the host for unpkg (`https://unpkg.com/@cosmictraveler002/anim-kit@1.2.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
@@ -188,7 +189,7 @@ match `package-lock.json`.
 ```
 
 ```js
-import { smoothScroll, lineReveal, marquee, compose } from "anim-kit";
+import { smoothScroll, lineReveal, marquee, compose } from "@cosmictraveler002/anim-kit";
 
 const scroller = smoothScroll({ lerp: 0.08, smoothWheel: true });
 
@@ -278,16 +279,20 @@ prompt dock, and backs the `category` / `subcategory` fields on
 | Core & setup | Smooth scrolling | `smoothScroll` |
 | 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 | Counters | `counter` |
+| Text animations | Layout transfers | `flipWords` |
 | Scroll & media | Pinned galleries | `horizontalScroll`, `stackedCards`, `stackedCardsPinned` |
 | Scroll & media | Parallax & depth | `parallax` |
-| Scroll & media | Heroes & media | `heroShrink` |
-| Scroll & media | Enter reveals | `revealRule` |
+| Scroll & media | Heroes & media | `heroShrink`, `mediaSettle` |
+| Scroll & media | Enter reveals | `revealRule`, `unfoldReveal`, `clipWipe` |
 | Loops & marquees | Marquees | `marquee` |
 | Loops & marquees | Infinite draggables | `dragStrip` |
 | 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` |
@@ -308,7 +313,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`
@@ -346,7 +351,8 @@ Central reduced-motion gate. If the user prefers reduced motion and
 
 ### Text animations
 
-Typography in motion — masked lines, rising masks, per-character scatter, tickers.
+Typography in motion — masked lines, rising masks, per-character scatter,
+decode reveals, rolling words, tickers, layout transfers.
 
 #### `lineReveal(target, options?) => destroy`
 
@@ -356,12 +362,14 @@ source site.
 ```ts
 lineReveal("[data-hero-text]", { mode: "immediate", delay: 0.35 }); // above the fold
 lineReveal("[data-lines]", { mode: "scroll" });                     // reverses on leave
+lineReveal("[data-headline]", { split: "chars", stagger: 0.03 });    // per-character rise
 ```
 
 | Option    | Default         | Notes                                   |
 | --------- | --------------- | --------------------------------------- |
 | `mode`    | `"scroll"`      | `"scroll"` or `"immediate"`             |
-| `stagger` | `0.1`           | seconds between lines                   |
+| `split`   | `"lines"`       | `"lines"` or `"chars"` (per-character masked rise) |
+| `stagger` | `0.1`           | seconds between lines (`0.03` for chars) |
 | `duration`| `1`             | seconds                                 |
 | `ease`    | `"power4.out"`  |                                         |
 | `delay`   | `0`             | seconds                                 |
@@ -369,7 +377,8 @@ lineReveal("[data-lines]", { mode: "scroll" });                     // reverses
 | `end`     | `"bottom 10%"`  | ScrollTrigger end                       |
 
 **DOM:** any block of text — headings with `<br>` hard breaks work. Produces
-`.ak-line-mask > .ak-line` per line; `destroy()` restores the original HTML.
+`.ak-line-mask > .ak-line` per line (or `.ak-char-mask > .ak-char` with
+`split: "chars"`); `destroy()` restores the original HTML.
 
 #### `maskReveal(target, options?) => destroy`
 
@@ -420,6 +429,91 @@ scatterText("[data-scatter-pin]", {
 `destroy()`). Line measurement waits for `document.fonts.ready` so travel
 distance is correct with webfonts.
 
+#### `scrambleText(target, options?) => destroy`
+
+The decode / cipher reveal: each character churns through the charset and
+settles on its final glyph, left to right. Letters scramble; digits,
+punctuation and spaces stay put; case is preserved.
+
+```ts
+scrambleText("[data-scramble]");                                   // once, on enter
+scrambleText("[data-headline]", { mode: "immediate", delay: 0.2 }); // right away
+scrambleText(".nav-link", { mode: "hover", durationPerChar: 0.12 }); // on hover
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `mode` | `"scroll"` | `"scroll"` (once on enter), `"immediate"`, or `"hover"` (re-scrambles on pointerenter) |
+| `charset` | `"abcdefghijklmnopqrstuvwxyz"` | glyphs letters churn through |
+| `durationPerChar` | `0.18` | seconds each character scrambles |
+| `stagger` | `0.04` | seconds between character starts |
+| `delay` | `0` | seconds before the timeline starts |
+| `start` | `"top 80%"` | ScrollTrigger start (`mode: "scroll"`) |
+
+**DOM:** plain-text elements only — the effect rewrites `textContent` while
+scrambling and restores the original exactly on `destroy()`.
+
+#### `rollText(target, options?) => destroy`
+
+The rolling word rotator: two or more rows stacked into a hidden overflow box
+one row tall, rolling to the next on an interval. The first row is cloned at
+the end so the wrap is seamless (same trick as `marquee()`).
+
+```html
+<span class="ak-roll" data-roll>
+  <span>Design</span><span>Build</span><span>Motion</span>
+</span>
+```
+
+```ts
+rollText("[data-roll]", { interval: 2.2, duration: 0.6 });
+rollText("[data-roll-rev]", { direction: "down" }); // walk rows in reverse
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `interval` | `2.2` | seconds each row is shown (including the roll) |
+| `duration` | `0.6` | roll duration, seconds |
+| `ease` | `"power4.inOut"` | GSAP ease for the roll |
+| `direction` | `"up"` | `"up"` or `"down"` |
+
+**DOM:** rows are direct children of the target; the effect stacks them as
+blocks itself. `destroy()` unwraps the rows, removes the clone and restores
+every inline style — markup comes back byte-identical.
+
+#### `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.
@@ -428,6 +522,7 @@ Tabular number ticker.
 counter("[data-count]", { to: 240, duration: 3, suffix: "+" });
 counter("[data-count-scroll]", { to: 98, onScroll: true });          // waits for view
 counter("[data-count-pad]", { to: 42, pad: 3 });                     // 000 → 042
+counter("[data-progress]", { progress: true, pad: 2, suffix: "%" }); // scrubs 00% → 100%
 ```
 
 | Option       | Default        |
@@ -438,7 +533,8 @@ counter("[data-count-pad]", { to: 42, pad: 3 });                     // 000 →
 | `pad`        | `0` (none)     |
 | `suffix`     | `""`           |
 | `onScroll`   | `false`        |
-| `start`      | ScrollTrigger start when `onScroll` |
+| `progress`   | `false` — scrub the value from scroll progress instead of a timed tween |
+| `start` / `end` | `"top 90%"` / `"bottom top"` — ScrollTrigger positions (`end` with `progress`) |
 | `onComplete` | `(value) => {}` |
 
 ---
@@ -457,6 +553,61 @@ revealRule("[data-rule]", { duration: 1, delay: 0.2 }); // default ease: EASES.r
 
 **DOM:** any element that should animate `width: 0 → 100%` when it enters.
 
+#### `unfoldReveal(target, options?) => destroy`
+
+Blocks that grow open from an edge: `scaleY: 0 → 1` from the top (or bottom)
+for a vertical unfold, `scaleX: 0 → 1` from the left for a horizontal one —
+targets stagger together off the first match's trigger.
+
+```ts
+unfoldReveal("[data-unfold]", { axis: "y", origin: "top" });
+unfoldReveal("[data-unfold-x]", { axis: "x", origin: "left", duration: 1.2 });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `axis` | `"y"` | `"y"` → `scaleY`, `"x"` → `scaleX` |
+| `origin` | `"top"` / `"left"` | `transformOrigin`, defaults per axis |
+| `duration` | `0.7` | seconds |
+| `ease` | `"power3.out"` | GSAP ease |
+| `stagger` | `0.08` | seconds between targets |
+| `delay` | `0` | seconds |
+| `mode` | `"scroll"` | or `"immediate"` to play at once |
+| `start` | `"top 85%"` | ScrollTrigger start |
+| `replay` | `false` | re-unfold when leaving / re-entering |
+
+`destroy()` clears `transform` + `transform-origin`, so elements rest exactly
+as authored.
+
+#### `clipWipe(target, options?) => destroy`
+
+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"`, 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
+`clip-path`, restoring the authored (visible) state.
+
 #### `parallax(target, options?) => destroy`
 
 `data-speed` parallax over everything inside `target`.
@@ -546,6 +697,34 @@ heroShrink("[data-hero-media]", { offsetY: "49vh", scale: 0.23, scrub: 1 });
 // options: offsetX "0px", start "top top", end "bottom top"
 ```
 
+#### `mediaSettle(target, options?) => destroy`
+
+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, 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
+mediaSettle("[data-settle-scrub]", { scrub: 0.5, from: 1.2 }); // scroll-bound
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `from` | `1.15` | starting scale — settles down to 1 |
+| `duration` | `1.5` | seconds (enter mode) |
+| `ease` | `"power2.out"` | GSAP ease (enter mode) |
+| `origin` | `"center"` | `transformOrigin` |
+| `stagger` | `0.06` | seconds between targets |
+| `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
+the entrance.
+
 ---
 
 ### Loops & marquees
@@ -638,7 +817,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`
 
@@ -682,6 +861,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
@@ -725,7 +927,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]", {
@@ -827,14 +1034,15 @@ Types: `TargetLike`, `Destroy`, `CommonOptions`.
 ## Styling
 
 ```ts
-import "anim-kit/styles";   // → dist/styles/anim-kit.css
+import "@cosmictraveler002/anim-kit/styles";   // → dist/styles/anim-kit.css
 ```
 
 The companion stylesheet supplies:
 
 - **Design tokens:** `--ak-primary`, `--ak-curtain`, `--ak-reveal`, `--ak-out`
-- **Text masks:** `.ak-line-mask`, `.ak-line`, `.ak-word`, `.ak-space`
+- **Text masks:** `.ak-line-mask`, `.ak-line`, `.ak-char-mask`, `.ak-char`, `.ak-word`, `.ak-space`
 - **Heading masks:** `.ak-mask`, `.ak-mask__inner`
+- **Rolling text:** `.ak-roll`, `.ak-roll__inner`
 - **Liquid button:** `.ak-liquid`, `.ak-liquid__wave`, `.ak-liquid__label`
 - **Underline:** `.ak-underline`
 - **Marquee:** `.ak-marquee`, `.ak-marquee__viewport`, `.ak-marquee__track`
@@ -924,15 +1132,30 @@ 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 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.
 
 ### 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,
-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 }] }
@@ -940,7 +1163,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 (22)** 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`:
@@ -951,28 +1174,30 @@ and slotting the effect into a subcategory.
 **Unit smoke** (`scripts/smoke.mjs`) runs the built bundle in **jsdom** and
 asserts:
 
-1. all 38 exports are present;
+1. all 45 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. 16 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 restores markup on
-   destroy;
-7. `utils`, `compose` and `guard` behave per contract.
+6. `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
+   `counter({ progress: true })` renders a scrubbed readout;
+8. `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
 actually *did* something (hero split, preloader counter ticking, marquee track
 duplicated, per-call liquid directions, menu/theme/smooth-scroll handles in
-their initial state), that ~40 ScrollTriggers + a Draggable were created, that
+their initial state), that ~50 ScrollTriggers + a Draggable were created, that
 no console errors were logged, that `dragStrip` tiled its content for the
 seamless loop, that every effect referenced on the page has a `/api/prompts`
 entry, that the taxonomy classifies every effect exactly once, that the
 prompt dock renders one group per category with every effect listed once,
 and that teardown leaves **zero** live ScrollTriggers, Draggables or
 page-element tweens behind while restoring the original markup (marquee and
-drag-strip clones removed).
+drag-strip clones removed, rolling rows unwrapped, scrambled text restored).
 
 > jsdom is used deliberately: GSAP's CSSPlugin/Draggable probe element
 > style/computed values during registration, which a hand-rolled DOM stub
@@ -992,9 +1217,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 (17 files, 21 effect functions)
+│  ├─ effects/             one file per effect (24 files, 28 effect functions)
 │  ├─ styles/anim-kit.css  companion stylesheet
-│  └─ index.ts             barrel — 38 exports
+│  └─ index.ts             barrel — 45 exports
 ├─ demo/                   visual demo (import map, no bundler)
 ├─ scripts/
 │  ├─ serve.mjs            static server + /api/prompts (:4321)
@@ -1007,7 +1232,7 @@ anim-kit/
 ├─ LICENSE                 MIT
 └─ dist/                   build output
    ├─ index.js / *.d.ts    per-file ESM + declarations (tsc)
-   ├─ effects/*.js         one module per effect → anim-kit/effects/* subpaths
+   ├─ effects/*.js         one module per effect → @cosmictraveler002/anim-kit/effects/* subpaths
    ├─ anim-kit.standalone.js  self-contained CDN bundle (gsap+lenis inlined)
    └─ styles/anim-kit.css  plain CSS, copied verbatim
 ```
@@ -1019,7 +1244,7 @@ push/PR) and `.github/workflows/release.yml` (tag `v*` → `npm publish
 
 Each effect is an independent module — if you only need the marquee, import
 `marquee` and the bundler drops the rest, or deep-import
-`anim-kit/effects/marquee` to skip the barrel entirely.
+`@cosmictraveler002/anim-kit/effects/marquee` to skip the barrel entirely.
 
 ---