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

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

@@ -5,18 +5,27 @@ import {
 	withDelay,
 	withTiming,
 } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../providers/screen/descriptors";
-import { AnimationStore } from "../../../stores/animation.store";
-import { getDestination } from "../../../stores/bounds/internals/links";
-import { pairs } from "../../../stores/bounds/internals/state";
-import type { BoundTag } from "../../../stores/bounds/types";
+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 { pairs } from "../../../../stores/bounds/internals/state";
+import type { BoundTag } from "../../../../stores/bounds/types";
 import {
 	LifecycleTransitionRequestKind,
 	SystemStore,
-} from "../../../stores/system.store";
-import { logger } from "../../../utils/logger";
-import type { MeasureBoundary } from "../types";
-import { getInitialDestinationMeasurePairKey } from "../utils/destination-signals";
+} 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";
 
 const VIEWPORT_RETRY_DELAY_MS = 100;
 /**
@@ -37,7 +46,7 @@ export const useInitialDestinationMeasurement = ({
 	enabled,
 	measureBoundary,
 }: UseInitialDestinationMeasurementParams) => {
-	const { linkKey, group } = boundTag;
+	const { tag, linkKey, group } = boundTag;
 	const currentScreenKey = useDescriptorsStore(
 		(s) => s.derivations.currentScreenKey,
 	);
@@ -109,9 +118,6 @@ export const useInitialDestinationMeasurement = ({
 		([measurePairKey, retryTick], previous) => {
 			"worklet";
 			if (!measurePairKey) {
-				releaseLifecycleStartBlock();
-				viewportRetries.set(0);
-				hasGivenUp.set(0);
 				return;
 			}
 
@@ -143,6 +149,27 @@ export const useInitialDestinationMeasurement = ({
 				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) {
+					// Screen-level escape has a second readiness phase after destination
+					// measurement: the host must commit before the transition starts, or
+					// the payload can disappear for a frame.
+					return;
+				}
 				releaseLifecycleStartBlock();
 				viewportRetries.set(0);
 				return;

package/src/shared/components/boundary/hooks/{use-initial-source-measurement.ts → lifecycles/use-initial-source-measurement.ts}

@@ -1,17 +1,16 @@
 import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../providers/screen/descriptors";
-import { pairs } from "../../../stores/bounds/internals/state";
-import type { BoundTag } from "../../../stores/bounds/types";
-import type { MeasureBoundary } from "../types";
-import { getInitialSourceCaptureSignal } from "../utils/source-signals";
+import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { pairs } from "../../../../stores/bounds/internals/state";
+import type { BoundTag } from "../../../../stores/bounds/types";
+import type { MeasureBoundary } from "../../types";
+import { getInitialSourceCaptureSignal } from "../../utils/source-signals";
 
 export const useInitialSourceMeasurement = (params: {
 	enabled: boolean;
 	measureBoundary: MeasureBoundary;
 	boundTag: BoundTag;
-	shouldAutoMeasure: boolean;
 }) => {
-	const { enabled, measureBoundary, boundTag, shouldAutoMeasure } = params;
+	const { enabled, measureBoundary, boundTag } = params;
 	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
 	const lastSourceCaptureSignal = useSharedValue<string | null>(null);
 
@@ -23,8 +22,7 @@ export const useInitialSourceMeasurement = (params: {
 				sourcePairKey,
 				linkId: boundTag.linkKey,
 				group: boundTag.group,
-				shouldAutoMeasure,
-				linkState: shouldAutoMeasure && sourcePairKey ? pairs.get() : undefined,
+				linkState: sourcePairKey ? pairs.get() : undefined,
 			});
 		},
 		(captureSignal) => {

package/src/shared/components/boundary/hooks/{use-refresh-boundary.ts → lifecycles/use-refresh-boundary.ts}

@@ -1,10 +1,10 @@
 import { useAnimatedReaction } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../providers/screen/descriptors";
-import { AnimationStore } from "../../../stores/animation.store";
-import { pairs } from "../../../stores/bounds/internals/state";
-import type { BoundTag } from "../../../stores/bounds/types";
-import type { MeasureBoundary } from "../types";
-import { getRefreshBoundarySignal } from "../utils/refresh-signals";
+import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { pairs } from "../../../../stores/bounds/internals/state";
+import type { BoundTag } from "../../../../stores/bounds/types";
+import type { MeasureBoundary } from "../../types";
+import { getRefreshBoundarySignal } from "../../utils/refresh-signals";
 
 interface UseRefreshBoundaryParams {
 	enabled: boolean;

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

@@ -1,17 +1,14 @@
-import { useCallback, useMemo } from "react";
+import { useMemo } from "react";
 import type { View } from "react-native";
 import type { AnimatedRef, StyleProps } from "react-native-reanimated";
-import { runOnUI } from "react-native-reanimated";
-import { createPendingPairKey } from "../../../stores/bounds/helpers/link-pairs.helpers";
 import type { BoundTag } from "../../../stores/bounds/types";
 import { prepareStyleForBounds } from "../../../utils/bounds/helpers/styles/styles";
-import { resolvePortalHost } from "../portal/resolve-portal";
-import type { BoundaryConfigProps, BoundaryPortal } from "../types";
-import { useBoundaryPresence } from "./use-boundary-presence";
-import { useInitialDestinationMeasurement } from "./use-initial-destination-measurement";
-import { useInitialSourceMeasurement } from "./use-initial-source-measurement";
+import type { BoundaryConfigProps } from "../types";
+import { useBoundaryPresence } from "./lifecycles/use-boundary-presence";
+import { useInitialDestinationMeasurement } from "./lifecycles/use-initial-destination-measurement";
+import { useInitialSourceMeasurement } from "./lifecycles/use-initial-source-measurement";
+import { useRefreshBoundary } from "./lifecycles/use-refresh-boundary";
 import { useMeasurer } from "./use-measurer";
-import { useRefreshBoundary } from "./use-refresh-boundary";
 
 interface UseBoundaryMeasurementParams {
 	boundTag: BoundTag;
@@ -25,17 +22,15 @@ interface UseBoundaryMeasurementParams {
 	/** Root's own style; ignored when a nested target supplies its own. */
 	style?: unknown;
 	targetPreparedStyles?: StyleProps;
