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

package/AnimToggle.js

@@ -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

@@ -591,7 +591,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 +609,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,9 @@
 
 All notable changes to `gclass-anims` will be documented in this file.
 
+## [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/Listeners.js

@@ -93,7 +93,13 @@ const invokePlay = (config, el, delay, dur, ease) => {
     }
 }
 
-export default function initListeners(root = document) {
+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)
@@ -1539,38 +1545,28 @@ export default function initListeners(root = document) {
         // 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)
 
 
 
@@ -1609,7 +1605,23 @@ export default function initListeners(root = document) {
             }
         }
 
-        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
@@ -1639,20 +1651,77 @@ export default function initListeners(root = document) {
                     if (pinned) ScrollTrigger.refresh()
                 })
             })
-        })
-        appearObserver.observe(document.body, { childList: true, subtree: true })
-
-        // Capture any .leave elements already present so they can exit later
-        qAll(".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
@@ -1671,9 +1740,12 @@ export default function initListeners(root = document) {
         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)

package/index.d.ts

@@ -4,8 +4,28 @@
 
 // --- AnimToggle ------------------------------------------------------------
 
-/** Boots the GSAP animation system (idempotent). */
-export function initAnimations(): void
+export interface GClassConfig {
+  throttlePerFrame: number
+  fps: number
+}
+
+/**
+ * Boots the GSAP animation system (idempotent).
+ * @param throttlePerFrame - number of observer handlers allowed per rAF frame (0 = no throttling, default).
+ *   Also accepts initAnimations({throttlePerFrame, fps}) object overload.
+ * @param fps - GSAP ticker fps cap (0 = default rAF, e.g. 30 for low-end). 0/undefined = no cap.
+ */
+export function initAnimations(throttlePerFrame?: number | GClassConfig, fps?: number): void
+/**
+ * Change GClass runtime options on the fly without reload.
+ * gclassOpts(throttlePerFrame, fps) — both optional numbers, missing -> defaults (0).
+ * gclassOpts() resets to defaults (no throttle, default ticker).
+ * Also accepts gclassOpts({throttlePerFrame, fps}).
+ * Example low-end button: onClick={() => gclassOpts(1, 30)}
+ */
+export function gclassOpts(throttlePerFrame?: number | GClassConfig, fps?: number): GClassConfig
+export function getGClassConfig(): GClassConfig
+export function subscribeGClassConfig(cb: (cfg: GClassConfig) => void): () => void
 /** Toggle animations on/off and reload the page. */
 export function toggleAnimations(): void
 /** Force animations off (wins over any stored preference) and reload. */
@@ -28,8 +48,12 @@ export function registerComplete(name: string, fn: CompleteHandler): CompleteHan
  * Boot the engine directly, bypassing AnimToggle. Returns a teardown function
  * that removes all listeners/observers/tweens created by this run.
  * Pass a root to scope to that subtree (used for .boot-up).
+ * @param root - scope root (Document or HTMLElement)
+ * @param throttlePerFrame - number of observer handlers allowed per rAF frame.
+ *   0/undefined = no throttling (default). 1 = 1 observer per frame round-robin.
+ *   Overload: initListeners(throttlePerFrame) is also supported (root defaults to document).
  */
-export default function initListeners(root?: Document | HTMLElement): () => void
+export default function initListeners(root?: Document | HTMLElement | number, throttlePerFrame?: number): () => void
 
 // --- onComplete config -----------------------------------------------------
 

package/index.js

@@ -1,4 +1,4 @@
-export { initAnimations, toggleAnimations, enableReducedMotion, disableReducedMotion } from './AnimToggle.js'
+export { initAnimations, gclassOpts, getGClassConfig, subscribeGClassConfig, toggleAnimations, enableReducedMotion, disableReducedMotion } from './AnimToggle.js'
 export { default as initListeners, registerComplete } from './Listeners.js'
 export { customAnims } from './CustomAnims.js'
 export { defaults, animations, normalize } from './Config.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gclass-anims",
-  "version": "1.0.0-beta.20",
+  "version": "1.0.0-beta.21",
   "description": "A Tailwind-style utility layer on top of GSAP. Framework-agnostic - works in vanilla JS, React, Vue, Svelte, or any bundler.",
   "type": "module",
   "main": "index.js",