react-sway 0.3.1 → 0.4.1

package/dist/index.js

@@ -1,35 +1,85 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/ReactSway.tsx
+//#region src/edge-hover-velocity.ts
 /**
-* Core ReactSway component implementing axis-aware infinite scrolling interactions.
+* Defines the bounded spatial mapping from edge-hover depth to Sway velocity.
 */
-/** Velocity applied per arrow key press (pixels). */
-var ARROW_KEY_VELOCITY = 15;
 /** Default edge-hover activation thickness in pixels. */
 var DEFAULT_EDGE_HOVER_SIZE = 96;
-/** Default friction coefficient applied to velocity each frame. */
-var DEFAULT_FRICTION = .95;
-/** Default IntersectionObserver rootMargin for lazy visibility detection. */
-var DEFAULT_LAZY_ROOT_MARGIN = "100px";
-/** Default IntersectionObserver threshold for lazy visibility detection. */
-var DEFAULT_LAZY_THRESHOLD = .01;
-/** Default delay in milliseconds before auto-scroll resumes after user interaction. */
-var DEFAULT_RESUME_DELAY = 2e3;
-/** Default scroll speed in pixels per frame at 60fps. */
-var DEFAULT_SPEED = .5;
-/** Number of stacked content groups used to build the seamless loop. */
-var MIN_LOOP_SEGMENTS = 3;
-/** Maximum deltaTime cap to prevent physics instability during frame drops. */
-var MAX_DELTA_TIME = 3;
-/** Maximum allowed velocity magnitude to prevent runaway scrolling. */
-var MAX_VELOCITY = 150;
-/** Duration of a single frame at 60fps in milliseconds. */
-var MS_PER_FRAME_60FPS = 16.667;
-/** Speed multiplier when user prefers reduced motion (25% of normal). */
-var REDUCED_MOTION_SPEED_FACTOR = .25;
-/** Debounce delay in milliseconds for ResizeObserver callbacks. */
-var RESIZE_DEBOUNCE_MS = 150;
+/** Default maximum edge-hover speed relative to the configured base speed. */
+var DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER = 6;
+/** Upper bound for consumer-configured edge-hover speed amplification. */
+var MAX_EDGE_HOVER_SPEED_MULTIPLIER = 10;
+/** Normalized ingress band used to remove the zero-to-baseline velocity jump. */
+var EDGE_HOVER_ENTRY_FEATHER_INTENSITY = .08;
+/** Intensity reached at the physical edge of the visible viewport. */
+var EDGE_HOVER_PHYSICAL_EDGE_INTENSITY = .5;
+/** Historical physical-edge response retained before beyond-edge acceleration. */
+var EDGE_HOVER_PHYSICAL_EDGE_SPEED_MULTIPLIER = 3;
+function clampUnit(value) {
+	if (!Number.isFinite(value)) return 0;
+	return Math.max(0, Math.min(1, value));
+}
+function smoothUnitStep(value) {
+	const unitValue = clampUnit(value);
+	return unitValue * unitValue * (3 - 2 * unitValue);
+}
+function normalizeEdgeHoverIntensity(value) {
+	if (!Number.isFinite(value)) return 0;
+	const clampedValue = Math.max(-1, Math.min(1, value));
+	return clampedValue === 0 ? 0 : clampedValue;
+}
+function normalizeEdgeHoverSpeedMultiplier(value) {
+	if (!Number.isFinite(value)) return 6;
+	return Math.max(1, Math.min(MAX_EDGE_HOVER_SPEED_MULTIPLIER, value));
+}
+/**
+* Maps signed edge depth onto a bounded velocity scale.
+*
+* Intensity carries direction and lies in [-1, 1]. The speed multiplier is
+* the maximum amplification reached one activation-zone width beyond the
+* visible edge.
+*/
+function getEdgeHoverVelocityScale(intensity, speedMultiplier = 6) {
+	const normalizedIntensity = normalizeEdgeHoverIntensity(intensity);
+	if (normalizedIntensity === 0) return 0;
+	const direction = Math.sign(normalizedIntensity);
+	const depth = Math.abs(normalizedIntensity);
+	const maximumScale = normalizeEdgeHoverSpeedMultiplier(speedMultiplier);
+	if (depth < EDGE_HOVER_ENTRY_FEATHER_INTENSITY) return direction * smoothUnitStep(depth / EDGE_HOVER_ENTRY_FEATHER_INTENSITY);
+	const physicalEdgeScale = Math.min(EDGE_HOVER_PHYSICAL_EDGE_SPEED_MULTIPLIER, maximumScale);
+	if (depth <= EDGE_HOVER_PHYSICAL_EDGE_INTENSITY) {
+		const physicalEdgeProgress = (depth - EDGE_HOVER_ENTRY_FEATHER_INTENSITY) / (EDGE_HOVER_PHYSICAL_EDGE_INTENSITY - EDGE_HOVER_ENTRY_FEATHER_INTENSITY);
+		return direction * (1 + (physicalEdgeScale - 1) * smoothUnitStep(physicalEdgeProgress));
+	}
+	const beyondEdgeProgress = (depth - EDGE_HOVER_PHYSICAL_EDGE_INTENSITY) / (1 - EDGE_HOVER_PHYSICAL_EDGE_INTENSITY);
+	return direction * (physicalEdgeScale + (maximumScale - physicalEdgeScale) * smoothUnitStep(beyondEdgeProgress));
+}
+/**
+* Computes signed edge depth using a symmetric linear ramp.
+*
+* The inner edge of either activation zone maps to zero, the physical edge
+* maps to half intensity, and motion keeps accelerating outside the viewport
+* until it reaches the cap one activation-zone width beyond the visible edge.
+*/
+function getEdgeHoverIntensity(pointerPosition, visibleInterval, edgeHoverSize) {
+	const effectiveEdgeHoverSize = Math.min(Math.max(edgeHoverSize, 0), visibleInterval.size / 2);
+	if (effectiveEdgeHoverSize <= 0) return 0;
+	const accelerationDistance = effectiveEdgeHoverSize * 2;
+	const leadingEdgeEnd = visibleInterval.start + effectiveEdgeHoverSize;
+	if (pointerPosition <= leadingEdgeEnd) {
+		const leadingIntensity = clampUnit((leadingEdgeEnd - pointerPosition) / accelerationDistance);
+		if (leadingIntensity > 0) return leadingIntensity;
+	}
+	const trailingEdgeStart = visibleInterval.end - effectiveEdgeHoverSize;
+	if (pointerPosition >= trailingEdgeStart) {
+		const trailingIntensity = clampUnit((pointerPosition - trailingEdgeStart) / accelerationDistance);
+		if (trailingIntensity > 0) return -trailingIntensity;
+	}
+	return 0;
+}
+//#endregion
+//#region src/wheel-input.ts
 /** Fallback pixel height for wheel events reported in line units. */
 var WHEEL_LINE_HEIGHT_FALLBACK_PX = 16;
 /** WheelEvent deltaMode value for line-based deltas. */
