@rootnative/inertia-gestures 0.0.7 → 0.0.8

package/CHANGELOG.md

@@ -6,6 +6,18 @@ This package ships in lockstep with `@rootnative/inertia` — version numbers tr
 
 ## [Unreleased]
 
+## [0.0.8] - 2026-08-16
+
+### Added
+
+- **`useSwipe` snap-back is configurable: `releaseTransition`.** The reset to zero after a release was a hard-coded `withSpring(0)` — it could not join a design-token motion system, and it dropped the release velocity, so a flick that stopped short of the threshold reset as if the finger had been still. The option accepts a spring / timing / no-animation config inline, or a `TransitionName` registered on the nearest `<MotionConfig transitions={...}>`. The release velocity is passed into a spring automatically (unless the config sets `velocity` itself), on both the default spring and a configured one. Decay is excluded — the snap-back always targets zero and decay has no target; a name that resolves to a decay config dev-warns and falls back to the default spring.
+
+- **`useSwipe` commit exit: `onCommit` + `onSwipeEnd`.** The hook always sprang back to zero, which is right for swipe-to-delete and wrong for a card deck — a committed card must continue in the swipe direction and leave the screen, and consumers were rebuilding that with a parallel translation layer, an animation-end handler, and a safety timer. `onCommit` is a UI-thread worklet that fires when the gesture commits and returns per-axis release transitions (the same `ReleaseResult` shape as `useDrag`'s `onRelease`) to run **instead of** the snap-back; an omitted axis or a `void` return snaps back as usual. `onSwipeEnd(direction, { finished })` fires on the JS thread when the committed swipe's release animation settles — the commit exit if one ran, the snap-back otherwise — which is the "card is gone, advance the deck" moment `onSwipe` (fired at release) cannot give. It does not fire for a release that did not commit.
+
+- **`useSwipe` returns `reset()`.** Snaps both shared values back to zero with no animation, cancelling anything in flight. After a commit exit the values stay at the exit target; call `reset()` when the next card takes over the same mounted component. A keyed remount gets fresh values and doesn't need it.
+
+- New exported type: `SnapBackTransition` (the `releaseTransition` shapes). Requires `@rootnative/inertia` >=0.0.8 — the settle callback rides a new third parameter on core's `buildReleaseAnimation`.
+
 ## [0.0.7] - 2026-08-14
 
 **Lockstep version bump** alongside `@rootnative/inertia@0.0.7` (`Motion.FlatList`, a virtualized animated scroller, and `gesture={{ pressed }}` responding to a mouse on web). No runtime changes in this adapter; the `@rootnative/inertia` peer range moves to `>=0.0.7`.
@@ -55,7 +67,8 @@ Initial alpha publish alongside `@rootnative/inertia@0.0.0-alpha.0`. Optional ad
 - `useDrag({ onRelease })` — release worklet returns per-axis Inertia transitions (snap-to-tick spring, decay with bounds, etc.). Velocity stays on the UI thread; no JS round-trip.
 - `useSwipe`, `usePan` hooks composable with any `Motion.*` primitive via `<GestureDetector>`.
 
-[unreleased]: https://github.com/rootnative/inertia/compare/core+gestures+gradients+svg@0.0.7...HEAD
+[unreleased]: https://github.com/rootnative/inertia/compare/core+gestures+gradients+svg@0.0.8...HEAD
+[0.0.8]: https://github.com/rootnative/inertia/releases/tag/core+gestures+gradients+svg@0.0.8
 [0.0.7]: https://github.com/rootnative/inertia/releases/tag/core+gestures+gradients+svg@0.0.7
 [0.0.6]: https://github.com/rootnative/inertia/releases/tag/core+gestures+gradients+svg@0.0.6
 [0.0.5]: https://github.com/rootnative/inertia/releases/tag/core+gestures+gradients+svg@0.0.5

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { PanGesture } from 'react-native-gesture-handler';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { SpringTransition, TimingTransition, DecayTransition, NoAnimationTransition } from '@rootnative/inertia';
+import { SpringTransition, TimingTransition, DecayTransition, NoAnimationTransition, TransitionName } from '@rootnative/inertia';
 
 /**
  * Public types for `@rootnative/inertia-gestures`.
@@ -48,11 +48,22 @@ type ReleaseTransition = (SpringTransition & {
 /**
  * Per-axis release transitions returned by `onRelease`. Omit an axis to leave
  * its SV where it landed (no release animation on that axis).
+ *
+ * `useSwipe`'s `onCommit` returns the same shape with one difference in the
+ * omit semantics: an omitted axis snaps back to zero (the hook's resting
+ * state) rather than staying where it landed.
  */
 interface ReleaseResult {
     x?: ReleaseTransition;
     y?: ReleaseTransition;
 }
+/**
+ * Transition shapes `useSwipe` accepts for its snap-back (the
+ * `releaseTransition` option). The target is always zero, so decay — which
+ * has no target — is excluded; a registered name that resolves to a decay
+ * config dev-warns and falls back to the default spring.
+ */
+type SnapBackTransition = SpringTransition | TimingTransition | NoAnimationTransition;
 /**
  * Configuration for `useDrag`. All fields are optional; the defaults give an
  * unconstrained two-axis drag with no elasticity.
@@ -104,8 +115,14 @@ interface UseDragResult {
     /** Pan gesture to pass to a `<GestureDetector>`. */
     gesture: PanGesture;
     /**
-     * Animated style fragment (a single `transform` entry) to stack onto the
-     * dragged Motion primitive's `style` prop. Stable across renders.
+     * Animated style fragment for the dragged Motion primitive's `style` prop.
+     * Stable across renders.
+     *
+     * This owns the whole `transform` key. Do not stack a second transform style
+     * beside it — `transform` is one key in React Native, so the later style
+     * replaces this one instead of merging, and the drag silently stops
+     * following the finger. Nest another animated view, or build one style from
+     * `dragX` / `dragY` with `useInterpolatedStyle`, to add a transform.
      */
     animatedStyle: ReturnType<typeof useAnimatedStyle>;
     /** Current x translation in pixels. UI-thread shared value. */
@@ -155,6 +172,17 @@ interface SwipeOptions {
      * to `800`.
      */
     velocityThreshold?: number;
+    /**
+     * Transition for the snap-back to zero, given inline or as a registered
+     * `TransitionName` from the nearest `<MotionConfig transitions={...}>`.
+     * Defaults to the library default spring. The release velocity is passed
+     * into a spring automatically (unless the config sets `velocity` itself),
+     * so a flick that stops short of the threshold resets with the momentum it
+     * had. Decay is excluded — the snap-back always targets zero, and decay has
+     * no target; a name that resolves to a decay config dev-warns and falls
+     * back to the default spring.
+     */
+    releaseTransition?: SnapBackTransition | TransitionName;
     /**
      * Fired on the JS thread when the gesture commits in an allowed direction.
      */
@@ -162,14 +190,62 @@ interface SwipeOptions {
         distance: number;
         velocity: number;
     }) => void;
+    /**
+     * UI-thread callback fired when the gesture commits, before any release
+     * animation starts. Return per-axis release transitions to run **instead
+     * of** the snap-back — the commit-exit path a card deck needs, where the
+     * committed card continues in the swipe direction and leaves the screen:
+     *
+     * ```ts
+     * onCommit: (direction, info) => {
+     *   'worklet'
+     *   return {
+     *     x: {
+     *       type: 'spring',
+     *       to: direction === 'right' ? 500 : -500,
+     *       velocity: info.velocity.x,
+     *     },
+     *   }
+     * }
+     * ```
+     *
+     * An omitted axis (or a `void` return) snaps back to zero as usual. This
+     * callback runs as a worklet so the release velocity stays on the UI
+     * thread — author it with the `'worklet'` directive at the top of the body.
+     *
+     * Composes with `onSwipe`: both fire on commit. `onCommit` picks the
+     * release animation on the UI thread; `onSwipe` is for JS-thread side
+     * effects. Note the shared values stay at the exit target afterwards — call
+     * `reset()` when the next card takes over without a remount.
+     */
+    onCommit?: (direction: SwipeDirection, info: ReleaseInfo) => ReleaseResult | void;
+    /**
+     * Fired on the JS thread when a committed swipe's release animation
+     * settles — the commit exit from `onCommit` if one ran, the snap-back
+     * otherwise. This is the "card is gone, advance the deck" moment that
+     * `onSwipe` (which fires at release) cannot give you. `finished` is `false`
+     * when the animation was interrupted (for example by a new gesture). Does
+     * not fire for a release that did not commit.
+     */
+    onSwipeEnd?: (direction: SwipeDirection, info: {
+        finished: boolean;
+    }) => void;
 }
 interface UseSwipeResult {
     /** Pan gesture to pass to a `<GestureDetector>`. */
     gesture: PanGesture;
     /**
      * Animated style fragment exposing live translation while the gesture is
-     * active. Snaps back to `{ 0, 0 }` after release (whether or not the swipe
-     * committed) via a default spring.
+     * active. After release it snaps back to `{ 0, 0 }` via `releaseTransition`
+     * (default spring), unless a committed swipe's `onCommit` returned a
+     * commit-exit transition for that axis.
+     *
+     * This owns the whole `transform` style key. `transform` is one key in React
+     * Native, so a second style in the same array **replaces** this array rather
+     * than merging with it — `style={[swipe.animatedStyle, tiltStyle]}` silently
+     * drops the translation and only the tilt runs. To add a transform of your
+     * own, nest another animated view, or build one style from `swipeX` /
+     * `swipeY` yourself with `useInterpolatedStyle`.
      */
     animatedStyle: ReturnType<typeof useAnimatedStyle>;
     /** Live x translation. */
@@ -178,14 +254,24 @@ interface UseSwipeResult {
     swipeY: SharedValue<number>;
     /** True while the user is actively swiping. */
     isActive: SharedValue<boolean>;
+    /**
+     * Snap both shared values back to zero with no animation, cancelling
+     * anything in flight. After a commit exit the values stay at the exit
+     * target — call this when the next card takes over the same mounted
+     * component. A keyed remount gets fresh values and doesn't need it.
+     */
+    reset: () => void;
 }
 /**
  * Directional commit-or-snap-back gesture. Tracks live translation while the
  * user drags and fires `onSwipe(direction)` on release if either the distance
- * or velocity threshold is exceeded in an allowed direction. The position
- * shared values always animate back to zero — the consumer is responsible
- * for whatever side effect the commit drives (delete a row, dismiss a sheet,
- * etc.).
+ * or velocity threshold is exceeded in an allowed direction.
+ *
+ * By default the position shared values animate back to zero whether or not
+ * the swipe commits — the right shape for swipe-to-delete, where the row
+ * returns and the consumer removes it. For a card deck, return a commit-exit
+ * transition from `onCommit` so the committed card continues off screen, and
+ * advance the deck from `onSwipeEnd` when it settles.
  *
  * Usage:
  * ```tsx
@@ -199,6 +285,22 @@ interface UseSwipeResult {
  *   </GestureDetector>
  * )
  * ```
+ *
+ * `animatedStyle` owns the whole `transform` key, so it does not compose with
+ * a second transform style. To add rotation — the usual card-deck shape —
+ * build one style from `swipeX` instead of stacking two:
+ *
+ * ```tsx
+ * const cardStyle = useInterpolatedStyle(swipe.swipeX, {
+ *   translateX: [-200, 0, 200],
+ *   rotate: ['-12deg', '0deg', '12deg'],
+ * })
+ * return (
+ *   <GestureDetector gesture={swipe.gesture}>
+ *     <Motion.View style={cardStyle}>...</Motion.View>
+ *   </GestureDetector>
+ * )
+ * ```
  */
 declare function useSwipe(options?: SwipeOptions): UseSwipeResult;
 
@@ -227,7 +329,12 @@ interface PanOptions {
 interface UsePanResult {
     /** Pan gesture to pass to a `<GestureDetector>`. */
     gesture: PanGesture;
-    /** Stable animated `transform` style. */
+    /**
+     * Stable animated `transform` style. This owns the whole `transform` key —
+     * a second transform style in the same array replaces it rather than merging
+     * with it. Nest another animated view, or build one style from `panX` /
+     * `panY` with `useInterpolatedStyle`, to add a transform of your own.
+     */
     animatedStyle: ReturnType<typeof useAnimatedStyle>;
     /** Live x translation, persistent across gestures. */
     panX: SharedValue<number>;
@@ -247,4 +354,4 @@ interface UsePanResult {
  */
 declare function usePan(options?: PanOptions): UsePanResult;
 
-export { type DragConstraints, type DragOptions, type PanOptions, type ReleaseInfo, type ReleaseResult, type ReleaseTransition, type SwipeDirection, type SwipeOptions, type UseDragResult, type UsePanResult, type UseSwipeResult, useDrag, usePan, useSwipe };
+export { type DragConstraints, type DragOptions, type PanOptions, type ReleaseInfo, type ReleaseResult, type ReleaseTransition, type SnapBackTransition, type SwipeDirection, type SwipeOptions, type UseDragResult, type UsePanResult, type UseSwipeResult, useDrag, usePan, useSwipe };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { PanGesture } from 'react-native-gesture-handler';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { SpringTransition, TimingTransition, DecayTransition, NoAnimationTransition } from '@rootnative/inertia';
+import { SpringTransition, TimingTransition, DecayTransition, NoAnimationTransition, TransitionName } from '@rootnative/inertia';
 
 /**
  * Public types for `@rootnative/inertia-gestures`.
@@ -48,11 +48,22 @@ type ReleaseTransition = (SpringTransition & {
 /**
  * Per-axis release transitions returned by `onRelease`. Omit an axis to leave
  * its SV where it landed (no release animation on that axis).
+ *
+ * `useSwipe`'s `onCommit` returns the same shape with one difference in the
+ * omit semantics: an omitted axis snaps back to zero (the hook's resting
+ * state) rather than staying where it landed.
  */
 interface ReleaseResult {
     x?: ReleaseTransition;
     y?: ReleaseTransition;
 }
+/**
+ * Transition shapes `useSwipe` accepts for its snap-back (the
+ * `releaseTransition` option). The target is always zero, so decay — which
+ * has no target — is excluded; a registered name that resolves to a decay
+ * config dev-warns and falls back to the default spring.
+ */
+type SnapBackTransition = SpringTransition | TimingTransition | NoAnimationTransition;
 /**
  * Configuration for `useDrag`. All fields are optional; the defaults give an
  * unconstrained two-axis drag with no elasticity.
@@ -104,8 +115,14 @@ interface UseDragResult {
     /** Pan gesture to pass to a `<GestureDetector>`. */
     gesture: PanGesture;
     /**
-     * Animated style fragment (a single `transform` entry) to stack onto the
-     * dragged Motion primitive's `style` prop. Stable across renders.
+     * Animated style fragment for the dragged Motion primitive's `style` prop.
+     * Stable across renders.
+     *
+     * This owns the whole `transform` key. Do not stack a second transform style
+     * beside it — `transform` is one key in React Native, so the later style
+     * replaces this one instead of merging, and the drag silently stops
+     * following the finger. Nest another animated view, or build one style from
+     * `dragX` / `dragY` with `useInterpolatedStyle`, to add a transform.
      */
     animatedStyle: ReturnType<typeof useAnimatedStyle>;
     /** Current x translation in pixels. UI-thread shared value. */
@@ -155,6 +172,17 @@ interface SwipeOptions {
      * to `800`.
      */
     velocityThreshold?: number;
+    /**
+     * Transition for the snap-back to zero, given inline or as a registered
+     * `TransitionName` from the nearest `<MotionConfig transitions={...}>`.
+     * Defaults to the library default spring. The release velocity is passed
+     * into a spring automatically (unless the config sets `velocity` itself),
+     * so a flick that stops short of the threshold resets with the momentum it
+     * had. Decay is excluded — the snap-back always targets zero, and decay has
+     * no target; a name that resolves to a decay config dev-warns and falls
+     * back to the default spring.
+     */
+    releaseTransition?: SnapBackTransition | TransitionName;
     /**
      * Fired on the JS thread when the gesture commits in an allowed direction.
      */
@@ -162,14 +190,62 @@ interface SwipeOptions {
         distance: number;
         velocity: number;
     }) => void;
+    /**
+     * UI-thread callback fired when the gesture commits, before any release
+     * animation starts. Return per-axis release transitions to run **instead
+     * of** the snap-back — the commit-exit path a card deck needs, where the
+     * committed card continues in the swipe direction and leaves the screen:
+     *
+     * ```ts
+     * onCommit: (direction, info) => {
+     *   'worklet'
+     *   return {
+     *     x: {
+     *       type: 'spring',
+     *       to: direction === 'right' ? 500 : -500,
+     *       velocity: info.velocity.x,
+     *     },
+     *   }
+     * }
+     * ```
+     *
+     * An omitted axis (or a `void` return) snaps back to zero as usual. This
+     * callback runs as a worklet so the release velocity stays on the UI
+     * thread — author it with the `'worklet'` directive at the top of the body.
+     *
+     * Composes with `onSwipe`: both fire on commit. `onCommit` picks the
+     * release animation on the UI thread; `onSwipe` is for JS-thread side
+     * effects. Note the shared values stay at the exit target afterwards — call
+     * `reset()` when the next card takes over without a remount.
+     */
+    onCommit?: (direction: SwipeDirection, info: ReleaseInfo) => ReleaseResult | void;
+    /**
+     * Fired on the JS thread when a committed swipe's release animation
+     * settles — the commit exit from `onCommit` if one ran, the snap-back
+     * otherwise. This is the "card is gone, advance the deck" moment that
+     * `onSwipe` (which fires at release) cannot give you. `finished` is `false`
+     * when the animation was interrupted (for example by a new gesture). Does
+     * not fire for a release that did not commit.
+     */
+    onSwipeEnd?: (direction: SwipeDirection, info: {
+        finished: boolean;
+    }) => void;
 }
 interface UseSwipeResult {
     /** Pan gesture to pass to a `<GestureDetector>`. */
     gesture: PanGesture;
     /**
      * Animated style fragment exposing live translation while the gesture is
-     * active. Snaps back to `{ 0, 0 }` after release (whether or not the swipe
-     * committed) via a default spring.
+     * active. After release it snaps back to `{ 0, 0 }` via `releaseTransition`
+     * (default spring), unless a committed swipe's `onCommit` returned a
+     * commit-exit transition for that axis.
+     *
+     * This owns the whole `transform` style key. `transform` is one key in React
+     * Native, so a second style in the same array **replaces** this array rather
+     * than merging with it — `style={[swipe.animatedStyle, tiltStyle]}` silently
+     * drops the translation and only the tilt runs. To add a transform of your
+     * own, nest another animated view, or build one style from `swipeX` /
+     * `swipeY` yourself with `useInterpolatedStyle`.
      */
     animatedStyle: ReturnType<typeof useAnimatedStyle>;
     /** Live x translation. */
@@ -178,14 +254,24 @@ interface UseSwipeResult {
     swipeY: SharedValue<number>;
     /** True while the user is actively swiping. */
     isActive: SharedValue<boolean>;
+    /**
+     * Snap both shared values back to zero with no animation, cancelling
+     * anything in flight. After a commit exit the values stay at the exit
+     * target — call this when the next card takes over the same mounted
+     * component. A keyed remount gets fresh values and doesn't need it.
+     */
+    reset: () => void;
 }
 /**
  * Directional commit-or-snap-back gesture. Tracks live translation while the
  * user drags and fires `onSwipe(direction)` on release if either the distance
- * or velocity threshold is exceeded in an allowed direction. The position
- * shared values always animate back to zero — the consumer is responsible
- * for whatever side effect the commit drives (delete a row, dismiss a sheet,
- * etc.).
+ * or velocity threshold is exceeded in an allowed direction.
+ *
+ * By default the position shared values animate back to zero whether or not
+ * the swipe commits — the right shape for swipe-to-delete, where the row
+ * returns and the consumer removes it. For a card deck, return a commit-exit
+ * transition from `onCommit` so the committed card continues off screen, and
+ * advance the deck from `onSwipeEnd` when it settles.
  *
  * Usage:
  * ```tsx
@@ -199,6 +285,22 @@ interface UseSwipeResult {
  *   </GestureDetector>
  * )
  * ```
+ *
+ * `animatedStyle` owns the whole `transform` key, so it does not compose with
+ * a second transform style. To add rotation — the usual card-deck shape —
+ * build one style from `swipeX` instead of stacking two:
+ *
+ * ```tsx
+ * const cardStyle = useInterpolatedStyle(swipe.swipeX, {
+ *   translateX: [-200, 0, 200],
+ *   rotate: ['-12deg', '0deg', '12deg'],
+ * })
+ * return (
+ *   <GestureDetector gesture={swipe.gesture}>
+ *     <Motion.View style={cardStyle}>...</Motion.View>
+ *   </GestureDetector>
+ * )
+ * ```
  */
 declare function useSwipe(options?: SwipeOptions): UseSwipeResult;
 
@@ -227,7 +329,12 @@ interface PanOptions {
 interface UsePanResult {
     /** Pan gesture to pass to a `<GestureDetector>`. */
     gesture: PanGesture;
-    /** Stable animated `transform` style. */
+    /**
+     * Stable animated `transform` style. This owns the whole `transform` key —
+     * a second transform style in the same array replaces it rather than merging
+     * with it. Nest another animated view, or build one style from `panX` /
+     * `panY` with `useInterpolatedStyle`, to add a transform of your own.
+     */
     animatedStyle: ReturnType<typeof useAnimatedStyle>;
     /** Live x translation, persistent across gestures. */
     panX: SharedValue<number>;
@@ -247,4 +354,4 @@ interface UsePanResult {
  */
 declare function usePan(options?: PanOptions): UsePanResult;
 
-export { type DragConstraints, type DragOptions, type PanOptions, type ReleaseInfo, type ReleaseResult, type ReleaseTransition, type SwipeDirection, type SwipeOptions, type UseDragResult, type UsePanResult, type UseSwipeResult, useDrag, usePan, useSwipe };
+export { type DragConstraints, type DragOptions, type PanOptions, type ReleaseInfo, type ReleaseResult, type ReleaseTransition, type SnapBackTransition, type SwipeDirection, type SwipeOptions, type UseDragResult, type UsePanResult, type UseSwipeResult, useDrag, usePan, useSwipe };

package/dist/index.js

@@ -116,12 +116,16 @@ function applyBounds(value, min, max, elastic) {
   return value;
 }
 var DEFAULT_DIRECTIONS = ["left", "right", "up", "down"];
+var DEFAULT_SNAP_BACK = { type: "spring" };
 function useSwipe(options = {}) {
   const {
     directions = DEFAULT_DIRECTIONS,
     distanceThreshold = 80,
     velocityThreshold = 800,
-    onSwipe
+    releaseTransition,
+    onSwipe,
+    onCommit,
+    onSwipeEnd
   } = options;
   const swipeX = reactNativeReanimated.useSharedValue(0);
   const swipeY = reactNativeReanimated.useSharedValue(0);
@@ -130,6 +134,19 @@ function useSwipe(options = {}) {
   const allowRight = directions.includes("right");
   const allowUp = directions.includes("up");
   const allowDown = directions.includes("down");
+  const registry = inertia.useNamedTransitions();
+  const snapBack = react.useMemo(() => {
+    const cfg = inertia.resolveNamedTransition(releaseTransition, registry) ?? DEFAULT_SNAP_BACK;
+    if (cfg.type === "decay") {
+      if (__DEV__) {
+        console.warn(
+          "[inertia] useSwipe `releaseTransition` resolved to a decay transition, which has no target and cannot snap back to zero \u2014 falling back to the default spring."
+        );
+      }
+      return DEFAULT_SNAP_BACK;
+    }
+    return cfg;
+  }, [releaseTransition, registry]);
   const gesture = react.useMemo(() => {
     const pan = reactNativeGestureHandler.Gesture.Pan().onStart(() => {
       "worklet";
@@ -159,8 +176,53 @@ function useSwipe(options = {}) {
         const velocity = isHoriz ? Math.abs(e.velocityX) : Math.abs(e.velocityY);
         reactNativeReanimated.runOnJS(onSwipe)(direction, { distance, velocity });
       }
-      swipeX.value = reactNativeReanimated.withSpring(0);
-      swipeY.value = reactNativeReanimated.withSpring(0);
+      let exit = void 0;
+      if (direction !== null && onCommit) {
+        exit = onCommit(direction, {
+          x: swipeX.value,
+          y: swipeY.value,
+          velocity: { x: e.velocityX, y: e.velocityY }
+        });
+      }
+      let settle;
+      if (direction !== null && onSwipeEnd) {
+        const dir = direction;
+        const end = onSwipeEnd;
+        settle = (finished) => {
+          reactNativeReanimated.runOnJS(end)(dir, { finished: finished === true });
+        };
+      }
+      const isHorizontalCommit = direction === "left" || direction === "right";
+      const settleX = isHorizontalCommit ? settle : void 0;
+      const settleY = isHorizontalCommit ? void 0 : settle;
+      const exitX = exit ? exit.x : void 0;
+      const exitY = exit ? exit.y : void 0;
+      if (exitX) {
+        swipeX.value = inertia.buildReleaseAnimation(
+          exitX,
+          "to" in exitX ? exitX.to : swipeX.value,
+          settleX
+        );
+      } else {
+        swipeX.value = inertia.buildReleaseAnimation(
+          withReleaseVelocity(snapBack, e.velocityX),
+          0,
+          settleX
+        );
+      }
+      if (exitY) {
+        swipeY.value = inertia.buildReleaseAnimation(
+          exitY,
+          "to" in exitY ? exitY.to : swipeY.value,
+          settleY
+        );
+      } else {
+        swipeY.value = inertia.buildReleaseAnimation(
+          withReleaseVelocity(snapBack, e.velocityY),
+          0,
+          settleY
+        );
+      }
     }).onFinalize(() => {
       "worklet";
       isActive.value = false;
@@ -173,7 +235,10 @@ function useSwipe(options = {}) {
     allowRight,
     allowUp,
     allowDown,
+    snapBack,
     onSwipe,
+    onCommit,
+    onSwipeEnd,
     swipeX,
     swipeY,
     isActive
@@ -181,7 +246,17 @@ function useSwipe(options = {}) {
   const animatedStyle = reactNativeReanimated.useAnimatedStyle(() => ({
     transform: [{ translateX: swipeX.value }, { translateY: swipeY.value }]
   }));
-  return { gesture, animatedStyle, swipeX, swipeY, isActive };
+  const reset = react.useCallback(() => {
+    swipeX.value = 0;
+    swipeY.value = 0;
+  }, [swipeX, swipeY]);
+  return { gesture, animatedStyle, swipeX, swipeY, isActive, reset };
+}
+function withReleaseVelocity(cfg, velocity) {
+  "worklet";
+  if (cfg.type !== "spring" && cfg.type !== void 0) return cfg;
+  if (cfg.velocity !== void 0) return cfg;
+  return { ...cfg, velocity };
 }
 function pickDirection(tx, ty, vx, vy, distanceThreshold, velocityThreshold, allowLeft, allowRight, allowUp, allowDown) {
   "worklet";

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { useMemo } from 'react';
+import { useMemo, useCallback } from 'react';
 import { Gesture } from 'react-native-gesture-handler';
-import { useSharedValue, runOnJS, useAnimatedStyle, withSpring, withDecay } from 'react-native-reanimated';
-import { buildReleaseAnimation } from '@rootnative/inertia';
+import { useSharedValue, runOnJS, useAnimatedStyle, withDecay } from 'react-native-reanimated';
+import { buildReleaseAnimation, useNamedTransitions, resolveNamedTransition } from '@rootnative/inertia';
 
 // src/useDrag.ts
 function useDrag(options = {}) {
@@ -114,12 +114,16 @@ function applyBounds(value, min, max, elastic) {
   return value;
 }
 var DEFAULT_DIRECTIONS = ["left", "right", "up", "down"];
+var DEFAULT_SNAP_BACK = { type: "spring" };
 function useSwipe(options = {}) {
   const {
     directions = DEFAULT_DIRECTIONS,
     distanceThreshold = 80,
     velocityThreshold = 800,
-    onSwipe
+    releaseTransition,
+    onSwipe,
+    onCommit,
+    onSwipeEnd
   } = options;
   const swipeX = useSharedValue(0);
   const swipeY = useSharedValue(0);
@@ -128,6 +132,19 @@ function useSwipe(options = {}) {
   const allowRight = directions.includes("right");
   const allowUp = directions.includes("up");
   const allowDown = directions.includes("down");
+  const registry = useNamedTransitions();
+  const snapBack = useMemo(() => {
+    const cfg = resolveNamedTransition(releaseTransition, registry) ?? DEFAULT_SNAP_BACK;
+    if (cfg.type === "decay") {
+      if (__DEV__) {
+        console.warn(
+          "[inertia] useSwipe `releaseTransition` resolved to a decay transition, which has no target and cannot snap back to zero \u2014 falling back to the default spring."
+        );
+      }
+      return DEFAULT_SNAP_BACK;
+    }
+    return cfg;
+  }, [releaseTransition, registry]);
   const gesture = useMemo(() => {
     const pan = Gesture.Pan().onStart(() => {
       "worklet";
@@ -157,8 +174,53 @@ function useSwipe(options = {}) {
         const velocity = isHoriz ? Math.abs(e.velocityX) : Math.abs(e.velocityY);
         runOnJS(onSwipe)(direction, { distance, velocity });
       }
-      swipeX.value = withSpring(0);
-      swipeY.value = withSpring(0);
+      let exit = void 0;
+      if (direction !== null && onCommit) {
+        exit = onCommit(direction, {
+          x: swipeX.value,
+          y: swipeY.value,
+          velocity: { x: e.velocityX, y: e.velocityY }
+        });
+      }
+      let settle;
+      if (direction !== null && onSwipeEnd) {
+        const dir = direction;
+        const end = onSwipeEnd;
+        settle = (finished) => {
+          runOnJS(end)(dir, { finished: finished === true });
+        };
+      }
+      const isHorizontalCommit = direction === "left" || direction === "right";
+      const settleX = isHorizontalCommit ? settle : void 0;
+      const settleY = isHorizontalCommit ? void 0 : settle;
+      const exitX = exit ? exit.x : void 0;
+      const exitY = exit ? exit.y : void 0;
+      if (exitX) {
+        swipeX.value = buildReleaseAnimation(
+          exitX,
+          "to" in exitX ? exitX.to : swipeX.value,
+          settleX
+        );
+      } else {
+        swipeX.value = buildReleaseAnimation(
+          withReleaseVelocity(snapBack, e.velocityX),
+          0,
+          settleX
+        );
+      }
+      if (exitY) {
+        swipeY.value = buildReleaseAnimation(
+          exitY,
+          "to" in exitY ? exitY.to : swipeY.value,
+          settleY
+        );
+      } else {
+        swipeY.value = buildReleaseAnimation(
+          withReleaseVelocity(snapBack, e.velocityY),
+          0,
+          settleY
+        );
+      }
     }).onFinalize(() => {
       "worklet";
       isActive.value = false;
@@ -171,7 +233,10 @@ function useSwipe(options = {}) {
     allowRight,
     allowUp,
     allowDown,
+    snapBack,
     onSwipe,
+    onCommit,
+    onSwipeEnd,
     swipeX,
     swipeY,
     isActive
@@ -179,7 +244,17 @@ function useSwipe(options = {}) {
   const animatedStyle = useAnimatedStyle(() => ({
     transform: [{ translateX: swipeX.value }, { translateY: swipeY.value }]
   }));
-  return { gesture, animatedStyle, swipeX, swipeY, isActive };
+  const reset = useCallback(() => {
+    swipeX.value = 0;
+    swipeY.value = 0;
+  }, [swipeX, swipeY]);
+  return { gesture, animatedStyle, swipeX, swipeY, isActive, reset };
+}
+function withReleaseVelocity(cfg, velocity) {
+  "worklet";
+  if (cfg.type !== "spring" && cfg.type !== void 0) return cfg;
+  if (cfg.velocity !== void 0) return cfg;
+  return { ...cfg, velocity };
 }
 function pickDirection(tx, ty, vx, vy, distanceThreshold, velocityThreshold, allowLeft, allowRight, allowUp, allowDown) {
   "worklet";

package/llms.txt

@@ -100,7 +100,7 @@ Internally this routes through `buildReleaseAnimation` exported from `@rootnativ
 
 ## `useSwipe`
 
-Directional commit-or-snap-back gesture. Tracks live translation while the user drags; on release, fires `onSwipe` if either the distance or velocity threshold is met along an allowed axis. Whether or not it commits, the position springs back to zero — the consumer drives the side effect (delete, dismiss, advance).
+Directional commit-or-snap-back gesture. Tracks live translation while the user drags; on release, fires `onSwipe` if either the distance or velocity threshold is met along an allowed axis. By default the position animates back to zero whether or not it commits — the right shape for swipe-to-delete, where the row returns and the consumer removes it. For a card deck, return a commit-exit transition from `onCommit` so the committed card continues off screen instead (see below).
 
 ```tsx
 const swipe = useSwipe({
@@ -121,15 +121,95 @@ return (
 )
 ```
 
-| Option              | Type                                          | Default  | Notes                                                             |
-| ------------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------- |
-| `directions`        | `Array<'left' \| 'right' \| 'up' \| 'down'>`  | all four | Only commits along listed directions. Off-axis swipes do nothing. |
-| `distanceThreshold` | `number` (px)                                 | `80`     | Distance past which a release commits.                            |
-| `velocityThreshold` | `number` (px/sec)                             | `800`    | Flick velocity that commits even before distance threshold.       |
-| `onSwipe`           | `(direction, { distance, velocity }) => void` | none     | JS-thread callback. Direction is one of the allowed values.       |
+| Option              | Type                                                   | Default        | Notes                                                                  |
+| ------------------- | ------------------------------------------------------ | -------------- | ---------------------------------------------------------------------- |
+| `directions`        | `Array<'left' \| 'right' \| 'up' \| 'down'>`           | all four       | Only commits along listed directions. Off-axis swipes do nothing.      |
+| `distanceThreshold` | `number` (px)                                          | `80`           | Distance past which a release commits.                                 |
+| `velocityThreshold` | `number` (px/sec)                                      | `800`          | Flick velocity that commits even before distance threshold.            |
+| `releaseTransition` | `SnapBackTransition \| TransitionName`                 | default spring | Transition for the snap-back to zero — see below.                      |
+| `onSwipe`           | `(direction, { distance, velocity }) => void`          | none           | JS-thread callback at release. Direction is one of the allowed values. |
+| `onCommit`          | `(direction, info) => ReleaseResult \| void` (worklet) | none           | UI-thread commit-exit transition — see below.                          |
+| `onSwipeEnd`        | `(direction, { finished }) => void`                    | none           | JS-thread callback when a committed swipe's release animation settles. |
 
 The dominant axis (whichever of \|tx\|, \|ty\| is larger at release) decides which direction is checked.
 
+Returns `{ gesture, animatedStyle, swipeX, swipeY, isActive, reset }`. `reset()` snaps both shared values back to zero with no animation — useful after a commit exit when the next card takes over the same mounted component (a keyed remount gets fresh values and doesn't need it).
+
+### Snap-back transition (`releaseTransition`)
+
+The snap-back to zero defaults to the library default spring. Pass `releaseTransition` to use your own — inline, or as a `TransitionName` registered on the nearest [`<MotionConfig transitions={...}>`](./motion-config#named-transitions), which is how the reset joins a design-token motion system:
+
+```tsx
+const swipe = useSwipe({
+  directions: ['left', 'right'],
+  releaseTransition: 'spatial-default', // or { type: 'spring', tension: 220 }
+  onSwipe: (direction) => archive(direction),
+})
+```
+
+The release velocity is passed into a spring automatically (unless the config sets `velocity` itself), so a flick that stops short of the threshold resets with the momentum it had instead of resetting as if the finger had been still.
+
+`SnapBackTransition` is spring / timing / no-animation — decay is excluded, because the snap-back always targets zero and decay has no target. A registered name that resolves to a decay config dev-warns and falls back to the default spring.
+
+### Commit exit (`onCommit` + `onSwipeEnd`)
+
+The snap-back is right for swipe-to-delete, but a card deck needs the opposite: a **committed** card must continue in the swipe direction and leave the screen. Return per-axis release transitions from `onCommit` to run instead of the snap-back, and advance the deck from `onSwipeEnd` when the exit settles:
+
+```tsx
+const swipe = useSwipe({
+  directions: ['left', 'right'],
+  onCommit: (direction, info) => {
+    'worklet'
+    return {
+      x: {
+        type: 'spring',
+        to: direction === 'right' ? 500 : -500,
+        velocity: info.velocity.x, // continue the finger's momentum
+      },
+    }
+  },
+  onSwipeEnd: (direction, { finished }) => {
+    if (finished) advanceDeck(direction)
+  },
+})
+```
+
+`onCommit` runs as a **worklet** on the UI thread (author it with the `'worklet'` directive), fires only when the gesture commits, and receives the same `info` shape as `useDrag`'s `onRelease` — final translation plus release velocity. The return shape is the same `ReleaseResult` too, with one difference: an omitted axis (or a `void` return) snaps back to zero as usual, because zero is this hook's resting state.
+
+`onSwipeEnd` fires on the JS thread when the committed swipe's release animation settles — the commit exit if one ran, the snap-back otherwise. That is the "card is gone, the next one takes over" moment that `onSwipe` (which fires at release) cannot give you. `finished` is `false` when the animation was interrupted, for example by a new gesture. It does not fire for a release that did not commit.
+
+Composition: `onSwipe` (JS side effects at release) → `onCommit` (UI-thread exit decision) → `onSwipeEnd` (JS side effects at settle). Use whichever subset the interaction needs.
+
+### `animatedStyle` owns the whole `transform` key
+
+`animatedStyle` returns a complete `transform` array. In React Native `transform` is a **single** style key, so a second style carrying its own `transform` **replaces** this one rather than merging with it. Stacking a rotation beside it — the first thing almost every card deck does — silently drops the translation, and the card rotates without following the finger:
+
+```tsx
+// Broken: tiltStyle's transform replaces the swipe translation.
+<Motion.View style={[swipe.animatedStyle, tiltStyle]} />
+```
+
+Pairing `animatedStyle` with a static style is safe (`[styles.card, swipe.animatedStyle]` above) because a static style declares no `transform`. The conflict only appears when the second style is itself a transform.
+
+Build one style from `swipeX` instead of stacking two:
+
+```tsx
+const cardStyle = useInterpolatedStyle(swipe.swipeX, {
+  translateX: [-200, 0, 200],
+  rotate: ['-12deg', '0deg', '12deg'],
+})
+
+return (
+  <GestureDetector gesture={swipe.gesture}>
+    <Motion.View style={[styles.card, cardStyle]}>{children}</Motion.View>
+  </GestureDetector>
+)
+```
+
+Nesting a second `Motion.View` also works — one view per transform source — when the transforms come from genuinely independent drivers.
+
+The same applies to `useDrag` and `usePan`: each owns its `transform` key too.
+
 ## `usePan`
 
 Camera-style pan with momentum on release. Position **persists across separate gestures** — the next pan starts from the current offset, not zero — and on release the position continues gliding via Reanimated's `withDecay`.
@@ -159,11 +239,11 @@ For rubber-banded constraints, prefer `useDrag({ elastic })` — `usePan` hard-c
 
 ## When to pick which
 
-| Gesture    | Snap back on release? | Momentum on release?         | Typical UX                                         |
-| ---------- | --------------------- | ---------------------------- | -------------------------------------------------- |
-| `useDrag`  | No — stays where left | No                           | Move-to-position, sliders, sortable handles.       |
-| `useSwipe` | Yes — always          | No (springs back)            | Swipe-to-delete rows, card stacks, dismiss sheets. |
-| `usePan`   | No — stays where left | Yes — coasts via `withDecay` | Maps, zoomable canvases, large-image navigation.   |
+| Gesture    | Snap back on release?                   | Momentum on release?         | Typical UX                                         |
+| ---------- | --------------------------------------- | ---------------------------- | -------------------------------------------------- |
+| `useDrag`  | No — stays where left                   | No                           | Move-to-position, sliders, sortable handles.       |
+| `useSwipe` | Yes — unless `onCommit` returns an exit | No (springs back)            | Swipe-to-delete rows, card stacks, dismiss sheets. |
+| `usePan`   | No — stays where left                   | Yes — coasts via `withDecay` | Maps, zoomable canvases, large-image navigation.   |
 
 ## Scope: touch + mouse only
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia-gestures",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Gesture-handler-driven drag / pan / swipe adapters for @rootnative/inertia.",
   "license": "MIT",
   "author": "RootNative",
@@ -50,7 +50,7 @@
     "!**/*.test.*"
   ],
   "peerDependencies": {
-    "@rootnative/inertia": ">=0.0.7",
+    "@rootnative/inertia": ">=0.0.8",
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",
     "react-native-gesture-handler": ">=2.0.0",
@@ -69,7 +69,7 @@
     "react-test-renderer": "19.1.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
-    "@rootnative/inertia": "0.0.7"
+    "@rootnative/inertia": "0.0.8"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -6,7 +6,8 @@
  * - `useDrag` — one- or two-axis drag with optional constraints and
  *   rubber-band elasticity.
  * - `useSwipe` — directional commit-or-snap-back gesture (distance + velocity
- *   thresholds).
+ *   thresholds), with a configurable snap-back and an optional commit-exit
+ *   path for card decks.
  * - `usePan` — camera-style pan with momentum on release.
  */
 export { useDrag } from './useDrag'
@@ -21,4 +22,5 @@ export type {
   ReleaseInfo,
   ReleaseResult,
   ReleaseTransition,
+  SnapBackTransition,
 } from './types'

package/src/types.ts

@@ -49,12 +49,27 @@ export type ReleaseTransition =
 /**
  * Per-axis release transitions returned by `onRelease`. Omit an axis to leave
  * its SV where it landed (no release animation on that axis).
+ *
+ * `useSwipe`'s `onCommit` returns the same shape with one difference in the
+ * omit semantics: an omitted axis snaps back to zero (the hook's resting
+ * state) rather than staying where it landed.
  */
 export interface ReleaseResult {
   x?: ReleaseTransition
   y?: ReleaseTransition
 }
 
+/**
+ * Transition shapes `useSwipe` accepts for its snap-back (the
+ * `releaseTransition` option). The target is always zero, so decay — which
+ * has no target — is excluded; a registered name that resolves to a decay
+ * config dev-warns and falls back to the default spring.
+ */
+export type SnapBackTransition =
+  | SpringTransition
+  | TimingTransition
+  | NoAnimationTransition
+
 /**
  * Configuration for `useDrag`. All fields are optional; the defaults give an
  * unconstrained two-axis drag with no elasticity.

package/src/useDrag.ts

@@ -13,8 +13,14 @@ export interface UseDragResult {
   /** Pan gesture to pass to a `<GestureDetector>`. */
   gesture: PanGesture
   /**
-   * Animated style fragment (a single `transform` entry) to stack onto the
-   * dragged Motion primitive's `style` prop. Stable across renders.
+   * Animated style fragment for the dragged Motion primitive's `style` prop.
+   * Stable across renders.
+   *
+   * This owns the whole `transform` key. Do not stack a second transform style
+   * beside it — `transform` is one key in React Native, so the later style
+   * replaces this one instead of merging, and the drag silently stops
+   * following the finger. Nest another animated view, or build one style from
+   * `dragX` / `dragY` with `useInterpolatedStyle`, to add a transform.
    */
   animatedStyle: ReturnType<typeof useAnimatedStyle>
   /** Current x translation in pixels. UI-thread shared value. */

package/src/usePan.ts

@@ -34,7 +34,12 @@ export interface PanOptions {
 export interface UsePanResult {
   /** Pan gesture to pass to a `<GestureDetector>`. */
   gesture: PanGesture
-  /** Stable animated `transform` style. */
+  /**
+   * Stable animated `transform` style. This owns the whole `transform` key —
+   * a second transform style in the same array replaces it rather than merging
+   * with it. Nest another animated view, or build one style from `panX` /
+   * `panY` with `useInterpolatedStyle`, to add a transform of your own.
+   */
   animatedStyle: ReturnType<typeof useAnimatedStyle>
   /** Live x translation, persistent across gestures. */
   panX: SharedValue<number>

package/src/useSwipe.ts

@@ -1,12 +1,21 @@
-import { useMemo } from 'react'
+import { useCallback, useMemo } from 'react'
 import { Gesture, type PanGesture } from 'react-native-gesture-handler'
 import {
   runOnJS,
   useAnimatedStyle,
   useSharedValue,
-  withSpring,
   type SharedValue,
 } from 'react-native-reanimated'
+import {
+  buildReleaseAnimation,
+  resolveNamedTransition,
+  useNamedTransitions,
+  type TransitionConfig,
+  type TransitionName,
+} from '@rootnative/inertia'
+import type { ReleaseInfo, ReleaseResult, SnapBackTransition } from './types'
+
+declare const __DEV__: boolean
 
 export type SwipeDirection = 'left' | 'right' | 'up' | 'down'
 
@@ -28,6 +37,17 @@ export interface SwipeOptions {
    * to `800`.
    */
   velocityThreshold?: number
+  /**
+   * Transition for the snap-back to zero, given inline or as a registered
+   * `TransitionName` from the nearest `<MotionConfig transitions={...}>`.
+   * Defaults to the library default spring. The release velocity is passed
+   * into a spring automatically (unless the config sets `velocity` itself),
+   * so a flick that stops short of the threshold resets with the momentum it
+   * had. Decay is excluded — the snap-back always targets zero, and decay has
+   * no target; a name that resolves to a decay config dev-warns and falls
+   * back to the default spring.
+   */
+  releaseTransition?: SnapBackTransition | TransitionName
   /**
    * Fired on the JS thread when the gesture commits in an allowed direction.
    */
@@ -35,6 +55,47 @@ export interface SwipeOptions {
     direction: SwipeDirection,
     info: { distance: number; velocity: number },
   ) => void
+  /**
+   * UI-thread callback fired when the gesture commits, before any release
+   * animation starts. Return per-axis release transitions to run **instead
+   * of** the snap-back — the commit-exit path a card deck needs, where the
+   * committed card continues in the swipe direction and leaves the screen:
+   *
+   * ```ts
+   * onCommit: (direction, info) => {
+   *   'worklet'
+   *   return {
+   *     x: {
+   *       type: 'spring',
+   *       to: direction === 'right' ? 500 : -500,
+   *       velocity: info.velocity.x,
+   *     },
+   *   }
+   * }
+   * ```
+   *
+   * An omitted axis (or a `void` return) snaps back to zero as usual. This
+   * callback runs as a worklet so the release velocity stays on the UI
+   * thread — author it with the `'worklet'` directive at the top of the body.
+   *
+   * Composes with `onSwipe`: both fire on commit. `onCommit` picks the
+   * release animation on the UI thread; `onSwipe` is for JS-thread side
+   * effects. Note the shared values stay at the exit target afterwards — call
+   * `reset()` when the next card takes over without a remount.
+   */
+  onCommit?: (
+    direction: SwipeDirection,
+    info: ReleaseInfo,
+  ) => ReleaseResult | void
+  /**
+   * Fired on the JS thread when a committed swipe's release animation
+   * settles — the commit exit from `onCommit` if one ran, the snap-back
+   * otherwise. This is the "card is gone, advance the deck" moment that
+   * `onSwipe` (which fires at release) cannot give you. `finished` is `false`
+   * when the animation was interrupted (for example by a new gesture). Does
+   * not fire for a release that did not commit.
+   */
+  onSwipeEnd?: (direction: SwipeDirection, info: { finished: boolean }) => void
 }
 
 export interface UseSwipeResult {
@@ -42,8 +103,16 @@ export interface UseSwipeResult {
   gesture: PanGesture
   /**
    * Animated style fragment exposing live translation while the gesture is
-   * active. Snaps back to `{ 0, 0 }` after release (whether or not the swipe
-   * committed) via a default spring.
+   * active. After release it snaps back to `{ 0, 0 }` via `releaseTransition`
+   * (default spring), unless a committed swipe's `onCommit` returned a
+   * commit-exit transition for that axis.
+   *
+   * This owns the whole `transform` style key. `transform` is one key in React
+   * Native, so a second style in the same array **replaces** this array rather
+   * than merging with it — `style={[swipe.animatedStyle, tiltStyle]}` silently
+   * drops the translation and only the tilt runs. To add a transform of your
+   * own, nest another animated view, or build one style from `swipeX` /
+   * `swipeY` yourself with `useInterpolatedStyle`.
    */
   animatedStyle: ReturnType<typeof useAnimatedStyle>
   /** Live x translation. */
@@ -52,17 +121,29 @@ export interface UseSwipeResult {
   swipeY: SharedValue<number>
   /** True while the user is actively swiping. */
   isActive: SharedValue<boolean>
+  /**
+   * Snap both shared values back to zero with no animation, cancelling
+   * anything in flight. After a commit exit the values stay at the exit
+   * target — call this when the next card takes over the same mounted
+   * component. A keyed remount gets fresh values and doesn't need it.
+   */
+  reset: () => void
 }
 
 const DEFAULT_DIRECTIONS: SwipeDirection[] = ['left', 'right', 'up', 'down']
 
+const DEFAULT_SNAP_BACK: TransitionConfig = { type: 'spring' }
+
 /**
  * Directional commit-or-snap-back gesture. Tracks live translation while the
  * user drags and fires `onSwipe(direction)` on release if either the distance
- * or velocity threshold is exceeded in an allowed direction. The position
- * shared values always animate back to zero — the consumer is responsible
- * for whatever side effect the commit drives (delete a row, dismiss a sheet,
- * etc.).
+ * or velocity threshold is exceeded in an allowed direction.
+ *
+ * By default the position shared values animate back to zero whether or not
+ * the swipe commits — the right shape for swipe-to-delete, where the row
+ * returns and the consumer removes it. For a card deck, return a commit-exit
+ * transition from `onCommit` so the committed card continues off screen, and
+ * advance the deck from `onSwipeEnd` when it settles.
  *
  * Usage:
  * ```tsx
@@ -76,13 +157,32 @@ const DEFAULT_DIRECTIONS: SwipeDirection[] = ['left', 'right', 'up', 'down']
  *   </GestureDetector>
  * )
  * ```
+ *
+ * `animatedStyle` owns the whole `transform` key, so it does not compose with
+ * a second transform style. To add rotation — the usual card-deck shape —
+ * build one style from `swipeX` instead of stacking two:
+ *
+ * ```tsx
+ * const cardStyle = useInterpolatedStyle(swipe.swipeX, {
+ *   translateX: [-200, 0, 200],
+ *   rotate: ['-12deg', '0deg', '12deg'],
+ * })
+ * return (
+ *   <GestureDetector gesture={swipe.gesture}>
+ *     <Motion.View style={cardStyle}>...</Motion.View>
+ *   </GestureDetector>
+ * )
+ * ```
  */
 export function useSwipe(options: SwipeOptions = {}): UseSwipeResult {
   const {
     directions = DEFAULT_DIRECTIONS,
     distanceThreshold = 80,
     velocityThreshold = 800,
+    releaseTransition,
     onSwipe,
+    onCommit,
+    onSwipeEnd,
   } = options
 
   const swipeX = useSharedValue(0)
@@ -94,6 +194,25 @@ export function useSwipe(options: SwipeOptions = {}): UseSwipeResult {
   const allowUp = directions.includes('up')
   const allowDown = directions.includes('down')
 
+  // Resolve a named snap-back on the JS thread, at the nearest provider —
+  // the worklet captures the resolved plain config.
+  const registry = useNamedTransitions()
+  const snapBack = useMemo(() => {
+    const cfg =
+      resolveNamedTransition(releaseTransition, registry) ?? DEFAULT_SNAP_BACK
+    if (cfg.type === 'decay') {
+      if (__DEV__) {
+        console.warn(
+          '[inertia] useSwipe `releaseTransition` resolved to a decay ' +
+            'transition, which has no target and cannot snap back to zero — ' +
+            'falling back to the default spring.',
+        )
+      }
+      return DEFAULT_SNAP_BACK
+    }
+    return cfg
+  }, [releaseTransition, registry])
+
   const gesture = useMemo(() => {
     const pan = Gesture.Pan()
       .onStart(() => {
@@ -130,8 +249,63 @@ export function useSwipe(options: SwipeOptions = {}): UseSwipeResult {
             : Math.abs(e.velocityY)
           runOnJS(onSwipe)(direction, { distance, velocity })
         }
-        swipeX.value = withSpring(0)
-        swipeY.value = withSpring(0)
+
+        // A commit may return per-axis exit transitions to run instead of
+        // the snap-back; any axis it leaves out snaps back as usual.
+        let exit: ReleaseResult | void = undefined
+        if (direction !== null && onCommit) {
+          exit = onCommit(direction, {
+            x: swipeX.value,
+            y: swipeY.value,
+            velocity: { x: e.velocityX, y: e.velocityY },
+          })
+        }
+
+        // `onSwipeEnd` rides the settle callback of the swipe axis — the one
+        // animation whose end means "the card has arrived".
+        let settle: ((finished?: boolean) => void) | undefined
+        if (direction !== null && onSwipeEnd) {
+          const dir = direction
+          const end = onSwipeEnd
+          settle = (finished?: boolean) => {
+            runOnJS(end)(dir, { finished: finished === true })
+          }
+        }
+        const isHorizontalCommit = direction === 'left' || direction === 'right'
+        const settleX = isHorizontalCommit ? settle : undefined
+        const settleY = isHorizontalCommit ? undefined : settle
+
+        const exitX = exit ? exit.x : undefined
+        const exitY = exit ? exit.y : undefined
+        // Decay ignores its target (it has no `to`); the other types animate
+        // to `to`. The snap-back injects the release velocity so a spring
+        // reset continues the finger's momentum.
+        if (exitX) {
+          swipeX.value = buildReleaseAnimation(
+            exitX,
+            'to' in exitX ? exitX.to : swipeX.value,
+            settleX,
+          ) as unknown as number
+        } else {
+          swipeX.value = buildReleaseAnimation(
+            withReleaseVelocity(snapBack, e.velocityX),
+            0,
+            settleX,
+          ) as unknown as number
+        }
+        if (exitY) {
+          swipeY.value = buildReleaseAnimation(
+            exitY,
+            'to' in exitY ? exitY.to : swipeY.value,
+            settleY,
+          ) as unknown as number
+        } else {
+          swipeY.value = buildReleaseAnimation(
+            withReleaseVelocity(snapBack, e.velocityY),
+            0,
+            settleY,
+          ) as unknown as number
+        }
       })
       .onFinalize(() => {
         'worklet'
@@ -145,7 +319,10 @@ export function useSwipe(options: SwipeOptions = {}): UseSwipeResult {
     allowRight,
     allowUp,
     allowDown,
+    snapBack,
     onSwipe,
+    onCommit,
+    onSwipeEnd,
     swipeX,
     swipeY,
     isActive,
@@ -155,7 +332,30 @@ export function useSwipe(options: SwipeOptions = {}): UseSwipeResult {
     transform: [{ translateX: swipeX.value }, { translateY: swipeY.value }],
   }))
 
-  return { gesture, animatedStyle, swipeX, swipeY, isActive }
+  const reset = useCallback(() => {
+    swipeX.value = 0
+    swipeY.value = 0
+  }, [swipeX, swipeY])
+
+  return { gesture, animatedStyle, swipeX, swipeY, isActive, reset }
+}
+
+/**
+ * Inject the release velocity into a spring snap-back so the reset continues
+ * the finger's momentum. Leaves every other transition type — and a spring
+ * whose config already sets `velocity` — untouched.
+ *
+ * Worklet — runs on the UI thread inside the pan handler.
+ */
+function withReleaseVelocity(
+  cfg: TransitionConfig,
+  velocity: number,
+): TransitionConfig {
+  'worklet'
+  // An omitted `type` means spring — the library default everywhere.
+  if (cfg.type !== 'spring' && cfg.type !== undefined) return cfg
+  if (cfg.velocity !== undefined) return cfg
+  return { ...cfg, velocity }
 }
 
 /**