react-native-screen-transitions 3.4.0-alpha.1 → 3.4.0-alpha.3

package/src/shared/components/native-screen.tsx

@@ -52,42 +52,74 @@ export const NativeScreen = ({
 	const { activeScreensLimit, backdropBehaviors } = useManagedStackContext();
 
 	const routesLength = routes.length;
+	const topIndex = routesLength - 1;
+	const topRouteKey = routes[topIndex]?.key ?? routeKey;
 	const screenRef = useAnimatedRef<View>();
 
-	const sceneProgress = AnimationStore.getRouteAnimation(routeKey, "progress");
 	const sceneClosing = AnimationStore.getRouteAnimation(routeKey, "closing");
+	const topSceneProgress = AnimationStore.getRouteAnimation(
+		topRouteKey,
+		"progress",
+	);
+	const topSceneClosing = AnimationStore.getRouteAnimation(
+		topRouteKey,
+		"closing",
+	);
 	const screenActivity = useSharedValue<ScreenActivity>(
 		ScreenActivity.TRANSITIONING_OR_BELOW_TOP,
 	);
 
 	useDerivedValue(() => {
-		if (!sceneProgress) {
+		if (!topSceneProgress) {
 			screenActivity.set(ScreenActivity.TRANSITIONING_OR_BELOW_TOP);
 			return;
 		}
 
 		if (index < routesLength - activeScreensLimit - 1 || isPreloaded) {
 			screenActivity.set(ScreenActivity.INACTIVE);
-		} else {
-			const outputValue =
-				index === routesLength - 1
+			return;
+		}
+
+		const focusedIndex = optimisticFocusedIndex.value;
+		const topIsClosing =
+			topSceneClosing.get() > 0 && focusedIndex >= 0 && focusedIndex < topIndex;
+
+		if (topIsClosing) {
+			const postCloseActiveStart = Math.max(
+				0,
+				focusedIndex - activeScreensLimit + 1,
+			);
+			const next =
+				index === topIndex
 					? ScreenActivity.ON_TOP
-					: index >= routesLength - activeScreensLimit
+					: index > focusedIndex || index >= postCloseActiveStart
 						? ScreenActivity.TRANSITIONING_OR_BELOW_TOP
 						: ScreenActivity.INACTIVE;
 
-			const v = interpolate(
-				sceneProgress.get(),
-				[0, 1 - EPSILON, 1],
-				[1, 1, outputValue],
-				Extrapolation.CLAMP,
-			);
-
-			const next = Math.trunc(v) ?? ScreenActivity.TRANSITIONING_OR_BELOW_TOP;
-
 			if (next !== screenActivity.get()) {
 				screenActivity.set(next);
 			}
+			return;
+		}
+
+		const outputValue =
+			index === topIndex
+				? ScreenActivity.ON_TOP
+				: index >= routesLength - activeScreensLimit
+					? ScreenActivity.TRANSITIONING_OR_BELOW_TOP
+					: ScreenActivity.INACTIVE;
+
+		const v = interpolate(
+			topSceneProgress.get(),
+			[0, 1 - EPSILON, 1],
+			[1, 1, outputValue],
+			Extrapolation.CLAMP,
+		);
+
+		const next = Math.trunc(v) ?? ScreenActivity.TRANSITIONING_OR_BELOW_TOP;
+
+		if (next !== screenActivity.get()) {
+			screenActivity.set(next);
 		}
 	});
 
@@ -126,12 +158,25 @@ export const NativeScreen = ({
 		};
 	});
 
-	const NativeScreenComponent = !DISABLE_NATIVE_SCREENS
-		? AnimatedNativeScreen
-		: Animated.View;
+	if (DISABLE_NATIVE_SCREENS) {
+		return (
+			<Animated.View
+				ref={screenRef}
+				// Keep a native boundary per screen when falling back to plain views.
+				// Android release builds can otherwise flatten sibling screens together.
+				collapsable={false}
+				style={StyleSheet.absoluteFill}
+				animatedProps={animatedProps}
+			>
+				<LayoutAnchorProvider anchorRef={screenRef}>
+					{children}
+				</LayoutAnchorProvider>
+			</Animated.View>
+		);
+	}
 
 	return (
-		<NativeScreenComponent
+		<AnimatedNativeScreen
 			enabled
 			ref={screenRef}
 			style={StyleSheet.absoluteFill}
@@ -141,6 +186,6 @@ export const NativeScreen = ({
 			<LayoutAnchorProvider anchorRef={screenRef}>
 				{children}
 			</LayoutAnchorProvider>
-		</NativeScreenComponent>
+		</AnimatedNativeScreen>
 	);
 };

package/src/shared/components/screen-container/deferred-visibility-host.tsx

@@ -0,0 +1,37 @@
+import { memo } from "react";
+import { StyleSheet } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { HIDDEN_STYLE, NO_STYLES } from "../../constants";
+import { useScreenStyles } from "../../providers/screen/styles.provider";
+
+type Props = {
+	children: React.ReactNode;
+};
+
+/**
+ * Hides the full screen visual subtree while an interpolator explicitly reports
+ * that it is not safe to reveal yet.
+ *
+ * This sits above backdrop/content/mask/surface so a deferred transition does
+ * not leak raw first-paint UI from nested layers.
+ */
+export const DeferredVisibilityHost = memo(({ children }: Props) => {
+	const { resolutionMode } = useScreenStyles();
+
+	const animatedStyle = useAnimatedStyle(() => {
+		"worklet";
+		return resolutionMode.value === "deferred" ? HIDDEN_STYLE : NO_STYLES;
+	});
+
+	return (
+		<Animated.View collapsable={false} style={[styles.host, animatedStyle]}>
+			{children}
+		</Animated.View>
+	);
+});
+
+const styles = StyleSheet.create({
+	host: {
+		flex: 1,
+	},
+});

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

@@ -0,0 +1,82 @@
+import { useCallback } from "react";
+import { type LayoutChangeEvent, useWindowDimensions } from "react-native";
+import { runOnUI } from "react-native-reanimated";
+import {
+	useDescriptorDerivations,
+	useDescriptors,
+} from "../../../providers/screen/descriptors";
+import { AnimationStore } from "../../../stores/animation.store";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+
+export function useContentLayout() {
+	const { current } = useDescriptors();
+	const { isFirstKey } = useDescriptorDerivations();
+	const { height: screenHeight } = useWindowDimensions();
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getRouteAnimations(routeKey);
+	const autoSnapPointValue = AnimationStore.getAnimation(
+		routeKey,
+		"autoSnapPoint",
+	);
+	const contentLayoutValue = AnimationStore.getAnimation(
+		routeKey,
+		"contentLayout",
+	);
+
+	return useCallback(
+		(event: LayoutChangeEvent) => {
+			const { width, height } = event.nativeEvent.layout;
+			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,
+					};
+
+					const isFirstMeasurement = autoSnapPointValue.value <= 0;
+					autoSnapPointValue.value = nextFraction;
+
+					if (
+						!isFirstMeasurement ||
+						animations.progress.value !== 0 ||
+						animations.animating.value !== 0
+					) {
+						return;
+					}
+
+					if (isInitialScreen) {
+						animations.targetProgress.value = nextFraction;
+						animations.progress.value = nextFraction;
+						return;
+					}
+
+					animateToProgress({
+						target: nextFraction,
+						spec,
+						animations,
+					});
+				},
+			)(width, height, fraction, isFirstKey, transitionSpec);
+		},
+		[
+			animations,
+			autoSnapPointValue,
+			contentLayoutValue,
+			current.options.transitionSpec,
+			isFirstKey,
+			screenHeight,
+		],
+	);
+}

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/content.tsx

