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

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

@@ -5,12 +5,12 @@ import { StyleSheet } from "react-native";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { StackType } from "../../types/stack.types";
 import createProvider from "../../utils/create-provider";
-import { ViewportProvider } from "../viewport.provider";
 
 export interface StackCoreConfig {
 	TRANSITIONS_ALWAYS_ON?: boolean;
 	STACK_TYPE?: StackType;
 	DISABLE_NATIVE_SCREENS?: boolean;
+	DISABLE_NATIVE_SCREEN_CONTAINER?: boolean;
 }
 
 interface StackCoreProviderProps {
@@ -23,6 +23,7 @@ export interface StackCoreContextValue {
 		TRANSITIONS_ALWAYS_ON: boolean;
 		STACK_TYPE?: StackType;
 		DISABLE_NATIVE_SCREENS: boolean;
+		DISABLE_NATIVE_SCREEN_CONTAINER: boolean;
 	};
 }
 
@@ -34,18 +35,27 @@ const { StackCoreProvider: InternalStackCoreProvider, useStackCoreContext } =
 		const {
 			TRANSITIONS_ALWAYS_ON = false,
 			DISABLE_NATIVE_SCREENS = false,
+			DISABLE_NATIVE_SCREEN_CONTAINER = false,
 			STACK_TYPE = StackType.BLANK,
 		} = config;
 
 		const flags = useMemo(
-			() => ({ TRANSITIONS_ALWAYS_ON, STACK_TYPE, DISABLE_NATIVE_SCREENS }),
-			[TRANSITIONS_ALWAYS_ON, STACK_TYPE, DISABLE_NATIVE_SCREENS],
+			() => ({
+				TRANSITIONS_ALWAYS_ON,
+				STACK_TYPE,
+				DISABLE_NATIVE_SCREENS,
+				DISABLE_NATIVE_SCREEN_CONTAINER,
+			}),
+			[
+				TRANSITIONS_ALWAYS_ON,
+				STACK_TYPE,
+				DISABLE_NATIVE_SCREENS,
+				DISABLE_NATIVE_SCREEN_CONTAINER,
+			],
 		);
 
-		const value = useMemo(() => ({ flags }), [flags]);
-
 		return {
-			value,
+			value: { flags },
 			children: (
 				<GestureHandlerRootView
 					style={styles.container}
@@ -53,9 +63,7 @@ const { StackCoreProvider: InternalStackCoreProvider, useStackCoreContext } =
 						STACK_TYPE === StackType.COMPONENT ? "box-none" : undefined
 					}
 				>
-					<SafeAreaProviderCompat>
-						<ViewportProvider>{children}</ViewportProvider>
-					</SafeAreaProviderCompat>
+					<SafeAreaProviderCompat>{children}</SafeAreaProviderCompat>
 				</GestureHandlerRootView>
 			),
 		};
