react-native-screen-transitions 3.5.2 → 3.6.0-alpha.1

package/src/shared/components/create-boundary-component/hooks/use-measurer.ts

@@ -1,37 +1,24 @@
 import { useCallback } from "react";
 import type { View } from "react-native";
 import { useWindowDimensions } from "react-native";
-import {
-	type AnimatedRef,
-	measure,
-	type StyleProps,
-} from "react-native-reanimated";
-import { applyMeasuredBoundsWrites } from "../../../stores/bounds/helpers/apply-measured-bounds-writes";
-import {
-	getMeasuredEntry,
-	getPendingLink,
-	hasDestinationLink,
-	hasSourceLink,
-} from "../../../stores/bounds/internals/registry";
-import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
+import type { AnimatedRef, StyleProps } from "react-native-reanimated";
+import { ScrollStore } from "../../../stores/scroll.store";
+import { SystemStore } from "../../../stores/system.store";
+import { applyMeasuredBoundsWrites } from "../helpers/apply-measured-bounds-writes";
 import type { MeasureParams } from "../types";
+import { createLinkContext } from "./helpers/boundary-link-context";
+import { isMeasurementInViewport } from "./helpers/measurement";
 import {
-	areMeasurementsEqual,
-	isMeasurementInViewport,
-} from "./helpers/measurement";
-import {
+	buildMeasurementWritePlan,
 	getMeasureIntentFlags,
-	resolveMeasureWritePlan,
 } from "./helpers/measurement-rules";
+import { measureWithOverscrollAwareness } from "./helpers/scroll-measurement";
 
 interface UseMeasurerParams {
 	enabled: boolean;
 	sharedBoundTag: string;
 	preferredSourceScreenKey?: string;
 	currentScreenKey: string;
-	ancestorKeys: string[];
-	navigatorKey?: string;
-	ancestorNavigatorKeys?: string[];
 	preparedStyles: StyleProps;
 	measuredAnimatedRef: AnimatedRef<View>;
 }
