react-native-screen-transitions 3.8.0-alpha.0 → 3.8.0-beta.1

package/src/shared/providers/screen/gestures/types.ts

@@ -16,11 +16,11 @@ import type {
 } from "../../../types/animation.types";
 import type {
 	GestureDirections,
-	GestureProgressMode,
 	ResolvedGestureActivationArea,
 	ScrollGestureAxis,
 	ScrollGestureAxisState,
 	ScrollGestureState,
+	ScrollMetadataState,
 	SnapPanDirectionConfig,
 	SnapPinchDirectionConfig,
 } from "../../../types/gesture.types";
@@ -48,14 +48,14 @@ export type RotationGestureEvent =
 	| GestureUpdateEvent<RotationGestureHandlerEventPayload>
 	| GestureStateChangeEvent<RotationGestureHandlerEventPayload>;
 
-/** Gesture that initiated the current simultaneous gesture composition. */
-export type GestureCompositionActivation = "pan" | "pinch" | null;
+/** Gesture that owns navigation release for the current simultaneous composition. */
+export type GestureCompositionOwner = "pan" | "pinch" | null;
 
 export type {
-	GestureProgressMode,
 	ScrollGestureAxis,
 	ScrollGestureAxisState,
 	ScrollGestureState,
+	ScrollMetadataState,
 };
 
 export type DirectionClaim = {
@@ -112,7 +112,6 @@ export interface PanGesturePolicy {
 	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>;
 	panActivationDirections: GestureDirections;
 	snapAxisDirections: SnapPanDirectionConfig;
-	gestureProgressMode: GestureProgressMode;
 	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
 	gestureVelocityImpact: number;
 	gestureSnapVelocityImpact: number;
@@ -132,7 +131,6 @@ export interface PinchGesturePolicy {
 	snapDirections: SnapPinchDirectionConfig;
 	pinchInEnabled: boolean;
 	pinchOutEnabled: boolean;
-	gestureProgressMode: GestureProgressMode;
 	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
 	gestureSnapVelocityImpact: number;
 	gestureSnapLocked: boolean;
@@ -152,8 +150,6 @@ export interface GestureRuntime<TPolicy extends GesturePolicy> {
 	participation: ScreenGestureParticipation;
 	policy: TPolicy;
 	stores: GestureRuntimeStores;
-	gestureProgressBaseline: SharedValue<number>;
-	lockedSnapPoint: SharedValue<number>;
 }
 
 export type PanGestureRuntime = GestureRuntime<PanGesturePolicy>;
@@ -185,7 +181,6 @@ export interface PanReleaseResult {
 	shouldDismiss: boolean;
 	initialVelocity: number;
 	commitProgress?: number;
-	resetNormalizedValuesImmediately?: boolean;
 	transitionSpec: TransitionSpec | undefined;
 	resetSpec: AnimationConfig | undefined;
 }
@@ -198,10 +193,7 @@ export interface PanReleasePlan {
 	resetVelocityY: number;
 	resetVelocityNormX: number;
 	resetVelocityNormY: number;
-	releaseVelocity: number;
-	resetNormalizedValues: boolean;
-	resetNormalizedValuesImmediately: boolean;
-	preserveRawValues: boolean;
+	handoffVelocity: number;
 	commitProgress?: number;
 	transitionSpec: TransitionSpec | undefined;
 	resetSpec: AnimationConfig | undefined;
@@ -211,6 +203,7 @@ export interface PinchReleaseResult {
 	target: number;
 	shouldDismiss: boolean;
 	initialVelocity: number;
+	handoffVelocity: number;
 	commitProgress?: number;
 	resetValuesImmediately?: boolean;
 	transitionSpec: TransitionSpec | undefined;

package/src/shared/providers/screen/options/helpers.ts

@@ -1,7 +1,6 @@
 import {
 	DEFAULT_GESTURE_ACTIVATION_AREA,
 	DEFAULT_GESTURE_DIRECTION,
-	DEFAULT_GESTURE_PROGRESS_MODE,
 	DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
 	DEFAULT_GESTURE_SENSITIVITY,
 	DEFAULT_GESTURE_SNAP_LOCKED,
@@ -20,11 +19,6 @@ import type {
 	TransitionInterpolatedStyle,
 } from "../../../types";
 import type { BackdropBehavior } from "../../../types/screen.types";
-import {
-	gestureProgressModeDrivesProgress,
-	isGestureProgressMode,
-	resolveGestureProgressMode,
-} from "../../../utils/gesture-progress-mode";
 import { resolveSheetScrollGestureBehavior } from "../../../utils/resolve-screen-transition-options";
 import type {
 	RequiredScreenOption,
@@ -186,25 +180,6 @@ const resolveBackdropBehaviorOption = (
 		: fallback;
 };
 
-const resolveGestureProgressModeOption = (
-	gestureProgressMode: unknown,
-	gestureDrivesProgress: unknown,
-	fallback: RequiredScreenOption<"gestureProgressMode">,
-): RequiredScreenOption<"gestureProgressMode"> => {
-	"worklet";
-	if (isGestureProgressMode(gestureProgressMode)) {
-		return gestureProgressMode;
-	}
-
-	return resolveGestureProgressMode({
-		gestureDrivesProgress:
-			typeof gestureDrivesProgress === "boolean"
-				? gestureDrivesProgress
-				: undefined,
-		fallback,
-	});
-};
-
 const areGestureActivationAreasEqual = (
 	left: RequiredScreenOption<"gestureActivationArea">,
 	right: RequiredScreenOption<"gestureActivationArea">,
@@ -282,8 +257,6 @@ const areScreenOptionsEqual = (
 		left.gestureSnapVelocityImpact === right.gestureSnapVelocityImpact &&
 		left.gestureReleaseVelocityScale === right.gestureReleaseVelocityScale &&
 		left.gestureResponseDistance === right.gestureResponseDistance &&
-		left.gestureProgressMode === right.gestureProgressMode &&
-		left.gestureDrivesProgress === right.gestureDrivesProgress &&
 		areGestureActivationAreasEqual(
 			left.gestureActivationArea,
 			right.gestureActivationArea,
@@ -299,12 +272,6 @@ const areScreenOptionsEqual = (
 export const resolveBaseScreenOptions = (
 	options: ScreenTransitionConfig,
 ): ScreenOptionsSnapshot => {
-	const gestureProgressMode = resolveGestureProgressModeOption(
-		options.gestureProgressMode,
-		options.gestureDrivesProgress,
-		DEFAULT_GESTURE_PROGRESS_MODE,
-	);
-
 	return {
 		navigationMaskEnabled: resolveBooleanOption(
 			options.navigationMaskEnabled,
@@ -339,9 +306,6 @@ export const resolveBaseScreenOptions = (
 			options.gestureResponseDistance,
 			undefined,
 		),
-		gestureProgressMode,
-		gestureDrivesProgress:
-			gestureProgressModeDrivesProgress(gestureProgressMode),
 		gestureActivationArea: resolveGestureActivationAreaOption(
 			options.gestureActivationArea,
 			DEFAULT_GESTURE_ACTIVATION_AREA,
@@ -384,11 +348,6 @@ export const syncScreenOptionsOverrides = (
 	"worklet";
 	const options = raw?.options;
 	const base = screenOptions.get().baseOptions;
-	const gestureProgressMode = resolveGestureProgressModeOption(
-		options?.gestureProgressMode,
-		options?.gestureDrivesProgress,
-		base.gestureProgressMode,
-	);
 
 	const next: ScreenOptionsState = {
 		navigationMaskEnabled: base.navigationMaskEnabled,
@@ -421,9 +380,6 @@ export const syncScreenOptionsOverrides = (
 			options?.gestureResponseDistance,
 			base.gestureResponseDistance,
 		),
-		gestureProgressMode,
-		gestureDrivesProgress:
-			gestureProgressModeDrivesProgress(gestureProgressMode),
 		gestureActivationArea: resolveGestureActivationAreaOption(
 			options?.gestureActivationArea,
 			base.gestureActivationArea,

package/src/shared/providers/screen/options/types.ts

@@ -18,8 +18,6 @@ export type ScreenOptionsSnapshot = {
 	gestureSnapVelocityImpact: RequiredScreenOption<"gestureSnapVelocityImpact">;
 	gestureReleaseVelocityScale: RequiredScreenOption<"gestureReleaseVelocityScale">;
 	gestureResponseDistance: OptionalScreenOption<"gestureResponseDistance">;
-	gestureProgressMode: RequiredScreenOption<"gestureProgressMode">;
-	gestureDrivesProgress: RequiredScreenOption<"gestureDrivesProgress">;
 	gestureActivationArea: RequiredScreenOption<"gestureActivationArea">;
 	gestureSnapLocked: RequiredScreenOption<"gestureSnapLocked">;
 	sheetScrollGestureBehavior: RequiredScreenOption<"sheetScrollGestureBehavior">;

package/src/shared/providers/screen/styles/hooks/use-interpolated-style-maps.tsx

@@ -197,19 +197,19 @@ export const useInterpolatedStylesMap = () => {
 		const interpolatorOptionsOwner =
 			isInGestureMode || !nextInterpolator ? "current" : "next";
 
-		let effectiveProgress = progress;
-		let effectiveNext = next;
+		let selectedProgress = progress;
+		let selectedNext = next;
 
 		if (isInGestureMode) {
-			effectiveProgress = current.progress;
-			effectiveNext = undefined;
+			selectedProgress = current.progress;
+			selectedNext = undefined;
 		}
 
 		const currentResult = runInterpolator({
 			interpolator: currentInterpolator,
 			props,
-			progress: effectiveProgress,
-			next: effectiveNext,
+			progress: selectedProgress,
+			next: selectedNext,
 			bounds: boundsAccessor,
 			transition,
 			shouldDeferStyleBuckets,
@@ -233,8 +233,8 @@ export const useInterpolatedStylesMap = () => {
 		const nextResult = runInterpolator({
 			interpolator: nextInterpolator,
 			props,
-			progress: effectiveProgress,
-			next: effectiveNext,
+			progress: selectedProgress,
+			next: selectedNext,
 			bounds: boundsAccessor,
 			transition,
 			shouldDeferStyleBuckets,

package/src/shared/providers/screen/styles/hooks/use-maybe-block-visibility.tsx

@@ -14,7 +14,8 @@ import { resolveScreenVisibilityGate } from "../helpers/visibility-gate";
 export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 	const { height } = useWindowDimensions();
 	const { currentScreenKey } = useDescriptorDerivations();
-	const { entering, progress } = AnimationStore.getBag(currentScreenKey);
+	const { entering, transitionProgress } =
+		AnimationStore.getBag(currentScreenKey);
 
 	const { pendingLifecycleStartBlockCount, pendingLifecycleRequestKind } =
 		SystemStore.getBag(currentScreenKey);
@@ -40,7 +41,7 @@ export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 				hasVisibilityGateOpened: hasVisibilityGateOpened.get(),
 				pendingLifecycleStartBlockCount: pendingLifecycleStartBlockCount.get(),
 				pendingLifecycleRequestKind: pendingLifecycleRequestKind.get(),
-				progress: progress.get(),
+				progress: transitionProgress.get(),
 				entering: entering.get(),
 			});
 		},

package/src/shared/stores/animation.store.ts

@@ -6,8 +6,8 @@ import {
 import { createStore } from "../utils/create-store";
 
 export type AnimationStoreMap = {
-	progress: SharedValue<number>;
-	effectiveProgress: SharedValue<number>;
+	transitionProgress: SharedValue<number>;
+	visualProgress: SharedValue<number>;
 	willAnimate: SharedValue<number>;
 	progressAnimating: SharedValue<number>;
 	progressSettled: SharedValue<number>;
@@ -17,8 +17,8 @@ export type AnimationStoreMap = {
 
 function createAnimationBag(): AnimationStoreMap {
 	return {
-		progress: makeMutable(0),
-		effectiveProgress: makeMutable(0),
+		transitionProgress: makeMutable(0),
+		visualProgress: makeMutable(0),
 		willAnimate: makeMutable(0),
 		closing: makeMutable(0),
 		progressAnimating: makeMutable(0),
@@ -29,14 +29,14 @@ function createAnimationBag(): AnimationStoreMap {
 
 /**
  * Route-keyed screen transition state for the public animation lifecycle.
- * `progress` tracks committed transition progress; `effectiveProgress` tracks
- * the hydrated progress after live gesture policy is applied.
+ * `transitionProgress` tracks committed transition progress; `visualProgress`
+ * tracks hydrated progress after live gestures are applied.
  */
 export const AnimationStore = createStore<AnimationStoreMap>({
 	createBag: createAnimationBag,
 	disposeBag: (bag) => {
-		cancelAnimation(bag.progress);
-		cancelAnimation(bag.effectiveProgress);
+		cancelAnimation(bag.transitionProgress);
+		cancelAnimation(bag.visualProgress);
 		cancelAnimation(bag.willAnimate);
 		cancelAnimation(bag.progressAnimating);
 		cancelAnimation(bag.progressSettled);

package/src/shared/stores/gesture.store.ts

@@ -19,6 +19,30 @@ type GestureRawStoreMap = {
 	rotation: SharedValue<number>;
 };
 
+type GestureSnapshotStoreMap = {
+	x: SharedValue<number>;
+	y: SharedValue<number>;
+	normX: SharedValue<number>;
+	normY: SharedValue<number>;
+	velocity: SharedValue<number>;
+	scale: SharedValue<number>;
+	normScale: SharedValue<number>;
+	focalX: SharedValue<number>;
+	focalY: SharedValue<number>;
+	rotation: SharedValue<number>;
+	raw: GestureRawStoreMap;
+	active: SharedValue<ActiveGesture | null>;
+	direction: SharedValue<ResolvedPanGestureDirection | null>;
+};
+
+type GestureInternalStoreMap = {
+	progressBaseline: SharedValue<number>;
+	progressDeltaX: SharedValue<number>;
+	progressDeltaY: SharedValue<number>;
+	lockedSnapPoint: SharedValue<number | null>;
+	snapshot: GestureSnapshotStoreMap;
+};
+
 export type GestureStoreMap = {
 	x: SharedValue<number>;
 	y: SharedValue<number>;
@@ -31,6 +55,7 @@ export type GestureStoreMap = {
 	focalY: SharedValue<number>;
 	rotation: SharedValue<number>;
 	raw: GestureRawStoreMap;
+	internal: GestureInternalStoreMap;
 	dismissing: SharedValue<number>;
 	dragging: SharedValue<number>;
 	settling: SharedValue<number>;
@@ -57,6 +82,10 @@ export type GestureStoreMap = {
 };
 
 function createGestureBag(): GestureStoreMap {
+	const progressBaseline = makeMutable(0);
+	const progressDeltaX = makeMutable(0);
+	const progressDeltaY = makeMutable(0);
+	const lockedSnapPoint = makeMutable<number | null>(null);
 	const normX = makeMutable(0);
 	const normY = makeMutable(0);
 	const scale = makeMutable(1);
@@ -86,6 +115,35 @@ function createGestureBag(): GestureStoreMap {
 			normScale: makeMutable(0),
 			rotation: makeMutable(0),
 		},
+		internal: {
+			progressBaseline,
+			progressDeltaX,
+			progressDeltaY,
+			lockedSnapPoint,
+			snapshot: {
+				x: makeMutable(0),
+				y: makeMutable(0),
+				normX: makeMutable(0),
+				normY: makeMutable(0),
+				velocity: makeMutable(0),
+				scale: makeMutable(1),
+				normScale: makeMutable(0),
+				focalX: makeMutable(0),
+				focalY: makeMutable(0),
+				rotation: makeMutable(0),
+				raw: {
+					x: makeMutable(0),
+					y: makeMutable(0),
+					normX: makeMutable(0),
+					normY: makeMutable(0),
+					scale: makeMutable(1),
+					normScale: makeMutable(0),
+					rotation: makeMutable(0),
+				},
+				active: makeMutable<ActiveGesture | null>(null),
+				direction: makeMutable<ResolvedPanGestureDirection | null>(null),
+			},
+		},
 		dismissing,
 		dragging,
 		settling,
@@ -127,6 +185,29 @@ export const GestureStore = createStore<GestureStoreMap>({
 		cancelAnimation(bag.raw.scale);
 		cancelAnimation(bag.raw.normScale);
 		cancelAnimation(bag.raw.rotation);
+		cancelAnimation(bag.internal.progressBaseline);
+		cancelAnimation(bag.internal.progressDeltaX);
+		cancelAnimation(bag.internal.progressDeltaY);
+		cancelAnimation(bag.internal.lockedSnapPoint);
+		cancelAnimation(bag.internal.snapshot.x);
+		cancelAnimation(bag.internal.snapshot.y);
+		cancelAnimation(bag.internal.snapshot.normX);
+		cancelAnimation(bag.internal.snapshot.normY);
+		cancelAnimation(bag.internal.snapshot.velocity);
+		cancelAnimation(bag.internal.snapshot.scale);
+		cancelAnimation(bag.internal.snapshot.normScale);
+		cancelAnimation(bag.internal.snapshot.focalX);
+		cancelAnimation(bag.internal.snapshot.focalY);
+		cancelAnimation(bag.internal.snapshot.rotation);
+		cancelAnimation(bag.internal.snapshot.raw.x);
+		cancelAnimation(bag.internal.snapshot.raw.y);
+		cancelAnimation(bag.internal.snapshot.raw.normX);
+		cancelAnimation(bag.internal.snapshot.raw.normY);
+		cancelAnimation(bag.internal.snapshot.raw.scale);
+		cancelAnimation(bag.internal.snapshot.raw.normScale);
+		cancelAnimation(bag.internal.snapshot.raw.rotation);
+		cancelAnimation(bag.internal.snapshot.active);
+		cancelAnimation(bag.internal.snapshot.direction);
 		cancelAnimation(bag.dismissing);
 		cancelAnimation(bag.dragging);
 		cancelAnimation(bag.settling);

package/src/shared/stores/scroll.store.ts

@@ -3,23 +3,96 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import type { ScrollGestureState } from "../types/gesture.types";
+import type {
+	ScrollGestureAxis,
+	ScrollGestureState,
+	ScrollMetadataState,
+} from "../types/gesture.types";
+import type { ScreenKey } from "../types/screen.types";
 import { createStore } from "../utils/create-store";
 
 export type ScrollStoreMap = {
-	state: SharedValue<ScrollGestureState | null>;
+	coordination: SharedValue<ScrollGestureState | null>;
+	metadata: SharedValue<ScrollMetadataState | null>;
+};
+
+const metadataWriters: Record<
+	ScreenKey,
+	Partial<Record<ScrollGestureAxis, string>>
+> = {};
+
+let nextMetadataWriterId = 0;
+
+const createMetadataWriterId = () => {
+	nextMetadataWriterId += 1;
+	return `scroll-metadata-${nextMetadataWriterId}`;
+};
+
+const claimMetadataWriter = (
+	routeKey: ScreenKey,
+	axis: ScrollGestureAxis,
+	writerId: string,
+): boolean => {
+	const writers = metadataWriters[routeKey] ?? {};
+	metadataWriters[routeKey] = writers;
+
+	if (!writers[axis]) {
+		writers[axis] = writerId;
+	}
+
+	return writers[axis] === writerId;
+};
+
+const releaseMetadataWriter = (
+	routeKey: ScreenKey,
+	axis: ScrollGestureAxis,
+	writerId: string,
+): boolean => {
+	const writers = metadataWriters[routeKey];
+	if (!writers || writers[axis] !== writerId) return false;
+
+	delete writers[axis];
+
+	if (!writers.vertical && !writers.horizontal) {
+		delete metadataWriters[routeKey];
+	}
+
+	return true;
+};
+
+const hasMetadataWriters = (routeKey: ScreenKey): boolean => {
+	const writers = metadataWriters[routeKey];
+	return Boolean(writers?.vertical || writers?.horizontal);
+};
+
+const clearMetadataWriters = (routeKey: ScreenKey) => {
+	delete metadataWriters[routeKey];
 };
 
 /**
  * Route-keyed scroll geometry used by gesture activation and bounds measurement.
- * The state tracks coordinated ScrollView offsets and dimensions so consumers
- * can reason about overscroll without coupling to a specific scroll component.
+ * Coordination tracks gesture-owner scoped ScrollView offsets and dimensions;
+ * metadata tracks screen-scoped scroll values exposed to animation consumers.
  */
-export const ScrollStore = createStore<ScrollStoreMap>({
+const scrollStore = createStore<ScrollStoreMap>({
 	createBag: () => ({
-		state: makeMutable<ScrollGestureState | null>(null),
+		coordination: makeMutable<ScrollGestureState | null>(null),
+		metadata: makeMutable<ScrollMetadataState | null>(null),
 	}),
 	disposeBag: (bag) => {
-		cancelAnimation(bag.state);
+		cancelAnimation(bag.coordination);
+		cancelAnimation(bag.metadata);
 	},
 });
+
+export const ScrollStore = {
+	...scrollStore,
+	createMetadataWriterId,
+	claimMetadataWriter,
+	releaseMetadataWriter,
+	hasMetadataWriters,
+	clearBag(routeKey: ScreenKey) {
+		clearMetadataWriters(routeKey);
+		scrollStore.clearBag(routeKey);
+	},
+};

package/src/shared/types/animation.types.ts

@@ -48,6 +48,15 @@ export type ScreenTransitionState = {
 	 */
 	progress: number;
 
+	/**
+	 * Transition progress without live gesture contribution.
+	 *
+	 * `progress` is always the visual progress, including live pan or pinch
+	 * movement. Use `transitionProgress` when an interpolator needs the committed
+	 * transition progress as if the current gesture were not active.
+	 */
+	transitionProgress: number;
+
 	/**
 	 * Whether this screen is in the process of being dismissed.
 	 * - `0`: Screen is opening or active

package/src/shared/types/bounds.types.ts

@@ -98,11 +98,13 @@ export type BoundsNavigationZoomOptions = {
 	 */
 	velocityDepth?: number;
 	/**
-	 * Whether gesture displacement should drive transition progress or remain as
-	 * freeform gesture values. Zoom defaults to `"freeform"` so drag can move the
-	 * content without owning the whole screen progress.
+	 * Deprecated compatibility option.
 	 *
-	 * @default "freeform"
+	 * Gesture movement now always contributes to `progress`; use `transitionProgress`
+	 * when a recipe needs transition progress without live gesture contribution.
+	 * The zoom helper no longer reads this option.
+	 *
+	 * @deprecated Use `transitionProgress` from interpolation state instead.
 	 */
 	gestureProgressMode?: GestureProgressMode;
 	/**
@@ -224,11 +226,13 @@ export type BoundsNavigationRevealOptions = {
 	 */
 	velocityDepth?: number;
 	/**
-	 * Whether gesture displacement should drive transition progress or remain as
-	 * freeform gesture values. Reveal defaults to `"freeform"` so drag can move
-	 * the masked container without owning the whole screen progress.
+	 * Deprecated compatibility option.
+	 *
+	 * Gesture movement now always contributes to `progress`; use `transitionProgress`
+	 * when a recipe needs transition progress without live gesture contribution.
+	 * The reveal helper no longer reads this option.
 	 *
-	 * @default "freeform"
+	 * @deprecated Use `transitionProgress` from interpolation state instead.
 	 */
 	gestureProgressMode?: GestureProgressMode;
 	/**

package/src/shared/types/gesture.types.ts

@@ -20,18 +20,35 @@ export type GestureProgressMode = "progress-driven" | "freeform";
 
 export type SnapPanAxis = "horizontal" | "vertical";
 
+/**
+ * Axis reported by a transition-aware scrollable.
+ */
 export type ScrollGestureAxis = "vertical" | "horizontal";
 
+/**
+ * Scroll geometry for one axis of a transition-aware scrollable.
+ */
 export type ScrollGestureAxisState = {
 	offset: number;
 	contentSize: number;
 	layoutSize: number;
+	isTouched: boolean;
 };
 
+/**
+ * Scroll metadata exposed through screen transition layouts.
+ */
+export type ScrollMetadataState = {
+	vertical: ScrollGestureAxisState | null;
+	horizontal: ScrollGestureAxisState | null;
+};
+
+/**
+ * Scroll geometry used by gesture coordination.
+ */
 export type ScrollGestureState = {
 	vertical: ScrollGestureAxisState;
 	horizontal: ScrollGestureAxisState;
-	isTouched: boolean;
 };
 
 export type SnapPanAxisConfig = {
@@ -117,6 +134,36 @@ export type RawGestureValues = {
 	rotation: number;
 };
 
+/**
+ * Gesture values used when a release hands off into a dismiss animation.
+ *
+ * These match live gesture values while a screen is not dismissing, then read
+ * from the release snapshot while dismissal is in flight.
+ */
+export type GestureHandoffValues = {
+	x: number;
+	y: number;
+	normX: number;
+	normY: number;
+	velocity: number;
+	scale: number;
+	normScale: number;
+	focalX: number;
+	focalY: number;
+	rotation: number;
+	raw: RawGestureValues;
+	/**
+	 * The gesture associated with the handoff values.
+	 */
+	active: ActiveGesture | null;
+	/**
+	 * The pan direction associated with the handoff values.
+	 *
+	 * @deprecated Use `active` instead.
+	 */
+	direction: ResolvedPanGestureDirection | null;
+};
+
 export type GestureValues = {
 	/**
 	 * The live horizontal translation of the gesture.
@@ -137,9 +184,6 @@ export type GestureValues = {
 	/**
 	 * A 0-1 scalar derived from the pan velocity magnitude, normalized against
 	 * a screen-relative full-flick threshold.
-	 *
-	 * This is live while dragging, frozen at release during dismiss animations,
-	 * and reset to 0 while idle or settling from a cancelled gesture.
 	 */
 	velocity: number;
 	/**
@@ -166,6 +210,24 @@ export type GestureValues = {
 	 * Physical gesture values before `gestureSensitivity` is applied.
 	 */
 	raw: RawGestureValues;
+	/**
+	 * The gesture that is currently active.
+	 */
+	active: ActiveGesture | null;
+	/**
+	 * The initial pan direction that activated the gesture.
+	 *
+	 * @deprecated Use `active` instead.
+	 */
+	direction: ResolvedPanGestureDirection | null;
+	/**
+	 * Gesture values latched at the release boundary for animation handoff.
+	 *
+	 * While dragging, these values match the live gesture values. During a
+	 * dismissing release, they read from the release snapshot so live gesture
+	 * values can reset without breaking handoff animations.
+	 */
+	handoff: GestureHandoffValues;
 	/**
 	 * A flag indicating if the screen is in the process of dismissing (0 or 1).
 	 */
@@ -178,17 +240,6 @@ export type GestureValues = {
 	 * A flag indicating if released gesture values are animating back to neutral.
 	 */
 	settling: number;
-	/**
-	 * The gesture that is currently active.
-	 */
-	active: ActiveGesture | null;
-	/**
-	 * The initial pan direction that activated the gesture.
-	 *
-	 * @deprecated Use `active` instead.
-	 */
-	direction: ResolvedPanGestureDirection | null;
-
 	/** @deprecated Use `normX` instead. */
 	normalizedX: number;
 	/** @deprecated Use `normY` instead. */