react-native-screen-transitions 3.4.0-alpha.2 → 3.4.0-alpha.4

package/src/shared/components/screen-container/hooks/use-content-layout.ts

@@ -6,6 +6,7 @@ import {
 	useDescriptors,
 } from "../../../providers/screen/descriptors";
 import { AnimationStore } from "../../../stores/animation.store";
+import { SystemStore } from "../../../stores/system.store";
 import { animateToProgress } from "../../../utils/animation/animate-to-progress";
 
 export function useContentLayout() {
@@ -13,15 +14,19 @@ export function useContentLayout() {
 	const { isFirstKey } = useDescriptorDerivations();
 	const { height: screenHeight } = useWindowDimensions();
 	const routeKey = current.route.key;
-	const animations = AnimationStore.getRouteAnimations(routeKey);
-	const autoSnapPointValue = AnimationStore.getAnimation(
+	const animations = AnimationStore.getBag(routeKey);
+	const targetProgressValue = SystemStore.getValue(routeKey, "targetProgress");
+	const resolvedAutoSnapPointValue = SystemStore.getValue(
 		routeKey,
-		"autoSnapPoint",
+		"resolvedAutoSnapPoint",
 	);
-	const contentLayoutValue = AnimationStore.getAnimation(
+	const measuredContentLayoutValue = SystemStore.getValue(
 		routeKey,
-		"contentLayout",
+		"measuredContentLayout",
 	);
+	const experimental_animateOnInitialMount =
+		current.options.experimental_animateOnInitialMount;
+	const transitionSpec = current.options.transitionSpec;
 
 	return useCallback(
 		(event: LayoutChangeEvent) => {
@@ -29,54 +34,48 @@ export function useContentLayout() {
 			if (width <= 0 || height <= 0) return;
 
 			const fraction = Math.min(height / screenHeight, 1);
-			const transitionSpec = current.options.transitionSpec;
 
-			runOnUI(
-				(
-					nextWidth: number,
-					nextHeight: number,
-					nextFraction: number,
-					isInitialScreen: boolean,
-					spec: typeof transitionSpec,
-				) => {
-					"worklet";
-					contentLayoutValue.value = {
-						width: nextWidth,
-						height: nextHeight,
-					};
+			runOnUI((nextWidth: number, nextHeight: number, nextFraction: number) => {
+				"worklet";
+				measuredContentLayoutValue.value = {
+					width: nextWidth,
+					height: nextHeight,
+				};
 
-					const isFirstMeasurement = autoSnapPointValue.value <= 0;
-					autoSnapPointValue.value = nextFraction;
+				const isFirstMeasurement = resolvedAutoSnapPointValue.value <= 0;
+				resolvedAutoSnapPointValue.value = nextFraction;
 
-					if (
-						!isFirstMeasurement ||
-						animations.progress.value !== 0 ||
-						animations.animating.value !== 0
-					) {
-						return;
-					}
+				if (
+					!isFirstMeasurement ||
+					animations.progress.value !== 0 ||
+					animations.animating.value !== 0
+				) {
+					return;
+				}
 
-					if (isInitialScreen) {
-						animations.targetProgress.value = nextFraction;
-						animations.progress.value = nextFraction;
-						return;
-					}
+				if (isFirstKey && !experimental_animateOnInitialMount) {
+					targetProgressValue.value = nextFraction;
+					animations.progress.value = nextFraction;
+					return;
+				}
 
-					animateToProgress({
-						target: nextFraction,
-						spec,
-						animations,
-					});
-				},
-			)(width, height, fraction, isFirstKey, transitionSpec);
+				animateToProgress({
+					target: nextFraction,
+					spec: transitionSpec,
+					animations,
+					targetProgress: targetProgressValue,
+				});
+			})(width, height, fraction);
 		},
 		[
 			animations,
-			autoSnapPointValue,
-			contentLayoutValue,
-			current.options.transitionSpec,
+			targetProgressValue,
+			resolvedAutoSnapPointValue,
+			measuredContentLayoutValue,
 			isFirstKey,
 			screenHeight,
+			experimental_animateOnInitialMount,
+			transitionSpec,
 		],
 	);
 }

package/src/shared/components/screen-container/index.tsx

@@ -1,5 +1,6 @@
 import { memo } from "react";
 import { StyleSheet, View } from "react-native";
+import { DeferredVisibilityHost } from "./deferred-visibility-host";
 import { useBackdropPointerEvents } from "./hooks/use-backdrop-pointer-events";
 import { BackdropLayer } from "./layers/backdrop";
 import { ContentLayer } from "./layers/content";
@@ -13,8 +14,10 @@ export const ScreenContainer = memo(({ children }: Props) => {
 
 	return (
 		<View style={styles.container} pointerEvents={pointerEvents}>
-			<BackdropLayer />
-			<ContentLayer>{children}</ContentLayer>
+			<DeferredVisibilityHost>
+				<BackdropLayer />
+				<ContentLayer>{children}</ContentLayer>
+			</DeferredVisibilityHost>
 		</View>
 	);
 });

package/src/shared/components/screen-container/layers/backdrop.tsx

@@ -12,6 +12,7 @@ import { useDescriptors } from "../../../providers/screen/descriptors";
 import { useScreenStyles } from "../../../providers/screen/styles.provider";
 import { AnimationStore } from "../../../stores/animation.store";
 import { GestureStore } from "../../../stores/gesture.store";
+import { SystemStore } from "../../../stores/system.store";
 import { animateToProgress } from "../../../utils/animation/animate-to-progress";
 import { findCollapseTarget } from "../../../utils/gesture/find-collapse-target";
 import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
@@ -24,10 +25,11 @@ export const BackdropLayer = memo(function BackdropLayer() {
 
 	const BackdropComponent = current.options.backdropComponent;
 	const routeKey = current.route.key;
-	const animations = AnimationStore.getRouteAnimations(routeKey);
-	const autoSnapPointValue = AnimationStore.getAnimation(
+	const animations = AnimationStore.getBag(routeKey);
+	const targetProgressValue = SystemStore.getValue(routeKey, "targetProgress");
+	const resolvedAutoSnapPointValue = SystemStore.getValue(
 		routeKey,
-		"autoSnapPoint",
+		"resolvedAutoSnapPoint",
 	);
 
 	const AnimatedBackdropComponent = useMemo(
@@ -53,13 +55,15 @@ export const BackdropLayer = memo(function BackdropLayer() {
 				return;
 			}
 
-			const gestures = GestureStore.getRouteGestures(routeKey);
+			const gestures = GestureStore.getBag(routeKey);
 			const transitionSpec = current.options.transitionSpec;
 
 			runOnUI(() => {
 				"worklet";
 				const resolvedSnaps = rawSnapPoints
-					.map((point) => (point === "auto" ? autoSnapPointValue.value : point))
+					.map((point) =>
+						point === "auto" ? resolvedAutoSnapPointValue.value : point,
+					)
 					.filter((point): point is number => typeof point === "number");
 
 				const { target, shouldDismiss } = findCollapseTarget(
@@ -84,13 +88,15 @@ export const BackdropLayer = memo(function BackdropLayer() {
 					target,
 					spec,
 					animations,
+					targetProgress: targetProgressValue,
 					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
 				});
 			})();
 		}
 	}, [
 		animations,
-		autoSnapPointValue,
+		targetProgressValue,
+		resolvedAutoSnapPointValue,
 		backdropBehavior,
 		current,
 		dismissScreen,

package/src/shared/components/screen-container/layers/content.tsx

@@ -24,11 +24,14 @@ export const ContentLayer = memo(({ children }: Props) => {
 	const { stylesMap } = useScreenStyles();
 	const { current } = useDescriptors();
 	const { pointerEvents, isBackdropActive } = useBackdropPointerEvents();
+
 	const gestureContext = useGestureContext();
 	const isNavigationMaskEnabled = resolveNavigationMaskEnabled(current.options);
 	const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
+
 	const hasAutoSnapPoint =
 		current.options.snapPoints?.includes("auto") ?? false;
+
 	const handleContentLayout = useContentLayout();
 
 	const animatedContentStyle = useAnimatedStyle(() => {

package/src/shared/components/screen-container/layers/maybe-masked-navigation-container.tsx

@@ -1,9 +1,9 @@
-import { memo, useEffect } from "react";
-import { Platform, StyleSheet, View, type ViewProps } from "react-native";
+import { memo, useCallback } from "react";
+import { StyleSheet, View, type ViewProps } from "react-native";
 import Animated, { useAnimatedStyle } from "react-native-reanimated";
 import {
-	NAVIGATION_CONTAINER_STYLE_ID,
-	NAVIGATION_MASK_STYLE_ID,
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_ELEMENT_STYLE_ID,
 	NO_STYLES,
 } from "../../../constants";
 import { useScreenStyles } from "../../../providers/screen/styles.provider";
@@ -24,22 +24,26 @@ try {
 }
 
 let hasWarnedMissingMaskedView = false;
-const IS_ANDROID = Platform.OS === "android";
 
 export const MaybeMaskedNavigationContainer = memo(
 	({ enabled, children, pointerEvents }: Props) => {
 		const { stylesMap } = useScreenStyles();
-		const animatedNavigationContainerStyle = useAnimatedStyle(() => {
+
+		const animatedNavigationMaskStyle = useAnimatedStyle(() => {
 			"worklet";
-			return stylesMap.value[NAVIGATION_CONTAINER_STYLE_ID]?.style || NO_STYLES;
+			return (
+				stylesMap.value[NAVIGATION_MASK_ELEMENT_STYLE_ID]?.style || NO_STYLES
+			);
 		});
 
-		const animatedNavigationMaskStyle = useAnimatedStyle(() => {
+		const animatedNavigationMaskContainerStyle = useAnimatedStyle(() => {
 			"worklet";
-			return stylesMap.value[NAVIGATION_MASK_STYLE_ID]?.style || NO_STYLES;
+			return (
+				stylesMap.value[NAVIGATION_MASK_CONTAINER_STYLE_ID]?.style || NO_STYLES
+			);
 		});
 
-		useEffect(() => {
+		const maybeLogWarning = useCallback(() => {
 			if (!enabled) return;
 			if (LazyMaskedView !== View) return;
 			if (hasWarnedMissingMaskedView) return;
@@ -50,24 +54,8 @@ export const MaybeMaskedNavigationContainer = memo(
 			);
 		}, [enabled]);
 
-		const navigationContainer = (
-			<Animated.View
-				style={[styles.navigationContainer, animatedNavigationContainerStyle]}
-				pointerEvents={pointerEvents}
-				collapsable={false}
-				renderToHardwareTextureAndroid={IS_ANDROID && !enabled}
-				needsOffscreenAlphaCompositing={IS_ANDROID && !enabled}
-			>
-				{children}
-			</Animated.View>
-		);
-
-		// Navigation zoom uses the root container transform even when the mask
-		// wrapper is disabled. Only the mask element itself is optional.
-		if (!enabled) return navigationContainer;
-
-		if (LazyMaskedView === View) {
-			return navigationContainer;
+		if (!enabled || LazyMaskedView === View) {
+			return children;
 		}
 
 		return (
@@ -81,8 +69,18 @@ export const MaybeMaskedNavigationContainer = memo(
 					/>
 				}
 				pointerEvents={pointerEvents}
+				onLayout={maybeLogWarning}
 			>
-				{navigationContainer}
+				<Animated.View
+					style={[
+						styles.navigationContainer,
+						animatedNavigationMaskContainerStyle,
+					]}
+					pointerEvents={pointerEvents}
+					collapsable={false}
+				>
+					{children}
+				</Animated.View>
 			</LazyMaskedView>
 		);
 	},
@@ -92,10 +90,10 @@ const styles = StyleSheet.create({
 	navigationMaskedRoot: {
 		flex: 1,
 	},
-	navigationMaskElement: {
-		backgroundColor: "white",
-	},
 	navigationContainer: {
 		flex: 1,
 	},
+	navigationMaskElement: {
+		backgroundColor: "white",
+	},
 });

package/src/shared/components/screen-lifecycle/hooks/use-close-transition/helpers/reset-stores-for-screen.ts

@@ -2,14 +2,16 @@ import { runOnUI } from "react-native-reanimated";
 import { AnimationStore } from "../../../../../stores/animation.store";
 import { BoundStore } from "../../../../../stores/bounds";
 import { GestureStore } from "../../../../../stores/gesture.store";
+import { SystemStore } from "../../../../../stores/system.store";
 
 export const resetStoresForScreen = (
 	routeKey: string,
 	isBranchScreen: boolean,
 	branchNavigatorKey?: string,
 ) => {
-	AnimationStore.clear(routeKey);
-	GestureStore.clear(routeKey);
+	AnimationStore.clearBag(routeKey);
+	GestureStore.clearBag(routeKey);
+	SystemStore.clearBag(routeKey);
 
 	runOnUI(() => {
 		"worklet";

package/src/shared/components/screen-lifecycle/hooks/use-close-transition/index.ts

@@ -1,6 +1,7 @@
 import { useLayoutEffect } from "react";
 import {
 	runOnJS,
+	type SharedValue,
 	useAnimatedReaction,
 	useDerivedValue,
 } from "react-native-reanimated";
@@ -23,6 +24,7 @@ import { useNavigatorHistoryRegistry } from "./helpers/use-navigator-history-reg
 interface CloseHookParams {
 	current: BaseDescriptor;
 	animations: AnimationStoreMap;
+	targetProgress: SharedValue<number>;
 	activate: () => void;
 	deactivate: () => void;
 	resetStores: () => void;
@@ -35,6 +37,7 @@ interface CloseHookParams {
 const useManagedClose = ({
 	current,
 	animations,
+	targetProgress,
 	activate,
 	deactivate,
 	resetStores,
@@ -66,6 +69,7 @@ const useManagedClose = ({
 				target: "close",
 				spec: transitionSpec,
 				animations,
+				targetProgress,
 				onAnimationFinish: handleCloseEnd,
 			});
 		},
@@ -78,6 +82,7 @@ const useManagedClose = ({
 const useNativeStackClose = ({
 	current,
 	animations,
+	targetProgress,
 	activate,
 	deactivate,
 	resetStores,
@@ -119,6 +124,7 @@ const useNativeStackClose = ({
 			target: "close",
 			spec: current.options.transitionSpec,
 			animations,
+			targetProgress,
 			onAnimationFinish: (finished: boolean) => {
 				deactivate();
 				if (finished) {
@@ -143,6 +149,7 @@ const useNativeStackClose = ({
 export function useCloseTransition(
 	current: BaseDescriptor,
 	animations: AnimationStoreMap,
+	targetProgress: SharedValue<number>,
 	activate: () => void,
 	deactivate: () => void,
 ) {
@@ -159,6 +166,7 @@ export function useCloseTransition(
 	const closeParams: CloseHookParams = {
 		current,
 		animations,
+		targetProgress,
 		activate,
 		deactivate,
 		resetStores,

package/src/shared/components/screen-lifecycle/hooks/use-open-transition.ts

@@ -1,4 +1,5 @@
 import { useLayoutEffect } from "react";
+import type { SharedValue } from "react-native-reanimated";
 import type { BaseDescriptor } from "../../../providers/screen/descriptors";
 import type { AnimationStoreMap } from "../../../stores/animation.store";
 import type { SnapPoint } from "../../../types/screen.types";
@@ -35,6 +36,7 @@ function getInitialProgress({
 export function useOpenTransition(
 	current: BaseDescriptor,
 	animations: AnimationStoreMap,
+	targetProgressValue: SharedValue<number>,
 	isFirstKey: boolean,
 ) {
 	const { activateHighRefreshRate, deactivateHighRefreshRate } =
@@ -42,16 +44,24 @@ export function useOpenTransition(
 
 	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
 	useLayoutEffect(() => {
-		const { snapPoints, initialSnapIndex = 0 } = current.options;
-		const targetProgress = getInitialProgress({ snapPoints, initialSnapIndex });
+		const {
+			snapPoints,
+			initialSnapIndex = 0,
+			experimental_animateOnInitialMount,
+		} = current.options;
 
-		if (isFirstKey) {
-			if (targetProgress === "auto") {
-				animations.targetProgress.set(0);
+		const initialProgress = getInitialProgress({
+			snapPoints,
+			initialSnapIndex,
+		});
+
+		if (isFirstKey && !experimental_animateOnInitialMount) {
+			if (initialProgress === "auto") {
+				targetProgressValue.set(0);
 				animations.progress.set(0);
 			} else {
-				const target = targetProgress ?? 1;
-				animations.targetProgress.set(target);
+				const target = initialProgress ?? 1;
+				targetProgressValue.set(target);
 				animations.progress.set(target);
 			}
 			animations.animating.set(0);
@@ -61,16 +71,17 @@ export function useOpenTransition(
 		}
 
 		// When the initial snap point is 'auto', defer the opening animation until
-		// ScreenContainer has measured the content and set autoSnapPoint.
-		if (targetProgress === "auto") {
+		// ScreenContainer has measured the content and set resolvedAutoSnapPoint.
+		if (initialProgress === "auto") {
 			return;
 		}
 
 		activateHighRefreshRate();
 		animateToProgress({
-			target: targetProgress ?? "open",
+			target: initialProgress ?? "open",
 			spec: current.options.transitionSpec,
 			animations,
+			targetProgress: targetProgressValue,
 			onAnimationFinish: deactivateHighRefreshRate,
 		});
 	}, []);

package/src/shared/components/screen-lifecycle/index.tsx

@@ -3,6 +3,7 @@ import {
 	useDescriptors,
 } from "../../providers/screen/descriptors";
 import { AnimationStore } from "../../stores/animation.store";
+import { SystemStore } from "../../stores/system.store";
 import { useCloseTransition } from "./hooks/use-close-transition";
 import { useOpenTransition } from "./hooks/use-open-transition";
 import { useScreenEvents } from "./hooks/use-screen-events";
@@ -18,14 +19,19 @@ interface Props {
 export const ScreenLifecycle = ({ children }: Props) => {
 	const { current, previous } = useDescriptors();
 	const { isFirstKey } = useDescriptorDerivations();
-	const animations = AnimationStore.getRouteAnimations(current.route.key);
+	const animations = AnimationStore.getBag(current.route.key);
+	const targetProgress = SystemStore.getValue(
+		current.route.key,
+		"targetProgress",
+	);
 
 	const { activateHighRefreshRate, deactivateHighRefreshRate } =
-		useOpenTransition(current, animations, isFirstKey);
+		useOpenTransition(current, animations, targetProgress, isFirstKey);
 
 	useCloseTransition(
 		current,
 		animations,
+		targetProgress,
 		activateHighRefreshRate,
 		deactivateHighRefreshRate,
 	);

package/src/shared/configs/presets.ts

@@ -5,8 +5,8 @@ import {
 	interpolateColor,
 } from "react-native-reanimated";
 import {
-	NAVIGATION_CONTAINER_STYLE_ID,
-	NAVIGATION_MASK_STYLE_ID,
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_ELEMENT_STYLE_ID,
 } from "../constants";
 import type { ScreenTransitionConfig } from "../types/screen.types";
 import { normalizeInterpolatedStyle } from "../utils/normalize-interpolated-style";
@@ -277,19 +277,19 @@ export const SharedIGImage = ({
 			const dragXScale = interpolate(normX, [0, 1], [1, 0.8]);
 			const dragYScale = interpolate(normY, [0, 1], [1, 0.8]);
 
-			const navigationStyles = bounds({
-				id: sharedBoundTag,
-				scaleMode: "uniform",
-			}).navigation.zoom();
+			const navigationStyles =
+				bounds({
+					id: sharedBoundTag,
+				}).navigation.zoom() ?? {};
 
 			// Extract raw style values from bounds result (legacy format)
 			const sourceStyle = navigationStyles[sharedBoundTag] as
 				| Record<string, unknown>
 				| undefined;
-			const containerStyle = navigationStyles[NAVIGATION_CONTAINER_STYLE_ID] as
-				| Record<string, unknown>
-				| undefined;
-			const maskStyle = navigationStyles[NAVIGATION_MASK_STYLE_ID] as
+			const containerStyle = navigationStyles[
+				NAVIGATION_MASK_CONTAINER_STYLE_ID
+			] as Record<string, unknown> | undefined;
+			const maskStyle = navigationStyles[NAVIGATION_MASK_ELEMENT_STYLE_ID] as
 				| Record<string, unknown>
 				| undefined;
 
@@ -317,7 +317,7 @@ export const SharedIGImage = ({
 							],
 						},
 					},
-					[NAVIGATION_CONTAINER_STYLE_ID]: containerStyle
+					[NAVIGATION_MASK_CONTAINER_STYLE_ID]: containerStyle
 						? {
 								style: {
 									...containerStyle,
@@ -329,7 +329,7 @@ export const SharedIGImage = ({
 								},
 							}
 						: undefined,
-					[NAVIGATION_MASK_STYLE_ID]: maskStyle
+					[NAVIGATION_MASK_ELEMENT_STYLE_ID]: maskStyle
 						? {
 								style: {
 									...maskStyle,
@@ -620,10 +620,11 @@ export const SharedXImage = ({
 
 			if (!focused) return {};
 
-			const navigationStyles = bounds({
-				id: sharedBoundTag,
-			}).navigation.zoom();
-			const maskStyle = navigationStyles[NAVIGATION_MASK_STYLE_ID] as
+			const navigationStyles =
+				bounds({
+					id: sharedBoundTag,
+				}).navigation.zoom() ?? {};
+			const maskStyle = navigationStyles[NAVIGATION_MASK_ELEMENT_STYLE_ID] as
 				| Record<string, unknown>
 				| undefined;
 
@@ -654,7 +655,7 @@ export const SharedXImage = ({
 
 			return {
 				...normalizedNav,
-				[NAVIGATION_MASK_STYLE_ID]: maskStyle
+				[NAVIGATION_MASK_ELEMENT_STYLE_ID]: maskStyle
 					? {
 							style: {
 								...maskStyle,

package/src/shared/constants.ts

@@ -8,6 +8,7 @@ import type { BaseStackRoute } from "./types/stack.types";
 
 /**
  * Masked view integration
+ * @deprecated No longer in use. Use {@link NAVIGATION_MASK_ELEMENT_STYLE_ID} and {@link NAVIGATION_MASK_CONTAINER_STYLE_ID} instead.
  */
 export const MASK_STYLE_ID = "_ROOT_MASKED";
 export const CONTAINER_STYLE_ID = "_ROOT_CONTAINER";
@@ -15,14 +16,15 @@ export const CONTAINER_STYLE_ID = "_ROOT_CONTAINER";
 /**
  * Navigation mask integration
  */
-export const NAVIGATION_MASK_HOST_FLAG_STYLE_ID = "_NAVIGATION_MASK_HOST";
-export const NAVIGATION_MASK_STYLE_ID = "_NAVIGATION_ROOT_MASK";
-export const NAVIGATION_CONTAINER_STYLE_ID = "_NAVIGATION_ROOT_CONTAINER";
+export const NAVIGATION_MASK_ELEMENT_STYLE_ID = "_NAVIGATION_ROOT_MASK";
+export const NAVIGATION_MASK_CONTAINER_STYLE_ID = "_NAVIGATION_ROOT_CONTAINER";
 
 /**
  * Styles
  */
 export const NO_STYLES = Object.freeze({});
+export const HIDDEN_STYLE = Object.freeze({ opacity: 0 });
+export const VISIBLE_STYLE = Object.freeze({ opacity: 1 });
 export const NO_PROPS = Object.freeze({});
 
 /**
@@ -59,6 +61,13 @@ export const createScreenTransitionState = (
 	gesture: { ...DEFAULT_GESTURE_VALUES },
 	route,
 	meta,
+	layouts: {
+		screen: {
+			width: 0,
+			height: 0,
+		},
+	},
+	snapIndex: -1,
 });
 
 /**
@@ -73,6 +82,13 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 		entering: 0,
 		gesture: DEFAULT_GESTURE_VALUES,
 		route: {} as RouteProp<ParamListBase>,
+		layouts: {
+			screen: {
+				width: 0,
+				height: 0,
+			},
+		},
+		snapIndex: -1,
 	});
 
 /**