react-native-screen-transitions 4.0.0-alpha.6 → 4.0.0-alpha.8

package/src/components/activity/activity-view.tsx

@@ -0,0 +1,93 @@
+import { Activity, type ReactNode } from "react";
+import {
+	type HostComponent,
+	NativeComponentRegistry,
+	type ViewProps,
+} from "react-native";
+
+export type ActivityViewMode = "normal" | "inert" | "paused";
+
+interface ActivityViewProps {
+	children: ReactNode;
+	mode: ActivityViewMode;
+	visible: boolean;
+}
+
+/**
+ * Separates React lifecycle activity from native presentation.
+ *
+ * A paused Activity tears down effects and deprioritizes updates. Keeping an
+ * explicit display value on its host view lets `pause` preserve the last paint,
+ * while `hide` can pause the same subtree and remove its presentation.
+ */
+export function ActivityView({ children, mode, visible }: ActivityViewProps) {
+	const activityMode = mode === "paused" ? "hidden" : "visible";
+	const display = visible ? "contents" : "none";
+	const { ContentView, PaintView } = getNativeActivityViews();
+
+	return (
+		<Activity mode={activityMode}>
+			<ContentView style={{ display: "contents" }}>
+				<PaintView style={{ display }}>{children}</PaintView>
+			</ContentView>
+		</Activity>
+	);
+}
+
+const ACTIVITY_CONTENT_STYLE: Record<
+	string,
+	true | { process?: (value: unknown) => unknown }
+> = {
+	display: {
+		// Activity writes display:none to its nearest host child. Preserve the
+		// native paint while React pauses the subtree.
+		process: () => "contents",
+	},
+};
+
+const ACTIVITY_PAINT_STYLE: Record<
+	string,
+	true | { process?: (value: unknown) => unknown }
+> = {
+	display: {
+		process: (value: unknown) => (value === "none" ? "none" : "contents"),
+	},
+};
+
+const ACTIVITY_CONTENT_VIEW_CONFIG = {
+	uiViewClassName: "RCTView",
+	validAttributes: { style: ACTIVITY_CONTENT_STYLE },
+};
+
+const ACTIVITY_PAINT_VIEW_CONFIG = {
+	uiViewClassName: "RCTView",
+	validAttributes: { style: ACTIVITY_PAINT_STYLE },
+};
+
+type NativeActivityViewProps = Omit<ViewProps, "style"> & {
+	style?: { display?: "contents" | "none" };
+};
+
+let nativeActivityViews:
+	| {
+			ContentView: HostComponent<NativeActivityViewProps>;
+			PaintView: HostComponent<NativeActivityViewProps>;
+	  }
+	| undefined;
+
+function getNativeActivityViews() {
+	if (!nativeActivityViews) {
+		nativeActivityViews = {
+			ContentView: NativeComponentRegistry.get<NativeActivityViewProps>(
+				"ScreenTransitionsActivityContentView",
+				() => ACTIVITY_CONTENT_VIEW_CONFIG,
+			),
+			PaintView: NativeComponentRegistry.get<NativeActivityViewProps>(
+				"ScreenTransitionsActivityPaintView",
+				() => ACTIVITY_PAINT_VIEW_CONFIG,
+			),
+		};
+	}
+
+	return nativeActivityViews;
+}

package/src/components/activity/activity-view.web.tsx

