react-sway 0.1.0 → 0.2.0

package/src/ReactSway.tsx

@@ -1,248 +1,463 @@
-import { useState, useRef, useEffect, useCallback, ReactNode } from 'react';
+import { type KeyboardEvent as ReactKeyboardEvent, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-// Constants (hardcoded as per current plan)
-const SCROLL_SPEED = 0.5; // pixels per frame at 60fps
-const INACTIVITY_DELAY = 2000; // ms
-const FRICTION = 0.95;
-const MAX_DELTA_TIME = 3; // Cap deltaTime to prevent physics breaking
+/** Velocity applied per arrow key press (pixels). */
+const ARROW_KEY_VELOCITY = 15;
 
-interface ReactSwayProps {
+/** Default friction coefficient applied to velocity each frame. */
+const DEFAULT_FRICTION = 0.95;
+
+/** Default IntersectionObserver rootMargin for lazy visibility detection. */
+const DEFAULT_LAZY_ROOT_MARGIN = '100px';
+
+/** Default IntersectionObserver threshold for lazy visibility detection. */
+const DEFAULT_LAZY_THRESHOLD = 0.01;
+
+/** Default delay in milliseconds before auto-scroll resumes after user interaction. */
+const DEFAULT_RESUME_DELAY = 2000;
+
+/** Default scroll speed in pixels per frame at 60fps. */
+const DEFAULT_SPEED = 0.5;
+
+/** Number of stacked content groups used to build the seamless loop. */
+const LOOP_SEGMENTS = 3;
+
+/** Maximum deltaTime cap to prevent physics instability during frame drops. */
+const MAX_DELTA_TIME = 3;
+
+/** Maximum allowed velocity magnitude to prevent runaway scrolling. */
+const MAX_VELOCITY = 150;
+
+/** Duration of a single frame at 60fps in milliseconds. */
+const MS_PER_FRAME_60FPS = 16.667;
+
+/** Speed multiplier when user prefers reduced motion (25% of normal). */
+const REDUCED_MOTION_SPEED_FACTOR = 0.25;
+
+/** Debounce delay in milliseconds for ResizeObserver callbacks. */
+const RESIZE_DEBOUNCE_MS = 150;
+
+/** Multiplier applied to wheel deltaY to convert to scroll velocity. */
+const WHEEL_VELOCITY_MULTIPLIER = 0.3;
+
+/**
+ * Props for the ReactSway infinite scrolling component.
+ */
+export interface ReactSwayProps {
+  /** Enable/disable auto-scrolling. @default true */
+  autoScroll?: boolean;
+  /** Content elements to render in the infinite scroll container. */
   children: ReactNode;
+  /** Auto-scroll direction. @default 'up' */
+  direction?: 'down' | 'up';
+  /** Enable mouse/touch drag interaction. @default true */
+  draggable?: boolean;
+  /** Momentum decay coefficient (0-1, lower = more friction). @default 0.95 */
+  friction?: number;
+  /** Enable keyboard controls (Space, ArrowUp/Down, Home/End). @default true */
+  keyboard?: boolean;
+  /** Enable lazy visibility detection via IntersectionObserver. @default true */
+  lazy?: boolean;
+  /** IntersectionObserver rootMargin for lazy visibility detection. @default '100px' */
+  lazyRootMargin?: string;
+  /** IntersectionObserver threshold for lazy visibility detection. @default 0.01 */
+  lazyThreshold?: number;
+  /** Fired when scrolling pauses (user interaction or Space key). */
+  onPause?: () => void;
+  /** Fired when scrolling resumes after pause. */
+  onResume?: () => void;
+  /** Fired on every position change with the current scroll position. */
+  onScroll?: (position: number) => void;
+  /** Pause auto-scroll during user interaction. @default true */
+  pauseOnInteraction?: boolean;
+  /** Milliseconds before auto-scroll resumes after interaction. @default 2000 */
+  resumeDelay?: number;
+  /** Auto-scroll speed in pixels per frame at 60fps. @default 0.5 */
+  speed?: number;
+  /** Enable mouse wheel scrolling. @default true */
+  wheelEnabled?: boolean;
 }
 
-function ReactSway({ children }: ReactSwayProps) {
-  const [position, setPosition] = useState(0);
-  const [, setVelocity] = useState(0); // velocity is set but never used directly for rendering, only for physics calcs
+/**
+ * A smooth, infinite scrolling container component.
+ *
+ * Renders children in a continuously looping scroll area with support for
+ * auto-scrolling, mouse drag, touch swipe, wheel, and keyboard interactions.
+ * Content is duplicated to create a seamless loop effect. Duplicate content
+ * is wrapped in `<aside>` elements with `aria-hidden="true"` for accessibility.
+ *
+ * Respects `prefers-reduced-motion: reduce` by lowering auto-scroll speed
+ * and disabling momentum effects.
+ *
+ * @example
+ * ```tsx
+ * <ReactSway direction="up" speed={1} friction={0.9}>
+ *   <div className="content-item">Item 1</div>
+ *   <div className="content-item">Item 2</div>
+ * </ReactSway>
+ * ```
+ */
+function ReactSway({
+  autoScroll = true,
+  children,
+  direction = 'up',
+  draggable = true,
+  friction = DEFAULT_FRICTION,
+  keyboard = true,
+  lazy = true,
+  lazyRootMargin = DEFAULT_LAZY_ROOT_MARGIN,
+  lazyThreshold = DEFAULT_LAZY_THRESHOLD,
+  onPause,
+  onResume,
+  onScroll,
+  pauseOnInteraction = true,
+  resumeDelay = DEFAULT_RESUME_DELAY,
+  speed = DEFAULT_SPEED,
+  wheelEnabled = true,
+}: ReactSwayProps) {
+  const normalizedFriction = useMemo(
+    () => (Number.isFinite(friction) ? Math.min(Math.max(friction, 0), 1) : DEFAULT_FRICTION),
+    [friction],
+  );
+  const normalizedResumeDelay = useMemo(
+    () => (Number.isFinite(resumeDelay) ? Math.max(0, resumeDelay) : DEFAULT_RESUME_DELAY),
+    [resumeDelay],
+  );
+  const normalizedSpeed = useMemo(
+    () => (Number.isFinite(speed) ? Math.max(0, speed) : DEFAULT_SPEED),
+    [speed],
+  );
+
   const [isDragging, setIsDragging] = useState(false);
   const [isPaused, setIsPaused] = useState(false);
-  const [autoScrollEnabled, setAutoScrollEnabled] = useState(true);
   const [isTabActive, setIsTabActive] = useState(true);
-
-  // Content dimensions
-  const [contentHeight, setContentHeight] = useState(0);
   const [loopPoint, setLoopPoint] = useState(0);
-  const [, setContainerHeight] = useState(0); // containerHeight is set but never used
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(() => {
+    if (typeof window === 'undefined') return false;
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  });
 
-  const containerRef = useRef<HTMLDivElement>(null);
   const animationFrameRef = useRef<number | null>(null);
+  const autoScrollRef = useRef({ active: autoScroll, desired: autoScroll });
+  const containerRef = useRef<HTMLDivElement>(null);
   const inactivityTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const lastTouchYRef = useRef(0);
-  const lastMouseYRef = useRef(0);
+  const isDraggingRef = useRef(false);
+  const isPausedRef = useRef(false);
   const lastFrameTimeRef = useRef(0);
-
-  // Visual position calculation
-  let visualPosition = position % (loopPoint || 1);
-  if (visualPosition > 0 && loopPoint > 0) visualPosition -= loopPoint;
-
+  const lastMouseYRef = useRef(0);
+  const lastTouchYRef = useRef(0);
+  const loopPointRef = useRef(0);
+  const onPauseRef = useRef(onPause);
+  const onResumeRef = useRef(onResume);
+  const onScrollRef = useRef(onScroll);
+  const positionRef = useRef(0);
+  const resizeDebounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const velocityRef = useRef(0);
+
+  // Keep callback refs in sync without triggering re-renders
   useEffect(() => {
-    const calculateDimensions = () => {
-      if (containerRef.current) {
-        // Force a reflow to ensure accurate measurements
-        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-        containerRef.current.offsetHeight;
-
-        const currentContentHeight = containerRef.current.scrollHeight;
-        const calculatedLoopPoint = currentContentHeight / 3;
-
-        console.log('Calculating dimensions:', { currentContentHeight, calculatedLoopPoint });
+    onPauseRef.current = onPause;
+    onResumeRef.current = onResume;
+    onScrollRef.current = onScroll;
+  }, [onPause, onResume, onScroll]);
 
-        if (currentContentHeight > 0) {
-          setContentHeight(currentContentHeight);
-          setLoopPoint(calculatedLoopPoint);
-        }
-
-        setContainerHeight(window.innerHeight);
-      }
+  // Listen for prefers-reduced-motion media query changes
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const handleChange = (e: MediaQueryListEvent) => {
+      setPrefersReducedMotion(e.matches);
     };
-
-    // Use RAF to ensure layout is complete
-    const rafId = requestAnimationFrame(() => {
-      calculateDimensions();
-    });
-
+    mediaQuery.addEventListener('change', handleChange);
     return () => {
-      cancelAnimationFrame(rafId);
+      mediaQuery.removeEventListener('change', handleChange);
     };
-  }, [children]);
+  }, []);
 
-  const pauseAutoScroll = useCallback(() => {
-    setAutoScrollEnabled(false);
-    if (inactivityTimerRef.current) {
-      clearTimeout(inactivityTimerRef.current);
-    }
+  const clearInactivityTimer = useCallback(() => {
+    if (!inactivityTimerRef.current) return;
+    clearTimeout(inactivityTimerRef.current);
+    inactivityTimerRef.current = null;
   }, []);
 
-  const scheduleAutoScrollResume = useCallback(() => {
-    if (inactivityTimerRef.current) {
-      clearTimeout(inactivityTimerRef.current);
+  const renderPosition = useCallback((rawPosition: number) => {
+    if (!containerRef.current) return;
+    const currentLoopPoint = loopPointRef.current;
+    let visualPosition = rawPosition % (currentLoopPoint || 1);
+    if (visualPosition > 0 && currentLoopPoint > 0) {
+      visualPosition -= currentLoopPoint;
     }
-    inactivityTimerRef.current = setTimeout(() => {
-      setAutoScrollEnabled(true);
-    }, INACTIVITY_DELAY);
+    containerRef.current.style.transform = `translate3d(0, ${visualPosition}px, 0)`;
   }, []);
 
-  const handleMouseDown = useCallback((e: globalThis.MouseEvent) => {
-    e.preventDefault();
-    setIsDragging(true);
-    lastMouseYRef.current = e.clientY;
-    setVelocity(0);
-    pauseAutoScroll();
-  }, [pauseAutoScroll]);
+  const commitPosition = useCallback((nextPosition: number) => {
+    if (positionRef.current === nextPosition) return;
+    positionRef.current = nextPosition;
+    renderPosition(nextPosition);
+    onScrollRef.current?.(nextPosition);
+  }, [renderPosition]);
 
-  const handleMouseMove = useCallback((e: globalThis.MouseEvent) => {
-    if (!isDragging) return;
-    e.preventDefault();
-    const deltaY = e.clientY - lastMouseYRef.current;
-    setPosition(prev => prev + deltaY);
-    setVelocity(deltaY);
-    lastMouseYRef.current = e.clientY;
-  }, [isDragging]);
+  const wrapPosition = useCallback((rawPosition: number) => {
+    const currentLoopPoint = loopPointRef.current;
+    if (currentLoopPoint <= 0) return rawPosition;
 
-  const handleMouseUp = useCallback((e: globalThis.MouseEvent) => {
-    if (!isDragging) return;
-    e.preventDefault();
-    setIsDragging(false);
-    scheduleAutoScrollResume();
-  }, [isDragging, scheduleAutoScrollResume]);
+    let wrappedPosition = rawPosition;
+    while (wrappedPosition > 0) {
+      wrappedPosition -= currentLoopPoint;
+    }
+    while (wrappedPosition < -currentLoopPoint * 2) {
+      wrappedPosition += currentLoopPoint;
+    }
+    return wrappedPosition;
+  }, []);
 
-  const handleTouchStart = useCallback((e: globalThis.TouchEvent) => {
-    if (e.touches.length === 1) {
-      setIsDragging(true);
-      lastTouchYRef.current = e.touches[0].clientY;
-      setVelocity(0);
-      pauseAutoScroll();
+  const recalculateLoopPoint = useCallback(() => {
+    if (!containerRef.current) return;
+    const currentContentHeight = containerRef.current.scrollHeight;
+    if (currentContentHeight <= 0) return;
+
+    const nextLoopPoint = currentContentHeight / LOOP_SEGMENTS;
+    loopPointRef.current = nextLoopPoint;
+    setLoopPoint((previousLoopPoint) => (Math.abs(previousLoopPoint - nextLoopPoint) < 0.5 ? previousLoopPoint : nextLoopPoint));
+    renderPosition(positionRef.current);
+  }, [renderPosition]);
+
+  // Sync autoScroll prop changes with internal state
+  useEffect(() => {
+    autoScrollRef.current.desired = autoScroll;
+    if (!autoScroll) {
+      clearInactivityTimer();
+      autoScrollRef.current.active = true;
     }
-  }, [pauseAutoScroll]);
+  }, [autoScroll, clearInactivityTimer]);
 
-  const handleTouchMove = useCallback((e: globalThis.TouchEvent) => {
-    if (!isDragging || e.touches.length !== 1) return;
-    e.preventDefault();
-    const touch = e.touches[0];
-    const deltaY = touch.clientY - lastTouchYRef.current;
-    setPosition(prev => prev + deltaY);
-    setVelocity(deltaY);
-    lastTouchYRef.current = touch.clientY;
-  }, [isDragging]);
+  // Sync loopPoint ref after state updates from observers/resizes
+  useEffect(() => {
+    loopPointRef.current = loopPoint;
+    renderPosition(positionRef.current);
+  }, [loopPoint, renderPosition]);
 
-  const handleTouchEnd = useCallback((_e: globalThis.TouchEvent) => { // e is not used
-    if (!isDragging) return;
-    setIsDragging(false);
-    scheduleAutoScrollResume();
-  }, [isDragging, scheduleAutoScrollResume]);
+  // Dimension calculation
+  useEffect(() => {
+    // Use RAF to ensure layout is complete
+    const rafId = requestAnimationFrame(recalculateLoopPoint);
 
-  const handleWheel = useCallback((e: globalThis.WheelEvent) => {
-    e.preventDefault();
-    setVelocity(prev => prev - e.deltaY * 0.3);
-    pauseAutoScroll();
-    scheduleAutoScrollResume();
-  }, [pauseAutoScroll, scheduleAutoScrollResume]);
+    return () => {
+      cancelAnimationFrame(rafId);
+    };
+  }, [children, recalculateLoopPoint]);
+
+  const pauseAutoScroll = useCallback(() => {
+    if (!pauseOnInteraction) return;
+    autoScrollRef.current.active = false;
+    onPauseRef.current?.();
+    clearInactivityTimer();
+  }, [clearInactivityTimer, pauseOnInteraction]);
+
+  const scheduleAutoScrollResume = useCallback(() => {
+    if (!pauseOnInteraction || !autoScrollRef.current.desired || isPausedRef.current) return;
+    clearInactivityTimer();
+
+    inactivityTimerRef.current = setTimeout(() => {
+      inactivityTimerRef.current = null;
+      if (!autoScrollRef.current.desired || isPausedRef.current) return;
+      autoScrollRef.current.active = true;
+      onResumeRef.current?.();
+    }, normalizedResumeDelay);
+  }, [clearInactivityTimer, normalizedResumeDelay, pauseOnInteraction]);
 
   const togglePause = useCallback(() => {
-    setIsPaused(prev => {
-      const newPausedState = !prev;
-      if (newPausedState) {
-        pauseAutoScroll();
-      } else {
-        setAutoScrollEnabled(true);
+    const newPaused = !isPausedRef.current;
+    isPausedRef.current = newPaused;
+    setIsPaused(newPaused);
+    if (newPaused) {
+      clearInactivityTimer();
+      autoScrollRef.current.active = false;
+      onPauseRef.current?.();
+    } else {
+      clearInactivityTimer();
+      autoScrollRef.current.active = true;
+      if (autoScrollRef.current.desired) {
+        onResumeRef.current?.();
       }
-      return newPausedState;
-    });
-  }, [pauseAutoScroll]);
+    }
+  }, [clearInactivityTimer]);
+
+  const handleKeyDown = useCallback((e: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (!keyboard) return;
 
-  const handleKeyDown = useCallback((e: globalThis.KeyboardEvent) => {
     switch (e.key) {
       case ' ':
         e.preventDefault();
         togglePause();
         break;
-      case 'ArrowUp':
+      case 'ArrowDown':
         e.preventDefault();
-        setVelocity(prev => prev + 15);
+        velocityRef.current -= ARROW_KEY_VELOCITY;
         pauseAutoScroll();
         scheduleAutoScrollResume();
         break;
-      case 'ArrowDown':
+      case 'ArrowUp':
         e.preventDefault();
-        setVelocity(prev => prev - 15);
+        velocityRef.current += ARROW_KEY_VELOCITY;
         pauseAutoScroll();
         scheduleAutoScrollResume();
         break;
-      case 'Home':
+      case 'End':
         e.preventDefault();
-        setPosition(0);
-        setVelocity(0);
+        if (loopPointRef.current > 0) {
+          commitPosition(-loopPointRef.current);
+        }
+        velocityRef.current = 0;
         pauseAutoScroll();
         scheduleAutoScrollResume();
         break;
-      case 'End':
+      case 'Home':
         e.preventDefault();
-        if (loopPoint > 0) {
-          setPosition(-loopPoint);
-        }
-        setVelocity(0);
+        commitPosition(0);
+        velocityRef.current = 0;
         pauseAutoScroll();
         scheduleAutoScrollResume();
         break;
       default:
         break;
     }
-  }, [togglePause, pauseAutoScroll, scheduleAutoScrollResume, loopPoint]);
-
-  const handleResize = useCallback(() => {
-    setContainerHeight(window.innerHeight);
-    if (containerRef.current) {
-      const currentContentHeight = containerRef.current.scrollHeight;
-      setContentHeight(currentContentHeight);
-      setLoopPoint(currentContentHeight / 3);
-    }
-  }, []);
+  }, [commitPosition, keyboard, pauseAutoScroll, scheduleAutoScrollResume, togglePause]);
+
+  const handleMouseDown = useCallback((e: globalThis.MouseEvent) => {
+    if (!draggable) return;
+    e.preventDefault();
+    containerRef.current?.focus();
+    setIsDragging(true);
+    isDraggingRef.current = true;
+    lastMouseYRef.current = e.clientY;
+    velocityRef.current = 0;
+    pauseAutoScroll();
+  }, [draggable, pauseAutoScroll]);
+
+  const handleMouseMove = useCallback((e: globalThis.MouseEvent) => {
+    if (!isDraggingRef.current) return;
+    e.preventDefault();
+    const deltaY = e.clientY - lastMouseYRef.current;
+    const nextPosition = wrapPosition(positionRef.current + deltaY);
+    commitPosition(nextPosition);
+    velocityRef.current = deltaY;
+    lastMouseYRef.current = e.clientY;
+  }, [commitPosition, wrapPosition]);
+
+  const handleMouseUp = useCallback((e: globalThis.MouseEvent) => {
+    if (!isDraggingRef.current) return;
+    e.preventDefault();
+    setIsDragging(false);
+    isDraggingRef.current = false;
+    scheduleAutoScrollResume();
+  }, [scheduleAutoScrollResume]);
+
+  const handleTouchEnd = useCallback((_e: globalThis.TouchEvent) => {
+    if (!isDraggingRef.current) return;
+    setIsDragging(false);
+    isDraggingRef.current = false;
+    scheduleAutoScrollResume();
+  }, [scheduleAutoScrollResume]);
+
+  const handleTouchMove = useCallback((e: globalThis.TouchEvent) => {
+    if (!isDraggingRef.current || e.touches.length !== 1) return;
+    e.preventDefault();
+    const touch = e.touches[0];
+    const deltaY = touch.clientY - lastTouchYRef.current;
+    const nextPosition = wrapPosition(positionRef.current + deltaY);
+    commitPosition(nextPosition);
+    velocityRef.current = deltaY;
+    lastTouchYRef.current = touch.clientY;
+  }, [commitPosition, wrapPosition]);
+
+  const handleTouchStart = useCallback((e: globalThis.TouchEvent) => {
+    if (!draggable || e.touches.length !== 1) return;
+    containerRef.current?.focus();
+    setIsDragging(true);
+    isDraggingRef.current = true;
+    lastTouchYRef.current = e.touches[0].clientY;
+    velocityRef.current = 0;
+    pauseAutoScroll();
+  }, [draggable, pauseAutoScroll]);
 
+  const handleWheel = useCallback((e: globalThis.WheelEvent) => {
+    if (!wheelEnabled) return;
+    e.preventDefault();
+    velocityRef.current -= e.deltaY * WHEEL_VELOCITY_MULTIPLIER;
+    velocityRef.current = Math.max(-MAX_VELOCITY, Math.min(MAX_VELOCITY, velocityRef.current));
+    pauseAutoScroll();
+    scheduleAutoScrollResume();
+  }, [pauseAutoScroll, scheduleAutoScrollResume, wheelEnabled]);
+
+  // Event listener registration
   useEffect(() => {
     const currentContainer = containerRef.current;
     if (!currentContainer) return;
 
-    // Create bound event handlers that maintain proper context
-    const boundHandlers = {
-      mouseDown: handleMouseDown,
-      mouseMove: handleMouseMove,
-      mouseUp: handleMouseUp,
-      touchStart: handleTouchStart,
-      touchMove: handleTouchMove,
-      touchEnd: handleTouchEnd,
-      wheel: handleWheel
+    currentContainer.addEventListener('mousedown', handleMouseDown);
+    window.addEventListener('mousemove', handleMouseMove);
+    window.addEventListener('mouseup', handleMouseUp);
+    currentContainer.addEventListener('touchstart', handleTouchStart, { passive: true });
+    window.addEventListener('touchmove', handleTouchMove, { passive: false });
+    window.addEventListener('touchend', handleTouchEnd, { passive: true });
+    currentContainer.addEventListener('wheel', handleWheel, { passive: false });
+
+    return () => {
+      currentContainer.removeEventListener('mousedown', handleMouseDown);
+      window.removeEventListener('mousemove', handleMouseMove);
+      window.removeEventListener('mouseup', handleMouseUp);
+      currentContainer.removeEventListener('touchstart', handleTouchStart);
+      window.removeEventListener('touchmove', handleTouchMove);
+      window.removeEventListener('touchend', handleTouchEnd);
+      currentContainer.removeEventListener('wheel', handleWheel);
     };
+  }, [handleMouseDown, handleMouseMove, handleMouseUp, handleTouchEnd, handleTouchMove, handleTouchStart, handleWheel]);
+
+  // Debounced resize handler shared by ResizeObserver and window resize fallback
+  const debouncedRecalculate = useCallback(() => {
+    if (resizeDebounceTimerRef.current) {
+      clearTimeout(resizeDebounceTimerRef.current);
+    }
+    resizeDebounceTimerRef.current = setTimeout(() => {
+      resizeDebounceTimerRef.current = null;
+      recalculateLoopPoint();
+    }, RESIZE_DEBOUNCE_MS);
+  }, [recalculateLoopPoint]);
 
-    // Add event listeners
-    currentContainer.addEventListener('mousedown', boundHandlers.mouseDown);
-    window.addEventListener('mousemove', boundHandlers.mouseMove);
-    window.addEventListener('mouseup', boundHandlers.mouseUp);
-    currentContainer.addEventListener('touchstart', boundHandlers.touchStart, { passive: true });
-    window.addEventListener('touchmove', boundHandlers.touchMove, { passive: false });
-    window.addEventListener('touchend', boundHandlers.touchEnd, { passive: true });
-    currentContainer.addEventListener('wheel', boundHandlers.wheel, { passive: false });
+  // Resize listener fallback for browsers without ResizeObserver
+  useEffect(() => {
+    window.addEventListener('resize', debouncedRecalculate);
 
     return () => {
-      currentContainer.removeEventListener('mousedown', boundHandlers.mouseDown);
-      window.removeEventListener('mousemove', boundHandlers.mouseMove);
-      window.removeEventListener('mouseup', boundHandlers.mouseUp);
-      currentContainer.removeEventListener('touchstart', boundHandlers.touchStart);
-      window.removeEventListener('touchmove', boundHandlers.touchMove);
-      window.removeEventListener('touchend', boundHandlers.touchEnd);
-      currentContainer.removeEventListener('wheel', boundHandlers.wheel);
+      window.removeEventListener('resize', debouncedRecalculate);
     };
-  }, [handleMouseDown, handleMouseMove, handleMouseUp, handleTouchStart, handleTouchMove, handleTouchEnd, handleWheel]);
+  }, [debouncedRecalculate]);
 
+  // ResizeObserver keeps loop measurements in sync with async content changes
   useEffect(() => {
-    document.addEventListener('keydown', handleKeyDown);
-    window.addEventListener('resize', handleResize);
+    if (!containerRef.current || typeof ResizeObserver === 'undefined') return;
+
+    const observer = new ResizeObserver(() => {
+      debouncedRecalculate();
+    });
+    observer.observe(containerRef.current);
 
     return () => {
-      document.removeEventListener('keydown', handleKeyDown);
-      window.removeEventListener('resize', handleResize);
+      observer.disconnect();
+    };
+  }, [debouncedRecalculate]);
+
+  // Clean up resize debounce timer on unmount
+  useEffect(() => {
+    return () => {
+      if (resizeDebounceTimerRef.current) {
+        clearTimeout(resizeDebounceTimerRef.current);
+        resizeDebounceTimerRef.current = null;
+      }
     };
-  }, [handleKeyDown, handleResize]);
+  }, []);
 
-  // Tab Visibility Handling
+  // Tab visibility handling
   useEffect(() => {
     const handleVisibilityChange = () => {
       setIsTabActive(!document.hidden);
@@ -257,7 +472,14 @@ function ReactSway({ children }: ReactSwayProps) {
     };
   }, []);
 
-  // Animation Loop
+  // Clean up inactivity timer on unmount
+  useEffect(() => {
+    return () => {
+      clearInactivityTimer();
+    };
+  }, [clearInactivityTimer]);
+
+  // Animation loop
   useEffect(() => {
     if (!isTabActive || isPaused) {
       if (animationFrameRef.current) {
@@ -267,52 +489,46 @@ function ReactSway({ children }: ReactSwayProps) {
       return;
     }
 
+    // Reset so the first frame uses deltaTime=1 instead of a stale timestamp
+    lastFrameTimeRef.current = 0;
+
+    const directionMultiplier = direction === 'down' ? 1 : -1;
+
     const animate = (currentTime: number) => {
-      let deltaTime = lastFrameTimeRef.current ? (currentTime - lastFrameTimeRef.current) / 16.667 : 1;
+      let deltaTime = lastFrameTimeRef.current
+        ? (currentTime - lastFrameTimeRef.current) / MS_PER_FRAME_60FPS
+        : 1;
       deltaTime = Math.min(deltaTime, MAX_DELTA_TIME);
       lastFrameTimeRef.current = currentTime;
 
-      setPosition(prevPosition => {
-        let newPosition = prevPosition;
-
-        // Auto-scroll when enabled
-        if (autoScrollEnabled && !isDragging && !isPaused) {
-          newPosition -= SCROLL_SPEED * deltaTime;
-        }
-
-        return newPosition;
-      });
-
-      setVelocity(prevVelocity => {
-        let newVelocity = prevVelocity;
+      // Apply velocity damping (skip momentum in reduced-motion mode)
+      if (prefersReducedMotion) {
+        velocityRef.current = 0;
+      } else if (Math.abs(velocityRef.current) > 0.1) {
+        velocityRef.current *= Math.pow(normalizedFriction, deltaTime);
+      } else {
+        velocityRef.current = 0;
+      }
 
-        if (Math.abs(newVelocity) > 0.1) {
-          if (!isDragging) {
-            setPosition(prev => prev + newVelocity * deltaTime);
-          }
-          newVelocity *= Math.pow(FRICTION, deltaTime);
-        } else {
-          newVelocity = 0;
-        }
+      let nextPosition = positionRef.current;
 
-        return newVelocity;
-      });
+      // Calculate effective speed (reduced when user prefers reduced motion)
+      const effectiveSpeed = prefersReducedMotion
+        ? normalizedSpeed * REDUCED_MOTION_SPEED_FACTOR
+        : normalizedSpeed;
 
-      // Handle position wrapping
-      setPosition(prevPosition => {
-        let newPosition = prevPosition;
+      // Auto-scroll when enabled and not dragging
+      if (autoScrollRef.current.desired && autoScrollRef.current.active && !isDraggingRef.current) {
+        nextPosition += directionMultiplier * effectiveSpeed * deltaTime;
+      }
 
-        if (loopPoint > 0) {
-          while (newPosition > 0) {
-            newPosition -= loopPoint;
-          }
-          while (newPosition < -loopPoint * 2) {
-            newPosition += loopPoint;
-          }
-        }
+      // Apply velocity momentum from user interaction
+      if (!isDraggingRef.current && Math.abs(velocityRef.current) > 0.1) {
+        nextPosition += velocityRef.current * deltaTime;
+      }
 
-        return newPosition;
-      });
+      nextPosition = wrapPosition(nextPosition);
+      commitPosition(nextPosition);
 
       animationFrameRef.current = requestAnimationFrame(animate);
     };
@@ -324,11 +540,11 @@ function ReactSway({ children }: ReactSwayProps) {
         cancelAnimationFrame(animationFrameRef.current);
       }
     };
-  }, [isTabActive, autoScrollEnabled, isDragging, isPaused, loopPoint]);
+  }, [commitPosition, direction, isPaused, isTabActive, normalizedFriction, normalizedSpeed, prefersReducedMotion, wrapPosition]);
 
-  // Intersection Observer for lazy loading
+  // Intersection Observer for lazy visibility detection
   useEffect(() => {
-    if (!containerRef.current) return;
+    if (!lazy || !containerRef.current || typeof IntersectionObserver === 'undefined') return;
 
     const observer = new IntersectionObserver(
       (entries) => {
@@ -340,8 +556,8 @@ function ReactSway({ children }: ReactSwayProps) {
       },
       {
         root: null,
-        rootMargin: '100px',
-        threshold: 0.01,
+        rootMargin: lazyRootMargin,
+        threshold: lazyThreshold,
       }
     );
 
@@ -352,60 +568,42 @@ function ReactSway({ children }: ReactSwayProps) {
       items.forEach((item) => observer.unobserve(item));
       observer.disconnect();
     };
-  }, [children, contentHeight]);
-
-  // Apply styles to override conflicting CSS
-  useEffect(() => {
-    const originalBodyStyle = {
-      touchAction: document.body.style.touchAction,
-      overflow: document.body.style.overflow
-    };
-
-    // Override body styles that might conflict
-    document.body.style.touchAction = 'none';
-    document.body.style.overflow = 'hidden';
-
-    return () => {
-      // Restore original styles
-      document.body.style.touchAction = originalBodyStyle.touchAction;
-      document.body.style.overflow = originalBodyStyle.overflow;
-    };
-  }, []);
+  }, [children, lazy, lazyRootMargin, lazyThreshold]);
 
   return (
     <div
       className="react-sway-container scroller-content"
       ref={containerRef}
       style={{
-        transform: `translate3d(0, ${visualPosition}px, 0)`,
-        cursor: isDragging ? 'grabbing' : 'grab',
+        cursor: draggable ? (isDragging ? 'grabbing' : 'grab') : 'default',
+        MozUserSelect: 'none',
+        msUserSelect: 'none',
+        overflow: 'hidden',
+        overscrollBehavior: 'contain',
+        pointerEvents: 'auto',
         position: 'absolute',
-        width: '100%',
-        willChange: 'transform',
-        WebkitTransform: 'translateZ(0)',
         touchAction: 'none',
+        transform: 'translate3d(0, 0px, 0)',
         userSelect: 'none',
         WebkitUserSelect: 'none',
-        msUserSelect: 'none',
-        MozUserSelect: 'none',
-        overscrollBehavior: 'contain',
-        // Ensure it's on top and can receive events
-        pointerEvents: 'auto',
-        zIndex: 1
+        width: '100%',
+        willChange: 'transform',
+        zIndex: 1,
       }}
-      tabIndex={0}
+      onKeyDown={keyboard ? handleKeyDown : undefined}
+      tabIndex={keyboard ? 0 : undefined}
     >
       <div className="content-group original">
         {children}
       </div>
-      <aside className="content-group duplicate" aria-hidden="true" data-duplicate="true" role="presentation">
+      <aside aria-hidden="true" className="content-group duplicate" data-duplicate="true" role="presentation">
         {children}
       </aside>
-      <aside className="content-group duplicate" aria-hidden="true" data-duplicate="true" role="presentation">
+      <aside aria-hidden="true" className="content-group duplicate" data-duplicate="true" role="presentation">
         {children}
       </aside>
     </div>
   );
 }
 
-export default ReactSway;
+export default ReactSway;