react-native-screen-transitions 4.1.0-alpha.0 → 4.1.0-beta.1

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

@@ -9,21 +9,16 @@ import {
 import type { View } from "react-native";
 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 { useBuilderStore } from "../../../providers/screen/builder";
 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 { BoundaryLifecycle } from "../components/boundary-lifecycle";
-import {
-	type BoundaryPortalRuntime,
-	resolveBoundaryPortal,
-} from "../portal/utils/resolve-portal";
+import { useBoundaryPresentation } from "../hooks/use-boundary-presentation";
+import { useComposedBoundaryStyle } from "../hooks/use-composed-boundary-style";
+import { resolveBoundaryPortal } from "../portal/utils/resolve-portal";
 import type {
 	BoundaryConfigProps,
 	BoundaryId,
@@ -42,13 +37,17 @@ export const TARGET_OUTSIDE_ROOT_WARNING =
 	"Boundary.Target must be rendered inside Transition.Boundary or a component created by createBoundaryComponent.";
 
 export type BoundaryRootRenderState = {
+	boundaryPresentation: ReturnType<
+		typeof useBoundaryPresentation
+	>["presentation"];
+	slotsMap: ReturnType<typeof useBoundaryPresentation>["slotsMap"];
 	attachedStyle: unknown;
 	boundTag: BoundTag;
 	currentScreenKey: string;
 	handoffEnabled: boolean;
 	localMeasurement: BoundaryLocalMeasurementValue;
 	measurementRef: AnimatedRef<View>;
-	portalRuntime: BoundaryPortalRuntime;
+	portalRuntime: ReturnType<typeof resolveBoundaryPortal>;
 	ref: AnimatedRef<View>;
 	shouldRenderBoundaryRootThroughPortal: boolean;
 	shouldRenderHandoffHost: boolean;
@@ -94,12 +93,12 @@ export const {
 			() => createBoundTag(String(id), group),
 			[id, group],
 		);
-		const portalRuntime = resolveBoundaryPortal({
-			handoff,
-			escapeClipping,
-		});
+		const portalRuntime = useMemo(
+			() => resolveBoundaryPortal({ handoff, escapeClipping }),
+			[handoff, escapeClipping],
+		);
 
-		const currentScreenKey = useDescriptorsStore(
+		const currentScreenKey = useBuilderStore(
 			(s) => s.derivations.currentScreenKey,
 		);
 		const isCurrentScreenClosing = useBlankStackStore(
@@ -124,8 +123,19 @@ export const {
 		const shouldAttachAssociatedStyles = enabled;
 		const shouldEscapeBoundaryRootToScreenHost = portalRuntime.escapeClipping;
 
-		const associatedStyles = useComposedSlotStyles(boundTag.tag, style);
-		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
+		const { presentation: boundaryPresentation, slotsMap } =
+			useBoundaryPresentation(
+				boundTag.tag,
+				enabled && (portalRuntime.handoff || portalRuntime.escapeClipping),
+			);
+
+		const associatedStyles = useComposedBoundaryStyle(
+			slotsMap,
+			boundTag.tag,
+			style,
+			hasTarget ? "stacking" : "full",
+		);
+
 		const rootRef = useAnimatedRef<View>();
 		const measurementRef = useAnimatedRef<View>();
 		const localMeasurement = useSharedValue<BoundaryLocalMeasurement | null>(
@@ -155,16 +165,16 @@ export const {
 		// Host-only handoff receivers still need the associated style: their
 		// handoff host is absolute-filled inside this root, so the root is the
 		// visual frame that animates the received payload.
-		const attachedStyle = shouldAttachAssociatedStyles
-			? hasTarget
-				? associatedStackingStyles
-				: shouldRenderBoundaryRootThroughPortal
-					? undefined
-					: associatedStyles
-			: undefined;
+		const attachedStyle =
+			shouldAttachAssociatedStyles &&
+			(hasTarget || !shouldRenderBoundaryRootThroughPortal)
+				? associatedStyles
+				: undefined;
 
 		const value = useMemo<BoundaryRootContextValue>(
 			() => ({
+				boundaryPresentation,
+				slotsMap,
 				attachedStyle,
 				boundTag,
 				currentScreenKey,
@@ -177,6 +187,8 @@ export const {
 				shouldRenderHandoffHost: handoffEnabled && !hasTarget,
 			}),
 			[
+				boundaryPresentation,
+				slotsMap,
 				attachedStyle,
 				boundTag,
 				currentScreenKey,

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

@@ -86,13 +86,13 @@ export const isMeasurementInViewport = (
 
 export const correctMeasuredBoundsForVisibilityGate = ({
 	measured,
-	visibilityBlocked,
+	isScreenReady,
 	visibilityBlockOffset,
 	viewportWidth,
 	viewportHeight,
 }: {
 	measured: MeasuredDimensions;
-	visibilityBlocked: boolean;
+	isScreenReady: boolean;
 	visibilityBlockOffset: number;
 	viewportWidth: number;
 	viewportHeight: number;
@@ -100,7 +100,7 @@ export const correctMeasuredBoundsForVisibilityGate = ({
 	"worklet";
 
 	if (
-		!visibilityBlocked ||
+		isScreenReady ||
 		visibilityBlockOffset <= 0 ||
 		isMeasurementInViewport(measured, viewportWidth, viewportHeight)
 	) {

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

@@ -1,14 +1,19 @@
 /** 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 { LayoutChangeEvent } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, { useComposedEventHandler } from "react-native-reanimated";
 import {
 	ScrollMetadataOwnerProvider,
 	useScrollGestureCoordination,
-} from "../providers/screen/gestures/scroll-coordination";
-import { useSlotProps, useSlotStyles } from "../providers/screen/styles";
+} from "../providers/screen/motion/gestures/scroll-coordination";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../providers/screen/orchestrator/styles";
 import type { TransitionAwareProps } from "../types/screen.types";
+import { useContentLayout } from "./screen/container/hooks/use-content-layout";
 
 interface CreateTransitionAwareComponentOptions {
 	isScrollable?: boolean;
@@ -110,17 +115,27 @@ export function createTransitionAwareComponent<P extends object>(
 			children,
 			style,
 			styleId,
+			onLayout,
 			animatedProps: userAnimatedProps,
 			...rest
 		} = props as any;
 
 		const associatedStyles = useSlotStyles(styleId);
 		const associatedProps = useSlotProps(styleId);
+		const measureLayout = useContentLayout(styleId);
 
 		return (
 			<AnimatedComponent
 				{...(rest as any)}
 				ref={ref}
+				onLayout={
+					measureLayout
+						? (event: LayoutChangeEvent) => {
+								measureLayout(event);
+								onLayout?.(event);
+							}
+						: onLayout
+				}
 				style={[style, associatedStyles]}
 				animatedProps={userAnimatedProps ?? associatedProps}
 			>

package/src/components/overlay/helpers/create-overlay-interpolator-frame.ts

@@ -1,5 +1,5 @@
-import { updateDerivations } from "../../../providers/screen/animation/helpers/derivations";
-import type { ScreenInterpolatorFrame } from "../../../providers/screen/animation/helpers/pipeline";
+import { updateDerivations } from "../../../providers/screen/orchestrator/helpers/derivations";
+import type { ScreenInterpolatorFrame } from "../../../providers/screen/orchestrator/helpers/pipeline";
 
 export const shouldUseOverlayGestureDriver = (
 	overlayFrame: ScreenInterpolatorFrame,

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

@@ -2,8 +2,6 @@ import type { BaseStackScene } from "../../../types/stack.types";
 
 type StackScene = BaseStackScene;
 
-import { isOverlayVisible } from "../../../utils/overlay/visibility";
-
 export type FloatOverlayEntry = {
 	scene: StackScene;
 	overlayIndex: number;
@@ -19,7 +17,6 @@ export type FloatOverlayTransitionEntry = FloatOverlayEntry & {
  */
 export function getFloatOverlayStack(
 	scenes: StackScene[],
-	transitionsAlwaysOn: boolean,
 ): FloatOverlayEntry[] {
 	const candidates: FloatOverlayEntry[] = [];
 
@@ -27,11 +24,7 @@ export function getFloatOverlayStack(
 		const scene = scenes[index];
 		const options = scene?.descriptor?.options;
 
-		if (!transitionsAlwaysOn && !options?.enableTransitions) {
-			continue;
-		}
-
-		if (isOverlayVisible(options)) {
+		if (options?.overlay && options?.overlayShown !== false) {
 			candidates.push({ scene, overlayIndex: index });
 		}
 	}

package/src/components/overlay/helpers/retain-ready-overlay-resources.ts

@@ -1,47 +1,38 @@
-import type { ScreenAnimationContextValue } from "../../../providers/screen/animation/animation.provider";
-import type { ScreenSlotContextValue } from "../../../providers/screen/styles/slot.provider";
+import type { SharedValue } from "react-native-reanimated";
+import type { OrchestratorState } from "../../../providers/screen/orchestrator/orchestrator.provider";
 import type { FloatOverlayEntry } from "./get-active-overlay";
 
 export type ReadyOverlayResources = {
-	overlayAnimationStore: ScreenAnimationContextValue;
-	overlaySlots: ScreenSlotContextValue;
+	overlayAnimationStore: OrchestratorState;
 	driverScene: FloatOverlayEntry["scene"];
-	driverAnimationStore: ScreenAnimationContextValue;
-	driverSlots: ScreenSlotContextValue;
+	driverAnimationStore: OrchestratorState;
+	driverIsScreenReady: SharedValue<boolean>;
 };
 
 export function retainReadyOverlayResources(
 	previous: ReadyOverlayResources | null,
-	overlayAnimationStore: ScreenAnimationContextValue | null,
-	overlaySlots: ScreenSlotContextValue | null,
+	overlayAnimationStore: OrchestratorState | null,
 	driverScene: FloatOverlayEntry["scene"],
-	driverAnimationStore: ScreenAnimationContextValue | null,
-	driverSlots: ScreenSlotContextValue | null,
+	driverAnimationStore: OrchestratorState | null,
+	driverIsScreenReady: SharedValue<boolean> | null,
 ): ReadyOverlayResources | null {
-	if (
-		!overlayAnimationStore ||
-		!overlaySlots ||
-		!driverAnimationStore ||
-		!driverSlots
-	) {
+	if (!overlayAnimationStore || !driverAnimationStore || !driverIsScreenReady) {
 		return previous;
 	}
 
 	if (
 		previous?.overlayAnimationStore === overlayAnimationStore &&
-		previous.overlaySlots === overlaySlots &&
 		previous.driverScene === driverScene &&
 		previous.driverAnimationStore === driverAnimationStore &&
-		previous.driverSlots === driverSlots
+		previous.driverIsScreenReady === driverIsScreenReady
 	) {
 		return previous;
 	}
 
 	return {
 		overlayAnimationStore,
-		overlaySlots,
 		driverScene,
 		driverAnimationStore,
-		driverSlots,
+		driverIsScreenReady,
 	};
 }

package/src/components/overlay/helpers/run-overlay-slot-interpolator.ts

@@ -1,7 +1,7 @@
-import type { ScreenInterpolatorFrame } from "../../../providers/screen/animation/helpers/pipeline";
-import { createInterpolatorScope } from "../../../providers/screen/styles/helpers/create-interpolator-scope";
-import { normalizeSlots } from "../../../providers/screen/styles/helpers/normalize-slots";
-import { selectInterpolatorFrame } from "../../../providers/screen/styles/helpers/select-interpolator-frame";
+import type { ScreenInterpolatorFrame } from "../../../providers/screen/orchestrator/helpers/pipeline";
+import { createInterpolatorScope } from "../../../providers/screen/orchestrator/styles/helpers/create-interpolator-scope";
+import { normalizeSlots } from "../../../providers/screen/orchestrator/styles/helpers/normalize-slots";
+import { selectInterpolatorFrame } from "../../../providers/screen/orchestrator/styles/helpers/select-interpolator-frame";
 import type {
 	NormalizedTransitionSlotStyle,
 	ScreenStyleInterpolator,

package/src/components/overlay/hooks/use-overlay-slot.ts

@@ -6,7 +6,7 @@ import {
 	useDerivedValue,
 } from "react-native-reanimated";
 import { NO_PROPS, NO_STYLES } from "../../../constants";
-import type { ScreenAnimationContextValue } from "../../../providers/screen/animation/animation.provider";
+import type { OrchestratorState } from "../../../providers/screen/orchestrator/orchestrator.provider";
 import type {
 	NormalizedTransitionSlotStyle,
 	ScreenStyleInterpolator,
@@ -24,15 +24,17 @@ export const useOverlaySlot = ({
 	driverAnimationStore,
 	previousOverlayAnimationStore,
 	driverInterpolator,
-	interpolatorReady,
+	isScreenReady,
+	ancestorIsScreenReady,
 	isIncoming,
 }: {
-	overlayAnimationStore: ScreenAnimationContextValue;
+	overlayAnimationStore: OrchestratorState;
 	overlayInterpolator: ScreenStyleInterpolator | undefined;
-	driverAnimationStore: ScreenAnimationContextValue;
-	previousOverlayAnimationStore?: ScreenAnimationContextValue;
+	driverAnimationStore: OrchestratorState;
+	previousOverlayAnimationStore?: OrchestratorState;
 	driverInterpolator: ScreenStyleInterpolator | undefined;
-	interpolatorReady: SharedValue<number>;
+	isScreenReady: SharedValue<boolean>;
+	ancestorIsScreenReady: SharedValue<boolean> | null;
 	isIncoming: boolean;
 }) => {
 	const { height } = useWindowDimensions();
@@ -67,7 +69,11 @@ export const useOverlaySlot = ({
 			return NO_STYLES;
 		}
 
-		if (isIncoming && !interpolatorReady.get()) {
+		if (
+			isIncoming &&
+			!isScreenReady.get() &&
+			(ancestorIsScreenReady?.get() ?? true)
+		) {
 			return {
 				transform: [{ translateY: getVisibilityBlockOffset(height) }],
 			};

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

@@ -1,5 +1,4 @@
 import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
-import { useStackCoreStore } from "../../../providers/stack/core.provider";
 
 import {
 	getFloatOverlayStack,
@@ -13,11 +12,9 @@ import { OverlayHost } from "./overlay-host";
  */
 export function FloatOverlay() {
 	const scenes = useBlankStackStore((store) => store.scenes);
-	const transitionsAlwaysOn = useStackCoreStore(
-		(store) => store.flags.TRANSITIONS_ALWAYS_ON,
-	);
 
-	const overlayStack = getFloatOverlayStack(scenes, transitionsAlwaysOn);
+	const overlayStack = getFloatOverlayStack(scenes);
+
 	if (overlayStack.length === 0) {
 		return null;
 	}

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

@@ -1,17 +1,16 @@
 import { memo, useMemo, useRef } from "react";
 import { StyleSheet, View } from "react-native";
-import Animated, { useDerivedValue } from "react-native-reanimated";
+import Animated, {
+	type SharedValue,
+	useDerivedValue,
+} from "react-native-reanimated";
 import { snapDescriptorToIndex } from "../../../animation/snap-to";
-import { useOptionalScreenAnimationStore } from "../../../providers/screen/animation";
+import { useOptionalMotionStore } from "../../../providers/screen/motion";
+import { useOptionalOrchestratorStore } from "../../../providers/screen/orchestrator";
 import {
-	type ScreenAnimationContextValue,
-	ScreenAnimationStoreProvider,
-} from "../../../providers/screen/animation/animation.provider";
-import {
-	type ScreenSlotContextValue,
-	ScreenSlotStoreProvider,
-	useOptionalScreenSlotStore,
-} from "../../../providers/screen/styles/slot.provider";
+	OrchestratorProvider,
+	type OrchestratorState,
+} from "../../../providers/screen/orchestrator/orchestrator.provider";
 import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
 import type { OverlayProps } from "../../../types/overlay.types";
 import type { FloatOverlayEntry } from "../helpers/get-active-overlay";
@@ -34,27 +33,26 @@ export const OverlayHost = memo(function OverlayHost({
 	previousOverlayScene,
 	layerIndex,
 }: OverlayHostProps) {
-	const overlayAnimationStore = useOptionalScreenAnimationStore(
-		scene.route.key,
-	);
-	const driverAnimationStore = useOptionalScreenAnimationStore(
+	const overlayAnimationStore = useOptionalOrchestratorStore(scene.route.key);
+	const driverAnimationStore = useOptionalOrchestratorStore(
 		driverScene.route.key,
 	);
-	const previousOverlayAnimationStore = useOptionalScreenAnimationStore(
+	const previousOverlayAnimationStore = useOptionalOrchestratorStore(
 		previousOverlayScene?.route.key ?? scene.route.key,
 	);
-	const overlaySlots = useOptionalScreenSlotStore(scene.route.key);
-	const driverSlots = useOptionalScreenSlotStore(driverScene.route.key);
+	const driverIsScreenReady = useOptionalMotionStore(
+		driverScene.route.key,
+		(store) => store.isScreenReady,
+	);
 	const overlayComponentRef = useRef(scene.descriptor.options.overlay);
 	const OverlayComponent = overlayComponentRef.current;
 	const readyResourcesRef = useRef<ReadyOverlayResources | null>(null);
 	readyResourcesRef.current = retainReadyOverlayResources(
 		readyResourcesRef.current,
 		overlayAnimationStore,
-		overlaySlots,
 		driverScene,
 		driverAnimationStore,
-		driverSlots,
+		driverIsScreenReady,
 	);
 	const readyResources = readyResourcesRef.current;
 
@@ -68,23 +66,21 @@ export const OverlayHost = memo(function OverlayHost({
 			driverScene={readyResources.driverScene}
 			layerIndex={layerIndex}
 			overlayAnimationStore={readyResources.overlayAnimationStore}
-			overlaySlots={readyResources.overlaySlots}
 			driverAnimationStore={readyResources.driverAnimationStore}
 			previousOverlayAnimationStore={
 				previousOverlayScene ? previousOverlayAnimationStore : undefined
 			}
-			driverSlots={readyResources.driverSlots}
+			driverIsScreenReady={readyResources.driverIsScreenReady}
 			OverlayComponent={OverlayComponent}
 		/>
 	);
 });
 
 type ReadyOverlayHostProps = OverlayHostProps & {
-	overlayAnimationStore: ScreenAnimationContextValue;
-	overlaySlots: ScreenSlotContextValue;
-	driverAnimationStore: ScreenAnimationContextValue;
-	previousOverlayAnimationStore?: ScreenAnimationContextValue | null;
-	driverSlots: ScreenSlotContextValue;
+	overlayAnimationStore: OrchestratorState;
+	driverAnimationStore: OrchestratorState;
+	previousOverlayAnimationStore?: OrchestratorState | null;
+	driverIsScreenReady: SharedValue<boolean>;
 	OverlayComponent: NonNullable<
 		FloatOverlayEntry["scene"]["descriptor"]["options"]["overlay"]
 	>;
@@ -95,22 +91,25 @@ function ReadyOverlayHost({
 	driverScene,
 	layerIndex,
 	overlayAnimationStore,
-	overlaySlots,
 	driverAnimationStore,
 	previousOverlayAnimationStore,
-	driverSlots,
+	driverIsScreenReady,
 	OverlayComponent,
 }: ReadyOverlayHostProps) {
 	const { scenes, focusedIndex, routeKeys, routes } = useBlankStackStore();
 	const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
 	const focusedDescriptor = focusedScene?.descriptor;
+	const ancestorIsScreenReady = useOptionalMotionStore(
+		(store) => store?.isScreenReady ?? null,
+	);
 	const { animatedProps, animatedStyle } = useOverlaySlot({
 		overlayAnimationStore,
 		overlayInterpolator: scene.descriptor.options.screenStyleInterpolator,
 		driverAnimationStore,
 		previousOverlayAnimationStore: previousOverlayAnimationStore ?? undefined,
 		driverInterpolator: driverScene.descriptor.options.screenStyleInterpolator,
-		interpolatorReady: driverSlots.interpolatorReady,
+		isScreenReady: driverIsScreenReady,
+		ancestorIsScreenReady,
 		isIncoming: scene.route.key === driverScene.route.key,
 	});
 	const relativeProgress = useDerivedValue(() => {
@@ -155,19 +154,14 @@ function ReadyOverlayHost({
 				animatedStyle,
 			]}
 		>
-			<ScreenAnimationStoreProvider
-				registerGlobally={false}
-				value={overlayAnimationStore}
-			>
-				<ScreenSlotStoreProvider registerGlobally={false} value={overlaySlots}>
-					<View
-						pointerEvents="box-none"
-						style={[StyleSheet.absoluteFill, styles.overlay]}
-					>
-						<OverlayComponent {...overlayProps} />
-					</View>
-				</ScreenSlotStoreProvider>
-			</ScreenAnimationStoreProvider>
+			<OrchestratorProvider screenKey={scene.route.key}>
+				<View
+					pointerEvents="box-none"
+					style={[StyleSheet.absoluteFill, styles.overlay]}
+				>
+					<OverlayComponent {...overlayProps} />
+				</View>
+			</OrchestratorProvider>
 		</Animated.View>
 	);
 }

package/src/components/screen/container/helpers/find-collapse-target.ts

@@ -0,0 +1,62 @@
+import { EPSILON } from "../../../../constants";
+import { sanitizeSnapPoints } from "../../../../providers/screen/motion/gestures/shared/snap-points";
+
+interface FindCollapseTargetResult {
+	target: number;
+	shouldDismiss: boolean;
+}
+
+/**
+ * Finds the next lower snap point for backdrop collapse behavior.
+ *
+ * - If above min snap: returns next lower snap point
+ * - If at or below min snap: returns 0 (dismiss) if canDismiss, else stays at min
+ *
+ * @param currentProgress - Current animation progress
+ * @param snapPoints - Array of snap points
+ * @param canDismiss - Whether dismissing is allowed
+ */
+export function findCollapseTarget(
+	currentProgress: number,
+	snapPoints: number[],
+	canDismiss: boolean,
+): FindCollapseTargetResult {
+	"worklet";
+
+	const normalized = sanitizeSnapPoints(snapPoints, canDismiss);
+
+	if (normalized.length === 0) {
+		return canDismiss
+			? { target: 0, shouldDismiss: true }
+			: { target: currentProgress, shouldDismiss: false };
+	}
+
+	let minSnap = normalized[0];
+	let nextLowerSnap: number | null = null;
+
+	for (let i = 0; i < normalized.length; i++) {
+		const snap = normalized[i];
+		if (snap < minSnap) {
+			minSnap = snap;
+		}
+
+		if (
+			snap < currentProgress - EPSILON &&
+			(nextLowerSnap === null || snap > nextLowerSnap)
+		) {
+			nextLowerSnap = snap;
+		}
+	}
+
+	if (nextLowerSnap !== null) {
+		return { target: nextLowerSnap, shouldDismiss: false };
+	}
+
+	// At or below min snap → dismiss if allowed
+	if (canDismiss) {
+		return { target: 0, shouldDismiss: true };
+	}
+
+	// Can't dismiss, stay at min
+	return { target: minSnap, shouldDismiss: false };
+}

package/src/components/screen/container/helpers/layer-component.tsx

@@ -0,0 +1,38 @@
+import { type ComponentType, type ReactNode, useMemo } from "react";
+import type { ViewProps } from "react-native";
+import Animated from "react-native-reanimated";
+import type { ScreenLayerComponentProps } from "../../../../types";
+import { usesLayerRenderProps } from "./uses-layer-render-props";
+
+/** Adapts the two supported custom layer APIs without changing component identity. */
+export function LayerComponent({
+	component,
+	styles,
+	props,
+	pointerEvents,
+	children,
+	collapsable,
+}: ScreenLayerComponentProps & {
+	component?: ComponentType<any>;
+	children?: ReactNode;
+	collapsable?: ViewProps["collapsable"];
+}) {
+	const renderProps = component && usesLayerRenderProps(component);
+	const Component = useMemo<ComponentType<any>>(() => {
+		if (!component) return Animated.View;
+		return usesLayerRenderProps(component)
+			? component
+			: Animated.createAnimatedComponent(component);
+	}, [component]);
+	return (
+		<Component
+			{...(renderProps
+				? { styles, props }
+				: { style: styles, animatedProps: props })}
+			pointerEvents={pointerEvents}
+			collapsable={collapsable}
+		>
+			{children}
+		</Component>
+	);
+}

package/src/components/screen/container/hooks/use-backdrop-pointer-events.ts

@@ -0,0 +1,51 @@
+import { useState } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import { useMotionStore } from "../../../../providers/screen/motion";
+import type { BackdropBehavior } from "../../../../types/screen.types";
+
+interface BackdropPointerEventsResult {
+	pointerEvents: "box-none" | undefined;
+	backdropBehavior: BackdropBehavior;
+	isBackdropActive: boolean;
+}
+
+/**
+ * Returns pointer events and backdrop behavior based on screen options.
+ *
+ * - Runtime interpolator `backdropBehavior` takes precedence
+ * - Explicit descriptor `backdropBehavior` option is next
+ * - Otherwise defaults to 'block' (undefined = normal touch handling)
+ */
+export function useBackdropPointerEvents(): BackdropPointerEventsResult {
+	const screenOptions = useMotionStore((store) => store.options);
+	const descriptorBackdropBehavior = useBuilderStore(
+		(store) => store.options.backdropBehavior,
+	);
+	const [runtimeBackdropBehavior, setRuntimeBackdropBehavior] = useState<
+		BackdropBehavior | undefined
+	>(undefined);
+
+	useAnimatedReaction(
+		() => screenOptions.get().backdropBehavior,
+		(next, previous) => {
+			"worklet";
+			if (next !== previous) {
+				scheduleOnRN(setRuntimeBackdropBehavior, next);
+			}
+		},
+		[screenOptions],
+	);
+
+	const backdropBehavior: BackdropBehavior =
+		runtimeBackdropBehavior ?? descriptorBackdropBehavior ?? "block";
+
+	const pointerEvents =
+		backdropBehavior === "passthrough" ? "box-none" : undefined;
+
+	const isBackdropActive =
+		backdropBehavior === "dismiss" || backdropBehavior === "collapse";
+
+	return { pointerEvents, backdropBehavior, isBackdropActive };
+}