r3f-motion 1.0.4 → 1.0.6

package/dist/cjs/index.js

@@ -4,9 +4,29 @@
 var tslib = require('tslib');
 var react = require('react');
 var motion$1 = require('motion');
-var jsxRuntime = require('react/jsx-runtime');
 var fiber = require('@react-three/fiber');
-var three = require('three');
+var THREE = require('three');
+var jsxRuntime = require('react/jsx-runtime');
+var react$1 = require('motion/react');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var THREE__namespace = /*#__PURE__*/_interopNamespaceDefault(THREE);
 
 const PresenceContext = react.createContext(null);
 /**
@@ -32,6 +52,7 @@ const useRender = (Component, props, forwardedRef, instanceRef, initialValues) =
      * Create a callback ref that captures the Three.js instance
      */
     const callbackRef = react.useCallback((instance) => {
+        var _a;
         if (!instance)
             return;
         // Apply initial values immediately to prevent FOUC - but only once
@@ -70,6 +91,12 @@ const useRender = (Component, props, forwardedRef, instanceRef, initialValues) =
                         colorProp.set(initialValues[key]);
                     }
                 }
+                else if (instance.uniforms &&
+                    instance.uniforms[key] &&
+                    typeof ((_a = instance.uniforms[key]) === null || _a === void 0 ? void 0 : _a.value) === "number") {
+                    // Set ShaderMaterial uniform initial value
+                    instance.uniforms[key].value = initialValues[key];
+                }
                 else if (key in instance && typeof instance[key] === "number") {
                     instance[key] = initialValues[key];
                 }
@@ -242,6 +269,389 @@ function useTap(isStatic, props, options) {
     };
 }
 
