react-native-screen-transitions 3.9.0-beta.1 → 3.9.0-beta.3

package/src/shared/components/boundary/components/boundary-target.tsx

@@ -1,5 +1,5 @@
 import type React from "react";
-import { memo, useLayoutEffect, useMemo } from "react";
+import { memo, useMemo } from "react";
 import type { View } from "react-native";
 import Animated, { useAnimatedRef } from "react-native-reanimated";
 import {
@@ -7,71 +7,62 @@ import {
 	useSlotLayoutStyles,
 } from "../../../providers/screen/styles";
 import { prepareStyleForBounds } from "../../../utils/bounds/helpers/styles/styles";
-import { logger } from "../../../utils/logger";
-import { Portal } from "../portal/components/portal";
+import { useRegisterTarget } from "../hooks/use-register-target";
 import {
-	TARGET_OUTSIDE_ROOT_WARNING,
-	useBoundaryRootContext,
-} from "../providers/boundary-root.provider";
+	BoundaryContentPortal,
+	BoundaryContentPortalHost,
+} from "../portal/components/boundary-content-portal";
+import { BoundaryPortal } from "../portal/components/boundary-portal";
+import { useBoundaryRootContext } from "../providers/boundary-root.provider";
 
-type BoundaryTargetProps = React.ComponentProps<typeof Animated.View>;
+type BoundaryTargetProps = Omit<
+	React.ComponentProps<typeof Animated.View>,
+	"children"
+> & {
+	children?: React.ReactNode;
+};
 
 export const BoundaryTarget = memo(function BoundaryTarget(
 	props: BoundaryTargetProps,
 ) {
-	const { style, ...rest } = props;
+	const { children, pointerEvents, style, ...rest } = props;
 	const targetAnimatedRef = useAnimatedRef<View>();
-	const placeholderAnimatedRef = useAnimatedRef<View>();
+	const targetEscapePlaceholderRef = useAnimatedRef<View>();
 	const rootContext = useBoundaryRootContext();
-	const registerTargetRef = rootContext?.registerTargetRef;
-	const unregisterTargetRef = rootContext?.unregisterTargetRef;
+	const boundaryId = rootContext?.boundTag.tag;
 	const isActiveTarget = rootContext?.activeTargetRef === targetAnimatedRef;
 	const portalRuntime = rootContext?.portalRuntime;
+	const handoffEnabled = isActiveTarget && rootContext?.handoffEnabled === true;
+	const shouldEscapeTargetToScreenHost =
+		portalRuntime?.escapeClipping === true && boundaryId !== undefined;
+
 	const shouldApplyAssociatedStyleInline =
-		isActiveTarget && portalRuntime?.enabled !== true;
+		isActiveTarget && portalRuntime?.escapeClipping !== true;
 	const shouldApplyPortalLayoutStyle =
-		isActiveTarget && portalRuntime?.enabled === true;
+		isActiveTarget && portalRuntime?.escapeClipping === true;
+
 	const associatedTargetStyles = useComposedSlotStyles(
 		rootContext?.boundTag.tag,
 		style,
 	);
 	const portalLayoutStyle = useSlotLayoutStyles(rootContext?.boundTag.tag);
 	const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
-	// Teleported content can render outside its layout slot. The placeholder is
-	// the truthful measurement surface whenever runtime portal behavior is active.
-	const measurementRef = portalRuntime?.enabled
-		? placeholderAnimatedRef
-		: targetAnimatedRef;
 
-	useLayoutEffect(() => {
-		if (!registerTargetRef || !unregisterTargetRef) {
-			if (__DEV__) {
-				logger.warn(TARGET_OUTSIDE_ROOT_WARNING);
-			}
-			return;
-		}
+	const measurementRef = shouldEscapeTargetToScreenHost
+		? targetEscapePlaceholderRef
+		: targetAnimatedRef;
 
-		registerTargetRef(targetAnimatedRef, preparedStyles, measurementRef);
-		return () => {
-			unregisterTargetRef(targetAnimatedRef);
-		};
-	}, [
-		registerTargetRef,
-		unregisterTargetRef,
-		targetAnimatedRef,
-		preparedStyles,
-		measurementRef,
-	]);
+	useRegisterTarget({ preparedStyles, measurementRef, targetAnimatedRef });
 
 	return (
-		<Portal
-			id={rootContext?.boundTag.tag}
-			handoff={portalRuntime?.handoff}
-			escapeClipping={portalRuntime?.escapeClipping}
-			placeholderRef={placeholderAnimatedRef}
+		<BoundaryPortal
+			boundaryId={boundaryId ?? ""}
+			enabled={shouldEscapeTargetToScreenHost}
+			placeholderRef={targetEscapePlaceholderRef}
 		>
 			<Animated.View
 				{...rest}
+				pointerEvents={pointerEvents}
 				ref={targetAnimatedRef}
 				style={[
 					style,
@@ -79,7 +70,20 @@ export const BoundaryTarget = memo(function BoundaryTarget(
 					shouldApplyPortalLayoutStyle ? portalLayoutStyle : undefined,
 				]}
 				collapsable={false}
-			/>
-		</Portal>
+			>
+				<BoundaryContentPortalHost
+					boundaryId={boundaryId ?? ""}
+					enabled={handoffEnabled}
+					screenKey={rootContext?.currentScreenKey ?? ""}
+				>
+					<BoundaryContentPortal
+						boundaryId={boundaryId}
+						enabled={handoffEnabled}
+					>
+						{children}
+					</BoundaryContentPortal>
+				</BoundaryContentPortalHost>
+			</Animated.View>
+		</BoundaryPortal>
 	);
 });

package/src/shared/components/boundary/create-boundary-component.tsx

@@ -1,49 +1,14 @@
-import {
-	type ComponentType,
-	forwardRef,
-	memo,
-	type ReactNode,
-	useImperativeHandle,
-	useMemo,
-} from "react";
-import type { View } from "react-native";
-import Animated, { useAnimatedRef } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../providers/screen/descriptors";
-import {
-	useComposedSlotStyles,
-	useSlotStackingStyles,
-} from "../../providers/screen/styles";
-import { createBoundTag } from "../../stores/bounds/helpers/link-pairs.helpers";
-import { useBoundaryMeasurement } from "./hooks/use-boundary-measurement";
-import { BoundaryLocalPortalHost } from "./portal/components/boundary-local-portal-host";
-import { Portal } from "./portal/components/portal";
-import { resolveBoundaryPortal } from "./portal/utils/resolve-portal";
-import {
-	BoundaryRootProvider,
-	useBoundaryRootState,
-} from "./providers/boundary-root.provider";
+import { type ComponentType, forwardRef, memo } from "react";
+import Animated from "react-native-reanimated";
+import { BoundaryContentPortalHost } from "./portal/components/boundary-content-portal";
+import { BoundaryPortal } from "./portal/components/boundary-portal";
+import { BoundaryRootProvider } from "./providers/boundary-root.provider";
 import type { BoundaryComponentProps } from "./types";
 
 interface CreateBoundaryComponentOptions {
 	alreadyAnimated?: boolean;
 }
 
-const hasRenderableChildren = (children: ReactNode): boolean => {
-	if (
-		children === null ||
-		children === undefined ||
-		typeof children === "boolean"
-	) {
-		return false;
-	}
-
-	if (Array.isArray(children)) {
-		return children.some(hasRenderableChildren);
-	}
-
-	return true;
-};
-
 export function createBoundaryComponent<P extends object>(
 	Wrapped: ComponentType<P>,
 	options: CreateBoundaryComponentOptions = {},
@@ -66,124 +31,44 @@ export function createBoundaryComponent<P extends object>(
 			target,
 			method,
 			style,
-			onPress,
 			handoff,
 			escapeClipping,
 			children,
 			...rest
 		} = props as any;
 
-		const boundTag = useMemo(
-			() => createBoundTag(String(id), group),
-			[id, group],
-		);
-		const portalRuntime = resolveBoundaryPortal({
-			handoff,
-			escapeClipping,
-		});
-
-		const currentScreenKey = useDescriptorsStore(
-			(s) => s.derivations.currentScreenKey,
-		);
-		const hasConfiguredInterpolator = useDescriptorsStore(
-			(s) => s.derivations.hasConfiguredInterpolator,
-		);
-		const runtimeEnabled = enabled && hasConfiguredInterpolator;
-		// Associated slot styles attach whenever the boundary is enabled,
-		// independent of whether an interpolator is configured for this transition.
-		const shouldAttachAssociatedStyles = enabled;
-		const canPortalRoot =
-			portalRuntime.enabled && hasRenderableChildren(children);
-
-		const associatedStyles = useComposedSlotStyles(boundTag.tag, style);
-		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
-		const rootPlaceholderRef = useAnimatedRef<View>();
-
-		const {
-			ref,
-			contextValue,
-			measuredRef,
-			hasActiveTarget,
-			targetPreparedStyles,
-		} = useBoundaryRootState({
-			boundTag,
-			portalRuntime,
-			rootMeasurementRef: canPortalRoot ? rootPlaceholderRef : undefined,
-		});
-
-		useBoundaryMeasurement({
-			boundTag,
-			enabled,
-			runtimeEnabled,
-			currentScreenKey,
-			measuredRef,
-			style,
-			targetPreparedStyles,
-			handoff: portalRuntime.handoff,
-			escapeClipping: portalRuntime.escapeClipping,
-			config: { anchor, scaleMode, target, method },
-		});
-
-		useImperativeHandle(forwardedRef, () => ref.current as any, [ref]);
-
-		const shouldPortalRoot = canPortalRoot && !hasActiveTarget;
-		// A nested active target takes the full associated style, so the root keeps
-		// only its stacking context. Without a nested target, a portal'd root is the
-		// target, so its associated style is applied through the portal host instead
-		// of inline on the teleported element.
-		// Host-only handoff receivers still need the associated style: their local
-		// portal host is absolute-filled inside this root, so the root is the visual
-		// frame that animates the received payload.
-		const attachedStyle = shouldAttachAssociatedStyles
-			? hasActiveTarget
-				? associatedStackingStyles
-				: shouldPortalRoot
-					? undefined
-					: associatedStyles
-			: undefined;
-		const pressProps = typeof onPress === "function" ? { onPress } : undefined;
-
-		const localPortalHost = (
-			<BoundaryLocalPortalHost
-				boundaryId={boundTag.tag}
-				enabled={enabled && portalRuntime.handoff}
-				screenKey={currentScreenKey}
-			/>
-		);
-		const canInjectLocalPortalHost = typeof children !== "function";
-
-		const renderBoundaryRoot = (extraChildren?: ReactNode) => (
-			<AnimatedComponent
-				{...rest}
-				{...pressProps}
-				ref={ref}
-				style={[style, attachedStyle]}
-				collapsable={false}
-			>
-				{children}
-				{canInjectLocalPortalHost ? extraChildren : null}
-			</AnimatedComponent>
-		);
-		const boundaryRoot = renderBoundaryRoot(
-			shouldPortalRoot ? undefined : localPortalHost,
-		);
-
 		return (
-			<BoundaryRootProvider value={contextValue}>
-				{shouldPortalRoot ? (
-					<Portal
-						id={boundTag.tag}
-						handoff={portalRuntime.handoff}
-						escapeClipping={portalRuntime.escapeClipping}
-						placeholderRef={rootPlaceholderRef}
-						placeholderChildren={
-							portalRuntime.handoff ? localPortalHost : undefined
-						}
+			<BoundaryRootProvider
+				config={{ anchor, scaleMode, target, method }}
+				enabled={enabled}
+				escapeClipping={escapeClipping}
+				forwardedRef={forwardedRef}
+				group={group}
+				handoff={handoff}
+				id={id}
+				style={style}
+			>
+				{(root) => (
+					<BoundaryPortal
+						boundaryId={root.boundTag.tag}
+						enabled={root.shouldRenderBoundaryRootThroughPortal}
+						placeholderRef={root.rootEscapePlaceholderRef}
 					>
-						{boundaryRoot}
-					</Portal>
-				) : (
-					boundaryRoot
+						<AnimatedComponent
+							{...rest}
+							ref={root.ref}
+							style={[style, root.attachedStyle]}
+							collapsable={false}
+						>
+							<BoundaryContentPortalHost
+								boundaryId={root.boundTag.tag}
+								enabled={root.shouldRenderHandoffHost}
+								screenKey={root.currentScreenKey}
+							>
+								{children}
+							</BoundaryContentPortalHost>
+						</AnimatedComponent>
+					</BoundaryPortal>
 				)}
 			</BoundaryRootProvider>
 		);

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,94 @@ export const useInitialDestinationMeasurement = ({
 			return;
 		}
 
-		unblockLifecycleStart();
 		isBlockingLifecycleStart.set(0);
-	};
+		unblockLifecycleStart();
+	}, [isBlockingLifecycleStart, retryToken, unblockLifecycleStart]);
 
-	useAnimatedReaction(
-		() => {
-			"worklet";
-			const retryTick = retryToken.get();
+	const claimLifecycleStartBlock = useCallback(() => {
+		"worklet";
+
+		// The progress check and block claim must share one UI-thread operation.
+		// Otherwise a JS-thread layout effect can observe zero, enqueue the block,
+		// and let the opening animation start before that block reaches the UI thread.
+		if (progress.get() > 0 || isBlockingLifecycleStart.get()) {
+			return;
+		}
 
-			const hasPendingOpenRequest =
-				pendingLifecycleRequestKind.get() ===
-				LifecycleTransitionRequestKind.Open;
+		blockLifecycleStart();
+		isBlockingLifecycleStart.set(1);
+	}, [blockLifecycleStart, isBlockingLifecycleStart, progress]);
 
-			const isWaitingForOpenToStart = progress.get() <= 0;
+	useLayoutEffect(() => {
+		if (!destinationEnabled || !initialDestinationPairKey) {
+			return;
+		}
 
-			if (!hasPendingOpenRequest || !isWaitingForOpenToStart) {
-				return [0, retryTick] as const;
+		runOnUI(claimLifecycleStartBlock)();
+
+		return () => {
+			if (escapeClipping) {
+				// The portal host owns the release after this boundary hands off.
+				return;
 			}
 
-			const measurePairKey = getInitialDestinationMeasurePairKey({
-				enabled: destinationEnabled,
+			// 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)();
+		};
+	}, [
+		claimLifecycleStartBlock,
+		destinationEnabled,
+		escapeClipping,
+		initialDestinationPairKey,
+		releaseLifecycleStartBlock,
+	]);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			const retryTick = retryToken.get();
+			const isWaitingForOpenToStart = progress.get() <= 0;
+			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 +171,51 @@ export const useInitialDestinationMeasurement = ({
 				return;
 			}
 
-			if (!isBlockingLifecycleStart.get()) {
-				blockLifecycleStart();
-				isBlockingLifecycleStart.set(1);
+			if (action === "release") {
+				releaseLifecycleStartBlock();
+				handshakeRetries.set(0);
+				return;
 			}
 
-			measureBoundary({
-				type: "destination",
-				pairKey: measurePairKey,
-			});
+			if (action === "measure") {
+				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,
 	});