@@ -38,24 +88,15 @@ var WHEEL_MODE_LINE = 1;
 var WHEEL_MODE_PAGE = 2;
 /** Minimum pixel impulse for discrete wheel hardware reporting tiny pixel deltas. */
 var WHEEL_PIXEL_MIN_DELTA_PX = 48;
-/** Multiplier applied to wheel deltaY to convert to scroll velocity. */
-var WHEEL_VELOCITY_MULTIPLIER = .14;
-/** Small immediate wheel movement used to keep input responsive without jumping. */
-var WHEEL_IMMEDIATE_DELTA_FACTOR = .14;
 /** Legacy wheelDelta magnitude that usually represents one physical wheel notch. */
 var WHEEL_LEGACY_NOTCH_DELTA = 120;
-/** Minimum touch movement before a gesture is classified by axis. */
-var TOUCH_AXIS_LOCK_THRESHOLD_PX = 8;
 function getLegacyWheelPixelDeltaY(event) {
 	const { wheelDelta, wheelDeltaY } = event;
 	const legacyWheelDelta = typeof wheelDeltaY === "number" ? wheelDeltaY : wheelDelta;
 	if (typeof legacyWheelDelta !== "number" || !Number.isFinite(legacyWheelDelta)) return 0;
 	return -(legacyWheelDelta / WHEEL_LEGACY_NOTCH_DELTA) * WHEEL_PIXEL_MIN_DELTA_PX;
 }
