react-native-screen-transitions 3.7.0-alpha.0 → 3.7.0-beta.1

package/src/shared/adapters/with-screen-transitions/options.ts

@@ -1,4 +1,3 @@
-import type { ScreenProps } from "react-native-screens";
 import type { ScreenTransitionConfig } from "../../types";
 
 type NativeStackTransitionResetOptions = {
@@ -8,26 +7,14 @@ type NativeStackTransitionResetOptions = {
 	gestureEnabled: false;
 };
 
-export type NativeStackNativeGestureOptions = {
-	nativeGestureEnabled?: boolean;
-	nativeGestureDirection?: ScreenProps["swipeDirection"];
-	nativeGestureResponseDistance?: ScreenProps["gestureResponseDistance"];
-};
-
-export type ScreenTransitionDescriptorOptions = ScreenTransitionConfig & {
+export type AdapterDescriptorOptions = ScreenTransitionConfig & {
 	enableTransitions?: boolean;
-	screenTransition?: ScreenTransitionConfig | null | false;
 };
 
 export type NativeStackAdapterOptions<
 	TNativeOptions extends object = Record<string, unknown>,
-> = Omit<
-	TNativeOptions,
-	| keyof ScreenTransitionDescriptorOptions
-	| keyof NativeStackNativeGestureOptions
-> &
-	ScreenTransitionDescriptorOptions &
-	NativeStackNativeGestureOptions;
+> = Omit<TNativeOptions, keyof AdapterDescriptorOptions> &
+	AdapterDescriptorOptions;
 
 const NATIVE_STACK_TRANSITION_RESET_OPTIONS: NativeStackTransitionResetOptions =
 	{
@@ -37,14 +24,15 @@ const NATIVE_STACK_TRANSITION_RESET_OPTIONS: NativeStackTransitionResetOptions =
 		gestureEnabled: false,
 	};
 
-const COLLIDING_TRANSITION_OPTION_KEYS = [
-	"gestureEnabled",
-	"gestureDirection",
-	"gestureResponseDistance",
-] as const satisfies readonly (keyof ScreenTransitionConfig)[];
+type GestureEnabledRestore = {
+	gestureEnabled: ScreenTransitionConfig["gestureEnabled"];
+	hasGestureEnabled: boolean;
+};
 
-type CollidingTransitionOptionKey =
-	(typeof COLLIDING_TRANSITION_OPTION_KEYS)[number];
+const gestureEnabledRestoreByAdaptedOptions = new WeakMap<
+	Record<string, unknown>,
+	GestureEnabledRestore
+>();
 
 export type NativeStackAdapterOptionInput =
 	| Record<string, unknown>
@@ -54,63 +42,6 @@ function isPlainOptions(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
-function extractCollidingTransitionOptions(
-	options: Record<string, unknown>,
-): ScreenTransitionConfig | undefined {
-	let screenTransition: ScreenTransitionConfig | undefined;
-
-	for (const key of COLLIDING_TRANSITION_OPTION_KEYS) {
-		if (!(key in options)) {
-			continue;
-		}
-
-		screenTransition ??= {};
-		screenTransition[key] = options[key] as never;
-	}
-
-	return screenTransition;
-}
-
-function removeCollidingTransitionOptions<
-	TOptions extends Record<string, unknown>,
->(options: TOptions): Omit<TOptions, CollidingTransitionOptionKey> {
-	const nativeOptions = { ...options };
-
-	for (const key of COLLIDING_TRANSITION_OPTION_KEYS) {
-		delete nativeOptions[key];
-	}
-
-	return nativeOptions;
-}
-
-function applyNativeGestureAliases<TOptions extends Record<string, unknown>>(
-	options: TOptions,
-): TOptions {
-	const nativeOptions: Record<string, unknown> = { ...options };
-	const {
-		nativeGestureEnabled,
-		nativeGestureDirection,
-		nativeGestureResponseDistance,
-	} = options;
-	delete nativeOptions.nativeGestureEnabled;
-	delete nativeOptions.nativeGestureDirection;
-	delete nativeOptions.nativeGestureResponseDistance;
-
-	if (nativeGestureEnabled !== undefined) {
-		nativeOptions.gestureEnabled = nativeGestureEnabled;
-	}
-
-	if (nativeGestureDirection !== undefined) {
-		nativeOptions.gestureDirection = nativeGestureDirection;
-	}
-
-	if (nativeGestureResponseDistance !== undefined) {
-		nativeOptions.gestureResponseDistance = nativeGestureResponseDistance;
-	}
-
-	return nativeOptions as TOptions;
-}
-
 export function adaptNativeStackTransitionOptions<
 	TOptions extends NativeStackAdapterOptionInput | undefined,
 >(options: TOptions): TOptions {
@@ -123,50 +54,48 @@ export function adaptNativeStackTransitionOptions<
 		return options;
 	}
 
-	const inlineScreenTransition = extractCollidingTransitionOptions(options);
-	const explicitScreenTransition = options.screenTransition;
-	const hasTransitionsEnabled =
-		options.enableTransitions === true || !!explicitScreenTransition;
+	const hasTransitionsEnabled = options.enableTransitions === true;
 
 	if (!hasTransitionsEnabled) {
-		return applyNativeGestureAliases(options) as TOptions;
+		return options;
 	}
 
-	const nativeOptions = applyNativeGestureAliases(
-		removeCollidingTransitionOptions(options),
-	);
-	const nativeGestureEnabled = nativeOptions.gestureEnabled;
-	const screenTransition =
-		explicitScreenTransition && isPlainOptions(explicitScreenTransition)
-			? {
-					...inlineScreenTransition,
-					...explicitScreenTransition,
-				}
-			: inlineScreenTransition;
-
-	return {
+	const nativeOptions = options as Record<string, unknown>;
+	const adaptedOptions: Record<string, unknown> = {
 		...nativeOptions,
 		...NATIVE_STACK_TRANSITION_RESET_OPTIONS,
-		...(nativeGestureEnabled !== undefined
-			? { gestureEnabled: nativeGestureEnabled }
-			: null),
 		enableTransitions: true,
-		...(screenTransition ? { screenTransition } : null),
-	} as TOptions;
+	};
+	gestureEnabledRestoreByAdaptedOptions.set(adaptedOptions, {
+		gestureEnabled:
+			nativeOptions.gestureEnabled as ScreenTransitionConfig["gestureEnabled"],
+		hasGestureEnabled: "gestureEnabled" in nativeOptions,
+	});
+
+	return adaptedOptions as TOptions;
 }
 
-export function resolveScreenTransitionOptions<
-	TOptions extends ScreenTransitionDescriptorOptions,
+export function resolveAdapterTransitionOptions<
+	TOptions extends AdapterDescriptorOptions,
 >(options: TOptions): TOptions & ScreenTransitionConfig {
-	const screenTransition = options.screenTransition;
+	const gestureEnabledRestore = gestureEnabledRestoreByAdaptedOptions.get(
+		options as Record<string, unknown>,
+	);
 
-	if (!screenTransition) {
+	if (!gestureEnabledRestore) {
 		return options;
 	}
 
-	return {
+	const resolvedOptions = {
 		...options,
-		...screenTransition,
 		enableTransitions: true,
 	};
+
+	if (gestureEnabledRestore.hasGestureEnabled) {
+		resolvedOptions.gestureEnabled = gestureEnabledRestore.gestureEnabled;
+	} else {
+		delete resolvedOptions.gestureEnabled;
+	}
+
+	return resolvedOptions;
 }

package/src/shared/adapters/with-screen-transitions/stack-layout.tsx

@@ -24,8 +24,8 @@ import {
 	useScreenTransitionsAdapterContext,
 } from "./context";
 import {
-	resolveScreenTransitionOptions,
-	type ScreenTransitionDescriptorOptions,
+	type AdapterDescriptorOptions,
+	resolveAdapterTransitionOptions,
 } from "./options";
 import type {
 	NavigatorLayout,
@@ -63,8 +63,8 @@ function normalizeDescriptor(
 ): BaseStackDescriptor {
 	return {
 		...descriptor,
-		options: resolveScreenTransitionOptions(
-			descriptor.options as ScreenTransitionDescriptorOptions,
+		options: resolveAdapterTransitionOptions(
+			descriptor.options as AdapterDescriptorOptions,
 		),
 	};
 }
@@ -119,7 +119,7 @@ function buildTransitionStackState({
 
 		if (
 			!shouldShowFloatOverlay &&
-			(normalizedDescriptor.options as ScreenTransitionDescriptorOptions)
+			(normalizedDescriptor.options as AdapterDescriptorOptions)
 				.enableTransitions &&
 			isOverlayVisible(normalizedDescriptor.options)
 		) {

package/src/shared/components/activity/helpers.ts

@@ -5,4 +5,4 @@ export type { InactiveBehavior } from "../../types/screen.types";
 
 export const DEFAULT_INACTIVE_BEHAVIOR: InactiveBehavior = IS_WEB
 	? "unmount"
-	: "detach";
+	: "hide";

package/src/shared/components/activity/variants/activity-screen.tsx

@@ -79,14 +79,15 @@ export const ActivityScreen = memo(function ActivityScreen({
 			// a blank frame during the transition.
 			activityState = 1;
 			visible = true;
-		} else if (inactiveBehavior === "freeze") {
+		} else if (inactiveBehavior === "pause") {
 			activityState = 1;
 			shouldFreeze = true;
 			visible = true;
 		} else {
-			// `detach` hides native presentation. Non-nested `unmount`
-			// removes the React subtree through the JS guard below.
+			// `hide` freezes and hides native presentation. Non-nested
+			// `unmount` removes the React subtree through the JS guard below.
 			activityState = 0;
+			shouldFreeze = true;
 			visible = false;
 		}
 	}

package/src/shared/index.ts

@@ -26,11 +26,7 @@ export default {
 	Specs,
 };
 
-export type {
-	NativeStackAdapterOptions,
-	NativeStackNativeGestureOptions,
-	ScreenTransitionDescriptorOptions,
-} from "./adapters/with-screen-transitions";
+export type { NativeStackAdapterOptions } from "./adapters/with-screen-transitions";
 export { withScreenTransitions } from "./adapters/with-screen-transitions";
 export { snapTo } from "./animation/snap-to";
 export {

package/src/shared/providers/screen/styles/helpers/resolve-slot-styles/index.ts

@@ -17,7 +17,6 @@ type ResolveSlotStylesContext = {
 	localStylesMaps: LocalStyleLayers;
 	ancestorStylesMap: NormalizedTransitionInterpolatedStyle;
 	previousStyleStatesBySlot: ResettableStyleStatesBySlot;
-	deferLocalSlotResets: boolean;
 	resolvedStylesMap: NormalizedTransitionInterpolatedStyle;
 	nextPreviousStyleStatesBySlot: ResettableStyleStatesBySlot;
 };
@@ -75,42 +74,32 @@ const hasResettableDisappearedKeys = (
 const getResolvedSlotOutput = ({
 	slot,
 	previousState,
-	resetDroppedKeys,
-	carryPreviousState,
 }: {
 	slot: NormalizedTransitionSlotStyle | undefined;
 	previousState: ResettableStyleState | undefined;
-	resetDroppedKeys: boolean;
-	carryPreviousState: boolean;
 }) => {
 	"worklet";
 	const state = getResolvedSlotState(slot);
 
-	const hasStyleResetPatch =
-		resetDroppedKeys &&
-		hasResettableDisappearedKeys(
-			previousState?.styleKeys,
-			previousState?.styleResetValues,
-			state.styleKeys,
-		);
-	const hasPropResetPatch =
-		resetDroppedKeys &&
-		hasResettableDisappearedKeys(
-			previousState?.propKeys,
-			previousState?.propResetValues,
-			state.propKeys,
-		);
+	const hasStyleResetPatch = hasResettableDisappearedKeys(
+		previousState?.styleKeys,
+		previousState?.styleResetValues,
+		state.styleKeys,
+	);
+	const hasPropResetPatch = hasResettableDisappearedKeys(
+		previousState?.propKeys,
+		previousState?.propResetValues,
+		state.propKeys,
+	);
 	const hasResetPatch = hasEitherResetPatch(
 		hasStyleResetPatch,
 		hasPropResetPatch,
 	);
-	const nextState =
-		state.nextState ?? (carryPreviousState ? previousState : undefined);
 
 	if (!hasResetPatch) {
 		return {
 			resolvedSlot: getForwardedSlot(slot, state.hasAnyKeys),
-			nextState,
+			nextState: state.nextState,
 		};
 	}
 
@@ -126,15 +115,10 @@ const getResolvedSlotOutput = ({
 			hasStyleResetPatch,
 			hasPropResetPatch,
 		}),
-		nextState,
+		nextState: state.nextState,
 	};
 };
 
-const hasLocalStyleSource = (context: ResolveSlotStylesContext) => {
-	"worklet";
-	return context.localStylesMaps.length > 0;
-};
-
 const hasLocalSlot = (context: ResolveSlotStylesContext, slotId: string) => {
 	"worklet";
 
@@ -147,25 +131,6 @@ const hasLocalSlot = (context: ResolveSlotStylesContext, slotId: string) => {
 	return false;
 };
 
-const shouldDeferMissingLocalSlotReset = (
-	context: ResolveSlotStylesContext,
-	slotId: string,
-) => {
-	"worklet";
-	const canInherit = shouldSlotInherit(slotId);
-	const localSlotExists = hasLocalSlot(context, slotId);
-	const hasInheritedSlot =
-		canInherit && context.ancestorStylesMap[slotId] !== undefined;
-
-	return (
-		context.deferLocalSlotResets &&
-		!hasLocalStyleSource(context) &&
-		!canInherit &&
-		!localSlotExists &&
-		!hasInheritedSlot
-	);
-};
-
 const mergeBucket = (
 	resolvedBucket: Record<string, unknown> | undefined,
 	source: Record<string, unknown> | undefined,
@@ -421,12 +386,9 @@ const appendResolvedSlot = (
 	slotId: string,
 ) => {
 	"worklet";
-	const shouldDeferReset = shouldDeferMissingLocalSlotReset(context, slotId);
 	const { resolvedSlot, nextState } = getResolvedSlotOutput({
 		slot: getSlotForId(context, slotId),
 		previousState: context.previousStyleStatesBySlot[slotId],
-		resetDroppedKeys: !shouldDeferReset,
-		carryPreviousState: shouldDeferReset,
 	});
 
 	writeResolvedSlotOutput({
@@ -505,12 +467,10 @@ export const resolveSlotStyles = ({
 	localStylesMaps,
 	ancestorStylesMap,
 	previousStyleStatesBySlot,
-	deferLocalSlotResets = false,
 }: {
 	localStylesMaps: LocalStyleLayers;
 	ancestorStylesMap: NormalizedTransitionInterpolatedStyle;
 	previousStyleStatesBySlot: ResettableStyleStatesBySlot;
-	deferLocalSlotResets?: boolean;
 }) => {
 	"worklet";
 	const resolvedStylesMap: NormalizedTransitionInterpolatedStyle = {};
@@ -519,7 +479,6 @@ export const resolveSlotStyles = ({
 		localStylesMaps,
 		ancestorStylesMap,
 		previousStyleStatesBySlot,
-		deferLocalSlotResets,
 		resolvedStylesMap,
 		nextPreviousStyleStatesBySlot,
 	};

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

@@ -3,9 +3,8 @@ import {
 	useDerivedValue,
 	useSharedValue,
 } from "react-native-reanimated";
-import { NO_STYLES } from "../../../../constants";
+import { NO_PROPS, NO_STYLES } from "../../../../constants";
 import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
-import { useScreenAnimationContext } from "../../animation";
 import {
 	type LocalStyleLayers,
 	type ResettableStyleStatesBySlot,
@@ -22,30 +21,18 @@ export const useResolvedStylesMap = ({
 	localStylesMaps,
 	ancestorStylesMap,
 }: UseResolvedStylesMapParams) => {
-	const { screenInterpolatorProps, screenInterpolatorPropsRevision } =
-		useScreenAnimationContext();
-	const previousStyleStatesBySlot = useSharedValue<ResettableStyleStatesBySlot>(
-		{},
-	);
+	const previousStyleStatesBySlot =
+		useSharedValue<ResettableStyleStatesBySlot>(NO_PROPS);
 	const previousResolvedStylesMap =
 		useSharedValue<NormalizedTransitionInterpolatedStyle>(NO_STYLES);
 
 	return useDerivedValue(() => {
 		"worklet";
-		screenInterpolatorPropsRevision.get();
-
-		const props = screenInterpolatorProps.get();
-		// 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({
 				localStylesMaps: localStylesMaps.get(),
 				ancestorStylesMap: ancestorStylesMap?.get() ?? NO_STYLES,
 				previousStyleStatesBySlot: previousStyleStatesBySlot.get(),
-				deferLocalSlotResets,
 			});
 
 		previousStyleStatesBySlot.set(nextPreviousStyleStatesBySlot);

package/src/shared/providers/stack/helpers/managed-stack-state/helpers/build-managed-stack-state.ts

@@ -13,6 +13,7 @@ import {
 	areDescriptorsEqual,
 	areRouteChildStateMapsEqual,
 	getRouteChildState,
+	routeKeyListsAreEqual,
 	setsAreEqual,
 } from "./helpers";
 import type {
@@ -34,13 +35,6 @@ type BuildManagedStackStateParams<
 	previousState?: LocalRoutesState<TDescriptor>;
 };
 
-const areRouteKeysEqual = (a: string[], b: string[]): boolean => {
-	if (a === b) return true;
-	if (a.length !== b.length) return false;
-
-	return a.every((key, index) => key === b[index]);
-};
-
 const resolveStableDescriptorSource = <
 	TDescriptor extends BaseStackDescriptor,
 >({
@@ -106,10 +100,13 @@ const getSceneActivityWindow = <
 >): SceneActivityWindow => {
 	const focusedRouteKey = props.state.routes[props.state.index]?.key;
 
-	let focusedIndex = Math.max(
-		0,
-		routes.findIndex((route) => route.key === focusedRouteKey),
-	);
+	let focusedIndex = routes.findIndex((route) => route.key === focusedRouteKey);
+
+	if (focusedIndex === -1) {
+		throw new Error(
+			`Focused route "${focusedRouteKey}" is missing from routes`,
+		);
+	}
 
 	while (focusedIndex > 0 && closingRouteKeys.has(routes[focusedIndex]?.key)) {
 		focusedIndex--;
@@ -355,7 +352,7 @@ export const buildManagedStackState = <
 		scenes,
 		routeKeys:
 			params.previousState &&
-			areRouteKeysEqual(params.previousState.routeKeys, routeKeys)
+			routeKeyListsAreEqual(params.previousState.routeKeys, routeKeys)
 				? params.previousState.routeKeys
 				: routeKeys,
 		shouldShowFloatOverlay,

package/src/shared/providers/stack/helpers/managed-stack-state/helpers/derive-managed-stack-state.ts

@@ -10,6 +10,7 @@ import {
 	areDescriptorsEqual,
 	areRouteChildStateMapsEqual,
 	getRouteChildStateMap,
+	routesHaveSameKeys,
 	setsAreEqual,
 } from "./helpers";
 import { reconcileManagedRoutes } from "./reconcile-managed-routes";
@@ -35,15 +36,6 @@ const routesAreIdentical = <Route extends RouteWithKey>(
 	return a.every((route, index) => route === b[index]);
 };
 
-const routeKeysAreEqual = <Route extends RouteWithKey>(
-	a: Route[],
-	b: Route[],
-): boolean => {
-	if (a.length !== b.length) return false;
-
-	return a.every((route, index) => route.key === b[index]?.key);
-};
-
 export const deriveManagedStackState = <
 	TDescriptor extends BaseStackDescriptor,
 	TNavigation extends BaseStackNavigation,
@@ -85,7 +77,7 @@ export const deriveManagedStackState = <
 		focusedRouteUnchanged &&
 		closingRouteKeysUnchanged &&
 		routeChildStatesUnchanged &&
-		routeKeysAreEqual(current.routes, nextRoutesSnapshot) &&
+		routesHaveSameKeys(current.routes, nextRoutesSnapshot) &&
 		areDescriptorSourceMapsEquivalent(
 			current.sourceDescriptors,
 			nextDescriptors,

package/src/shared/providers/stack/helpers/managed-stack-state/helpers/helpers.ts

@@ -38,6 +38,25 @@ export const setsAreEqual = <T>(
 	return true;
 };
 
+export const routeKeyListsAreEqual = (
+	a: readonly string[],
+	b: readonly string[],
+): boolean => {
+	if (a === b) return true;
+	if (a.length !== b.length) return false;
+
+	return a.every((key, index) => key === b[index]);
+};
+
+export const routesHaveSameKeys = <Route extends RouteWithKey>(
+	a: readonly Route[],
+	b: readonly Route[],
+): boolean => {
+	if (a.length !== b.length) return false;
+
+	return a.every((route, index) => route.key === b[index]?.key);
+};
+
 export const getRouteChildState = (route: RouteWithKey): unknown => {
 	if (!route || typeof route !== "object") {
 		return undefined;

package/src/shared/providers/stack/helpers/managed-stack-state/helpers/reconcile-managed-routes.ts

@@ -4,6 +4,7 @@ import type {
 } from "../../../../../types/stack.types";
 import { composeDescriptors } from "../../../../../utils/navigation/compose-descriptors";
 import { syncRoutesWithRemoved } from "../../../../../utils/navigation/sync-routes-with-removed";
+import { routesHaveSameKeys } from "./helpers";
 import type {
 	LocalRoutesState,
 	ManagedDescriptorSources,
@@ -19,17 +20,6 @@ type ReconcileManagedRoutesParams<TDescriptor extends BaseStackDescriptor> = {
 	closingRouteKeys: Set<string>;
 };
 
-const haveSameRouteKeys = <Route extends RouteWithKey>(
-	previous: Route[],
-	next: Route[],
-): boolean => {
-	if (previous.length !== next.length) {
-		return false;
-	}
-
-	return previous.every((route, index) => route?.key === next[index]?.key);
-};
-
 const alignRoutesWithLatest = <
 	Route extends RouteWithKey,
 	DescriptorMap extends Record<string, unknown>,
@@ -155,7 +145,7 @@ export const reconcileManagedRoutes = <TDescriptor extends BaseStackDescriptor>(
 		closingRouteKeys,
 	} = params;
 
-	const routeKeysUnchanged = haveSameRouteKeys(
+	const routeKeysUnchanged = routesHaveSameKeys(
 		previousRoutesSnapshot,
 		nextRoutesSnapshot,
 	);

package/src/shared/providers/stack/helpers/managed-stack-state/managed-stack-controller.ts

@@ -30,7 +30,7 @@ export const createManagedStackController = <
 ): ManagedStackControllerType<TDescriptor, TNavigation> => {
 	const closingRouteKeys = new Set<string>();
 	let props = initialProps;
-	let previousPropRoutes = initialProps.state.routes;
+	let previousRoutesSnapshot = initialProps.state.routes;
 	let snapshot: ManagedStackControllerSnapshot<TDescriptor> = {
 		state: buildManagedStackState({
 			props,
@@ -60,16 +60,16 @@ export const createManagedStackController = <
 	};
 
 	const update = (nextProps: ManagedStackProps<TDescriptor, TNavigation>) => {
-		const previousRoutesSnapshot = previousPropRoutes;
+		const lastRoutesSnapshot = previousRoutesSnapshot;
 		props = nextProps;
 
 		const nextState = deriveManagedStackState({
 			props,
 			current: snapshot.state,
-			previousRoutesSnapshot,
+			previousRoutesSnapshot: lastRoutesSnapshot,
 			closingRouteKeys,
 		});
-		previousPropRoutes = nextProps.state.routes;
+		previousRoutesSnapshot = nextProps.state.routes;
 
 		if (nextState === snapshot.state) {
 			return;

package/src/shared/types/bounds.types.ts

@@ -231,6 +231,25 @@ export type BoundsNavigationRevealOptions = {
 	 * @default "freeform"
 	 */
 	gestureProgressMode?: GestureProgressMode;
+	/**
+	 * Scale applied to the unfocused background content while the reveal runs
+	 * above it.
+	 *
+	 * @default 0.9375
+	 */
+	backgroundScale?: number;
+	/**
+	 * Whether reveal should reset the unfocused background content scale once the
+	 * transition is logically settled.
+	 *
+	 * By default, reveal restores the background to scale `1` after settle so the
+	 * next drag or programmatic dismiss starts from a fresh, unmodified layout
+	 * measurement. Keeping the background transformed while idle can make the next
+	 * measurement read the scaled screen instead of the real screen geometry.
+	 *
+	 * @default true
+	 */
+	shouldBackgroundScaleResetOnSettled?: boolean;
 	/**
 	 * Temporarily blocks pointer-event pass-through on the inactive content until
 	 * the source element transition handoff reaches progress `0.25`.