react-native-screen-transitions 4.0.0-alpha.0 → 4.0.0-alpha.2

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

@@ -4,7 +4,6 @@ import type {
 	GestureUpdateEvent,
 	PanGestureHandlerEventPayload,
 	PinchGestureHandlerEventPayload,
-	RotationGestureHandlerEventPayload,
 } from "react-native-gesture-handler";
 import type { SharedValue } from "react-native-reanimated";
 import type { AnimationStoreMap } from "../../../stores/animation.store";
@@ -33,7 +32,6 @@ import type { EffectiveSnapPointsResult } from "./shared/snap-points";
 
 export type PanGesture = ReturnType<typeof Gesture.Pan>;
 export type PinchGesture = ReturnType<typeof Gesture.Pinch>;
-export type RotationGesture = ReturnType<typeof Gesture.Rotation>;
 export type ComposedGesture = ReturnType<typeof Gesture.Simultaneous>;
 
 export type PanGestureEvent =
@@ -44,10 +42,6 @@ export type PinchGestureEvent =
 	| GestureUpdateEvent<PinchGestureHandlerEventPayload>
 	| GestureStateChangeEvent<PinchGestureHandlerEventPayload>;
 
-export type RotationGestureEvent =
-	| GestureUpdateEvent<RotationGestureHandlerEventPayload>
-	| GestureStateChangeEvent<RotationGestureHandlerEventPayload>;
-
 /** Gesture that owns navigation release for the current simultaneous composition. */
 export type GestureCompositionOwner = "pan" | "pinch" | null;
 
