@brandocms/jupiter 5.0.0-beta.12 → 5.0.0-beta.14

package/src/modules/Looper/index.js

@@ -1,6 +1,26 @@
 import { animate, motionValue, frame, cancelFrame } from 'motion'
 import _defaultsDeep from 'lodash.defaultsdeep'
 import Dom from '../Dom'
+import prefersReducedMotion from '../../utils/prefersReducedMotion'
+
+/**
+ * Modulo that centers the result around zero: (-base/2, base/2]
+ * Useful for finding shortest distance on a cycle.
+ */
+function symmetricMod(value, base) {
+  let m = value % base
+  if (Math.abs(m) > base / 2) {
+    m = m > 0 ? m - base : m + base
+  }
+  return m
+}
+
+// Named constants (M5)
+const CLONE_BUFFER_MULTIPLIER = 2.5
+const MIN_CRAWL_SPEED = 0.001
+const PING_PONG_PAUSE_MS = 200
+const VELOCITY_WINDOW_MS = 150
+const SPEED_RAMP_DURATION = 2
 
 /**
  * Looper Module
@@ -24,12 +44,13 @@ const DEFAULT_OPTIONS = {
   loop: true, // Infinite looping (false for linear scrolling)
   draggable: true, // Enable drag interaction
   endAlignment: 'right', // For non-looping: 'right' = last item at viewport right edge, 'start' = last item at viewport left edge
-  minimumMovement: 3, // Pixels - movement below this is treated as click, above as drag
+  minimumMovement: 3, // Pixels for mouse - movement below this is treated as click, above as drag
+  touchMinimumMovement: 10, // Pixels for touch - higher threshold for finger imprecision
 
   // Inertia/throw configuration (when dragging and releasing)
   throwResistance: 325, // Time constant for deceleration (lower = more resistance/faster stop, higher = less resistance/longer glide)
   throwPower: 0.8, // Deceleration curve (0-1, higher = more gradual slowdown)
-  throwVelocityMultiplier: 1.0, // Scale velocity for all throws (0.5 = half speed, 2.0 = double)
+  throwVelocityMultiplier: 0.8, // Scale velocity for all throws (0.5 = half speed, 2.0 = double)
   snapVelocityMultiplier: 0.8, // Additional scaling for snapped loopers (stacks with throwVelocityMultiplier)
 
   // Snap animation configuration (when snap: true)
@@ -63,6 +84,7 @@ function horizontalLoop(app, items, config) {
 
   const shouldLoop = config.loop !== false
   const shouldDrag = config.draggable !== false
+  const reducedMotion = prefersReducedMotion() && app?.opts?.respectReducedMotion
 
   // Container setup
   const center = config.center
@@ -92,6 +114,7 @@ function horizontalLoop(app, items, config) {
   let containerWidth = 0 // Cache container width to avoid layout reads on every frame
   let itemWrapOffsets = [] // Cache current wrap offset for each item
   let isCloneCache = [] // Cache which items are clones (avoid hasAttribute checks)
+  let itemsHaveTransforms = null // Cache whether any original items have CSS transforms (H5)
 
   // Drag state and cleanup handlers
   let dragState = {}
@@ -102,6 +125,12 @@ function horizontalLoop(app, items, config) {
   let navAnimation = null // Track navigation animation (next/previous/toIndex)
   let positionUnsubscribe = null // Track position listener for cleanup
   let renderUnsubscribe = null // Track frame.render loop for cleanup
+  let indexUnsubscribe = null // Track index display position listener (C3)
+  let pingPongTimeout = null // Track ping-pong pause timeout (C4)
+  let resumeCrawlGeneration = 0 // Generation counter for resumeCrawl race condition (C7)
+  let hoverCleanup = null // Track hover effects cleanup function (C1/C9)
+  let startPingPongCrawl = null // Closure-scoped ping-pong starter (M2)
+  let indexSetByNav = false // True when curIndex was set by toIndex, cleared on drag
 
   // Scroll direction tracking for wrap logic
   let scrollDirection = 0 // -1 = backward, 0 = neutral, 1 = forward
@@ -111,6 +140,9 @@ function horizontalLoop(app, items, config) {
   let indexElements = []
   let countElements = []
 
+  // Cache track element reference (M3)
+  const trackElement = items[0].parentElement
+
   /**
    * Measure total width of all items as currently laid out
    * @returns {number} Total width in pixels
@@ -165,7 +197,7 @@ function horizontalLoop(app, items, config) {
 
     // Use 2.5x container width to ensure plenty of buffer for wrapping
     // This prevents items from visibly moving to the back before they're off-screen
-    const minRequiredWidth = containerWidth * 2.5 + maxItemWidth
+    const minRequiredWidth = containerWidth * CLONE_BUFFER_MULTIPLIER + maxItemWidth
 
     // Store original count to prevent exponential growth
     const originalItemCount = items.length
@@ -228,17 +260,29 @@ function horizontalLoop(app, items, config) {
         const rect = el.getBoundingClientRect()
         widths[i] = rect.width
 
-        // Calculate xPercent based on current transform (expensive, only for originals)
-        const computedStyle = window.getComputedStyle(el)
-        const transform = computedStyle.transform
-        let currentX = 0
-
-        if (transform && transform !== 'none') {
-          const matrix = new DOMMatrix(transform)
-          currentX = matrix.m41
+        // Check transforms only if items have them (H5)
+        // Check once at first call, cache for subsequent calls
+        if (itemsHaveTransforms === null) {
+          itemsHaveTransforms = items.slice(0, originalItemCount || items.length).some(item => {
+            const t = window.getComputedStyle(item).transform
+            return t && t !== 'none'
+          })
         }
 
-        xPercents[i] = (currentX / widths[i]) * 100
+        if (itemsHaveTransforms) {
+          const computedStyle = window.getComputedStyle(el)
+          const transform = computedStyle.transform
+          let currentX = 0
+
+          if (transform && transform !== 'none') {
+            const matrix = new DOMMatrix(transform)
+            currentX = matrix.m41
+          }
+
+          xPercents[i] = (currentX / widths[i]) * 100
+        } else {
+          xPercents[i] = 0
+        }
       }
     })
 
@@ -291,65 +335,38 @@ function horizontalLoop(app, items, config) {
     }
   }
 
+  /**
+   * Calculate snap position for an item (M4 - shared between loop and non-loop paths)
+   */
+  function calculateSnapPos(item, i) {
+    const curX = (xPercents[i] / 100) * widths[i]
+
+    if (config.peek) {
+      const itemRightEdge = item.offsetLeft + curX + widths[i] - startX
+      const viewportCenter = containerWidth / 2
+      return itemRightEdge + gap / 2 - viewportCenter
+    } else if (config.centerSlide) {
+      const itemCenter = item.offsetLeft + curX + widths[i] / 2 - startX
+      const viewportCenter = containerWidth / 2
+      return itemCenter - viewportCenter
+    } else {
+      return item.offsetLeft + curX - startX
+    }
+  }
+
   /**
    * Calculate time positions for snapping
    * These represent when each item hits the "start" position
    */
   function populateSnapTimes() {
-    if (!shouldLoop) {
-      // For non-looping, calculate based on actual item positions (pixels)
-      // This ensures snap and navigation work correctly
-      items.forEach((item, i) => {
-        const curX = (xPercents[i] / 100) * widths[i]
-        let snapPos
-
-        if (config.peek) {
-          // Peek mode: viewport center at the gap AFTER this item
-          // This shows: half(i) | gap | full(i+1) | gap | full(i+2) | gap | half(i+3)
-          const itemRightEdge = item.offsetLeft + curX + widths[i] - startX
-          const viewportCenter = containerWidth / 2
-          snapPos = itemRightEdge + gap / 2 - viewportCenter
-        } else if (config.centerSlide) {
-          // Center mode: item's center at viewport's center
-          const itemCenter = item.offsetLeft + curX + widths[i] / 2 - startX
-          const viewportCenter = containerWidth / 2
-          snapPos = itemCenter - viewportCenter
-        } else {
-          // Normal mode: item's left edge at viewport's left edge
-          snapPos = item.offsetLeft + curX - startX
-        }
-
-        times[i] = snapPos / pixelsPerSecond
-      })
-      return
-    }
-
-    // For looping, calculate based on item positions including gaps
     items.forEach((item, i) => {
-      const curX = (xPercents[i] / 100) * widths[i]
-      let snapPos
-
-      if (config.peek) {
-        // Peek mode: viewport center at the gap AFTER this item
-        const itemRightEdge = item.offsetLeft + curX + widths[i] - startX
-        const viewportCenter = containerWidth / 2
-        snapPos = itemRightEdge + gap / 2 - viewportCenter
-      } else if (config.centerSlide) {
-        // Center mode: item's center at viewport's center
-        const itemCenter = item.offsetLeft + curX + widths[i] / 2 - startX
-        const viewportCenter = containerWidth / 2
-        snapPos = itemCenter - viewportCenter
-      } else {
-        // Normal mode: item's left edge at viewport's left edge
-        snapPos = item.offsetLeft + curX - startX
-      }
-
-      times[i] = snapPos / pixelsPerSecond
+      times[i] = calculateSnapPos(item, i) / pixelsPerSecond
     })
 
-    // Adjust for container padding if present
-    const itemsContainer = items[0].parentNode
-    const containerPaddingLeft = parseFloat(getComputedStyle(itemsContainer).paddingLeft) || 0
+    if (!shouldLoop) return
+
+    // Adjust for container padding if present (looping only)
+    const containerPaddingLeft = parseFloat(getComputedStyle(trackElement).paddingLeft) || 0
 
     if (containerPaddingLeft > 0) {
       const paddingTime = containerPaddingLeft / pixelsPerSecond
@@ -365,15 +382,23 @@ function horizontalLoop(app, items, config) {
   function updateItemPositions(rawPos) {
     if (!shouldLoop) return
 
-    // Initialize wrap offsets cache if needed
-    if (itemWrapOffsets.length === 0) {
-      itemWrapOffsets = new Array(items.length).fill(0)
-    }
-
     // 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
 
+    // Initialize wrap offsets - calculate correct cycle directly (not incrementally)
+    // so items land in the right place even when position is many cycles away
+    if (itemWrapOffsets.length === 0) {
+      itemWrapOffsets = new Array(items.length)
+      for (let i = 0; i < items.length; i++) {
+        const distance = offsetLefts[i] - rawPos
+        const offset = Math.round(distance / -cycleDistance) * cycleDistance
+        itemWrapOffsets[i] = offset
+        items[i].style.transform = offset !== 0 ? `translateX(${offset}px)` : 'none'
+      }
+      return
+    }
+
     // Wrap threshold: when an item is more than half a cycle from view, wrap it
     const wrapThreshold = cycleDistance / 2
 
@@ -414,28 +439,26 @@ function horizontalLoop(app, items, config) {
       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
-        }
+    if (deep) {
+      // Save pre-resize measurements for proportional position restore
+      const oldOriginalItemsWidth = originalItemsWidth
+      const oldMaxScrollPosition = maxScrollPosition
+      const oldPosition = position.get()
+
+      if (shouldLoop) {
+        // DEEP REFRESH: Reset wrap offset tracking (DOM transforms written by updateItemPositions init)
+        itemWrapOffsets = []
       }
-      itemWrapOffsets = []
-    }
 
-    // Remeasure everything
-    populateWidths()
+      // Remeasure everything
+      populateWidths()
 
-    if (deep) {
       // Check if we need to replicate more items
       const currentContainerWidth = container.offsetWidth
       const currentTotalWidth = getTotalWidthOfItems()
 
-      // Use same 2.5x buffer as replication logic
-      if (shouldLoop && currentTotalWidth < currentContainerWidth * 2.5) {
+      // Use same buffer multiplier as replication logic
+      if (shouldLoop && currentTotalWidth < currentContainerWidth * CLONE_BUFFER_MULTIPLIER) {
         replicateItemsIfNeeded()
         // Re-cache clone status for any new items
         isCloneCache = items.map((item, i) => i >= originalItemCount)
@@ -444,20 +467,33 @@ function horizontalLoop(app, items, config) {
 
       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
+      // Restore position proportionally to preserve scroll progress across resize
+      let restoredPos
+      if (shouldLoop) {
+        const ratio = oldOriginalItemsWidth > 0
+          ? oldPosition / oldOriginalItemsWidth
+          : 1
+        restoredPos = ratio * originalItemsWidth
+      } else {
+        const ratio = oldMaxScrollPosition > 0
+          ? oldPosition / oldMaxScrollPosition
+          : 0
+        restoredPos = ratio * maxScrollPosition
+      }
+
+      position.set(restoredPos)
+      lastPositionForDirection = restoredPos
+
+      // Apply position and item wraps synchronously to avoid flash
+      // (frame.render is async so we must write DOM directly here)
+      trackElement.style.transform = `translateX(${-restoredPos}px)`
+      updateItemPositions(restoredPos)
+
+      // If snap is enabled, settle to nearest snap point
+      if (config.snap && !config.crawl) {
+        const snapPos = findNearestSnapPoint(restoredPos)
+        const clampedPos = shouldLoop ? snapPos : Math.max(0, Math.min(snapPos, maxScrollPosition))
+        animate(position, clampedPos, { duration: 0.3, ease: 'easeOut' })
       }
 
       // Recreate animation with new measurements
@@ -500,6 +536,7 @@ function horizontalLoop(app, items, config) {
       updateIndexDisplay()
     } else {
       // Light refresh - just update measurements
+      populateWidths()
       populateSnapTimes()
       // Update positions based on current scroll
       updateItemPositions(position.get())
@@ -562,6 +599,14 @@ function horizontalLoop(app, items, config) {
    * Initialize the loop animation
    */
   function init() {
+    // Inject CSS for drag pointer-events (H3) - once per page
+    if (!document.getElementById('looper-drag-style')) {
+      const style = document.createElement('style')
+      style.id = 'looper-drag-style'
+      style.textContent = '.looper-dragging [data-looper-item] { pointer-events: none; }'
+      document.head.appendChild(style)
+    }
+
     // Store original item count BEFORE replication
     originalItemCount = items.length
 
@@ -579,27 +624,25 @@ function horizontalLoop(app, items, config) {
     // whose individual translateX positions fall outside the container's bounds,
     // even when they are visually positioned within the viewport.
     // Apply overflow-x: clip on a parent element instead.
-    const itemsContainer = items[0].parentElement
-    const containerOverflow = getComputedStyle(itemsContainer).overflowX
+    const containerOverflow = getComputedStyle(trackElement).overflowX
     if (containerOverflow === 'clip') {
       console.warn(
-        `[Looper] ⚠️ [data-looper] has overflow-x: clip which will hide looped items. Apply overflow-x: clip on a parent wrapper element instead.`,
-        itemsContainer
+        `[Looper] [data-looper] has overflow-x: clip which will hide looped items. Apply overflow-x: clip on a parent wrapper element instead.`,
+        trackElement
       )
     }
 
     // Set initial container position
-    const containerElement = items[0].parentElement
-    containerElement.style.willChange = 'transform'
+    trackElement.style.willChange = 'transform'
 
     // 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)`
+      trackElement.style.transform = `translateX(${-originalItemsWidth}px)`
     } else {
-      containerElement.style.transform = 'translateX(0px)'
+      trackElement.style.transform = 'translateX(0px)'
     }
 
     // Set up RAF loop to update container position and wrap items
@@ -608,8 +651,6 @@ function horizontalLoop(app, items, config) {
     function startRenderLoop() {
       if (renderUnsubscribe) return // Already running
 
-      const containerElement = items[0].parentElement
-
       // Track scroll direction for wrap logic
       const positionUnsubscribe = position.on('change', latest => {
         const delta = latest - lastPositionForDirection
@@ -622,7 +663,7 @@ function horizontalLoop(app, items, config) {
       renderUnsubscribe = frame.render(() => {
         // Use RAW position (no bounded) for container
         const currentPos = position.get()
-        containerElement.style.transform = `translateX(${-currentPos}px)`
+        trackElement.style.transform = `translateX(${-currentPos}px)`
 
         // Wrap items based on raw position
         updateItemPositions(currentPos)
@@ -637,26 +678,26 @@ function horizontalLoop(app, items, config) {
       startRenderLoop()
     } else {
       // Non-looping: simple position listener to update container transform
-      const containerElement = items[0].parentElement
       positionUnsubscribe = position.on('change', latest => {
-        containerElement.style.transform = `translateX(${-latest}px)`
+        trackElement.style.transform = `translateX(${-latest}px)`
       })
     }
 
     // Create animation by animating the position motionValue
-    if (shouldLoop && config.crawl) {
+    // Skip crawl entirely when reduced motion is preferred (H4)
+    if (shouldLoop && config.crawl && !reducedMotion) {
       const duration = totalWidth / pixelsPerSecond
 
       // Create initial animation (paused)
       animation = startLoopAnimation()
       animation.pause()
-    } else if (!shouldLoop && config.crawl) {
+    } else if (!shouldLoop && config.crawl && !reducedMotion) {
       // Non-looping: ping-pong animation (crawl to end, reverse to start)
       // Use maxScrollPosition (last item at right edge) instead of totalWidth
       const duration = maxScrollPosition / pixelsPerSecond
 
       // Create a ping-pong crawl animation
-      function startPingPongCrawl(fromStart = true) {
+      startPingPongCrawl = function pingPongCrawl(fromStart = true) {
         const currentPos = position.get()
         const target = fromStart ? maxScrollPosition : 0
         const remainingDist = Math.abs(target - currentPos)
@@ -672,17 +713,14 @@ function horizontalLoop(app, items, config) {
         // When reaching the end, reverse direction
         animation.then(() => {
           // Brief pause at boundary for visual clarity
-          setTimeout(() => {
+          pingPongTimeout = setTimeout(() => {
             if (animation && animation.speed !== 0) {
-              startPingPongCrawl(!fromStart)
+              pingPongCrawl(!fromStart)
             }
-          }, 200) // Slightly longer pause for smooth reversal
+          }, PING_PONG_PAUSE_MS)
         })
       }
 
-      // Store the ping-pong starter for later use
-      config.startPingPongCrawl = startPingPongCrawl
-
       // Create initial animation (starts paused)
       animation = animate(position, maxScrollPosition, {
         duration,
@@ -696,8 +734,10 @@ function horizontalLoop(app, items, config) {
       setupDrag()
     }
 
-    // Setup hover effects
-    setupHoverEffects()
+    // Setup hover effects (skip in reduced motion - H4)
+    if (!reducedMotion) {
+      setupHoverEffects()
+    }
 
     // Setup slide index/count display elements
     if (config.wrapper) {
@@ -731,7 +771,7 @@ function horizontalLoop(app, items, config) {
         }
 
         // Update index display whenever position changes (closestIndex normalizes internally)
-        position.on('change', updateIndexOnChange)
+        indexUnsubscribe = position.on('change', updateIndexOnChange)
       }
     }
 
@@ -777,10 +817,23 @@ function horizontalLoop(app, items, config) {
   function setupDrag() {
     // isDragging is now module-level so wrap detection can see it
     let startX = 0
+    let startY = 0
     let startPosition = 0
     let velocityTracker = [] // Track recent movements for velocity calculation
     let hasDragged = false // Did movement exceed minimumMovement threshold?
-    let totalMovement = 0 // Total pixels moved (for click vs drag detection)
+    let axisDecided = false // Has the drag axis been determined? (horizontal vs vertical)
+    let stoppedAnimation = false // Was an animation stopped by this pointer down? (tap-to-stop)
+    let resumeTimeout = null // Delayed crawl resume after tap-to-stop
+    let activeMinimumMovement = config.minimumMovement // Adjusted per pointer type (touch vs mouse)
+
+    /**
+     * Capture-phase click handler that prevents link navigation after a drag.
+     * Added once per drag and auto-removes via { once: true }.
+     */
+    function swallowClick(e) {
+      e.preventDefault()
+      e.stopPropagation()
+    }
 
     /**
      * Calculate velocity from recent pointer movements
@@ -790,8 +843,8 @@ function horizontalLoop(app, items, config) {
     function getVelocity() {
       if (velocityTracker.length < 2) return 0
 
-      // Use last 5 movements for smoothing
-      const recent = velocityTracker.slice(-5)
+      // Use last 6 movements for smoothing
+      const recent = velocityTracker.slice(-6)
       let totalVelocity = 0
       let totalWeight = 0
 
@@ -821,17 +874,35 @@ function horizontalLoop(app, items, config) {
       if (e.button !== undefined && e.button !== 0) return
 
       isDragging = true
+      indexSetByNav = false
       startX = e.clientX
+      startY = e.clientY
       startPosition = position.get()
-      velocityTracker = [{ x: e.clientX, time: Date.now() }]
+      velocityTracker = [{ x: e.clientX, time: e.timeStamp }]
       hasDragged = false // Reset - will be set true if movement exceeds threshold
-      totalMovement = 0
+      axisDecided = false // Reset - will be decided on first significant movement
+
+      // Use higher threshold for touch to prevent accidental drags from finger imprecision
+      activeMinimumMovement = e.pointerType === 'touch'
+        ? config.touchMinimumMovement
+        : config.minimumMovement
 
       // Stop autoplay on user interaction
       if (loopController && loopController.stopAutoplay) {
         loopController.stopAutoplay()
       }
 
+      // Cancel any pending resume from a previous tap-to-stop
+      clearTimeout(resumeTimeout)
+
+      // Detect if we're stopping a running animation (tap-to-stop)
+      stoppedAnimation = !!(
+        inertiaAnimation ||
+        snapAnimation ||
+        (animation && animation.speed !== 0) ||
+        speedRampAnimation
+      )
+
       // Stop any ongoing animations
       if (inertiaAnimation) {
         inertiaAnimation.stop()
@@ -850,14 +921,20 @@ function horizontalLoop(app, items, config) {
         speedRampAnimation = null
       }
 
-      // Prevent default to stop native drag behavior on links/images
-      // We'll manually trigger click in onPointerUp if it wasn't a real drag
-      e.preventDefault()
+      // For mouse: prevent default to stop native drag behavior on links/images
+      // For touch: don't preventDefault here — we need the browser to be able to scroll
+      // if the gesture turns out to be vertical. CSS touch-action: pan-y handles horizontal.
+      if (e.pointerType === 'mouse') {
+        e.preventDefault()
+      }
 
-      // Add move/up listeners to window for better tracking
-      window.addEventListener('pointermove', onPointerMove, { passive: false })
-      window.addEventListener('pointerup', onPointerUp)
-      window.addEventListener('pointercancel', onPointerUp)
+      // Capture pointer to prevent events being lost when finger moves outside container
+      try { container.setPointerCapture(e.pointerId) } catch (err) { /* ignore */ }
+
+      // Add move/up listeners to container (pointer capture routes events here)
+      container.addEventListener('pointermove', onPointerMove, { passive: false })
+      container.addEventListener('pointerup', onPointerUp)
+      container.addEventListener('pointercancel', onPointerUp)
     }
 
     /**
@@ -867,32 +944,49 @@ function horizontalLoop(app, items, config) {
       if (!isDragging) return
 
       const currentX = e.clientX
-      const currentTime = Date.now()
-
-      // Track total movement for click vs drag detection
-      const movementDelta = Math.abs(currentX - startX)
+      const currentTime = e.timeStamp
+
+      // Axis locking: when movement first exceeds threshold, check if primarily
+      // horizontal or vertical. If vertical, abort drag and let the browser scroll.
+      if (!axisDecided) {
+        const deltaX = Math.abs(currentX - startX)
+        const deltaY = Math.abs(e.clientY - startY)
+        const maxDelta = Math.max(deltaX, deltaY)
+
+        // Wait until enough movement to decide
+        if (maxDelta < activeMinimumMovement) return
+
+        axisDecided = true
+
+        // If clearly vertical, abort — release pointer and let browser scroll.
+        // Bias toward carousel interaction: vertical must be 1.2x horizontal to abort.
+        if (deltaY > deltaX * 1.2) {
+          isDragging = false
+          try { container.releasePointerCapture(e.pointerId) } catch (err) { /* ignore */ }
+          container.removeEventListener('pointermove', onPointerMove)
+          container.removeEventListener('pointerup', onPointerUp)
+          container.removeEventListener('pointercancel', onPointerUp)
+          // Resume crawl if we stopped it on pointerdown
+          if (stoppedAnimation && config.crawl) {
+            resumeCrawl()
+          }
+          return
+        }
 
-      // Check if this is now a real drag (exceeded minimum movement threshold)
-      if (!hasDragged && movementDelta > config.minimumMovement) {
+        // Horizontal — commit to drag
         hasDragged = true
-        // Now that we know it's a drag, change cursor and disable pointer events on items
         container.style.cursor = 'grabbing'
-        items.forEach(item => {
-          item.style.pointerEvents = 'none'
-        })
+        trackElement.classList.add('looper-dragging')
       }
 
-      // Only update position if we've confirmed this is a drag
-      if (!hasDragged) return
-
       // Prevent default only for actual drags (not clicks)
       e.preventDefault()
 
       // Track for velocity calculation
       velocityTracker.push({ x: currentX, time: currentTime })
 
-      // Keep only recent movements (last 100ms)
-      while (velocityTracker.length > 0 && currentTime - velocityTracker[0].time > 100) {
+      // Keep only recent movements
+      while (velocityTracker.length > 0 && currentTime - velocityTracker[0].time > VELOCITY_WINDOW_MS) {
         velocityTracker.shift()
       }
 
@@ -912,23 +1006,6 @@ function horizontalLoop(app, items, config) {
       }
     }
 
-    /**
-     * Calculate where inertia would land based on velocity
-     * Uses same physics as startInertia to predict landing position
-     * Motion.js inertia formula: distance = velocity * timeConstant * (power / (1 - power))
-     * @param {number} velocity - Cursor velocity in pixels per second
-     * @returns {number} Predicted landing position
-     */
-    function calculateInertiaTarget(velocity) {
-      const currentPos = position.get()
-      const motionVelocity = -velocity
-      const power = config.throwPower
-      const timeConstant = config.throwResistance / 1000
-      // Motion.js inertia distance formula
-      const estimatedDistance = motionVelocity * timeConstant * (power / (1 - power))
-      return currentPos + estimatedDistance
-    }
-
     /**
      * Handle pointer up - end drag and start inertia
      */
@@ -937,31 +1014,57 @@ function horizontalLoop(app, items, config) {
 
       isDragging = false
 
+      // Release pointer capture
+      try { container.releasePointerCapture(e.pointerId) } catch (err) { /* ignore */ }
+
       // Clean up listeners
-      window.removeEventListener('pointermove', onPointerMove)
-      window.removeEventListener('pointerup', onPointerUp)
-      window.removeEventListener('pointercancel', onPointerUp)
+      container.removeEventListener('pointermove', onPointerMove)
+      container.removeEventListener('pointerup', onPointerUp)
+      container.removeEventListener('pointercancel', onPointerUp)
 
       // Reset cursor and re-enable hover effects (only if we actually dragged)
       if (hasDragged) {
         container.style.cursor = 'grab'
-        items.forEach(item => {
-          item.style.pointerEvents = ''
-        })
+        trackElement.classList.remove('looper-dragging')
+
+        // Swallow the next click event so links don't navigate after a drag.
+        // The browser fires click after pointerup — capture it before it reaches any <a>.
+        container.addEventListener('click', swallowClick, { capture: true, once: true })
       }
 
-      // If this was a click (not a drag), trigger click on the element
+      // If this was a click (not a drag):
+      // - If we stopped a running animation, silently stop (like native iOS scroll tap-to-stop)
+      //   then resume crawl after a delay so it doesn't feel jittery
+      // - Otherwise, forward the click to the element under the pointer
       if (!hasDragged) {
-        // Find the element under the pointer and trigger a click
-        const clickedElement = document.elementFromPoint(e.clientX, e.clientY)
-        if (clickedElement) {
-          clickedElement.click()
+        if (!stoppedAnimation) {
+          const clickedElement = document.elementFromPoint(e.clientX, e.clientY)
+          if (clickedElement) {
+            clickedElement.click()
+          }
+        }
+        if (stoppedAnimation && config.crawl) {
+          clearTimeout(resumeTimeout)
+          resumeTimeout = setTimeout(() => resumeCrawl(), 5000)
         }
         return
       }
 
-      // Calculate final velocity
-      const velocity = getVelocity()
+      // Calculate velocity from pointermove samples only.
+      // Do NOT use pointerup/pointercancel clientX — iOS Safari often reports 0
+      // on pointercancel which corrupts velocity and direction calculations.
+      let velocity = getVelocity()
+
+      // Use last reliable pointermove position for direction check (not e.clientX
+      // which may be 0 from a pointercancel event on iOS)
+      const lastTrackedX = velocityTracker.length > 0
+        ? velocityTracker[velocityTracker.length - 1].x
+        : e.clientX
+      const overallDelta = lastTrackedX - startX
+
+      // Sanity check: velocity direction must match overall drag direction.
+      if (overallDelta > 0 && velocity < 0) velocity = 0
+      if (overallDelta < 0 && velocity > 0) velocity = 0
 
       // If snap is enabled, always use it (GSAP-style: snap modifies inertia target)
       // Otherwise use old logic: inertia if velocity, or resume crawl
@@ -990,12 +1093,14 @@ function horizontalLoop(app, items, config) {
       // Note: This is ALWAYS opposite, regardless of reversed setting
       // (reversed only affects auto-crawl, not drag)
       // Apply velocity multiplier for tuning throw feel
-      const motionVelocity = -velocity * config.throwVelocityMultiplier
+      // Reduce inertia when reduced motion is preferred (H4)
+      const velocityMultiplier = reducedMotion ? config.throwVelocityMultiplier * 0.3 : config.throwVelocityMultiplier
+      const motionVelocity = -velocity * velocityMultiplier
 
-      // Calculate estimated target based on inertia physics
+      // Estimate target for Motion.js (it recomputes internally for type: 'inertia',
+      // but we pass a reasonable target to avoid a zero-distance animation)
       const power = config.throwPower
-      const timeConstant = config.throwResistance / 1000 // Convert to seconds
-      const estimatedDistance = motionVelocity * timeConstant * 0.5
+      const estimatedDistance = power * motionVelocity
       const targetPos = currentPos + estimatedDistance
 
       // Animate position motionValue with inertia
@@ -1094,6 +1199,24 @@ function horizontalLoop(app, items, config) {
      */
     function snapToNearest(velocity = 0) {
       const currentPos = position.get()
+
+      // Reduced motion: instant snap with short duration, no inertia (H4)
+      if (reducedMotion) {
+        const snapPos = findNearestSnapPoint(currentPos)
+        const clampedPos = shouldLoop ? snapPos : Math.max(0, Math.min(snapPos, maxScrollPosition))
+        snapAnimation = animate(position, clampedPos, {
+          duration: 0.15,
+          ease: 'easeOut',
+        })
+        snapAnimation
+          .then(() => {
+            snapAnimation = null
+            updateIndexDisplay()
+          })
+          .catch(() => { snapAnimation = null })
+        return
+      }
+
       // Apply both velocity multipliers for snapped loopers
       const motionVelocity =
         -velocity * config.throwVelocityMultiplier * config.snapVelocityMultiplier
@@ -1151,7 +1274,10 @@ function horizontalLoop(app, items, config) {
      * Reads current position and resumes infinite loop
      */
     function resumeCrawl() {
-      if (!config.crawl) return
+      if (!config.crawl || reducedMotion) return
+
+      // Increment generation to invalidate any pending .then() callbacks (C7)
+      const generation = ++resumeCrawlGeneration
 
       // Stop any existing animations
       if (animation) {
@@ -1168,7 +1294,10 @@ function horizontalLoop(app, items, config) {
       // Calculate position within current cycle (using originalItemsWidth)
       // Use proper modulo for negative positions (dragging right/backward)
       const cyclePos = ((currentPos % originalItemsWidth) + originalItemsWidth) % originalItemsWidth
-      const remainingDist = originalItemsWidth - cyclePos
+      // For reversed carousels, remaining distance to complete cycle backward is cyclePos (C6)
+      const remainingDist = config.reversed
+        ? (cyclePos || originalItemsWidth)
+        : (originalItemsWidth - cyclePos)
       const remainingDuration = remainingDist / pixelsPerSecond
 
       // Animate position to complete this cycle
@@ -1181,6 +1310,9 @@ function horizontalLoop(app, items, config) {
 
       // When cycle completes, restart infinite loop
       animation.then(() => {
+        // Check generation to avoid stale .then() callbacks (C7)
+        if (generation !== resumeCrawlGeneration) return
+
         // Capture current speed before replacing animation
         const currentSpeed = animation.speed
 
@@ -1203,9 +1335,8 @@ function horizontalLoop(app, items, config) {
         if (speedRampAnimation) {
           speedRampAnimation.stop()
           // Calculate remaining ramp duration based on current speed
-          // speed goes from 0.001 to 1.0, so progress = (currentSpeed - 0.001) / (1.0 - 0.001)
-          const rampProgress = (currentSpeed - 0.001) / 0.999
-          const remainingRampDuration = 2 * (1 - rampProgress)
+          const rampProgress = (currentSpeed - MIN_CRAWL_SPEED) / (1 - MIN_CRAWL_SPEED)
+          const remainingRampDuration = SPEED_RAMP_DURATION * (1 - rampProgress)
 
           speedRampAnimation = animate(
             animation,
@@ -1216,9 +1347,9 @@ function horizontalLoop(app, items, config) {
       })
 
       // Start at nearly-stopped speed and ramp up to full speed
-      // Use 0.001 instead of 0 to keep animation running (speed = 0 completely pauses)
-      animation.speed = 0.001
-      speedRampAnimation = animate(animation, { speed: 1 }, { duration: 2, ease: 'easeIn' })
+      // Use MIN_CRAWL_SPEED instead of 0 to keep animation running (speed = 0 completely pauses)
+      animation.speed = MIN_CRAWL_SPEED
+      speedRampAnimation = animate(animation, { speed: 1 }, { duration: SPEED_RAMP_DURATION, ease: 'easeIn' })
     }
 
     // Set up touch-action CSS for proper touch handling
@@ -1232,15 +1363,17 @@ function horizontalLoop(app, items, config) {
     dragState = {
       cleanup: () => {
         container.removeEventListener('pointerdown', onPointerDown)
-        window.removeEventListener('pointermove', onPointerMove)
-        window.removeEventListener('pointerup', onPointerUp)
-        window.removeEventListener('pointercancel', onPointerUp)
+        container.removeEventListener('click', swallowClick, { capture: true })
+        container.removeEventListener('pointermove', onPointerMove)
+        container.removeEventListener('pointerup', onPointerUp)
+        container.removeEventListener('pointercancel', onPointerUp)
       },
     }
   }
 
   /**
-   * Setup hover slow-down effects
+   * Setup hover slow-down effects using event delegation on container (H1/C1/C5)
+   * Single listener pair on container covers all items including future clones
    */
   function setupHoverEffects() {
     if (!config.crawl || !animation) return
@@ -1252,37 +1385,48 @@ function horizontalLoop(app, items, config) {
     // Track hover animations to prevent accumulation
     let hoverAnimation = null
 
-    items.forEach(item => {
-      item.addEventListener('mouseenter', () => {
-        if (!animation) return
+    function onMouseEnter(e) {
+      if (!animation) return
+      if (!e.target.closest('[data-looper-item]')) return
 
-        // Stop previous hover animation before creating new one
-        if (hoverAnimation) {
-          hoverAnimation.stop()
-        }
+      if (hoverAnimation) {
+        hoverAnimation.stop()
+      }
 
-        hoverAnimation = animate(
-          animation,
-          { speed: hoverSpeed },
-          { duration: config.ease.mouseOver.duration, ease: 'easeOut' }
-        )
-      })
+      hoverAnimation = animate(
+        animation,
+        { speed: hoverSpeed },
+        { duration: config.ease.mouseOver.duration, ease: 'easeOut' }
+      )
+    }
 
-      item.addEventListener('mouseleave', () => {
-        if (!animation) return
+    function onMouseLeave(e) {
+      if (!animation) return
+      if (!e.target.closest('[data-looper-item]')) return
 
-        // Stop previous hover animation before creating new one
-        if (hoverAnimation) {
-          hoverAnimation.stop()
-        }
+      if (hoverAnimation) {
+        hoverAnimation.stop()
+      }
 
-        hoverAnimation = animate(
-          animation,
-          { speed: targetSpeed },
-          { duration: config.ease.mouseOut.duration, ease: 'easeOut' }
-        )
-      })
-    })
+      hoverAnimation = animate(
+        animation,
+        { speed: targetSpeed },
+        { duration: config.ease.mouseOut.duration, ease: 'easeOut' }
+      )
+    }
+
+    container.addEventListener('mouseenter', onMouseEnter, true)
+    container.addEventListener('mouseleave', onMouseLeave, true)
+
+    // Return cleanup function (C1/C9)
+    hoverCleanup = () => {
+      if (hoverAnimation) {
+        hoverAnimation.stop()
+        hoverAnimation = null
+      }
+      container.removeEventListener('mouseenter', onMouseEnter, true)
+      container.removeEventListener('mouseleave', onMouseLeave, true)
+    }
   }
 
   /**
@@ -1293,6 +1437,11 @@ function horizontalLoop(app, items, config) {
   function closestIndex(setCurrent = false) {
     if (!times || times.length === 0) return 0
 
+    // If curIndex was set by toIndex (nav button), trust it.
+    // Position-based lookup fails when maxScrollPosition clamps positions
+    // too close together to distinguish items.
+    if (indexSetByNav) return curIndex
+
     // Use bounded position to find what's actually visible
     const currentPos = position.get()
 
@@ -1308,21 +1457,14 @@ function horizontalLoop(app, items, config) {
 
     let closest = 0
     let closestDist = Infinity
+    const duration = shouldLoop ? originalItemsWidth / pixelsPerSecond : 0
 
     // Only check original items, not clones
     for (let i = 0; i < originalItemCount; i++) {
       const time = times[i]
-      let dist = Math.abs(time - currentTime)
-
-      // For looping, check wrapped distance
-      if (shouldLoop) {
-        const duration = originalItemsWidth / pixelsPerSecond
-        const wrappedDist = Math.min(
-          Math.abs(time + duration - currentTime),
-          Math.abs(time - duration - currentTime)
-        )
-        dist = Math.min(dist, wrappedDist)
-      }
+      const dist = shouldLoop
+        ? Math.abs(symmetricMod(time - currentTime, duration))
+        : Math.abs(time - currentTime)
 
       if (dist < closestDist) {
         closestDist = dist
@@ -1398,6 +1540,7 @@ function horizontalLoop(app, items, config) {
 
     // Update current index
     curIndex = targetIndex
+    indexSetByNav = true
 
     // Update display immediately
     updateIndexDisplay()
@@ -1431,19 +1574,19 @@ function horizontalLoop(app, items, config) {
 
   const loopController = {
     position,
-    animation,
+    get animation() { return animation },
     items,
-    times,
+    get times() { return times },
     isReversed: config.reversed,
     isLooping: shouldLoop,
 
     play() {
-      if (!shouldLoop && config.crawl && config.startPingPongCrawl) {
+      if (!shouldLoop && config.crawl && startPingPongCrawl) {
         // Non-looping: start ping-pong crawl
         const currentPos = position.get()
         // Determine direction based on current position
         const goForward = currentPos < maxScrollPosition / 2
-        config.startPingPongCrawl(goForward)
+        startPingPongCrawl(goForward)
       } else if (animation) {
         animation.play()
       }
@@ -1544,17 +1687,51 @@ function horizontalLoop(app, items, config) {
       // Stop autoplay
       this.stopAutoplay()
 
-      // Stop animation
+      // Stop all animations (C9)
       if (animation) {
         animation.stop()
+        animation = null
+      }
+      if (speedRampAnimation) {
+        speedRampAnimation.stop()
+        speedRampAnimation = null
+      }
+      if (inertiaAnimation) {
+        inertiaAnimation.stop()
+        inertiaAnimation = null
+      }
+      if (snapAnimation) {
+        snapAnimation.stop()
+        snapAnimation = null
+      }
+      if (navAnimation) {
+        navAnimation.stop()
+        navAnimation = null
+      }
+
+      // Clear pending timeouts (C4)
+      if (pingPongTimeout) {
+        clearTimeout(pingPongTimeout)
+        pingPongTimeout = null
+      }
+
+      // Cleanup hover effects (C1/C9)
+      if (hoverCleanup) {
+        hoverCleanup()
+        hoverCleanup = null
       }
 
       // Stop frame.render loop
       stopRenderLoop()
 
-      // Cleanup position listener
+      // Cleanup position listeners (C3)
       if (positionUnsubscribe) {
         positionUnsubscribe()
+        positionUnsubscribe = null
+      }
+      if (indexUnsubscribe) {
+        indexUnsubscribe()
+        indexUnsubscribe = null
       }
 
       // Cleanup drag
@@ -1565,6 +1742,23 @@ function horizontalLoop(app, items, config) {
       // Cleanup resize listener
       window.removeEventListener('APPLICATION:RESIZE', handleResize)
 
+      // Remove clone elements from DOM (C10)
+      const clones = trackElement.querySelectorAll('[data-looper-clone]')
+      clones.forEach(clone => clone.remove())
+
+      // Clear inline styles on track element (C10)
+      trackElement.style.willChange = ''
+      trackElement.style.transform = ''
+
+      // Clear inline styles on container
+      container.style.touchAction = ''
+      container.style.cursor = ''
+
+      // Clear item wrap transforms
+      items.forEach(item => {
+        item.style.transform = ''
+      })
+
       // Destroy position value
       position.destroy()
     },
@@ -1603,7 +1797,7 @@ export default class Looper {
 
       if (!wrapper) {
         console.error(
-          '[Looper] ⚠️ No wrapper element found (expected [data-looper-container] or .looper-wrapper)'
+          '[Looper] No wrapper element found (expected [data-looper-container] or .looper-wrapper)'
         )
       }
 
@@ -1689,6 +1883,7 @@ export default class Looper {
           snapDuration: this.opts.snapDuration,
           snapBounce: this.opts.snapBounce,
           minimumMovement: this.opts.minimumMovement,
+          touchMinimumMovement: this.opts.touchMinimumMovement,
         },
       })
     })
@@ -1720,22 +1915,26 @@ export default class Looper {
       // Replace stub with real loop
       element.$loop = loop
 
-      // Setup navigation buttons if present
+      // Setup navigation buttons if present (C2 - store refs for cleanup)
       const next = Dom.find(element, '[data-panner-next]')
       const previous = Dom.find(element, '[data-panner-previous]')
+      const navCleanups = []
 
       if (next) {
-        next.addEventListener('click', () => {
-          loop.next({ duration: 0.85, ease: 'easeInOut' })
-        })
+        const onNext = () => loop.next({ duration: 0.85, ease: 'easeInOut' })
+        next.addEventListener('click', onNext)
+        navCleanups.push(() => next.removeEventListener('click', onNext))
       }
 
       if (previous) {
-        previous.addEventListener('click', () => {
-          loop.previous({ duration: 0.85, ease: 'easeInOut' })
-        })
+        const onPrev = () => loop.previous({ duration: 0.85, ease: 'easeInOut' })
+        previous.addEventListener('click', onPrev)
+        navCleanups.push(() => previous.removeEventListener('click', onPrev))
       }
 
+      // Store nav cleanup on the loop controller
+      loop._navCleanups = navCleanups
+
       // Reveal lazyload images: immediately reveal off-screen items (no visible transition),
       // defer reveal of viewport items until after wrapper fade-in for a nice per-image fade
       if (this.app?.lazyload && wrapper) {
@@ -1770,7 +1969,14 @@ export default class Looper {
   }
 
   destroy() {
-    this.loopers.forEach(loop => loop.destroy())
+    this.loopers.forEach(loop => {
+      // Clean up navigation button listeners (C2)
+      if (loop._navCleanups) {
+        loop._navCleanups.forEach(fn => fn())
+        loop._navCleanups = null
+      }
+      loop.destroy()
+    })
     this.loopers = []
     this.pendingLoopers = []
   }