+// World-space units per CSS pixel at the given depth from the camera.
+const getWorldPerPixel = (camera, depth, viewportHeight) => {
+    var _a;
+    const ortho = camera;
+    if (ortho.isOrthographicCamera) {
+        return ((ortho.top - ortho.bottom) / (viewportHeight * (ortho.zoom || 1)));
+    }
+    const persp = camera;
+    const fov = ((_a = persp.fov) !== null && _a !== void 0 ? _a : 60) * (Math.PI / 180);
+    return (2 * Math.tan(fov / 2) * depth) / viewportHeight;
+};
+const clampWithElastic = (value, min, max, elastic) => {
+    if (min !== undefined && value < min)
+        return min + (value - min) * elastic;
+    if (max !== undefined && value > max)
+        return max + (value - max) * elastic;
+    return value;
+};
+function useDrag(isStatic, props, options) {
+    const { camera, gl } = fiber.useThree();
+    const { drag, whileDrag, onDragStart, onPointerDown, transition } = props;
+    const { instanceRef, captureInstanceState, buildTargetFromState, animateToTarget, resolveVariant, stopAnimation, } = options;
+    const isDraggingRef = react.useRef(false);
+    const dragStartPointerRef = react.useRef({ x: 0, y: 0 });
+    const dragStartPosRef = react.useRef(new THREE__namespace.Vector3());
+    const cameraRightRef = react.useRef(new THREE__namespace.Vector3());
+    const cameraUpRef = react.useRef(new THREE__namespace.Vector3());
+    const worldPerPixelRef = react.useRef(0);
+    const targetPosRef = react.useRef(new THREE__namespace.Vector3());
+    const lastPosRef = react.useRef(new THREE__namespace.Vector3());
+    const velocityRef = react.useRef(new THREE__namespace.Vector3());
+    const lastDeltaRef = react.useRef(new THREE__namespace.Vector3());
+    const lastTimeRef = react.useRef(0);
+    const preDragStateRef = react.useRef(null);
+    const pointerIdRef = react.useRef(null);
+    const springStateRef = react.useRef(null);
+    const lastFrameTimeRef = react.useRef(0);
+    const propsRef = react.useRef(props);
+    propsRef.current = props;
+    fiber.useFrame(() => {
+        var _a;
+        const instance = instanceRef.current;
+        if (!instance)
+            return;
+        const obj = instance;
+        // Phase 1: dragging — apply the drag target
+        if (isDraggingRef.current) {
+            const t = targetPosRef.current;
+            obj.position.set(t.x, t.y, t.z);
+            return;
+        }
+        // Phase 2: spring (momentum / snap-to-origin)
+        const s = springStateRef.current;
+        if (!s || !s.active)
+            return;
+        const now = performance.now();
+        let dt = (now - lastFrameTimeRef.current) / 1000;
+        if (dt > 0.05)
+            dt = 0.05;
+        if (dt <= 0)
+            dt = 1 / 60;
+        lastFrameTimeRef.current = now;
+        // Sub-step the integrator for stability with stiff springs
+        const subSteps = 4;
+        const subDt = dt / subSteps;
+        for (let i = 0; i < subSteps; i++) {
+            if (s.hasX) {
+                const force = -s.stiffness * (obj.position.x - s.targetX) - s.damping * s.velX;
+                s.velX += force * subDt;
+                obj.position.x += s.velX * subDt;
+            }
+            if (s.hasY) {
+                const force = -s.stiffness * (obj.position.y - s.targetY) - s.damping * s.velY;
+                s.velY += force * subDt;
+                obj.position.y += s.velY * subDt;
+            }
+            if (s.hasZ) {
+                const force = -s.stiffness * (obj.position.z - s.targetZ) - s.damping * s.velZ;
+                s.velZ += force * subDt;
+                obj.position.z += s.velZ * subDt;
+            }
+        }
+        // Rest detection — stop when both speed and offset are tiny
+        const speedSq = s.velX * s.velX + s.velY * s.velY + s.velZ * s.velZ;
+        const offX = s.hasX ? obj.position.x - s.targetX : 0;
+        const offY = s.hasY ? obj.position.y - s.targetY : 0;
+        const offZ = s.hasZ ? obj.position.z - s.targetZ : 0;
+        const offsetSq = offX * offX + offY * offY + offZ * offZ;
+        if (speedSq < 0.0005 && offsetSq < 0.0005) {
+            if (s.hasX)
+                obj.position.x = s.targetX;
+            if (s.hasY)
+                obj.position.y = s.targetY;
+            if (s.hasZ)
+                obj.position.z = s.targetZ;
+            s.active = false;
+            (_a = s.onComplete) === null || _a === void 0 ? void 0 : _a.call(s);
+        }
+    });
+    const handlePointerDown = react.useCallback((event) => {
+        const instance = instanceRef.current;
+        if (!instance)
+            return;
+        event.stopPropagation();
+        // Halt any in-flight motion-library animation (e.g. main `animate` prop
+        // tween that's still running) and any active drag spring.
+        stopAnimation();
+        if (springStateRef.current)
+            springStateRef.current.active = false;
+        if (whileDrag) {
+            preDragStateRef.current = captureInstanceState();
+            const targetValues = typeof whileDrag === "string"
+                ? resolveVariant(whileDrag)
+                : whileDrag;
+            animateToTarget(targetValues, transition || { duration: 0.1 });
+        }
+        const obj = instance;
+        // Capture initial pointer + position. All subsequent moves are computed
+        // as `initialPos + pixelDelta * worldPerPixel` — never re-derived from
+        // the live (potentially-mid-animation) instance position.
+        dragStartPointerRef.current.x = event.nativeEvent.clientX;
+        dragStartPointerRef.current.y = event.nativeEvent.clientY;
+        dragStartPosRef.current.set(obj.position.x, obj.position.y, obj.position.z);
+        targetPosRef.current.copy(dragStartPosRef.current);
+        lastPosRef.current.copy(dragStartPosRef.current);
+        lastDeltaRef.current.set(0, 0, 0);
+        velocityRef.current.set(0, 0, 0);
+        lastTimeRef.current = performance.now();
+        // Compute world-units-per-pixel at the object's perpendicular depth
+        // (distance from camera along its forward axis).
+        const cameraForward = new THREE__namespace.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
+        const cameraToObj = new THREE__namespace.Vector3().subVectors(dragStartPosRef.current, camera.position);
+        const depth = Math.abs(cameraToObj.dot(cameraForward));
+        const rect = gl.domElement.getBoundingClientRect();
+        worldPerPixelRef.current = getWorldPerPixel(camera, depth, rect.height);
+        // Cache camera basis vectors so screen X/Y maps correctly to world
+        // X/Y/Z even if the camera is tilted.
+        cameraRightRef.current.set(1, 0, 0).applyQuaternion(camera.quaternion);
+        cameraUpRef.current.set(0, 1, 0).applyQuaternion(camera.quaternion);
+        isDraggingRef.current = true;
+        pointerIdRef.current = event.nativeEvent.pointerId;
+        try {
+            gl.domElement.setPointerCapture(event.nativeEvent.pointerId);
+        }
+        catch (_a) {
+            // not all environments support setPointerCapture
+        }
+        onDragStart === null || onDragStart === void 0 ? void 0 : onDragStart(event.nativeEvent, {
+            point: { x: event.nativeEvent.clientX, y: event.nativeEvent.clientY },
+            offset: { x: 0, y: 0, z: 0 },
+            delta: { x: 0, y: 0, z: 0 },
+            velocity: { x: 0, y: 0, z: 0 },
+        });
+        onPointerDown === null || onPointerDown === void 0 ? void 0 : onPointerDown(event);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        whileDrag,
+        onDragStart,
+        onPointerDown,
+        camera,
+        gl,
+        captureInstanceState,
+        resolveVariant,
+        animateToTarget,
+        stopAnimation,
+        transition,
+        instanceRef,
+    ]);
+    react.useEffect(() => {
+        const handlePointerMove = (event) => {
+            var _a;
+            if (!isDraggingRef.current || event.pointerId !== pointerIdRef.current)
+                return;
+            const instance = instanceRef.current;
+            if (!instance)
+                return;
+            const cur = propsRef.current;
+            const dragAxis = cur.drag;
+            const elasticVal = typeof cur.dragElastic === "number"
+                ? cur.dragElastic
+                : cur.dragElastic === false
+                    ? 0
+                    : 0.5;
+            const constraints = cur.dragConstraints;
+            const pixelDx = event.clientX - dragStartPointerRef.current.x;
+            const pixelDy = event.clientY - dragStartPointerRef.current.y;
+            const scale = worldPerPixelRef.current;
+            let newX = dragStartPosRef.current.x;
+            let newY = dragStartPosRef.current.y;
+            let newZ = dragStartPosRef.current.z;
+            if (dragAxis === "z") {
+                // Vertical screen movement → Z. Cursor down (pixelDy > 0) = closer.
+                newZ = dragStartPosRef.current.z + pixelDy * scale;
+            }
+            else {
+                // Map screen XY to camera-relative world delta.
+                const r = cameraRightRef.current;
+                const u = cameraUpRef.current;
+                const worldDx = r.x * pixelDx * scale + u.x * -pixelDy * scale;
+                const worldDy = r.y * pixelDx * scale + u.y * -pixelDy * scale;
+                const worldDz = r.z * pixelDx * scale + u.z * -pixelDy * scale;
+                if (dragAxis === "x") {
+                    newX = dragStartPosRef.current.x + worldDx;
+                }
+                else if (dragAxis === "y") {
+                    newY = dragStartPosRef.current.y + worldDy;
+                }
+                else {
+                    newX = dragStartPosRef.current.x + worldDx;
+                    newY = dragStartPosRef.current.y + worldDy;
+                    newZ = dragStartPosRef.current.z + worldDz;
+                }
+            }
+            // Constraints with elastic rubber-banding
+            if (constraints) {
+                if (dragAxis !== "y" && dragAxis !== "z") {
+                    newX = clampWithElastic(newX, constraints.left, constraints.right, elasticVal);
+                }
+                if (dragAxis !== "x" && dragAxis !== "z") {
+                    newY = clampWithElastic(newY, constraints.bottom, constraints.top, elasticVal);
+                }
+            }
+            // Velocity tracking (used for momentum on release)
+            const now = performance.now();
+            const dt = (now - lastTimeRef.current) / 1000;
+            if (dt > 0) {
+                const dx = newX - lastPosRef.current.x;
+                const dy = newY - lastPosRef.current.y;
+                const dz = newZ - lastPosRef.current.z;
+                velocityRef.current.set(dx / dt, dy / dt, dz / dt);
+                lastDeltaRef.current.set(dx, dy, dz);
+            }
+            lastTimeRef.current = now;
+            lastPosRef.current.set(newX, newY, newZ);
+            // Stash target — useFrame applies it next R3F frame.
+            targetPosRef.current.set(newX, newY, newZ);
+            const offset = {
+                x: newX - dragStartPosRef.current.x,
+                y: newY - dragStartPosRef.current.y,
+                z: newZ - dragStartPosRef.current.z,
+            };
+            (_a = cur.onDrag) === null || _a === void 0 ? void 0 : _a.call(cur, event, {
+                point: { x: event.clientX, y: event.clientY },
+                offset,
+                delta: {
+                    x: lastDeltaRef.current.x,
+                    y: lastDeltaRef.current.y,
+                    z: lastDeltaRef.current.z,
+                },
+                velocity: {
+                    x: velocityRef.current.x,
+                    y: velocityRef.current.y,
+                    z: velocityRef.current.z,
+                },
+            });
+        };
+        const handlePointerUp = (event) => {
+            var _a, _b;
+            if (!isDraggingRef.current || event.pointerId !== pointerIdRef.current)
+                return;
+            isDraggingRef.current = false;
+            pointerIdRef.current = null;
+            const instance = instanceRef.current;
+            const cur = propsRef.current;
+            // Lock in the final dragged position synchronously. Once useFrame stops
+            // applying the drag target, a still-pending write from the *previous*
+            // momentum animation can land before the new animateToTarget() call
+            // reads instance.position to use as its "from" value — which causes the
+            // new animation to start from the old momentum's path instead of where
+            // the user actually released.
+            if (instance) {
+                const obj = instance;
+                const t = targetPosRef.current;
+                obj.position.set(t.x, t.y, t.z);
+            }
+            // Restore whileDrag visual state
+            if (cur.whileDrag && preDragStateRef.current) {
+                const targetValues = buildTargetFromState(preDragStateRef.current);
+                animateToTarget(targetValues, options.transition || { duration: 0.2 });
+                const dur = ((_a = options.transition) === null || _a === void 0 ? void 0 : _a.duration) || 0.2;
+                setTimeout(() => {
+                    preDragStateRef.current = null;
+                }, dur * 1000);
+            }
+            if (!instance)
+                return;
+            const finalPos = targetPosRef.current;
+            const offset = {
+                x: finalPos.x - dragStartPosRef.current.x,
+                y: finalPos.y - dragStartPosRef.current.y,
+                z: finalPos.z - dragStartPosRef.current.z,
+            };
+            const vel = velocityRef.current;
+            // Read spring tuning from dragTransition (if user provided one).
+            const dt = cur.dragTransition;
+            const userStiffness = typeof (dt === null || dt === void 0 ? void 0 : dt.stiffness) === "number" ? dt.stiffness : undefined;
+            const userDamping = typeof (dt === null || dt === void 0 ? void 0 : dt.damping) === "number" ? dt.damping : undefined;
+            if (cur.dragSnapToOrigin) {
+                lastFrameTimeRef.current = performance.now();
+                springStateRef.current = {
+                    active: true,
+                    targetX: dragStartPosRef.current.x,
+                    targetY: dragStartPosRef.current.y,
+                    targetZ: dragStartPosRef.current.z,
+                    velX: vel.x,
+                    velY: vel.y,
+                    velZ: vel.z,
+                    hasX: true,
+                    hasY: true,
+                    hasZ: true,
+                    stiffness: userStiffness !== null && userStiffness !== void 0 ? userStiffness : 400,
+                    damping: userDamping !== null && userDamping !== void 0 ? userDamping : 40,
+                };
+            }
+            else if (cur.dragMomentum !== false) {
+                const speed = Math.sqrt(Math.pow(vel.x, 2) + Math.pow(vel.y, 2) + Math.pow(vel.z, 2));
+                if (speed > 0.5) {
+                    const coeff = 0.25;
+                    const dragAxis = cur.drag;
+                    const hasX = dragAxis !== "y" && dragAxis !== "z";
+                    const hasY = dragAxis !== "x" && dragAxis !== "z";
+                    const hasZ = dragAxis === "z";
+                    let targetX = hasX ? finalPos.x + vel.x * coeff : finalPos.x;
+                    let targetY = hasY ? finalPos.y + vel.y * coeff : finalPos.y;
+                    const targetZ = hasZ ? finalPos.z + vel.z * coeff : finalPos.z;
+                    const constraints = cur.dragConstraints;
+                    if (constraints) {
+                        if (hasX) {
+                            if (constraints.left !== undefined)
+                                targetX = Math.max(targetX, constraints.left);
+                            if (constraints.right !== undefined)
+                                targetX = Math.min(targetX, constraints.right);
+                        }
+                        if (hasY) {
+                            if (constraints.bottom !== undefined)
+                                targetY = Math.max(targetY, constraints.bottom);
+                            if (constraints.top !== undefined)
+                                targetY = Math.min(targetY, constraints.top);
+                        }
+                    }
+                    lastFrameTimeRef.current = performance.now();
+                    springStateRef.current = {
+                        active: true,
+                        targetX,
+                        targetY,
+                        targetZ,
+                        velX: hasX ? vel.x : 0,
+                        velY: hasY ? vel.y : 0,
+                        velZ: hasZ ? vel.z : 0,
+                        hasX,
+                        hasY,
+                        hasZ,
+                        stiffness: userStiffness !== null && userStiffness !== void 0 ? userStiffness : 200,
+                        damping: userDamping !== null && userDamping !== void 0 ? userDamping : 50,
+                    };
+                }
+            }
+            (_b = cur.onDragEnd) === null || _b === void 0 ? void 0 : _b.call(cur, event, {
+                point: { x: event.clientX, y: event.clientY },
+                offset,
+                delta: {
+                    x: lastDeltaRef.current.x,
+                    y: lastDeltaRef.current.y,
+                    z: lastDeltaRef.current.z,
+                },
+                velocity: { x: vel.x, y: vel.y, z: vel.z },
+            });
+        };
+        window.addEventListener("pointermove", handlePointerMove);
+        window.addEventListener("pointerup", handlePointerUp);
+        return () => {
+            window.removeEventListener("pointermove", handlePointerMove);
+            window.removeEventListener("pointerup", handlePointerUp);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [gl, instanceRef, animateToTarget, buildTargetFromState]);
+    const isDragEnabled = drag !== undefined && drag !== false;
+    if (!isDragEnabled)
+        return {};
+    return { onPointerDown: handlePointerDown };
+}
+
 function createAnimationState() {
     return {
         hasStarted: false,
@@ -447,6 +857,7 @@ function custom(Component) {
                 "attenuationColor",
             ]);
             Object.entries(targetValues).forEach(([key, value]) => {
+                var _a;
                 const opts = getPropertyOpts(key);
                 const mapping = transformMap[key];
                 if (mapping === null || mapping === void 0 ? void 0 : mapping.target) {
@@ -460,6 +871,14 @@ function custom(Component) {
                 else if (colorKeys.has(key) && instance[key]) {
                     animateColor(instance[key], value, opts, key);
                 }
+                else if (instance.uniforms &&
+                    instance.uniforms[key] &&
+                    typeof ((_a = instance.uniforms[key]) === null || _a === void 0 ? void 0 : _a.value) === "number") {
+                    // Animate ShaderMaterial uniforms (uniforms[key].value)
+                    // Note: consumers must useMemo their uniforms prop to prevent
+                    // R3F from overwriting animated values on re-render
+                    createAnimation(instance.uniforms[key], { value: value }, opts, key);
+                }
                 else if (key in instance && typeof instance[key] === "number") {
                     createAnimation(instance, { [key]: value }, opts, key);
                 }
@@ -517,14 +936,20 @@ function custom(Component) {
             return () => { var _a; return (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop(); };
             // eslint-disable-next-line react-hooks/exhaustive-deps
         }, [presenceContext === null || presenceContext === void 0 ? void 0 : presenceContext.isPresent]);
+        const stopAnimation = react.useCallback(() => {
+            var _a;
+            (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+        }, []);
         const gestureProps = {
+            instanceRef,
             captureInstanceState,
             buildTargetFromState,
             animateToTarget,
             resolveVariant,
             transition,
+            stopAnimation,
         };
-        const gestureHandlers = Object.assign(Object.assign({}, useHover(false, props, gestureProps)), useTap(false, props, gestureProps));
+        const gestureHandlers = Object.assign(Object.assign(Object.assign({}, useHover(false, props, gestureProps)), useTap(false, props, gestureProps)), useDrag(false, props, gestureProps));
         const resolvedInitialValues = typeof initial === "string" ? resolveVariant(initial) : initial;
         const element = useRender(Component, Object.assign(Object.assign(Object.assign({}, restProps), gestureHandlers), { children }), ref, instanceRef, resolvedInitialValues);
         const getNextChildIndex = react.useCallback(() => {
@@ -565,11 +990,11 @@ const MotionCamera = (props) => {
         const aspect = size.width / size.height;
         let cam;
         if (type === "perspective") {
-            cam = new three.PerspectiveCamera(fov, aspect, near, far);
+            cam = new THREE.PerspectiveCamera(fov, aspect, near, far);
         }
         else {
             const frustumSize = 10;
-            cam = new three.OrthographicCamera((-frustumSize * aspect) / 2, (frustumSize * aspect) / 2, frustumSize / 2, -frustumSize / 2, near, far);
+            cam = new THREE.OrthographicCamera((-frustumSize * aspect) / 2, (frustumSize * aspect) / 2, frustumSize / 2, -frustumSize / 2, near, far);
         }
         cam.updateProjectionMatrix();
         return cam;
@@ -694,7 +1119,146 @@ function AnimatePresence({ children, mode = "sync", onExitComplete, custom, }) {
     });
 }
 
+const DEFAULT_SPRING = {
+    type: 'spring',
+    stiffness: 600,
+    damping: 100,
+    restDelta: 0.001,
+};
+// Seconds of velocity to project past the release point when snapping —
+// higher value = a flick advances further.
+const VELOCITY_PROJECTION = 0.2;
+// Fraction of slideWidth the user must cross, or minimum velocity (world
+// units/sec) required, to commit to the next slide. Below both thresholds
+// the carousel snaps back to the slot the drag started on.
+const DRAG_THRESHOLD_RATIO = 0.25;
+const FLICK_VELOCITY = 1.0;
+const mod = (n, m) => ((n % m) + m) % m;
+const CarouselSlot = react.memo(({ hadDragRef, item, itemWidth, slotRef }) => {
+    const contentRef = react.useRef(null);
+    const coverRef = react.useRef(null);
+    react.useLayoutEffect(() => {
+        const content = contentRef.current;
+        const cover = coverRef.current;
+        if (!content || !cover)
+            return;
+        const box = new THREE.Box3().setFromObject(content);
+        if (box.isEmpty())
+            return;
+        const h = box.max.y - box.min.y;
+        cover.geometry.dispose();
+        cover.geometry = new THREE.PlaneGeometry(itemWidth, h);
+        cover.position.z = box.max.z + 0.001;
+    }, [item, itemWidth]);
+    // Dispose the generated geometry on unmount — useLayoutEffect's replacement
+    // logic only disposes the *previous* geometry, not the final one.
+    react.useEffect(() => () => { var _a; (_a = coverRef.current) === null || _a === void 0 ? void 0 : _a.geometry.dispose(); }, []);
+    return (jsxRuntime.jsxs("group", { ref: slotRef, children: [jsxRuntime.jsx("group", { ref: contentRef, children: item }), jsxRuntime.jsxs("mesh", { ref: coverRef, onClick: (e) => {
+                    if (hadDragRef.current) {
+                        e.stopPropagation();
+                        hadDragRef.current = false;
+                    }
+                }, children: [jsxRuntime.jsx("planeGeometry", { args: [itemWidth, itemWidth] }), jsxRuntime.jsx("meshBasicMaterial", { transparent: true, opacity: 0, depthWrite: false })] })] }));
+});
+const Carousel = ({ items, itemWidth = 1.5, gap = 0.5, defaultValue = 0, transition = DEFAULT_SPRING, onSwitch, onDragStart, onDrag, onDragEnd, renderThreshold = 1, dragThreshold = DRAG_THRESHOLD_RATIO, flickVelocity = FLICK_VELOCITY, }) => {
+    const slideWidth = itemWidth + gap;
+    const count = items.length;
+    // Render twice the items and center on the first item of the second copy.
+    // The first copy lives to the left, so wrap-points sit at ±N*slideWidth
+    // from camera center — well off-screen — instead of ±N*slideWidth/2
+    // where they'd pop in and out at the visible edges.
+    const loopedItems = react.useMemo(() => [...items, ...items], [items]);
+    const slotCount = loopedItems.length;
+    const period = slotCount * slideWidth;
+    const startSlot = count + defaultValue;
+    const groupRef = react.useRef(null);
+    const itemRefs = react.useRef([]);
+    // Single source of truth: a fractional slot index that grows up/down
+    // infinitely as the user navigates. group.position.x = -currIndex * slideWidth
+    // at rest. Snap animations animate currIndex toward integer targets;
+    // useFrame applies it to the group every frame (when not dragging).
+    const currIndex = react$1.useMotionValue(startSlot);
+    const isDraggingRef = react.useRef(false);
+    const hadDragRef = react.useRef(false);
+    const dragStartIndexRef = react.useRef(startSlot);
+    const snapAnimRef = react.useRef(null);
+    const initial = react.useMemo(() => ({ x: -startSlot * slideWidth }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    const goTo = react.useCallback((slot) => {
+        var _a;
+        onSwitch === null || onSwitch === void 0 ? void 0 : onSwitch(mod(slot, count));
+        (_a = snapAnimRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+        snapAnimRef.current = react$1.animate(currIndex, slot, transition);
+    }, [count, transition, onSwitch, currIndex]);
+    react.useEffect(() => () => { var _a; return (_a = snapAnimRef.current) === null || _a === void 0 ? void 0 : _a.stop(); }, []);
+    // Drag start: stop any in-flight snap and capture the slot we started on
+    // so an under-threshold release can elastic back to it.
+    const handleDragStart = react.useCallback(() => {
+        var _a;
+        isDraggingRef.current = true;
+        hadDragRef.current = false;
+        dragStartIndexRef.current = Math.round(currIndex.get());
+        (_a = snapAnimRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+        snapAnimRef.current = null;
+        onDragStart === null || onDragStart === void 0 ? void 0 : onDragStart();
+    }, [currIndex, onDragStart]);
+    const handleDragEnd = react.useCallback((_, info) => {
+        isDraggingRef.current = false;
+        const group = groupRef.current;
+        if (!group)
+            return;
+        // Resync the motion value to where use-drag actually locked the position
+        // — the next useFrame will use this same value, so there's no visible
+        // jump between the dragged position and the start of the snap tween.
+        const releasedX = group.position.x;
+        const releasedIndex = -releasedX / slideWidth;
+        currIndex.jump(releasedIndex);
+        const startIndex = dragStartIndexRef.current;
+        const offsetIndex = releasedIndex - startIndex;
+        const overThreshold = Math.abs(offsetIndex) > dragThreshold;
+        const overVelocity = Math.abs(info.velocity.x) > flickVelocity;
+        if (!overThreshold && !overVelocity) {
+            goTo(startIndex);
+            return;
+        }
+        hadDragRef.current = true;
+        const projectedX = releasedX + info.velocity.x * VELOCITY_PROJECTION;
+        const targetSlot = Math.round(-projectedX / slideWidth);
+        goTo(targetSlot);
+        onDragEnd === null || onDragEnd === void 0 ? void 0 : onDragEnd(info);
+    }, [slideWidth, goTo, currIndex, dragThreshold, flickVelocity, onDragEnd]);
+    // Drive position from currIndex unless the user is dragging — during drag
+    // use-drag writes to group.position.x directly (and dragMomentum=false
+    // ensures it stops writing the moment the pointer lifts, so there's no
+    // race with the snap animation).
+    fiber.useFrame(() => {
+        const group = groupRef.current;
+        if (!group)
+            return;
+        if (!isDraggingRef.current) {
+            group.position.x = -currIndex.get() * slideWidth;
+        }
+        const groupX = group.position.x;
+        for (let i = 0; i < slotCount; i++) {
+            const ref = itemRefs.current[i];
+            if (!ref)
+                continue;
+            const k = Math.round((-groupX - i * slideWidth) / period);
+            ref.position.x = i * slideWidth + k * period;
+            // +0.5 margin so the leading-edge slot fades in the moment the trailing
+            // one fades out — keeps the loop seamless mid-drag instead of waiting
+            // for snap to settle on an integer slot.
+            const slotDist = (groupX + ref.position.x) / slideWidth;
+            ref.visible = Math.abs(slotDist) <= renderThreshold + 0.5;
+        }
+    });
+    return (jsxRuntime.jsx(motion.group, { ref: groupRef, drag: "x", dragMomentum: false, initial: initial, onDragStart: handleDragStart, onDragEnd: handleDragEnd, onDrag: (_e, info) => onDrag === null || onDrag === void 0 ? void 0 : onDrag(info), children: loopedItems.map((item, i) => (jsxRuntime.jsx(CarouselSlot, { item: item, itemWidth: itemWidth, slotRef: (el) => { itemRefs.current[i] = el; }, hadDragRef: hadDragRef }, `carouselItem-${i}`))) }));
+};
+var index = react.memo(Carousel);
+
 exports.AnimatePresence = AnimatePresence;
+exports.Carousel = index;
 exports.MotionCamera = MotionCamera;
 exports.motion = motion;
 exports.usePresence = usePresence;

package/dist/es/components/Carousel/index.mjs

@@ -0,0 +1,147 @@
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { memo, useMemo, useRef, useCallback, useEffect, useLayoutEffect } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { Box3, PlaneGeometry } from 'three';
+import { useMotionValue, animate } from 'motion/react';
+import { motion } from '../../render/motion.mjs';
+
+const DEFAULT_SPRING = {
+    type: 'spring',
+    stiffness: 600,
+    damping: 100,
+    restDelta: 0.001,
+};
+// Seconds of velocity to project past the release point when snapping —
+// higher value = a flick advances further.
+const VELOCITY_PROJECTION = 0.2;
+// Fraction of slideWidth the user must cross, or minimum velocity (world
+// units/sec) required, to commit to the next slide. Below both thresholds
+// the carousel snaps back to the slot the drag started on.
+const DRAG_THRESHOLD_RATIO = 0.25;
+const FLICK_VELOCITY = 1.0;
+const mod = (n, m) => ((n % m) + m) % m;
+const CarouselSlot = memo(({ hadDragRef, item, itemWidth, slotRef }) => {
+    const contentRef = useRef(null);
+    const coverRef = useRef(null);
+    useLayoutEffect(() => {
+        const content = contentRef.current;
+        const cover = coverRef.current;
+        if (!content || !cover)
+            return;
+        const box = new Box3().setFromObject(content);
+        if (box.isEmpty())
+            return;
+        const h = box.max.y - box.min.y;
+        cover.geometry.dispose();
+        cover.geometry = new PlaneGeometry(itemWidth, h);
+        cover.position.z = box.max.z + 0.001;
+    }, [item, itemWidth]);
+    // Dispose the generated geometry on unmount — useLayoutEffect's replacement
+    // logic only disposes the *previous* geometry, not the final one.
+    useEffect(() => () => { var _a; (_a = coverRef.current) === null || _a === void 0 ? void 0 : _a.geometry.dispose(); }, []);
+    return (jsxs("group", { ref: slotRef, children: [jsx("group", { ref: contentRef, children: item }), jsxs("mesh", { ref: coverRef, onClick: (e) => {
+                    if (hadDragRef.current) {
+                        e.stopPropagation();
+                        hadDragRef.current = false;
+                    }
+                }, children: [jsx("planeGeometry", { args: [itemWidth, itemWidth] }), jsx("meshBasicMaterial", { transparent: true, opacity: 0, depthWrite: false })] })] }));
+});
+const Carousel = ({ items, itemWidth = 1.5, gap = 0.5, defaultValue = 0, transition = DEFAULT_SPRING, onSwitch, onDragStart, onDrag, onDragEnd, renderThreshold = 1, dragThreshold = DRAG_THRESHOLD_RATIO, flickVelocity = FLICK_VELOCITY, }) => {
+    const slideWidth = itemWidth + gap;
+    const count = items.length;
+    // Render twice the items and center on the first item of the second copy.
+    // The first copy lives to the left, so wrap-points sit at ±N*slideWidth
+    // from camera center — well off-screen — instead of ±N*slideWidth/2
+    // where they'd pop in and out at the visible edges.
+    const loopedItems = useMemo(() => [...items, ...items], [items]);
+    const slotCount = loopedItems.length;
+    const period = slotCount * slideWidth;
+    const startSlot = count + defaultValue;
+    const groupRef = useRef(null);
+    const itemRefs = useRef([]);
+    // Single source of truth: a fractional slot index that grows up/down
+    // infinitely as the user navigates. group.position.x = -currIndex * slideWidth
+    // at rest. Snap animations animate currIndex toward integer targets;
+    // useFrame applies it to the group every frame (when not dragging).
+    const currIndex = useMotionValue(startSlot);
+    const isDraggingRef = useRef(false);
+    const hadDragRef = useRef(false);
+    const dragStartIndexRef = useRef(startSlot);
+    const snapAnimRef = useRef(null);
+    const initial = useMemo(() => ({ x: -startSlot * slideWidth }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    const goTo = useCallback((slot) => {
+        var _a;
+        onSwitch === null || onSwitch === void 0 ? void 0 : onSwitch(mod(slot, count));
+        (_a = snapAnimRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+        snapAnimRef.current = animate(currIndex, slot, transition);
+    }, [count, transition, onSwitch, currIndex]);
+    useEffect(() => () => { var _a; return (_a = snapAnimRef.current) === null || _a === void 0 ? void 0 : _a.stop(); }, []);
+    // Drag start: stop any in-flight snap and capture the slot we started on
+    // so an under-threshold release can elastic back to it.
+    const handleDragStart = useCallback(() => {
+        var _a;
+        isDraggingRef.current = true;
+        hadDragRef.current = false;
+        dragStartIndexRef.current = Math.round(currIndex.get());
+        (_a = snapAnimRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+        snapAnimRef.current = null;
+        onDragStart === null || onDragStart === void 0 ? void 0 : onDragStart();
+    }, [currIndex, onDragStart]);
+    const handleDragEnd = useCallback((_, info) => {
+        isDraggingRef.current = false;
+        const group = groupRef.current;
+        if (!group)
+            return;
+        // Resync the motion value to where use-drag actually locked the position
+        // — the next useFrame will use this same value, so there's no visible
+        // jump between the dragged position and the start of the snap tween.
+        const releasedX = group.position.x;
+        const releasedIndex = -releasedX / slideWidth;
+        currIndex.jump(releasedIndex);
+        const startIndex = dragStartIndexRef.current;
+        const offsetIndex = releasedIndex - startIndex;
+        const overThreshold = Math.abs(offsetIndex) > dragThreshold;
+        const overVelocity = Math.abs(info.velocity.x) > flickVelocity;
+        if (!overThreshold && !overVelocity) {
+            goTo(startIndex);
+            return;
+        }
+        hadDragRef.current = true;
+        const projectedX = releasedX + info.velocity.x * VELOCITY_PROJECTION;
+        const targetSlot = Math.round(-projectedX / slideWidth);
+        goTo(targetSlot);
+        onDragEnd === null || onDragEnd === void 0 ? void 0 : onDragEnd(info);
+    }, [slideWidth, goTo, currIndex, dragThreshold, flickVelocity, onDragEnd]);
+    // Drive position from currIndex unless the user is dragging — during drag
+    // use-drag writes to group.position.x directly (and dragMomentum=false
+    // ensures it stops writing the moment the pointer lifts, so there's no
+    // race with the snap animation).
+    useFrame(() => {
+        const group = groupRef.current;
+        if (!group)
+            return;
+        if (!isDraggingRef.current) {
+            group.position.x = -currIndex.get() * slideWidth;
+        }
+        const groupX = group.position.x;
+        for (let i = 0; i < slotCount; i++) {
+            const ref = itemRefs.current[i];
+            if (!ref)
+                continue;
+            const k = Math.round((-groupX - i * slideWidth) / period);
+            ref.position.x = i * slideWidth + k * period;
+            // +0.5 margin so the leading-edge slot fades in the moment the trailing
+            // one fades out — keeps the loop seamless mid-drag instead of waiting
+            // for snap to settle on an integer slot.
+            const slotDist = (groupX + ref.position.x) / slideWidth;
+            ref.visible = Math.abs(slotDist) <= renderThreshold + 0.5;
+        }
+    });
+    return (jsx(motion.group, { ref: groupRef, drag: "x", dragMomentum: false, initial: initial, onDragStart: handleDragStart, onDragEnd: handleDragEnd, onDrag: (_e, info) => onDrag === null || onDrag === void 0 ? void 0 : onDrag(info), children: loopedItems.map((item, i) => (jsx(CarouselSlot, { item: item, itemWidth: itemWidth, slotRef: (el) => { itemRefs.current[i] = el; }, hadDragRef: hadDragRef }, `carouselItem-${i}`))) }));
+};
+var index = memo(Carousel);
+
+export { index as default };

package/dist/es/index.mjs

@@ -3,3 +3,4 @@ export { motion } from './render/motion.mjs';
 export { default as MotionCamera } from './components/MotionCamera.mjs';
 export { AnimatePresence } from './components/AnimatePresence/index.mjs';
 export { usePresence } from './components/AnimatePresence/PresenceContext.mjs';
+export { default as Carousel } from './components/Carousel/index.mjs';

package/dist/es/render/gestures/use-drag.mjs

@@ -0,0 +1,389 @@
+"use client";
+import { useRef, useCallback, useEffect } from 'react';
+import { useThree, useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+
+// World-space units per CSS pixel at the given depth from the camera.
+const getWorldPerPixel = (camera, depth, viewportHeight) => {
+    var _a;
+    const ortho = camera;
+    if (ortho.isOrthographicCamera) {
+        return ((ortho.top - ortho.bottom) / (viewportHeight * (ortho.zoom || 1)));
+    }
+    const persp = camera;
+    const fov = ((_a = persp.fov) !== null && _a !== void 0 ? _a : 60) * (Math.PI / 180);
+    return (2 * Math.tan(fov / 2) * depth) / viewportHeight;
+};
+const clampWithElastic = (value, min, max, elastic) => {
+    if (min !== undefined && value < min)
+        return min + (value - min) * elastic;
+    if (max !== undefined && value > max)
+        return max + (value - max) * elastic;
+    return value;
+};
+function useDrag(isStatic, props, options) {
+    const { camera, gl } = useThree();
+    const { drag, whileDrag, onDragStart, onPointerDown, transition } = props;
+    const { instanceRef, captureInstanceState, buildTargetFromState, animateToTarget, resolveVariant, stopAnimation, } = options;
+    const isDraggingRef = useRef(false);
+    const dragStartPointerRef = useRef({ x: 0, y: 0 });
+    const dragStartPosRef = useRef(new THREE.Vector3());
+    const cameraRightRef = useRef(new THREE.Vector3());
+    const cameraUpRef = useRef(new THREE.Vector3());
+    const worldPerPixelRef = useRef(0);
+    const targetPosRef = useRef(new THREE.Vector3());
+    const lastPosRef = useRef(new THREE.Vector3());
+    const velocityRef = useRef(new THREE.Vector3());
+    const lastDeltaRef = useRef(new THREE.Vector3());
+    const lastTimeRef = useRef(0);
+    const preDragStateRef = useRef(null);
+    const pointerIdRef = useRef(null);
+    const springStateRef = useRef(null);
+    const lastFrameTimeRef = useRef(0);
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    useFrame(() => {
+        var _a;
+        const instance = instanceRef.current;
+        if (!instance)
+            return;
+        const obj = instance;
+        // Phase 1: dragging — apply the drag target
+        if (isDraggingRef.current) {
+            const t = targetPosRef.current;
+            obj.position.set(t.x, t.y, t.z);
+            return;
+        }
+        // Phase 2: spring (momentum / snap-to-origin)
+        const s = springStateRef.current;
+        if (!s || !s.active)
+            return;
+        const now = performance.now();
+        let dt = (now - lastFrameTimeRef.current) / 1000;
+        if (dt > 0.05)
+            dt = 0.05;
+        if (dt <= 0)
+            dt = 1 / 60;
+        lastFrameTimeRef.current = now;
+        // Sub-step the integrator for stability with stiff springs
+        const subSteps = 4;
+        const subDt = dt / subSteps;
+        for (let i = 0; i < subSteps; i++) {
+            if (s.hasX) {
+                const force = -s.stiffness * (obj.position.x - s.targetX) - s.damping * s.velX;
+                s.velX += force * subDt;
+                obj.position.x += s.velX * subDt;
+            }
+            if (s.hasY) {
+                const force = -s.stiffness * (obj.position.y - s.targetY) - s.damping * s.velY;
+                s.velY += force * subDt;
+                obj.position.y += s.velY * subDt;
+            }
+            if (s.hasZ) {
+                const force = -s.stiffness * (obj.position.z - s.targetZ) - s.damping * s.velZ;
+                s.velZ += force * subDt;
+                obj.position.z += s.velZ * subDt;
+            }
+        }
+        // Rest detection — stop when both speed and offset are tiny
+        const speedSq = s.velX * s.velX + s.velY * s.velY + s.velZ * s.velZ;
+        const offX = s.hasX ? obj.position.x - s.targetX : 0;
+        const offY = s.hasY ? obj.position.y - s.targetY : 0;
+        const offZ = s.hasZ ? obj.position.z - s.targetZ : 0;
+        const offsetSq = offX * offX + offY * offY + offZ * offZ;
+        if (speedSq < 0.0005 && offsetSq < 0.0005) {
+            if (s.hasX)
+                obj.position.x = s.targetX;
+            if (s.hasY)
+                obj.position.y = s.targetY;
+            if (s.hasZ)
+                obj.position.z = s.targetZ;
+            s.active = false;
+            (_a = s.onComplete) === null || _a === void 0 ? void 0 : _a.call(s);
+        }
+    });
+    const handlePointerDown = useCallback((event) => {
+        const instance = instanceRef.current;
+        if (!instance)
+            return;
+        event.stopPropagation();
+        // Halt any in-flight motion-library animation (e.g. main `animate` prop
+        // tween that's still running) and any active drag spring.
+        stopAnimation();
+        if (springStateRef.current)
+            springStateRef.current.active = false;
+        if (whileDrag) {
+            preDragStateRef.current = captureInstanceState();
+            const targetValues = typeof whileDrag === "string"
+                ? resolveVariant(whileDrag)
+                : whileDrag;
+            animateToTarget(targetValues, transition || { duration: 0.1 });
+        }
+        const obj = instance;
+        // Capture initial pointer + position. All subsequent moves are computed
+        // as `initialPos + pixelDelta * worldPerPixel` — never re-derived from
+        // the live (potentially-mid-animation) instance position.
+        dragStartPointerRef.current.x = event.nativeEvent.clientX;
+        dragStartPointerRef.current.y = event.nativeEvent.clientY;
+        dragStartPosRef.current.set(obj.position.x, obj.position.y, obj.position.z);
+        targetPosRef.current.copy(dragStartPosRef.current);
+        lastPosRef.current.copy(dragStartPosRef.current);
+        lastDeltaRef.current.set(0, 0, 0);
+        velocityRef.current.set(0, 0, 0);
+        lastTimeRef.current = performance.now();
+        // Compute world-units-per-pixel at the object's perpendicular depth
+        // (distance from camera along its forward axis).
+        const cameraForward = new THREE.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
+        const cameraToObj = new THREE.Vector3().subVectors(dragStartPosRef.current, camera.position);
+        const depth = Math.abs(cameraToObj.dot(cameraForward));
+        const rect = gl.domElement.getBoundingClientRect();
+        worldPerPixelRef.current = getWorldPerPixel(camera, depth, rect.height);
+        // Cache camera basis vectors so screen X/Y maps correctly to world
+        // X/Y/Z even if the camera is tilted.
+        cameraRightRef.current.set(1, 0, 0).applyQuaternion(camera.quaternion);
+        cameraUpRef.current.set(0, 1, 0).applyQuaternion(camera.quaternion);
+        isDraggingRef.current = true;
+        pointerIdRef.current = event.nativeEvent.pointerId;
+        try {
+            gl.domElement.setPointerCapture(event.nativeEvent.pointerId);
+        }
+        catch (_a) {
+            // not all environments support setPointerCapture
+        }
+        onDragStart === null || onDragStart === void 0 ? void 0 : onDragStart(event.nativeEvent, {
+            point: { x: event.nativeEvent.clientX, y: event.nativeEvent.clientY },
+            offset: { x: 0, y: 0, z: 0 },
+            delta: { x: 0, y: 0, z: 0 },
+            velocity: { x: 0, y: 0, z: 0 },
+        });
+        onPointerDown === null || onPointerDown === void 0 ? void 0 : onPointerDown(event);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        whileDrag,
+        onDragStart,
+        onPointerDown,
+        camera,
+        gl,
+        captureInstanceState,
+        resolveVariant,
+        animateToTarget,
+        stopAnimation,
+        transition,
+        instanceRef,
+    ]);
+    useEffect(() => {
+        const handlePointerMove = (event) => {
+            var _a;
+            if (!isDraggingRef.current || event.pointerId !== pointerIdRef.current)
+                return;
+            const instance = instanceRef.current;
+            if (!instance)
+                return;
+            const cur = propsRef.current;
+            const dragAxis = cur.drag;
+            const elasticVal = typeof cur.dragElastic === "number"
+                ? cur.dragElastic
+                : cur.dragElastic === false
+                    ? 0
+                    : 0.5;
+            const constraints = cur.dragConstraints;
+            const pixelDx = event.clientX - dragStartPointerRef.current.x;
+            const pixelDy = event.clientY - dragStartPointerRef.current.y;
+            const scale = worldPerPixelRef.current;
+            let newX = dragStartPosRef.current.x;
+            let newY = dragStartPosRef.current.y;
+            let newZ = dragStartPosRef.current.z;
+            if (dragAxis === "z") {
+                // Vertical screen movement → Z. Cursor down (pixelDy > 0) = closer.
+                newZ = dragStartPosRef.current.z + pixelDy * scale;
+            }
+            else {
+                // Map screen XY to camera-relative world delta.
+                const r = cameraRightRef.current;
+                const u = cameraUpRef.current;
+                const worldDx = r.x * pixelDx * scale + u.x * -pixelDy * scale;
+                const worldDy = r.y * pixelDx * scale + u.y * -pixelDy * scale;
+                const worldDz = r.z * pixelDx * scale + u.z * -pixelDy * scale;
+                if (dragAxis === "x") {
+                    newX = dragStartPosRef.current.x + worldDx;
+                }
+                else if (dragAxis === "y") {
+                    newY = dragStartPosRef.current.y + worldDy;
+                }
+                else {
+                    newX = dragStartPosRef.current.x + worldDx;
+                    newY = dragStartPosRef.current.y + worldDy;
+                    newZ = dragStartPosRef.current.z + worldDz;
+                }
+            }
+            // Constraints with elastic rubber-banding
+            if (constraints) {
+                if (dragAxis !== "y" && dragAxis !== "z") {
+                    newX = clampWithElastic(newX, constraints.left, constraints.right, elasticVal);
+                }
+                if (dragAxis !== "x" && dragAxis !== "z") {
+                    newY = clampWithElastic(newY, constraints.bottom, constraints.top, elasticVal);
+                }
+            }
+            // Velocity tracking (used for momentum on release)
+            const now = performance.now();
+            const dt = (now - lastTimeRef.current) / 1000;
+            if (dt > 0) {
+                const dx = newX - lastPosRef.current.x;
+                const dy = newY - lastPosRef.current.y;
+                const dz = newZ - lastPosRef.current.z;
+                velocityRef.current.set(dx / dt, dy / dt, dz / dt);
+                lastDeltaRef.current.set(dx, dy, dz);
+            }
+            lastTimeRef.current = now;
+            lastPosRef.current.set(newX, newY, newZ);
+            // Stash target — useFrame applies it next R3F frame.
+            targetPosRef.current.set(newX, newY, newZ);
+            const offset = {
+                x: newX - dragStartPosRef.current.x,
+                y: newY - dragStartPosRef.current.y,
+                z: newZ - dragStartPosRef.current.z,
+            };
+            (_a = cur.onDrag) === null || _a === void 0 ? void 0 : _a.call(cur, event, {
+                point: { x: event.clientX, y: event.clientY },
+                offset,
+                delta: {
+                    x: lastDeltaRef.current.x,
+                    y: lastDeltaRef.current.y,
+                    z: lastDeltaRef.current.z,
+                },
+                velocity: {
+                    x: velocityRef.current.x,
+                    y: velocityRef.current.y,
+                    z: velocityRef.current.z,
+                },
+            });
+        };
+        const handlePointerUp = (event) => {
+            var _a, _b;
+            if (!isDraggingRef.current || event.pointerId !== pointerIdRef.current)
+                return;
+            isDraggingRef.current = false;
+            pointerIdRef.current = null;
+            const instance = instanceRef.current;
+            const cur = propsRef.current;
+            // Lock in the final dragged position synchronously. Once useFrame stops
+            // applying the drag target, a still-pending write from the *previous*
+            // momentum animation can land before the new animateToTarget() call
+            // reads instance.position to use as its "from" value — which causes the
+            // new animation to start from the old momentum's path instead of where
+            // the user actually released.
+            if (instance) {
+                const obj = instance;
+                const t = targetPosRef.current;
+                obj.position.set(t.x, t.y, t.z);
+            }
+            // Restore whileDrag visual state
+            if (cur.whileDrag && preDragStateRef.current) {
+                const targetValues = buildTargetFromState(preDragStateRef.current);
+                animateToTarget(targetValues, options.transition || { duration: 0.2 });
+                const dur = ((_a = options.transition) === null || _a === void 0 ? void 0 : _a.duration) || 0.2;
+                setTimeout(() => {
+                    preDragStateRef.current = null;
+                }, dur * 1000);
+            }
+            if (!instance)
+                return;
+            const finalPos = targetPosRef.current;
+            const offset = {
+                x: finalPos.x - dragStartPosRef.current.x,
+                y: finalPos.y - dragStartPosRef.current.y,
+                z: finalPos.z - dragStartPosRef.current.z,
+            };
+            const vel = velocityRef.current;
+            // Read spring tuning from dragTransition (if user provided one).
+            const dt = cur.dragTransition;
+            const userStiffness = typeof (dt === null || dt === void 0 ? void 0 : dt.stiffness) === "number" ? dt.stiffness : undefined;
+            const userDamping = typeof (dt === null || dt === void 0 ? void 0 : dt.damping) === "number" ? dt.damping : undefined;
+            if (cur.dragSnapToOrigin) {
+                lastFrameTimeRef.current = performance.now();
+                springStateRef.current = {
+                    active: true,
+                    targetX: dragStartPosRef.current.x,
+                    targetY: dragStartPosRef.current.y,
+                    targetZ: dragStartPosRef.current.z,
+                    velX: vel.x,
+                    velY: vel.y,
+                    velZ: vel.z,
+                    hasX: true,
+                    hasY: true,
+                    hasZ: true,
+                    stiffness: userStiffness !== null && userStiffness !== void 0 ? userStiffness : 400,
+                    damping: userDamping !== null && userDamping !== void 0 ? userDamping : 40,
+                };
+            }
+            else if (cur.dragMomentum !== false) {
+                const speed = Math.sqrt(Math.pow(vel.x, 2) + Math.pow(vel.y, 2) + Math.pow(vel.z, 2));
+                if (speed > 0.5) {
+                    const coeff = 0.25;
+                    const dragAxis = cur.drag;
+                    const hasX = dragAxis !== "y" && dragAxis !== "z";
+                    const hasY = dragAxis !== "x" && dragAxis !== "z";
+                    const hasZ = dragAxis === "z";
+                    let targetX = hasX ? finalPos.x + vel.x * coeff : finalPos.x;
+                    let targetY = hasY ? finalPos.y + vel.y * coeff : finalPos.y;
+                    const targetZ = hasZ ? finalPos.z + vel.z * coeff : finalPos.z;
+                    const constraints = cur.dragConstraints;
+                    if (constraints) {
+                        if (hasX) {
+                            if (constraints.left !== undefined)
+                                targetX = Math.max(targetX, constraints.left);
+                            if (constraints.right !== undefined)
+                                targetX = Math.min(targetX, constraints.right);
+                        }
+                        if (hasY) {
+                            if (constraints.bottom !== undefined)
+                                targetY = Math.max(targetY, constraints.bottom);
+                            if (constraints.top !== undefined)
+                                targetY = Math.min(targetY, constraints.top);
+                        }
+                    }
+                    lastFrameTimeRef.current = performance.now();
+                    springStateRef.current = {
+                        active: true,
+                        targetX,
+                        targetY,
+                        targetZ,
+                        velX: hasX ? vel.x : 0,
+                        velY: hasY ? vel.y : 0,
+                        velZ: hasZ ? vel.z : 0,
+                        hasX,
+                        hasY,
+                        hasZ,
+                        stiffness: userStiffness !== null && userStiffness !== void 0 ? userStiffness : 200,
+                        damping: userDamping !== null && userDamping !== void 0 ? userDamping : 50,
+                    };
+                }
+            }
+            (_b = cur.onDragEnd) === null || _b === void 0 ? void 0 : _b.call(cur, event, {
+                point: { x: event.clientX, y: event.clientY },
+                offset,
+                delta: {
+                    x: lastDeltaRef.current.x,
+                    y: lastDeltaRef.current.y,
+                    z: lastDeltaRef.current.z,
+                },
+                velocity: { x: vel.x, y: vel.y, z: vel.z },
+            });
+        };
+        window.addEventListener("pointermove", handlePointerMove);
+        window.addEventListener("pointerup", handlePointerUp);
+        return () => {
+            window.removeEventListener("pointermove", handlePointerMove);
+            window.removeEventListener("pointerup", handlePointerUp);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [gl, instanceRef, animateToTarget, buildTargetFromState]);
+    const isDragEnabled = drag !== undefined && drag !== false;
+    if (!isDragEnabled)
+        return {};
+    return { onPointerDown: handlePointerDown };
+}
+
+export { useDrag };

package/dist/es/render/motion.mjs

@@ -6,6 +6,7 @@ import { PresenceContext } from '../components/AnimatePresence/PresenceContext.m
 import { useRender } from './use-render.mjs';
 import { useHover } from './gestures/use-hover.mjs';
 import { useTap } from './gestures/use-tap.mjs';
+import { useDrag } from './gestures/use-drag.mjs';
 import { createAnimationState, createCallbackOptions, registerAnimation } from './events/index.mjs';
 
 const MotionContext = createContext(null);
@@ -166,6 +167,7 @@ function custom(Component) {
                 "attenuationColor",
             ]);
             Object.entries(targetValues).forEach(([key, value]) => {
+                var _a;
                 const opts = getPropertyOpts(key);
                 const mapping = transformMap[key];
                 if (mapping === null || mapping === void 0 ? void 0 : mapping.target) {
@@ -179,6 +181,14 @@ function custom(Component) {
                 else if (colorKeys.has(key) && instance[key]) {
                     animateColor(instance[key], value, opts, key);
                 }
+                else if (instance.uniforms &&
+                    instance.uniforms[key] &&
+                    typeof ((_a = instance.uniforms[key]) === null || _a === void 0 ? void 0 : _a.value) === "number") {
+                    // Animate ShaderMaterial uniforms (uniforms[key].value)
+                    // Note: consumers must useMemo their uniforms prop to prevent
+                    // R3F from overwriting animated values on re-render
+                    createAnimation(instance.uniforms[key], { value: value }, opts, key);
+                }
                 else if (key in instance && typeof instance[key] === "number") {
                     createAnimation(instance, { [key]: value }, opts, key);
                 }
@@ -236,14 +246,20 @@ function custom(Component) {
             return () => { var _a; return (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop(); };
             // eslint-disable-next-line react-hooks/exhaustive-deps
         }, [presenceContext === null || presenceContext === void 0 ? void 0 : presenceContext.isPresent]);
+        const stopAnimation = useCallback(() => {
+            var _a;
+            (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+        }, []);
         const gestureProps = {
+            instanceRef,
             captureInstanceState,
             buildTargetFromState,
             animateToTarget,
             resolveVariant,
             transition,
+            stopAnimation,
         };
-        const gestureHandlers = Object.assign(Object.assign({}, useHover(false, props, gestureProps)), useTap(false, props, gestureProps));
+        const gestureHandlers = Object.assign(Object.assign(Object.assign({}, useHover(false, props, gestureProps)), useTap(false, props, gestureProps)), useDrag(false, props, gestureProps));
         const resolvedInitialValues = typeof initial === "string" ? resolveVariant(initial) : initial;
         const element = useRender(Component, Object.assign(Object.assign(Object.assign({}, restProps), gestureHandlers), { children }), ref, instanceRef, resolvedInitialValues);
         const getNextChildIndex = useCallback(() => {

package/dist/es/render/use-render.mjs

@@ -7,6 +7,7 @@ const useRender = (Component, props, forwardedRef, instanceRef, initialValues) =
      * Create a callback ref that captures the Three.js instance
      */
     const callbackRef = useCallback((instance) => {
+        var _a;
         if (!instance)
             return;
         // Apply initial values immediately to prevent FOUC - but only once
@@ -45,6 +46,12 @@ const useRender = (Component, props, forwardedRef, instanceRef, initialValues) =
                         colorProp.set(initialValues[key]);
                     }
                 }
+                else if (instance.uniforms &&
+                    instance.uniforms[key] &&
+                    typeof ((_a = instance.uniforms[key]) === null || _a === void 0 ? void 0 : _a.value) === "number") {
+                    // Set ShaderMaterial uniform initial value
+                    instance.uniforms[key].value = initialValues[key];
+                }
                 else if (key in instance && typeof instance[key] === "number") {
                     instance[key] = initialValues[key];
                 }

package/dist/index.d.ts

@@ -2,12 +2,49 @@ import { Vector3, Euler, Color, ReactThreeFiber } from '@react-three/fiber';
 import * as THREE from 'three';
 import * as react from 'react';
 import { ForwardRefExoticComponent, PropsWithoutRef, RefAttributes, ReactNode } from 'react';
-import { MotionValue, MotionProps, ResolvedValues } from 'motion/react';
+import { MotionValue, MotionProps, Transition, ResolvedValues } from 'motion/react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type ThreeElement = InstanceType<typeof THREE.Object3D> & Record<string, unknown>;
-interface ThreeMotionProps extends Omit<MotionProps, "style" | "children" | "onUpdate" | "onAnimationStart" | "onAnimationComplete"> {
+interface DragInfo {
+    point: {
+        x: number;
+        y: number;
+    };
+    offset: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    delta: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface DragConstraints {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+interface ThreeMotionProps extends Omit<MotionProps, "style" | "children" | "onUpdate" | "onAnimationStart" | "onAnimationComplete" | "drag" | "dragConstraints" | "dragElastic" | "dragMomentum" | "dragSnapToOrigin" | "dragTransition" | "onDrag" | "onDragStart" | "onDragEnd" | "whileDrag" | "dragDirectionLock" | "dragPropagation" | "dragListener"> {
     [key: string]: unknown;
+    drag?: boolean | "x" | "y" | "z";
+    dragConstraints?: DragConstraints;
+    dragElastic?: number | boolean;
+    dragMomentum?: boolean;
+    dragSnapToOrigin?: boolean;
+    dragTransition?: Transition;
+    whileDrag?: Record<string, unknown> | string;
+    onDragStart?: (event: PointerEvent, info: DragInfo) => void;
+    onDrag?: (event: PointerEvent, info: DragInfo) => void;
+    onDragEnd?: (event: PointerEvent, info: DragInfo) => void;
     onInstanceUpdate?: ReactThreeFiber.ThreeElements["object3D"]["onUpdate"];
     onUpdate?: (values: Record<string, unknown>, animationVariant?: string) => void;
     onAnimationStart?: (values: Record<string, unknown>, animationVariant?: string) => void;
@@ -90,5 +127,22 @@ interface AnimatePresenceProps {
 }
 declare function AnimatePresence({ children, mode, onExitComplete, custom, }: AnimatePresenceProps): react.FunctionComponentElement<react.ProviderProps<PresenceContextValue | null>>[];
 
-export { AnimatePresence, MotionCamera, motion, usePresence };
-export type { AcceptMotionValues, ForwardRefComponent, ThreeElement, ThreeMotionComponents, ThreeMotionProps, ThreeRenderState };
+interface CarouselProps {
+    items: ReactNode[];
+    itemWidth?: number;
+    gap?: number;
+    defaultValue?: number;
+    transition?: Transition;
+    onSwitch?: (index: number) => void;
+    onDragStart?: () => void;
+    onDrag?: (info: DragInfo) => void;
+    onDragEnd?: (info: DragInfo) => void;
+    renderThreshold?: number;
+    dragThreshold?: number;
+    flickVelocity?: number;
+}
+declare const Carousel: ({ items, itemWidth, gap, defaultValue, transition, onSwitch, onDragStart, onDrag, onDragEnd, renderThreshold, dragThreshold, flickVelocity, }: CarouselProps) => react_jsx_runtime.JSX.Element;
+declare const _default: typeof Carousel;
+
+export { AnimatePresence, _default as Carousel, MotionCamera, motion, usePresence };
+export type { AcceptMotionValues, CarouselProps, DragConstraints, DragInfo, ForwardRefComponent, ThreeElement, ThreeMotionComponents, ThreeMotionProps, ThreeRenderState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "r3f-motion",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "A simple and powerful React animation library for @react-three/fiber leveraging motion.dev",
   "main": "dist/cjs/index.js",
   "module": "dist/es/index.mjs",