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

package/src/shared/providers/screen/animation/helpers/use-build-transition-state.ts

@@ -19,6 +19,7 @@ import { toPlainRoute, toPlainValue } from "./worklet";
 
 type BuiltState = {
 	progress: SharedValue<number>;
+	effectiveProgress: SharedValue<number>;
 	willAnimate: SharedValue<number>;
 	closing: SharedValue<number>;
 	progressAnimating: SharedValue<number>;
@@ -27,7 +28,7 @@ type BuiltState = {
 	route: BaseStackRoute;
 	meta?: Record<string, unknown>;
 	options: ScreenTransitionOptions;
-	navigationMaskEnabled: boolean;
+	optionsSlot: ScreenTransitionOptions;
 	targetProgress: SharedValue<number>;
 	logicalSettleFrameCount: SharedValue<number>;
 	resolvedAutoSnapPoint: SharedValue<number>;
@@ -44,7 +45,6 @@ export const useBuildTransitionState = (
 	const key = descriptor?.route?.key;
 	const meta = descriptor?.options?.meta;
 	const route = descriptor?.route;
-	const navigationMaskEnabled = !!descriptor?.options?.navigationMaskEnabled;
 	const snapPoints = descriptor?.options?.snapPoints;
 
 	return useMemo(() => {
@@ -63,6 +63,7 @@ export const useBuildTransitionState = (
 
 		return {
 			progress: AnimationStore.getValue(key, "progress"),
+			effectiveProgress: AnimationStore.getValue(key, "effectiveProgress"),
 			willAnimate: AnimationStore.getValue(key, "willAnimate"),
 			closing: AnimationStore.getValue(key, "closing"),
 			entering: AnimationStore.getValue(key, "entering"),
@@ -81,20 +82,12 @@ export const useBuildTransitionState = (
 			route: plainRoute,
 			meta: plainMeta,
 			options: transitionOptions,
-			navigationMaskEnabled,
+			optionsSlot: {},
 			unwrapped: createScreenTransitionState(
 				plainRoute,
 				plainMeta,
-				navigationMaskEnabled,
 				transitionOptions,
 			),
 		};
-	}, [
-		key,
-		meta,
-		route,
-		snapPoints,
-		navigationMaskEnabled,
-		descriptor?.options,
-	]);
+	}, [key, meta, route, snapPoints, descriptor?.options]);
 };

package/src/shared/providers/screen/gestures/shared/policy.ts

@@ -6,6 +6,7 @@ import {
 	DEFAULT_GESTURE_SENSITIVITY,
 	DEFAULT_GESTURE_SNAP_LOCKED,
 	DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	DEFAULT_GESTURE_TRACKING,
 	DEFAULT_GESTURE_VELOCITY_IMPACT,
 	DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR,
 } from "../../../../constants";
@@ -15,6 +16,7 @@ import type {
 	GestureProgressMode,
 } from "../../../../types/gesture.types";
 import type {
+	GestureTracking,
 	ScreenTransitionConfig,
 	SheetScrollGestureBehavior,
 	SnapPoint,
@@ -39,13 +41,13 @@ import {
 import { validateSnapPoints } from "./snap-points";
 
 export type GesturePolicyOptions = {
-	experimental_allowDisabledGestureTracking?: boolean;
 	expandViaScrollView?: boolean;
 	gestureActivationArea?: GestureActivationArea;
 	gestureDirection?: GestureDirection | GestureDirection[];
 	gestureDrivesProgress?: boolean;
 	gestureEnabled?: boolean;
 	gestureProgressMode?: GestureProgressMode;
+	gestureTracking?: GestureTracking;
 	gestureReleaseVelocityScale?: number;
 	gestureResponseDistance?: number;
 	gestureSensitivity?: number;
@@ -144,18 +146,26 @@ export const resolveGestureCanTrack = ({
 	isFirstKey,
 	canDismiss,
 	hasSnapPoints,
-	allowDisabledGestureTracking,
+	gestureTracking = DEFAULT_GESTURE_TRACKING,
 }: {
 	isFirstKey: boolean;
 	canDismiss: boolean;
 	hasSnapPoints: boolean;
-	allowDisabledGestureTracking?: boolean;
+	gestureTracking?: GestureTracking;
 }) => {
 	"worklet";
 	if (isFirstKey) {
 		return false;
 	}
 
+	if (gestureTracking === "never") {
+		return false;
+	}
+
+	if (gestureTracking === "always") {
+		return true;
+	}
+
 	if (canDismiss) {
 		return true;
 	}
@@ -164,7 +174,7 @@ export const resolveGestureCanTrack = ({
 		return true;
 	}
 
-	return allowDisabledGestureTracking === true;
+	return false;
 };
 
 export const resolvePanPolicy = (
@@ -234,8 +244,7 @@ const resolveGestureParticipation = ({
 		isFirstKey,
 		canDismiss,
 		hasSnapPoints: effectiveSnapPoints.hasSnapPoints,
-		allowDisabledGestureTracking:
-			options.experimental_allowDisabledGestureTracking,
+		gestureTracking: options.gestureTracking,
 	});
 	const claimedDirections = computeClaimedDirections(
 		canTrackGesture,
@@ -309,7 +318,11 @@ function resolveRuntimeCanTrackGesture(
 		return false;
 	}
 
-	if (options.experimental_allowDisabledGestureTracking === true) {
+	if (options.gestureTracking === "never") {
+		return false;
+	}
+
+	if (options.gestureTracking === "always") {
 		return true;
 	}
 

package/src/shared/providers/screen/options/helpers.ts

@@ -6,6 +6,7 @@ import {
 	DEFAULT_GESTURE_SENSITIVITY,
 	DEFAULT_GESTURE_SNAP_LOCKED,
 	DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	DEFAULT_GESTURE_TRACKING,
 	DEFAULT_GESTURE_VELOCITY_IMPACT,
 	DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR,
 } from "../../../constants";
@@ -126,6 +127,16 @@ const resolveSheetScrollGestureBehaviorOption = (
 		: fallback;
 };
 
+const resolveGestureTrackingOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"gestureTracking">,
+): RequiredScreenOption<"gestureTracking"> => {
+	"worklet";
+	return value === "auto" || value === "never" || value === "always"
+		? value
+		: fallback;
+};
+
 const resolveBackdropBehaviorOption = (
 	value: unknown,
 	fallback: BackdropBehavior | undefined,
@@ -206,9 +217,9 @@ const areScreenOptionsEqual = (
 ) => {
 	"worklet";
 	return (
+		left.navigationMaskEnabled === right.navigationMaskEnabled &&
 		left.gestureEnabled === right.gestureEnabled &&
-		left.experimental_allowDisabledGestureTracking ===
-			right.experimental_allowDisabledGestureTracking &&
+		left.gestureTracking === right.gestureTracking &&
 		areGestureDirectionsEqual(left.gestureDirection, right.gestureDirection) &&
 		left.gestureSensitivity === right.gestureSensitivity &&
 		left.gestureVelocityImpact === right.gestureVelocityImpact &&
@@ -238,10 +249,14 @@ export const resolveBaseScreenOptions = (
 	);
 
 	return {
+		navigationMaskEnabled: resolveBooleanOption(
+			options.navigationMaskEnabled,
+			undefined,
+		),
 		gestureEnabled: resolveBooleanOption(options.gestureEnabled, undefined),
-		experimental_allowDisabledGestureTracking: resolveBooleanOption(
-			options.experimental_allowDisabledGestureTracking,
-			false,
+		gestureTracking: resolveGestureTrackingOption(
+			options.gestureTracking,
+			DEFAULT_GESTURE_TRACKING,
 		),
 		gestureDirection: resolveGestureDirectionOption(
 			options.gestureDirection,
@@ -322,14 +337,12 @@ export const syncScreenOptionsOverrides = (
 	);
 
 	const next: ScreenOptionsState = {
+		navigationMaskEnabled: base.navigationMaskEnabled,
 		gestureEnabled: resolveBooleanOption(
 			options?.gestureEnabled,
 			base.gestureEnabled,
 		),
-		experimental_allowDisabledGestureTracking: resolveBooleanOption(
-			options?.experimental_allowDisabledGestureTracking,
-			base.experimental_allowDisabledGestureTracking,
-		),
+		gestureTracking: base.gestureTracking,
 		gestureDirection: resolveGestureDirectionOption(
 			options?.gestureDirection,
 			base.gestureDirection,

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

@@ -9,8 +9,9 @@ export type OptionalScreenOption<K extends keyof ScreenTransitionOptions> =
 	ScreenTransitionOptions[K];
 
 export type ScreenOptionsSnapshot = {
+	navigationMaskEnabled: OptionalScreenOption<"navigationMaskEnabled">;
 	gestureEnabled: OptionalScreenOption<"gestureEnabled">;
-	experimental_allowDisabledGestureTracking: RequiredScreenOption<"experimental_allowDisabledGestureTracking">;
+	gestureTracking: RequiredScreenOption<"gestureTracking">;
 	gestureDirection: RequiredScreenOption<"gestureDirection">;
 	gestureSensitivity: RequiredScreenOption<"gestureSensitivity">;
 	gestureVelocityImpact: RequiredScreenOption<"gestureVelocityImpact">;

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
@@ -142,5 +132,5 @@ function withDirectStack<TProps extends DirectStackProps>(
 	};
 }
 
-export { withDirectStack };
 export type { DirectStackContextValue, DirectStackProps, DirectStackScene };
+export { withDirectStack };

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,
 		],
 	);
@@ -138,9 +134,9 @@ function withManagedStack<
 	};
 }
 
-export { useManagedStackContext, withManagedStack };
 export type {
 	ManagedStackContextValue,
 	ManagedStackProps,
 	ManagedStackRenderProps,
 };
+export { useManagedStackContext, withManagedStack };

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/types/animation.types.ts

@@ -23,8 +23,9 @@ import type { BaseStackRoute } from "./stack.types";
  */
 export type ScreenTransitionOptions = Pick<
 	ScreenTransitionConfig,
+	| "navigationMaskEnabled"
 	| "gestureEnabled"
-	| "experimental_allowDisabledGestureTracking"
+	| "gestureTracking"
 	| "gestureDirection"
 	| "gestureSensitivity"
 	| "gestureVelocityImpact"
@@ -227,6 +228,9 @@ export interface ScreenInterpolationProps {
 	/**
 	 * Whether the active transition is visually close enough to its target to be
 	 * treated as complete, even if the animation is still physically settling.
+	 *
+	 * @deprecated Use `active.logicallySettled` instead. Screen settlement state
+	 * belongs on the screen state object.
 	 */
 	logicallySettled: number;
 
@@ -283,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/bounds.types.ts

@@ -14,6 +14,7 @@ import type {
 	TransitionInterpolatedStyle,
 	TransitionSlotStyle,
 } from "./animation.types";
+import type { GestureProgressMode } from "./gesture.types";
 
 /**
  * Target style computation.
@@ -161,11 +162,81 @@ export type BoundsNavigationZoomStyle = TransitionInterpolatedStyle & {
 	[NAVIGATION_MASK_ELEMENT_STYLE_ID]?: TransitionSlotStyle;
 };
 
+export type BoundsNavigationRevealOptions = {
+	/**
+	 * Destination mask border radius.
+	 *
+	 * Reveal interpolates from the measured source border radius to this value.
+	 *
+	 * @default Platform-specific reveal radius
+	 */
+	borderRadius?: number;
+	/**
+	 * Whether the reveal mask should use React Native's continuous border curve.
+	 *
+	 * @default true
+	 */
+	borderContinuous?: boolean;
+	/**
+	 * Maximum dynamic gesture sensitivity applied by reveal.
+	 *
+	 * Reveal lowers gesture sensitivity as the drag gets deeper so the masked
+	 * container can keep its source-to-destination handoff stable. This value
+	 * controls the starting/highest sensitivity in that curve.
+	 *
+	 * @default 0.8
+	 */
+	maxSensitivity?: number;
+	/**
+	 * Velocity-driven depth applied to the dismiss scale handoff.
+	 *
+	 * Higher values make fast releases orbit farther around the final source
+	 * scale. Set to `0` to remove the velocity depth effect.
+	 *
+	 * @default 0.5
+	 */
+	velocityDepth?: number;
+	/**
+	 * Whether gesture displacement should drive transition progress or remain as
+	 * freeform gesture values. Reveal defaults to `"freeform"` so drag can move
+	 * the masked container without owning the whole screen progress.
+	 *
+	 * @default "freeform"
+	 */
+	gestureProgressMode?: GestureProgressMode;
+	/**
+	 * Temporarily blocks pointer-event pass-through on the inactive content until
+	 * the source element transition handoff reaches progress `0.25`.
+	 *
+	 * This is intentional and most users cannot react fast enough to swipe during
+	 * that brief handoff. If it becomes an issue, set this to `false` to disable
+	 * the guard and keep the default behavior that allows pointer events to pass
+	 * through.
+	 *
+	 * @default true
+	 */
+	disablePointerEventsTillElementTransition?: boolean;
+	/**
+	 * How reveal should resize the navigation mask element.
+	 *
+	 * `"auto"` uses the platform default. Android defaults to transform-based
+	 * resizing to avoid masked-size animation cost, while other platforms animate
+	 * width and height. Transform-based resizing can make large border radii look
+	 * less natural on Android; use `"size"` to force width/height animation when
+	 * radius quality is more important than that optimization.
+	 *
+	 * @default "auto"
+	 */
+	maskSizingMode?: "auto" | "transform" | "size";
+};
+
 export type BoundsNavigationRevealStyle = BoundsNavigationZoomStyle;
 
 export type BoundsNavigationAccessor = {
 	zoom: (options?: BoundsNavigationZoomOptions) => BoundsNavigationZoomStyle;
-	reveal: () => BoundsNavigationRevealStyle;
+	reveal: (
+		options?: BoundsNavigationRevealOptions,
+	) => BoundsNavigationRevealStyle;
 };
 
 type BoundsBoundNavigationAccessor = {

package/src/shared/types/index.ts

@@ -15,6 +15,7 @@ export type {
 	BoundsAccessor,
 	BoundsMethod,
 	BoundsNavigationAccessor,
+	BoundsNavigationRevealOptions,
 	BoundsNavigationRevealStyle,
 	BoundsNavigationZoomOpacityRange,
 	BoundsNavigationZoomOpacityRanges,
@@ -32,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

@@ -27,19 +27,13 @@ export type ScreenLayouts = {
 	 * auto snap-point sizing. It is undefined until a real measurement exists.
 	 */
 	content?: Layout;
-	/**
-	 * Whether navigation bounds masking is enabled for this screen.
-	 *
-	 * When enabled, navigation zoom helpers target the masked container path
-	 * instead of the plain content slot.
-	 */
-	navigationMaskEnabled: boolean;
 };
 
 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
@@ -137,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.
-	 *
-	 * 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.
+	 * Controls whether the screen tracks live gesture values.
 	 *
-	 * Screens with `snapPoints` already keep gesture tracking when
-	 * `gestureEnabled={false}`; this flag mainly affects disabled non-snap
-	 * gestures.
+	 * - `"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.
 	 *
-	 * @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.
@@ -206,15 +196,12 @@ export type ScreenTransitionConfig = {
 	gestureReleaseVelocityScale?: number;
 
 	/**
-	 * Caps the absolute post-scale release velocity used by spring animations.
+	 * Deprecated compatibility option.
 	 *
-	 * This does NOT affect dismissal threshold decisions (`gestureVelocityImpact`)
-	 * or snap target selection (`snapVelocityImpact`). It only bounds release
-	 * animation intensity after `gestureReleaseVelocityScale` is applied.
+	 * This option is no longer read by the runtime transition options. Use
+	 * `gestureReleaseVelocityScale` to tune post-release spring energy.
 	 *
-	 * @deprecated v3 compatibility only. This option is removed in the next
-	 * gesture runtime.
-	 * @default 3.2
+	 * @deprecated v3 compatibility only.
 	 */
 	gestureReleaseVelocityMax?: number;
 

package/src/shared/utils/bounds/index.ts

@@ -1,6 +1,7 @@
 import type {
 	BoundsAccessor,
 	BoundsInterpolationProps,
+	BoundsNavigationRevealOptions,
 	BoundsNavigationZoomOptions,
 } from "../../types/bounds.types";
 import { createBoundsAccessorCore } from "./helpers/create-bounds-accessor-core";
@@ -26,11 +27,12 @@ export const createBoundsAccessor = (
 							zoomOptions,
 						});
 					},
-					reveal: () => {
+					reveal: (revealOptions?: BoundsNavigationRevealOptions) => {
 						"worklet";
 						return buildRevealStyles({
 							props,
 							tag,
+							revealOptions,
 						});
 					},
 				},