react-native-screen-transitions 4.0.0-alpha.0 → 4.0.0-alpha.10

package/src/components/boundary/portal/utils/resolve-portal.ts

@@ -1,17 +1,33 @@
 import { logger } from "../../../../utils/logger";
 import { isTeleportAvailable } from "../teleport";
 
-export type BoundaryPortalRuntime = {
+export type BoundaryPortalRuntime = Readonly<{
 	handoff: boolean;
 	escapeClipping: boolean;
-	enabled: boolean;
-};
+}>;
 
 type ResolveBoundaryPortalParams = {
 	handoff?: boolean;
 	escapeClipping?: boolean;
 };
 
+const DISABLED_RUNTIME: BoundaryPortalRuntime = {
+	handoff: false,
+	escapeClipping: false,
+};
+const HANDOFF_RUNTIME: BoundaryPortalRuntime = {
+	handoff: true,
+	escapeClipping: false,
+};
+const ESCAPE_CLIPPING_RUNTIME: BoundaryPortalRuntime = {
+	handoff: false,
+	escapeClipping: true,
+};
+const HANDOFF_ESCAPE_CLIPPING_RUNTIME: BoundaryPortalRuntime = {
+	handoff: true,
+	escapeClipping: true,
+};
+
 export const resolveBoundaryPortal = ({
 	handoff,
 	escapeClipping,
@@ -22,11 +38,7 @@ export const resolveBoundaryPortal = ({
 	const enabled = resolvedHandoff || resolvedEscapeClipping;
 
 	if (!enabled) {
-		return {
-			handoff: false,
-			escapeClipping: false,
-			enabled: false,
-		};
+		return DISABLED_RUNTIME;
 	}
 
 	if (!isTeleportAvailable) {
@@ -35,16 +47,12 @@ export const resolveBoundaryPortal = ({
 			"react-native-teleport is not installed; handoff and escapeClipping boundaries will render inline.",
 		);
 
-		return {
-			handoff: false,
-			escapeClipping: false,
-			enabled: false,
-		};
+		return DISABLED_RUNTIME;
 	}
 
-	return {
-		handoff: resolvedHandoff,
-		escapeClipping: resolvedEscapeClipping,
-		enabled,
-	};
+	return resolvedHandoff
+		? resolvedEscapeClipping
+			? HANDOFF_ESCAPE_CLIPPING_RUNTIME
+			: HANDOFF_RUNTIME
+		: ESCAPE_CLIPPING_RUNTIME;
 };

package/src/components/boundary/portal/utils/teleport-control.ts

@@ -11,15 +11,3 @@ export const isTeleportEnabled = (
 
 	return teleport?.enabled !== false;
 };
-
-export const shouldAttachBoundaryPortal = ({
-	enabled,
-	teleport,
-}: {
-	enabled: boolean;
-	teleport?: BoundaryTeleportControl;
-}) => {
-	"worklet";
-
-	return enabled && isTeleportEnabled(teleport);
-};

package/src/components/boundary/providers/boundary-root.provider.tsx

@@ -1,25 +1,25 @@
 import {
 	type ForwardedRef,
 	type ReactNode,
-	useCallback,
 	useImperativeHandle,
+	useLayoutEffect,
 	useMemo,
 	useRef,
-	useState,
 } from "react";
 import type { View } from "react-native";
-import type { AnimatedRef, StyleProps } from "react-native-reanimated";
-import { useAnimatedRef } from "react-native-reanimated";
+import type { AnimatedRef } from "react-native-reanimated";
+import { useAnimatedRef, useSharedValue } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../providers/screen/descriptors";
 import {
 	useComposedSlotStyles,
 	useSlotStackingStyles,
 } from "../../../providers/screen/styles";
+import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
 import { createBoundTag } from "../../../stores/bounds/helpers/link-pairs.helpers";
 import type { BoundTag } from "../../../stores/bounds/types";
 import createProvider from "../../../utils/create-provider";
 import { logger } from "../../../utils/logger";
-import { useBoundaryMeasurement } from "../hooks/use-boundary-measurement";
+import { BoundaryLifecycle } from "../components/boundary-lifecycle";
 import {
 	type BoundaryPortalRuntime,
 	resolveBoundaryPortal,
@@ -27,31 +27,16 @@ import {
 import type {
 	BoundaryConfigProps,
 	BoundaryId,
+	BoundaryLocalMeasurement,
+	BoundaryLocalMeasurementValue,
 	BoundaryOwnProps,
 } from "../types";
 
-interface BoundaryRootContextValue extends BoundaryRootRenderState {
-	registerTargetRef: (
-		targetRef: AnimatedRef<View>,
-		preparedStyles: StyleProps,
-		measurementRef?: AnimatedRef<View>,
-	) => void;
-	unregisterTargetRef: (targetRef: AnimatedRef<View>) => void;
-	activeTargetRef: AnimatedRef<View> | null;
-	boundTag: BoundTag;
-	portalRuntime: BoundaryPortalRuntime;
-}
-
-type BoundaryTargetEntry = {
-	ref: AnimatedRef<View>;
-	/** Surface to measure — the portal placeholder when content can teleport. */
-	measurementRef: AnimatedRef<View>;
-	preparedStyles: StyleProps;
-};
+type BoundaryRootContextValue = BoundaryRootRenderState;
 
 // logger.warn prepends the library prefix.
 const MULTIPLE_TARGETS_WARNING =
-	"Multiple Boundary.Target elements were rendered under the same boundary root. The first registered target will be measured.";
+	"Multiple Boundary.Target elements were rendered under the same boundary root. The first target in render order will be measured.";
 
 export const TARGET_OUTSIDE_ROOT_WARNING =
 	"Boundary.Target must be rendered inside Transition.Boundary or a component created by createBoundaryComponent.";
@@ -61,9 +46,10 @@ export type BoundaryRootRenderState = {
 	boundTag: BoundTag;
 	currentScreenKey: string;
 	handoffEnabled: boolean;
+	localMeasurement: BoundaryLocalMeasurementValue;
+	measurementRef: AnimatedRef<View>;
 	portalRuntime: BoundaryPortalRuntime;
 	ref: AnimatedRef<View>;
-	rootEscapePlaceholderRef: AnimatedRef<View>;
 	shouldRenderBoundaryRootThroughPortal: boolean;
 	shouldRenderHandoffHost: boolean;
 };
@@ -75,15 +61,18 @@ type BoundaryRootProviderProps = Pick<
 	children: (state: BoundaryRootRenderState) => ReactNode;
 	config: BoundaryConfigProps;
 	forwardedRef?: ForwardedRef<any>;
+	hasTarget: boolean;
 	id: BoundaryId;
 	style?: unknown;
+	targetCount: number;
+	targetStyle?: unknown;
 };
 
 export const {
 	BoundaryRootProvider,
-	useBoundaryRootContext,
 	useBoundaryRootStore,
-} = createProvider("BoundaryRoot", { guarded: false })<
+	useOptionalBoundaryRootStore,
+} = createProvider("BoundaryRoot")<
 	BoundaryRootProviderProps,
 	BoundaryRootContextValue
 >(
@@ -95,8 +84,11 @@ export const {
 		forwardedRef,
 		group,
 		handoff,
+		hasTarget,
 		id,
 		style,
+		targetCount,
+		targetStyle,
 	}) => {
 		const requestedBoundTag = useMemo(
 			() => createBoundTag(String(id), group),
@@ -110,12 +102,14 @@ export const {
 		const currentScreenKey = useDescriptorsStore(
 			(s) => s.derivations.currentScreenKey,
 		);
-		const currentActivity = useDescriptorsStore(
-			(s) => s.descriptors.current.activity,
+		const isCurrentScreenClosing = useBlankStackStore(
+			(store) =>
+				portalRuntime.handoff &&
+				store.scenesByKey[currentScreenKey]?.activity === "closing",
 		);
 		const retainedBoundTagRef = useRef(requestedBoundTag);
 		const shouldRetainClosingBoundTag =
-			portalRuntime.handoff && currentActivity === "closing";
+			portalRuntime.handoff && isCurrentScreenClosing;
 
 		// Navigation can update a retained closing route's params before that
 		// route leaves the stack. Keep its handoff identity stable so the payload
@@ -125,10 +119,6 @@ export const {
 		}
 
 		const boundTag = retainedBoundTagRef.current;
-		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;
@@ -137,69 +127,26 @@ export const {
 		const associatedStyles = useComposedSlotStyles(boundTag.tag, style);
 		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
 		const rootRef = useAnimatedRef<View>();
-		const rootEscapePlaceholderRef = useAnimatedRef<View>();
-		const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
+		const measurementRef = useAnimatedRef<View>();
+		const localMeasurement = useSharedValue<BoundaryLocalMeasurement | null>(
 			null,
 		);
 
-		const registerTargetRef = useCallback(
-			(
-				targetRef: AnimatedRef<View>,
-				preparedStyles: StyleProps,
-				measurementRef?: AnimatedRef<View>,
-			) => {
-				setTargetEntry((prev) => {
-					if (prev?.ref === targetRef) {
-						return prev;
-					}
-
-					if (__DEV__ && prev !== null) {
-						logger.warnOnce(
-							"boundary:multiple-targets",
-							MULTIPLE_TARGETS_WARNING,
-						);
-					}
-
-					return (
-						prev ?? {
-							ref: targetRef,
-							measurementRef: measurementRef ?? targetRef,
-							preparedStyles,
-						}
-					);
-				});
-			},
-			[],
-		);
-
-		const unregisterTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
-			setTargetEntry((prev) => (prev?.ref === targetRef ? null : prev));
-		}, []);
+		useLayoutEffect(() => {
+			if (__DEV__ && targetCount > 1) {
+				logger.warnOnce("boundary:multiple-targets", MULTIPLE_TARGETS_WARNING);
+			}
+		}, [targetCount]);
 
-		const rootMeasurementRef = shouldEscapeBoundaryRootToScreenHost
-			? rootEscapePlaceholderRef
-			: rootRef;
-		const measuredRef = targetEntry?.measurementRef ?? rootMeasurementRef;
-		const hasActiveTarget = targetEntry !== null;
-		const targetPreparedStyles = targetEntry?.preparedStyles;
+		const measuredRef =
+			hasTarget || shouldEscapeBoundaryRootToScreenHost
+				? measurementRef
+				: rootRef;
 
 		useImperativeHandle(forwardedRef, () => rootRef.current as any, [rootRef]);
 
-		useBoundaryMeasurement({
-			boundTag,
-			enabled,
-			runtimeEnabled,
-			currentScreenKey,
-			measuredRef,
-			style,
-			targetPreparedStyles,
-			handoff: portalRuntime.handoff,
-			escapeClipping: portalRuntime.escapeClipping,
-			config,
-		});
-
 		const shouldRenderBoundaryRootThroughPortal =
-			shouldEscapeBoundaryRootToScreenHost && !hasActiveTarget;
+			shouldEscapeBoundaryRootToScreenHost && !hasTarget;
 		const handoffEnabled = enabled && portalRuntime.handoff;
 		// A nested active target takes the full associated style, so the root keeps
 		// only its stacking context. Root-owned escape-clipping moves the root
@@ -209,7 +156,7 @@ export const {
 		// handoff host is absolute-filled inside this root, so the root is the
 		// visual frame that animates the received payload.
 		const attachedStyle = shouldAttachAssociatedStyles
-			? hasActiveTarget
+			? hasTarget
 				? associatedStackingStyles
 				: shouldRenderBoundaryRootThroughPortal
 					? undefined
@@ -219,37 +166,48 @@ export const {
 		const value = useMemo<BoundaryRootContextValue>(
 			() => ({
 				attachedStyle,
-				activeTargetRef: targetEntry?.ref ?? null,
 				boundTag,
 				currentScreenKey,
 				handoffEnabled,
+				localMeasurement,
+				measurementRef,
 				portalRuntime,
-				registerTargetRef,
 				ref: rootRef,
-				rootEscapePlaceholderRef,
 				shouldRenderBoundaryRootThroughPortal,
-				shouldRenderHandoffHost: handoffEnabled && !hasActiveTarget,
-				unregisterTargetRef,
+				shouldRenderHandoffHost: handoffEnabled && !hasTarget,
 			}),
 			[
 				attachedStyle,
 				boundTag,
 				currentScreenKey,
 				handoffEnabled,
-				hasActiveTarget,
+				hasTarget,
+				localMeasurement,
+				measurementRef,
 				portalRuntime,
-				registerTargetRef,
 				rootRef,
-				rootEscapePlaceholderRef,
 				shouldRenderBoundaryRootThroughPortal,
-				targetEntry,
-				unregisterTargetRef,
 			],
 		);
 
 		return {
 			value,
-			children: children(value),
+			children: (
+				<>
+					{children(value)}
+					<BoundaryLifecycle
+						boundTag={boundTag}
+						config={config}
+						currentScreenKey={currentScreenKey}
+						enabled={enabled}
+						escapeClipping={portalRuntime.escapeClipping}
+						handoff={portalRuntime.handoff}
+						localMeasurement={localMeasurement}
+						measuredRef={measuredRef}
+						style={hasTarget ? targetStyle : style}
+					/>
+				</>
+			),
 		};
 	},
 );

package/src/components/boundary/types.ts

@@ -1,3 +1,4 @@
+import type { MeasuredDimensions, SharedValue } from "react-native-reanimated";
 import type { ScreenPairKey } from "../../stores/bounds/types";
 import type { BoundsOptions } from "../../utils/bounds/types/options";
 
@@ -60,3 +61,11 @@ export type MeasureTarget =
 	  };
 
 export type MeasureBoundary = (target: MeasureTarget) => void;
+
+export type BoundaryLocalMeasurement = {
+	bounds: MeasuredDimensions;
+	pairKey: ScreenPairKey;
+};
+
+export type BoundaryLocalMeasurementValue =
+	SharedValue<BoundaryLocalMeasurement | null>;

package/src/components/boundary/utils/destination-signals.ts

@@ -14,14 +14,13 @@ export type InitialDestinationMeasurementAction =
 	| "complete";
 
 export type InitialDestinationMeasurementSignal = {
-	pairKey: ScreenPairKey;
+	pairKey: ScreenPairKey | null;
 	action: InitialDestinationMeasurementAction;
 };
 
 export const getInitialDestinationMeasurementSignal = (params: {
 	enabled: boolean;
-	destinationPairKey?: ScreenPairKey;
-	ancestorDestinationPairKey?: ScreenPairKey;
+	pairKey?: ScreenPairKey;
 	linkId: string;
 	group?: string;
 	destinationPresent: boolean;
@@ -31,20 +30,21 @@ export const getInitialDestinationMeasurementSignal = (params: {
 	"worklet";
 	const {
 		enabled,
-		destinationPairKey,
-		ancestorDestinationPairKey,
+		pairKey,
 		linkId,
 		group,
 		destinationPresent,
 		sourcePresent,
 		linkState,
 	} = params;
-	const pairKey = destinationPairKey ?? ancestorDestinationPairKey;
-
-	if (!enabled || !pairKey) {
+	if (!enabled) {
 		return null;
 	}
 
+	if (!pairKey) {
+		return { pairKey: null, action: "wait" };
+	}
+
 	if (!destinationPresent) {
 		return { pairKey, action: "wait" };
 	}

package/src/components/boundary/utils/measured-bounds.ts

@@ -60,18 +60,6 @@ export const adjustedMeasuredBoundsForOverscrollDeltas = (
 	};
 };
 
-export const normalizeMeasuredBoundsToOrigin = (
-	measured: MeasuredDimensions,
-	origin: MeasuredDimensions,
-): MeasuredDimensions => {
-	"worklet";
-	return {
-		...measured,
-		pageX: measured.pageX - origin.pageX,
-		pageY: measured.pageY - origin.pageY,
-	};
-};
-
 export const isMeasurementInViewport = (
 	measured: MeasuredDimensions,
 	viewportWidth: number,
@@ -96,52 +84,61 @@ export const isMeasurementInViewport = (
 	);
 };
 
-export const normalizeMeasuredBoundsWithVisibilityGate = ({
+export const correctMeasuredBoundsForVisibilityGate = ({
 	measured,
-	origin,
 	visibilityBlocked,
 	visibilityBlockOffset,
 	viewportWidth,
 	viewportHeight,
 }: {
 	measured: MeasuredDimensions;
-	origin: MeasuredDimensions;
 	visibilityBlocked: boolean;
 	visibilityBlockOffset: number;
 	viewportWidth: number;
 	viewportHeight: number;
 }): MeasuredDimensions => {
 	"worklet";
-	const normalized = normalizeMeasuredBoundsToOrigin(measured, origin);
 
 	if (
 		!visibilityBlocked ||
 		visibilityBlockOffset <= 0 ||
-		isMeasurementInViewport(normalized, viewportWidth, viewportHeight)
+		isMeasurementInViewport(measured, viewportWidth, viewportHeight)
 	) {
-		return normalized;
+		return measured;
 	}
 
-	// Fabric can expose the visibility transform to one native measurement one
-	// frame before the other. Prefer normal origin-relative coordinates, then
-	// test either side of that known frame skew while the gate is active.
-	const measuredAhead = {
-		...normalized,
-		pageY: normalized.pageY - visibilityBlockOffset,
+	// A destination can still carry the internal visibility transform for one
+	// native frame. Correct only that known offset and preserve all other
+	// presentation transforms in the measured coordinates.
+	const visibilityOffsetApplied = {
+		...measured,
+		pageY: measured.pageY - visibilityBlockOffset,
 	};
-	if (isMeasurementInViewport(measuredAhead, viewportWidth, viewportHeight)) {
-		return measuredAhead;
+	if (
+		isMeasurementInViewport(
+			visibilityOffsetApplied,
+			viewportWidth,
+			viewportHeight,
+		)
+	) {
+		return visibilityOffsetApplied;
 	}
 
-	const originAhead = {
-		...normalized,
-		pageY: normalized.pageY + visibilityBlockOffset,
+	const inverseVisibilityOffsetApplied = {
+		...measured,
+		pageY: measured.pageY + visibilityBlockOffset,
 	};
-	if (isMeasurementInViewport(originAhead, viewportWidth, viewportHeight)) {
-		return originAhead;
+	if (
+		isMeasurementInViewport(
+			inverseVisibilityOffsetApplied,
+			viewportWidth,
+			viewportHeight,
+		)
+	) {
+		return inverseVisibilityOffsetApplied;
 	}
 
-	return normalized;
+	return measured;
 };
 
 export const measureWithOverscrollAwareness = (