@brandocms/jupiter 5.0.0-beta.7 → 5.0.0-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandocms/jupiter",
-  "version": "5.0.0-beta.7",
+  "version": "5.0.0-beta.9",
   "description": "Frontend helpers.",
   "author": "Univers/Twined",
   "license": "UNLICENSED",
@@ -36,6 +36,7 @@
     "playwright:dataloader": "playwright test e2e/dataloader.spec.js --project=chromium  --reporter line",
     "playwright:dataloader-url-sync": "playwright test e2e/dataloader-url-sync.spec.js --project=chromium  --reporter line",
     "playwright:parallax": "playwright test e2e/parallax.spec.js --project=chromium  --reporter line",
+    "playwright:looper": "playwright test e2e/looper.spec.js --project=chromium  --reporter line",
     "vite": "vite",
     "vite:build": "vite build",
     "vite:preview": "vite preview"

package/src/modules/Cookies/index.js

@@ -3,6 +3,91 @@ import _defaultsDeep from 'lodash.defaultsdeep'
 import * as Events from '../../events'
 import { set } from '../../utils/motion-helpers'
 
+/**
+ * @module Cookies
+ *
+ * Cookie consent module with optional dialog and toggle button support.
+ *
+ * ## Consent dialog
+ *
+ * The traditional consent banner uses a fixed container at the bottom of the page:
+ *
+ * ```html
+ * <div class="cookie-container">
+ *   <div class="cookie-container-inner">
+ *     <div class="cookie-law-text">
+ *       <p>We use cookies...</p>
+ *     </div>
+ *     <div class="cookie-law-buttons">
+ *       <button class="dismiss-cookielaw">Accept</button>
+ *       <button class="refuse-cookielaw">Decline</button>
+ *     </div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * ## Consent toggle button
+ *
+ * A toggle button can be placed anywhere on the page to let users change their
+ * consent at any time. It can also serve as the sole consent mechanism (no
+ * dialog required).
+ *
+ * ```html
+ * <button data-cookie-consent
+ *         data-cookie-consent-accept="Accept cookies"
+ *         data-cookie-consent-refuse="Refuse cookies">
+ * </button>
+ * ```
+ *
+ * ### Data attributes
+ *
+ * | Attribute | Description |
+ * |---|---|
+ * | `data-cookie-consent` | Marks the element as a consent toggle |
+ * | `data-cookie-consent-accept` | Label shown when user can accept (currently refused/unset) |
+ * | `data-cookie-consent-refuse` | Label shown when user can retract (currently accepted) |
+ * | `data-cookie-consent-status` | Set by the module: `"accepted"` or `"refused"` |
+ * | `data-cookie-consent-icon` | Set on the injected icon `<span>` |
+ * | `data-cookie-consent-label` | Set on the injected label `<span>` |
+ *
+ * ### CSS styling
+ *
+ * ```css
+ * [data-cookie-consent-status="accepted"] [data-cookie-consent-icon] { color: green; }
+ * [data-cookie-consent-status="refused"] [data-cookie-consent-icon] { color: red; }
+ * ```
+ *
+ * ### Gettext / translation
+ *
+ * ```html
+ * <button data-cookie-consent
+ *         data-cookie-consent-accept="{{ _('Accept cookies') }}"
+ *         data-cookie-consent-refuse="{{ _('Refuse cookies') }}">
+ * </button>
+ * ```
+ *
+ * ## Usage examples
+ *
+ * Dialog only (default):
+ * ```js
+ * new Cookies(app)
+ * ```
+ *
+ * Toggle only (no dialog HTML needed):
+ * ```js
+ * new Cookies(app, { setCookies: (c) => { ... } })
+ * ```
+ *
+ * Both dialog and toggle:
+ * ```js
+ * new Cookies(app, {
+ *   onConsentChanged: (c) => {
+ *     console.log(c.getCookie('COOKIES_CONSENT_STATUS'))
+ *   }
+ * })
+ * ```
+ */
+
 /**
  * @typedef {Object} CookiesOptions
  * @property {Function} [onAccept] - Called when cookies are accepted
@@ -11,6 +96,7 @@ import { set } from '../../utils/motion-helpers'
  * @property {Function} [alreadyRefused] - Called if user has already refused cookies
  * @property {Function} [setCookies] - Custom function to set cookies
  * @property {Function} [showCC] - Custom function to display cookie consent dialog
+ * @property {Function} [onConsentChanged] - Called after consent is toggled via the toggle button
  */
 
 /** @type {CookiesOptions} */