-/**
-* Converts wheel deltas to pixels so mouse wheels, touchpads, and page-wheel
-* devices feed the same Sway velocity system.
-*/
+/** Converts line, page, modern pixel, and legacy wheel deltas to pixels. */
 function normalizeWheelDelta(event, container, axis) {
 	const rawDelta = axis === "x" ? event.deltaX : event.deltaY;
 	if (event.deltaMode === WHEEL_MODE_LINE) {
@@ -68,6 +109,10 @@ function normalizeWheelDelta(event, container, axis) {
 	if (Math.abs(rawDelta) < WHEEL_PIXEL_MIN_DELTA_PX && Math.abs(legacyWheelPixelDeltaY) >= WHEEL_PIXEL_MIN_DELTA_PX) return legacyWheelPixelDeltaY;
 	return rawDelta;
 }
+/**
+* Returns Sway's signed pixel delta, or null when native scroll chaining owns
+* the gesture. This partial function is the wheel-ownership boundary.
+*/
 function getOwnedWheelDelta(event, container, isHorizontal, wheelMode) {
 	const deltaX = normalizeWheelDelta(event, container, "x");
 	const deltaY = normalizeWheelDelta(event, container, "y");
@@ -80,6 +125,41 @@ function getOwnedWheelDelta(event, container, isHorizontal, wheelMode) {
 	if (wheelMode === "axis" && absDeltaX > absDeltaY) return null;
 	return deltaY;
 }
+//#endregion
+//#region src/ReactSway.tsx
+/**
+* Core ReactSway component implementing axis-aware infinite scrolling interactions.
+*/
+/** Velocity applied per arrow key press (pixels). */
+var ARROW_KEY_VELOCITY = 15;
+/** Default friction coefficient applied to velocity each frame. */
+var DEFAULT_FRICTION = .95;
+/** Default IntersectionObserver rootMargin for lazy visibility detection. */
+var DEFAULT_LAZY_ROOT_MARGIN = "100px";
+/** Default IntersectionObserver threshold for lazy visibility detection. */
+var DEFAULT_LAZY_THRESHOLD = .01;
+/** Default delay in milliseconds before auto-scroll resumes after user interaction. */
+var DEFAULT_RESUME_DELAY = 2e3;
+/** Default scroll speed in pixels per frame at 60fps. */
+var DEFAULT_SPEED = .5;
+/** Minimum stacked content groups needed to cover a seamless loop phase. */
+var MIN_LOOP_SEGMENTS = 2;
+/** Maximum deltaTime cap to prevent physics instability during frame drops. */
+var MAX_DELTA_TIME = 3;
+/** Edge-hover catch-up cap; larger jumps read as stalls followed by snapping. */
+var MAX_EDGE_HOVER_DELTA_TIME = 1;
+/** Maximum allowed velocity magnitude to prevent runaway scrolling. */
+var MAX_VELOCITY = 150;
+/** Duration of a single frame at 60fps in milliseconds. */
+var MS_PER_FRAME_60FPS = 16.667;
+/** Speed multiplier when user prefers reduced motion (25% of normal). */
+var REDUCED_MOTION_SPEED_FACTOR = .25;
+/** Multiplier applied to wheel deltaY to convert to scroll velocity. */
+var WHEEL_VELOCITY_MULTIPLIER = .14;
+/** Small immediate wheel movement used to keep input responsive without jumping. */
+var WHEEL_IMMEDIATE_DELTA_FACTOR = .14;
+/** Minimum touch movement before a gesture is classified by axis. */
+var TOUCH_AXIS_LOCK_THRESHOLD_PX = 8;
 function getVisibleEdgeInterval(rect, isHorizontal) {
 	const rectEnd = isHorizontal ? rect.right : rect.bottom;
 	const rectStart = isHorizontal ? rect.left : rect.top;
@@ -113,10 +193,12 @@ function getVisibleEdgeInterval(rect, isHorizontal) {
 * </ReactSway>
 * ```
 */
-function ReactSway({ axis, autoScroll = true, children, direction = "up", draggable = true, edgeHoverScroll = false, edgeHoverSize = DEFAULT_EDGE_HOVER_SIZE, 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, wheelMode = "axis" }) {
+var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content", axis, autoScroll = true, children, className, direction = "up", draggable = true, edgeHoverInputMode = "hybrid", edgeHoverScroll = false, edgeHoverSize = 96, edgeHoverSpeedMultiplier = 6, 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, wheelMode = "axis" }, ref) {
 	const isHorizontal = useMemo(() => axis ?? (direction === "left" || direction === "right" ? "horizontal" : "vertical"), [axis, direction]) === "horizontal";
-	const normalizedEdgeHoverSize = useMemo(() => Number.isFinite(edgeHoverSize) ? Math.max(1, edgeHoverSize) : DEFAULT_EDGE_HOVER_SIZE, [edgeHoverSize]);
+	const normalizedEdgeHoverSize = useMemo(() => Number.isFinite(edgeHoverSize) ? Math.max(1, edgeHoverSize) : 96, [edgeHoverSize]);
+	const normalizedEdgeHoverSpeedMultiplier = useMemo(() => normalizeEdgeHoverSpeedMultiplier(edgeHoverSpeedMultiplier), [edgeHoverSpeedMultiplier]);
 	const normalizedFriction = useMemo(() => Number.isFinite(friction) ? Math.min(Math.max(friction, 0), 1) : DEFAULT_FRICTION, [friction]);
+	const normalizedLazyThreshold = useMemo(() => Number.isFinite(lazyThreshold) ? Math.min(Math.max(lazyThreshold, 0), 1) : DEFAULT_LAZY_THRESHOLD, [lazyThreshold]);
 	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 touchAction = useMemo(() => {
@@ -124,16 +206,15 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		return isHorizontal ? "pan-y" : "pan-x";
 	}, [draggable, isHorizontal]);
 	const overscrollBehavior = wheelEnabled && wheelMode === "capture" ? "contain" : "auto";
-	const [isDragging, setIsDragging] = useState(false);
 	const [isPaused, setIsPaused] = useState(false);
-	const [isTabActive, setIsTabActive] = useState(true);
-	const [loopPoint, setLoopPoint] = useState(0);
+	const [isTabActive, setIsTabActive] = useState(() => typeof document === "undefined" || !document.hidden);
 	const [loopSegmentCount, setLoopSegmentCount] = useState(MIN_LOOP_SEGMENTS);
 	const [prefersReducedMotion, setPrefersReducedMotion] = useState(() => {
 		if (typeof window === "undefined") return false;
 		return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	});
 	const animationFrameRef = useRef(null);
+	const animationLoopRef = useRef(null);
 	const autoScrollRef = useRef({
 		active: autoScroll,
 		desired: autoScroll
@@ -148,13 +229,19 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 	const lastTouchXRef = useRef(0);
 	const lastTouchYRef = useRef(0);
 	const loopPointRef = useRef(0);
-	const edgeHoverDirectionRef = useRef(0);
+	const edgeHoverIntervalCacheFrameRef = useRef(null);
+	const edgeHoverIntervalCacheRef = useRef(null);
+	const edgeHoverIntensityRef = useRef(0);
+	const externalEdgeHoverLeaseRef = useRef(false);
 	const onPauseRef = useRef(onPause);
 	const onResumeRef = useRef(onResume);
 	const onScrollRef = useRef(onScroll);
 	const originalGroupRef = useRef(null);
 	const positionRef = useRef(0);
-	const resizeDebounceTimerRef = useRef(null);
+	const loopMeasurementFrameRef = useRef(null);
+	const lastLoopMeasurementRef = useRef(null);
+	const mouseDragListenerCleanupRef = useRef(null);
+	const touchDragListenerCleanupRef = useRef(null);
 	const touchInteractionStateRef = useRef("idle");
 	const touchStartXRef = useRef(0);
 	const touchStartYRef = useRef(0);
@@ -184,6 +271,32 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		clearTimeout(inactivityTimerRef.current);
 		inactivityTimerRef.current = null;
 	}, []);
+	const startAnimationLoop = useCallback(() => {
+		if (animationFrameRef.current !== null || !animationLoopRef.current) return;
+		animationFrameRef.current = requestAnimationFrame(animationLoopRef.current);
+	}, []);
+	const clearEdgeHoverIntervalCache = useCallback(() => {
+		edgeHoverIntervalCacheRef.current = null;
+		if (edgeHoverIntervalCacheFrameRef.current !== null) {
+			cancelAnimationFrame(edgeHoverIntervalCacheFrameRef.current);
+			edgeHoverIntervalCacheFrameRef.current = null;
+		}
+	}, []);
+	const readVisibleEdgeInterval = useCallback((viewport) => {
+		const cachedInterval = edgeHoverIntervalCacheRef.current;
+		if (cachedInterval && cachedInterval.viewport === viewport && cachedInterval.isHorizontal === isHorizontal) return cachedInterval.interval;
+		const interval = getVisibleEdgeInterval(viewport.getBoundingClientRect(), isHorizontal);
+		edgeHoverIntervalCacheRef.current = {
+			interval,
+			isHorizontal,
+			viewport
+		};
+		if (edgeHoverIntervalCacheFrameRef.current === null) edgeHoverIntervalCacheFrameRef.current = requestAnimationFrame(() => {
+			edgeHoverIntervalCacheFrameRef.current = null;
+			edgeHoverIntervalCacheRef.current = null;
+		});
+		return interval;
+	}, [isHorizontal]);
 	const renderPosition = useCallback((rawPosition) => {
 		if (!containerRef.current) return;
 		const currentLoopPoint = loopPointRef.current;
@@ -200,22 +313,33 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 	const wrapPosition = useCallback((rawPosition) => {
 		const currentLoopPoint = loopPointRef.current;
 		if (currentLoopPoint <= 0) return rawPosition;
-		let wrappedPosition = rawPosition;
-		while (wrappedPosition > 0) wrappedPosition -= currentLoopPoint;
-		while (wrappedPosition < -currentLoopPoint * 2) wrappedPosition += currentLoopPoint;
+		if (rawPosition <= 0 && rawPosition >= -currentLoopPoint * 2) return rawPosition;
+		let wrappedPosition = rawPosition % currentLoopPoint;
+		if (wrappedPosition > 0) wrappedPosition -= currentLoopPoint;
 		return wrappedPosition;
 	}, []);
+	const setDraggingState = useCallback((nextIsDragging) => {
+		isDraggingRef.current = nextIsDragging;
+		if (containerRef.current && draggable) containerRef.current.style.cursor = nextIsDragging ? "grabbing" : "grab";
+	}, [draggable]);
 	const recalculateLoopPoint = useCallback(() => {
 		if (!containerRef.current || !originalGroupRef.current) return;
 		const originalContentSize = isHorizontal ? originalGroupRef.current.scrollWidth : originalGroupRef.current.scrollHeight;
 		if (originalContentSize <= 0) return;
 		const viewport = containerRef.current.parentElement ?? containerRef.current;
 		const viewportSize = isHorizontal ? Math.max(viewport.clientWidth, 1) : Math.max(viewport.clientHeight, 1);
-		const nextLoopSegmentCount = Math.max(MIN_LOOP_SEGMENTS, Math.ceil(viewportSize / originalContentSize) + 2);
+		const nextLoopSegmentCount = Math.max(MIN_LOOP_SEGMENTS, Math.ceil(viewportSize / originalContentSize) + 1);
 		const nextLoopPoint = originalContentSize;
+		const previousMeasurement = lastLoopMeasurementRef.current;
+		const nextMeasurement = {
+			contentSize: originalContentSize,
+			isHorizontal,
+			viewportSize
+		};
+		if (previousMeasurement?.contentSize === nextMeasurement.contentSize && previousMeasurement.isHorizontal === nextMeasurement.isHorizontal && previousMeasurement.viewportSize === nextMeasurement.viewportSize) return;
+		lastLoopMeasurementRef.current = nextMeasurement;
 		setLoopSegmentCount((previousLoopSegmentCount) => previousLoopSegmentCount === nextLoopSegmentCount ? previousLoopSegmentCount : nextLoopSegmentCount);
 		loopPointRef.current = nextLoopPoint;
-		setLoopPoint((previousLoopPoint) => Math.abs(previousLoopPoint - nextLoopPoint) < .5 ? previousLoopPoint : nextLoopPoint);
 		renderPosition(positionRef.current);
 	}, [isHorizontal, renderPosition]);
 	useEffect(() => {
@@ -223,20 +347,30 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		if (!autoScroll) {
 			clearInactivityTimer();
 			autoScrollRef.current.active = true;
-		}
-	}, [autoScroll, clearInactivityTimer]);
-	useEffect(() => {
-		loopPointRef.current = loopPoint;
-		renderPosition(positionRef.current);
-	}, [loopPoint, renderPosition]);
+		} else startAnimationLoop();
+	}, [
+		autoScroll,
+		clearInactivityTimer,
+		startAnimationLoop
+	]);
+	const scheduleLoopPointRecalculation = useCallback(() => {
+		clearEdgeHoverIntervalCache();
+		if (loopMeasurementFrameRef.current !== null) return;
+		loopMeasurementFrameRef.current = requestAnimationFrame(() => {
+			loopMeasurementFrameRef.current = null;
+			recalculateLoopPoint();
+		});
+	}, [clearEdgeHoverIntervalCache, recalculateLoopPoint]);
 	useEffect(() => {
-		const rafId = requestAnimationFrame(recalculateLoopPoint);
-		return () => {
-			cancelAnimationFrame(rafId);
-		};
-	}, [children, recalculateLoopPoint]);
+		lastLoopMeasurementRef.current = null;
+		scheduleLoopPointRecalculation();
+	}, [
+		children,
+		isHorizontal,
+		scheduleLoopPointRecalculation
+	]);
 	const pauseAutoScroll = useCallback(() => {
-		if (!pauseOnInteraction) return;
+		if (!pauseOnInteraction || !autoScrollRef.current.desired || !autoScrollRef.current.active) return;
 		autoScrollRef.current.active = false;
 		onPauseRef.current?.();
 		clearInactivityTimer();
@@ -249,11 +383,13 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 			if (!autoScrollRef.current.desired || isPausedRef.current) return;
 			autoScrollRef.current.active = true;
 			onResumeRef.current?.();
+			startAnimationLoop();
 		}, normalizedResumeDelay);
 	}, [
 		clearInactivityTimer,
 		normalizedResumeDelay,
-		pauseOnInteraction
+		pauseOnInteraction,
+		startAnimationLoop
 	]);
 	const togglePause = useCallback(() => {
 		const newPaused = !isPausedRef.current;
@@ -267,8 +403,22 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 			clearInactivityTimer();
 			autoScrollRef.current.active = true;
 			if (autoScrollRef.current.desired) onResumeRef.current?.();
+			startAnimationLoop();
 		}
-	}, [clearInactivityTimer]);
+	}, [clearInactivityTimer, startAnimationLoop]);
+	const setEdgeHoverIntensity = useCallback((nextIntensityValue) => {
+		const nextIntensity = normalizeEdgeHoverIntensity(nextIntensityValue);
+		edgeHoverIntensityRef.current = nextIntensity;
+		if (nextIntensity !== 0) startAnimationLoop();
+	}, [startAnimationLoop]);
+	const detachMouseDragListeners = useCallback(() => {
+		mouseDragListenerCleanupRef.current?.();
+		mouseDragListenerCleanupRef.current = null;
+	}, []);
+	const detachTouchDragListeners = useCallback(() => {
+		touchDragListenerCleanupRef.current?.();
+		touchDragListenerCleanupRef.current = null;
+	}, []);
 	const handleKeyDown = useCallback((e) => {
 		if (!keyboard) return;
 		switch (e.key) {
@@ -320,25 +470,16 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 				break;
 			default: break;
 		}
+		startAnimationLoop();
 	}, [
 		commitPosition,
 		isHorizontal,
 		keyboard,
 		pauseAutoScroll,
 		scheduleAutoScrollResume,
+		startAnimationLoop,
 		togglePause
 	]);
-	const handleMouseDown = useCallback((e) => {
-		if (!draggable) return;
-		e.preventDefault();
-		containerRef.current?.focus();
-		setIsDragging(true);
-		isDraggingRef.current = true;
-		lastMouseXRef.current = e.clientX;
-		lastMouseYRef.current = e.clientY;
-		velocityRef.current = 0;
-		pauseAutoScroll();
-	}, [draggable, pauseAutoScroll]);
 	const handleMouseMove = useCallback((e) => {
 		if (!isDraggingRef.current) return;
 		e.preventDefault();
@@ -356,19 +497,77 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 	const handleMouseUp = useCallback((e) => {
 		if (!isDraggingRef.current) return;
 		e.preventDefault();
-		setIsDragging(false);
-		isDraggingRef.current = false;
+		setDraggingState(false);
+		detachMouseDragListeners();
+		scheduleAutoScrollResume();
+		startAnimationLoop();
+	}, [
+		detachMouseDragListeners,
+		scheduleAutoScrollResume,
+		setDraggingState,
+		startAnimationLoop
+	]);
+	const handleMouseCancel = useCallback(() => {
+		if (!isDraggingRef.current) return;
+		setDraggingState(false);
+		detachMouseDragListeners();
 		scheduleAutoScrollResume();
-	}, [scheduleAutoScrollResume]);
+		startAnimationLoop();
+	}, [
+		detachMouseDragListeners,
+		scheduleAutoScrollResume,
+		setDraggingState,
+		startAnimationLoop
+	]);
+	const attachMouseDragListeners = useCallback(() => {
+		detachMouseDragListeners();
+		window.addEventListener("mousemove", handleMouseMove);
+		window.addEventListener("mouseup", handleMouseUp);
+		window.addEventListener("blur", handleMouseCancel);
+		mouseDragListenerCleanupRef.current = () => {
+			window.removeEventListener("mousemove", handleMouseMove);
+			window.removeEventListener("mouseup", handleMouseUp);
+			window.removeEventListener("blur", handleMouseCancel);
+		};
+	}, [
+		detachMouseDragListeners,
+		handleMouseCancel,
+		handleMouseMove,
+		handleMouseUp
+	]);
+	const handleMouseDown = useCallback((e) => {
+		if (!draggable) return;
+		e.preventDefault();
+		containerRef.current?.focus();
+		setDraggingState(true);
+		lastMouseXRef.current = e.clientX;
+		lastMouseYRef.current = e.clientY;
+		velocityRef.current = 0;
+		pauseAutoScroll();
+		attachMouseDragListeners();
+		startAnimationLoop();
+	}, [
+		attachMouseDragListeners,
+		draggable,
+		pauseAutoScroll,
+		setDraggingState,
+		startAnimationLoop
+	]);
 	const handleTouchEnd = useCallback((_e) => {
 		const wasActive = touchInteractionStateRef.current === "active";
 		touchInteractionStateRef.current = "idle";
-		if (isDraggingRef.current) {
-			setIsDragging(false);
-			isDraggingRef.current = false;
+		detachTouchDragListeners();
+		if (isDraggingRef.current) setDraggingState(false);
+		if (wasActive) {
+			scheduleAutoScrollResume();
+			startAnimationLoop();
 		}
-		if (wasActive) scheduleAutoScrollResume();
-	}, [scheduleAutoScrollResume]);
+	}, [
+		detachTouchDragListeners,
+		scheduleAutoScrollResume,
+		setDraggingState,
+		startAnimationLoop
+	]);
 	const handleTouchMove = useCallback((e) => {
 		if (touchInteractionStateRef.current === "idle" || touchInteractionStateRef.current === "ignored") return;
 		if (e.touches.length !== 1) return;
@@ -384,8 +583,7 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 				return;
 			}
 			touchInteractionStateRef.current = "active";
-			setIsDragging(true);
-			isDraggingRef.current = true;
+			setDraggingState(true);
 			pauseAutoScroll();
 		}
 		e.preventDefault();
@@ -399,8 +597,24 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		commitPosition,
 		isHorizontal,
 		pauseAutoScroll,
+		setDraggingState,
 		wrapPosition
 	]);
+	const attachTouchDragListeners = useCallback(() => {
+		detachTouchDragListeners();
+		window.addEventListener("touchmove", handleTouchMove, { passive: false });
+		window.addEventListener("touchend", handleTouchEnd, { passive: true });
+		window.addEventListener("touchcancel", handleTouchEnd, { passive: true });
+		touchDragListenerCleanupRef.current = () => {
+			window.removeEventListener("touchmove", handleTouchMove);
+			window.removeEventListener("touchend", handleTouchEnd);
+			window.removeEventListener("touchcancel", handleTouchEnd);
+		};
+	}, [
+		detachTouchDragListeners,
+		handleTouchEnd,
+		handleTouchMove
+	]);
 	const handleTouchStart = useCallback((e) => {
 		if (!draggable || e.touches.length !== 1) return;
 		containerRef.current?.focus();
@@ -410,13 +624,14 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		touchStartXRef.current = e.touches[0].clientX;
 		touchStartYRef.current = e.touches[0].clientY;
 		velocityRef.current = 0;
-	}, [draggable]);
+		attachTouchDragListeners();
+	}, [attachTouchDragListeners, draggable]);
 	const handleWheel = useCallback((e) => {
-		if (!wheelEnabled) return;
+		if (!wheelEnabled) return false;
 		const currentContainer = e.currentTarget instanceof HTMLElement ? e.currentTarget : containerRef.current;
-		if (!currentContainer) return;
+		if (!currentContainer) return false;
 		const ownedDelta = getOwnedWheelDelta(e, currentContainer, isHorizontal, wheelMode);
-		if (ownedDelta === null) return;
+		if (ownedDelta === null) return false;
 		e.preventDefault();
 		const wheelDelta = -ownedDelta;
 		const nextPosition = wrapPosition(positionRef.current + wheelDelta * WHEEL_IMMEDIATE_DELTA_FACTOR);
@@ -425,125 +640,155 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		velocityRef.current = Math.max(-150, Math.min(MAX_VELOCITY, velocityRef.current));
 		pauseAutoScroll();
 		scheduleAutoScrollResume();
+		startAnimationLoop();
+		return true;
 	}, [
 		commitPosition,
 		isHorizontal,
 		pauseAutoScroll,
 		scheduleAutoScrollResume,
+		startAnimationLoop,
 		wheelEnabled,
 		wheelMode,
 		wrapPosition
 	]);
-	const handleEdgeHoverMove = useCallback((e) => {
-		if (!edgeHoverScroll) return;
+	const applyEdgeHoverPoint = useCallback((point) => {
+		if (!edgeHoverScroll) return false;
 		const viewport = containerRef.current?.parentElement ?? containerRef.current;
-		if (!viewport) return;
-		const visibleInterval = getVisibleEdgeInterval(viewport.getBoundingClientRect(), isHorizontal);
+		if (!viewport) return false;
+		const visibleInterval = readVisibleEdgeInterval(viewport);
 		if (!visibleInterval) {
-			edgeHoverDirectionRef.current = 0;
-			return;
-		}
-		const pointerPosition = isHorizontal ? e.clientX : e.clientY;
-		const effectiveEdgeHoverSize = Math.min(normalizedEdgeHoverSize, visibleInterval.size / 2);
-		if (pointerPosition <= visibleInterval.start + effectiveEdgeHoverSize) {
-			edgeHoverDirectionRef.current = 1;
-			return;
-		}
-		if (pointerPosition >= visibleInterval.end - effectiveEdgeHoverSize) {
-			edgeHoverDirectionRef.current = -1;
-			return;
+			setEdgeHoverIntensity(0);
+			return false;
 		}
-		edgeHoverDirectionRef.current = 0;
+		const nextIntensity = getEdgeHoverIntensity(isHorizontal ? point.clientX : point.clientY, visibleInterval, normalizedEdgeHoverSize);
+		setEdgeHoverIntensity(nextIntensity);
+		return true;
 	}, [
 		edgeHoverScroll,
 		isHorizontal,
-		normalizedEdgeHoverSize
+		normalizedEdgeHoverSize,
+		readVisibleEdgeInterval,
+		setEdgeHoverIntensity
 	]);
+	const handleEdgeHover = useCallback((point) => {
+		const accepted = applyEdgeHoverPoint(point);
+		externalEdgeHoverLeaseRef.current = accepted;
+		return accepted;
+	}, [applyEdgeHoverPoint]);
+	const clearEdgeHover = useCallback(() => {
+		externalEdgeHoverLeaseRef.current = false;
+		setEdgeHoverIntensity(0);
+	}, [setEdgeHoverIntensity]);
+	useImperativeHandle(ref, () => ({
+		clearEdgeHover,
+		handleEdgeHover,
+		handleWheel
+	}), [
+		clearEdgeHover,
+		handleEdgeHover,
+		handleWheel
+	]);
+	const handleEdgeHoverMove = useCallback((e) => {
+		if (externalEdgeHoverLeaseRef.current) return;
+		applyEdgeHoverPoint(e);
+	}, [applyEdgeHoverPoint]);
 	const handleEdgeHoverLeave = useCallback(() => {
-		edgeHoverDirectionRef.current = 0;
-	}, []);
+		if (externalEdgeHoverLeaseRef.current) return;
+		setEdgeHoverIntensity(0);
+	}, [setEdgeHoverIntensity]);
 	useEffect(() => {
 		const currentContainer = containerRef.current;
 		if (!currentContainer) return;
-		currentContainer.addEventListener("mousedown", handleMouseDown);
-		window.addEventListener("mousemove", handleMouseMove);
-		window.addEventListener("mouseup", handleMouseUp);
 		if (draggable) {
+			currentContainer.addEventListener("mousedown", handleMouseDown);
 			currentContainer.addEventListener("touchstart", handleTouchStart, { passive: true });
-			window.addEventListener("touchmove", handleTouchMove, { passive: false });
-			window.addEventListener("touchend", handleTouchEnd, { passive: true });
 		}
 		if (wheelEnabled) currentContainer.addEventListener("wheel", handleWheel, { passive: false });
 		const edgeHoverTarget = currentContainer.parentElement ?? currentContainer;
-		edgeHoverTarget.addEventListener("mousemove", handleEdgeHoverMove);
-		edgeHoverTarget.addEventListener("mouseleave", handleEdgeHoverLeave);
+		const usesPointerEdgeHover = typeof window.PointerEvent === "function";
+		const usesNativeEdgeHover = edgeHoverScroll && edgeHoverInputMode === "hybrid";
+		if (usesNativeEdgeHover && usesPointerEdgeHover) {
+			edgeHoverTarget.addEventListener("pointermove", handleEdgeHoverMove);
+			edgeHoverTarget.addEventListener("pointerleave", handleEdgeHoverLeave);
+			edgeHoverTarget.addEventListener("pointercancel", clearEdgeHover);
+		} else if (usesNativeEdgeHover) {
+			edgeHoverTarget.addEventListener("mousemove", handleEdgeHoverMove);
+			edgeHoverTarget.addEventListener("mouseleave", handleEdgeHoverLeave);
+		}
 		return () => {
-			currentContainer.removeEventListener("mousedown", handleMouseDown);
-			window.removeEventListener("mousemove", handleMouseMove);
-			window.removeEventListener("mouseup", handleMouseUp);
 			if (draggable) {
+				currentContainer.removeEventListener("mousedown", handleMouseDown);
 				currentContainer.removeEventListener("touchstart", handleTouchStart);
-				window.removeEventListener("touchmove", handleTouchMove);
-				window.removeEventListener("touchend", handleTouchEnd);
 			}
 			if (wheelEnabled) currentContainer.removeEventListener("wheel", handleWheel);
-			edgeHoverTarget.removeEventListener("mousemove", handleEdgeHoverMove);
-			edgeHoverTarget.removeEventListener("mouseleave", handleEdgeHoverLeave);
+			if (usesNativeEdgeHover && usesPointerEdgeHover) {
+				edgeHoverTarget.removeEventListener("pointermove", handleEdgeHoverMove);
+				edgeHoverTarget.removeEventListener("pointerleave", handleEdgeHoverLeave);
+				edgeHoverTarget.removeEventListener("pointercancel", clearEdgeHover);
+			} else if (usesNativeEdgeHover) {
+				edgeHoverTarget.removeEventListener("mousemove", handleEdgeHoverMove);
+				edgeHoverTarget.removeEventListener("mouseleave", handleEdgeHoverLeave);
+			}
+			detachMouseDragListeners();
+			detachTouchDragListeners();
 		};
 	}, [
+		detachMouseDragListeners,
+		detachTouchDragListeners,
 		draggable,
+		edgeHoverScroll,
+		edgeHoverInputMode,
+		clearEdgeHover,
 		handleEdgeHoverLeave,
 		handleEdgeHoverMove,
 		handleMouseDown,
-		handleMouseMove,
-		handleMouseUp,
-		handleTouchEnd,
-		handleTouchMove,
 		handleTouchStart,
 		handleWheel,
 		wheelEnabled
 	]);
-	const debouncedRecalculate = useCallback(() => {
-		if (resizeDebounceTimerRef.current) clearTimeout(resizeDebounceTimerRef.current);
-		resizeDebounceTimerRef.current = setTimeout(() => {
-			resizeDebounceTimerRef.current = null;
-			recalculateLoopPoint();
-		}, RESIZE_DEBOUNCE_MS);
-	}, [recalculateLoopPoint]);
 	useEffect(() => {
-		window.addEventListener("resize", debouncedRecalculate);
+		window.addEventListener("resize", scheduleLoopPointRecalculation);
 		return () => {
-			window.removeEventListener("resize", debouncedRecalculate);
+			window.removeEventListener("resize", scheduleLoopPointRecalculation);
 		};
-	}, [debouncedRecalculate]);
+	}, [scheduleLoopPointRecalculation]);
 	useEffect(() => {
-		if (!containerRef.current || typeof ResizeObserver === "undefined") return;
+		if (!containerRef.current || !originalGroupRef.current || typeof ResizeObserver === "undefined") return;
+		const currentContainer = containerRef.current;
+		const originalGroup = originalGroupRef.current;
+		const viewport = currentContainer.parentElement ?? currentContainer;
 		const observer = new ResizeObserver(() => {
-			debouncedRecalculate();
+			scheduleLoopPointRecalculation();
 		});
-		observer.observe(containerRef.current);
+		observer.observe(originalGroup);
+		if (viewport !== originalGroup) observer.observe(viewport);
 		return () => {
 			observer.disconnect();
 		};
-	}, [debouncedRecalculate]);
+	}, [scheduleLoopPointRecalculation]);
 	useEffect(() => {
 		return () => {
-			if (resizeDebounceTimerRef.current) {
-				clearTimeout(resizeDebounceTimerRef.current);
-				resizeDebounceTimerRef.current = null;
+			if (loopMeasurementFrameRef.current !== null) {
+				cancelAnimationFrame(loopMeasurementFrameRef.current);
+				loopMeasurementFrameRef.current = null;
 			}
+			clearEdgeHoverIntervalCache();
 		};
-	}, []);
+	}, [clearEdgeHoverIntervalCache]);
 	useEffect(() => {
 		const handleVisibilityChange = () => {
 			setIsTabActive(!document.hidden);
-			if (!document.hidden) lastFrameTimeRef.current = performance.now();
+			if (!document.hidden) {
+				lastFrameTimeRef.current = performance.now();
+				startAnimationLoop();
+			}
 		};
 		document.addEventListener("visibilitychange", handleVisibilityChange);
 		return () => {
 			document.removeEventListener("visibilitychange", handleVisibilityChange);
 		};
-	}, []);
+	}, [startAnimationLoop]);
 	useEffect(() => {
 		return () => {
 			clearInactivityTimer();
@@ -551,10 +796,11 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 	}, [clearInactivityTimer]);
 	useEffect(() => {
 		if (!isTabActive || isPaused) {
-			if (animationFrameRef.current) {
+			if (animationFrameRef.current !== null) {
 				cancelAnimationFrame(animationFrameRef.current);
 				animationFrameRef.current = null;
 			}
+			animationLoopRef.current = null;
 			return;
 		}
 		lastFrameTimeRef.current = 0;
@@ -568,27 +814,43 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 			else velocityRef.current = 0;
 			let nextPosition = positionRef.current;
 			const effectiveSpeed = prefersReducedMotion ? normalizedSpeed * REDUCED_MOTION_SPEED_FACTOR : normalizedSpeed;
-			const edgeHoverMultiplier = edgeHoverScroll ? edgeHoverDirectionRef.current : directionMultiplier;
-			if (autoScrollRef.current.desired && autoScrollRef.current.active && !isDraggingRef.current && (!edgeHoverScroll || edgeHoverMultiplier !== 0)) nextPosition += edgeHoverMultiplier * effectiveSpeed * deltaTime;
-			if (!isDraggingRef.current && Math.abs(velocityRef.current) > .1) nextPosition += velocityRef.current * deltaTime;
+			const edgeHoverMultiplier = edgeHoverScroll ? getEdgeHoverVelocityScale(edgeHoverIntensityRef.current, normalizedEdgeHoverSpeedMultiplier) : directionMultiplier;
+			const shouldAutoScroll = (autoScrollRef.current.desired && autoScrollRef.current.active || externalEdgeHoverLeaseRef.current) && !isDraggingRef.current && (!edgeHoverScroll || edgeHoverMultiplier !== 0);
+			if (shouldAutoScroll) {
+				const autoScrollDeltaTime = edgeHoverScroll ? Math.min(deltaTime, MAX_EDGE_HOVER_DELTA_TIME) : deltaTime;
+				nextPosition += edgeHoverMultiplier * effectiveSpeed * autoScrollDeltaTime;
+			}
+			const shouldApplyMomentum = !isDraggingRef.current && Math.abs(velocityRef.current) > .1;
+			if (shouldApplyMomentum) nextPosition += velocityRef.current * deltaTime;
 			nextPosition = wrapPosition(nextPosition);
 			commitPosition(nextPosition);
-			animationFrameRef.current = requestAnimationFrame(animate);
+			if (isDraggingRef.current || shouldAutoScroll || shouldApplyMomentum) {
+				animationFrameRef.current = requestAnimationFrame(animate);
+				return;
+			}
+			animationFrameRef.current = null;
+			lastFrameTimeRef.current = 0;
 		};
-		animationFrameRef.current = requestAnimationFrame(animate);
+		animationLoopRef.current = animate;
+		startAnimationLoop();
 		return () => {
-			if (animationFrameRef.current) cancelAnimationFrame(animationFrameRef.current);
+			if (animationFrameRef.current !== null) {
+				cancelAnimationFrame(animationFrameRef.current);
+				animationFrameRef.current = null;
+			}
+			if (animationLoopRef.current === animate) animationLoopRef.current = null;
 		};
 	}, [
 		commitPosition,
 		direction,
 		edgeHoverScroll,
-		isHorizontal,
 		isPaused,
 		isTabActive,
 		normalizedFriction,
+		normalizedEdgeHoverSpeedMultiplier,
 		normalizedSpeed,
 		prefersReducedMotion,
+		startAnimationLoop,
 		wrapPosition
 	]);
 	useEffect(() => {
@@ -600,7 +862,7 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		}, {
 			root: null,
 			rootMargin: lazyRootMargin,
-			threshold: lazyThreshold
+			threshold: normalizedLazyThreshold
 		});
 		const items = containerRef.current.querySelectorAll(".content-item");
 		items.forEach((item) => observer.observe(item));
@@ -612,13 +874,14 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 		children,
 		lazy,
 		lazyRootMargin,
-		lazyThreshold
+		normalizedLazyThreshold
 	]);
-	return /* @__PURE__ */ jsxs("div", {
-		className: "react-sway-container scroller-content",
+	return /* @__PURE__ */ jsxs("section", {
+		"aria-label": ariaLabel,
+		className: `react-sway-container scroller-content${className ? ` ${className}` : ""}`,
 		ref: containerRef,
 		style: {
-			cursor: draggable ? isDragging ? "grabbing" : "grab" : "default",
+			cursor: draggable ? isDraggingRef.current ? "grabbing" : "grab" : "default",
 			display: isHorizontal ? "flex" : void 0,
 			flexDirection: isHorizontal ? "row" : void 0,
 			height: isHorizontal ? "100%" : "max-content",
@@ -651,14 +914,16 @@ function ReactSway({ axis, autoScroll = true, children, direction = "up", dragga
 			"aria-hidden": "true",
 			className: "content-group duplicate",
 			"data-duplicate": "true",
+			inert: true,
 			role: "presentation",
 			style: isHorizontal ? {
 				display: "flex",
-				flex: "0 0 auto"
-			} : void 0,
+				flex: "0 0 auto",
+				pointerEvents: "none"
+			} : { pointerEvents: "none" },
 			children
 		}, `duplicate-${duplicateIndex}`))]
 	});
-}
+});
 //#endregion
-export { ReactSway };
+export { DEFAULT_EDGE_HOVER_SIZE, DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER, ReactSway };