@@ -82,7 +76,6 @@ export interface GestureContextType {
 	detectorGesture: ComposedGesture;
 	panGesture: PanGesture;
 	pinchGesture: PinchGesture;
-	rotationGesture: RotationGesture;
 	scrollState: SharedValue<ScrollGestureState | null>;
 	gestureContext: GestureContextType | null;
 	claimedDirections: ClaimedDirections;
@@ -156,8 +149,6 @@ export type PanGestureRuntime = GestureRuntime<PanGesturePolicy>;
 
 export type PinchGestureRuntime = GestureRuntime<PinchGesturePolicy>;
 
-export type RotationGestureRuntime = GestureRuntime<PinchGesturePolicy>;
-
 export interface GestureDimensions {
 	width: number;
 	height: number;
@@ -221,8 +212,3 @@ export interface PinchBehavior {
 	onUpdate: (event: PinchGestureEvent) => void;
 	onEnd: (event: PinchGestureEvent) => void;
 }
-
-export interface RotationBehavior {
-	onStart: () => void;
-	onUpdate: (event: RotationGestureEvent) => void;
-}

package/src/providers/screen/styles/helpers/transition-visual-state.ts

@@ -0,0 +1,44 @@
+/**
+ * Visual lifecycle boundaries use the internal directional clock rather than
+ * physical transition progress, which may overshoot or revisit an endpoint.
+ */
+export const hasOpenTransitionStarted = ({
+	pendingLifecycleStartBlockCount,
+	animationProgress,
+}: {
+	pendingLifecycleStartBlockCount: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+	return pendingLifecycleStartBlockCount === 0 && animationProgress > 0;
+};
+
+export const isOpenTransitionBlocked = ({
+	opening,
+	pendingLifecycleStartBlockCount,
+	animationProgress,
+}: {
+	opening: boolean;
+	pendingLifecycleStartBlockCount: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+	return (
+		opening &&
+		!hasOpenTransitionStarted({
+			pendingLifecycleStartBlockCount,
+			animationProgress,
+		})
+	);
+};
+
+export const hasCloseTransitionFinished = ({
+	closing,
+	animationProgress,
+}: {
+	closing: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+	return !!closing && animationProgress === 0;
+};

package/src/providers/screen/styles/helpers/visibility-gate.ts

@@ -1,11 +1,15 @@
 import { LifecycleTransitionRequestKind } from "../../../../stores/system.store";
+import {
+	hasOpenTransitionStarted,
+	isOpenTransitionBlocked,
+} from "./transition-visual-state";
 
 type ScreenVisibilityGateState = {
 	isFloatingOverlay?: boolean;
 	hasVisibilityGateOpened: boolean;
 	pendingLifecycleStartBlockCount: number;
 	pendingLifecycleRequestKind: LifecycleTransitionRequestKind;
-	progress: number;
+	animationProgress: number;
 	entering: number;
 };
 
@@ -19,7 +23,7 @@ export const resolveScreenVisibilityGate = ({
 	hasVisibilityGateOpened,
 	pendingLifecycleStartBlockCount,
 	pendingLifecycleRequestKind,
-	progress,
+	animationProgress,
 	entering,
 }: ScreenVisibilityGateState): ScreenVisibilityGateDecision => {
 	"worklet";
@@ -30,16 +34,22 @@ export const resolveScreenVisibilityGate = ({
 		};
 	}
 
-	const hasPendingLifecycleBlock = pendingLifecycleStartBlockCount > 0;
 	const isPendingOpen =
 		pendingLifecycleRequestKind === LifecycleTransitionRequestKind.Open;
 	const isOpening = isPendingOpen || !!entering;
-	const isWaitingForOpenToStart = progress <= 0;
-	const shouldBlock =
-		(hasPendingLifecycleBlock || isWaitingForOpenToStart) && isOpening;
+	const shouldBlock = isOpenTransitionBlocked({
+		opening: isOpening,
+		pendingLifecycleStartBlockCount,
+		animationProgress,
+	});
 
 	return {
 		shouldBlock,
-		shouldOpenGate: !shouldBlock && progress > 0,
+		shouldOpenGate:
+			!shouldBlock &&
+			hasOpenTransitionStarted({
+				pendingLifecycleStartBlockCount,
+				animationProgress,
+			}),
 	};
 };

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

@@ -25,9 +25,12 @@ import {
 } from "../../options";
 import { collectInterpolatorSharedValues } from "../helpers/collect-interpolator-shared-values";
 import { normalizeSlots } from "../helpers/normalize-slots";
-import { isOpeningBeforeStart } from "../helpers/opening-phase";
 import type { LocalStyleLayers } from "../helpers/resolve-slot-styles";
 import { stripInterpolatorOptions } from "../helpers/strip-interpolator-options";
+import {
+	hasCloseTransitionFinished,
+	isOpenTransitionBlocked,
+} from "../helpers/transition-visual-state";
 
 const NO_STYLE_LAYERS: LocalStyleLayers = [];
 
@@ -157,12 +160,13 @@ export const useInterpolatedStylesMap = () => {
 	);
 
 	const activeScreenKey = nextScreenKey ?? currentScreenKey;
+	const { closing: activeClosing, entering: activeEntering } =
+		AnimationStore.getBag(activeScreenKey);
 	const {
-		entering: activeEntering,
-		transitionProgress: activeTransitionProgress,
-	} = AnimationStore.getBag(activeScreenKey);
-	const { pendingLifecycleRequestKind: activePendingLifecycleRequestKind } =
-		SystemStore.getBag(activeScreenKey);
+		animationProgress: activeAnimationProgress,
+		pendingLifecycleRequestKind: activePendingLifecycleRequestKind,
+		pendingLifecycleStartBlockCount: activePendingLifecycleStartBlockCount,
+	} = SystemStore.getBag(activeScreenKey);
 
 	const isGesturingDuringCloseAnimation = useSharedValue(false);
 
@@ -194,22 +198,33 @@ export const useInterpolatedStylesMap = () => {
 		const isInGestureMode =
 			!!isDragging || isGesturingDuringCloseAnimation.get();
 
-		// The current screen keeps interpolator ownership until the next screen is
-		// genuinely live: never during a gesture-driven close, never before a next
-		// interpolator exists, and never in the next screen's pre-start window
-		// (entering, but no transformed frame yet). Only then does "next" take over.
+		// Interpolator ownership changes only at visual boundaries on the UI thread:
+		// the next screen attaches after its blockers clear and progress starts, then
+		// detaches once its closing progress has committed at zero. The downstream
+		// resolver sees the owner disappear in this same graph and resets its styles
+		// without waiting for React to remove the screen.
 		const isPendingOpen =
 			activePendingLifecycleRequestKind.get() ===
 			LifecycleTransitionRequestKind.Open;
 		const activeOpening = isPendingOpen || !!activeEntering.get();
+		const isOpeningBlocked = isOpenTransitionBlocked({
+			opening: activeOpening,
+			pendingLifecycleStartBlockCount:
+				activePendingLifecycleStartBlockCount.get(),
+			animationProgress: activeAnimationProgress.get(),
+		});
+		const hasCloseFinished = hasCloseTransitionFinished({
+			closing: activeClosing.get(),
+			animationProgress: activeAnimationProgress.get(),
+		});
 		const currentOwnsInterpolator =
 			isInGestureMode ||
 			!nextInterpolator ||
-			isOpeningBeforeStart(
-				activeOpening ? 1 : 0,
-				activeTransitionProgress.get(),
-			);
-		nextInterpolatorReady.set(currentOwnsInterpolator ? 0 : 1);
+			isOpeningBlocked ||
+			hasCloseFinished;
+		const nextReady = currentOwnsInterpolator ? 0 : 1;
+
+		nextInterpolatorReady.set(nextReady);
 
 		const interpolatorOptionsOwner = currentOwnsInterpolator
 			? "current"

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

@@ -9,15 +9,18 @@ import { AnimationStore } from "../../../../stores/animation.store";
 import { SystemStore } from "../../../../stores/system.store";
 import { getVisibilityBlockOffset } from "../../../../utils/visibility-block-offset";
 import { useDescriptorDerivations } from "../../descriptors";
+import { hasCloseTransitionFinished } from "../helpers/transition-visual-state";
 import { resolveScreenVisibilityGate } from "../helpers/visibility-gate";
 
 export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 	const { height } = useWindowDimensions();
 	const { currentScreenKey } = useDescriptorDerivations();
-	const { closing, entering, progressAnimating, transitionProgress } =
-		AnimationStore.getBag(currentScreenKey);
-	const { pendingLifecycleStartBlockCount, pendingLifecycleRequestKind } =
-		SystemStore.getBag(currentScreenKey);
+	const { closing, entering } = AnimationStore.getBag(currentScreenKey);
+	const {
+		animationProgress,
+		pendingLifecycleStartBlockCount,
+		pendingLifecycleRequestKind,
+	} = SystemStore.getBag(currentScreenKey);
 
 	const hasVisibilityGateOpened = useSharedValue(false);
 	const shouldBlockVisibility = useSharedValue(!isFloatingOverlay);
@@ -31,7 +34,7 @@ export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 				hasVisibilityGateOpened: hasVisibilityGateOpened.get(),
 				pendingLifecycleStartBlockCount: pendingLifecycleStartBlockCount.get(),
 				pendingLifecycleRequestKind: pendingLifecycleRequestKind.get(),
-				progress: transitionProgress.get(),
+				animationProgress: animationProgress.get(),
 				entering: entering.get(),
 			});
 		},
@@ -49,14 +52,12 @@ export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 	const animatedStyle = useAnimatedStyle(() => {
 		"worklet";
 		const offset = getVisibilityBlockOffset(height);
-		// Keep opacity out of normal rendering so effects such as Liquid Glass
-		// retain native compositing. Once closing has fully finished, hiding the
-		// outgoing screen lets the handoff settle before React removes its host.
-		const shouldHideClosedScreen =
-			closing.get() === 1 &&
-			transitionProgress.get() <= 0 &&
-			progressAnimating.get() === 0;
-
+		// Hide the outgoing screen after its visual close while React removes its
+		// host asynchronously.
+		const shouldHideClosedScreen = hasCloseTransitionFinished({
+			closing: closing.get(),
+			animationProgress: animationProgress.get(),
+		});
 		if (shouldHideClosedScreen) {
 			return {
 				opacity: 0,

package/src/stores/bounds/internals/links.ts

@@ -215,11 +215,12 @@ const writeDestination = (
 	bounds: MeasuredDimensions,
 	styles: StyleProps,
 	group?: GroupKey,
+	runtimeFlags: BoundaryRuntimeFlags = {},
 ) => {
 	"worklet";
 	const existingLink = getPairLink(state, pairKey, linkKey);
 
-	const destination = createLinkSide(screenKey, bounds, styles);
+	const destination = createLinkSide(screenKey, bounds, styles, runtimeFlags);
 	const link =
 		existingLink ??
 		({
@@ -296,12 +297,22 @@ function setDestination(
 	bounds: MeasuredDimensions,
 	styles: StyleProps = {},
 	group?: GroupKey,
+	runtimeFlags: BoundaryRuntimeFlags = {},
 ) {
 	"worklet";
 	pairs.modify(<T extends LinkPairsState>(state: T): T => {
 		"worklet";
 		const linkKey = getLinkKeyFromTag(tag);
-		writeDestination(state, pairKey, linkKey, screenKey, bounds, styles, group);
+		writeDestination(
+			state,
+			pairKey,
+			linkKey,
+			screenKey,
+			bounds,
+			styles,
+			group,
+			runtimeFlags,
+		);
 
 		return state;
 	});

package/src/stores/scroll.store.ts

@@ -137,6 +137,29 @@ export const getClampedScrollAxisDelta = (
 	return currentOffset - capturedOffset;
 };
 
+/**
+ * Visual scroll travel from a bounds snapshot normalized to its at-rest
+ * position. The captured side is clamped because measurement removes transient
+ * rubber-band displacement; the current side stays raw so consumers can follow
+ * the position that is actually visible on iOS.
+ */
+export const getVisualScrollAxisDelta = (
+	current: ScrollMetadataState | null | undefined,
+	captured: ScrollMetadataState | null | undefined,
+	axis: ScrollGestureAxis,
+): number => {
+	"worklet";
+
+	const currentAxisState = current?.[axis];
+	const capturedOffset = clampScrollAxisOffset(captured?.[axis]);
+
+	if (!currentAxisState || capturedOffset === null) {
+		return 0;
+	}
+
+	return currentAxisState.offset - capturedOffset;
+};
+
 /**
  * Route-keyed scroll geometry used by gesture activation and bounds measurement.
  * Coordination tracks gesture-owner scoped ScrollView offsets and dimensions;

package/src/stores/system.store.ts

@@ -16,6 +16,12 @@ export enum LifecycleTransitionRequestKind {
 type SystemStoreState = {
 	targetProgress: SharedValue<number>;
 
+	/**
+	 * Directional linear clock for the active progress animation. Increasing
+	 * animations run 0 -> 1; decreasing animations run 1 -> 0.
+	 */
+	animationProgress: SharedValue<number>;
+
 	/**
 	 * Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured.
 	 */
@@ -67,6 +73,7 @@ export type SystemStoreMap = SystemStoreState & {
 export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 	createBag: () => ({
 		targetProgress: makeMutable(1),
+		animationProgress: makeMutable(0),
 		resolvedAutoSnapPoint: makeMutable(-1),
 		measuredContentLayout: makeMutable<Layout | null>(null),
 		pendingLifecycleRequestKind: makeMutable<LifecycleTransitionRequestKind>(
@@ -77,6 +84,7 @@ export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 	}),
 	disposeBag: (bag) => {
 		cancelAnimation(bag.targetProgress);
+		cancelAnimation(bag.animationProgress);
 		cancelAnimation(bag.resolvedAutoSnapPoint);
 		cancelAnimation(bag.measuredContentLayout);
 		cancelAnimation(bag.pendingLifecycleRequestKind);

package/src/utils/animation/animate-to-progress.ts

@@ -17,6 +17,7 @@ interface AnimateToProgressProps {
 	onAnimationFinish?: (finished: boolean) => void;
 	animations: AnimationStoreMap;
 	targetProgress: SharedValue<number>;
+	animationProgress: SharedValue<number>;
 	emitWillAnimate?: boolean;
 	markEntering?: boolean;
 	/** Optional initial velocity for spring-based progress (units: progress/sec). */
@@ -36,17 +37,31 @@ const setTransitionLifecycleFlags = (
 		return;
 	}
 
+	animations.closing.set(FALSE);
+
 	if (markEntering) {
 		animations.entering.set(TRUE);
 	}
 };
 
+export const resolveAnimationProgressRange = (
+	currentProgress: number,
+	targetProgress: number,
+) => {
+	"worklet";
+	return {
+		from: Math.min(1, Math.max(0, currentProgress)),
+		to: targetProgress,
+	};
+};
+
 export const animateToProgress = ({
 	target,
 	spec,
 	onAnimationFinish,
 	animations,
 	targetProgress,
+	animationProgress,
 	emitWillAnimate = true,
 	markEntering = true,
 	initialVelocity,
@@ -78,7 +93,11 @@ export const animateToProgress = ({
 
 	const startAnimation = () => {
 		"worklet";
+		const { from: animationProgressFrom, to: animationProgressTo } =
+			resolveAnimationProgressRange(transitionProgress.get(), value);
+
 		targetProgress.set(value);
+		animationProgress.set(animationProgressFrom);
 
 		const shouldClearEnteringOnFinish =
 			!isClosing && (markEntering || entering.get());
@@ -89,6 +108,7 @@ export const animateToProgress = ({
 			progressAnimating.set(FALSE);
 			progressSettled.set(TRUE);
 			transitionProgress.set(value);
+			animationProgress.set(animationProgressTo);
 			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
 			}
@@ -102,43 +122,54 @@ export const animateToProgress = ({
 		progressAnimating.set(TRUE); //<-- Do not move this into the callback
 		progressSettled.set(FALSE);
 		transitionProgress.set(
-			animate(value, effectiveConfig, (state) => {
-				"worklet";
-				if (state.settled) {
-					progressSettled.set(TRUE);
-				}
+			animate(
+				value,
+				effectiveConfig,
+				(state) => {
+					"worklet";
+					if (state.settled) {
+						progressSettled.set(TRUE);
+					}
 
-				if (!state.finished) return;
+					if (!state.finished) return;
 
-				if (shouldClearEnteringOnFinish) {
-					entering.set(FALSE);
-				}
+					animationProgress.set(animationProgressTo);
 
-				if (isClosing) {
-					progressAnimating.set(FALSE);
+					if (shouldClearEnteringOnFinish) {
+						entering.set(FALSE);
+					}
 
-					if (onAnimationFinish) {
-						// Paint the terminal UI-thread host/style state before React
-						// removes the closing route and its native portal host.
-						requestAnimationFrame(() => {
-							"worklet";
+					if (isClosing) {
+						progressAnimating.set(FALSE);
+
+						if (onAnimationFinish) {
+							// Paint the terminal UI-thread host/style state before React
+							// removes the closing route and its native portal host.
 							requestAnimationFrame(() => {
 								"worklet";
-								scheduleOnRN(onAnimationFinish, state.finished);
+								requestAnimationFrame(() => {
+									"worklet";
+									scheduleOnRN(onAnimationFinish, state.finished);
+								});
 							});
+						}
+					} else {
+						if (onAnimationFinish) {
+							scheduleOnRN(onAnimationFinish, state.finished);
+						}
+
+						// Delay clearing progress animation by one frame to ensure final frame is painted
+						requestAnimationFrame(() => {
+							progressAnimating.set(FALSE);
 						});
 					}
-				} else {
-					if (onAnimationFinish) {
-						scheduleOnRN(onAnimationFinish, state.finished);
-					}
-
-					// Delay clearing progress animation by one frame to ensure final frame is painted
-					requestAnimationFrame(() => {
-						progressAnimating.set(FALSE);
-					});
-				}
-			}),
+				},
+				{
+					value: animationProgress,
+					from: animationProgressFrom,
+					to: animationProgressTo,
+				},
+			),
 		);
 	};
 

package/src/utils/animation/animate.ts

@@ -1,7 +1,7 @@
 import type { WithTimingConfig } from "react-native-reanimated";
 import { withTiming } from "react-native-reanimated";
 import { type SpringConfig, withInternalSpring } from "./spring";
-import type { AnimationStateCallback } from "./state";
+import type { AnimationProgressDriver, AnimationStateCallback } from "./state";
 
 export type TimingAnimationConfig = WithTimingConfig;
 export type SpringAnimationConfig = SpringConfig;
@@ -9,6 +9,11 @@ export type ScreenAnimationConfig =
 	| SpringAnimationConfig
 	| TimingAnimationConfig;
 
+const linearEasing = (progress: number) => {
+	"worklet";
+	return progress;
+};
+
 export const isSpringAnimationConfig = (
 	config: ScreenAnimationConfig | undefined,
 ): config is SpringAnimationConfig => {
@@ -33,10 +38,21 @@ export const animate = (
 	toValue: number,
 	config?: ScreenAnimationConfig,
 	callback?: AnimationStateCallback,
+	animationProgress?: AnimationProgressDriver,
 ) => {
 	"worklet";
 
 	if (!isSpringAnimationConfig(config)) {
+		if (animationProgress) {
+			animationProgress.value.set(animationProgress.from);
+			animationProgress.value.set(
+				withTiming(animationProgress.to, {
+					...config,
+					easing: linearEasing,
+				}),
+			);
+		}
+
 		return withTiming(toValue, config, (finished) => {
 			"worklet";
 			const didFinish = finished === true;
@@ -47,5 +63,5 @@ export const animate = (
 		});
 	}
 
-	return withInternalSpring(toValue, config, callback);
+	return withInternalSpring(toValue, config, callback, animationProgress);
 };