@@ -1,27 +1,22 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <Screen gesture is under the gesture context, so this will always exist.> */
-import { memo, useCallback } from "react";
-import {
-	type LayoutChangeEvent,
-	StyleSheet,
-	useWindowDimensions,
-	View,
-} from "react-native";
+import { memo } from "react";
+import { StyleSheet, View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, {
-	runOnUI,
 	useAnimatedProps,
 	useAnimatedStyle,
 } from "react-native-reanimated";
-import { NO_PROPS, NO_STYLES } from "../../../constants";
-import { useGestureContext } from "../../../providers/gestures";
 import {
-	useDescriptorDerivations,
-	useDescriptors,
-} from "../../../providers/screen/descriptors";
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NO_PROPS,
+	NO_STYLES,
+} from "../../../constants";
+import { useGestureContext } from "../../../providers/gestures";
+import { useDescriptors } from "../../../providers/screen/descriptors";
 import { useScreenStyles } from "../../../providers/screen/styles.provider";
-import { AnimationStore } from "../../../stores/animation.store";
-import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+import { resolveNavigationMaskEnabled } from "../../../utils/resolve-screen-transition-options";
 import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
+import { useContentLayout } from "../hooks/use-content-layout";
 import { MaybeMaskedNavigationContainer } from "./maybe-masked-navigation-container";
 import { SurfaceContainer } from "./surface-container";
 
