react-native-screen-transitions 3.6.0-alpha.3 → 3.6.0-beta.0

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

@@ -3,11 +3,13 @@ import { NO_STYLES } from "../../../../constants";
 import { SystemStore } from "../../../../stores/system.store";
 import type {
 	NormalizedTransitionInterpolatedStyle,
+	ScreenStyleInterpolator,
 	TransitionInterpolatedStyle,
 } from "../../../../types/animation.types";
 import { logger } from "../../../../utils/logger";
 import { useScreenAnimationContext } from "../../animation";
 import { useBuildBoundsAccessor } from "../../animation/helpers/accessors/use-build-bounds-accessor";
+import type { ScreenInterpolatorFrame } from "../../animation/helpers/pipeline";
 import { syncSelectedInterpolatorOptions } from "../../animation/helpers/selected-interpolator-options";
 import { useDescriptorDerivations } from "../../descriptors";
 import {
@@ -16,10 +18,93 @@ import {
 } from "../../options";
 import { normalizeSlots } from "../helpers/normalize-slots";
 import { preserveAnimatedPropsOnly } from "../helpers/preserve-animated-props-only";
+import type { LocalStyleLayers } from "../helpers/resolve-slot-styles";
 import { stripInterpolatorOptions } from "../helpers/strip-interpolator-options";
 
+const NO_STYLE_LAYERS: LocalStyleLayers = [];
+
+type InterpolatorResult = {
+	stylesMap: NormalizedTransitionInterpolatedStyle;
+	rawStyleMap: TransitionInterpolatedStyle | undefined;
+};
+
+type RunInterpolatorParams = {
+	interpolator: ScreenStyleInterpolator | undefined;
+	props: ScreenInterpolatorFrame;
+	progress: ScreenInterpolatorFrame["progress"];
+	next: ScreenInterpolatorFrame["next"];
+	bounds: Parameters<ScreenStyleInterpolator>[0]["bounds"];
+	shouldDeferStyleBuckets: boolean;
+};
+
+const normalizeRawStyleMap = (
+	rawStyleMap: TransitionInterpolatedStyle | undefined,
+	shouldDeferStyleBuckets: boolean,
+) => {
+	"worklet";
+
+	if (!rawStyleMap) {
+		return NO_STYLES;
+	}
+
+	const stylesMap = normalizeSlots(stripInterpolatorOptions(rawStyleMap));
+
+	return shouldDeferStyleBuckets
+		? preserveAnimatedPropsOnly(stylesMap)
+		: stylesMap;
+};
+
+const runInterpolator = ({
+	interpolator,
+	props,
+	progress,
+	next,
+	bounds,
+	shouldDeferStyleBuckets,
+}: RunInterpolatorParams): InterpolatorResult | undefined => {
+	"worklet";
+
+	if (!interpolator) {
+		return undefined;
+	}
+
+	try {
+		const raw = interpolator({
+			...props,
+			progress,
+			next,
+			bounds,
+		});
+
+		const rawStyleMap: TransitionInterpolatedStyle | undefined =
+			typeof raw === "object" && raw != null ? raw : undefined;
+
+		return {
+			rawStyleMap,
+			stylesMap: normalizeRawStyleMap(rawStyleMap, shouldDeferStyleBuckets),
+		};
+	} catch (_) {
+		if (__DEV__) {
+			logger.warn("screenStyleInterpolator must be a worklet");
+		}
+
+		return undefined;
+	}
+};
+
+const appendLayer = (
+	layers: LocalStyleLayers,
+	result: InterpolatorResult | undefined,
+) => {
+	"worklet";
+
+	if (result) {
+		layers.push(result.stylesMap);
+	}
+};
+
 /**
- * Builds the raw interpolated styles map for the current screen pass.
+ * Builds the raw interpolated style layers for the current screen pass.
  *
  * This hook exists to stabilize style ownership during rapid navigation,
  * especially when an interactive close gesture overlaps with a new navigation
@@ -39,9 +124,9 @@ import { stripInterpolatorOptions } from "../helpers/strip-interpolator-options"
  * hidden window so animated props and runtime options stay warm, but defer style
  * buckets so measurement sees the final untransformed layout.
  *
- * The result stays as a single slot map. Resolution happens downstream, where
- * slot ids determine whether a slot may inherit from ancestors or must remain
- * local to the owning screen container.
+ * The result is ordered from lowest to highest priority. Resolution happens
+ * downstream, where slot ids determine whether slots inherit from ancestors and
+ * where higher owner layers override lower owner layers per key.
  */
 export const useInterpolatedStylesMap = () => {
 	const { currentScreenKey } = useDescriptorDerivations();
@@ -61,7 +146,7 @@ export const useInterpolatedStylesMap = () => {
 
 	const isGesturingDuringCloseAnimation = useSharedValue(false);
 
-	return useDerivedValue<NormalizedTransitionInterpolatedStyle>(() => {
+	return useDerivedValue<LocalStyleLayers>(() => {
 		"worklet";
 		screenInterpolatorPropsRevision.get();
 		const props = screenInterpolatorProps.get();
@@ -99,16 +184,6 @@ export const useInterpolatedStylesMap = () => {
 
 		const interpolatorOptionsOwner =
 			isInGestureMode || !nextInterpolator ? "current" : "next";
-		const interpolator =
-			interpolatorOptionsOwner === "current"
-				? currentInterpolator
-				: nextInterpolator;
-
-		if (!interpolator) {
-			syncSelectedInterpolatorOptions(selectedInterpolatorOptions, "current");
-			syncScreenOptionsOverrides(undefined, screenOptions);
-			return NO_STYLES;
-		}
 
 		let effectiveProgress = progress;
 		let effectiveNext = next;
@@ -118,42 +193,55 @@ export const useInterpolatedStylesMap = () => {
 			effectiveNext = undefined;
 		}
 
-		try {
-			const raw = interpolator({
-				...props,
-				progress: effectiveProgress,
-				next: effectiveNext,
-				bounds: boundsAccessor,
-			});
-
-			const rawStyleMap: TransitionInterpolatedStyle | undefined =
-				typeof raw === "object" && raw != null ? raw : undefined;
+		const currentResult = runInterpolator({
+			interpolator: currentInterpolator,
+			props,
+			progress: effectiveProgress,
+			next: effectiveNext,
+			bounds: boundsAccessor,
+			shouldDeferStyleBuckets,
+		});
 
+		if (interpolatorOptionsOwner === "current") {
 			syncSelectedInterpolatorOptions(
 				selectedInterpolatorOptions,
-				interpolatorOptionsOwner,
-				rawStyleMap?.options,
-			);
-			syncScreenOptionsOverrides(
-				interpolatorOptionsOwner === "current" ? rawStyleMap : undefined,
-				screenOptions,
+				"current",
+				currentResult?.rawStyleMap?.options,
 			);
+			syncScreenOptionsOverrides(currentResult?.rawStyleMap, screenOptions);
 
-			const stylesMap = !rawStyleMap
-				? NO_STYLES
-				: normalizeSlots(stripInterpolatorOptions(rawStyleMap));
-
-			return shouldDeferStyleBuckets
-				? preserveAnimatedPropsOnly(stylesMap)
-				: stylesMap;
-		} catch (_) {
-			if (__DEV__) {
-				logger.warn("screenStyleInterpolator must be a worklet");
+			if (!currentResult) {
+				return NO_STYLE_LAYERS;
 			}
 
-			syncSelectedInterpolatorOptions(selectedInterpolatorOptions, "current");
-			syncScreenOptionsOverrides(undefined, screenOptions);
-			return NO_STYLES;
+			return [currentResult.stylesMap];
 		}
+
+		const nextResult = runInterpolator({
+			interpolator: nextInterpolator,
+			props,
+			progress: effectiveProgress,
+			next: effectiveNext,
+			bounds: boundsAccessor,
+			shouldDeferStyleBuckets,
+		});
+
+		syncSelectedInterpolatorOptions(
+			selectedInterpolatorOptions,
+			"next",
+			nextResult?.rawStyleMap?.options,
+		);
+		syncScreenOptionsOverrides(undefined, screenOptions);
+
+		const layers: LocalStyleLayers = [];
+
+		appendLayer(layers, currentResult);
+		appendLayer(layers, nextResult);
+
+		if (layers.length === 0) {
+			return NO_STYLE_LAYERS;
+		}
+
+		return layers;
 	});
 };

package/src/shared/providers/screen/styles/hooks/use-resolved-slot-style-map.tsx

@@ -7,18 +7,19 @@ import { NO_STYLES } from "../../../../constants";
 import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
 import { useScreenAnimationContext } from "../../animation";
 import {
+	type LocalStyleLayers,
 	type ResettableStyleStatesBySlot,
 	resolveSlotStyles,
 	reuseEqualResolvedSlots,
 } from "../helpers/resolve-slot-styles";
 
 interface UseResolvedStylesMapParams {
-	currentStylesMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
+	localStylesMaps: SharedValue<LocalStyleLayers>;
 	ancestorStylesMap?: SharedValue<NormalizedTransitionInterpolatedStyle>;
 }
 
 export const useResolvedStylesMap = ({
-	currentStylesMap,
+	localStylesMaps,
 	ancestorStylesMap,
 }: UseResolvedStylesMapParams) => {
 	const { screenInterpolatorProps, screenInterpolatorPropsRevision } =
@@ -34,13 +35,14 @@ export const useResolvedStylesMap = ({
 		screenInterpolatorPropsRevision.get();
 
 		const props = screenInterpolatorProps.get();
-		// Keep missing local slots alive while another route drives this screen.
-		// Custom ids and keys from slots that still exist are still reset.
+		// Keep missing local slots alive only when another route drives this screen
+		// and no active local style layer is available. Once a current/next layer
+		// runs, omitted local slots and dropped keys are intentional reset signals.
 		const deferLocalSlotResets = !props.focused && !props.current.closing;
 
 		const { resolvedStylesMap, nextPreviousStyleStatesBySlot } =
 			resolveSlotStyles({
-				currentStylesMap: currentStylesMap.get(),
+				localStylesMaps: localStylesMaps.get(),
 				ancestorStylesMap: ancestorStylesMap?.get() ?? NO_STYLES,
 				previousStyleStatesBySlot: previousStyleStatesBySlot.get(),
 				deferLocalSlotResets,

package/src/shared/providers/screen/styles/styles.provider.tsx

@@ -26,10 +26,10 @@ export const {
 })<Props, ScreenStylesContextValue>(({ children, isFloatingOverlay }) => {
 	const parentContext = useContext(ScreenStylesContext);
 
-	const rawStylesMap = useInterpolatedStylesMap();
+	const rawStylesMaps = useInterpolatedStylesMap();
 
 	const stylesMap = useResolvedStylesMap({
-		currentStylesMap: rawStylesMap,
+		localStylesMaps: rawStylesMaps,
 		ancestorStylesMap: parentContext?.stylesMap,
 	});
 

package/src/shared/providers/stack/direct.provider.tsx

@@ -79,8 +79,7 @@ function useDirectStackValue(
 		};
 	}, [state.routes, state.preloadedRoutes, preloadedDescriptors, descriptors]);
 
-	const { stackProgress, optimisticFocusedIndex } =
-		useStackDerived(animationMaps);
+	const { optimisticFocusedIndex } = useStackDerived(animationMaps);
 
 	const focusedIndex = state.index;
 
@@ -91,18 +90,9 @@ function useDirectStackValue(
 			routeKeys,
 			routes: allRoutes,
 			scenes,
-			stackProgress,
 			optimisticFocusedIndex,
 		}),
-		[
-			flags,
-			navigatorKey,
-			routeKeys,
-			allRoutes,
-			scenes,
-			stackProgress,
-			optimisticFocusedIndex,
-		],
+		[flags, navigatorKey, routeKeys, allRoutes, scenes, optimisticFocusedIndex],
 	);
 
 	// DirectStack context value

package/src/shared/providers/stack/helpers/use-stack-derived.ts

@@ -1,9 +1,9 @@
 import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
 import type { AnimationStoreMap } from "../../../stores/animation.store";
 
+type StackDerivedAnimationMap = Pick<AnimationStoreMap, "closing">;
+
 export interface StackDerived {
-	/** Sum of all individual screen progress values. */
-	stackProgress: DerivedValue<number>;
 	/**
 	 * Focused index that accounts for closing screens.
 	 * Counts consecutive closing screens from the top so that
@@ -13,21 +13,12 @@ export interface StackDerived {
 }
 
 /**
- * Derives aggregated stack progress and an optimistic focused index
- * from animation store maps. Shared between managed and direct providers.
+ * Derives an optimistic focused index from animation store maps.
+ * Shared between managed and direct providers.
  */
 export function useStackDerived(
-	animationMaps: AnimationStoreMap[],
+	animationMaps: StackDerivedAnimationMap[],
 ): StackDerived {
-	const stackProgress = useDerivedValue(() => {
-		"worklet";
-		let total = 0;
-		for (let i = 0; i < animationMaps.length; i++) {
-			total += animationMaps[i].progress.get();
-		}
-		return total;
-	});
-
 	const optimisticFocusedIndex = useDerivedValue(() => {
 		"worklet";
 		const lastIndex = animationMaps.length - 1;
@@ -39,5 +30,5 @@ export function useStackDerived(
 		return lastIndex - closingFromTop;
 	});
 
-	return { stackProgress, optimisticFocusedIndex };
+	return { optimisticFocusedIndex };
 }

package/src/shared/providers/stack/managed.provider.tsx

@@ -47,9 +47,7 @@ function useManagedStackValue<
 	const navigatorKey = props.state.key;
 
 	const processed = useProcessedRoutes(state.routes, state.descriptors);
-	const { stackProgress, optimisticFocusedIndex } = useStackDerived(
-		processed.animationMaps,
-	);
+	const { optimisticFocusedIndex } = useStackDerived(processed.animationMaps);
 	const closingRouteMap = useClosingRouteMap(
 		processed.routeKeys,
 		processed.animationMaps,
@@ -65,7 +63,6 @@ function useManagedStackValue<
 			routeKeys: processed.routeKeys,
 			routes: state.routes as Route<string>[],
 			scenes: processed.scenes as BaseStackScene[],
-			stackProgress,
 			optimisticFocusedIndex,
 		}),
 		[
@@ -74,7 +71,6 @@ function useManagedStackValue<
 			processed.routeKeys,
 			state.routes,
 			processed.scenes,
-			stackProgress,
 			optimisticFocusedIndex,
 		],
 	);

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

@@ -7,6 +7,7 @@ import { createStore } from "../utils/create-store";
 
 export type AnimationStoreMap = {
 	progress: SharedValue<number>;
+	effectiveProgress: SharedValue<number>;
 	willAnimate: SharedValue<number>;
 	progressAnimating: SharedValue<number>;
 	closing: SharedValue<number>;
@@ -16,6 +17,7 @@ export type AnimationStoreMap = {
 function createAnimationBag(): AnimationStoreMap {
 	return {
 		progress: makeMutable(0),
+		effectiveProgress: makeMutable(0),
 		willAnimate: makeMutable(0),
 		closing: makeMutable(0),
 		progressAnimating: makeMutable(0),
@@ -24,14 +26,15 @@ function createAnimationBag(): AnimationStoreMap {
 }
 
 /**
- * Route-keyed screen transition state for the public animation lifecycle. These
- * shared values track the current progress, whether a transition is about to
- * begin, and whether a screen is entering, closing, or actively animating.
+ * 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.
  */
 export const AnimationStore = createStore<AnimationStoreMap>({
 	createBag: createAnimationBag,
 	disposeBag: (bag) => {
 		cancelAnimation(bag.progress);
+		cancelAnimation(bag.effectiveProgress);
 		cancelAnimation(bag.willAnimate);
 		cancelAnimation(bag.progressAnimating);
 		cancelAnimation(bag.closing);

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

@@ -216,6 +216,20 @@ const isCompletedLink = (link: TagLink | null): link is TagLink => {
 	return !!link?.destination;
 };
 
+const getPendingSourceLink = (
+	state: LinkPairsState,
+	pairKey: ScreenPairKey,
+	linkKey: LinkKey,
+): TagLink | null => {
+	"worklet";
+	const sourceScreenKey = getSourceScreenKeyFromPairKey(pairKey);
+	const pendingPairKey = createPendingPairKey(sourceScreenKey);
+
+	if (pendingPairKey === pairKey) return null;
+
+	return getPairLink(state, pendingPairKey, linkKey);
+};
+
 function getResolvedLink(
 	pairKey: ScreenPairKey,
 	tag: TagID,
@@ -226,12 +240,22 @@ function getResolvedLink(
 	const group = getGroupKeyFromTag(tag);
 	const requestedLink = getPairLink(state, pairKey, linkKey);
 
+	// Press-triggered zoom captures the source before navigation under a pending
+	// source<> pair. If the destination screen has no Boundary.View, nothing
+	// promotes that source into source<>destination, but zoom can still animate to
+	// its default top target from the pending source bounds.
+	const fallbackPendingLink = requestedLink
+		? null
+		: getPendingSourceLink(state, pairKey, linkKey);
+
+	const link = requestedLink ?? fallbackPendingLink;
+
 	// Group active ids can update before the new member has a full source/destination
 	// link, so unresolved grouped links fall back to the initial id's measurements.
-	if (!group || isCompletedLink(requestedLink)) {
+	if (!group || isCompletedLink(link)) {
 		return {
 			tag,
-			link: requestedLink,
+			link,
 		};
 	}
 
@@ -248,7 +272,7 @@ function getResolvedLink(
 
 	return {
 		tag,
-		link: requestedLink,
+		link,
 	};
 }
 

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

@@ -25,7 +25,7 @@ export type ScreenTransitionOptions = Pick<
 	ScreenTransitionConfig,
 	| "navigationMaskEnabled"
 	| "gestureEnabled"
-	| "experimental_allowDisabledGestureTracking"
+	| "gestureTracking"
 	| "gestureDirection"
 	| "gestureSensitivity"
 	| "gestureVelocityImpact"
@@ -287,13 +287,17 @@ export type TransitionSlotStyle = AnimatedViewStyle | TransitionSlotDefinition;
  * Runtime options returned by `screenStyleInterpolator`.
  *
  * These values are not style slots. They are derived per frame and consumed by
- * the transition runtime.
+ * the transition runtime. Structural options that change the React tree, such
+ * as `navigationMaskEnabled`, must be configured statically on the screen.
  *
  * If `gestureSensitivity` is derived from the current gesture, prefer
  * `active.gesture.raw` so the sensitivity calculation does not feed back into
  * itself.
  */
-export type TransitionInterpolatorOptions = ScreenTransitionOptions;
+export type TransitionInterpolatorOptions = Omit<
+	ScreenTransitionOptions,
+	"navigationMaskEnabled" | "gestureTracking"
+>;
 
 /**
  * Internal normalized slot format.

package/src/shared/types/index.ts

@@ -33,6 +33,7 @@ export type {
 } from "./gesture.types";
 export type { OverlayProps } from "./overlay.types";
 export type {
+	GestureTracking,
 	Layout,
 	ScreenKey,
 	ScreenTransitionConfig,

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

@@ -33,6 +33,7 @@ export type ScreenKey = string;
 export type SheetScrollGestureBehavior =
 	| "expand-and-collapse"
 	| "collapse-only";
+export type GestureTracking = "auto" | "never" | "always";
 
 /**
  * A single snap point value. Either a fraction of screen height (0–1) or
@@ -130,21 +131,17 @@ export type ScreenTransitionConfig = {
 	gestureEnabled?: boolean;
 
 	/**
-	 * Allows screens with `gestureEnabled={false}` to still activate gestures for
-	 * live gesture values while preventing gesture dismissal.
+	 * Controls whether the screen tracks live gesture values.
 	 *
-	 * This is a v3 compatibility bridge for the next gesture behavior. Direction
-	 * ownership/claims participate while this is enabled so nested screens can
-	 * intentionally shadow parent gestures for resistance-style animations.
+	 * - `"auto"` tracks gestures when dismissal is enabled, or when snap points
+	 *   can move without dismissal.
+	 * - `"never"` disables gesture tracking for the screen.
+	 * - `"always"` keeps tracking live gesture values even when
+	 *   `gestureEnabled` is `false`, without allowing dismiss.
 	 *
-	 * Screens with `snapPoints` already keep gesture tracking when
-	 * `gestureEnabled={false}`; this flag mainly affects disabled non-snap
-	 * gestures.
-	 *
-	 * @experimental This API may change in future versions.
-	 * @default false
+	 * @default "auto"
 	 */
-	experimental_allowDisabledGestureTracking?: boolean;
+	gestureTracking?: GestureTracking;
 
 	/**
 	 * The direction(s) of the screen gesture used to dismiss the screen.

package/src/shared/utils/bounds/navigation/reveal/build.ts

@@ -328,7 +328,6 @@ export function buildRevealStyles({
 
 		return {
 			options: {
-				navigationMaskEnabled: true,
 				gestureProgressMode,
 				gestureSensitivity,
 				gestureReleaseVelocityScale,
@@ -424,7 +423,6 @@ export function buildRevealStyles({
 
 	return {
 		options: {
-			navigationMaskEnabled: true,
 			gestureProgressMode,
 		},
 		content: {

package/src/shared/utils/bounds/navigation/zoom/build.ts

@@ -416,6 +416,10 @@ export function buildZoomStyles({
 		Math.abs(unfocusedContentScale),
 		EPSILON,
 	);
+	// A naturally settled close can leave this as the last emitted style frame,
+	// so drop temporary stacking here instead of waiting for a later reset pass.
+	const shouldElevateUnfocusedElement =
+		!props.active.closing || !props.active.logicallySettled;
 
 	const scaleShiftX = computeCenterScaleShift({
 		center: elementCenterX,
@@ -480,8 +484,8 @@ export function buildZoomStyles({
 					},
 				],
 				opacity: zoomOptions?.debug ? 1 : unfocusedFade,
-				zIndex: 9999,
-				elevation: 9999,
+				zIndex: shouldElevateUnfocusedElement ? 9999 : 0,
+				elevation: shouldElevateUnfocusedElement ? 9999 : 0,
 			};
 
 	return {