react-native-screen-transitions 3.3.0 → 3.4.0-alpha.1

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

@@ -0,0 +1,263 @@
+import {
+	type ComponentType,
+	forwardRef,
+	memo,
+	useCallback,
+	useMemo,
+} from "react";
+import { Pressable, View as RNView, type View } from "react-native";
+import Animated, { runOnUI, useAnimatedRef } from "react-native-reanimated";
+import { useAssociatedStyles } from "../../hooks/animation/use-associated-style";
+import { useLayoutAnchorContext } from "../../providers/layout-anchor.provider";
+import { useDescriptorDerivations } from "../../providers/screen/descriptors";
+import { AnimationStore } from "../../stores/animation.store";
+import { BoundStore } from "../../stores/bounds";
+import { prepareStyleForBounds } from "../../utils/bounds/helpers/styles";
+import { useAutoSourceMeasurement } from "./hooks/use-auto-source-measurement";
+import { useBoundaryMeasureAndStore } from "./hooks/use-boundary-measure-and-store";
+import { useBoundaryPresence } from "./hooks/use-boundary-presence";
+import { useGroupActiveMeasurement } from "./hooks/use-group-active-measurement";
+import { useInitialLayoutHandler } from "./hooks/use-initial-layout-handler";
+import { usePendingDestinationMeasurement } from "./hooks/use-pending-destination-measurement";
+import { usePendingDestinationRetryMeasurement } from "./hooks/use-pending-destination-retry-measurement";
+import { useScrollSettledMeasurement } from "./hooks/use-scroll-settled-measurement";
+import type { BoundaryComponentProps, BoundaryConfigProps } from "./types";
+import { buildBoundaryMatchKey } from "./utils/build-boundary-match-key";
+
+const setGroupActiveIdOnUI = (group: string, id: string) => {
+	"worklet";
+	BoundStore.setGroupActiveId(group, id);
+};
+
+export function createBoundaryComponent<P extends object>(
+	Wrapped: ComponentType<P>,
+) {
+	const AnimatedComponent = Animated.createAnimatedComponent(Wrapped);
+
+	const Inner = forwardRef<
+		React.ComponentRef<typeof AnimatedComponent>,
+		BoundaryComponentProps<P>
+	>((props, _ref) => {
+		const {
+			enabled = true,
+			group,
+			id,
+			anchor,
+			scaleMode,
+			target,
+			method,
+			style,
+			onPress,
+			...rest
+		} = props as any;
+
+		const sharedBoundTag = buildBoundaryMatchKey({ group, id });
+		const animatedRef = useAnimatedRef<View>();
+
+		const {
+			previousScreenKey: preferredSourceScreenKey,
+			currentScreenKey,
+			nextScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			hasConfiguredInterpolator,
+		} = useDescriptorDerivations();
+		const runtimeEnabled = enabled && hasConfiguredInterpolator;
+		const hasNextScreen = !!nextScreenKey;
+		const shouldUpdateDestination = !hasNextScreen;
+		const layoutAnchor = useLayoutAnchorContext();
+		const boundaryConfig = useMemo<BoundaryConfigProps | undefined>(() => {
+			if (
+				anchor === undefined &&
+				scaleMode === undefined &&
+				target === undefined &&
+				method === undefined
+			) {
+				return undefined;
+			}
+
+			return {
+				anchor,
+				scaleMode,
+				target,
+				method,
+			};
+		}, [anchor, scaleMode, target, method]);
+
+		const isAnimating = AnimationStore.getRouteAnimation(
+			currentScreenKey,
+			"animating",
+		);
+		const progress = AnimationStore.getRouteAnimation(
+			currentScreenKey,
+			"progress",
+		);
+
+		const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
+
+		const { associatedStyles } = useAssociatedStyles({
+			id: sharedBoundTag,
+			resetTransformOnUnset: true,
+			waitForFirstResolvedStyle: true,
+		});
+
+		const maybeMeasureAndStore = useBoundaryMeasureAndStore({
+			enabled,
+			sharedBoundTag,
+			preferredSourceScreenKey,
+			currentScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			isAnimating,
+			preparedStyles,
+			animatedRef,
+			layoutAnchor,
+		});
+
+		const shouldRunDestinationEffects = runtimeEnabled && !hasNextScreen;
+
+		// Register/unregister this boundary in the presence map so source/destination
+		// matching can resolve across screens (including ancestor relationships).
+		useBoundaryPresence({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			currentScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			boundaryConfig,
+		});
+
+		// On the source screen, capture source bounds when a matching destination
+		// appears on the next screen.
+		useAutoSourceMeasurement({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			nextScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		// Primary destination capture: once a pending source link exists for this tag,
+		// measure destination bounds and complete the pair.
+		usePendingDestinationMeasurement({
+			sharedBoundTag,
+			enabled: shouldRunDestinationEffects,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		// Reliability fallback: retry destination capture during transition progress
+		// when the initial pending-destination attempt happens before layout is ready.
+		usePendingDestinationRetryMeasurement({
+			sharedBoundTag,
+			enabled: shouldRunDestinationEffects,
+			currentScreenKey,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			progress,
+			animating: isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// Grouped boundaries (e.g. paged/detail UIs): re-measure when this boundary
+		// becomes the active member so destination bounds stay accurate.
+		useGroupActiveMeasurement({
+			enabled: runtimeEnabled,
+			group,
+			id,
+			shouldUpdateDestination,
+			isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// While idle on source screens, re-measure after scroll settles so a later
+		// close transition starts from up-to-date source geometry.
+		useScrollSettledMeasurement({
+			enabled: runtimeEnabled,
+			group,
+			hasNextScreen,
+			isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// Destination mount-time capture path: onLayout schedules a one-time UI-thread
+		// initial measurement when transitions are active.
+		useInitialLayoutHandler({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			currentScreenKey,
+			ancestorKeys,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		const handlePress = useCallback(
+			(...args: unknown[]) => {
+				// Press path has priority: capture source before user onPress/navigation.
+				if (group) {
+					runOnUI(setGroupActiveIdOnUI)(group, String(id));
+				}
+				runOnUI(maybeMeasureAndStore)({ shouldSetSource: true });
+
+				if (typeof onPress === "function") {
+					onPress(...args);
+				}
+			},
+			[group, id, maybeMeasureAndStore, onPress],
+		);
+
+		const resolvedOnPress =
+			typeof onPress === "function" ? handlePress : undefined;
+
+		return (
+			<AnimatedComponent
+				{...(rest as any)}
+				ref={animatedRef}
+				style={[style, enabled ? associatedStyles : undefined]}
+				onPress={resolvedOnPress}
+				collapsable={false}
+			/>
+		);
+	});
+
+	return memo(Inner) as unknown as React.MemoExoticComponent<
+		React.ForwardRefExoticComponent<
+			BoundaryComponentProps<P> &
+				React.RefAttributes<React.ComponentRef<typeof Wrapped>>
+		>
+	>;
+}
+
+// Pre-built boundary component variants
+const BoundaryView = createBoundaryComponent(RNView);
+BoundaryView.displayName = "Transition.Boundary.View";
+
+const BoundaryPressable = createBoundaryComponent(Pressable);
+BoundaryPressable.displayName = "Transition.Boundary.Pressable";
+
+/**
+ * Shared-boundary components.
+ *
+ * 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).
+ *
+ * Press behavior:
+ * - When a boundary has `onPress` (typically `Boundary.Pressable`), source
+ *   measurement runs before the user callback. This gives navigation transitions
+ *   fresh source geometry on the first frame.
+ *
+ * Use:
+ * - `Boundary.View` for passive/shared elements.
+ * - `Boundary.Pressable` for tappable elements that start navigation.
+ */
+export const Boundary = {
+	/** Passive boundary wrapper (no built-in press semantics). */
+	View: BoundaryView,
+	/** Pressable boundary wrapper with press-priority source capture. */
+	Pressable: BoundaryPressable,
+	/** Factory for custom boundary wrappers. */
+	createBoundaryComponent,
+};

package/src/shared/components/create-boundary-component/types.ts

@@ -0,0 +1,47 @@
+import type { ViewProps } from "react-native";
+import type { BoundsOptions } from "../../utils/bounds/types/options";
+
+export type BoundaryId = string | number;
+
+export type BoundaryConfigProps = Pick<
+	BoundsOptions,
+	"anchor" | "scaleMode" | "target" | "method"
+>;
+
+/**
+ * Boundary-specific props shared across all boundary component variants.
+ * These are the props that `createBoundaryComponent` extracts and handles
+ * internally, regardless of the underlying wrapped component.
+ */
+export interface BoundaryOwnProps extends BoundaryConfigProps {
+	/**
+	 * Optional group name for collection/list scenarios.
+	 * When provided, boundaries are tracked as a group and the active member
+	 * re-measures automatically when focus changes within the group.
+	 * The internal tag becomes `group:id`.
+	 */
+	group?: string;
+	/**
+	 * Whether this boundary should participate in matching and measurement.
+	 * @default true
+	 */
+	enabled?: boolean;
+	id: BoundaryId;
+}
+
+/**
+ * Full props for a boundary component wrapping a component with props `P`.
+ * Omits `id` from the wrapped component's props (since boundary uses its own `id`).
+ */
+export type BoundaryComponentProps<P extends object> = Omit<P, "id"> &
+	BoundaryOwnProps;
+
+/** Convenience alias for a View-based boundary (the most common case). */
+export type BoundaryProps = BoundaryComponentProps<ViewProps>;
+
+export interface MaybeMeasureAndStoreParams {
+	shouldSetSource?: boolean;
+	shouldSetDestination?: boolean;
+	shouldUpdateSource?: boolean;
+	shouldUpdateDestination?: boolean;
+}

package/src/shared/components/create-boundary-component/utils/build-boundary-match-key.ts

@@ -0,0 +1,17 @@
+import type { BoundaryId } from "../types";
+
+type BuildBoundaryMatchKeyParams = {
+	group?: string;
+	id: BoundaryId;
+};
+
+export function buildBoundaryMatchKey(
+	params: BuildBoundaryMatchKeyParams,
+): string;
+export function buildBoundaryMatchKey(
+	params: BuildBoundaryMatchKeyParams,
+): string {
+	"worklet";
+	const { group, id } = params;
+	return group ? `${group}:${id}` : String(id);
+}

package/src/shared/components/create-transition-aware-component.tsx

@@ -1,16 +1,18 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <This helper is usually being used inside a transitionable stack> */
 import type React from "react";
-import { type ComponentType, forwardRef, memo } from "react";
+import { type ComponentType, forwardRef, memo, useCallback } from "react";
 import type { View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, {
 	runOnUI,
 	useAnimatedRef,
 	useComposedEventHandler,
+	useSharedValue,
 } from "react-native-reanimated";
 import { useAssociatedStyles } from "../hooks/animation/use-associated-style";
 import { useScrollRegistry } from "../hooks/gestures/use-scroll-registry";
 import { RegisterBoundsProvider } from "../providers/register-bounds.provider";
+import { ScrollSettleProvider } from "../providers/scroll-settle.provider";
 import type { TransitionAwareProps } from "../types/screen.types";
 
 interface CreateTransitionAwareComponentOptions {
@@ -32,9 +34,20 @@ export function createTransitionAwareComponent<P extends object>(
 		const {
 			remeasureOnFocus: _remeasureOnFocus,
 			onScroll: userOnScroll,
+			onMomentumScrollEnd: userOnMomentumScrollEnd,
+			onScrollEndDrag: userOnScrollEndDrag,
 			...scrollableProps
 		} = props;
 
+		const settledSignal = useSharedValue(0);
+
+		const emitScrollSettled = useCallback(() => {
+			runOnUI(() => {
+				"worklet";
+				settledSignal.value = settledSignal.value + 1;
+			})();
+		}, [settledSignal]);
+
 		// Determine scroll direction from the horizontal prop (standard ScrollView API)
 		const scrollDirection = scrollableProps.horizontal
 			? "horizontal"
@@ -53,11 +66,37 @@ export function createTransitionAwareComponent<P extends object>(
 			userOnScroll ?? null,
 		]);
 
+		const handleMomentumScrollEnd = useCallback(
+			(event: unknown) => {
+				userOnMomentumScrollEnd?.(event);
+				emitScrollSettled();
+			},
+			[userOnMomentumScrollEnd, emitScrollSettled],
+		);
+
+		const handleScrollEndDrag = useCallback(
+			(event: any) => {
+				userOnScrollEndDrag?.(event);
+
+				const velocityX = Math.abs(event?.nativeEvent?.velocity?.x ?? 0);
+				const velocityY = Math.abs(event?.nativeEvent?.velocity?.y ?? 0);
+
+				// If there is no momentum, onMomentumScrollEnd may not fire.
+				// Emit settled signal here only when velocity is effectively zero.
+				if (velocityX < 0.01 && velocityY < 0.01) {
+					emitScrollSettled();
+				}
+			},
+			[userOnScrollEndDrag, emitScrollSettled],
+		);
+
 		const scrollableComponent = (
 			<AnimatedComponent
 				{...(scrollableProps as any)}
 				ref={ref}
 				onScroll={composedScrollHandler}
+				onMomentumScrollEnd={handleMomentumScrollEnd}
+				onScrollEndDrag={handleScrollEndDrag}
 				onContentSizeChange={onContentSizeChange}
 				onLayout={onLayout}
 				scrollEventThrottle={scrollableProps.scrollEventThrottle || 16}
@@ -65,14 +104,16 @@ export function createTransitionAwareComponent<P extends object>(
 		);
 
 		// If no gesture owner found for this axis, render without GestureDetector
-		if (!nativeGesture) {
-			return scrollableComponent;
-		}
-
 		return (
-			<GestureDetector gesture={nativeGesture}>
-				{scrollableComponent}
-			</GestureDetector>
+			<ScrollSettleProvider settledSignal={settledSignal}>
+				{!nativeGesture ? (
+					scrollableComponent
+				) : (
+					<GestureDetector gesture={nativeGesture}>
+						{scrollableComponent}
+					</GestureDetector>
+				)}
+			</ScrollSettleProvider>
 		);
 	});
 
@@ -92,9 +133,11 @@ export function createTransitionAwareComponent<P extends object>(
 
 		const animatedRef = useAnimatedRef<View>();
 
-		const { associatedStyles } = useAssociatedStyles({
+		const { associatedStyles, associatedProps } = useAssociatedStyles({
 			id: sharedBoundTag || styleId,
 			style,
+			resetTransformOnUnset: !!sharedBoundTag,
+			waitForFirstResolvedStyle: false,
 		});
 
 		return (
@@ -110,6 +153,7 @@ export function createTransitionAwareComponent<P extends object>(
 						{...(rest as any)}
 						ref={animatedRef}
 						style={[style, associatedStyles]}
+						animatedProps={associatedProps}
 						onPress={captureActiveOnPress}
 						onLayout={runOnUI(handleInitialLayout)}
 						collapsable={!sharedBoundTag}

package/src/shared/components/native-screen.tsx

@@ -46,20 +46,16 @@ export const NativeScreen = ({
 }: ScreenProps) => {
 	const {
 		flags: { DISABLE_NATIVE_SCREENS = false },
-	} = useStack();
-
-	const {
-		activeScreensLimit,
 		routes,
 		optimisticFocusedIndex,
-		backdropBehaviors,
-	} = useManagedStackContext();
+	} = useStack();
+	const { activeScreensLimit, backdropBehaviors } = useManagedStackContext();
 
 	const routesLength = routes.length;
 	const screenRef = useAnimatedRef<View>();
 
-	const sceneProgress = AnimationStore.getAnimation(routeKey, "progress");
-	const sceneClosing = AnimationStore.getAnimation(routeKey, "closing");
+	const sceneProgress = AnimationStore.getRouteAnimation(routeKey, "progress");
+	const sceneClosing = AnimationStore.getRouteAnimation(routeKey, "closing");
 	const screenActivity = useSharedValue<ScreenActivity>(
 		ScreenActivity.TRANSITIONING_OR_BELOW_TOP,
 	);

package/src/shared/components/overlay/helpers/get-active-overlay.ts

@@ -1,10 +1,10 @@
 import type { StackScene } from "../../../hooks/navigation/use-stack";
-import { isFloatOverlayVisible } from "../../../utils/overlay/visibility";
+import { isOverlayVisible } from "../../../utils/overlay/visibility";
 
 /**
  * Find the active float overlay from scenes.
  * Scans from the top of the stack downward to find the first screen
- * with a visible overlay that isn't explicitly set to legacy screen mode.
+ * with a visible overlay.
  */
 export function getActiveFloatOverlay(
 	scenes: StackScene[],
@@ -30,7 +30,7 @@ export function getActiveFloatOverlay(
 			continue;
 		}
 
-		if (isFloatOverlayVisible(options)) {
+		if (isOverlayVisible(options)) {
 			return { scene, overlayIndex: i };
 		}
 	}

package/src/shared/components/overlay/index.ts

@@ -1,7 +1,5 @@
 import { FloatOverlay } from "./variations/float-overlay";
-import { ScreenOverlay } from "./variations/screen-overlay";
 
 export const Overlay = {
 	Float: FloatOverlay,
-	Screen: ScreenOverlay,
 };

package/src/shared/components/overlay/variations/float-overlay.tsx

@@ -2,21 +2,15 @@ import { useMemo } from "react";
 import { snapDescriptorToIndex } from "../../../animation/snap-to";
 import { useOptimisticFocusedIndex } from "../../../hooks/navigation/use-optimistic-focused-index";
 import { useStack } from "../../../hooks/navigation/use-stack";
-import type { BaseDescriptor } from "../../../providers/screen/keys.provider";
-import { KeysProvider } from "../../../providers/screen/keys.provider";
+import { ScreenAnimationProvider } from "../../../providers/screen/animation";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import { DescriptorsProvider } from "../../../providers/screen/descriptors";
 import { ScreenStylesProvider } from "../../../providers/screen/styles.provider";
-import type { OverlayProps } from "../../../types/overlay.types";
+import type { OverlayScreenState } from "../../../types/overlay.types";
+
 import { getActiveFloatOverlay } from "../helpers/get-active-overlay";
 import { OverlayHost } from "./overlay-host";
 
-type OverlayScreenState = Omit<
-	OverlayProps<BaseDescriptor["navigation"]>,
-	"progress" | "overlayAnimation" | "screenAnimation"
-> & {
-	index: number;
-	snapTo: (index: number) => void;
-};
-
 /**
  * Float overlay component that renders above all screens.
  * Gets routes and descriptors from stack context.
@@ -45,18 +39,19 @@ export function FloatOverlay() {
 		const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
 		const focusedDescriptor = focusedScene?.descriptor;
 
-		const overlayScreenState: OverlayScreenState = {
-			index: routeKeys.indexOf(current.route.key),
-			options: focusedDescriptor?.options ?? {},
-			routes,
-			focusedRoute: focusedScene?.route ?? current.route,
-			focusedIndex,
-			meta: focusedDescriptor?.options?.meta,
-			navigation: current.navigation,
-			snapTo: (index: number) => {
-				snapDescriptorToIndex(current, index);
-			},
-		};
+		const overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]> =
+			{
+				index: routeKeys.indexOf(current.route.key),
+				options: focusedDescriptor?.options ?? {},
+				routes,
+				focusedRoute: focusedScene?.route ?? current.route,
+				focusedIndex,
+				meta: focusedDescriptor?.options?.meta,
+				navigation: current.navigation,
+				snapTo: (index: number) => {
+					snapDescriptorToIndex(current, index);
+				},
+			};
 
 		return {
 			scene,
@@ -74,10 +69,12 @@ export function FloatOverlay() {
 	const { scene, previous, current, next, overlayScreenState } = overlayData;
 
 	return (
-		<KeysProvider current={current} previous={previous} next={next}>
-			<ScreenStylesProvider>
-				<OverlayHost scene={scene} overlayScreenState={overlayScreenState} />
-			</ScreenStylesProvider>
-		</KeysProvider>
+		<DescriptorsProvider current={current} previous={previous} next={next}>
+			<ScreenAnimationProvider>
+				<ScreenStylesProvider>
+					<OverlayHost scene={scene} overlayScreenState={overlayScreenState} />
+				</ScreenStylesProvider>
+			</ScreenAnimationProvider>
+		</DescriptorsProvider>
 	);
 }

package/src/shared/components/overlay/variations/overlay-host.tsx

@@ -3,26 +3,19 @@ import {
 	NavigationRouteContext,
 } from "@react-navigation/native";
 import { memo, useMemo } from "react";
-import { Animated, StyleSheet, useWindowDimensions, View } from "react-native";
+import { Animated, StyleSheet, View } from "react-native";
 import { useDerivedValue } from "react-native-reanimated";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { useScreenAnimation } from "../../../hooks/animation/use-screen-animation";
 import type { StackScene } from "../../../hooks/navigation/use-stack";
-import type { BaseDescriptor } from "../../../providers/screen/keys.provider";
-import type { OverlayInterpolationProps } from "../../../types/animation.types";
-import type { OverlayProps } from "../../../types/overlay.types";
-
-type OverlayScreenState = Omit<
-	OverlayProps<BaseDescriptor["navigation"]>,
-	"progress" | "overlayAnimation" | "screenAnimation"
-> & {
-	index: number;
-	snapTo: (index: number) => void;
-};
+import { useScreenAnimation } from "../../../providers/screen/animation";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import type {
+	OverlayProps,
+	OverlayScreenState,
+} from "../../../types/overlay.types";
 
 type OverlayHostProps = {
 	scene: StackScene;
-	overlayScreenState: OverlayScreenState;
+	overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]>;
 };
 
 export const OverlayHost = memo(function OverlayHost({
@@ -30,8 +23,6 @@ export const OverlayHost = memo(function OverlayHost({
 	overlayScreenState,
 }: OverlayHostProps) {
 	const OverlayComponent = scene.descriptor.options.overlay;
-	const screen = useWindowDimensions();
-	const insets = useSafeAreaInsets();
 
 	const screenAnimation = useScreenAnimation();
 	const relativeProgress = useDerivedValue(() => {
@@ -39,22 +30,12 @@ export const OverlayHost = memo(function OverlayHost({
 		return screenAnimation.value.stackProgress;
 	});
 
-	const overlayAnimation = useDerivedValue<OverlayInterpolationProps>(() => ({
-		progress: relativeProgress.value,
-		layouts: { screen },
-		insets,
-	}));
-
 	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(
 		() => ({
 			...overlayScreenState,
 			progress: relativeProgress,
-			/**@deprecated */
-			overlayAnimation,
-			/**@deprecated */
-			screenAnimation,
 		}),
-		[relativeProgress, overlayAnimation, screenAnimation, overlayScreenState],
+		[relativeProgress, overlayScreenState],
 	);
 
 	if (!OverlayComponent) {

package/src/shared/components/scene-view.tsx

@@ -0,0 +1,29 @@
+import {
+	NavigationContext,
+	NavigationRouteContext,
+} from "@react-navigation/native";
+import * as React from "react";
+import type { BaseStackDescriptor } from "../types/stack.types";
+
+type SceneViewProps = {
+	descriptor: BaseStackDescriptor;
+};
+
+/**
+ * Shared scene view for managed stacks (blank-stack, component-stack).
+ * Wraps screen render output with navigation context providers
+ * and optional screen overlay.
+ */
+export const SceneView = React.memo(function SceneView({
+	descriptor,
+}: SceneViewProps) {
+	const { route, navigation, render } = descriptor;
+
+	return (
+		<NavigationContext.Provider value={navigation as any}>
+			<NavigationRouteContext.Provider value={route}>
+				{render?.()}
+			</NavigationRouteContext.Provider>
+		</NavigationContext.Provider>
+	);
+});