@@ -32,78 +27,63 @@ type Props = {
 export const ContentLayer = memo(({ children }: Props) => {
 	const { stylesMap } = useScreenStyles();
 	const { current } = useDescriptors();
-	const { isFirstKey } = useDescriptorDerivations();
 	const { pointerEvents, isBackdropActive } = useBackdropPointerEvents();
 	const gestureContext = useGestureContext();
-	const { height: screenHeight } = useWindowDimensions();
-	const isNavigationMaskEnabled = !!current.options.maskEnabled;
+	const isNavigationMaskEnabled = resolveNavigationMaskEnabled(current.options);
 	const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
-	const routeKey = current.route.key;
-	const animations = AnimationStore.getRouteAnimations(routeKey);
-	const autoSnapPointValue = AnimationStore.getAnimation(
-		routeKey,
-		"autoSnapPoint",
-	);
 	const hasAutoSnapPoint =
 		current.options.snapPoints?.includes("auto") ?? false;
 
+	const handleContentLayout = useContentLayout();
+
 	const animatedContentStyle = useAnimatedStyle(() => {
 		"worklet";
 		return stylesMap.value.content?.style || NO_STYLES;
 	});
 
+	const animatedNavigationContainerStyle = useAnimatedStyle(() => {
+		"worklet";
+		return (
+			stylesMap.value[NAVIGATION_MASK_CONTAINER_STYLE_ID]?.style || NO_STYLES
+		);
+	});
+
 	const animatedContentProps = useAnimatedProps(() => {
 		"worklet";
 		return stylesMap.value.content?.props ?? NO_PROPS;
 	});
 
-	const handleContentLayout = useCallback(
-		(event: LayoutChangeEvent) => {
-			const contentHeight = event.nativeEvent.layout.height;
-			if (contentHeight <= 0) return;
-
-			const fraction = Math.min(contentHeight / screenHeight, 1);
-			const transitionSpec = current.options.transitionSpec;
-
-			runOnUI(
-				(
-					nextFraction: number,
-					isInitialScreen: boolean,
-					spec: typeof transitionSpec,
-				) => {
-					"worklet";
-					const isFirstMeasurement = autoSnapPointValue.value <= 0;
-					autoSnapPointValue.value = nextFraction;
-
-					if (
-						!isFirstMeasurement ||
-						animations.progress.value !== 0 ||
-						animations.animating.value !== 0
-					) {
-						return;
-					}
+	const surfaceChildren = (
+		<SurfaceContainer pointerEvents={contentPointerEvents}>
+			{hasAutoSnapPoint ? (
+				<View collapsable={false} onLayout={handleContentLayout}>
+					{children}
+				</View>
+			) : (
+				children
+			)}
+		</SurfaceContainer>
+	);
 
-					if (isInitialScreen) {
-						animations.targetProgress.value = nextFraction;
-						animations.progress.value = nextFraction;
-						return;
-					}
+	const navigationContainer = (
+		<Animated.View
+			style={[styles.navigationContainer, animatedNavigationContainerStyle]}
+			pointerEvents={contentPointerEvents}
+			collapsable={false}
+		>
+			{surfaceChildren}
+		</Animated.View>
+	);
 
-					animateToProgress({
-						target: nextFraction,
-						spec,
-						animations,
-					});
-				},
-			)(fraction, isFirstKey, transitionSpec);
-		},
-		[
-			animations,
-			autoSnapPointValue,
-			current.options.transitionSpec,
-			isFirstKey,
-			screenHeight,
-		],
+	const navigationScopedChildren = isNavigationMaskEnabled ? (
+		<MaybeMaskedNavigationContainer
+			pointerEvents={contentPointerEvents}
+			enabled={isNavigationMaskEnabled}
+		>
+			{navigationContainer}
+		</MaybeMaskedNavigationContainer>
+	) : (
+		navigationContainer
 	);
 
 	return (
@@ -113,17 +93,7 @@ export const ContentLayer = memo(({ children }: Props) => {
 				animatedProps={animatedContentProps}
 				pointerEvents={contentPointerEvents}
 			>
-				<MaybeMaskedNavigationContainer enabled={isNavigationMaskEnabled}>
-					<SurfaceContainer pointerEvents={contentPointerEvents}>
-						{hasAutoSnapPoint ? (
-							<View collapsable={false} onLayout={handleContentLayout}>
-								{children}
-							</View>
-						) : (
-							children
-						)}
-					</SurfaceContainer>
-				</MaybeMaskedNavigationContainer>
+				{navigationScopedChildren}
 			</Animated.View>
 		</GestureDetector>
 	);
@@ -133,4 +103,7 @@ const styles = StyleSheet.create({
 	content: {
 		flex: 1,
 	},
+	navigationContainer: {
+		flex: 1,
+	},
 });

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

@@ -1,9 +1,8 @@
 import { memo, useEffect } from "react";
-import { StyleSheet, View } from "react-native";
+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_ELEMENT_STYLE_ID,
 	NO_STYLES,
 } from "../../../constants";
 import { useScreenStyles } from "../../../providers/screen/styles.provider";
@@ -12,6 +11,7 @@ import { logger } from "../../../utils/logger";
 type Props = {
 	enabled: boolean;
 	children: React.ReactNode;
+	pointerEvents: ViewProps["pointerEvents"];
 };
 
 let LazyMaskedView = View;
@@ -25,16 +25,13 @@ try {
 let hasWarnedMissingMaskedView = false;
 
 export const MaybeMaskedNavigationContainer = memo(
-	({ enabled, children }: Props) => {
+	({ enabled, children, pointerEvents }: Props) => {
 		const { stylesMap } = useScreenStyles();
-		const animatedNavigationContainerStyle = useAnimatedStyle(() => {
-			"worklet";
-			return stylesMap.value[NAVIGATION_CONTAINER_STYLE_ID]?.style || NO_STYLES;
-		});
-
 		const animatedNavigationMaskStyle = useAnimatedStyle(() => {
 			"worklet";
-			return stylesMap.value[NAVIGATION_MASK_STYLE_ID]?.style || NO_STYLES;
+			return (
+				stylesMap.value[NAVIGATION_MASK_ELEMENT_STYLE_ID]?.style || NO_STYLES
+			);
 		});
 
 		useEffect(() => {
@@ -44,20 +41,13 @@ export const MaybeMaskedNavigationContainer = memo(
 
 			hasWarnedMissingMaskedView = true;
 			logger.warn(
-				"maskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
+				"navigationMaskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
 			);
 		}, [enabled]);
-
 		if (!enabled) return children;
 
 		if (LazyMaskedView === View) {
-			return (
-				<Animated.View
-					style={[styles.navigationContainer, animatedNavigationContainerStyle]}
-				>
-					{children}
-				</Animated.View>
-			);
+			return children;
 		}
 
 		return (
@@ -67,14 +57,12 @@ export const MaybeMaskedNavigationContainer = memo(
 				maskElement={
 					<Animated.View
 						style={[styles.navigationMaskElement, animatedNavigationMaskStyle]}
+						pointerEvents="none"
 					/>
 				}
+				pointerEvents={pointerEvents}
 			>
-				<Animated.View
-					style={[styles.navigationContainer, animatedNavigationContainerStyle]}
-				>
-					{children}
-				</Animated.View>
+				{children}
 			</LazyMaskedView>
 		);
 	},
@@ -87,7 +75,4 @@ const styles = StyleSheet.create({
 	navigationMaskElement: {
 		backgroundColor: "white",
 	},
-	navigationContainer: {
-		flex: 1,
-	},
 });

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";
@@ -286,10 +286,10 @@ export const SharedIGImage = ({
 			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,
@@ -623,7 +623,7 @@ export const SharedXImage = ({
 			const navigationStyles = bounds({
 				id: sharedBoundTag,
 			}).navigation.zoom();
-			const maskStyle = navigationStyles[NAVIGATION_MASK_STYLE_ID] as
+			const maskStyle = navigationStyles[NAVIGATION_MASK_ELEMENT_STYLE_ID] as
 				| Record<string, unknown>
 				| undefined;
 
@@ -654,7 +654,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({});
 
 /**