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

package/AnimToggle.js

@@ -1,6 +1,6 @@
   import initListeners from './Listeners.js'
   import { defaults, animations } from './Config.js'
-  import gsap from 'gsap'
+  import { gsap } from 'gsap'
 
 // localStorage key controlling whether the GSAP animation system is mounted.
 const STORAGE_KEY = 'gclass-animations-enabled'
@@ -118,6 +118,57 @@ 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)
 
+// Runtime config for gclassOpts — 0 = defaults (no throttle, default GSAP ticker)
+let currentThrottle = 0
+let currentFps = 0
+const configSubscribers = new Set()
+function getConfigSnapshot() { return { throttlePerFrame: currentThrottle, fps: currentFps } }
+function emitConfig() { configSubscribers.forEach(fn => fn(getConfigSnapshot())) }
+function applyFps(fps) {
+  const v = Number(fps) || 0
+  currentFps = v
+  if (v > 0) gsap.ticker.fps(v)
+  else gsap.ticker.fps(0) // 0 = remove cap, fallback to rAF (GSAP default)
+  emitConfig()
+}
+function normalizeGclassArgs(throttlePerFrame, fps) {
+  // support gclassOpts({throttlePerFrame, fps}) object overload
+  if (typeof throttlePerFrame === 'object' && throttlePerFrame !== null) {
+    fps = throttlePerFrame.fps
+    throttlePerFrame = throttlePerFrame.throttlePerFrame
+  }
+  const nextThrottle = throttlePerFrame == null ? 0 : Number(throttlePerFrame) || 0
+  const nextFps = fps == null ? 0 : Number(fps) || 0
+  return { nextThrottle, nextFps }
+}
+
+/**
+ * Change GClass runtime options on the fly without reload.
+ * gclassOpts(throttlePerFrame, fps) — both optional numbers.
+ * gclassOpts() or gclassOpts(undefined, undefined) resets to defaults (no throttle, default ticker).
+ * Also accepts gclassOpts({throttlePerFrame, fps}).
+ * Example low-end button: onClick={() => gclassOpts(1, 30)}
+ * Example reset: onClick={() => gclassOpts()} // 0, 60fps rAF
+ */
+export function gclassOpts(throttlePerFrame, fps) {
+  const { nextThrottle, nextFps } = normalizeGclassArgs(throttlePerFrame, fps)
+  currentThrottle = nextThrottle
+  applyFps(nextFps)
+  // re-wire observers with new throttle without full boot reload (if already running)
+  if (typeof window !== 'undefined' && cleanup && !bootTimeout) {
+    try { cleanup() } catch {}
+    cleanup = null
+    if (getEnabled()) cleanup = initListeners(document, currentThrottle)
+  }
+  // if boot is in progress we just store for next initAnimations; if not running, next initAnimations will use stored values
+  return getConfigSnapshot()
+}
+export function getGClassConfig() { return getConfigSnapshot() }
+export function subscribeGClassConfig(cb) {
+  configSubscribers.add(cb)
+  return () => configSubscribers.delete(cb)
+}
+
 const readBootTime = (els, fallback) => {
   let max = null
   for (const el of els) {
@@ -136,7 +187,28 @@ const readBootTime = (els, fallback) => {
 // 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() {
+// throttlePerFrame / fps: forwarded to gclassOpts-equivalent runtime.
+//   initAnimations(throttlePerFrame, fps) — positional numbers, 0/undefined = defaults
+//   initAnimations({throttlePerFrame, fps}) — object overload
+//   initAnimations() — uses last gclassOpts values (defaults on first call)
+export function initAnimations(throttlePerFrame, fps) {
+  // gclassOpts-style normalization: (throttle, fps) positional or {throttlePerFrame, fps} object
+  // no args -> fallback to last gclassOpts values (defaults 0 = no throttle, default ticker)
+  let effThrottle = currentThrottle
+  let effFps = currentFps
+  if (throttlePerFrame !== undefined || fps !== undefined) {
+    const { nextThrottle, nextFps } = normalizeGclassArgs(throttlePerFrame, fps)
+    effThrottle = nextThrottle
+    effFps = nextFps
+    currentThrottle = effThrottle
+    currentFps = effFps
+    if (effFps > 0) gsap.ticker.fps(effFps)
+    else gsap.ticker.fps(0)
+    emitConfig()
+  } else {
+    if (effFps > 0) gsap.ticker.fps(effFps)
+    else gsap.ticker.fps(0)
+  }
   if (typeof window === 'undefined' || !getEnabled()) return
   // boot already in progress (first mount in StrictMode) - ignore second mount
   if (bootTimeout) {
@@ -194,7 +266,7 @@ export function initAnimations() {
     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)
+    bootCleanup = initListeners(bootEl, effThrottle)
 
     bootTimeout = setTimeout(() => {
       const bootEndCls = [...bootEl.classList].find(c => c.startsWith('boot-end-'))
@@ -205,7 +277,7 @@ export function initAnimations() {
         bootStyle?.remove(); bootStyle = null
         hideBootEls(bootEls)
         bootTimeout = null
-        cleanup = initListeners()
+        cleanup = initListeners(document, effThrottle)
         return
       }
       const name = bootEndCls.slice('boot-end-'.length) // e.g. spawn-blur
@@ -224,7 +296,7 @@ export function initAnimations() {
         bootStyle?.remove(); bootStyle = null
         hideBootEls(bootEls)
         bootTimeout = null
-        cleanup = initListeners()
+        cleanup = initListeners(document, effThrottle)
       }
 
       if (!cfg || !from) {
@@ -238,5 +310,5 @@ export function initAnimations() {
     return
   }
 
-  cleanup = initListeners()
+  cleanup = initListeners(document, effThrottle)
 }

package/Animations.js

@@ -1,5 +1,5 @@
 import { DrawSVGPlugin, Flip, MotionPathPlugin, ScrambleTextPlugin, SplitText, TextPlugin } from "gsap/all";
-import gsap from "gsap";
+import { gsap } from "gsap";
 import { defaults } from './Config.js'
 
 gsap.registerPlugin(Flip)
@@ -9,6 +9,44 @@ gsap.registerPlugin(DrawSVGPlugin)
 gsap.registerPlugin(MotionPathPlugin)
 gsap.registerPlugin(ScrambleTextPlugin)
 
+// --- Breakpoint helpers for modifiers (xs/s/m/l/xl) -------------------------
+// Lazy to avoid circular init (Config.js <-> Animations.js)
+const getBpDataMod = () => {
+    const entries = Object.entries(defaults.breakpoints || {}).sort((a,b)=>a[1]-b[1])
+    const names = entries.map(([k])=>k)
+    const map = Object.fromEntries(entries)
+    const re = names.length ? new RegExp(`^(${names.join('|')}):(.+)$`) : /^$^/
+    return { entries, names, map, re }
+}
+const isBreakpointActiveMod = (bp) => {
+    if (!bp) return true
+    const { map } = getBpDataMod()
+    const px = map[bp]
+    if (px == null) return true
+    if (typeof window === 'undefined' || !window.matchMedia) return true
+    return window.matchMedia(`(min-width: ${px}px)`).matches
+}
+const hasGClassMod = (el, name) => {
+    if (el.classList.contains(name)) return true
+    const { names } = getBpDataMod()
+    for (const bp of names) if (el.classList.contains(`${bp}:${name}`) && isBreakpointActiveMod(bp)) return true
+    return false
+}
+const getActivePrefixedClassMod = (el, prefix) => {
+    const { names, map, re } = getBpDataMod()
+    let best = null, bestPx = -2
+    for (const c of el.classList) {
+        let bp = null, core = c
+        const m = c.match(re)
+        if (m) { bp = m[1]; core = m[2] }
+        if (!core.startsWith(prefix)) continue
+        if (bp && !isBreakpointActiveMod(bp)) continue
+        const px = bp ? map[bp] : -1
+        if (px > bestPx) { best = c; bestPx = px }
+    }
+    return best
+}
+
 // 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.
 const DEFAULT_EASE = "power3.out";
@@ -210,9 +248,9 @@ export function countTargetVars (target){
     const end = match ? parseFloat(match[0]) : 0
     const decimals = match?.[0].includes(".") ? (match[0].split(".")[1] || "").length : 0
     // Count FROM `.spawn-num-N` (N = the starting number) up to `end`. When the
-    // class is absent, fall back to 0.
-    const startCls = [...target.classList].find(c => c.startsWith("spawn-num-"))
-    const start = startCls ? parseFloat(startCls.slice("spawn-num-".length)) : 0
+    // class is absent, fall back to 0. Supports `m:spawn-num-10` etc. (mobile-first)
+    const startCls = getActivePrefixedClassMod(target, "spawn-num-")
+    const start = startCls ? parseFloat(startCls.slice(startCls.indexOf("spawn-num-") + "spawn-num-".length)) : 0
     return target._countTarget = { start, end, decimals }
 }
 
@@ -231,12 +269,12 @@ export function countUp (target , delay , dur, ease){
 // 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 m = getActivePrefixedClassMod(el, "fill-time-")
+    return m ? Number(m.slice(m.indexOf("fill-time-") + "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
+    const m = getActivePrefixedClassMod(el, "fill-ease-")
+    return m ? m.slice(m.indexOf("fill-ease-") + "fill-ease-".length) : fallbackEase
 }
 
 // Stroke-draw reveal (strokes only - filled SVGs are deliberately out of
@@ -248,13 +286,13 @@ const fillEaseOf = (el , fallbackEase) => {
 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")
+    const hasFill = !!first && hasGClassMod(first, "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 fillTargets = gsap.utils.toArray(target).filter(el => hasGClassMod(el, "fill-svg"))
     const tl = gsap.timeline({ delay })
     // Keep fill invisible while the stroke draws
     if (fillTargets.length) gsap.set(fillTargets , { fillOpacity: 0 })
@@ -332,7 +370,7 @@ export function splitPaths (paths){
 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 hasFill = !!first && hasGClassMod(first, "fill-svg")
     const fillDur = hasFill ? fillTimeOf(first , dur) : 0
     const fillEase = hasFill ? fillEaseOf(first , ease) : ease
     const tl = gsap.timeline({ delay })
@@ -397,13 +435,29 @@ export const scrambleSegments = (target) => {
 //   .reveal-delay-N  -> revealDelay in seconds (default defaults.revealDelay)
 //   .chars-[...]     -> character pool taken verbatim from inside the brackets
 //                       (default defaults.characterlist)
+//   Supports `m:amount-N`, `l:chars-[...]` etc. (largest active wins)
 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
+        const c = getActivePrefixedClassMod(target, prefix)
+        if (!c) return fallback
+        const idx = c.indexOf(prefix)
+        const n = Number(c.slice(idx + prefix.length))
+        return Number.isNaN(n) ? fallback : n
     }
     // Greedy up to the LAST "]" so pools containing "]" survive intact.
-    const charsCls = [...target.classList].find(c => /^chars-\[(.*)\]$/.test(c))
+    // Check for `m:chars-[...]` then fallback to `chars-[...]`
+    let charsCls = null
+    let bestPx = -2
+    const { re: reChars, map: mapChars } = getBpDataMod()
+    for (const c of target.classList) {
+        let bp = null, core = c
+        const m = c.match(reChars)
+        if (m) { bp = m[1]; core = m[2] }
+        if (!/^chars-\[(.*)\]$/.test(core)) continue
+        if (bp && !isBreakpointActiveMod(bp)) continue
+        const px = bp ? mapChars[bp] : -1
+        if (px > bestPx) { charsCls = core; bestPx = px }
+    }
     return {
         segs: scrambleSegments(target) ,
         chars: charsCls ? charsCls.slice("chars-[".length , -1) : defaults.characterlist ,
@@ -411,7 +465,7 @@ export function scrambleVars (target){
         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") ,
+        rtl: hasGClassMod(target, "scramble-rtl") ,
     }
 }
 
@@ -430,9 +484,9 @@ export function scrambleVars (target){
 //                       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 e = getActivePrefixedClassMod(target, "ease-") ? easeOf(ease) : "none"
     const { segs , chars , speed , revealDelay , rtl } = scrambleVars(target)
-    const all = target.classList.contains("scramble-all")
+    const all = hasGClassMod(target, "scramble-all")
     const tl = gsap.timeline({ delay })
     segs.forEach(({ t , text }) => {
         if (all) {
@@ -591,7 +645,7 @@ export function radiate (delay , target , amount , dur , ease , zIndex){
         tick = true
         requestAnimationFrame(() => { tick = false; applyRect() })
     }
-    // Don't animate detached targets — return inert tween
+    // Don't animate detached targets - return inert tween
     if (!target.isConnected) {
         return gsap.fromTo(clone, {}, { duration: 0 })
     }
@@ -609,7 +663,7 @@ export function radiate (delay , target , amount , dur , ease , zIndex){
         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
+    // kill the tween and remove the clone - mirrors React useEffect cleanup
     const observer = new MutationObserver(() => {
         if (!target.isConnected) {
             if (tween) tween.kill()

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `gclass-anims` will be documented in this file.
 
+## [1.0.0-beta.22] - 2026-09-06
+- Added responsive breakpoints — `Config.js:75` `defaults.breakpoints {xs:475,s:640,m:768,l:1024,xl:1280}` (single-letter `s/m/l` avoids Tailwind `sm/md/lg` collision). Usage `m:spawn-up`, `l:float`, `xs:spawn-up`. Gating is live via `gsap.matchMedia` (`Listeners.js:26,202`).
+- Added breakpoint-aware modifiers — `m:amount-20`, `m:time-2`, `m:ease-bounce`, `m:priority-3`, `m:chars-[...]`, `m:spawn-num-10` etc. Mobile-first largest active wins (`Listeners.js:237` `getActivePrefixedClass`, `Animations.js:13` lazy helpers). Covers `amount-`, `time-`, `priority-`, `edelay-`, `etime-`, `stagger-`, `fill-time-`, `reveal-delay-`, `spawn-num-`, `progress-start-`, etc.
+- Fixed runtime `customAnims` re-normalization — `Listeners.js:190` now calls `normalize(customAnims)` inside `initListeners()` so `customAnims.push()` before next `init` is picked up.
+- Added ESM + CJS dual build — `vite.lib.config.js` (Vite lib) builds `dist/gclass.esm.js` + `dist/gclass.cjs` (`gsap` external); `package.json:4` bumped to `beta.22`, `main/module` point to `dist/`, `exports: {import, require}`, `sideEffects:false`, `prepublishOnly: build`.
+- Fixed CJS `gsap` interop — `Animations.js:2`/`Listeners.js:1`/`AnimToggle.js:3`/`CustomAnims.js:1` now `import {gsap} from 'gsap'` (named import) for correct `require('gsap').gsap` interop.
+- Added `dev-react-strict` test harness — `vitest` + `jsdom` + `src/__tests__/breakpoints.test.jsx` (14 tests: gating, modifiers, Tailwind coexistence, StrictMode) + `BreakpointHarness.jsx` visual; `vite.config.js` test config.
+
+## [1.0.0-beta.21] - 2026-9-3
+- Added a `gclassOpts()` function that controls the animation fps and observer throttling
+
 ## [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

package/Config.js

@@ -72,6 +72,7 @@ export const defaults = {
   revealDelay:0,
   characterlist:"AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz",
   bootTime: 5,
+  breakpoints : {xs : 475 , s:640 , m:768 , l:1024 , xl:1280}
 }
 
 export const animations = [

package/CustomAnims.js

@@ -1,4 +1,4 @@
-import gsap from "gsap";
+import { gsap } from "gsap";
 
 // A custom animation is just an entry with the SAME shape as one in
 // Listeners.js' `spawnConfigs`. Give it: