gclass-anims 1.0.0-beta.2 → 1.0.0-beta.21

package/Listeners.js

@@ -1,7 +1,7 @@
 import gsap from 'gsap'
-import { SpawnV, verticalmove, expandmove, magnet, magnet3d, reset, typewriter, countTargetVars } from './Animations'
-import { customAnims } from './CustomAnims'
-import { defaults, normalize } from './Config'
+import { SpawnV, verticalmove, expandmove, magnet, magnet3d, reset, typewriter, countTargetVars, stashText, scrambleVars } from './Animations.js'
+import { customAnims } from './CustomAnims.js'
+import { defaults, normalize } from './Config.js'
 import { TextPlugin, ScrollTrigger, SplitText } from 'gsap/all'
 
 // Prefix for SplitText text-reveal classes. Distinct from the raw `text-*`
@@ -30,9 +30,90 @@ export function resolveHandler(name) {
     return null
 }
 
-export default function initListeners() {
+// --- .randomize-<prop>-[min]-[max] randomization -----------------------------
+// Adds function-based values (e.g. rotation: () => gsap.utils.random(-90, 90))
+// to the FROM state of spawn tweens, so each element enters from its own pose.
+// GSAP evaluates function values on tween BUILD, and the engine always kills +
+// rebuilds tweens on replay (.scroll re-enter, .appear re-insert), so every
+// replay re-rolls automatically - no invalidate/repeatRefresh bookkeeping.
+//
+// The class is the guard: hasRandom() is a cheap className probe and nothing
+// below allocates or patches anything unless it passes, so elements without
+// .randomize-* run exactly the pre-feature code path.
+//
+// Notes:
+//   • randomize OVERRIDES the base spawn's value for that prop (a
+//     randomize-rotation on .spawn-cw replaces the spin).
+//   • A matching END value is derived per prop (scale* -> 1, opacity -> 1,
+//     transforms -> 0, ...) unless the config's own `to` already animates the
+//     prop, so a randomized prop on a spawn that doesn't natively use it still
+//     tweens back to rest instead of sticking at the rolled value.
+//   • Timeline-mediated builders (count/scramble/draw-split) construct via
+//     Timeline methods, not the exported gsap.fromTo, so they sit outside the
+//     injection - irrelevant in practice, since their props aren't randomize
+//     targets.
+const RANDOMIZE_RE = /^randomize-(\w+)-\[(-?[\d.]+)\]-\[(-?[\d.]+)\]$/
+const hasRandom = (el) => typeof el.className === "string" && /\brandomize-/.test(el.className)
+const randomVars = (el) => {
+    const rnd = {}
+    for (const c of el.classList) {
+        const m = c.match(RANDOMIZE_RE)
+        if (m) rnd[m[1]] = () => gsap.utils.random(Number(m[2]), Number(m[3]))
+    }
+    return rnd
+}
+// Resting end-state for a randomized prop (mirrors computeTo's rules).
+const randomEnds = (keys) => Object.fromEntries(keys.map((k) => [
+    k,
+    k === "opacity" ? 1
+        : k === "filter" ? "blur(0px)"
+        : k === "clipPath" ? "inset(0% 0% 0% 0%)"
+        : k === "drawSVG" ? "100%"
+        : k.startsWith("scale") ? 1
+        : 0,
+]))
+// Runs a spawn config's play(), injecting the element's .randomize-* function
+// values into every from-state the config builds. Config helpers hardcode
+// their from literals inside Animations.js, so the injection hooks the only
+// interception point available: play() builds its tweens SYNCHRONOUSLY, which
+// makes a scoped gsap.fromTo swap safe - patch, let the config construct,
+// restore in finally{}. Without .randomize-* this is a bare passthrough.
+const invokePlay = (config, el, delay, dur, ease) => {
+    if (!hasRandom(el)) return config.play(el, delay, dur, ease)
+    const rnd = randomVars(el)
+    const keys = Object.keys(rnd)
+    if (!keys.length) return config.play(el, delay, dur, ease)
+    const ends = randomEnds(keys)
+    const origFromTo = gsap.fromTo
+    gsap.fromTo = (t, from, to) => origFromTo(t, { ...from, ...rnd }, { ...ends, ...to })
+    try {
+        return config.play(el, delay, dur, ease)
+    } finally {
+        gsap.fromTo = origFromTo
+    }
+}
+
+export default function initListeners(root = document, throttlePerFrame) {
+    // overload: initListeners(1) -> throttle only, root defaults to document
+    if (typeof root === 'number') {
+        throttlePerFrame = root
+        root = document
+    }
+    throttlePerFrame = Number(throttlePerFrame) || 0 // 0 = no throttling (default)
     gsap.registerPlugin(TextPlugin, ScrollTrigger, SplitText)
 
+    // helper to scope queries to root (for boot screen: only boot-up subtree animates during boot)
+    const qAll = (sel) => {
+        if (root === document || root === document.documentElement || root === document.body) return gsap.utils.toArray(sel)
+        if (sel === "body *") return gsap.utils.toArray(root.querySelectorAll("*"))
+        try {
+            const els = [...(root.querySelectorAll ? root.querySelectorAll(sel) : [])]
+            if (root.matches?.(sel)) els.unshift(root)
+            // handle comma selectors where root itself may match one part
+            return els
+        } catch { return gsap.utils.toArray(sel) }
+    }
+
     const registeredListeners = []
         const onCompleteTweens = []
         const addListener = (el, type, fn) => {
@@ -57,19 +138,37 @@ export default function initListeners() {
 
         // `.preserve` keeps an already-rendered element (e.g. one that persists
         // in a shared layout across route changes) from being re-animated when
-        // the Listeners setup re-runs. The element is animated the first time it
-        // appears and tagged with data-gsap-preserved; on a later path change the
-        // tag survives on the persistent DOM node, so setup skips it.
-        // `.preserve` keeps an already-rendered element from being re-animated. It
-        // applies to the element AND its children: any preserved ancestor also
-        // suppresses animation on this node.
+        // the Listeners setup re-runs. It applies to the element AND its
+        // children: any preserved ancestor also suppresses animation on this
+        // node. Two subtleties make this behave correctly:
+        //   • markPreserved() tags the FULL preserve-ancestor chain, so a bare
+        //     `.preserve` container without its own spawn class (a site header,
+        //     say) still gets tagged when one of its children animates.
+        //   • Suppression requires the element ITSELF to carry data-gsap-wired
+        //     (set when a previous run animated it). Freshly mounted content
+        //     under a preserved root therefore still plays its entrance - only
+        //     DOM that survived from an earlier run stays frozen.
         const isPreserved = (el) => {
+            if (!el.dataset.gsapWired) return false
+            for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
+                if (node.classList.contains("preserve") && node.dataset.gsapPreserved) return true
+            }
+            return false
+        }
+        const markPreserved = (el) => {
+            for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
+                if (node.classList.contains("preserve")) node.dataset.gsapPreserved = "1"
+            }
+        }
+        // True when el sits inside a `.preserve` root that a run has already
+        // tagged. Such regions are frozen by design: later runs skip them, so
+        // teardown must leave their visual state untouched too.
+        const underPreservedRoot = (el) => {
             for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
                 if (node.classList.contains("preserve") && node.dataset.gsapPreserved) return true
             }
             return false
         }
-        const markPreserved = (el) => { if (el.classList.contains("preserve")) el.dataset.gsapPreserved = "1" }
 
         // `spawnConfigs` is derived from the config in Config.js (see top of
         // file). Adding/removing an entry there automatically re-wires every
@@ -126,7 +225,7 @@ export default function initListeners() {
         }
 
         // Capture the element's first (resting) bounds. A later layout change
-        // morphs from this snapshot to the live position — a vanilla FLIP.
+        // morphs from this snapshot to the live position - a vanilla FLIP.
         const captureFlip = (node) => {
             if (!node.classList?.contains("flip")) return
             const config = findSpawn(node)
@@ -277,7 +376,7 @@ export default function initListeners() {
             spawnConfigs.map(({ sel }) => "." + TEXT_PREFIX + sel.slice(1)).join(",")
 
         const getOrderDelay = (el, priority) => {
-            const samepri = gsap.utils.toArray(orderSelector())
+            const samepri = qAll(orderSelector())
                 .filter((e) => {
                     if (!e.classList.contains("order")) return false
                     const match = [...e.classList].find(p => p.startsWith("priority-"))
@@ -317,7 +416,7 @@ export default function initListeners() {
             const delay = readClassNumber(el, "complete-delay-", 0)
             const dur = readClassNumber(el, "complete-time-", 1)
             const tween = entry.play
-                ? entry.play(el, delay, dur, getEase(el))
+                ? invokePlay(entry, el, delay, dur, getEase(el))
                 : entry.build(el, readLoopCtx(el))
             if (!tween) return
             if (!entry.play) tween.delay(delay)
@@ -337,12 +436,16 @@ export default function initListeners() {
         }
 
         const scrollTriggers = []
+        // Derives the fully-visible twin of a spawn's `from` state. drawSVG is
+        // inverted relative to the numeric default: its HIDDEN value is 0%, so
+        // the drawn end state is the full stroke.
         const computeTo = (from) => {
             const to = {}
-            for (const [key] of Object.entries(from)) {
+            for (const [key] of Object.entries(from || {})) {
                 if (key === "opacity") to[key] = 1
                 else if (key === "filter") to[key] = "blur(0px)"
                 else if (key === "clipPath") to[key] = "inset(0% 0% 0% 0%)"
+                else if (key === "drawSVG") to[key] = "100%"
                 else to[key] = key.startsWith("scale") ? 1 : 0
             }
             return to
@@ -381,8 +484,8 @@ export default function initListeners() {
         // whitespace) must not become tween targets; they are kept as inert text
         // nodes so the natural gap is preserved and never animated.
         const RTL_JOIN_BREAK = /[\u200C\u200D\s]/
-        // A real Arabic/Persian joining letter. Any other visible character —
-        // Latin, digits, punctuation (، ؟ ؛ . ! …) — is NOT a joining letter: it
+        // A real Arabic/Persian joining letter. Any other visible character -
+        // Latin, digits, punctuation (، ؟ ؛ . ! …) - is NOT a joining letter: it
         // must not give the preceding letter a trailing Zero-Width-Joiner (which
         // would render it in its connecting form instead of its correct END form),
         // but it should still be split into its own span so it animates too.
@@ -471,20 +574,80 @@ export default function initListeners() {
             },
         })
 
+        // Flex targets can't be split directly: the split parts would become
+        // flex ITEMS, so justify-content/gap would apply per letter, whitespace-
+        // only text nodes stop rendering (spaces vanish) and line grouping reads
+        // garbage. Loose text runs are therefore pre-wrapped in plain block
+        // divs - real boxes with normal inline flow inside - and the wrappers
+        // are undone whenever the split reverts. Non-text children (icons etc.)
+        // stay put, keeping their own flex-item status and the gaps around them.
+        const wrapFlexTarget = (el) => {
+            if (!/^(inline-)?flex$/.test(getComputedStyle(el).display)) return null
+            const wrappers = []
+            let run = []
+            const flush = () => {
+                if (!run.length) return
+                const w = document.createElement("div")
+                el.insertBefore(w, run[0])
+                run.forEach((n) => w.appendChild(n))
+                wrappers.push(w)
+                run = []
+            }
+            ;[...el.childNodes].forEach((n) => {
+                if (n.nodeType === 3 && n.textContent.trim()) run.push(n)
+                else flush()
+            })
+            flush()
+            if (!wrappers.length) return null
+            return () => wrappers.forEach((w) => {
+                while (w.firstChild) el.insertBefore(w.firstChild, w)
+                w.remove()
+            })
+        }
+
+        // Revert a SplitText instance AND undo any flex pre-wrapping made for
+        // it. Every revert path funnels through here so wrappers can't leak.
+        const revertSplitInstance = (s) => {
+            s.revert()
+            s._gcFlexUnwrap?.()
+        }
+
         const getSplit = (el, gran) => {
             let s = splitCache.get(el)
             const rtlChars = gran === "chars" && isRTLText(el)
             const key = rtlChars ? "rtl-chars" : gran
             if (!s || s.granularity !== key) {
-                s?.revert()
+                if (s) revertSplitInstance(s)
+                const hasN = el.textContent.includes('\n')
+                // only set pre-wrap if element actually contains a newline, so \n renders without breaking other SplitText (flex/lines)
+                if (hasN && el.style) el.style.whiteSpace = 'pre-wrap'
                 s = rtlChars
                     ? getRTLCharSplit(el)
                     : new SplitText(el, {
                         type: gran,
+                        reduceWhiteSpace: hasN ? false : undefined,
                         linesClass: "gsap-line",
                         wordsClass: "gsap-word",
                         charsClass: "gsap-char",
+                        onSplit(self) {
+                            // make \n actually break line DURING split (not just after revert)
+                            for (const c of self.chars || []) {
+                                if (c.textContent === '\n') {
+                                    c.textContent = ''
+                                    c.style.display = 'block'
+                                    c.style.width = '100%'
+                                    c.style.height = '0'
+                                }
+                            }
+                            // also handle words split where \n is between words
+                            for (const w of self.words || []) {
+                                if (w.textContent.includes('\n')) {
+                                    w.style.whiteSpace = 'pre-wrap'
+                                }
+                            }
+                        }
                     })
+                s._gcFlexUnwrap = wrapFlexTarget(el)
                 s.granularity = key
                 splitCache.set(el, s)
                 textSplits.push(s)
@@ -498,8 +661,10 @@ export default function initListeners() {
             // does this automatically for animated elements; Firefox is
             // conservative and otherwise repaints these inline-block parts on the
             // main thread every frame, which is what makes split-text lag there.
+            // A: keep inline flow so <strong> etc stays inline during split
             for (let i = 0; i < parts.length; i++) {
                 parts[i].style.willChange = "transform, opacity"
+                if (gran === "chars" || gran === "words") parts[i].style.display = "inline-block"
             }
             return parts
         }
@@ -514,13 +679,13 @@ export default function initListeners() {
             splitCache.delete(el)
             const idx = textSplits.indexOf(s)
             if (idx !== -1) textSplits.splice(idx, 1)
-            s.revert()
+            revertSplitInstance(s)
         }
         // The whole point of `.time-X` on a `.spawn-text-X` element is that the
         // FULL reveal (first part starting to last part finishing) takes X
         // seconds, no matter how many chars/words/lines it got split into.
         // GSAP staggered tweens actually finish at `duration + stagger * (n-1)`,
-        // so `dur` can't be handed straight to `duration` as before — instead we
+        // so `dur` can't be handed straight to `duration` as before - instead we
         // solve for `duration`/`stagger` together so they always sum to `dur`.
         // An explicit `.stagger-N` class is honored as-is; only `duration` is
         // back-solved in that case so the last part still lands on `dur`.
@@ -545,8 +710,17 @@ export default function initListeners() {
                 duration = Math.min(dur, Math.max(dur / 3, defaults.minTextPartDuration))
                 stagger = parts.length > 1 ? (dur - duration) / (parts.length - 1) : 0
             }
-            return gsap.fromTo(parts, { ...from }, {
-                ...computeTo(from), ease, duration, delay, stagger,
+            // .randomize-*: per-PART roll (function values evaluate once per
+            // target, so every char/word/line lands on its own pose); end
+            // states recompute from the merged keys so new props tween to rest.
+            let rnd = null
+            if (hasRandom(el)) {
+                rnd = randomVars(el)
+                if (!Object.keys(rnd).length) rnd = null
+            }
+            const effFrom = { ...from, ...rnd }
+            return gsap.fromTo(parts, effFrom, {
+                ...computeTo(effFrom), ease, duration, delay, stagger,
                 onComplete: () => {
                     if (el.classList.contains("leave")) refreshLeaveRect(el)
                     revertSplit(el)
@@ -606,9 +780,9 @@ export default function initListeners() {
         // created before any scroll/scroll-progress trigger measures its position.
         // Setting them up here (before the trigger pass below) keeps offsets correct
         // and lets the single ScrollTrigger.refresh() at the end reconcile layout.
-        gsap.utils.toArray(".pin").forEach(setupPin)
+        qAll(".pin").forEach(setupPin)
 
-        // Scroll-driven extras — class-driven ScrollTrigger behaviours that don't
+        // Scroll-driven extras - class-driven ScrollTrigger behaviours that don't
         // fit the spawn/loop machinery (no `play`/`build`), handled like `.pin`:
         //   .parallax-N            - element drifts relative to scroll. N is a
         //                            speed factor: 1 = static, <1 = slower,
@@ -699,7 +873,17 @@ export default function initListeners() {
                 scrollTriggers.push(t.scrollTrigger)
             }
         }
-        gsap.utils.toArray('[class^="parallax-"], .progress-bar, .scroll-fill, .scroll-fade-bg, .scroll-horizontal').forEach(setupScrollDriven)
+        qAll('[class^="parallax-"],[class*=" parallax-"], .progress-bar, .scroll-fill, .scroll-fade-bg, .scroll-horizontal').forEach(setupScrollDriven)
+
+        // Scroller resolution: a `.scroll`/`.scroll-progress` element inside a
+        // `.scroll-frame` container binds its trigger to THAT box instead of the
+        // window. Innermost frame wins (`closest` walks up); no frame ancestor
+        // keeps the default window scroller. The frame must be a real scroller
+        // (fixed height + overflow auto/scroll) or its triggers never fire.
+        const getScroller = (el) => {
+            const frame = el.closest?.(".scroll-frame")
+            return frame && frame !== el ? frame : undefined
+        }
 
         // `.scroll`/`.scroll-progress` entrance animation, driven by ScrollTrigger.
         // Split out into a helper so DYNAMICALLY-added elements (e.g. pagination
@@ -721,11 +905,12 @@ export default function initListeners() {
                     : getEase(el)
 
                 const to = {}
-                for (const [key] of Object.entries(from)) {
+                for (const [key] of Object.entries(from || {})) {
                     if (key === "opacity") to[key] = 1
                     else if (key === "filter") to[key] = "blur(0px)"
-                    else if (key === "text") to[key] = el.innerHTML
+                    else if (key === "text") to[key] = stashText(el)
                     else if (key === "clipPath") to[key] = "inset(0% 0% 0% 0%)"
+                    else if (key === "drawSVG") to[key] = "100%"
                     else to[key] = key.startsWith("scale") ? 1 : 0
                 }
 
@@ -736,10 +921,16 @@ export default function initListeners() {
                 // GSAP's ScrollTrigger ignores a `reversed` config; swap from/to so
                 // the scrub maps in the opposite direction instead.
                 const reverse = el.classList.contains("progress-reverse")
+                // .randomize-* applies to the HIDDEN start only (non-reverse):
+                // a scrub's resting end must stay deterministic or the element
+                // would sit permanently off-pose after being scrolled through.
+                const rnd = !reverse && hasRandom(el) ? randomVars(el) : null
+                const rndEnds = rnd ? randomEnds(Object.keys(rnd)) : null
 
                 const tl = gsap.timeline({
                     scrollTrigger: {
                         trigger: el,
+                        scroller: getScroller(el),
                         start: startClass != null ? `top ${clamp(100 - startClass)}%` : defaults.progressStart,
                         end: endClass != null ? `top ${clamp(100 - endClass)}%` : defaults.progressEnd,
                         scrub: true,
@@ -751,11 +942,50 @@ export default function initListeners() {
                     const { start, end, decimals } = countTargetVars(el)
                     const obj = { n: reverse ? end : start }
                     tl.fromTo(obj, { n: reverse ? end : start }, { n: reverse ? start : end, ease, onUpdate: () => { el.textContent = obj.n.toFixed(decimals) } }, 0)
+                } else if (config.scramble) {
+                    // Scramble driven by scroll progress: each top-level text
+                    // run scrubs through garbage states (.progress-reverse
+                    // swaps the endpoints). The generic from/to scrub can't
+                    // express this (it only knows the numeric `from` keys),
+                    // which is why the entry carries the scramble flag.
+                    // .scramble-all has no empty state: its tween runs between
+                    // identical endpoints so the scrub just drives the sweep.
+                    // Same ease rule as play(): linear unless .ease-* present.
+                    const { segs, chars, speed, revealDelay, rtl } = scrambleVars(el)
+                    const all = el.classList.contains("scramble-all")
+                    segs.forEach(({ t, text }) => {
+                        if (all) {
+                            tl.to(t,
+                                { scrambleText: { text, chars, speed, revealDelay, rightToLeft: rtl }, ease }, 0)
+                        } else {
+                            tl.fromTo(t,
+                                { scrambleText: { text: reverse ? text : "", chars } },
+                                { scrambleText: { text: reverse ? "" : text, chars, speed, revealDelay, rightToLeft: rtl }, ease }, 0)
+                        }
+                    })
                 } else if (typewriterSplit) {
                     const parts = getParts(el, getGranularity(el))
                     if (parts.length) tl.fromTo(parts, { opacity: reverse ? 1 : 0 }, { opacity: reverse ? 0 : 1, ease })
+                } else if (el.classList.contains("fill-svg") && (el.classList.contains("draw") || el.classList.contains("draw-split"))) {
+                    // fill-svg modifier for draw: stroke first, then fill, sequential scrub.
+                    // For scrub the two phases are sequential tweens so scroll maps
+                    // draw → fill. Reverse swaps order so unfill happens before undraw.
+                    const fillEaseCls = [...el.classList].find(c => c.startsWith("fill-ease-"))
+                    const fillEase = fillEaseCls ? fillEaseCls.slice("fill-ease-".length) : ease
+                    const fillTimeCls = [...el.classList].find(c => c.startsWith("fill-time-"))
+                    const fillDur = fillTimeCls ? Number(fillTimeCls.slice("fill-time-".length)) : 0.5
+                    const drawDur = 1
+                    // Ensure the hidden / revealed fill state is correct before scrub starts
+                    gsap.set(el, { fillOpacity: reverse ? 1 : 0 })
+                    if (!reverse) {
+                        tl.fromTo(el, { drawSVG: "0%" , ...rnd }, { drawSVG: "100%" , ...rndEnds, ease, duration: drawDur })
+                        tl.fromTo(el, { fillOpacity: 0 }, { fillOpacity: 1, ease: fillEase, duration: fillDur })
+                    } else {
+                        tl.fromTo(el, { fillOpacity: 1 }, { fillOpacity: 0, ease: fillEase, duration: fillDur })
+                        tl.fromTo(el, { drawSVG: "100%" , ...rndEnds }, { drawSVG: "0%" , ...rnd, ease, duration: drawDur })
+                    }
                 } else {
-                    tl.fromTo(el, { ...(reverse ? to : from) }, { ...(reverse ? from : to), ease })
+                    tl.fromTo(el, { ...(reverse ? to : from), ...rnd }, { ...rndEnds, ...(reverse ? from : to), ease })
                 }
                 scrollTriggers.push(tl.scrollTrigger)
                 return
@@ -767,7 +997,7 @@ export default function initListeners() {
                 ? ([...el.classList].find(c => c.startsWith("ease-"))?.split("-")[1] ?? "none")
                 : getEase(el)
 
-            const fullText = el.innerHTML
+            const fullText = stashText(el)
 
             const enter = () => {
                 if (el._scrollTween) el._scrollTween.kill()
@@ -775,7 +1005,7 @@ export default function initListeners() {
                     ? (typewriterSplit
                         ? playTypewriterSplit(el, delay, duration, ease)
                         : typewriter(el, fullText, duration, delay, ease))
-                    : play(el, delay, duration, ease)
+                    : invokePlay(config, el, delay, duration, ease)
                 el._scrollTween.eventCallback("onComplete", () => fireOnComplete(el, "spawn"))
             }
             const reverseToStart = () => {
@@ -802,6 +1032,7 @@ export default function initListeners() {
 
             const st = ScrollTrigger.create({
                 trigger: el,
+                scroller: getScroller(el),
                 start: "top bottom",
                 end: "bottom top",
                 onEnter: enter,
@@ -811,7 +1042,7 @@ export default function initListeners() {
             })
             scrollTriggers.push(st)
         }
-        gsap.utils.toArray(".scroll, .scroll-progress").forEach(setupScroll)
+        qAll(".scroll, .scroll-progress").forEach(setupScroll)
 
         // SplitText scroll variants: `.spawn-text-<spawn>.scroll` plays the per-part
         // tween when the element enters the viewport and reverses on exit.
@@ -819,7 +1050,7 @@ export default function initListeners() {
             if (isTypewriter || text === false) return
             const tSel = "." + TEXT_PREFIX + sel.slice(1)
 
-            gsap.utils.toArray(tSel + ".scroll:not(.scroll-progress)").forEach((el) => {
+            qAll(tSel + ".scroll:not(.scroll-progress)").forEach((el) => {
                 if (isReduced(el)) return
                 const { delay, duration } = readTiming(el)
                 const ease = getEase(el)
@@ -834,6 +1065,7 @@ export default function initListeners() {
                 }
                 scrollTriggers.push(ScrollTrigger.create({
                     trigger: el,
+                    scroller: getScroller(el),
                     start: "top bottom",
                     end: "top top",
                     onEnter: enter,
@@ -843,7 +1075,7 @@ export default function initListeners() {
                 }))
             })
 
-            gsap.utils.toArray(tSel + ".scroll-progress").forEach((el) => {
+            qAll(tSel + ".scroll-progress").forEach((el) => {
                 if (isReduced(el)) return
                 const ease = getEase(el)
                 const parts = getParts(el, getGranularity(el))
@@ -855,14 +1087,19 @@ export default function initListeners() {
                 const tl = gsap.timeline({
                     scrollTrigger: {
                         trigger: el,
+                        scroller: getScroller(el),
                         start: startClass != null ? `top ${clamp(100 - startClass)}%` : defaults.progressStart,
                         end: endClass != null ? `top ${clamp(100 - endClass)}%` : defaults.progressEnd,
                         scrub: true,
                     },
                 })
                 // `.progress-reverse` runs the split scrub in reverse; swap from/to.
+                // Randomize applies to the hidden (non-reverse) start only, same
+                // rule as the element-level scrub above.
                 const reverse = el.classList.contains("progress-reverse")
-                tl.fromTo(parts, { ...(reverse ? to : from) }, { ...(reverse ? from : to), ease })
+                const rnd = !reverse && hasRandom(el) ? randomVars(el) : null
+                tl.fromTo(parts, { ...(reverse ? to : from), ...rnd },
+                    { ...(rnd ? randomEnds(Object.keys(rnd)) : null), ...(reverse ? from : to), ease })
                 scrollTriggers.push(tl.scrollTrigger)
             })
         })
@@ -889,8 +1126,9 @@ export default function initListeners() {
         setTimeout(scheduleRefresh, 400)
         setTimeout(scheduleRefresh, 1200)
 
-        spawnConfigs.forEach(({ sel, typewriter: isTypewriter, typewriterSplit, play }) => {
-            gsap.utils.toArray(sel).forEach((el) => {
+        spawnConfigs.forEach((config) => {
+            const { sel, typewriter: isTypewriter, typewriterSplit } = config
+            qAll(sel).forEach((el) => {
                 if (el.classList.contains("scroll") || el.classList.contains("scroll-progress")) return
                 if (isPreserved(el)) return
                 if (isReduced(el)) return
@@ -902,10 +1140,10 @@ export default function initListeners() {
                         el._spawnTween = playTypewriterSplit(el, delay, duration, elEase)
                     } else {
                         el.typewriter?.kill()
-                        el.typewriter = typewriter(el, el.innerHTML, duration, delay, elEase)
+                        el.typewriter = typewriter(el, stashText(el), duration, delay, elEase)
                     }
                 } else {
-                    el._spawnTween = play(el, delay, duration, getEase(el))
+                    el._spawnTween = invokePlay(config, el, delay, duration, getEase(el))
                     el._spawnTween.eventCallback("onComplete", () => {
                         if (el.classList.contains("leave")) refreshLeaveRect(el)
                         if (el.classList.contains("flip")) captureFlip(el)
@@ -915,6 +1153,7 @@ export default function initListeners() {
                     })
                 }
                 markPreserved(el)
+                el.dataset.gsapWired = "1"
             })
         })
 
@@ -924,13 +1163,14 @@ export default function initListeners() {
         spawnConfigs.forEach(({ sel, from, typewriter: isTypewriter, text }) => {
             if (isTypewriter || text === false) return
             const tSel = "." + TEXT_PREFIX + sel.slice(1)
-            gsap.utils.toArray(tSel).forEach((el) => {
+            qAll(tSel).forEach((el) => {
                 if (el.classList.contains("scroll") || el.classList.contains("scroll-progress")) return
                 if (isPreserved(el)) return
                 if (isReduced(el)) return
                 const { delay, duration } = readTiming(el)
                 el._spawnTween = playText(el, from, delay, duration, getEase(el))
                 markPreserved(el)
+                el.dataset.gsapWired = "1"
             })
         })
 
@@ -1077,8 +1317,11 @@ export default function initListeners() {
                     el[key]?.kill()
                     el[key] = trackCompatLoop(el, build(el, ctx))
                     if (loop) el[key].repeat(-1)
-                    // Infinite loops never truly complete, so fire on each cycle
-                    // (onRepeat); finite ones fire on their real completion.
+                    // Track wired loops so teardown can kill them (radiate
+                    // relies on kill/onInterrupt to remove its clones).
+                    if (!loopEls.some((l) => l.el === el && l.key === key)) {
+                        loopEls.push({ el, key })
+                    }
                     el[key].eventCallback(el[key].repeat() === -1 ? "onRepeat" : "onComplete",
                         () => fireOnComplete(el, "loop"))
                 }
@@ -1120,7 +1363,7 @@ export default function initListeners() {
 
         // `hover-<name>` and `click-<name>` trigger one of the loop animations on
         // mouseenter/mousedown. The element is wrapped in a parent div that acts as
-        // the stable hover/click hit area, while the element itself animates — so
+        // the stable hover/click hit area, while the element itself animates - so
         // the WHOLE box moves/scales instead of just its text, and the area never
         // shifts under the cursor. Marquee is skipped (its build restructures the
         // DOM).
@@ -1267,7 +1510,7 @@ export default function initListeners() {
 
         // Per-entry `setup` hook: a "special abilities" extension point. Any
         // config entry with a `setup(el, ctx)` function runs it once for every
-        // matching element at wiring time — for behaviour that doesn't fit the
+        // matching element at wiring time - for behaviour that doesn't fit the
         // scroll/order/loop machinery. If it RETURNS a function, that's treated
         // as a teardown and invoked when the whole engine is torn down, so
         // side-effects (listeners, observers, timers) can be cleaned up.
@@ -1285,7 +1528,7 @@ export default function initListeners() {
 
         // Bind click + loop animations to every element present at load, tagging
         // them so the MutationObserver below never double-binds a dynamic one.
-        gsap.utils.toArray("body *").forEach((el) => {
+        qAll("body *").forEach((el) => {
             if (el.dataset?.gsapSetup) return
             el.dataset.gsapSetup = "1"
             setupClicks(el)
@@ -1302,38 +1545,28 @@ export default function initListeners() {
         // stops the observer<->morph feedback loop.
         let flipRoots = new Set()
         let flipPendingRaf = null
-        const flipObserver = new MutationObserver((mutations) => {
-            for (const mutation of mutations) {
-                if (mutation.type !== "childList") continue
-                const target = mutation.target
-                if (target.nodeType !== 1) continue
-                flipRoots.add(target)
-            }
-            if (!flipPendingRaf) {
-                flipPendingRaf = requestAnimationFrame(() => {
-                    flipPendingRaf = null
-                    if (!flipRoots.size) return
-                    // A single frame can register several scopes for the SAME
-                    // element: removing a `.leave` node re-attaches a fixed ghost
-                    // to <body>, which adds `body` as a second scope alongside the
-                    // node's former parent. Running animateFlip per scope re-enters
-                    // playFlip on the same element, killing the in-flight tween and
-                    // clearing its transform — snapping the element into place.
-                    // Dedupe across scopes so each element flips exactly once.
-                    const toFlip = new Set()
-                    flipRoots.forEach((scope) => {
-                        if (!scope) return
-                        gsap.utils.toArray(scope.querySelectorAll?.(".flip") || [])
-                            .forEach((el) => { if (el.isConnected) toFlip.add(el) })
-                    })
-                    toFlip.forEach(playFlip)
-                    // Refresh baselines for any .flip that settled this frame.
-                    gsap.utils.toArray(document.body.querySelectorAll?.(".flip") || []).forEach(captureFlip)
-                    flipRoots = new Set()
-                })
-            }
-        })
-        flipObserver.observe(document.body, { childList: true, subtree: true })
+        const flushFlipRoots = () => {
+            if (!flipRoots.size) return
+            // A single frame can register several scopes for the SAME
+            // element: removing a `.leave` node re-attaches a fixed ghost
+            // to <body>, which adds `body` as a second scope alongside the
+            // node's former parent. Running animateFlip per scope re-enters
+            // playFlip on the same element, killing the in-flight tween and
+            // clearing its transform - snapping the element into place.
+            // Dedupe across scopes so each element flips exactly once.
+            const toFlip = new Set()
+            flipRoots.forEach((scope) => {
+                if (!scope) return
+                gsap.utils.toArray(scope.querySelectorAll?.(".flip") || [])
+                    .forEach((el) => { if (el.isConnected) toFlip.add(el) })
+            })
+            toFlip.forEach(playFlip)
+            // Refresh baselines for any .flip that settled this frame.
+            gsap.utils.toArray(document.body.querySelectorAll?.(".flip") || []).forEach(captureFlip)
+            flipRoots = new Set()
+        }
+        let flipObserver = null
+        // flipObserver is created conditionally below (hub vs direct)
 
 
 
@@ -1361,9 +1594,9 @@ export default function initListeners() {
                 const elEase = easeClass ? easeClass.split("-")[1] : "none"
                 el._spawnTween = config.typewriterSplit
                     ? playTypewriterSplit(el, delay, duration, elEase)
-                    : config.play(el, delay, duration, elEase)
+                    : invokePlay(config, el, delay, duration, elEase)
             } else {
-                el._spawnTween = config.play(el, delay, duration, ease)
+                el._spawnTween = invokePlay(config, el, delay, duration, ease)
                 el._spawnTween.eventCallback("onComplete", () => {
                     if (el.classList.contains("leave")) refreshLeaveRect(el)
                     if (el.classList.contains("flip")) captureFlip(el)
@@ -1372,7 +1605,23 @@ export default function initListeners() {
             }
         }
 
-        const appearObserver = new MutationObserver((mutations) => {
+        let appearObserver = null
+        let leaveObserver = null
+        let hubObserver = null
+        let hubRaf = null
+        let hubQueue = []
+        let hubCurrentBatch = null
+        let hubCursor = 0
+
+        const handleFlipBatch = (mutations) => {
+            for (const mutation of mutations) {
+                if (mutation.type !== "childList") continue
+                const target = mutation.target
+                if (target.nodeType !== 1) continue
+                flipRoots.add(target)
+            }
+        }
+        const handleAppearBatch = (mutations) => {
             mutations.forEach((mutation) => {
                 mutation.addedNodes.forEach((node) => {
                     if (node.nodeType !== 1) return
@@ -1402,20 +1651,77 @@ export default function initListeners() {
                     if (pinned) ScrollTrigger.refresh()
                 })
             })
-        })
-        appearObserver.observe(document.body, { childList: true, subtree: true })
-
-        // Capture any .leave elements already present so they can exit later
-        gsap.utils.toArray(".leave").forEach(captureLeave)
-
-        const leaveObserver = new MutationObserver((mutations) => {
+        }
+        const handleLeaveBatch = (mutations) => {
             mutations.forEach((mutation) => {
                 if (mutation.type !== "childList") return
                 mutation.addedNodes.forEach((n) => collectLeave(n).forEach(captureLeave))
                 mutation.removedNodes.forEach((n) => collectLeave(n).forEach(playLeave))
             })
-        })
-        leaveObserver.observe(document.body, { childList: true, subtree: true })
+        }
+        const hubHandlers = [handleFlipBatch, handleAppearBatch, handleLeaveBatch]
+        const hubDrain = () => {
+            hubRaf = null
+            if (!hubCurrentBatch) {
+                if (!hubQueue.length) return
+                hubCurrentBatch = hubQueue.splice(0, hubQueue.length)
+                hubCursor = 0
+            }
+            const end = Math.min(hubCursor + throttlePerFrame, hubHandlers.length)
+            for (let i = hubCursor; i < end; i++) {
+                hubHandlers[i](hubCurrentBatch)
+                if (hubHandlers[i] === handleFlipBatch) flushFlipRoots()
+            }
+            hubCursor = end
+            if (hubCursor < hubHandlers.length) {
+                hubRaf = requestAnimationFrame(hubDrain)
+            } else {
+                hubCurrentBatch = null
+                hubCursor = 0
+                if (hubQueue.length) hubRaf = requestAnimationFrame(hubDrain)
+            }
+        }
+        const scheduleHub = () => {
+            if (hubRaf) return
+            hubRaf = requestAnimationFrame(hubDrain)
+        }
+
+        if (throttlePerFrame > 0) {
+            hubObserver = new MutationObserver((mutations) => {
+                hubQueue.push(...mutations)
+                scheduleHub()
+            })
+            hubObserver.observe(document.body, { childList: true, subtree: true })
+        } else {
+            flipObserver = new MutationObserver((mutations) => {
+                handleFlipBatch(mutations)
+                if (!flipPendingRaf) {
+                    flipPendingRaf = requestAnimationFrame(() => {
+                        flipPendingRaf = null
+                        flushFlipRoots()
+                    })
+                }
+            })
+            flipObserver.observe(document.body, { childList: true, subtree: true })
+
+            appearObserver = new MutationObserver((mutations) => {
+                handleAppearBatch(mutations)
+            })
+            appearObserver.observe(document.body, { childList: true, subtree: true })
+
+            // Capture any .leave elements already present so they can exit later
+            qAll(".leave").forEach(captureLeave)
+
+            leaveObserver = new MutationObserver((mutations) => {
+                handleLeaveBatch(mutations)
+            })
+            leaveObserver.observe(document.body, { childList: true, subtree: true })
+            // leave capture for throttled path is done below after branch
+        }
+        if (throttlePerFrame > 0) {
+            // capture for throttled path (was inside else branch above for non-throttled)
+            qAll(".leave").forEach(captureLeave)
+        }
 
         // Keep the captured position fresh (throttled to one pass per frame)
         let positionTick = false
@@ -1423,7 +1729,7 @@ export default function initListeners() {
             if (positionTick) return
             positionTick = true
             requestAnimationFrame(() => {
-                gsap.utils.toArray(".leave").forEach((el) => {
+                qAll(".leave").forEach((el) => {
                     const s = leaveStates.get(el)
                     if (s) s.rect = el.getBoundingClientRect()
                 })
@@ -1434,27 +1740,76 @@ export default function initListeners() {
         window.addEventListener("resize", refreshLeavePositions, { passive: true })
 
     return () => {
-        appearObserver.disconnect()
-        leaveObserver.disconnect()
-        flipObserver.disconnect()
+        appearObserver?.disconnect()
+        leaveObserver?.disconnect()
+        flipObserver?.disconnect()
+        if (hubObserver) hubObserver.disconnect()
+        if (hubRaf) cancelAnimationFrame(hubRaf)
+        if (flipPendingRaf) cancelAnimationFrame(flipPendingRaf)
         window.removeEventListener("scroll", refreshLeavePositions)
         window.removeEventListener("resize", refreshLeavePositions)
         window.removeEventListener("load", ScrollTrigger.refresh)
         clearTimeout(refreshTimer)
         scrollTriggers.forEach((t) => {
-            t.kill()
+            const tw = t.trigger._scrollTween
+            // Finalize a mid-flight typewriter/scramble entrance at its end state
+            // BEFORE killing: stranded partial/garbled text would otherwise be read as
+            // settled content by the next run's stash.
+            const cls = t.trigger.classList
+            if (tw && !tw.reversed() && (cls?.contains("typewriter") || cls?.contains("scramble"))) tw.progress(1)
+            // kill(true): revert pinning (remove pin-spacers, restore inline
+            // styles) so a later init can re-pin cleanly instead of nesting a
+            // second spacer inside the leaked first one.
+            t.kill(true)
             t.trigger._scrollTween?.kill()
             delete t.trigger._scrollTween
         })
         ScrollTrigger.refresh()
+        // Clear per-element wire-up tags. Without this, any engine restart
+        // (initAnimations() called again, StrictMode remounts, route-level
+        // re-mounts that keep DOM nodes alive) would silently skip rewiring:
+        // .scroll/.pin/parallax triggers stay dead (their old ones were just
+        // killed) and clicks/loops/hover never re-bind. `_appeared` goes too,
+        // so dynamically-added .appear elements can animate under the new
+        // engine run. data-gsap-preserved (cross-reset memory) and
+        // data-gsap-ghost (detached .leave clones) are intentionally KEPT.
+        qAll('[data-gsap-scroll],[data-gsap-setup],[data-gsap-pinned],[data-gsap-scroll-driven]').forEach((el) => {
+            delete el.dataset.gsapScroll
+            delete el.dataset.gsapSetup
+            delete el.dataset.gsapPinned
+            delete el.dataset.gsapScrollDriven
+            delete el._appeared
+        })
         registeredListeners.forEach(({ el, type, fn }) => el.removeEventListener(type, fn))
         magnetListeners.forEach(({ el, type, fn }) => el.removeEventListener(type, fn))
         magnetQuery?.removeEventListener("change", applyMagnet)
         loopEls.forEach(({ el, key }) => el[key]?.kill())
+        // Sweep any radiate clones orphaned by pre-fix kills or edge cases.
+        document.querySelectorAll('[data-gsap-radiate]').forEach((n) => n.remove())
         cssTweens.forEach((t) => t?.kill())
         cssTweens.length = 0
-        gsap.utils.toArray(".typewriter").forEach(el => el.typewriter?.kill())
-        textSplits.forEach((s) => s.revert())
+        qAll(".typewriter, .scramble").forEach(el => {
+            // Preserved-region typewriters/scrambles stay as-is (already at
+            // their end state); finalize the rest so a mid-type/mid-scramble
+            // kill can't strand partial or garbled text where the next run's
+            // stash would read it.
+            const keep = el.isConnected && underPreservedRoot(el)
+            const tw = el.typewriter || el._spawnTween || el._scrollTween
+            if (!keep && tw && !tw.reversed()) tw.progress(1)
+            tw?.kill()
+        })
+        textSplits.forEach((s) => {
+            // Splits inside a tagged preserve region keep their spans - the
+            // next run will skip those elements, and reverting here would
+            // visibly strip their finished animation. Everything else reverts
+            // cleanly (and drops out of splitCache so a reused element can be
+            // re-split fresh).
+            const keep = (s.elements || []).some((e) => e.isConnected && underPreservedRoot(e))
+            if (!keep) {
+                ;(s.elements || []).forEach((e) => splitCache.delete(e))
+                revertSplitInstance(s)
+            }
+        })
         textSplits.length = 0
         onCompleteTweens.forEach((t) => t?.kill())
         onCompleteTweens.length = 0