react-native-screen-transitions 3.9.0-beta.0 → 3.9.0-beta.2

package/src/shared/components/boundary/hooks/lifecycles/use-initial-destination-measurement.ts

@@ -1,5 +1,7 @@
+import { useCallback, useLayoutEffect } from "react";
 import {
 	cancelAnimation,
+	runOnUI,
 	useAnimatedReaction,
 	useSharedValue,
 	withDelay,
@@ -9,41 +11,33 @@ import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
 import { AnimationStore } from "../../../../stores/animation.store";
 import { getSourceScreenKeyFromPairKey } from "../../../../stores/bounds/helpers/link-pairs.helpers";
 import { getEntry } from "../../../../stores/bounds/internals/entries";
-import {
-	getDestination,
-	getLink,
-} from "../../../../stores/bounds/internals/links";
+import { getLink } from "../../../../stores/bounds/internals/links";
 import { pairs } from "../../../../stores/bounds/internals/state";
 import type { BoundTag } from "../../../../stores/bounds/types";
-import {
-	LifecycleTransitionRequestKind,
-	SystemStore,
-} from "../../../../stores/system.store";
+import { SystemStore } from "../../../../stores/system.store";
 import { logger } from "../../../../utils/logger";
-import {
-	hasHandoffEscapeContinuation,
-	usesEscapeClippingHost,
-} from "../../portal/utils/ownership";
 import type { MeasureBoundary } from "../../types";
-import { getInitialDestinationMeasurePairKey } from "../../utils/destination-signals";
+import { getInitialDestinationMeasurementSignal } from "../../utils/destination-signals";
 
-const VIEWPORT_RETRY_DELAY_MS = 100;
+const HANDSHAKE_RETRY_DELAY_MS = 100;
 /**
- * A destination that keeps failing its measurement guards must not hold the
- * transition gate forever — after this budget the block is released with a
- * warning so the open proceeds without that boundary.
+ * A destination whose initial handshake never completes must not hold the
+ * transition gate forever. After this budget, release the block with a warning
+ * so the open proceeds without that boundary.
  */
-const MAX_VIEWPORT_RETRIES = 20;
+const MAX_HANDSHAKE_RETRIES = 20;
 
 interface UseInitialDestinationMeasurementParams {
 	boundTag: BoundTag;
 	enabled: boolean;
+	escapeClipping: boolean;
 	measureBoundary: MeasureBoundary;
 }
 
 export const useInitialDestinationMeasurement = ({
 	boundTag,
 	enabled,
+	escapeClipping,
 	measureBoundary,
 }: UseInitialDestinationMeasurementParams) => {
 	const { tag, linkKey, group } = boundTag;
@@ -58,22 +52,23 @@ export const useInitialDestinationMeasurement = ({
 		(s) => s.derivations.ancestorDestinationPairKey,
 	);
 	const destinationEnabled = enabled && !nextScreenKey;
+	const initialDestinationPairKey =
+		destinationPairKey ?? ancestorDestinationPairKey;
 	const progress = AnimationStore.getValue(
 		currentScreenKey,
 		"transitionProgress",
 	);
 
 	const {
-		pendingLifecycleRequestKind,
 		actions: { blockLifecycleStart, unblockLifecycleStart },
 	} = SystemStore.getBag(currentScreenKey);
 
 	const isBlockingLifecycleStart = useSharedValue(0);
 	const retryToken = useSharedValue(0);
-	const viewportRetries = useSharedValue(0);
+	const handshakeRetries = useSharedValue(0);
 	const hasGivenUp = useSharedValue(0);
 
-	const releaseLifecycleStartBlock = () => {
+	const releaseLifecycleStartBlock = useCallback(() => {
 		"worklet";
 		cancelAnimation(retryToken);
 
@@ -81,53 +76,91 @@ export const useInitialDestinationMeasurement = ({
 			return;
 		}
 
-		unblockLifecycleStart();
 		isBlockingLifecycleStart.set(0);
-	};
+		unblockLifecycleStart();
+	}, [isBlockingLifecycleStart, retryToken, unblockLifecycleStart]);
+
+	useLayoutEffect(() => {
+		if (
+			!destinationEnabled ||
+			!initialDestinationPairKey ||
+			progress.get() > 0 ||
+			isBlockingLifecycleStart.get()
+		) {
+			return;
+		}
+
+		// Boundary layout effects run before the parent screen's open intent. Claim
+		// this boundary's startup block before the transition controller can consume
+		// the request; the UI-thread handshake below releases it once matching is done.
+		blockLifecycleStart();
+		isBlockingLifecycleStart.set(1);
+
+		return () => {
+			if (escapeClipping) {
+				// The portal host owns the release after this boundary hands off.
+				return;
+			}
+
+			// This is an abandonment fallback, not a second release. Run it on the UI
+			// runtime so it serializes with the handshake's guarded release.
+			runOnUI(releaseLifecycleStartBlock)();
+		};
+	}, [
+		blockLifecycleStart,
+		destinationEnabled,
+		escapeClipping,
+		initialDestinationPairKey,
+		isBlockingLifecycleStart,
+		progress,
+		releaseLifecycleStartBlock,
+	]);
 
 	useAnimatedReaction(
 		() => {
 			"worklet";
 			const retryTick = retryToken.get();
-
-			const hasPendingOpenRequest =
-				pendingLifecycleRequestKind.get() ===
-				LifecycleTransitionRequestKind.Open;
-
 			const isWaitingForOpenToStart = progress.get() <= 0;
-
-			if (!hasPendingOpenRequest || !isWaitingForOpenToStart) {
-				return [0, retryTick] as const;
-			}
-
-			const measurePairKey = getInitialDestinationMeasurePairKey({
-				enabled: destinationEnabled,
+			const sourceScreenKey = initialDestinationPairKey
+				? getSourceScreenKeyFromPairKey(initialDestinationPairKey)
+				: undefined;
+			const signal = getInitialDestinationMeasurementSignal({
+				enabled:
+					destinationEnabled &&
+					isWaitingForOpenToStart &&
+					isBlockingLifecycleStart.get() > 0,
 				destinationPairKey,
 				ancestorDestinationPairKey,
 				linkId: linkKey,
 				group,
-				linkState:
-					destinationEnabled &&
-					(destinationPairKey || ancestorDestinationPairKey)
-						? pairs.get()
-						: undefined,
+				destinationPresent: getEntry(tag, currentScreenKey) !== null,
+				sourcePresent:
+					sourceScreenKey !== undefined &&
+					getEntry(tag, sourceScreenKey) !== null,
+				linkState: initialDestinationPairKey ? pairs.get() : undefined,
 			});
 
-			return [measurePairKey, retryTick] as const;
+			return [
+				signal?.pairKey ?? null,
+				signal?.action ?? null,
+				retryTick,
+			] as const;
 		},
-		([measurePairKey, retryTick], previous) => {
+		([measurePairKey, action, retryTick], previous) => {
 			"worklet";
-			if (!measurePairKey) {
+			if (!measurePairKey || !action) {
 				return;
 			}
 
 			const previousMeasurePairKey = previous?.[0];
-			const previousRetryTick = previous?.[1];
-			const shouldAttemptMeasure =
+			const previousAction = previous?.[1];
+			const previousRetryTick = previous?.[2];
+			const shouldHandleSignal =
 				measurePairKey !== previousMeasurePairKey ||
+				action !== previousAction ||
 				retryTick !== previousRetryTick;
 
-			if (!shouldAttemptMeasure) {
+			if (!shouldHandleSignal) {
 				return;
 			}
 
@@ -135,62 +168,51 @@ export const useInitialDestinationMeasurement = ({
 				return;
 			}
 
-			if (!isBlockingLifecycleStart.get()) {
-				blockLifecycleStart();
-				isBlockingLifecycleStart.set(1);
+			if (action === "release") {
+				releaseLifecycleStartBlock();
+				handshakeRetries.set(0);
+				return;
+			}
+
+			if (action === "measure") {
+				measureBoundary({
+					type: "destination",
+					pairKey: measurePairKey,
+				});
 			}
 
-			measureBoundary({
-				type: "destination",
-				pairKey: measurePairKey,
-			});
+			const link = getLink(measurePairKey, linkKey);
+			const linkComplete = !!link?.source && !!link.destination;
 
-			const destinationAttached =
-				getDestination(measurePairKey, linkKey) !== null;
-
-			if (destinationAttached) {
-				const linkState = pairs.get();
-				const link = getLink(measurePairKey, linkKey);
-				const sourceScreenKey = getSourceScreenKeyFromPairKey(measurePairKey);
-				const sourceEntry = getEntry(tag, sourceScreenKey);
-				const sourceEntryUsesDestinationEscapeHost =
-					sourceEntry?.handoff === true && sourceEntry.escapeClipping === true;
-				const shouldWaitForEscapeClippingHost =
-					usesEscapeClippingHost(link) ||
-					sourceEntryUsesDestinationEscapeHost ||
-					hasHandoffEscapeContinuation({
-						linkKey,
-						linkState,
-						sourceScreenKey,
-					});
-
-				if (shouldWaitForEscapeClippingHost) {
+			if (linkComplete || action === "complete") {
+				cancelAnimation(retryToken);
+				handshakeRetries.set(0);
+				if (escapeClipping) {
 					// Screen-level escape has a second readiness phase after destination
-					// measurement: the host must commit before the transition starts, or
+					// matching: the host must commit before the transition starts, or
 					// the payload can disappear for a frame.
 					return;
 				}
 				releaseLifecycleStartBlock();
-				viewportRetries.set(0);
 				return;
 			}
 
-			if (viewportRetries.get() >= MAX_VIEWPORT_RETRIES) {
+			if (handshakeRetries.get() >= MAX_HANDSHAKE_RETRIES) {
 				hasGivenUp.set(1);
 				releaseLifecycleStartBlock();
 				logger.warn(
-					`Destination boundary "${linkKey}" never produced a valid measurement after ${MAX_VIEWPORT_RETRIES} attempts; releasing the transition gate without it. The boundary is likely off-viewport (e.g. an inactive group member on a paged screen) or unmounted.`,
+					`Boundary "${linkKey}" never formed a complete source/destination link after ${MAX_HANDSHAKE_RETRIES} attempts; releasing the transition gate without it. One side is likely off-viewport or unmounted.`,
 				);
 				return;
 			}
 
-			// Destination did not attach (malformed off-screen measurement); retry
-			// after the retry token advances while the lifecycle stays blocked.
-			viewportRetries.set(viewportRetries.get() + 1);
+			// Keep the lifecycle blocked while registration, measurement, or source
+			// attachment settles. The retry token also retries rejected destination bounds.
+			handshakeRetries.set(handshakeRetries.get() + 1);
 			cancelAnimation(retryToken);
 			retryToken.set(
 				withDelay(
-					VIEWPORT_RETRY_DELAY_MS,
+					HANDSHAKE_RETRY_DELAY_MS,
 					withTiming(retryToken.get() + 1, { duration: 0 }),
 				),
 			);

package/src/shared/components/boundary/hooks/use-boundary-measurement.ts

@@ -86,6 +86,7 @@ export const useBoundaryMeasurement = ({
 	useInitialDestinationMeasurement({
 		boundTag,
 		enabled: runtimeEnabled,
+		escapeClipping,
 		measureBoundary,
 	});
 

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

@@ -8,15 +8,17 @@ import {
 } from "react-native-reanimated";
 import { applyMeasuredBoundsWrites } from "../../../providers/helpers/measured-bounds-writes";
 import { useOriginContext } from "../../../providers/screen/origin.provider";
+import { useScreenSlots } from "../../../providers/screen/styles";
 import type { BoundTag } from "../../../stores/bounds/types";
 import { ScrollStore } from "../../../stores/scroll.store";
 import { SystemStore } from "../../../stores/system.store";
+import { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
 import type { MeasureBoundary } from "../types";
 import {
 	attachScrollSnapshotToMeasuredBounds,
 	isMeasurementInViewport,
 	measureWithOverscrollAwareness,
-	normalizeMeasuredBoundsToOrigin,
+	normalizeMeasuredBoundsWithVisibilityGate,
 } from "../utils/measured-bounds";
 
 interface UseMeasurerParams {
@@ -48,6 +50,7 @@ export const useMeasurer = ({
 		"pendingLifecycleStartBlockCount",
 	);
 	const { originRef } = useOriginContext();
+	const { visibilityBlocked } = useScreenSlots();
 
 	return useCallback(
 		(target) => {
@@ -62,10 +65,14 @@ export const useMeasurer = ({
 
 			if (!measured || !measuredOrigin) return;
 
-			const normalizedMeasured = normalizeMeasuredBoundsToOrigin(
+			const normalizedMeasured = normalizeMeasuredBoundsWithVisibilityGate({
 				measured,
-				measuredOrigin,
-			);
+				origin: measuredOrigin,
+				visibilityBlocked: escapeClipping && visibilityBlocked.get(),
+				visibilityBlockOffset: getVisibilityBlockOffset(viewportHeight),
+				viewportWidth,
+				viewportHeight,
+			});
 
 			/**
 			 * - Destination Pass -
@@ -119,6 +126,7 @@ export const useMeasurer = ({
 			scrollMetadata,
 			pendingLifecycleStartBlockCount,
 			originRef,
+			visibilityBlocked,
 		],
 	);
 };

package/src/shared/components/boundary/hooks/use-register-target.ts

@@ -0,0 +1,43 @@
+import { useLayoutEffect } from "react";
+import type { View } from "react-native";
+import type { AnimatedRef } from "react-native-reanimated";
+import { logger } from "../../../utils/logger";
+import {
+	TARGET_OUTSIDE_ROOT_WARNING,
+	useBoundaryRootContext,
+} from "../providers/boundary-root.provider";
+
+interface RegisterTargetProps {
+	targetAnimatedRef: AnimatedRef<View>;
+	preparedStyles: Record<string, any>;
+	measurementRef: AnimatedRef<View>;
+}
+
+export const useRegisterTarget = ({
+	targetAnimatedRef,
+	preparedStyles,
+	measurementRef,
+}: RegisterTargetProps) => {
+	const rootContext = useBoundaryRootContext();
+	const registerTargetRef = rootContext?.registerTargetRef;
+	const unregisterTargetRef = rootContext?.unregisterTargetRef;
+	useLayoutEffect(() => {
+		if (!registerTargetRef || !unregisterTargetRef) {
+			if (__DEV__) {
+				logger.warn(TARGET_OUTSIDE_ROOT_WARNING);
+			}
+			return;
+		}
+
+		registerTargetRef(targetAnimatedRef, preparedStyles, measurementRef);
+		return () => {
+			unregisterTargetRef(targetAnimatedRef);
+		};
+	}, [
+		registerTargetRef,
+		unregisterTargetRef,
+		targetAnimatedRef,
+		preparedStyles,
+		measurementRef,
+	]);
+};

package/src/shared/components/boundary/index.tsx

@@ -53,7 +53,7 @@ type BoundaryRootComponent = typeof BoundaryRoot;
  * Use:
  * - `Boundary` for passive and pressable shared elements.
  * - `Boundary.Target` to measure a nested descendant instead of the root.
- * - `Boundary.Host` to make nested portal placement explicit.
+ * - `Boundary.Host` to make clipping-escape host placement explicit.
  */
 export interface BoundaryComponent extends BoundaryRootComponent {
 	/**
@@ -61,7 +61,7 @@ export interface BoundaryComponent extends BoundaryRootComponent {
 	 */
 	Target: typeof BoundaryTarget;
 	/**
-	 * Explicit portal host for scrollable or otherwise clipped coordinate spaces.
+	 * Explicit host for clipping-escape placement.
 	 */
 	Host: typeof Host;
 	/**

package/src/shared/components/boundary/portal/components/boundary-content-portal/components/host.tsx

@@ -0,0 +1,48 @@
+import { memo, type ReactNode } from "react";
+import { StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { NativePortalHost } from "../../../teleport";
+import { createBoundaryContentPortalHostName } from "../helpers/host-name";
+
+const AnimatedPortalHost = NativePortalHost
+	? Animated.createAnimatedComponent(NativePortalHost)
+	: null;
+
+type BoundaryContentPortalHostProps = {
+	boundaryId: string;
+	children: ReactNode;
+	enabled: boolean;
+	screenKey: string;
+};
+
+export const BoundaryContentPortalHost = memo(
+	function BoundaryContentPortalHost({
+		boundaryId,
+		children,
+		enabled,
+		screenKey,
+	}: BoundaryContentPortalHostProps) {
+		if (!enabled || !AnimatedPortalHost) {
+			return <>{children}</>;
+		}
+
+		const portalHostName = createBoundaryContentPortalHostName(
+			screenKey,
+			boundaryId,
+		);
+
+		return (
+			<>
+				{children}
+				<AnimatedPortalHost name={portalHostName} style={styles.host} />
+			</>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	host: {
+		...StyleSheet.absoluteFillObject,
+		overflow: "visible",
+	},
+});

package/src/shared/components/boundary/portal/components/boundary-content-portal/helpers/host-name.ts

@@ -0,0 +1,9 @@
+const BOUNDARY_CONTENT_PORTAL_HOST_NAME_SUFFIX = "-content-portal-host";
+
+export const createBoundaryContentPortalHostName = (
+	screenKey: string,
+	boundaryId: string,
+) => {
+	"worklet";
+	return `${screenKey}-${boundaryId}${BOUNDARY_CONTENT_PORTAL_HOST_NAME_SUFFIX}`;
+};