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

package/AnimToggle.js

@@ -1,10 +1,12 @@
-  import initListeners from './Listeners'
+  import initListeners from './Listeners.js'
+  import { defaults, animations } from './Config.js'
+  import gsap from 'gsap'
 
 // localStorage key controlling whether the GSAP animation system is mounted.
-const STORAGE_KEY = 'funbyte-animations-enabled'
+const STORAGE_KEY = 'gclass-animations-enabled'
 // localStorage key for a forced reduced-motion override (see
 // enableReducedMotion / disableReducedMotion).
-const REDUCED_KEY = 'funbyte-reduced-motion'
+const REDUCED_KEY = 'gclass-reduced-motion'
 
 const reducedMotionQuery = typeof window !== 'undefined'
   ? window.matchMedia('(prefers-reduced-motion: reduce)')
@@ -44,7 +46,7 @@ function readReducedOverride() {
 //   - Otherwise, if the user HAS an explicit stored choice, respect it
 //     (override wins), even under reduced motion.
 //   - Otherwise (no stored value) fall back to the default, which is ON unless
-//     reduced motion is detected — in which case animations are off.
+//     reduced motion is detected - in which case animations are off.
 function getEnabled() {
   if (forcedReduced) return false
   return stored === null ? !reduced : stored
@@ -111,12 +113,130 @@ export function disableReducedMotion() {
 }
 
 let cleanup = null
+let bootCleanup = null
+let bootTimeout = null
+let bootStyle = null
+let hasBooted = false // true after first hard-load boot, skips boot on SPA path changes (remains false until first boot, resets on hard reload)
+
+const readBootTime = (els, fallback) => {
+  let max = null
+  for (const el of els) {
+    const cls = [...el.classList].find(c => c.startsWith('boot-time-'))
+    if (cls) {
+      const n = Number(cls.slice('boot-time-'.length))
+      if (!Number.isNaN(n)) max = max === null ? n : Math.max(max, n)
+    }
+  }
+  return max ?? fallback
+}
 
 // Boots the GSAP animation system unless animations are disabled (stored "off"
 // or reduced-motion fallback with no explicit choice). Idempotent: calling it
 // again tears down any previous run first.
+// Now also handles boot screen: any HTML/JSX with `.boot-up` anywhere is treated as the boot overlay.
+// No separate initBoot needed - just call initAnimations().
+// Boot stops all DOM rendering for defaults.bootTime (overwritten by boot-time-N class).
 export function initAnimations() {
   if (typeof window === 'undefined' || !getEnabled()) return
-  if (cleanup) cleanup()
+  // boot already in progress (first mount in StrictMode) - ignore second mount
+  if (bootTimeout) {
+    console.log(`[initAnimations] boot already in progress - ignoring duplicate call`)
+    return
+  }
+  if (cleanup) { cleanup(); cleanup = null }
+  if (bootCleanup) { bootCleanup(); bootCleanup = null }
+  if (bootStyle) { bootStyle.remove(); bootStyle = null; document.documentElement.classList.remove('gclass-booting') }
+
+  const hideBootEls = (els) => {
+    // React-safe: don't el.remove() - React owns the nodes and will throw
+    // insertBefore/removeChild on next commit if we mutate outside React.
+    // Hiding keeps React's tree intact but visually removes boot screen.
+    els.forEach(el => {
+      el.style.display = 'none'
+      el.setAttribute('hidden', '')
+      el.setAttribute('data-gclass-boot-hidden', '1')
+    })
+  }
+
+  const bootEls = typeof document !== 'undefined' ? [...document.querySelectorAll(".boot-up")].filter(el => !el.hasAttribute('data-gclass-boot-hidden')) : []
+  if (!bootEls.length) {
+    // no .boot-up -> completely skip boot
+  } else if (bootEls.length > 1) {
+    console.error(`[initAnimations] Multiple .boot-up elements detected (${bootEls.length}) - skipping all boot animations`, bootEls)
+    hideBootEls(bootEls)
+    hasBooted = true
+    // fall through to normal initListeners without pausing DOM
+  } else if (hasBooted && !bootTimeout) {
+    // path change after already booted (SPA navigation) - skip boot, hard reload resets hasBooted
+    console.log(`[initAnimations] skipping boot on path change (already booted)`, bootEls)
+    hideBootEls(bootEls)
+    hasBooted = true
+    // fall through
+  } else {
+    const bootEl = bootEls[0]
+    const hasBootEnd = [...bootEl.classList].some(c => c.startsWith('boot-end-'))
+    if (!hasBootEnd) {
+      // no boot-end-* -> completely skip boot animation (still pause? spec says skip it)
+      // spec: skip boot-end animation if no class, but still do boot pause? user said "completely skip it if no .boot-end-<name> class is present"
+      // interpret as skip the exit animation only, still pause for bootTime
+      // To match "completely skip it" for boot-end, we just don't play exit tween
+    }
+    const bootTime = readBootTime(bootEls, defaults.bootTime ?? 2)
+    console.log(`[initAnimations] .boot-up found: ${bootEls.length} - pausing DOM for ${bootTime}s`, bootEls)
+    hasBooted = true
+    // stop all DOM rendering except .boot-up
+    bootStyle = document.createElement('style')
+    bootStyle.id = 'gclass-boot-style'
+    bootStyle.textContent = `html.gclass-booting{visibility:hidden} html.gclass-booting .boot-up,html.gclass-booting .boot-up *{visibility:visible} html.gclass-booting .boot-up{position:fixed;inset:0;z-index:9999;display:grid;place-items:center}`
+    document.head.appendChild(bootStyle)
+    document.documentElement.classList.add('gclass-booting')
+    // ensure boot els are visible even if nested inside hidden ancestors
+    bootEls.forEach(el => { el.style.visibility = 'visible' })
+
+    // animations inside boot screen must play while rest of DOM is hidden - init scoped to boot-up
+    bootCleanup = initListeners(bootEl)
+
+    bootTimeout = setTimeout(() => {
+      const bootEndCls = [...bootEl.classList].find(c => c.startsWith('boot-end-'))
+      if (!bootEndCls) {
+        // no boot-end -> skip exit animation, just hide
+        bootCleanup?.(); bootCleanup = null
+        document.documentElement.classList.remove('gclass-booting')
+        bootStyle?.remove(); bootStyle = null
+        hideBootEls(bootEls)
+        bootTimeout = null
+        cleanup = initListeners()
+        return
+      }
+      const name = bootEndCls.slice('boot-end-'.length) // e.g. spawn-blur
+      const cfg = animations.find(a => a.sel === '.' + name)
+      const from = cfg?.from
+      const easeCl = [...bootEl.classList].find(c => c.startsWith('ease-'))
+      const ease = easeCl ? easeCl.split('-')[1] : defaults.ease
+      const dur = readBootTime([bootEl], defaults.effectDuration ?? 1) // reuse boot-time- or fallback to effectDuration; if boot-time used for pause, reuse same value for exit unless overridden
+      // Actually use boot-end-time-N if present, else effectDuration
+      const endTimeCls = [...bootEl.classList].find(c => c.startsWith('boot-end-time-'))
+      const endDur = endTimeCls ? Number(endTimeCls.slice('boot-end-time-'.length)) : dur
+
+      const finish = () => {
+        bootCleanup?.(); bootCleanup = null
+        document.documentElement.classList.remove('gclass-booting')
+        bootStyle?.remove(); bootStyle = null
+        hideBootEls(bootEls)
+        bootTimeout = null
+        cleanup = initListeners()
+      }
+
+      if (!cfg || !from) {
+        console.warn(`[initAnimations] boot-end-${name} has no from state - removing without animation`)
+        finish()
+        return
+      }
+      // play spawn in reverse (visible -> hidden) before removing
+      gsap.to(bootEl, { ...from, duration: endDur, ease, onComplete: finish })
+    }, bootTime * 1000)
+    return
+  }
+
   cleanup = initListeners()
 }

package/Animations.js

@@ -1,9 +1,13 @@
-import { Flip, SplitText, TextPlugin } from "gsap/all";
+import { DrawSVGPlugin, Flip, MotionPathPlugin, ScrambleTextPlugin, SplitText, TextPlugin } from "gsap/all";
 import gsap from "gsap";
+import { defaults } from './Config.js'
 
 gsap.registerPlugin(Flip)
 gsap.registerPlugin(SplitText)
 gsap.registerPlugin(TextPlugin)
+gsap.registerPlugin(DrawSVGPlugin)
+gsap.registerPlugin(MotionPathPlugin)
+gsap.registerPlugin(ScrambleTextPlugin)
 
 // A tasteful fallback whenever a call site omits an ease, so the animation
 // never lapses into the raw "none" look. Callers still override this freely.
@@ -28,6 +32,23 @@ export const finalOpacity = (target) => {
     return isNaN(v) ? 1 : v
 }
 
+// TextPlugin tweens take their endpoints from the LIVE DOM: the `.typewriter`
+// play callbacks pass `el.innerHTML` as the text to type. The tween's from
+// state ("") is applied the instant the tween is created, and a teardown that
+// kills the tween mid-flight leaves that wiped state behind - so a later
+// engine re-init reading `el.innerHTML` again would type an empty (or
+// partially-typed) string forever. Stash the full HTML on first sight and
+// reuse it. The stash only refreshes from SETTLED content: never while a
+// typewriter tween on the element is actively rendering partial progress, and
+// never from a blank DOM. Legit content changes (React re-renders, dynamic
+// `.appear` elements) therefore update the stash naturally.
+export const stashText = (el) => {
+    const busy = (el.typewriter || el._spawnTween || el._scrollTween)?.isActive?.()
+    const html = el.innerHTML
+    if (!busy && html && html.trim()) el._gcText = html
+    return el._gcText !== undefined ? el._gcText : html
+}
+
 
 //Spawn animations
 
@@ -58,7 +79,11 @@ export function expandA (target , delay , dur , ease){
 }
 
 export function typewriter (target , text , dur , delay , ease){
-    return gsap.fromTo(target , {text:""} , {ease:easeOf(ease) , duration:dur , delay:delay , text:text})
+    // Any element using TextPlugin gets pre-wrap so "\n" from VSCode Enter or JS strings
+    // renders as a real line break and any innerHTML formatting is preserved.
+    gsap.utils.toArray(target).forEach(el => { if (el.style) el.style.whiteSpace = "pre-wrap" })
+    const value = String(text).replace(/\n/g, "<br>")
+    return gsap.fromTo(target , {text:""} , {ease:easeOf(ease) , duration:dur , delay:delay , text:{value}})
 }
 
 export function spawnSpinCCW (target , delay , dur , ease){
@@ -90,7 +115,7 @@ export function spawnBlur (target , delay , dur , ease){
 //   right - hidden on the left, wipes open rightward (left -> right)
 // The `from` inset is mirrored in the Config entry so
 // `.scroll`/`.scroll-progress`/`.leave` reversal and `.appear` all know the
-// hidden state. No opacity is involved — pure clip wipe.
+// hidden state. No opacity is involved - pure clip wipe.
 const CLIP_FROM = {
     up: "inset(0% 0% 100% 0%)",
     down: "inset(100% 0% 0% 0%)",
@@ -102,13 +127,13 @@ export function spawnClipReveal (target , delay , dur , ease , dir = "up"){
     return gsap.fromTo(target , {clipPath: from} , {clipPath:"inset(0% 0% 0% 0%)" , ease:easeOf(ease) , duration:dur , delay:delay})
 }
 
-// Curtain reveal: opens outward from the horizontal centre — a vertical slit in
+// Curtain reveal: opens outward from the horizontal centre - a vertical slit in
 // the middle widens left and right until the whole box is shown.
 export function curtainHorizontal (target , delay , dur , ease){
     return gsap.fromTo(target , {clipPath:"inset(0% 50% 0% 50%)"} , {clipPath:"inset(0% 0% 0% 0%)" , ease:easeOf(ease) , duration:dur , delay:delay})
 }
 
-// Curtain reveal: opens outward from the vertical centre — a horizontal slit in
+// Curtain reveal: opens outward from the vertical centre - a horizontal slit in
 // the middle widens up and down until the whole box is shown.
 export function curtainVertical (target , delay , dur , ease){
     return gsap.fromTo(target , {clipPath:"inset(50% 0% 50% 0%)"} , {clipPath:"inset(0% 0% 0% 0%)" , ease:easeOf(ease) , duration:dur , delay:delay})
@@ -201,6 +226,227 @@ export function countUp (target , delay , dur, ease){
     return gsap.timeline({ delay }).fromTo(obj , { n: start } , { n: end , duration:dur , ease:e , onUpdate: () => { target.textContent = obj.n.toFixed(decimals) } } , 0)
 }
 
+// Helpers for the `fill-svg` draw-modifier. When an element carries both
+// `.draw`/`.draw-split` and `.fill-svg`, the stroke is drawn first and then
+// the interior fills. `fill-time-N` / `fill-ease-NAME` override the fill
+// phase; otherwise the fill takes half of `dur` and reuses the draw ease.
+const fillTimeOf = (el , fallback) => {
+    const m = [...el.classList].find(c => c.startsWith("fill-time-"))
+    return m ? Number(m.slice("fill-time-".length)) : fallback * 0.5
+}
+const fillEaseOf = (el , fallbackEase) => {
+    const m = [...el.classList].find(c => c.startsWith("fill-ease-"))
+    return m ? m.slice("fill-ease-".length) : fallbackEase
+}
+
+// Stroke-draw reveal (strokes only - filled SVGs are deliberately out of
+// scope for now). Explicit fromTo endpoints so the animation's hidden state
+// matches this class's Config `from` metadata exactly: `.scroll-progress`
+// scrubs between those two values and `.leave`/`.scroll` reversal tweens back
+// into them. When the target also carries `.fill-svg`, the interior is filled
+// after the stroke finishes (draw → fill sequential timeline).
+export function drawsvg (target , delay , dur , ease){
+    const e = easeOf(ease)
+    const first = gsap.utils.toArray(target)[0]
+    const hasFill = !!first?.classList?.contains("fill-svg")
+    if (!hasFill) {
+        return gsap.fromTo(target , {drawSVG:"0%"} , {ease:e , duration:dur , delay:delay , drawSVG:"100%"})
+    }
+    const fillDur = fillTimeOf(first , dur)
+    const fillEase = fillEaseOf(first , ease)
+    const fillTargets = gsap.utils.toArray(target).filter(el => el.classList.contains("fill-svg"))
+    const tl = gsap.timeline({ delay })
+    // Keep fill invisible while the stroke draws
+    if (fillTargets.length) gsap.set(fillTargets , { fillOpacity: 0 })
+    tl.fromTo(target , {drawSVG:"0%"} , {ease:e , duration:dur , drawSVG:"100%"})
+    if (fillTargets.length) {
+        tl.fromTo(fillTargets , {fillOpacity:0} , {ease:easeOf(fillEase) , duration:fillDur , fillOpacity:1})
+    }
+    return tl
+}
+
+// Busts a multi-segment <path> (one containing multiple "M" commands) apart
+// into one single-segment <path> per segment. Browsers can't reliably render
+// a stroke-dash progressive reveal across disconnected subpaths, while
+// separate paths draw correctly. Adapted from the official DrawSVGPlugin
+// helper, with one addition: splitting REPLACES the source path in the DOM,
+// so the result is cached on that element and reused while the segments are
+// still live - an engine re-init (StrictMode remount, route change) must not
+// churn the DOM a second time. Attributes are copied verbatim; filled SVGs
+// are simply untouched territory for now.
+export function splitPaths (paths){
+    const toSplit = gsap.utils.toArray(paths)
+    let newPaths = []
+    if (toSplit.length > 1) {
+        toSplit.forEach(path => newPaths.push(...splitPaths(path)))
+        return newPaths
+    }
+    const path = toSplit[0]
+    if (!path) return newPaths
+    if (path._gcSplitPaths?.[0]?.isConnected) return path._gcSplitPaths
+    const rawPath = MotionPathPlugin.getRawPath(path)
+    const parent = path.parentNode
+    const attributes = [...path.attributes]
+    newPaths = rawPath.map(segment => {
+        const newPath = document.createElementNS("http://www.w3.org/2000/svg" , "path")
+        let i = attributes.length
+        while (i--) {
+            const attr = attributes[i]
+            // Don't copy GSAP wiring or appear/scroll triggers - children are
+            // animated via the returned timeline, not as independent spawns.
+            // Copying "appear" caused appearObserver → split → appear loop.
+            if (attr.nodeName === "class") {
+                const filtered = attr.nodeValue
+                    .split(/\s+/)
+                    .filter(c => c && c !== "appear" && c !== "scroll" && c !== "scroll-progress" && c !== "draw" && c !== "draw-split")
+                    .join(" ")
+                if (filtered) newPath.setAttributeNS(null, "class", filtered)
+                continue
+            }
+            if (attr.nodeName.startsWith("data-gsap")) continue
+            newPath.setAttributeNS(null , attr.nodeName , attr.nodeValue)
+        }
+        newPath.setAttributeNS(null , "d" ,
+            "M" + segment[0] + "," + segment[1] +
+            "C" + segment.slice(2).join(",") +
+            (segment.closed ? "z" : ""))
+        // Isolate paint and mark as split child so future inits skip it
+        newPath.dataset.gsapSplit = "1"
+        newPath.style.contain = "paint"
+        newPath.style.willChange = "transform"
+        parent.insertBefore(newPath , path)
+        return newPath
+    })
+    parent.removeChild(path)
+    return path._gcSplitPaths = newPaths
+}
+
+// Like drawsvg but built for MULTI-SEGMENT paths: splitPaths() first, then
+// draw each resulting segment one after another, giving every segment a slice
+// of `dur` proportional to its own stroke length so the pen travels at a
+// constant speed across the whole drawing. Returns a timeline, so leave /
+// scroll reversal un-draws the segments back-to-front and the engine's
+// onComplete hooks fire only after the final segment lands. When the source
+// also carries `.fill-svg`, every resulting segment is filled together after
+// the last draw segment lands (draw → fill).
+export function drawsvgSplit (target , delay , dur , ease){
+    const e = easeOf(ease)
+    const first = gsap.utils.toArray(target)[0]
+    const hasFill = !!first?.classList?.contains("fill-svg")
+    const fillDur = hasFill ? fillTimeOf(first , dur) : 0
+    const fillEase = hasFill ? fillEaseOf(first , ease) : ease
+    const tl = gsap.timeline({ delay })
+    const paths = splitPaths(target)
+    let distance = 0
+    paths.forEach(segment => distance += segment.getTotalLength())
+    // Nothing drawable (empty selection / zero-length strokes): hand back the
+    // inert timeline rather than divide by zero below.
+    if (!distance) return tl
+    if (hasFill && paths.length) gsap.set(paths , { fillOpacity: 0 })
+    paths.forEach(segment => {
+        tl.fromTo(segment ,
+            {drawSVG:"0%"} ,
+            {ease:e , duration:dur * (segment.getTotalLength() / distance) , drawSVG:"100%"})
+    })
+    if (hasFill && paths.length) {
+        tl.fromTo(paths , {fillOpacity:0} , {ease:easeOf(fillEase) , duration:fillDur , fillOpacity:1})
+    }
+    return tl
+}
+
+// Scramble plumbing. Only the element's TOP-LEVEL TEXT runs are scrambled:
+// each run is wrapped in its own span and tweened separately, while real child
+// elements (links, icons, ...) are left completely untouched - their markup
+// survives the animation intact. Wraps are cached on the element so replays
+// (engine re-inits, .appear re-triggers) reuse the same spans instead of
+// churning the DOM.
+export const scrambleSegments = (target) => {
+    let wraps = target._gcScrambleSegs
+    if (!wraps || !wraps.length || !wraps.every((w) => w.parentNode === target)) {
+        wraps = []
+        ;[...target.childNodes].forEach((node) => {
+            // Whitespace-only runs stay bare so natural spacing is preserved;
+            // everything else becomes an individually scrambable span.
+            if (node.nodeType !== 3 || !node.textContent.trim()) return
+            // ScrambleTextPlugin TRIMS its targets, so a span holding
+            // " with a " would resolve to "with a" and swallow the spaces
+            // around a neighbouring element. Split the edge whitespace off
+            // into bare text nodes and wrap only the trimmed core.
+            const raw = node.textContent
+            const core = raw.trim()
+            const leadIdx = raw.indexOf(core[0])
+            const trailStart = leadIdx + core.length
+            const frag = document.createDocumentFragment()
+            if (leadIdx > 0) frag.appendChild(document.createTextNode(raw.slice(0 , leadIdx)))
+            const span = document.createElement("span")
+            span.textContent = core
+            frag.appendChild(span)
+            if (trailStart < raw.length) frag.appendChild(document.createTextNode(raw.slice(trailStart)))
+            target.insertBefore(frag , node)
+            target.removeChild(node)
+            wraps.push(span)
+        })
+        target._gcScrambleSegs = wraps
+    }
+    return wraps.map((w) => ({ t: w , text: w.textContent }))
+}
+
+// Reads a scramble element's modifier classes and resolves them against the
+// package defaults:
+//   .amount-N        -> ScrambleText speed (default 1, GSAP's own default)
+//   .reveal-delay-N  -> revealDelay in seconds (default defaults.revealDelay)
+//   .chars-[...]     -> character pool taken verbatim from inside the brackets
+//                       (default defaults.characterlist)
+export function scrambleVars (target){
+    const num = (prefix , fallback) => {
+        const match = [...target.classList].find(c => c.startsWith(prefix))
+        return match ? Number(match.slice(prefix.length)) : fallback
+    }
+    // Greedy up to the LAST "]" so pools containing "]" survive intact.
+    const charsCls = [...target.classList].find(c => /^chars-\[(.*)\]$/.test(c))
+    return {
+        segs: scrambleSegments(target) ,
+        chars: charsCls ? charsCls.slice("chars-[".length , -1) : defaults.characterlist ,
+        speed: num("amount-" , 1) ,
+        revealDelay: num("reveal-delay-" , defaults.revealDelay) ,
+        // .scramble-rtl flips the reveal direction (ScrambleTextPlugin's
+        // rightToLeft) so the sweep travels right -> left.
+        rtl: target.classList.contains("scramble-rtl") ,
+    }
+}
+
+// Scramble spawn: the text starts empty and resolves into the real content
+// through garbage characters - no opacity involved, the scramble IS the
+// reveal. Unlike typewriter there is no opacity fade to hide behind, so the
+// package default "back" ease would visually finish at ~36% of `dur` (back.out
+// crosses ~99% early and the reveal index clamps): unless an explicit ease-*
+// class is present the tween therefore eases linearly, making time-N the TRUE
+// total reveal time. One timeline holds a per-text-run tween at position 0 so
+// leave/scroll reversal and onComplete hooks treat it as a single animation.
+//
+// Variants / modifiers:
+//   .scramble-all     - no empty-start typing: the already-finished string
+//                       flips to garbage as a whole and sweeps back (native
+//                       ScrambleTextPlugin resolve).
+//   .scramble-rtl     - reveal travels right -> left.
+export function scramble (target , delay , dur , ease){
+    const e = [...target.classList].some(c => c.startsWith("ease-")) ? easeOf(ease) : "none"
+    const { segs , chars , speed , revealDelay , rtl } = scrambleVars(target)
+    const all = target.classList.contains("scramble-all")
+    const tl = gsap.timeline({ delay })
+    segs.forEach(({ t , text }) => {
+        if (all) {
+            tl.to(t ,
+                {scrambleText:{text , chars , speed , revealDelay , rightToLeft:rtl} , ease:e , duration:dur} , 0)
+        } else {
+            tl.fromTo(t ,
+                {scrambleText:{text:"" , chars}} ,
+                {scrambleText:{text , chars , speed , revealDelay , rightToLeft:rtl} , ease:e , duration:dur} , 0)
+        }
+    })
+    return tl
+}
+
 
 //Mouse animations
 
@@ -295,7 +541,7 @@ export function shake (delay , target , amount , dur , ease){
 export function bell (delay , target , amount , dur , ease){
     const tl = gsap.timeline()
     tl.set(target , {transformOrigin : "50% 0%"})
-    // A quick toll that overshoots and damps down — reads as a physical strike
+    // A quick toll that overshoots and damps down - reads as a physical strike
     // instead of a symmetrical wiggle.
     .to(target , {rotate:amount , duration:dur * 0.12 , ease:"power2.out"})
     .to(target , {rotate:-amount * 0.7, duration:dur * 0.18 , ease:"power2.inOut"})
@@ -323,6 +569,9 @@ export function pulse (delay , target , amount , dur , ease){
 
 export function radiate (delay , target , amount , dur , ease , zIndex){
     const clone = target.cloneNode(true)
+    // Tagged so engine teardown can sweep up clones whose tween was killed
+    // before its onComplete (route changes mid-animation).
+    clone.setAttribute("data-gsap-radiate", "1")
     clone.style.cssText = `position:fixed;left:0;top:0;right:auto;bottom:auto;margin:0;pointer-events:none;transform-origin:50% 50%;${zIndex != null ? `z-index:${zIndex};` : ""}`
     // Keep the ripple glued to the target so it tracks scroll/resize instead of
     // getting stranded at the position captured when the animation was built.
@@ -342,23 +591,43 @@ export function radiate (delay , target , amount , dur , ease , zIndex){
         tick = true
         requestAnimationFrame(() => { tick = false; applyRect() })
     }
+    // Don't animate detached targets — return inert tween
+    if (!target.isConnected) {
+        return gsap.fromTo(clone, {}, { duration: 0 })
+    }
     document.body.appendChild(clone)
     applyRect()
     window.addEventListener("scroll", schedule, { passive: true })
     window.addEventListener("resize", schedule, { passive: true })
+    // Killing the tween (teardown, hover/click rebuilds) must clean up exactly
+    // like natural completion - otherwise clones + listeners leak.
+    let tween = null
+    const cleanup = () => {
+        clone.remove()
+        window.removeEventListener("scroll", schedule)
+        window.removeEventListener("resize", schedule)
+        if (observer) observer.disconnect()
+    }
+    // If target is removed from DOM (React unmount, .remove(), SPA navigation),
+    // kill the tween and remove the clone — mirrors React useEffect cleanup
+    const observer = new MutationObserver(() => {
+        if (!target.isConnected) {
+            if (tween) tween.kill()
+            cleanup()
+        }
+    })
+    observer.observe(document.body, { childList: true, subtree: true })
 
-    return gsap.fromTo(clone , {scale:1 , opacity:1} , {
+    tween = gsap.fromTo(clone , {scale:1 , opacity:1} , {
         scale:amount / 10 ,
         opacity:0 ,
         duration:dur ,
         delay:delay ,
         ease:easeOf(ease) ,
-        onComplete: () => {
-            clone.remove()
-            window.removeEventListener("scroll", schedule)
-            window.removeEventListener("resize", schedule)
-        } ,
+        onComplete: () => { observer.disconnect(); cleanup(); },
+        onInterrupt: () => { observer.disconnect(); cleanup(); },
     })
+    return tween
 }
 
 
@@ -378,33 +647,57 @@ export function marquee (target , dir , duration , xOffset = 0 , yOffset = 0 , n
     const horizontal = dir === "left" || dir === "right"
     // Anchor the track to the top-left corner so its two identical copies tile
     // the container exactly. The track is positioned absolutely, out of the
-    // container's flex layout — otherwise a `justify-center` (or any alignment)
+    // container's flex layout - otherwise a `justify-center` (or any alignment)
     // on the container centers the overflowing track and shifts the tile seam,
     // which opens a gap on the trailing edge at some point in the loop.
     target.style.position = "relative"
     target.style.overflow = "hidden"
-    const track = document.createElement("div")
-    track.style.cssText = `position:absolute;top:${yOffset}px;left:${xOffset}px;display:flex;flex-direction:${horizontal ? "row" : "column"};width:max-content;will-change:transform;`
-    while (target.firstChild) track.appendChild(target.firstChild)
-    target.appendChild(track)
-
-    // The track is absolutely positioned, so once its content moves in, the host
-    // has no in-flow children left and can collapse to zero height. With the
-    // `overflow:hidden` set above that clips the track away entirely (e.g. a
-    // bare-text `<h1 class="marquee-left">` disappears). Preserve the content's
-    // height on the host when that happens so the marquee stays visible. Hosts
-    // with their own height (flex cards etc.) are left untouched.
+
+    // Rebuilds over the SAME element (engine restarts, StrictMode remounts)
+    // must reuse the existing track. Re-creating it would swallow the old
+    // absolute track as the first "child", repeat THAT as the tiling unit -
+    // every copy stacks at the same offset and scrollWidth collapses.
+    let track = target._gcTrack
+    if (!track || !track.isConnected) {
+        track = document.createElement("div")
+        track.style.cssText = `position:absolute;top:${yOffset}px;left:${xOffset}px;display:flex;flex-direction:${horizontal ? "row" : "column"};width:max-content;will-change:transform;`
+        while (target.firstChild) track.appendChild(target.firstChild)
+        target.appendChild(track)
+        // Guard against legacy poisoned DOM: older builds could wrap a previous
+        // absolute track inside this one. Unwrap any nested engine tracks so
+        // the stashed unit is always the raw content.
+        while (
+            track.children.length &&
+            [...track.children].every((c) => c.style.position === "absolute" && c.style.display === "flex")
+        ) {
+            const inner = track.firstElementChild
+            while (inner.firstChild) track.insertBefore(inner.firstChild, inner)
+            track.removeChild(inner)
+        }
+        target._gcUnitHtml = track.innerHTML
+    }
+    track.style.flexDirection = horizontal ? "row" : "column"
+    const unitHtml = target._gcUnitHtml
+
+    // Measure ONE unit on its own: the live track may already hold N copies
+    // (or stale content), which would inflate unitSize and starve `copies`.
+    const measurer = document.createElement("div")
+    measurer.style.cssText = track.style.cssText + "visibility:hidden;"
+    measurer.innerHTML = unitHtml
+    target.appendChild(measurer)
+    const unitSize = horizontal ? measurer.scrollWidth : measurer.scrollHeight
+    measurer.remove()
+
+    // Nothing to tile (empty content) - return an inert tween rather than one
+    // dividing by a zero-width unit.
+    if (!unitSize) return gsap.fromTo(track, {}, { duration: 0 })
+
+    // The track is absolutely positioned, so a bare-text host can collapse to
+    // zero height and `overflow:hidden` would clip the strip away entirely.
     if (target.offsetHeight === 0 && track.offsetHeight > 0) {
         target.style.height = track.offsetHeight + "px"
     }
 
-    const first = track.children[0]
-    if (!first) return gsap.fromTo(track, {}, { duration: 0 })
-
-    // A single copy of the content (the width one loop step must travel).
-    const unitHtml = track.innerHTML
-    const unitSize = horizontal ? track.scrollWidth : track.scrollHeight
-
     // Default: repeat the unit until the whole strip is at least as wide as the
     // viewport (plus one extra copy so the trailing edge stays covered mid-loop).
     // `.marquee-no-repeat` opts into the minimal 2-copy single-seam behaviour.

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `gclass-anims` will be documented in this file.
+
+## [1.0.0-beta.20] - 2026-9-2
+- Fix ESM strict import: `AnimToggle.js` and `Listeners.js` now use `.js` extensions (`Remix`/`Qwik` Node ESM `Cannot find module` fix)
+- Fix `Lit` shadow DOM `works.txt` `no` → light DOM default (`createRenderRoot(){return this}`) + `initListeners(shadowRoot)` docs
+- Fix `SvelteKit` `ERESOLVE` (`@sveltejs/vite-plugin-svelte 4` → `5.1` for `vite@6`) + missing `src/app.html`
+- Fix `Qwik` `entry.ssr not found` → add `src/root.tsx`+`entry.ssr.tsx`+`tsconfig.json`
+- Fix `SolidStart` Vinxi `503` → simplified to `vite-plugin-solid` SPA (same fine-grained model)
+- Reverted license `LGPL-3.0-only` → `MIT` (anywhere GSAP is usable)
+
+## [1.0.0-beta.19] - 2026-9-1
+- Fixed the SplitText animations formatting and removed Boot.js
+
+## [1.0.0-beta.18] - 2026-9-1
+- Hopefully finally fixed `.boot-up` properly skipping on path changes
+
+## [1.0.0-beta.17] - 2026-9-1
+- Fixed the `.boot-up` class firing on every path change
+
+## [1.0.0-beta.16] - 2026-09-1
+- Added a new `.boot-up` class for boot up animations
+- Fixed text animations not taking formatting into account
+
+
+## [1.0.0-beta.13] - 2026-08-27
+- Added a new `.fill-svg` modifier for the `.draw` and `.draw-split` classes that fills the SVG after it has been drawn.
+
+## [1.0.0-beta.12] - 2026-08-26
+
+- Fixed `scramble` with `scroll-progress` throwing `can't convert undefined to object` - `computeTo` (`Listeners.js:424`) and scrub `to` builder (`Listeners.js:867`) now guard `from` (`scramble` has no `from`).
+
+## [1.0.0-beta.11] - 2026-08-26
+
+- Fixed `.draw-split` infinite loop when paired with `.appear` - `splitPaths` (`Animations.js:244`) now strips `appear`/`scroll`/`scroll-progress`/`draw`/`draw-split`/`data-gsap-*` from cloned segments, marks children with `data-gsap-split` + `contain:paint`/`will-change:transform` isolation, and prevents `appearObserver` (`Listeners.js:1559`) re-triggering. Also isolated `draw-split` demos in docs.
+
+## [1.0.0-beta.10] - 2026-08-26
+
+- Added `.randomize-<prop>-[min]-[max]` - randomize spawn start values per element (e.g. `randomize-rotation-[-90]-[90]`, `randomize-x-[-40]-[40]`). Re-rolls on every replay (`.scroll` re-enter, `.appear`).
+- Added `.draw` - stroke-draw reveal for SVG paths using DrawSVGPlugin (`drawSVG: 0% → 100%`).
+- Added `.draw-split` - draws multi-segment SVG paths sequentially at constant pen speed (splits paths with multiple `M` commands into individual strokes).
+- Added `.scramble` - text resolves from empty through scrambled characters into real content (ScrambleTextPlugin). Supports `.reveal-delay-N`, `.chars-[...]`, `.amount-N`, `.scramble-rtl`.
+- Added `.scramble-all` - variant of scramble with no empty start; the finished string flips to garbage as a whole then sweeps back.
+- Added `.scroll-frame` - use a scrollable container as the ScrollTrigger scroller for nested `.scroll` / `.scroll-progress` elements (innermost `.scroll-frame` ancestor wins).
+- Fixed `spawn-text-*` (SplitText) not working correctly on flex containers - text runs are now wrapped in block containers before splitting to preserve flex layout, spacing, and line grouping.
+
+## [1.0.0-beta.9] - Previous release
+
+- See git history for earlier changes.