@@ -41,92 +28,92 @@ export const useMeasurer = ({
 	sharedBoundTag,
 	preferredSourceScreenKey,
 	currentScreenKey,
-	ancestorKeys,
-	navigatorKey,
-	ancestorNavigatorKeys,
 	preparedStyles,
 	measuredAnimatedRef,
 }: UseMeasurerParams) => {
 	const { width: viewportWidth, height: viewportHeight } =
 		useWindowDimensions();
 
+	const scrollState = ScrollStore.getValue(currentScreenKey, "state");
+	const pendingLifecycleStartBlockCount = SystemStore.getValue(
+		currentScreenKey,
+		"pendingLifecycleStartBlockCount",
+	);
+
 	return useCallback(
 		({ intent }: MeasureParams = {}) => {
 			"worklet";
 			if (!enabled) return;
 
 			const intents = getMeasureIntentFlags(intent);
-
-			const expectedSourceScreenKey: string | undefined =
-				resolvePendingSourceKey(sharedBoundTag, preferredSourceScreenKey) ||
-				undefined;
-
-			const pendingLink = expectedSourceScreenKey
-				? getPendingLink(sharedBoundTag, expectedSourceScreenKey)
-				: getPendingLink(sharedBoundTag);
-			const hasPendingLink = pendingLink !== null;
-			const hasAttachableSourceLink = expectedSourceScreenKey
-				? hasSourceLink(sharedBoundTag, expectedSourceScreenKey)
-				: false;
-			const hasSource = hasSourceLink(sharedBoundTag, currentScreenKey);
-			const hasDestination = hasDestinationLink(
+			const currentLink = createLinkContext({
 				sharedBoundTag,
 				currentScreenKey,
-			);
+				preferredSourceScreenKey,
+			});
 
-			const writePlan = resolveMeasureWritePlan({
+			const writePlan = buildMeasurementWritePlan({
 				intents,
-				hasPendingLink,
-				hasSourceLink: hasSource,
-				hasDestinationLink: hasDestination,
-				hasAttachableSourceLink,
+				hasPendingLink: currentLink.hasPendingLink,
+				hasSourceLink: currentLink.hasSourceLink,
+				hasDestinationLink: currentLink.hasDestinationLink,
+				hasAttachableSourceLink: currentLink.hasAttachableSourceLink,
 			});
 
-			if (!writePlan.writesAny) {
-				return;
-			}
+			if (!writePlan.writesAny) return;
+
+			const measured = measureWithOverscrollAwareness(
+				measuredAnimatedRef,
+				scrollState.get(),
+			);
 
-			const measured = measure(measuredAnimatedRef);
 			if (!measured) return;
 
-			const destinationInViewport =
-				!writePlan.wantsDestinationWrite ||
+			/**
+			 * Source Pass
+			 * Source intents are intentionally used & kept unguarded.
+			 */
+			const sourceWrites = {
+				shouldSetSource: writePlan.captureSource,
+				shouldUpdateSource: writePlan.refreshSource,
+			};
+
+			/**
+			 * - Destination Pass -
+			 * Be strict while lifecycle start is blocked for destination capture.
+			 * This is the initial attach window: the transition has not started yet,
+			 * and malformed off-screen destination measurements should keep the
+			 * lifecycle blocked until a valid retry lands.
+			 */
+			const shouldGuardDestinationViewport =
+				pendingLifecycleStartBlockCount.get() > 0;
+			const viewportAllowsDestinationWrite =
+				!shouldGuardDestinationViewport ||
 				isMeasurementInViewport(measured, viewportWidth, viewportHeight);
 
-			if (
-				!destinationInViewport &&
-				!writePlan.captureSource &&
-				!writePlan.refreshSource
-			) {
-				return;
-			}
+			const destinationWrites = {
+				shouldSetDestination:
+					viewportAllowsDestinationWrite && writePlan.completeDestination,
+				shouldUpdateDestination:
+					viewportAllowsDestinationWrite && writePlan.refreshDestination,
+			};
 
-			const existingMeasuredEntry = getMeasuredEntry(
-				sharedBoundTag,
-				currentScreenKey,
-			);
-			const hasMeasuredEntryChanged =
-				!existingMeasuredEntry ||
-				!areMeasurementsEqual(existingMeasuredEntry.bounds, measured);
+			const shouldApplyMeasurement =
+				sourceWrites.shouldSetSource ||
+				sourceWrites.shouldUpdateSource ||
+				destinationWrites.shouldSetDestination ||
+				destinationWrites.shouldUpdateDestination;
+
+			if (!shouldApplyMeasurement) return;
 
 			applyMeasuredBoundsWrites({
 				sharedBoundTag,
 				currentScreenKey,
 				measured,
 				preparedStyles,
-				ancestorKeys,
-				navigatorKey,
-				ancestorNavigatorKeys,
-				expectedSourceScreenKey,
-				shouldWriteEntry: hasMeasuredEntryChanged,
-				shouldSetSource: writePlan.captureSource,
-				shouldUpdateSource: writePlan.refreshSource && hasMeasuredEntryChanged,
-				shouldUpdateDestination:
-					writePlan.refreshDestination &&
-					destinationInViewport &&
-					hasMeasuredEntryChanged,
-				shouldSetDestination:
-					writePlan.completeDestination && destinationInViewport,
+				expectedSourceScreenKey: currentLink.expectedSourceScreenKey,
+				...sourceWrites,
+				...destinationWrites,
 			});
 		},
 		[
@@ -134,13 +121,12 @@ export const useMeasurer = ({
 			sharedBoundTag,
 			preferredSourceScreenKey,
 			currentScreenKey,
-			ancestorKeys,
-			navigatorKey,
-			ancestorNavigatorKeys,
 			preparedStyles,
 			measuredAnimatedRef,
 			viewportWidth,
 			viewportHeight,
+			scrollState,
+			pendingLifecycleStartBlockCount,
 		],
 	);
 };

package/src/shared/components/create-boundary-component/hooks/use-refresh-boundary.ts

@@ -1,8 +1,10 @@
 import { useAnimatedReaction } from "react-native-reanimated";
 import { AnimationStore } from "../../../stores/animation.store";
 import { getGroupActiveId } from "../../../stores/bounds/internals/groups";
-import { hasSourceLink } from "../../../stores/bounds/internals/registry";
-import { GestureStore } from "../../../stores/gesture.store";
+import {
+	hasDestinationLink,
+	hasSourceLink,
+} from "../../../stores/bounds/internals/links";
 import type { BoundaryId, MeasureParams } from "../types";
 
 interface UseRefreshBoundaryParams {
@@ -30,63 +32,63 @@ export const useRefreshBoundary = ({
 		currentScreenKey,
 		"willAnimate",
 	);
+	const currentClosing = AnimationStore.getValue(currentScreenKey, "closing");
+	const currentEntering = AnimationStore.getValue(currentScreenKey, "entering");
 	const currentAnimating = AnimationStore.getValue(
 		currentScreenKey,
-		"animating",
+		"progressAnimating",
 	);
-	const currentDragging = GestureStore.getValue(currentScreenKey, "dragging");
+	const currentProgress = AnimationStore.getValue(currentScreenKey, "progress");
 	const nextWillAnimate = nextScreenKey
 		? AnimationStore.getValue(nextScreenKey, "willAnimate")
 		: null;
-	const nextAnimating = nextScreenKey
-		? AnimationStore.getValue(nextScreenKey, "animating")
+
+	const nextClosing = nextScreenKey
+		? AnimationStore.getValue(nextScreenKey, "closing")
 		: null;
-	const nextDragging = nextScreenKey
-		? GestureStore.getValue(nextScreenKey, "dragging")
+	const nextEntering = nextScreenKey
+		? AnimationStore.getValue(nextScreenKey, "entering")
 		: null;
 
 	useAnimatedReaction(
-		() => (hasNextScreen ? (nextWillAnimate?.get() ?? 0) : 0),
-		(nextValue, previousValue) => {
+		() => {
 			"worklet";
-			if (!enabled || !hasNextScreen) return;
-			if (nextValue === 0 || nextValue === previousValue) return;
-
-			const currentGroupActiveId = group ? getGroupActiveId(group) : null;
-
-			if (group && currentGroupActiveId !== String(id)) {
-				return;
-			}
-
-			const shouldCancelMeasurement =
-				!!nextAnimating?.get() && !!nextDragging?.get();
 
-			if (shouldCancelMeasurement) {
-				return;
+			const shouldRefresh = hasNextScreen
+				? (nextWillAnimate?.get() ?? 0)
+				: currentWillAnimate.get();
+			const closing = hasNextScreen
+				? (nextClosing?.get() ?? 0)
+				: currentClosing.get();
+			const entering = hasNextScreen
+				? (nextEntering?.get() ?? 0)
+				: currentEntering.get();
+
+			// Programmatic close marks `closing` before pulsing `willAnimate`.
+			// This frame is still settled, so destination refresh is valid and
+			// reveal can compute initial/current destination delta before progress moves.
+			const canRefreshPreCloseDestination =
+				!hasNextScreen &&
+				shouldRefresh &&
+				closing &&
+				!entering &&
+				!currentAnimating.get() &&
+				currentProgress.get() >= 1;
+
+			if (
+				canRefreshPreCloseDestination ||
+				(shouldRefresh && !closing && !entering)
+			) {
+				return 1;
 			}
 
-			const hasSource = hasSourceLink(sharedBoundTag, currentScreenKey);
-
-			const intent = !hasSource
-				? "capture-source"
-				: group
-					? "refresh-source"
-					: null;
-
-			if (!intent) {
-				return;
-			}
-
-			measureBoundary({ intent });
+			return 0;
 		},
-	);
-
-	useAnimatedReaction(
-		() => (!hasNextScreen ? currentWillAnimate.get() : 0),
-		(nextValue, previousValue) => {
+		(shouldRefresh, prevShouldRefresh) => {
 			"worklet";
-			if (!enabled || hasNextScreen) return;
-			if (nextValue === 0 || nextValue === previousValue) return;
+
+			if (!enabled || !shouldRefresh || shouldRefresh === prevShouldRefresh)
+				return;
 
 			const currentGroupActiveId = group ? getGroupActiveId(group) : null;
 
@@ -94,15 +96,21 @@ export const useRefreshBoundary = ({
 				return;
 			}
 
-			const shouldCancelMeasurement =
-				!!currentAnimating.get() && !!currentDragging.get();
+			if (hasNextScreen) {
+				if (
+					!nextScreenKey ||
+					!hasSourceLink(sharedBoundTag, currentScreenKey) ||
+					!hasDestinationLink(sharedBoundTag, nextScreenKey)
+				) {
+					return;
+				}
 
-			if (shouldCancelMeasurement) {
+				measureBoundary({ intent: "refresh-source" });
 				return;
 			}
 
 			measureBoundary({
-				intent: ["complete-destination", "refresh-destination"] as const,
+				intent: "refresh-destination",
 			});
 		},
 	);

package/src/shared/components/create-boundary-component/providers/boundary-owner.provider.tsx

@@ -10,7 +10,7 @@ import {
 } from "react";
 import type { View } from "react-native";
 import type Animated from "react-native-reanimated";
-import type { AnimatedRef } from "react-native-reanimated";
+import type { AnimatedRef, StyleProps } from "react-native-reanimated";
 
 type BoundaryAssociatedStyle = React.ComponentProps<
 	typeof Animated.View
@@ -18,12 +18,20 @@ type BoundaryAssociatedStyle = React.ComponentProps<
 
 interface BoundaryOwnerContextValue {
 	ownerRef: AnimatedRef<View>;
-	registerTargetRef: (targetRef: AnimatedRef<View>) => void;
+	registerTargetRef: (
+		targetRef: AnimatedRef<View>,
+		preparedStyles: StyleProps,
+	) => void;
 	unregisterTargetRef: (targetRef: AnimatedRef<View>) => void;
 	activeTargetRef: AnimatedRef<View> | null;
 	associatedTargetStyles?: BoundaryAssociatedStyle;
 }
 
+type BoundaryTargetEntry = {
+	ref: AnimatedRef<View>;
+	preparedStyles: StyleProps;
+};
+
 const BoundaryOwnerContext = createContext<BoundaryOwnerContextValue | null>(
 	null,
 );
@@ -57,31 +65,34 @@ export const useBoundaryOwner = (params: {
 }) => {
 	const { ownerRef, associatedTargetStyles } = params;
 	const warnedAboutMultipleTargetsRef = useRef(false);
-	const [targetRefs, setTargetRefs] = useState<AnimatedRef<View>[]>([]);
-
-	const registerTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
-		setTargetRefs((prev) => {
-			if (prev.includes(targetRef)) {
-				return prev;
-			}
-
-			if (
-				__DEV__ &&
-				prev.length > 0 &&
-				!warnedAboutMultipleTargetsRef.current
-			) {
-				warnedAboutMultipleTargetsRef.current = true;
-				console.warn(MULTIPLE_TARGETS_WARNING);
-			}
-
-			return [...prev, targetRef];
-		});
-	}, []);
+	const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
+		null,
+	);
+
+	const registerTargetRef = useCallback(
+		(targetRef: AnimatedRef<View>, preparedStyles: StyleProps) => {
+			setTargetEntry((prev) => {
+				if (prev?.ref === targetRef) {
+					return prev;
+				}
+
+				if (
+					__DEV__ &&
+					prev !== null &&
+					!warnedAboutMultipleTargetsRef.current
+				) {
+					warnedAboutMultipleTargetsRef.current = true;
+					console.warn(MULTIPLE_TARGETS_WARNING);
+				}
+
+				return prev ?? { ref: targetRef, preparedStyles };
+			});
+		},
+		[],
+	);
 
 	const unregisterTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
-		setTargetRefs((prev) =>
-			prev.filter((existingRef) => existingRef !== targetRef),
-		);
+		setTargetEntry((prev) => (prev?.ref === targetRef ? null : prev));
 	}, []);
 
 	const contextValue = useMemo(
@@ -89,21 +100,22 @@ export const useBoundaryOwner = (params: {
 			ownerRef,
 			registerTargetRef,
 			unregisterTargetRef,
-			activeTargetRef: targetRefs[0] ?? null,
+			activeTargetRef: targetEntry?.ref ?? null,
 			associatedTargetStyles,
 		}),
 		[
 			ownerRef,
 			registerTargetRef,
 			unregisterTargetRef,
-			targetRefs,
+			targetEntry,
 			associatedTargetStyles,
 		],
 	);
 
 	return {
 		contextValue,
-		hasActiveTarget: targetRefs.length > 0,
-		measuredRef: targetRefs[0] ?? ownerRef,
+		hasActiveTarget: targetEntry !== null,
+		measuredRef: targetEntry?.ref ?? ownerRef,
+		targetPreparedStyles: targetEntry?.preparedStyles,
 	};
 };

package/src/shared/components/create-boundary-component/types.ts

@@ -1,4 +1,3 @@
-import type { ViewProps } from "react-native";
 import type { BoundsOptions } from "../../utils/bounds/types/options";
 
 export type BoundaryId = string | number;
@@ -36,19 +35,12 @@ export interface BoundaryOwnProps extends BoundaryConfigProps {
 export type BoundaryComponentProps<P extends object> = Omit<P, "id"> &
 	BoundaryOwnProps;
 
-/** Convenience alias for a View-based boundary (the most common case). */
-export type BoundaryProps = BoundaryComponentProps<ViewProps>;
-
 export type MeasureIntent =
 	| "capture-source"
 	| "complete-destination"
 	| "refresh-source"
 	| "refresh-destination";
 
-export type MeasurementIntent = MeasureIntent;
-
 export interface MeasureParams {
 	intent?: MeasureIntent | readonly MeasureIntent[];
 }
-
-export interface MaybeMeasureAndStoreParams extends MeasureParams {}

package/src/shared/components/create-boundary-component/utils/build-boundary-match-key.ts

@@ -5,9 +5,6 @@ type BuildBoundaryMatchKeyParams = {
 	id: BoundaryId;
 };
 
-export function buildBoundaryMatchKey(
-	params: BuildBoundaryMatchKeyParams,
-): string;
 export function buildBoundaryMatchKey(
 	params: BuildBoundaryMatchKeyParams,
 ): string {

package/src/shared/components/create-transition-aware-component.tsx

@@ -11,8 +11,8 @@ import Animated, {
 	useComposedEventHandler,
 } from "react-native-reanimated";
 import { NO_PROPS, NO_STYLES } from "../constants";
-import { useScrollRegistry } from "../hooks/gestures/use-scroll-registry";
 import { RegisterBoundsProvider } from "../providers/register-bounds.provider";
+import { useScrollGestureCoordination } from "../providers/screen/gestures/scroll-coordination";
 import { useScreenStyles } from "../providers/screen/styles";
 import type { TransitionAwareProps } from "../types/screen.types";
 
@@ -49,12 +49,17 @@ export function createTransitionAwareComponent<P extends object>(
 			: "vertical";
 
 		// Get scroll handlers and the gesture owner's nativeGesture for this axis
-		const { scrollHandler, onContentSizeChange, onLayout, nativeGesture } =
-			useScrollRegistry({
-				onContentSizeChange: scrollableProps.onContentSizeChange,
-				onLayout: scrollableProps.onLayout,
-				direction: scrollDirection,
-			});
+		const {
+			scrollHandler,
+			scrollEventsEnabled,
+			onContentSizeChange,
+			onLayout,
+			nativeGesture,
+		} = useScrollGestureCoordination({
+			onContentSizeChange: scrollableProps.onContentSizeChange,
+			onLayout: scrollableProps.onLayout,
+			direction: scrollDirection,
+		});
 
 		const composedScrollHandler = useComposedEventHandler([
 			scrollHandler,
@@ -65,12 +70,22 @@ export function createTransitionAwareComponent<P extends object>(
 			<AnimatedComponent
 				{...(scrollableProps as any)}
 				ref={ref}
-				onScroll={composedScrollHandler}
+				/**
+				 * Keep the scroll listener detached while the owning gesture screen is
+				 * closing. On iOS, a bounced ScrollView can keep sending native scroll
+				 * events after the transition gesture activates, which competes with
+				 * close animation work on the UI thread.
+				 */
+				onScroll={scrollEventsEnabled ? composedScrollHandler : undefined}
 				onMomentumScrollEnd={userOnMomentumScrollEnd}
 				onScrollEndDrag={userOnScrollEndDrag}
 				onContentSizeChange={onContentSizeChange}
 				onLayout={onLayout}
-				scrollEventThrottle={scrollableProps.scrollEventThrottle || 16}
+				scrollEventThrottle={
+					scrollEventsEnabled
+						? scrollableProps.scrollEventThrottle || 16
+						: undefined
+				}
 			/>
 		);
 
@@ -78,7 +93,6 @@ export function createTransitionAwareComponent<P extends object>(
 			return scrollableComponent;
 		}
 
-		// If no gesture owner found for this axis, render without GestureDetector
 		return (
 			<GestureDetector gesture={nativeGesture}>
 				{scrollableComponent}

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

@@ -74,7 +74,7 @@ export const NativeScreen = ({
 			return;
 		}
 
-		const focusedIndex = optimisticFocusedIndex.value;
+		const focusedIndex = optimisticFocusedIndex.get();
 		const topIsClosing =
 			topSceneClosing.get() > 0 && focusedIndex >= 0 && focusedIndex < topIndex;
 
@@ -120,7 +120,7 @@ export const NativeScreen = ({
 	const animatedProps = useAnimatedProps(() => {
 		const activity = screenActivity.get();
 		const isClosing = sceneClosing.get() > 0;
-		const activeIndex = optimisticFocusedIndex.value;
+		const activeIndex = optimisticFocusedIndex.get();
 		const isActive = index === activeIndex;
 
 		// Check if the active screen allows passthrough to the screen below

package/src/shared/components/overlay/variations/overlay-host.tsx

@@ -27,7 +27,7 @@ export const OverlayHost = memo(function OverlayHost({
 	const screenAnimation = useScreenAnimation();
 	const relativeProgress = useDerivedValue(() => {
 		"worklet";
-		return screenAnimation.value.stackProgress;
+		return screenAnimation.get().stackProgress;
 	});
 
 	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(

package/src/shared/{utils/gesture → components/screen-container/helpers}/find-collapse-target.ts

@@ -1,5 +1,5 @@
-import { EPSILON } from "../../constants";
-import { sanitizeSnapPoints } from "./validate-snap-points";
+import { EPSILON } from "../../../constants";
+import { sanitizeSnapPoints } from "../../../providers/screen/gestures/shared/snap-points";
 
 interface FindCollapseTargetResult {
 	target: number;
@@ -31,14 +31,25 @@ export function findCollapseTarget(
 			: { target: currentProgress, shouldDismiss: false };
 	}
 
-	const sorted = [...normalized].sort((a, b) => a - b);
-	const minSnap = sorted[0];
+	let minSnap = normalized[0];
+	let nextLowerSnap: number | null = null;
 
-	// Find next lower snap point
-	for (let i = sorted.length - 1; i >= 0; i--) {
-		if (sorted[i] < currentProgress - EPSILON) {
-			return { target: sorted[i], shouldDismiss: false };
+	for (let i = 0; i < normalized.length; i++) {
+		const snap = normalized[i];
+		if (snap < minSnap) {
+			minSnap = snap;
 		}
+
+		if (
+			snap < currentProgress - EPSILON &&
+			(nextLowerSnap === null || snap > nextLowerSnap)
+		) {
+			nextLowerSnap = snap;
+		}
+	}
+
+	if (nextLowerSnap !== null) {
+		return { target: nextLowerSnap, shouldDismiss: false };
 	}
 
 	// At or below min snap → dismiss if allowed

package/src/shared/components/screen-container/hooks/use-backdrop-pointer-events.ts

@@ -1,4 +1,7 @@
+import { useState } from "react";
+import { runOnJS, useAnimatedReaction } from "react-native-reanimated";
 import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useScreenOptionsContext } from "../../../providers/screen/options";
 import { useStackCoreContext } from "../../../providers/stack/core.provider";
 import type { BackdropBehavior } from "../../../types/screen.types";
 import { StackType } from "../../../types/stack.types";
@@ -12,16 +15,33 @@ interface BackdropPointerEventsResult {
 /**
  * Returns pointer events and backdrop behavior based on screen options.
  *
- * - Explicit `backdropBehavior` option takes precedence
+ * - Runtime interpolator `backdropBehavior` takes precedence
+ * - Explicit descriptor `backdropBehavior` option is next
  * - Component stacks default to 'passthrough' (box-none)
  * - Other stacks default to 'block' (undefined = normal touch handling)
  */
 export function useBackdropPointerEvents(): BackdropPointerEventsResult {
 	const { current } = useDescriptors();
+	const screenOptions = useScreenOptionsContext();
 	const { flags } = useStackCoreContext();
+	const [runtimeBackdropBehavior, setRuntimeBackdropBehavior] = useState<
+		BackdropBehavior | undefined
+	>(undefined);
+
+	useAnimatedReaction(
+		() => screenOptions.get().backdropBehavior,
+		(next, previous) => {
+			"worklet";
+			if (next !== previous) {
+				runOnJS(setRuntimeBackdropBehavior)(next);
+			}
+		},
+		[screenOptions],
+	);
 
 	const isComponentStack = flags.STACK_TYPE === StackType.COMPONENT;
 	const backdropBehavior: BackdropBehavior =
+		runtimeBackdropBehavior ??
 		current.options.backdropBehavior ??
 		(isComponentStack ? "passthrough" : "block");