@@ -0,0 +1,79 @@
+/// <reference lib="dom" />
+
+import { Activity, type ReactNode, useCallback } from "react";
+import { StyleSheet, View } from "react-native";
+
+export type ActivityViewMode = "normal" | "inert" | "paused";
+
+interface ActivityViewProps {
+	children: ReactNode;
+	mode: ActivityViewMode;
+	visible: boolean;
+}
+
+/**
+ * Web Activity writes display:none directly to its host child. Observe that
+ * write so lifecycle pausing and retained paint remain independent there too.
+ */
+export function ActivityView({ children, mode, visible }: ActivityViewProps) {
+	const display = visible ? "flex" : "none";
+	const activityMode = mode === "paused" ? "hidden" : "visible";
+	const onRef = useCallback(
+		(node: React.ComponentRef<typeof View> | null) => {
+			if (!(node instanceof HTMLElement)) {
+				return;
+			}
+
+			const childObservers: MutationObserver[] = [];
+			const observeChildren = () => {
+				for (const observer of childObservers) {
+					observer.disconnect();
+				}
+				childObservers.length = 0;
+
+				node.childNodes.forEach((child) => {
+					if (!(child instanceof HTMLElement)) {
+						return;
+					}
+
+					child.style.display = display;
+					const observer = new MutationObserver(() => {
+						child.style.display = display;
+					});
+					observer.observe(child, {
+						attributes: true,
+						attributeFilter: ["style"],
+					});
+					childObservers.push(observer);
+				});
+			};
+
+			observeChildren();
+			const observer = new MutationObserver(observeChildren);
+			observer.observe(node, { childList: true });
+
+			return () => {
+				observer.disconnect();
+				for (const childObserver of childObservers) {
+					childObserver.disconnect();
+				}
+			};
+		},
+		[display],
+	);
+
+	return (
+		<View ref={onRef} collapsable={false} style={styles.contents}>
+			<Activity mode={activityMode}>
+				<View collapsable={false} style={[styles.content, { display }]}>
+					{children}
+				</View>
+			</Activity>
+		</View>
+	);
+}
+
+const styles = StyleSheet.create({
+	contents: { display: "contents" },
+	content: { flex: 1 },
+});

package/src/components/activity/variants/activity-container.tsx

@@ -1,25 +1,13 @@
 import { StyleSheet, View } from "react-native";
 
-import { ScreenContainer } from "react-native-screens";
-import { IS_WEB } from "../../../constants";
-import { useStack } from "../../../hooks/navigation/use-stack";
-
 interface Props {
 	children: React.ReactNode;
 }
 
 export const ActivityContainer = ({ children }: Props) => {
-	const nativeScreenDisabled = useStack((s) => s.flags.DISABLE_NATIVE_SCREENS);
-	const Component = IS_WEB || nativeScreenDisabled ? View : ScreenContainer;
 	return (
-		<Component collapsable={false} style={styles.container}>
+		<View collapsable={false} style={StyleSheet.absoluteFill}>
 			{children}
-		</Component>
+		</View>
 	);
 };
-
-const styles = StyleSheet.create({
-	container: {
-		flex: 1,
-	},
-});

package/src/components/activity/variants/activity-screen.tsx

@@ -2,23 +2,13 @@ import type * as React from "react";
 import { memo } from "react";
 import { StyleSheet, View, type ViewProps } from "react-native";
 import { useDerivedValue } from "react-native-reanimated";
-import { Screen } from "react-native-screens";
-import { IS_WEB } from "../../../constants";
-import { useStack } from "../../../hooks/navigation/use-stack";
 import { useSharedValueState } from "../../../hooks/reanimated/use-shared-value-state";
 import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
 import { AnimationStore } from "../../../stores/animation.store";
 import type { StackSceneActivity } from "../../../types/stack.types";
+import { ActivityView, type ActivityViewMode } from "../activity-view";
 import { DEFAULT_INACTIVE_BEHAVIOR, type InactiveBehavior } from "../helpers";
 