-	portal?: BoundaryPortal;
-	shouldAutoMeasure: boolean;
+	handoff: boolean;
+	escapeClipping: boolean;
 	config: BoundaryConfigProps;
-	onPress?: (...args: unknown[]) => void;
 }
 
 /**
  * Owns the full measurement lifecycle for a boundary: builds the measurer,
  * registers presence, runs the initial source/destination + refresh reactions,
- * and returns the press-priority `onPress`. The component never touches the
- * measurer itself.
+ * and keeps the component itself away from the measurer.
  */
 export const useBoundaryMeasurement = ({
 	boundTag,
@@ -45,10 +40,9 @@ export const useBoundaryMeasurement = ({
 	measuredRef,
 	style,
 	targetPreparedStyles,
-	portal,
-	shouldAutoMeasure,
+	handoff,
+	escapeClipping,
 	config,
-	onPress,
 }: UseBoundaryMeasurementParams) => {
 	const { anchor, scaleMode, target, method } = config;
 	const boundaryConfig = useMemo<BoundaryConfigProps>(
@@ -62,15 +56,14 @@ export const useBoundaryMeasurement = ({
 	);
 	const preparedStyles = targetPreparedStyles ?? rootPreparedStyles;
 
-	const portalHost = resolvePortalHost(portal);
-
 	const measureBoundary = useMeasurer({
 		enabled,
 		boundTag,
 		currentScreenKey,
 		preparedStyles,
 		measuredAnimatedRef: measuredRef,
-		portalHost,
+		handoff,
+		escapeClipping,
 	});
 
 	// Register/unregister this boundary in the presence map so source/destination
@@ -80,18 +73,14 @@ export const useBoundaryMeasurement = ({
 		boundTag,
 		currentScreenKey,
 		boundaryConfig,
+		handoff,
+		escapeClipping,
 	});
 
-	// Passive auto-measurement only applies to non-pressable boundaries; pressable
-	// ones capture their source on press (see handlePress below).
-	const shouldPassivelyMeasureSource =
-		shouldAutoMeasure && typeof onPress !== "function";
-
 	useInitialSourceMeasurement({
 		enabled: runtimeEnabled,
 		measureBoundary,
 		boundTag,
-		shouldAutoMeasure: shouldPassivelyMeasureSource,
 	});
 
 	useInitialDestinationMeasurement({
@@ -105,23 +94,4 @@ export const useBoundaryMeasurement = ({
 		boundTag,
 		measureBoundary,
 	});
-
-	const handlePress = useCallback(
-		(...args: unknown[]) => {
-			// Press path has priority: capture source before user onPress/navigation.
-			runOnUI(measureBoundary)({
-				type: "source",
-				pairKey: createPendingPairKey(currentScreenKey),
-			});
-
-			if (typeof onPress === "function") {
-				onPress(...args);
-			}
-		},
-		[measureBoundary, onPress, currentScreenKey],
-	);
-
-	return {
-		onPress: typeof onPress === "function" ? handlePress : undefined,
-	};
 };

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

@@ -8,13 +8,9 @@ import {
 } from "react-native-reanimated";
 import { applyMeasuredBoundsWrites } from "../../../providers/helpers/measured-bounds-writes";
 import { useOriginContext } from "../../../providers/screen/origin.provider";
-import type {
-	BoundsPortalAttachTarget,
-	BoundTag,
-} from "../../../stores/bounds/types";
+import type { BoundTag } from "../../../stores/bounds/types";
 import { ScrollStore } from "../../../stores/scroll.store";
 import { SystemStore } from "../../../stores/system.store";
-import { getActiveScrollHost } from "../portal/stores/host-registry.store";
 import type { MeasureBoundary } from "../types";
 import {
 	attachScrollSnapshotToMeasuredBounds,
@@ -29,7 +25,8 @@ interface UseMeasurerParams {
 	currentScreenKey: string;
 	preparedStyles: StyleProps;
 	measuredAnimatedRef: AnimatedRef<View>;
-	portalHost?: BoundsPortalAttachTarget;
+	handoff: boolean;
+	escapeClipping: boolean;
 }
 
 export const useMeasurer = ({
@@ -38,7 +35,8 @@ export const useMeasurer = ({
 	currentScreenKey,
 	preparedStyles,
 	measuredAnimatedRef,
-	portalHost,
+	handoff,
+	escapeClipping,
 }: UseMeasurerParams): MeasureBoundary => {
 	const { width: viewportWidth, height: viewportHeight } =
 		useWindowDimensions();
@@ -94,10 +92,6 @@ export const useMeasurer = ({
 				normalizedMeasured,
 				scrollMetadata.get(),
 			);
-			const sourceHost =
-				target.type === "source"
-					? (getActiveScrollHost(currentScreenKey) ?? undefined)
-					: undefined;
 
 			applyMeasuredBoundsWrites({
 				entryTag: boundTag.tag,
@@ -107,8 +101,8 @@ export const useMeasurer = ({
 				measured: measuredWithScroll,
 				preparedStyles,
 				linkWrite: target,
-				portalHost,
-				sourceHost,
+				handoff,
+				escapeClipping,
 			});
 		},
 		[
@@ -117,7 +111,8 @@ export const useMeasurer = ({
 			currentScreenKey,
 			preparedStyles,
 			measuredAnimatedRef,
-			portalHost,
+			handoff,
+			escapeClipping,
 			viewportWidth,
 			viewportHeight,
 			scrollState,

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

@@ -1,58 +1,84 @@
-import { Pressable, View } from "react-native";
+import { forwardRef } from "react";
+import {
+	Pressable,
+	type PressableProps,
+	View,
+	type ViewProps,
+} from "react-native";
 import { BoundaryTarget } from "./components/boundary-target";
 import { createBoundaryComponent } from "./create-boundary-component";
 import { Host } from "./portal";
+import type { BoundaryComponentProps } from "./types";
 
-export type {
-	BoundaryPortal,
-	BoundaryPortalAttachTarget,
-	BoundaryPortalOptions,
-} from "./types";
 export { createBoundaryComponent };
 
-const BoundaryView = createBoundaryComponent(View, {
-	shouldAutoMeasure: true,
-});
+type BoundaryPrimitiveProps = Omit<ViewProps, "id" | "style"> &
+	Omit<PressableProps, "id" | "style"> & {
+		style?: ViewProps["style"] | PressableProps["style"];
+	};
+
+const BoundaryPrimitive = forwardRef<View, BoundaryPrimitiveProps>(
+	(props, ref) => {
+		const Component = "onPress" in props ? Pressable : View;
+
+		return <Component {...(props as any)} ref={ref as any} />;
+	},
+);
+
+BoundaryPrimitive.displayName = "Transition.Boundary.Primitive";
+
+const BoundaryRoot = createBoundaryComponent(BoundaryPrimitive);
+const BoundaryView = createBoundaryComponent(View);
 const BoundaryTrigger = createBoundaryComponent(Pressable);
+BoundaryRoot.displayName = "Transition.Boundary";
 BoundaryView.displayName = "Transition.Boundary.View";
 BoundaryTrigger.displayName = "Transition.Boundary.Trigger";
 BoundaryTarget.displayName = "Transition.Boundary.Target";
 Host.displayName = "Transition.Boundary.Host";
 
+type BoundaryRootComponent = typeof BoundaryRoot;
+
 /**
- * Shared-boundary components.
+ * Shared-boundary component with static helpers.
  *
  * How measurement works:
- * 1. Source screen captures bounds for a tag.
- * 2. Destination screen captures bounds for the same tag.
- * 3. The link is updated as layout changes (group-active + scroll-settled paths).
+ * 1. Destination screen captures bounds for a tag.
+ * 2. Source screen captures bounds for the same concrete pair.
+ * 3. The link is updated as layout changes.
  *
- * Trigger behavior:
- * - When a boundary has `onPress` (typically `Boundary.Trigger`), source
- *   measurement runs before the user callback. This gives navigation transitions
- *   fresh source geometry on the first frame.
+ * Runtime primitive:
+ * - With an `onPress` handler, the root renders as a Pressable.
+ * - Without an `onPress` handler, the root renders as a View.
  *
  * Use:
- * - `Boundary.View` for passive/shared elements.
- * - `Boundary.Trigger` for tappable elements that start navigation.
+ * - `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.
  */
-export const Boundary = {
+export interface BoundaryComponent extends BoundaryRootComponent {
 	/**
-	 * Passive boundary wrapper (no built-in press semantics).
+	 * Optional nested measurement override inside a boundary root.
 	 */
-	View: BoundaryView,
+	Target: typeof BoundaryTarget;
 	/**
-	 * Pressable boundary wrapper with press-priority source capture.
+	 * Explicit portal host for scrollable or otherwise clipped coordinate spaces.
 	 */
-	Trigger: BoundaryTrigger,
+	Host: typeof Host;
 	/**
-	 * Optional nested measurement override inside a boundary root.
+	 * @deprecated Use `Transition.Boundary` without `onPress`.
 	 */
-	Target: BoundaryTarget,
+	View: typeof BoundaryView;
 	/**
-	 * Explicit portal host for scrollable or otherwise clipped coordinate spaces.
+	 * @deprecated Use `Transition.Boundary` with `onPress`.
 	 */
-	Host: Host,
-};
+	Trigger: typeof BoundaryTrigger;
+}
+
+export type BoundaryProps = BoundaryComponentProps<BoundaryPrimitiveProps>;
+
+export const Boundary = Object.assign(BoundaryRoot, {
+	Target: BoundaryTarget,
+	Host,
+	View: BoundaryView,
+	Trigger: BoundaryTrigger,
+}) as BoundaryComponent;

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

@@ -0,0 +1,66 @@
+import { memo, useCallback, useLayoutEffect } from "react";
+import { StyleSheet, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { SystemStore } from "../../../../stores/system.store";
+import { NativePortalHost } from "../teleport";
+import { createBoundaryLocalPortalHostName } from "../utils/naming";
+
+const AnimatedPortalHost = NativePortalHost
+	? Animated.createAnimatedComponent(NativePortalHost)
+	: null;
+
+type BoundaryLocalPortalHostProps = {
+	boundaryId: string;
+	enabled: boolean;
+	screenKey: string;
+};
+
+export const BoundaryLocalPortalHost = memo(function BoundaryLocalPortalHost({
+	boundaryId,
+	enabled,
+	screenKey,
+}: BoundaryLocalPortalHostProps) {
+	const { drainLifecycleStartBlocks } = SystemStore.getBag(screenKey).actions;
+	const handleLayout = useCallback(() => {
+		drainLifecycleStartBlocks();
+	}, [drainLifecycleStartBlocks]);
+
+	useLayoutEffect(() => {
+		if (!enabled || !AnimatedPortalHost) {
+			return;
+		}
+
+		drainLifecycleStartBlocks();
+	}, [enabled, drainLifecycleStartBlocks]);
+
+	if (!enabled || !AnimatedPortalHost) {
+		return null;
+	}
+
+	const portalHostName = createBoundaryLocalPortalHostName(
+		screenKey,
+		boundaryId,
+	);
+
+	return (
+		<View
+			pointerEvents="none"
+			style={styles.hostWrapper}
+			onLayout={handleLayout}
+			collapsable={false}
+		>
+			<AnimatedPortalHost name={portalHostName} style={styles.host} />
+		</View>
+	);
+});
+
+const styles = StyleSheet.create({
+	host: {
+		...StyleSheet.absoluteFillObject,
+		overflow: "visible",
+	},
+	hostWrapper: {
+		...StyleSheet.absoluteFillObject,
+		overflow: "visible",
+	},
+});

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

@@ -1,4 +1,4 @@
-import { memo, useLayoutEffect, useRef } from "react";
+import { memo, useCallback, useLayoutEffect, useRef } from "react";
 import {
 	type StyleProp,
 	StyleSheet,
@@ -8,6 +8,7 @@ import {
 } from "react-native";
 import Animated from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { SystemStore } from "../../../../stores/system.store";
 import { useHostMeasurement } from "../hooks/use-host-measurement";
 import { registerHost, unregisterHost } from "../stores/host-registry.store";
 import { useActivePortalBoundaryHosts } from "../stores/portal-boundary-host.store";
@@ -25,6 +26,7 @@ type HostImplProps = PublicHostProps & {
 
 function HostImpl({ fallback = false, style }: HostImplProps) {
 	const screenKey = useDescriptorsStore((s) => s.derivations.currentScreenKey);
+	const { drainLifecycleStartBlocks } = SystemStore.getBag(screenKey).actions;
 	const generatedHostKeyRef = useRef<string | null>(null);
 
 	if (generatedHostKeyRef.current === null) {
@@ -57,15 +59,28 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 		};
 	}, [capturesScroll, fallback, hostKey, screenKey]);
 
+	const handleUnblocking = useCallback(() => {
+		// Screen-level escape keeps the open transition gated until portal hosts
+		// have committed layout. A screen may render more than one portal boundary
+		// host for the same lifecycle request, so the final host layout drains the
+		// outstanding start blocks for this screen.
+		drainLifecycleStartBlocks();
+	}, [drainLifecycleStartBlocks]);
+
 	const boundaryHosts = measurement.canRenderHosts
-		? activeBoundaryHosts.map((host) => (
+		? activeBoundaryHosts.map((host, idx, list) => (
 				<View
-					key={host.boundaryId}
-					pointerEvents="box-none"
+					key={host.portalHostName}
+					pointerEvents="none"
 					style={[
 						styles.boundaryHostViewport,
 						{ width: viewportWidth, height: viewportHeight },
 					]}
+					onLayout={() => {
+						if (list.length - 1 === idx) {
+							handleUnblocking();
+						}
+					}}
 				>
 					<PortalBoundaryHost host={host} style={StyleSheet.absoluteFill} />
 				</View>
@@ -75,7 +90,7 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 	return (
 		<Animated.View
 			ref={measurement.hostRef}
-			pointerEvents="box-none"
+			pointerEvents="none"
 			style={[
 				styles.host,
 				{ width: viewportWidth, height: viewportHeight },