@@ -21,6 +107,7 @@ const DEFAULT_OPTIONS = {
 
     c.setCookie('COOKIES_CONSENT_STATUS', 1, oneYearFromNow, '/')
     c.opts.setCookies(c)
+    c.updateConsentToggles()
 
     const timeline = [
       [c.cc, { y: '120%' }, { duration: 0.35, ease: 'easeIn', at: 0 }],
@@ -37,6 +124,7 @@ const DEFAULT_OPTIONS = {
     oneYearFromNow.setFullYear(oneYearFromNow.getFullYear() + 1)
 
     c.setCookie('COOKIES_CONSENT_STATUS', 0, oneYearFromNow, '/')
+    c.updateConsentToggles()
 
     const timeline = [
       [c.cc, { y: '120%' }, { duration: 0.35, ease: 'easeIn', at: 0 }],
@@ -58,6 +146,8 @@ const DEFAULT_OPTIONS = {
 
   setCookies: (c) => {},
 
+  onConsentChanged: (c) => {},
+
   showCC: (c) => {
     if (c.hasCookie('COOKIES_CONSENT_STATUS')) {
       if (c.getCookie('COOKIES_CONSENT_STATUS') === '1') {
@@ -107,22 +197,114 @@ export default class Cookies {
     this.btn = document.querySelector('.dismiss-cookielaw')
     this.btnRefuse = document.querySelector('.refuse-cookielaw')
 
-    if (!this.btn) {
+    this.setupConsentToggles()
+
+    if (!this.btn && this.consentToggles.length === 0) {
       return
     }
 
-    this.app.registerCallback(Events.APPLICATION_REVEALED, () => {
-      this.opts.showCC(this)
+    if (this.btn) {
+      this.app.registerCallback(Events.APPLICATION_REVEALED, () => {
+        this.opts.showCC(this)
+      })
+
+      this.btn.addEventListener('click', () => {
+        this.opts.onAccept(this)
+      })
+      if (this.btnRefuse) {
+        this.btnRefuse.addEventListener('click', () => {
+          this.opts.onRefuse(this)
+        })
+      }
+    }
+  }
+
+  /**
+   * Find all `[data-cookie-consent]` elements and wire them up.
+   */
+  setupConsentToggles() {
+    this.consentToggles = [...document.querySelectorAll('[data-cookie-consent]')]
+
+    this.consentToggles.forEach(el => {
+      const icon = document.createElement('span')
+      icon.setAttribute('data-cookie-consent-icon', '')
+
+      const label = document.createElement('span')
+      label.setAttribute('data-cookie-consent-label', '')
+
+      el.appendChild(icon)
+      el.appendChild(label)
+
+      this.updateConsentToggle(el)
+
+      el.addEventListener('click', () => {
+        this.handleConsentToggle()
+      })
     })
+  }
 
-    this.btn.addEventListener('click', () => {
-      this.opts.onAccept(this)
+  /**
+   * Update a single consent toggle element to reflect current cookie state.
+   * @param {Element} el - The toggle element
+   */
+  updateConsentToggle(el) {
+    const accepted = this.getCookie('COOKIES_CONSENT_STATUS') === '1'
+    const acceptText = el.getAttribute('data-cookie-consent-accept') || 'Accept cookies'
+    const refuseText = el.getAttribute('data-cookie-consent-refuse') || 'Refuse cookies'
+
+    const icon = el.querySelector('[data-cookie-consent-icon]')
+    const label = el.querySelector('[data-cookie-consent-label]')
+
+    if (accepted) {
+      el.setAttribute('data-cookie-consent-status', 'accepted')
+      icon.textContent = '\u2713'
+      label.textContent = refuseText
+    } else {
+      el.setAttribute('data-cookie-consent-status', 'refused')
+      icon.textContent = '\u2715'
+      label.textContent = acceptText
+    }
+  }
+
+  /**
+   * Update all consent toggle elements.
+   */
+  updateConsentToggles() {
+    this.consentToggles.forEach(el => {
+      this.updateConsentToggle(el)
     })
-    if (this.btnRefuse) {
-      this.btnRefuse.addEventListener('click', () => {
-        this.opts.onRefuse(this)
+  }
+
+  /**
+   * Handle a click on a consent toggle button.
+   */
+  handleConsentToggle() {
+    const oneYearFromNow = new Date()
+    oneYearFromNow.setFullYear(oneYearFromNow.getFullYear() + 1)
+
+    const accepted = this.getCookie('COOKIES_CONSENT_STATUS') === '1'
+
+    if (accepted) {
+      this.setCookie('COOKIES_CONSENT_STATUS', 0, oneYearFromNow, '/')
+    } else {
+      this.setCookie('COOKIES_CONSENT_STATUS', 1, oneYearFromNow, '/')
+      this.opts.setCookies(this)
+    }
+
+    this.updateConsentToggles()
+
+    if (this.cc && this.cc.style.display !== 'none') {
+      const timeline = [
+        [this.cc, { y: '120%' }, { duration: 0.35, ease: 'easeIn', at: 0 }],
+        [this.inner, { opacity: 0 }, { duration: 0.3, ease: 'easeIn', at: 0 }]
+      ]
+
+      animate(timeline).finished.then(() => {
+        this.cc.style.display = 'none'
       })
     }
+
+    this.opts.onConsentChanged(this)
   }
 
   /**

package/src/modules/Lazyload/index.js

@@ -209,7 +209,10 @@ export default class Lazyload {
     images.forEach(img => this.swapImage(img))
 
     const pictures = Dom.all($container, '[data-ll-srcset]')
-    pictures.forEach(picture => this.revealPicture(picture))
+    pictures.forEach(picture => {
+      this.loadPicture(picture)
+      this.revealPicture(picture)
+    })
   }
 
   initializeResizeObserver() {

package/src/modules/Looper/index.js

@@ -77,9 +77,7 @@ function horizontalLoop(app, items, config) {
   let originalItemsWidth = 0 // Width of ONLY original items (for wrapping)
   let pixelsPerSecond = (config.speed || 1) * 100
   let animation = null
-  let position = motionValue(0) // Source of truth for position
-  let boundedPos = motionValue(0) // Bounded position (0 to originalItemsWidth)
-  let lastBoundedValue = 0 // Track last value to detect wraps
+  let position = motionValue(0) // Source of truth for position (raw, unbounded)
   let originalItemCount = 0 // Track count of ORIGINAL items (before clones)
   let maxScrollPosition = 0 // For non-looping: max scroll where last item is at right edge
 
@@ -174,9 +172,9 @@ function horizontalLoop(app, items, config) {
     let count = 0
     let previousTotalWidth = totalWidth
 
-    // Always create at least one set of clones - the wrapping logic depends on clones existing
+    // Always create at least TWO sets of clones - needed for starting at first clone position
     // Then continue until we have enough width for seamless looping
-    while ((count === 0 || totalWidth < minRequiredWidth) && count < maxReplications) {
+    while ((count < 2 || totalWidth < minRequiredWidth) && count < maxReplications) {
       // Clone ONLY original items
       for (let i = 0; i < originalItemCount; i++) {
         const clone = items[i].cloneNode(true)
@@ -184,28 +182,9 @@ function horizontalLoop(app, items, config) {
         container.appendChild(clone)
         items.push(clone)
 
-        // Register cloned lazyload elements with Lazyload module if available
-        if (app?.lazyload?.observe) {
-          // Clear data-ll-idx from unloaded [data-ll-image] images
-          clone.querySelectorAll('[data-ll-image]:not([data-ll-loaded])').forEach(img => {
-            img.removeAttribute('data-ll-idx')
-          })
-
-          // Clear attributes from unloaded [data-ll-srcset] pictures so they can be re-observed
-          clone.querySelectorAll('[data-ll-srcset]:not([data-ll-srcset-ready])').forEach(picture => {
-            picture.removeAttribute('data-ll-srcset-initialized')
-            // Clear ready state from sources and img so they can be re-processed
-            picture.querySelectorAll('source').forEach(source => {
-              source.removeAttribute('data-ll-ready')
-            })
-            picture.querySelectorAll('img').forEach(img => {
-              img.removeAttribute('data-ll-idx')
-              img.removeAttribute('data-ll-loaded')
-              img.removeAttribute('data-ll-ready')
-            })
-          })
-
-          app.lazyload.observe(clone)
+        // Force-load cloned lazyload elements immediately to prevent flash on wrap
+        if (app?.lazyload?.forceLoad) {
+          app.lazyload.forceLoad(clone)
         }
       }
 
@@ -358,84 +337,48 @@ function horizontalLoop(app, items, config) {
 
   /**
    * Check item positions and wrap when needed
-   * Container is animated DIRECTLY (not updated here!)
-   * This function only reads position to determine wrapping
-   * @param {number} pos - Current position value (can grow infinitely)
+   * Container uses RAW position - items wrap individually when far off-screen
+   * @param {number} rawPos - Current raw position value (unbounded)
    */
-  function updateItemPositions(pos) {
-    const containerElement = items[0].parentElement
-
-    if (!shouldLoop) {
-      // Non-looping: we'll handle this with direct animation
-      return
-    }
-
-    // Calculate bounded position for checking item wrap points
-    // Use same wrapping formula as frame.render to handle negative positions (reversed mode)
-    const boundedPos = ((pos % originalItemsWidth) + originalItemsWidth) % originalItemsWidth
+  function updateItemPositions(rawPos) {
+    if (!shouldLoop) return
 
     // Initialize wrap offsets cache if needed
     if (itemWrapOffsets.length === 0) {
       itemWrapOffsets = new Array(items.length).fill(0)
     }
 
-    // TICKER PATTERN: ONLY move ORIGINAL items to the back, NEVER touch clones!
-    // This massively reduces DOM manipulation and style recalculation
-    items.forEach((item, i) => {
-      // Skip clones - they stay in natural flow! (use cached value for performance)
-      if (isCloneCache[i]) {
-        return
-      }
+    // Items wrap by the full cycle distance (totalWidth) to maintain relative positions
+    // This keeps all items within viewing distance as position grows/shrinks
+    const cycleDistance = totalWidth
 
-      // Calculate where this ORIGINAL item is on screen (relative to bounded container)
-      const itemLeft = offsetLefts[i] - boundedPos
-
-      // Original items only ever have -totalWidth, 0, or +totalWidth offset
-      // This positions them AFTER all clones (not just after wrapping area)
-      let newOffset = 0
-
-      // Ticker boundary pattern: Check if item should be at the END or at the START
-      // When container cycles (boundedPos wraps from ~originalItemsWidth to ~0),
-      // items with large offsets get reset back to 0
-
-      // Wrap distance includes the trailing gap for seamless cycling
-      const wrapOffset = totalWidth + gap
-
-      // Check if we're in the "reset zone" near wrap boundaries
-      const nearForwardWrap = boundedPos > originalItemsWidth - gap
-      const nearReverseWrap = boundedPos < gap
-
-      // RESET: When in reset zone, reset items and SKIP wrap checks to avoid fighting
-      if (nearForwardWrap && itemWrapOffsets[i] === wrapOffset) {
-        // Container about to wrap (forward), reset items at END back to START
-        newOffset = 0
-      } else if (nearReverseWrap && itemWrapOffsets[i] === -wrapOffset) {
-        // Container about to wrap (reverse), reset items at START back to END
-        newOffset = 0
-      } else if (nearForwardWrap || nearReverseWrap) {
-        // In reset zone but item doesn't need reset → keep current offset
-        newOffset = itemWrapOffsets[i]
-      } else if (itemLeft < -(widths[i] + containerWidth * 0.5)) {
-        // Item exited LEFT edge - only wrap during forward scroll
-        // During reverse scroll (scrollDirection < 0), items off-screen left
-        // will naturally scroll back into view - don't wrap them
-        const isForwardScroll = scrollDirection >= 0
-        newOffset = (isForwardScroll && boundedPos < originalItemsWidth / 2) ? wrapOffset : 0
-      } else if (itemLeft > containerWidth + containerWidth * 0.5) {
-        // Item exited RIGHT edge
-        // This shouldn't happen much, but handle it
-        newOffset = 0
-      } else {
-        // Keep current offset
-        newOffset = itemWrapOffsets[i]
+    // Wrap threshold: when an item is more than half a cycle from view, wrap it
+    const wrapThreshold = cycleDistance / 2
+
+    for (let i = 0; i < items.length; i++) {
+      // Calculate this item's effective position (DOM position + wrap offset)
+      const effectivePos = offsetLefts[i] + itemWrapOffsets[i]
+
+      // Distance from current view position
+      // Positive = item is ahead (to the right), Negative = item is behind (to the left)
+      const distanceFromView = effectivePos - rawPos
+
+      let newOffset = itemWrapOffsets[i]
+
+      if (distanceFromView < -wrapThreshold) {
+        // Item is too far left (behind), wrap it forward (to the right)
+        newOffset = itemWrapOffsets[i] + cycleDistance
+      } else if (distanceFromView > wrapThreshold + containerWidth) {
+        // Item is too far right (ahead), wrap it backward (to the left)
+        newOffset = itemWrapOffsets[i] - cycleDistance
       }
 
-      // ONLY update transform if the offset has changed!
+      // Only update DOM if offset changed
       if (newOffset !== itemWrapOffsets[i]) {
-        item.style.transform = newOffset !== 0 ? `translateX(${newOffset}px)` : 'none'
+        items[i].style.transform = newOffset !== 0 ? `translateX(${newOffset}px)` : 'none'
         itemWrapOffsets[i] = newOffset
       }
-    })
+    }
   }
 
   /**
@@ -443,32 +386,58 @@ function horizontalLoop(app, items, config) {
    * @param {boolean} deep - Whether to rebuild animation (on resize)
    */
   function refresh(deep = false) {
-    // Save progress to preserve position
-    const progress = animation ? animation.time / animation.duration : 0
-    const currentPos = position.get()
-
     // Pause animation if running
     const wasPlaying = animation && animation.speed !== 0
     if (animation) {
       animation.pause()
     }
 
+    if (deep && shouldLoop) {
+      // DEEP REFRESH: Reset everything for new dimensions
+      // Clear all item wrap offsets and transforms
+      for (let i = 0; i < items.length; i++) {
+        items[i].style.transform = 'none'
+        if (itemWrapOffsets[i] !== undefined) {
+          itemWrapOffsets[i] = 0
+        }
+      }
+      itemWrapOffsets = []
+    }
+
     // Remeasure everything
     populateWidths()
 
     if (deep) {
       // Check if we need to replicate more items
-      const containerWidth = container.offsetWidth
+      const currentContainerWidth = container.offsetWidth
       const currentTotalWidth = getTotalWidthOfItems()
 
       // Use same 2.5x buffer as replication logic
-      if (shouldLoop && currentTotalWidth < containerWidth * 2.5) {
+      if (shouldLoop && currentTotalWidth < currentContainerWidth * 2.5) {
         replicateItemsIfNeeded()
+        // Re-cache clone status for any new items
+        isCloneCache = items.map((item, i) => i >= originalItemCount)
         populateWidths()
       }
 
       populateSnapTimes()
 
+      // Reset position to start at first clone (like initial state)
+      if (shouldLoop && !config.centerSlide) {
+        position.set(originalItemsWidth)
+        lastPositionForDirection = originalItemsWidth
+        items[0].parentElement.style.transform = `translateX(${-originalItemsWidth}px)`
+      } else if (shouldLoop && config.centerSlide) {
+        // For center mode, go to middle slide
+        const middleIndex = Math.floor(originalItemCount / 2)
+        const targetTime = times[middleIndex]
+        const initialPos = targetTime * pixelsPerSecond
+        position.set(initialPos)
+        lastPositionForDirection = initialPos
+        items[0].parentElement.style.transform = `translateX(${-initialPos}px)`
+        curIndex = middleIndex
+      }
+
       // Recreate animation with new measurements
       if (shouldLoop && config.crawl) {
         // Stop old animation
@@ -476,7 +445,7 @@ function horizontalLoop(app, items, config) {
           animation.stop()
         }
 
-        // Use startLoopAnimation for bounded position (no repeat: Infinity!)
+        // Recreate loop animation with new measurements
         animation = startLoopAnimation()
 
         // Restore playback state
@@ -499,19 +468,20 @@ function horizontalLoop(app, items, config) {
         })
 
         if (wasPlaying) {
-          animation.time = progress * animation.duration
           animation.play()
         } else {
           animation.pause()
         }
       }
+
+      // Update index display
+      updateIndexDisplay()
     } else {
       // Light refresh - just update measurements
       populateSnapTimes()
+      // Update positions based on current scroll
+      updateItemPositions(position.get())
     }
-
-    // Update positions based on current scroll
-    updateItemPositions(currentPos)
   }
 
   /**
@@ -541,7 +511,7 @@ function horizontalLoop(app, items, config) {
       : currentPos + originalItemsWidth
 
     // Animate the position motionValue
-    // frame.render loop will apply bounded position to DOM
+    // frame.render loop will apply raw position to container and wrap items
     animation = animate(position, target, {
       duration,
       repeat: Infinity,
@@ -551,6 +521,21 @@ function horizontalLoop(app, items, config) {
     return animation
   }
 
+  /**
+   * Stop the frame.render loop and cleanup listeners
+   * Called from init() and destroy()
+   */
+  function stopRenderLoop() {
+    if (renderUnsubscribe) {
+      // Unsubscribe from motionValue listener
+      if (renderUnsubscribe.positionUnsubscribe) {
+        renderUnsubscribe.positionUnsubscribe()
+      }
+      cancelFrame(renderUnsubscribe)
+      renderUnsubscribe = null
+    }
+  }
+
   /**
    * Initialize the loop animation
    */
@@ -571,82 +556,45 @@ function horizontalLoop(app, items, config) {
     // Set initial container position
     const containerElement = items[0].parentElement
     containerElement.style.willChange = 'transform'
-    containerElement.style.transform = 'translateX(0px)'
 
-    // Set up RAF loop to check item positions for wrapping
-    // Frame.render loop to apply bounded position to DOM
+    // For looping (non-center mode): start viewing first CLONE, not originals
+    // This positions originals OFF-SCREEN LEFT so backward scroll reveals them smoothly
+    if (shouldLoop && !config.centerSlide) {
+      position.set(originalItemsWidth)
+      lastPositionForDirection = originalItemsWidth
+      containerElement.style.transform = `translateX(${-originalItemsWidth}px)`
+    } else {
+      containerElement.style.transform = 'translateX(0px)'
+    }
+
+    // Set up RAF loop to update container position and wrap items
+    // Uses RAW position (no modulo) for container transform
     // This is Motion's optimized render loop - prevents layout thrashing
     function startRenderLoop() {
       if (renderUnsubscribe) return // Already running
 
       const containerElement = items[0].parentElement
 
-      // Set up boundedPos motionValue to automatically sync with position
-      // This calculates the bounded position (0 to originalItemsWidth)
+      // Track scroll direction for wrap logic
       const positionUnsubscribe = position.on('change', latest => {
-        // Track scroll direction for wrap logic
         const delta = latest - lastPositionForDirection
         if (Math.abs(delta) > 1) {
           scrollDirection = delta > 0 ? 1 : -1
         }
         lastPositionForDirection = latest
-
-        const bounded = ((latest % originalItemsWidth) + originalItemsWidth) % originalItemsWidth
-        boundedPos.set(bounded)
-      })
-
-      // Detect when boundedPos wraps (makes large jump) and reset all items
-      // This prevents stuck items during fast drags in either direction
-      const boundedPosUnsubscribe = boundedPos.on('change', latest => {
-        const delta = Math.abs(latest - lastBoundedValue)
-
-        // If boundedPos jumped by more than 40% of the width, it wrapped
-        // Using 40% instead of 50% to catch edge cases
-        const didWrap = delta > originalItemsWidth * 0.4
-
-        if (didWrap) {
-          // NOTE: We intentionally do NOT reset item transforms here anymore.
-          // Resetting here caused flash because it happens between render frames.
-          // The updateItemPositions() in frame.render handles wrapping correctly
-          // when called with the new boundedPos.
-
-          // Sync position to bounded value (only when not dragging/animating)
-          if (!snapAnimation && !navAnimation && !isDragging) {
-            position.set(latest)
-          }
-        }
-
-        lastBoundedValue = latest
       })
 
       renderUnsubscribe = frame.render(() => {
-        // Read bounded position from motionValue
-        const currentBoundedPos = boundedPos.get()
-
-        // Apply bounded transform to container
-        containerElement.style.transform = `translateX(${-currentBoundedPos}px)`
+        // Use RAW position (no bounded) for container
+        const currentPos = position.get()
+        containerElement.style.transform = `translateX(${-currentPos}px)`
 
-        // Wrap items based on bounded position
-        updateItemPositions(currentBoundedPos)
+        // Wrap items based on raw position
+        updateItemPositions(currentPos)
       }, true) // true = keep alive
 
-      // Store unsubscribe functions for cleanup
+      // Store unsubscribe function for cleanup
       renderUnsubscribe.positionUnsubscribe = positionUnsubscribe
-      renderUnsubscribe.boundedPosUnsubscribe = boundedPosUnsubscribe
-    }
-
-    function stopRenderLoop() {
-      if (renderUnsubscribe) {
-        // Unsubscribe from motionValue listeners
-        if (renderUnsubscribe.positionUnsubscribe) {
-          renderUnsubscribe.positionUnsubscribe()
-        }
-        if (renderUnsubscribe.boundedPosUnsubscribe) {
-          renderUnsubscribe.boundedPosUnsubscribe()
-        }
-        cancelFrame(renderUnsubscribe)
-        renderUnsubscribe = null
-      }
     }
 
     // Start the frame.render loop
@@ -734,7 +682,7 @@ function horizontalLoop(app, items, config) {
         // Update display in real-time as position changes
         let lastDisplayedIndex = -1
         const updateIndexOnChange = () => {
-          // Find closest slide to current bounded position
+          // Find closest slide to current position
           const closest = closestIndex(false)
 
           // Only update DOM if index changed (avoid thrashing)
@@ -747,12 +695,8 @@ function horizontalLoop(app, items, config) {
           }
         }
 
-        // For looping, use boundedPos; for non-looping, use position directly
-        if (shouldLoop) {
-          boundedPos.on('change', updateIndexOnChange)
-        } else {
-          position.on('change', updateIndexOnChange)
-        }
+        // Update index display whenever position changes (closestIndex normalizes internally)
+        position.on('change', updateIndexOnChange)
       }
     }
 
@@ -922,9 +866,9 @@ function horizontalLoop(app, items, config) {
       const newPosition = startPosition + deltaX
 
       // Update position motionValue
-      // frame.render loop will apply bounded transform to DOM
+      // frame.render loop applies raw position to container
       if (shouldLoop) {
-        // For looping, allow unbounded position (frame.render will bound it)
+        // For looping, position grows freely - items wrap as groups
         position.set(newPosition)
       } else {
         // For non-looping, clamp position to maxScrollPosition (last item at right edge)
@@ -1513,13 +1457,18 @@ function horizontalLoop(app, items, config) {
       closestIndex(true)
       let nextIndex = curIndex + 1
 
-      // Non-looping: reset to start when reaching the end
+      // Non-looping: clamp at boundaries
       if (!shouldLoop) {
         const currentPos = position.get()
         const atEnd = currentPos >= maxScrollPosition - 1
 
         if (nextIndex >= originalItemCount || atEnd) {
-          nextIndex = 0
+          // Autoplay resets to start, user navigation clamps
+          if (options.autoplay) {
+            nextIndex = 0
+          } else {
+            return // Clamp - do nothing at boundary
+          }
         }
       }
 
@@ -1535,9 +1484,14 @@ function horizontalLoop(app, items, config) {
       closestIndex(true)
       let prevIndex = curIndex - 1
 
-      // Non-looping: reset to end when at the start
+      // Non-looping: clamp at boundaries
       if (!shouldLoop && prevIndex < 0) {
-        prevIndex = originalItemCount - 1
+        // Autoplay resets to end, user navigation clamps
+        if (options.autoplay) {
+          prevIndex = originalItemCount - 1
+        } else {
+          return // Clamp - do nothing at boundary
+        }
       }
 
       return toIndex(prevIndex, vars)

package/types/index.d.ts

@@ -3,4 +3,4 @@ import imagesAreLoaded from './utils/imagesAreLoaded';
 import loadScript from './utils/loadScript';
 import prefersReducedMotion from './utils/prefersReducedMotion';
 import rafCallback from './utils/rafCallback';
-export { Application, Breakpoints, Cookies, CoverOverlay, Dataloader, Dom, DoubleHeader, Draggable, Dropdown, EqualHeightElements, EqualHeightImages, Events, FixedHeader, FooterReveal, Parallax, HeroSlider, HeroVideo, Lazyload, Lightbox, Links, Looper, Marquee, MobileMenu, Moonwalk, Popover, Popup, ScrollSpy, StackedBoxes, StickyHeader, Toggler, Typography, imageIsLoaded, imagesAreLoaded, loadScript, prefersReducedMotion, rafCallback, _defaultsDeep };
+export { Application, Breakpoints, Cookies, CoverOverlay, Dataloader, Dom, DoubleHeader, Dropdown, EqualHeightElements, EqualHeightImages, Events, FixedHeader, FooterReveal, Parallax, HeroSlider, HeroVideo, Lazyload, Lightbox, Links, Looper, Marquee, MobileMenu, Moonwalk, Popover, Popup, ScrollSpy, StackedBoxes, StickyHeader, Toggler, Typography, imageIsLoaded, imagesAreLoaded, loadScript, prefersReducedMotion, rafCallback, _defaultsDeep, animate, scroll, stagger, motionValue };

package/types/modules/Cookies/index.d.ts

@@ -16,6 +16,24 @@ export default class Cookies {
     btns: Element;
     btn: Element;
     btnRefuse: Element;
+    /**
+     * Find all `[data-cookie-consent]` elements and wire them up.
+     */
+    setupConsentToggles(): void;
+    consentToggles: Element[];
+    /**
+     * Update a single consent toggle element to reflect current cookie state.
+     * @param {Element} el - The toggle element
+     */
+    updateConsentToggle(el: Element): void;
+    /**
+     * Update all consent toggle elements.
+     */
+    updateConsentToggles(): void;
+    /**
+     * Handle a click on a consent toggle button.
+     */
+    handleConsentToggle(): void;
     /**
      * Get a cookie value by key
      * @param {string} sKey - Cookie key
@@ -78,4 +96,8 @@ export type CookiesOptions = {
      * - Custom function to display cookie consent dialog
      */
     showCC?: Function;
+    /**
+     * - Called after consent is toggled via the toggle button
+     */
+    onConsentChanged?: Function;
 };

package/types/modules/DoubleHeader/index.d.ts

@@ -20,6 +20,7 @@ export default class DoubleHeader {
     mobileMenuOpen: boolean;
     timer: any;
     resetResizeTimer: any;
+    scrollSettleTimeout: NodeJS.Timeout;
     firstReveal: boolean;
     initialize(): void;
     setupObserver(): void;

package/types/modules/Dropdown/index.d.ts

@@ -5,9 +5,9 @@ export default class Dropdown {
     elements: {};
     open: boolean;
     element: any;
-    timeline: any;
     handleDocumentClick(event: any): void;
     initialize(): void;
+    positionMenu(): void;
     onClick(event: any): Promise<void>;
     openMenu(): Promise<void>;
     closeMenu(): Promise<void>;

package/types/modules/FixedHeader/index.d.ts

@@ -30,6 +30,7 @@ export default class FixedHeader {
     mobileMenuOpen: boolean;
     timer: any;
     resetResizeTimer: any;
+    scrollSettleTimeout: NodeJS.Timeout;
     intersectingElements: any;
     initialize(): void;
     pageIsScrolledOnReady: boolean;

package/types/modules/HeroSlider/index.d.ts

@@ -19,10 +19,20 @@ export default class HeroSlider {
      * Switches between slides
      */
     slide(type: any): void;
+    _currentAnimation: any;
     /**
      * Add a window resize handler that resizes slide widths
      */
     _addResizeHandler(): void;
     observer: IntersectionObserver;
     _resizeSlides(): void;
+    resizeAnimation: any;
+    /**
+     * Add a visibility change handler to restart animations when tab becomes visible
+     */
+    _addVisibilityHandler(): void;
+    /**
+     * Reset slide states and restart the animation cycle
+     */
+    _resetAndRestart(): void;
 }

package/types/modules/Lazyload/index.d.ts

@@ -15,6 +15,13 @@ export default class Lazyload {
     rafId: number;
     srcsetReadyObserver: MutationObserver;
     watch(): void;
+    /**
+     * Observe new lazyload elements within a container
+     * Handles both [data-ll-image] and [data-ll-srcset] elements
+     * Useful for dynamically added content (e.g., Looper clones)
+     * @param {HTMLElement|HTMLElement[]|NodeList} elements - Container element(s) or lazyload element(s) to observe
+     */
+    observe(elements: HTMLElement | HTMLElement[] | NodeList): void;
     initialize(): void;
     lazyPictures: any;
     loadObserver: IntersectionObserver;

package/types/modules/Lightbox/index.d.ts

@@ -19,8 +19,8 @@ export default class Lightbox {
     firstTransition: boolean;
     previousCaption: any;
     timelines: {
-        caption: any;
-        image: any;
+        caption: PausedTimeline;
+        image: PausedTimeline;
     };
     showBox(section: any, index: any): void;
     buildBox(section: any, index: any): void;
@@ -121,3 +121,4 @@ export type LightboxOptions = {
      */
     onClose?: Function;
 };
+import { PausedTimeline } from '../../utils/motion-helpers';

package/types/modules/Looper/index.d.ts

@@ -1,127 +1,14 @@
 /**
- * Options for configuring the Looper module
- */
-export interface LooperOptions {
-  /** Center the loop container. Can be true, false, or a selector string */
-  center?: boolean | string;
-  /** Enable snap-to-item behavior. Can be true, false, or a number for custom snap distance */
-  snap?: boolean | number;
-  /** Enable continuous auto-scrolling */
-  crawl?: boolean;
-  /** Enable infinite looping. If false, creates linear scrolling */
-  loop?: boolean;
-  /** Enable drag interaction with mouse/touch */
-  draggable?: boolean;
-  /** Speed multipliers for different breakpoints */
-  speed?: {
-    sm?: number;
-    lg?: number;
-  };
-  /** Easing configuration for hover interactions */
-  ease?: {
-    mouseOver?: {
-      speed?: number;
-      duration?: number;
-    };
-    mouseOut?: {
-      speed?: number;
-      duration?: number;
-    };
-  };
-  /** CSS selector for looper elements */
-  selector?: string;
-  /** Extra padding on the right side in pixels */
-  paddingRight?: number | string;
-  /** Start in reversed direction */
-  reversed?: boolean;
-}
-
-/**
- * Loop controller returned by horizontalLoop function
- */
-export interface LoopController {
-  /** Motion value tracking the current position */
-  position: any;
-  /** Main animation instance */
-  animation: any;
-  /** Array of item elements */
-  items: HTMLElement[];
-  /** Array of snap time positions */
-  times: number[];
-  /** Whether the loop is reversed */
-  isReversed: boolean;
-  /** Whether the loop is in looping mode */
-  isLooping: boolean;
-
-  /** Start/resume the loop animation */
-  play(): void;
-
-  /** Pause the loop animation */
-  pause(): void;
-
-  /** Get the current active item index */
-  current(): number;
-
-  /** Find the closest item index to current position */
-  closestIndex(setCurrent?: boolean): number;
-
-  /** Navigate to the next item */
-  next(vars?: { duration?: number; easing?: string }): any;
-
-  /** Navigate to the previous item */
-  previous(vars?: { duration?: number; easing?: string }): any;
-
-  /** Navigate to a specific item index */
-  toIndex(index: number, vars?: { duration?: number; easing?: string }): any;
-
-  /** Refresh measurements and recalculate (useful after resize) */
-  refresh(deep?: boolean): void;
-
-  /** Clean up and destroy the loop */
-  destroy(): void;
-}
-
-/**
- * Looper Module
- * Creates seamless horizontal infinite scrolling carousels with drag interaction,
- * momentum/inertia, auto-crawl, snap-to-item, and responsive resize handling
+ * Looper Module Class
  */
 export default class Looper {
-  /**
-   * Create a new Looper instance
-   * @param app - Jupiter application instance
-   * @param opts - Configuration options
-   */
-  constructor(app: any, opts?: Partial<LooperOptions>);
-
-  /** Configuration options */
-  opts: LooperOptions;
-
-  /** Jupiter application instance */
-  app: any;
-
-  /** Array of active loop controllers */
-  loopers: LoopController[];
-
-  /** Array of pending loopers waiting for initialization */
-  pendingLoopers: any[];
-
-  /** DOM elements matching the selector */
-  looperElements: HTMLElement[];
-
-  /**
-   * Initialize the module and find all looper elements
-   */
-  init(): void;
-
-  /**
-   * Finalize loopers after APPLICATION:REVEALED event
-   * This is when actual measurements and animations are set up
-   */
-  finalizeLoopers(): void;
-
-  /**
-   * Destroy all loopers and clean up
-   */
-  destroy(): void;
+    constructor(app: any, opts?: {});
+    app: any;
+    opts: any;
+    loopers: any[];
+    pendingLoopers: any[];
+    init(): void;
+    looperElements: any;
+    finalizeLoopers(): void;
+    destroy(): void;
 }

package/types/modules/Marquee/index.d.ts

@@ -11,6 +11,7 @@ export default class Marquee {
     duration: number;
     clearHolders(): void;
     killTweens(): void;
+    speedAnimation: any;
     initializeTween(): void;
     play(rampUp?: boolean): void;
     playing: boolean;
@@ -19,5 +20,6 @@ export default class Marquee {
     speedUp(): void;
     setupObserver(): void;
     fillText(): void;
+    measuredHeight: any;
     setHeight(): void;
 }

package/types/modules/Moonwalk/index.d.ts

@@ -15,7 +15,11 @@ export default class Moonwalk {
         id: string;
         el: any;
         name: any;
-        timeline: any;
+        animation: {
+            lastDelay: number;
+            lastDuration: number;
+            lastStartTime: any;
+        };
         observer: any;
         stage: {
             name: any;
@@ -91,7 +95,11 @@ export default class Moonwalk {
         id: string;
         el: any;
         name: any;
-        timeline: any;
+        animation: {
+            lastDelay: number;
+            lastDuration: number;
+            lastStartTime: any;
+        };
         observer: any;
         stage: {
             name: any;
@@ -104,7 +112,11 @@ export default class Moonwalk {
         id: string;
         el: any;
         name: any;
-        timeline: any;
+        animation: {
+            lastDelay: number;
+            lastDuration: number;
+            lastStartTime: any;
+        };
         observer: any;
         stage: {
             name: any;
@@ -153,6 +165,24 @@ export default class Moonwalk {
      * @param {*} children
      */
     orderChildren(children: any): any[];
+    /**
+     * Calculate the delay for the next animation in the section.
+     * This replaces GSAP's timeline.recent() logic.
+     *
+     * @param {*} section - The section object
+     * @param {*} duration - Duration of the animation to add
+     * @param {*} overlap - How much the animations should overlap
+     * @returns {number} The delay in seconds
+     */
+    calculateDelay(section: any, duration: any, overlap: any): number;
+    /**
+     * Update the animation state after adding an animation.
+     *
+     * @param {*} section - The section object
+     * @param {*} delay - The delay that was used
+     * @param {*} duration - The duration of the animation
+     */
+    updateAnimationState(section: any, delay: any, duration: any): void;
     onReady(): void;
     /**
      * Called on `APPLICATION_READY` event, if `config.fireOnReady`.

package/types/modules/Popover/index.d.ts

@@ -16,7 +16,7 @@ export default class Popover {
     handleClick(e: any): void;
     get isVisible(): boolean;
     show(): void;
-    updatePosition(animate?: boolean): void;
+    updatePosition(shouldAnimate?: boolean): void;
     hide(): void;
     toggle(): void;
     addDocumentClickHandler(): void;

package/types/modules/StickyHeader/index.d.ts

@@ -31,6 +31,7 @@ export default class StickyHeader {
     mobileMenuOpen: boolean;
     timer: any;
     resetResizeTimer: any;
+    scrollSettleTimeout: NodeJS.Timeout;
     intersectingElements: any;
     initialize(): void;
     pageIsScrolledOnReady: boolean;

package/types/modules/Toggler/index.d.ts

@@ -2,6 +2,22 @@
  * Toggler component for show/hide functionality
  * Uses [data-toggle-trigger] for the toggle button and [data-toggle-content] for toggleable content
  * Can be grouped using [data-toggle-group] to create accordion-like behavior
+ *
+ * IMPORTANT: For smooth animations, avoid padding/margins on [data-toggle-content].
+ * Instead, wrap content in a child element with padding/margins:
+ *
+ * @example
+ * // ❌ DON'T: Padding/margins directly on toggle content
+ * <div data-toggle-content style="padding: 20px; margin-top: 10px">
+ *   Content here
+ * </div>
+ *
+ * // ✅ DO: Wrap content in child element
+ * <div data-toggle-content>
+ *   <div style="padding: 20px; margin-top: 10px">
+ *     Content here
+ *   </div>
+ * </div>
  */
 export default class Toggler {
     /**

package/types/utils/motion-helpers.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Set properties immediately (like gsap.set)
+ * Uses direct DOM manipulation for synchronous style application
+ *
+ * @param {Element|string|NodeList|Array} target - Element(s) or selector
+ * @param {Object} values - Properties to set
+ */
+export function set(target: Element | string | NodeList | any[], values: any): void;
+/**
+ * Animate autoAlpha (opacity + visibility)
+ * Mimics GSAP's autoAlpha property
+ *
+ * @param {Element|string} target - Element or selector
+ * @param {number} value - Target alpha value (0 or 1)
+ * @param {Object} options - Animation options
+ * @returns {Object} Animation object
+ */
+export function animateAutoAlpha(target: Element | string, value: number, options?: any): any;
+/**
+ * Clear inline styles
+ * Mimics GSAP's clearProps
+ *
+ * @param {Element|string|NodeList|Array} target - Element(s) or selector
+ * @param {string|Array} props - Properties to clear or 'all'
+ */
+export function clearProps(target: Element | string | NodeList | any[], props?: string | any[]): void;
+/**
+ * Delayed call helper
+ * Mimics gsap.delayedCall
+ * Uses Motion's delay function (locked to animation frame loop for better sync)
+ *
+ * @param {number} duration - Delay in seconds
+ * @param {Function} callback - Callback function
+ * @returns {Promise} Promise that resolves after delay
+ */
+export function delayedCall(duration: number, callback: Function): Promise<any>;
+/**
+ * Convert GSAP easing strings to Motion.js compatible easings
+ * Handles common GSAP easing types and returns valid Motion.js easing
+ *
+ * @param {string|Array} easing - GSAP easing string or bezier array
+ * @returns {string|Array} Motion.js compatible easing
+ *
+ * Valid Motion.js easings:
+ * - "linear"
+ * - "easeIn"
+ * - "easeInOut"
+ * - "easeOut"
+ * - "circIn"
+ * - "circInOut"
+ * - "circOut"
+ * - "backIn"
+ * - "backInOut"
+ * - "backOut"
+ * - "anticipate"
+ * - Bezier arrays: [x1, y1, x2, y2]
+ */
+export function convertEasing(easing: string | any[]): string | any[];
+/**
+ * Paused Timeline helper
+ * Mimics GSAP's paused timeline pattern for building sequences
+ * Used by modules like Lightbox that build animations before playing them
+ */
+export class PausedTimeline {
+    sequence: any[];
+    /**
+     * Add animation to timeline
+     * @param {Element|string} target - Element or selector
+     * @param {Object} values - Properties to animate
+     * @param {Object} options - Animation options
+     * @returns {PausedTimeline} this for chaining
+     */
+    to(target: Element | string, values: any, options?: any): PausedTimeline;
+    /**
+     * Add callback to timeline
+     * @param {Function} callback - Function to call
+     * @returns {PausedTimeline} this for chaining
+     */
+    call(callback: Function): PausedTimeline;
+    /**
+     * Clear timeline sequence
+     * @returns {PausedTimeline} this for chaining
+     */
+    clear(): PausedTimeline;
+    /**
+     * Play timeline sequence
+     * Executes all animations and callbacks in order
+     * @returns {Promise} Promise that resolves when sequence completes
+     */
+    play(): Promise<any>;
+}