@@ -71,16 +79,21 @@ export function withStackCore<TProps extends object>(
 ): React.FC<TProps & StackCoreConfig> {
 	return function StackCoreWrapper({
 		DISABLE_NATIVE_SCREENS,
+		DISABLE_NATIVE_SCREEN_CONTAINER,
 		TRANSITIONS_ALWAYS_ON,
 		STACK_TYPE,
 		...props
 	}: TProps & StackCoreConfig) {
-		// User props first, then defaultConfig overrides (config takes priority)
+		// Start from defaults, then apply explicit overrides from the caller.
 		const config: StackCoreConfig = {
-			...(DISABLE_NATIVE_SCREENS !== undefined && { DISABLE_NATIVE_SCREENS }),
-			...(TRANSITIONS_ALWAYS_ON !== undefined && { TRANSITIONS_ALWAYS_ON }),
-			...(STACK_TYPE !== undefined && { STACK_TYPE }),
-			...defaultConfig,
+			TRANSITIONS_ALWAYS_ON:
+				TRANSITIONS_ALWAYS_ON ?? defaultConfig.TRANSITIONS_ALWAYS_ON,
+			STACK_TYPE: STACK_TYPE ?? defaultConfig.STACK_TYPE,
+			DISABLE_NATIVE_SCREENS:
+				DISABLE_NATIVE_SCREENS ?? defaultConfig.DISABLE_NATIVE_SCREENS,
+			DISABLE_NATIVE_SCREEN_CONTAINER:
+				DISABLE_NATIVE_SCREEN_CONTAINER ??
+				defaultConfig.DISABLE_NATIVE_SCREEN_CONTAINER,
 		};
 		return (
 			<InternalStackCoreProvider config={config}>

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

@@ -3,7 +3,7 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import type { ScreenKey } from "../types/screen.types";
+import type { Layout, ScreenKey } from "../types/screen.types";
 
 export type AnimationStoreMap = {
 	progress: SharedValue<number>;
@@ -13,6 +13,8 @@ export type AnimationStoreMap = {
 	targetProgress: SharedValue<number>;
 	/** Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured. */
 	autoSnapPoint: SharedValue<number>;
+	/** Intrinsic content layout measured from the screen container wrapper. */
+	contentLayout: SharedValue<Layout | null>;
 };
 
 const store: Record<ScreenKey, AnimationStoreMap> = {};
@@ -25,6 +27,7 @@ function createAnimationBag(): AnimationStoreMap {
 		entering: makeMutable(0),
 		targetProgress: makeMutable(1),
 		autoSnapPoint: makeMutable(-1),
+		contentLayout: makeMutable<Layout | null>(null),
 	};
 }
 
@@ -43,17 +46,17 @@ function peekRouteAnimations(
 	return store[routeKey];
 }
 
-function getRouteAnimation(
+function getRouteAnimation<K extends keyof AnimationStoreMap>(
 	routeKey: ScreenKey,
-	type: keyof AnimationStoreMap,
-): SharedValue<number> {
+	type: K,
+): AnimationStoreMap[K] {
 	return ensure(routeKey)[type];
 }
 
-function getAnimation(
+function getAnimation<K extends keyof AnimationStoreMap>(
 	routeKey: ScreenKey,
-	type: keyof AnimationStoreMap,
-): SharedValue<number> {
+	type: K,
+): AnimationStoreMap[K] {
 	return getRouteAnimation(routeKey, type);
 }
 
@@ -70,6 +73,7 @@ function clear(routeKey: ScreenKey) {
 		cancelAnimation(bag.entering);
 		cancelAnimation(bag.targetProgress);
 		cancelAnimation(bag.autoSnapPoint);
+		cancelAnimation(bag.contentLayout);
 	}
 	delete store[routeKey];
 }

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

@@ -118,7 +118,9 @@ function setGroupActiveId(group: string, id: string) {
 	groups.modify(<T extends GroupsState>(state: T): T => {
 		"worklet";
 		const mutableState = state as GroupsState;
-		mutableState[group] = { activeId: id };
+		mutableState[group] = {
+			activeId: id,
+		};
 		return state;
 	});
 	debugStoreSizeLog(`setGroupActiveId(${group},${id})`);

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

@@ -103,6 +103,13 @@ export interface ScreenInterpolationProps {
 		 * The `width` and `height` of the screen container.
 		 */
 		screen: Layout;
+		/**
+		 * The intrinsic measured content wrapper layout when available.
+		 *
+		 * This is currently populated for the measured screen-container path used by
+		 * auto snap-point sizing. It is undefined until a real measurement exists.
+		 */
+		content?: Layout;
 	};
 
 	/**
@@ -160,9 +167,14 @@ export interface ScreenInterpolationProps {
 	inactive: ScreenTransitionState | undefined;
 }
 
+/**
+ * Returning `null` explicitly defers rendering of the screen's visual subtree
+ * for the current frame. Returning an object applies transition styles
+ * immediately.
+ */
 export type ScreenStyleInterpolator = (
 	props: ScreenInterpolationProps,
-) => TransitionInterpolatedStyle;
+) => TransitionInterpolatedStyle | null;
 
 /**
  * Animated style properties with full autocomplete.

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

@@ -12,6 +12,9 @@ export type Layout = {
 };
 
 export type ScreenKey = string;
+export type SheetScrollGestureBehavior =
+	| "expand-and-collapse"
+	| "collapse-only";
 
 /**
  * A single snap point value. Either a fraction of screen height (0–1) or
@@ -33,10 +36,13 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * </Transition.View>
 	 *
 	 * // In your screenStyleInterpolator:
-	 * return {
-	 *   'hero-image': {
-	 *     opacity: interpolate(progress, [0, 1], [0, 1]),
-	 *     transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }]
+	 * screenStyleInterpolator: ({ progress }) => {
+	 *   "worklet";
+	 *   return {
+	 *     'hero-image': {
+	 *       opacity: interpolate(progress, [0, 1], [0, 1]),
+	 *       transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }]
+	 *     }
 	 *   }
 	 * }
 	 */
@@ -74,6 +80,11 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 export type ScreenTransitionConfig = {
 	/**
 	 * The user-provided function to calculate styles based on animation progress.
+	 *
+	 * Return `null` to explicitly defer rendering of the screen's visual subtree
+	 * until a later frame. This is useful for transitions such as
+	 * `bounds().navigation.zoom()` where the screen should stay hidden until the
+	 * interpolator has enough state to produce a safe first frame.
 	 */
 	screenStyleInterpolator?: ScreenStyleInterpolator;
 
@@ -87,6 +98,13 @@ export type ScreenTransitionConfig = {
 	 * (e.g. `bounds().navigation.zoom()`) is ready from the first frame.
 	 *
 	 * Requires `@react-native-masked-view/masked-view` to be installed.
+	 *
+	 * @default false
+	 */
+	navigationMaskEnabled?: boolean;
+
+	/**
+	 * @deprecated Use `navigationMaskEnabled` instead.
 	 */
 	maskEnabled?: boolean;
 
@@ -209,16 +227,25 @@ export type ScreenTransitionConfig = {
 	initialSnapIndex?: number;
 
 	/**
-	 * Controls whether swiping to expand the sheet works from within a ScrollView.
-	 *
-	 * - `true` (Apple Maps style): Swiping up at scroll top expands the sheet
-	 * - `false` (Instagram style): Expand only works via deadspace (non-scrollable areas)
+	 * Controls how nested scroll content hands gestures off to a snap sheet.
 	 *
-	 * Collapse (swipe down at scroll top) always works regardless of this setting.
+	 * - `"expand-and-collapse"` (Apple Maps style): Swiping up at scroll boundary expands the sheet,
+	 *   and swiping down at scroll boundary collapses or dismisses it
+	 * - `"collapse-only"` (Instagram style): Expand only works via deadspace; collapse/dismiss via
+	 *   nested scroll content still works at boundary
 	 *
 	 * Only applies to screens with `snapPoints` configured.
 	 *
-	 * @default true
+	 * @default "expand-and-collapse"
+	 */
+	sheetScrollGestureBehavior?: SheetScrollGestureBehavior;
+
+	/**
+	 * @deprecated Use `sheetScrollGestureBehavior` instead.
+	 *
+	 * Mapping:
+	 * - `true` -> `"expand-and-collapse"`
+	 * - `false` -> `"collapse-only"`
 	 */
 	expandViaScrollView?: boolean;
 
@@ -255,12 +282,15 @@ export type ScreenTransitionConfig = {
 	 *
 	 * @example
 	 * backdropComponent: BlurView,
-	 * screenStyleInterpolator: ({ progress }) => ({
-	 *   backdrop: {
-	 *     style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
-	 *     props: { intensity: interpolate(progress, [0, 1], [0, 80]) },
-	 *   },
-	 * })
+	 * screenStyleInterpolator: ({ progress }) => {
+	 *   "worklet";
+	 *   return {
+	 *     backdrop: {
+	 *       style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
+	 *       props: { intensity: interpolate(progress, [0, 1], [0, 80]) },
+	 *     },
+	 *   };
+	 * }
 	 *
 	 * @default undefined
 	 */
@@ -277,12 +307,15 @@ export type ScreenTransitionConfig = {
 	 *
 	 * @example
 	 * surfaceComponent: SquircleView,
-	 * screenStyleInterpolator: ({ progress }) => ({
-	 *   surface: {
-	 *     style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
-	 *     props: { cornerRadius: 24, cornerSmoothing: 0.7 },
-	 *   },
-	 * })
+	 * screenStyleInterpolator: ({ progress }) => {
+	 *   "worklet";
+	 *   return {
+	 *     surface: {
+	 *       style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
+	 *       props: { cornerRadius: 24, cornerSmoothing: 0.7 },
+	 *     },
+	 *   };
+	 * }
 	 *
 	 * @default undefined
 	 */

package/src/shared/utils/bounds/helpers/compute-bounds-styles.ts

@@ -5,6 +5,7 @@ import {
 	ENTER_RANGE,
 	EXIT_RANGE,
 	FULLSCREEN_DIMENSIONS,
+	HIDDEN_STYLE,
 } from "../../../constants";
 import {
 	BoundStore,
@@ -73,6 +74,8 @@ const resolveBounds = (params: {
 			currentScreenKey,
 			sourceScreenKey: resolvedPair.sourceScreenKey,
 			destinationScreenKey: resolvedPair.destinationScreenKey,
+			hasTargetOverride,
+			usedSnapshotDestination: resolvedPair.usedSnapshotDestination,
 		};
 	}
 
@@ -85,6 +88,8 @@ const resolveBounds = (params: {
 			currentScreenKey,
 			sourceScreenKey: resolvedPair.sourceScreenKey,
 			destinationScreenKey: resolvedPair.destinationScreenKey,
+			hasTargetOverride,
+			usedSnapshotDestination: resolvedPair.usedSnapshotDestination,
 		};
 	}
 
@@ -107,6 +112,8 @@ const resolveBounds = (params: {
 		currentScreenKey,
 		sourceScreenKey: resolvedPair.sourceScreenKey,
 		destinationScreenKey: resolvedPair.destinationScreenKey,
+		hasTargetOverride,
+		usedSnapshotDestination: resolvedPair.usedSnapshotDestination,
 	};
 };
 
@@ -121,7 +128,7 @@ export const computeBoundStyles = (
 		if (computeOptions.raw) {
 			return EMPTY_BOUND_HELPER_RESULT_RAW;
 		}
-		return EMPTY_BOUND_HELPER_RESULT;
+		return HIDDEN_STYLE;
 	}
 
 	const {
@@ -131,6 +138,8 @@ export const computeBoundStyles = (
 		currentScreenKey,
 		sourceScreenKey,
 		destinationScreenKey,
+		hasTargetOverride,
+		usedSnapshotDestination,
 	} = resolveBounds({
 		id,
 		previous,
@@ -145,16 +154,21 @@ export const computeBoundStyles = (
 		if (computeOptions.raw) {
 			return EMPTY_BOUND_HELPER_RESULT_RAW;
 		}
-		return EMPTY_BOUND_HELPER_RESULT;
+		return HIDDEN_STYLE;
 	}
 
 	const ranges: readonly [number, number] = entering ? ENTER_RANGE : EXIT_RANGE;
 
 	if (computeOptions.method === "content") {
+		const ignoresSnapshotDestinationOwnership =
+			hasTargetOverride &&
+			usedSnapshotDestination &&
+			destinationScreenKey === sourceScreenKey;
 		const currentOwnsSource =
 			!!currentScreenKey &&
 			currentScreenKey === sourceScreenKey &&
-			currentScreenKey !== destinationScreenKey;
+			(currentScreenKey !== destinationScreenKey ||
+				ignoresSnapshotDestinationOwnership);
 		const contentStart = currentOwnsSource ? end : start;
 		const contentEnd = currentOwnsSource ? start : end;
 		const geometry = computeContentTransformGeometry({

package/src/shared/utils/bounds/helpers/resolve-bound-tag.ts

@@ -1,4 +1,3 @@
-import { BoundStore } from "../../../stores/bounds";
 import type { BoundId } from "../types/options";
 
 export type ResolveBoundTagParams = {
@@ -20,10 +19,5 @@ export const resolveBoundTag = ({
 		return normalizedId;
 	}
 
-	const currentActiveId = BoundStore.getGroupActiveId(group);
-	if (currentActiveId !== normalizedId) {
-		BoundStore.setGroupActiveId(group, normalizedId);
-	}
-
 	return `${group}:${normalizedId}`;
 };

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

@@ -6,11 +6,23 @@ import { computeBoundStyles } from "./helpers/compute-bounds-styles";
 import { createInterpolators } from "./helpers/interpolators";
 import { createLinkAccessor } from "./helpers/link-accessor";
 import { resolveBoundTag } from "./helpers/resolve-bound-tag";
+import type { BoundsFrameProps } from "./types/frame-props";
 import type { BoundsOptions } from "./types/options";
 import { createZoomAccessor } from "./zoom";
 
+const syncGroupActiveMember = (group?: string, id?: string | number) => {
+	"worklet";
+	if (!group) return;
+	if (id === undefined || id === null || id === "") return;
+
+	const normalizedId = String(id);
+	if (BoundStore.getGroupActiveId(group) === normalizedId) return;
+
+	BoundStore.setGroupActiveId(group, normalizedId);
+};
+
 export const createBoundsAccessor = (
-	getProps: () => Omit<ScreenInterpolationProps, "bounds">,
+	getProps: () => BoundsFrameProps,
 ): BoundsAccessor => {
 	"worklet";
 
@@ -37,6 +49,7 @@ export const createBoundsAccessor = (
 	const computeElementBoundsStyles = (params?: BoundsOptions) => {
 		"worklet";
 		const props = getProps();
+		syncGroupActiveMember(params?.group, params?.id);
 
 		const resolved = buildBoundsOptions({
 			props,
@@ -54,15 +67,13 @@ export const createBoundsAccessor = (
 			scaleMode: params?.scaleMode,
 			target: params?.target,
 		};
-		let cachedNavigationPairProps:
-			| Omit<ScreenInterpolationProps, "bounds">
-			| undefined;
+		let cachedNavigationPairProps: BoundsFrameProps | undefined;
 		let cachedNavigationPairTag = "";
 		let cachedNavigationPair: ResolvedTransitionPair | undefined;
 
 		const resolveNavigationPair = (
 			tag: string,
-			frameProps: Omit<ScreenInterpolationProps, "bounds">,
+			frameProps: BoundsFrameProps,
 		): ResolvedTransitionPair | undefined => {
 			"worklet";
 			if (!tag) return undefined;

package/src/shared/utils/bounds/types/frame-props.ts

@@ -0,0 +1,5 @@
+import type { ScreenInterpolationProps } from "../../../types/animation.types";
+
+export type BoundsFrameProps = Omit<ScreenInterpolationProps, "bounds"> & {
+	navigationMaskEnabled: boolean;
+};

package/src/shared/utils/bounds/zoom/accessor.ts

@@ -1,17 +1,17 @@
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
 import type { BoundsNavigationZoomOptions } from "../../../types/bounds.types";
 import type { ResolveBoundTagParams } from "../helpers/resolve-bound-tag";
+import type { BoundsFrameProps } from "../types/frame-props";
 import type { BoundId, BoundsOptions } from "../types/options";
 import { buildZoomStyles } from "./build";
 
 type ZoomAccessorParams = {
 	id?: BoundId;
 	group?: string;
-	getProps: () => Omit<ScreenInterpolationProps, "bounds">;
+	getProps: () => BoundsFrameProps;
 	resolveBoundTag: (params: ResolveBoundTagParams) => string | undefined;
 	computeRaw: (
 		overrides?: Partial<BoundsOptions>,
-		frameProps?: Omit<ScreenInterpolationProps, "bounds">,
+		frameProps?: BoundsFrameProps,
 	) => Record<string, unknown>;
 	zoomBaseOptions?: Pick<
 		BoundsNavigationZoomOptions,

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

@@ -1,15 +1,19 @@
 import { interpolate, type StyleProps } from "react-native-reanimated";
 import {
 	EPSILON,
-	NAVIGATION_CONTAINER_STYLE_ID,
-	NAVIGATION_MASK_STYLE_ID,
-	NO_STYLES,
+	HIDDEN_STYLE,
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_ELEMENT_STYLE_ID,
+	VISIBLE_STYLE,
 } from "../../../constants";
 import {
 	BoundStore,
 	type ResolvedTransitionPair,
 } from "../../../stores/bounds";
-import type { TransitionInterpolatedStyle } from "../../../types/animation.types";
+import type {
+	ScreenStyleInterpolator,
+	TransitionInterpolatedStyle,
+} from "../../../types/animation.types";
 import type { BoundsNavigationZoomOptions } from "../../../types/bounds.types";
 import type { Layout } from "../../../types/screen.types";
 import type { BoundsOptions } from "../types/options";
@@ -449,7 +453,7 @@ export const buildZoomStyles = ({
 	props,
 	resolveTag,
 	computeRaw,
-}: BuildZoomStylesParams): TransitionInterpolatedStyle => {
+}: BuildZoomStylesParams): ReturnType<ScreenStyleInterpolator> => {
 	"worklet";
 
 	const focused = props.focused;
@@ -459,6 +463,12 @@ export const buildZoomStyles = ({
 	const nextRouteKey = props.next?.route.key;
 	const entering = !props.next;
 	const screenLayout = props.layouts.screen;
+	const transitionContext = {
+		currentScreenKey: currentRouteKey,
+		previousScreenKey: previousRouteKey,
+		nextScreenKey: nextRouteKey,
+		entering,
+	};
 
 	const resolvedConfig = resolveZoomConfig({
 		id,
@@ -469,7 +479,7 @@ export const buildZoomStyles = ({
 		defaultAnchor: "top",
 	});
 
-	if (!resolvedConfig) return NO_STYLES;
+	if (!resolvedConfig) return null;
 
 	const {
 		resolvedTag,
@@ -478,6 +488,21 @@ export const buildZoomStyles = ({
 		zoomOptions: resolvedZoomOptions,
 	} = resolvedConfig;
 
+	const resolvedPair = BoundStore.resolveTransitionPair(
+		resolvedTag,
+		transitionContext,
+	);
+
+	const focusedVisibilityStyles = {
+		[resolvedTag]: VISIBLE_STYLE,
+	} satisfies TransitionInterpolatedStyle;
+
+	if (!resolvedPair.sourceBounds) {
+		return {
+			[NAVIGATION_MASK_CONTAINER_STYLE_ID]: HIDDEN_STYLE,
+		};
+	}
+
 	const normX = props.active.gesture.normX;
 	const normY = props.active.gesture.normY;
 	const initialDirection = props.active.gesture.direction;
@@ -519,13 +544,6 @@ export const buildZoomStyles = ({
 	const dragScale = combineScales(dragXScale, dragYScale);
 
 	if (focused) {
-		const focusedPair = BoundStore.resolveTransitionPair(resolvedTag, {
-			currentScreenKey: currentRouteKey,
-			previousScreenKey: previousRouteKey,
-			nextScreenKey: nextRouteKey,
-			entering,
-		});
-
 		const contentTarget = getZoomContentTarget({
 			explicitTarget,
 			resolvedTag,
@@ -535,7 +553,7 @@ export const buildZoomStyles = ({
 			entering,
 			screenLayout,
 			anchor: sharedOptions.anchor,
-			resolvedPair: focusedPair,
+			resolvedPair,
 		});
 
 		const contentRaw = computeRaw({
@@ -565,21 +583,22 @@ export const buildZoomStyles = ({
 		const maskRadii = resolveMaskRadii({
 			progress,
 			zoomOptions: resolvedZoomOptions,
-			resolvedPair: focusedPair,
+			resolvedPair,
 		});
+		const focusedContentStyle = {
+			opacity: focusedFade,
+			transform: [
+				{ translateX: contentTranslateX },
+				{ translateY: contentTranslateY },
+				{ scale: contentScale },
+			],
+		};
 
 		return {
-			[NAVIGATION_CONTAINER_STYLE_ID]: {
-				style: {
-					opacity: focusedFade,
-					transform: [
-						{ translateX: contentTranslateX },
-						{ translateY: contentTranslateY },
-						{ scale: contentScale },
-					],
-				},
+			[NAVIGATION_MASK_CONTAINER_STYLE_ID]: {
+				style: focusedContentStyle,
 			},
-			[NAVIGATION_MASK_STYLE_ID]: {
+			[NAVIGATION_MASK_ELEMENT_STYLE_ID]: {
 				style: {
 					width: maskWidth,
 					height: maskHeight,
@@ -598,13 +617,7 @@ export const buildZoomStyles = ({
 						: {}),
 				},
 			},
-			// Signal the destination boundary to stay visible during the transition.
-			// Without this, useAssociatedStyles enters "waiting-first-style" mode
-			// (opacity: 0) because it detects previous-screen evidence but never
-			// receives a resolved style for this tag.
-			[resolvedTag]: {
-				style: { opacity: 1 },
-			},
+			...focusedVisibilityStyles,
 		};
 	}
 
@@ -626,6 +639,7 @@ export const buildZoomStyles = ({
 					entering,
 					screenLayout,
 					anchor: sharedOptions.anchor,
+					resolvedPair,
 				});
 
 	const elementRaw = computeRaw({

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

@@ -1,5 +1,5 @@
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
 import type { BoundsNavigationZoomOptions } from "../../../types/bounds.types";
+import type { BoundsFrameProps } from "../types/frame-props";
 import type { BoundId, BoundsOptions } from "../types/options";
 
 export type ResolveTag = (params: {
@@ -9,14 +9,14 @@ export type ResolveTag = (params: {
 
 export type ComputeRaw = (
 	overrides: Partial<BoundsOptions>,
-	frameProps?: Omit<ScreenInterpolationProps, "bounds">,
+	frameProps?: BoundsFrameProps,
 ) => Record<string, unknown>;
 
 export type BuildZoomStylesParams = {
 	id: BoundId;
 	group?: string;
 	zoomOptions?: BoundsNavigationZoomOptions;
-	props: Omit<ScreenInterpolationProps, "bounds">;
+	props: BoundsFrameProps;
 	resolveTag: ResolveTag;
 	computeRaw: ComputeRaw;
 };