-type ActivityState = 0 | 1 | 2;
-const ActivityStateByActivity = {
-	active: 2,
-	inert: 1,
-	inactive: 0,
-	closing: 1,
-} satisfies Record<StackSceneActivity, ActivityState>;
-
 const PointerEventsByActivity = {
 	active: "auto",
 	inert: "auto",
@@ -27,53 +17,32 @@ const PointerEventsByActivity = {
 } satisfies Record<StackSceneActivity, ViewProps["pointerEvents"]>;
 
 interface ActivityScreenProps {
-	activity?: StackSceneActivity;
 	children: React.ReactNode;
 	inactiveBehavior?: InactiveBehavior;
 	paintDriverRouteKey?: string;
 	hasNestedState?: boolean;
-	routeKey?: string;
+	routeKey: string;
 }
 
 export const ActivityScreen = memo(function ActivityScreen({
-	activity,
 	children,
 	inactiveBehavior,
 	paintDriverRouteKey,
 	hasNestedState,
 	routeKey,
 }: ActivityScreenProps) {
-	const stackActivity = useBlankStackStore((store) =>
-		routeKey ? store?.scenesByKey[routeKey]?.activity : undefined,
-	);
-	const stackInactiveBehavior = useBlankStackStore((store) =>
-		routeKey
-			? (
-					store?.scenesByKey[routeKey]?.descriptor.options as
-						| { inactiveBehavior?: InactiveBehavior }
-						| undefined
-				)?.inactiveBehavior
-			: undefined,
+	const scene = useBlankStackStore((store) => store.scenesByKey[routeKey]);
+	const stackPaintDriverRouteKey = useBlankStackStore((store) =>
+		store.paintDriverRouteKeyByRouteKey.get(routeKey),
 	);
-	const stackRoute = useBlankStackStore((store) =>
-		routeKey ? store?.scenesByKey[routeKey]?.route : undefined,
-	);
-	const stackPaintDriverRouteKey = useBlankStackStore((store) => {
-		if (!routeKey || !store) {
-			return undefined;
-		}
-
-		const routeIndex = store.routeKeys.indexOf(routeKey);
-		return store.routeKeys[routeIndex + 2];
-	});
-	const resolvedActivity = activity ?? stackActivity ?? "active";
+	const stackInactiveBehavior = (
+		scene.descriptor.options as { inactiveBehavior?: InactiveBehavior }
+	).inactiveBehavior;
 	const resolvedInactiveBehavior =
 		inactiveBehavior ?? stackInactiveBehavior ?? DEFAULT_INACTIVE_BEHAVIOR;
 	const resolvedPaintDriverRouteKey =
 		paintDriverRouteKey ?? stackPaintDriverRouteKey;
-	const resolvedHasNestedState =
-		hasNestedState ?? (stackRoute ? "state" in stackRoute : false);
-	const nativeScreenDisabled = useStack((s) => s.flags.DISABLE_NATIVE_SCREENS);
+	const resolvedHasNestedState = hasNestedState ?? "state" in scene.route;
 	const paintDriverAnimations = resolvedPaintDriverRouteKey
 		? AnimationStore.getBag(resolvedPaintDriverRouteKey)
 		: undefined;
@@ -97,77 +66,41 @@ export const ActivityScreen = memo(function ActivityScreen({
 
 	const isPaintDriverSettledOnJS = useSharedValueState(isPaintDriverSettled);
 
-	let activityState: ActivityState = ActivityStateByActivity[resolvedActivity];
-	let shouldFreeze = false;
-	let visible = resolvedActivity !== "inactive";
+	let activityViewMode: ActivityViewMode =
+		scene.activity === "active" ? "normal" : "inert";
+	let visible = scene.activity !== "inactive";
 
-	const shouldWaitForPaintDriver = !isPaintDriverSettledOnJS;
-
-	if (resolvedActivity === "inactive") {
-		if (resolvedInactiveBehavior === "keep") {
-			activityState = 1;
-			visible = true;
-		} else if (shouldWaitForPaintDriver) {
-			// Delay hiding until the paint driver has settled to avoid
-			// a blank frame during the transition.
-			activityState = 1;
+	if (scene.activity === "inactive") {
+		if (resolvedInactiveBehavior === "keep" || !isPaintDriverSettledOnJS) {
 			visible = true;
 		} else if (resolvedInactiveBehavior === "pause") {
-			activityState = 1;
-			shouldFreeze = true;
+			activityViewMode = "paused";
 			visible = true;
 		} else {
-			// `hide` freezes and hides native presentation. Non-nested
-			// `unmount` removes the React subtree through the JS guard below.
-			activityState = 0;
-			shouldFreeze = true;
+			activityViewMode = "paused";
 			visible = false;
 		}
 	}
 
 	const shouldUnmount =
 		resolvedInactiveBehavior === "unmount" &&
-		resolvedActivity === "inactive" &&
+		scene.activity === "inactive" &&
 		!resolvedHasNestedState &&
 		isPaintDriverSettledOnJS;
 
-	const pointerEvents = PointerEventsByActivity[resolvedActivity];
-
 	if (shouldUnmount) {
 		return null;
 	}
 
-	const style = [StyleSheet.absoluteFill, visible ? undefined : styles.hidden];
-
-	if (IS_WEB || nativeScreenDisabled) {
-		return (
-			<View style={style} pointerEvents={pointerEvents} collapsable={false}>
-				{children}
-			</View>
-		);
-	}
-
 	return (
-		<Screen
-			style={style}
-			activityState={activityState}
-			shouldFreeze={shouldFreeze}
-			pointerEvents={pointerEvents}
+		<View
+			style={StyleSheet.absoluteFill}
+			pointerEvents={PointerEventsByActivity[scene.activity]}
 			collapsable={false}
 		>
-			{children}
-		</Screen>
+			<ActivityView mode={activityViewMode} visible={visible}>
+				{children}
+			</ActivityView>
+		</View>
 	);
 });
-
-const HIDDEN_SCREEN_OFFSET = 10_000;
-const styles = StyleSheet.create({
-	hidden: {
-		// NOTE:
-		// When setting a screen to display:"none", the gesture detector will not recognize anymore. Since I believe
-		// rngh is attaching itself to its nearest native view, this of course would kill the detector.
-		// To avoid this, we use a transform to move the screen off-screen instead of display: "none". This isn't my favorite approach,
-		// but i'm hoping react 19's activity could mitigate this better and avoid dependence on rns.
-		transform: [{ translateY: HIDDEN_SCREEN_OFFSET }],
-	},
-});

package/src/components/boundary/components/boundary-lifecycle.tsx

@@ -0,0 +1,53 @@
+import { memo } from "react";
+import type { View } from "react-native";
+import type { AnimatedRef } from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../providers/screen/descriptors";
+import type { BoundTag } from "../../../stores/bounds/types";
+import { useBoundaryMeasurement } from "../hooks/use-boundary-measurement";
+import type {
+	BoundaryConfigProps,
+	BoundaryLocalMeasurementValue,
+} from "../types";
+
+interface BoundaryLifecycleProps {
+	boundTag: BoundTag;
+	config: BoundaryConfigProps;
+	currentScreenKey: string;
+	enabled: boolean;
+	escapeClipping: boolean;
+	handoff: boolean;
+	localMeasurement: BoundaryLocalMeasurementValue;
+	measuredRef: AnimatedRef<View>;
+	style?: unknown;
+}
+
+export const BoundaryLifecycle = memo(function BoundaryLifecycle({
+	boundTag,
+	config,
+	currentScreenKey,
+	enabled,
+	escapeClipping,
+	handoff,
+	localMeasurement,
+	measuredRef,
+	style,
+}: BoundaryLifecycleProps) {
+	const hasConfiguredInterpolator = useDescriptorsStore(
+		(s) => s.derivations.hasConfiguredInterpolator,
+	);
+
+	useBoundaryMeasurement({
+		boundTag,
+		enabled,
+		runtimeEnabled: enabled && hasConfiguredInterpolator,
+		currentScreenKey,
+		measuredRef,
+		style,
+		handoff,
+		escapeClipping,
+		localMeasurement,
+		config,
+	});
+
+	return null;
+});

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

@@ -13,7 +13,7 @@ import {
 import { BoundaryPortal } from "../portal/components/boundary-portal";
 import {
 	TARGET_OUTSIDE_ROOT_WARNING,
-	useBoundaryRootStore,
+	useOptionalBoundaryRootStore,
 } from "../providers/boundary-root.provider";
 
 type BoundaryTargetProps = Omit<
@@ -36,7 +36,7 @@ const BoundaryTargetInner = (props: InternalBoundaryTargetProps) => {
 		style,
 		...rest
 	} = props;
-	const rootContext = useBoundaryRootStore();
+	const rootContext = useOptionalBoundaryRootStore();
 	const boundaryId = rootContext?.boundTag.tag;
 	const isActiveTarget = active === true && rootContext !== null;
 	const portalRuntime = rootContext?.portalRuntime;

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

@@ -7,8 +7,8 @@ import {
 	withTiming,
 } from "react-native-reanimated";
 import { scheduleOnUI } from "react-native-worklets";
-import { useStack } from "../../../../hooks/navigation/use-stack";
 import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { useBlankStackStore } from "../../../../providers/stack/blank-stack.provider";
 import { AnimationStore } from "../../../../stores/animation.store";
 import {
 	createScreenPairKey,
@@ -39,14 +39,12 @@ 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;
@@ -62,7 +60,7 @@ export const useInitialDestinationMeasurement = ({
 	const preferredSourceScreenKey = destinationPairKey
 		? getSourceScreenKeyFromPairKey(destinationPairKey)
 		: undefined;
-	const stackScenes = useStack((store) => store.scenes);
+	const stackScenes = useBlankStackStore((store) => store.scenes);
 	// A retained closing screen can still have registered boundaries, but it
 	// cannot own a new transition link.
 	const closingSourceScreenKeys = useMemo(
@@ -142,18 +140,12 @@ export const useInitialDestinationMeasurement = ({
 		scheduleOnUI(claimLifecycleStartBlock);
 
 		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.
 			scheduleOnUI(releaseLifecycleStartBlock);
 		};
 	}, [
 		claimLifecycleStartBlock,
-		escapeClipping,
 		canReceiveDestination,
 		releaseLifecycleStartBlock,
 	]);
@@ -247,12 +239,6 @@ export const useInitialDestinationMeasurement = ({
 				cancelAnimation(retryToken);
 				handshakeRetries.set(0);
 				hasFinishedInitialMeasurement.set(1);
-				if (escapeClipping) {
-					// Screen-level escape has a second readiness phase after destination
-					// matching: the host must commit before the transition starts, or
-					// the payload can disappear for a frame.
-					return;
-				}
 				releaseLifecycleStartBlock();
 				return;
 			}

package/src/components/boundary/hooks/lifecycles/use-refresh-boundary.ts

@@ -33,14 +33,24 @@ export const useRefreshBoundary = ({
 		refreshScreenKey,
 		"willAnimate",
 	);
+	const refreshSettled = AnimationStore.getValue(
+		refreshScreenKey,
+		"progressSettled",
+	);
 	const refreshClosing = AnimationStore.getValue(refreshScreenKey, "closing");
 
 	useAnimatedReaction(
 		() => {
 			"worklet";
 
-			const shouldRefresh = enabled && !!refreshWillAnimate.get();
-			if (!shouldRefresh) {
+			if (!enabled) return null;
+
+			const shouldRefresh = !!refreshWillAnimate.get();
+			const settled = !!refreshSettled.get();
+			// A group's active member can change while the transition is settled
+			// (for example, paging a destination gallery). Let that member publish
+			// fresh bounds even though there is no willAnimate lifecycle pulse yet.
+			if (!shouldRefresh && (!group || !settled)) {
 				return null;
 			}
 			const sourcePairKey =
@@ -56,6 +66,7 @@ export const useRefreshBoundary = ({
 				linkId: linkKey,
 				group,
 				shouldRefresh,
+				settled,
 				closing: !!refreshClosing.get(),
 				linkState: pairs.get(),
 			});

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

@@ -3,7 +3,10 @@ import type { View } from "react-native";
 import type { AnimatedRef } from "react-native-reanimated";
 import type { BoundTag } from "../../../stores/bounds/types";
 import { prepareStyleForBounds } from "../../../utils/bounds/helpers/styles/styles";
-import type { BoundaryConfigProps } from "../types";
+import type {
+	BoundaryConfigProps,
+	BoundaryLocalMeasurementValue,
+} 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";
@@ -23,6 +26,7 @@ interface UseBoundaryMeasurementParams {
 	style?: unknown;
 	handoff: boolean;
 	escapeClipping: boolean;
+	localMeasurement: BoundaryLocalMeasurementValue;
 	config: BoundaryConfigProps;
 }
 
@@ -40,6 +44,7 @@ export const useBoundaryMeasurement = ({
 	style,
 	handoff,
 	escapeClipping,
+	localMeasurement,
 	config,
 }: UseBoundaryMeasurementParams) => {
 	const { anchor, scaleMode, target, method } = config;
@@ -58,6 +63,7 @@ export const useBoundaryMeasurement = ({
 		measuredAnimatedRef: measuredRef,
 		handoff,
 		escapeClipping,
+		localMeasurement,
 	});
 
 	// Presence and source capture must not depend on this screen owning an
@@ -81,7 +87,6 @@ export const useBoundaryMeasurement = ({
 	useInitialDestinationMeasurement({
 		boundTag,
 		enabled: runtimeEnabled,
-		escapeClipping,
 		measureBoundary,
 	});
 

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

@@ -3,12 +3,12 @@ import type { View } from "react-native";
 import { useWindowDimensions } from "react-native";
 import type { AnimatedRef, StyleProps } from "react-native-reanimated";
 import { applyMeasuredBoundsWrites } from "../../../providers/helpers/measured-bounds-writes";
-import { useScreenSlots } from "../../../providers/screen/styles";
+import { useScreenSlotStore } 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 type { BoundaryLocalMeasurementValue, MeasureBoundary } from "../types";
 import {
 	attachScrollSnapshotToMeasuredBounds,
 	correctMeasuredBoundsForVisibilityGate,
@@ -24,6 +24,7 @@ interface UseMeasurerParams {
 	measuredAnimatedRef: AnimatedRef<View>;
 	handoff: boolean;
 	escapeClipping: boolean;
+	localMeasurement: BoundaryLocalMeasurementValue;
 }
 
 export const useMeasurer = ({
@@ -34,6 +35,7 @@ export const useMeasurer = ({
 	measuredAnimatedRef,
 	handoff,
 	escapeClipping,
+	localMeasurement,
 }: UseMeasurerParams): MeasureBoundary => {
 	const { width: viewportWidth, height: viewportHeight } =
 		useWindowDimensions();
@@ -44,7 +46,9 @@ export const useMeasurer = ({
 		currentScreenKey,
 		"pendingLifecycleStartBlockCount",
 	);
-	const { visibilityBlocked } = useScreenSlots();
+	const visibilityBlocked = useScreenSlotStore(
+		(store) => store.visibilityBlocked,
+	);
 
 	return useCallback(
 		(target) => {
@@ -66,6 +70,13 @@ export const useMeasurer = ({
 				viewportHeight,
 			});
 
+			if (escapeClipping && target.type === "source") {
+				localMeasurement.set({
+					bounds: measured,
+					pairKey: target.pairKey,
+				});
+			}
+
 			/**
 			 * - Destination Pass -
 			 * Be strict while lifecycle start is blocked for destination capture.
@@ -112,6 +123,7 @@ export const useMeasurer = ({
 			measuredAnimatedRef,
 			handoff,
 			escapeClipping,
+			localMeasurement,
 			viewportWidth,
 			viewportHeight,
 			scrollState,