react-native-screen-transitions 3.4.0-alpha.2 → 3.4.0-alpha.4

package/src/shared/providers/stack/helpers/use-processed-routes.ts

@@ -49,7 +49,7 @@ export function useProcessedRoutes<
 			scenes[i] = { route, descriptor };
 			routeKeys[i] = route.key;
 			backdropBehaviors[i] = options?.backdropBehavior ?? "block";
-			animationMaps[i] = AnimationStore.getRouteAnimations(route.key);
+			animationMaps[i] = AnimationStore.getBag(route.key);
 
 			if (!shouldShowFloatOverlay) {
 				shouldShowFloatOverlay = isOverlayVisible(options);

package/src/shared/stores/animation.store.ts

@@ -3,85 +3,35 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import type { Layout, ScreenKey } from "../types/screen.types";
+import { createStore } from "../utils/create-store";
 
 export type AnimationStoreMap = {
 	progress: SharedValue<number>;
 	animating: SharedValue<number>;
 	closing: SharedValue<number>;
 	entering: SharedValue<number>;
-	targetProgress: SharedValue<number>;
-	/** Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured. */
-	autoSnapPoint: SharedValue<number>;
-	/** Intrinsic content layout measured from the screen container wrapper. */
-	contentLayout: SharedValue<Layout | null>;
 };
 
-const store: Record<ScreenKey, AnimationStoreMap> = {};
-
 function createAnimationBag(): AnimationStoreMap {
 	return {
 		progress: makeMutable(0),
 		closing: makeMutable(0),
 		animating: makeMutable(0),
 		entering: makeMutable(0),
-		targetProgress: makeMutable(1),
-		autoSnapPoint: makeMutable(-1),
-		contentLayout: makeMutable<Layout | null>(null),
 	};
 }
 
-function ensure(routeKey: ScreenKey): AnimationStoreMap {
-	let bag = store[routeKey];
-	if (!bag) {
-		bag = createAnimationBag();
-		store[routeKey] = bag;
-	}
-	return bag;
-}
-
-function peekRouteAnimations(
-	routeKey: ScreenKey,
-): AnimationStoreMap | undefined {
-	return store[routeKey];
-}
-
-function getRouteAnimation<K extends keyof AnimationStoreMap>(
-	routeKey: ScreenKey,
-	type: K,
-): AnimationStoreMap[K] {
-	return ensure(routeKey)[type];
-}
-
-function getAnimation<K extends keyof AnimationStoreMap>(
-	routeKey: ScreenKey,
-	type: K,
-): AnimationStoreMap[K] {
-	return getRouteAnimation(routeKey, type);
-}
-
-function getRouteAnimations(routeKey: ScreenKey): AnimationStoreMap {
-	return ensure(routeKey);
-}
-
-function clear(routeKey: ScreenKey) {
-	const bag = store[routeKey];
-	if (bag) {
+/**
+ * Route-keyed screen transition state for the public animation lifecycle. These
+ * shared values track the current progress and whether a screen is entering,
+ * closing, or actively animating.
+ */
+export const AnimationStore = createStore<AnimationStoreMap>({
+	createBag: createAnimationBag,
+	disposeBag: (bag) => {
 		cancelAnimation(bag.progress);
 		cancelAnimation(bag.animating);
 		cancelAnimation(bag.closing);
 		cancelAnimation(bag.entering);
-		cancelAnimation(bag.targetProgress);
-		cancelAnimation(bag.autoSnapPoint);
-		cancelAnimation(bag.contentLayout);
-	}
-	delete store[routeKey];
-}
-
-export const AnimationStore = {
-	getAnimation,
-	peekRouteAnimations,
-	getRouteAnimation,
-	getRouteAnimations,
-	clear,
-};
+	},
+});

package/src/shared/stores/gesture.store.ts

@@ -4,7 +4,7 @@ import {
 	type SharedValue,
 } from "react-native-reanimated";
 import type { GestureDirection } from "../types/gesture.types";
-import type { ScreenKey } from "../types/screen.types";
+import { createStore } from "../utils/create-store";
 
 export type GestureStoreMap = {
 	x: SharedValue<number>;
@@ -15,19 +15,24 @@ export type GestureStoreMap = {
 	dragging: SharedValue<number>;
 	direction: SharedValue<Omit<GestureDirection, "bidirectional"> | null>;
 
-	/** @deprecated Use `normX` instead. */
+	/**
+	 * @deprecated Use `normX` instead.
+	 */
 	normalizedX: SharedValue<number>;
-	/** @deprecated Use `normY` instead. */
+	/**
+	 * @deprecated Use `normY` instead.
+	 */
 	normalizedY: SharedValue<number>;
-	/** @deprecated Use `dismissing` instead. */
+	/**
+	 * @deprecated Use `dismissing` instead.
+	 */
 	isDismissing: SharedValue<number>;
-	/** @deprecated Use `dragging` instead. */
+	/**
+	 * @deprecated Use `dragging` instead.
+	 */
 	isDragging: SharedValue<number>;
 };
 
-const store: Record<ScreenKey, GestureStoreMap> = {};
-let neutralGestures: GestureStoreMap | undefined;
-
 function createGestureBag(): GestureStoreMap {
 	const normX = makeMutable(0);
 	const normY = makeMutable(0);
@@ -53,33 +58,16 @@ function createGestureBag(): GestureStoreMap {
 	};
 }
 
-function ensure(routeKey: ScreenKey): GestureStoreMap {
-	let bag = store[routeKey];
-	if (!bag) {
-		bag = createGestureBag();
-		store[routeKey] = bag;
-	}
-	return bag;
-}
-
-function peekRouteGestures(routeKey: ScreenKey): GestureStoreMap | undefined {
-	return store[routeKey];
-}
-
-function getRouteGestures(routeKey: ScreenKey) {
-	return ensure(routeKey);
-}
-
-function getNeutralGestures(): GestureStoreMap {
-	if (!neutralGestures) {
-		neutralGestures = createGestureBag();
-	}
-	return neutralGestures;
-}
-
-function clear(routeKey: ScreenKey) {
-	const bag = store[routeKey];
-	if (bag) {
+/**
+ * Route-keyed gesture state used by the transition system while a screen is
+ * being dragged or dismissed. It stores raw and normalized gesture values,
+ * dismissal flags, and the active gesture direction. `getCachedBag()` provides
+ * a stable neutral fallback bag for cases where a route should not own live
+ * gesture state.
+ */
+export const GestureStore = createStore<GestureStoreMap>({
+	createBag: createGestureBag,
+	disposeBag: (bag) => {
 		cancelAnimation(bag.x);
 		cancelAnimation(bag.y);
 		cancelAnimation(bag.normX);
@@ -87,13 +75,5 @@ function clear(routeKey: ScreenKey) {
 		cancelAnimation(bag.dismissing);
 		cancelAnimation(bag.dragging);
 		cancelAnimation(bag.direction);
-	}
-	delete store[routeKey];
-}
-
-export const GestureStore = {
-	peekRouteGestures,
-	getRouteGestures,
-	getNeutralGestures,
-	clear,
-};
+	},
+});

package/src/shared/stores/system.store.ts

@@ -0,0 +1,44 @@
+import {
+	cancelAnimation,
+	makeMutable,
+	type SharedValue,
+} from "react-native-reanimated";
+import type { Layout } from "../types/screen.types";
+import { createStore } from "../utils/create-store";
+
+export type SystemStoreMap = {
+	targetProgress: SharedValue<number>;
+
+	/**
+	 * Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured.
+	 */
+	resolvedAutoSnapPoint: SharedValue<number>;
+
+	/**
+	 * Intrinsic measured content layout from the screen container wrapper.
+	 */
+	measuredContentLayout: SharedValue<Layout | null>;
+};
+
+function createSystemBag(): SystemStoreMap {
+	return {
+		targetProgress: makeMutable(1),
+		resolvedAutoSnapPoint: makeMutable(-1),
+		measuredContentLayout: makeMutable<Layout | null>(null),
+	};
+}
+
+/**
+ * Route-keyed internal engine state that should not be treated as public screen
+ * animation data. These values support runtime measurement and orchestration,
+ * such as resolved auto snap points, measured content layout, and the current
+ * animation target progress. This could possibly grow in the future.
+ */
+export const SystemStore = createStore<SystemStoreMap>({
+	createBag: createSystemBag,
+	disposeBag: (bag) => {
+		cancelAnimation(bag.targetProgress);
+		cancelAnimation(bag.resolvedAutoSnapPoint);
+		cancelAnimation(bag.measuredContentLayout);
+	},
+});

package/src/shared/types/animation.types.ts

@@ -77,6 +77,33 @@ export type ScreenTransitionState = {
 	 * The route object for this screen.
 	 */
 	route: BaseStackRoute;
+
+	/**
+	 * Layout measurements for this specific screen.
+	 */
+	layouts: {
+		/**
+		 * The `width` and `height` of the screen container.
+		 */
+		screen: Layout;
+		/**
+		 * The intrinsic measured content wrapper layout when available.
+		 *
+		 * This is currently populated for the measured screen-container path used by
+		 * auto snap-point sizing. It is undefined until a real measurement exists.
+		 */
+		content?: Layout;
+	};
+
+	/**
+	 * Animated index of this screen's current snap point.
+	 * Interpolates between indices during gestures/animations.
+	 * - Returns -1 if no snap points are defined
+	 * - Returns 0 when at or below first snap point
+	 * - Returns fractional values between snap points (e.g., 1.5 = halfway between snap 1 and 2)
+	 * - Returns length-1 when at or above last snap point
+	 */
+	snapIndex: number;
 };
 
 export interface ScreenInterpolationProps {
@@ -97,6 +124,8 @@ export interface ScreenInterpolationProps {
 
 	/**
 	 * Layout measurements for the screen.
+	 *
+	 * @deprecated Use `current.layouts` instead.
 	 */
 	layouts: {
 		/**
@@ -142,11 +171,8 @@ export interface ScreenInterpolationProps {
 
 	/**
 	 * Animated index of the current snap point.
-	 * Interpolates between indices during gestures/animations.
-	 * - Returns -1 if no snap points are defined
-	 * - Returns 0 when at or below first snap point
-	 * - Returns fractional values between snap points (e.g., 1.5 = halfway between snap 1 and 2)
-	 * - Returns length-1 when at or above last snap point
+	 *
+	 * @deprecated Use `current.snapIndex` instead.
 	 */
 	snapIndex: number;
 
@@ -167,9 +193,20 @@ export interface ScreenInterpolationProps {
 	inactive: ScreenTransitionState | undefined;
 }
 
+/**
+ * Explicit signal for hiding a screen's visual subtree until the interpolator
+ * becomes ready for the current transition frame.
+ */
+export type DeferredScreenStyleSignal = "defer";
+
+/**
+ * Returning `'defer'` explicitly hides the screen's visual subtree until the
+ * transition is ready. Returning `null`, `undefined`, or `{}` applies no
+ * transition styles for the current frame.
+ */
 export type ScreenStyleInterpolator = (
 	props: ScreenInterpolationProps,
-) => TransitionInterpolatedStyle;
+) => TransitionInterpolatedStyle | DeferredScreenStyleSignal | null | undefined;
 
 /**
  * Animated style properties with full autocomplete.

package/src/shared/types/bounds.types.ts

@@ -1,13 +1,19 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
+import {
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_ELEMENT_STYLE_ID,
+} from "../constants";
 import type { Snapshot } from "../stores/bounds";
 import type {
 	BoundId,
-	BoundsAnchor,
 	BoundsOptions,
 	BoundsOptionsResult,
-	BoundsScaleMode,
 } from "../utils/bounds/types/options";
-import type { TransitionInterpolatedStyle } from "./animation.types";
+import type {
+	ScreenInterpolationProps,
+	TransitionInterpolatedStyle,
+	TransitionSlotStyle,
+} from "./animation.types";
 
 /**
  * Target style computation.
@@ -29,32 +35,19 @@ export type BoundsLink = {
 };
 
 export type BoundsNavigationZoomOptions = {
-	anchor?: BoundsAnchor;
-	scaleMode?: BoundsScaleMode;
 	target?: "bound" | "fullscreen" | MeasuredDimensions;
-	mask?: {
-		borderRadius?: number | "auto" | { from?: number; to?: number };
-		borderTopLeftRadius?: number | "auto" | { from?: number; to?: number };
-		borderTopRightRadius?: number | "auto" | { from?: number; to?: number };
-		borderBottomLeftRadius?: number | "auto" | { from?: number; to?: number };
-		borderBottomRightRadius?: number | "auto" | { from?: number; to?: number };
-		borderCurve?: "circular" | "continuous";
-		outset?:
-			| number
-			| { top?: number; right?: number; bottom?: number; left?: number };
-	};
-	motion?: {
-		dragResistance?: number;
-		dragDirectionalScaleMin?: number;
-	};
-	/**
-	 * @deprecated Use `mask.borderRadius` instead.
-	 */
-	maskBorderRadius?: number;
+	DEBUG?: boolean;
+	borderRadius?: number;
+};
+
+export type BoundsNavigationZoomStyle = TransitionInterpolatedStyle & {
+	content?: TransitionSlotStyle;
+	[NAVIGATION_MASK_CONTAINER_STYLE_ID]?: TransitionSlotStyle;
+	[NAVIGATION_MASK_ELEMENT_STYLE_ID]?: TransitionSlotStyle;
 };
 
 export type BoundsNavigationAccessor = {
-	zoom: (options?: BoundsNavigationZoomOptions) => TransitionInterpolatedStyle;
+	zoom: (options?: BoundsNavigationZoomOptions) => BoundsNavigationZoomStyle;
 };
 
 type BoundsBoundNavigationAccessor = {
@@ -80,3 +73,10 @@ export type BoundsAccessor = {
 		fallback?: number,
 	) => number;
 };
+
+export type BoundsInterpolationProps = Omit<
+	ScreenInterpolationProps,
+	"bounds"
+> & {
+	navigationMaskEnabled?: boolean;
+};

package/src/shared/types/index.ts

@@ -2,6 +2,7 @@ export { FALSE, TRUE } from "../constants";
 export type {
 	AnimatedViewStyle,
 	AnimationConfig,
+	DeferredScreenStyleSignal,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
 	ScreenTransitionState,
@@ -14,6 +15,7 @@ export type {
 	BoundsMethod,
 	BoundsNavigationAccessor,
 	BoundsNavigationZoomOptions,
+	BoundsNavigationZoomStyle,
 } from "./bounds.types";
 export type {
 	ActivationArea,

package/src/shared/types/screen.types.ts

@@ -80,6 +80,11 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 export type ScreenTransitionConfig = {
 	/**
 	 * The user-provided function to calculate styles based on animation progress.
+	 *
+	 * Return `null` to explicitly defer rendering of the screen's visual subtree
+	 * until a later frame. This is useful for transitions such as
+	 * `bounds().navigation.zoom()` where the screen should stay hidden until the
+	 * interpolator has enough state to produce a safe first frame.
 	 */
 	screenStyleInterpolator?: ScreenStyleInterpolator;
 
@@ -197,6 +202,18 @@ export type ScreenTransitionConfig = {
 	 */
 	experimental_enableHighRefreshRate?: boolean;
 
+	/**
+	 * Animates the first screen in a navigator from its closed state on initial mount
+	 * instead of snapping directly to its settled progress.
+	 *
+	 * Useful for launch/onboarding flows where the initial screen should participate
+	 * in the same transition system as pushed screens.
+	 *
+	 * @experimental This API may change in future versions.
+	 * @default false
+	 */
+	experimental_animateOnInitialMount?: boolean;
+
 	/**
 	 * Describes heights where a screen can rest, as fractions of screen height,
 	 * or `'auto'` to snap to the intrinsic height of the screen content.

package/src/shared/utils/animation/animate-to-progress.ts

@@ -1,4 +1,4 @@
-import { runOnJS } from "react-native-reanimated";
+import { runOnJS, type SharedValue } from "react-native-reanimated";
 import { FALSE, TRUE } from "../../constants";
 import type { AnimationStoreMap } from "../../stores/animation.store";
 import type { TransitionSpec } from "../../types/animation.types";
@@ -15,6 +15,7 @@ interface AnimateToProgressProps {
 	spec?: TransitionSpec;
 	onAnimationFinish?: (finished: boolean) => void;
 	animations: AnimationStoreMap;
+	targetProgress: SharedValue<number>;
 	/** Optional initial velocity for spring-based progress (units: progress/sec). */
 	initialVelocity?: number;
 }
@@ -24,6 +25,7 @@ export const animateToProgress = ({
 	spec,
 	onAnimationFinish,
 	animations,
+	targetProgress,
 	initialVelocity,
 }: AnimateToProgressProps) => {
 	"worklet";
@@ -44,7 +46,7 @@ export const animateToProgress = ({
 			? { ...config, velocity: initialVelocity }
 			: config;
 
-	const { progress, animating, closing, entering, targetProgress } = animations;
+	const { progress, animating, closing, entering } = animations;
 
 	targetProgress.set(value);
 

package/src/shared/utils/bounds/helpers/compute-bounds-styles.ts

@@ -1,10 +1,10 @@
 import type { MeasuredDimensions } from "react-native-reanimated";
 import {
-	EMPTY_BOUND_HELPER_RESULT,
 	EMPTY_BOUND_HELPER_RESULT_RAW,
 	ENTER_RANGE,
 	EXIT_RANGE,
 	FULLSCREEN_DIMENSIONS,
+	HIDDEN_STYLE,
 } from "../../../constants";
 import {
 	BoundStore,
@@ -127,7 +127,7 @@ export const computeBoundStyles = (
 		if (computeOptions.raw) {
 			return EMPTY_BOUND_HELPER_RESULT_RAW;
 		}
-		return EMPTY_BOUND_HELPER_RESULT;
+		return HIDDEN_STYLE;
 	}
 
 	const {
@@ -153,7 +153,7 @@ export const computeBoundStyles = (
 		if (computeOptions.raw) {
 			return EMPTY_BOUND_HELPER_RESULT_RAW;
 		}
-		return EMPTY_BOUND_HELPER_RESULT;
+		return HIDDEN_STYLE;
 	}
 
 	const ranges: readonly [number, number] = entering ? ENTER_RANGE : EXIT_RANGE;

package/src/shared/utils/bounds/index.ts

@@ -1,14 +1,17 @@
 import { BoundStore, type ResolvedTransitionPair } from "../../stores/bounds";
 import type { ScreenInterpolationProps } from "../../types/animation.types";
-import type { BoundsAccessor } from "../../types/bounds.types";
+import type {
+	BoundsAccessor,
+	BoundsInterpolationProps,
+	BoundsNavigationZoomOptions,
+} from "../../types/bounds.types";
 import { buildBoundsOptions } from "./helpers/build-bounds-options";
 import { computeBoundStyles } from "./helpers/compute-bounds-styles";
 import { createInterpolators } from "./helpers/interpolators";
 import { createLinkAccessor } from "./helpers/link-accessor";
 import { resolveBoundTag } from "./helpers/resolve-bound-tag";
-import type { BoundsFrameProps } from "./types/frame-props";
 import type { BoundsOptions } from "./types/options";
-import { createZoomAccessor } from "./zoom";
+import { buildZoomStyles } from "./zoom/build";
 
 const syncGroupActiveMember = (group?: string, id?: string | number) => {
 	"worklet";
@@ -22,7 +25,7 @@ const syncGroupActiveMember = (group?: string, id?: string | number) => {
 };
 
 export const createBoundsAccessor = (
-	getProps: () => BoundsFrameProps,
+	getProps: () => BoundsInterpolationProps,
 ): BoundsAccessor => {
 	"worklet";
 
@@ -49,90 +52,38 @@ export const createBoundsAccessor = (
 	const computeElementBoundsStyles = (params?: BoundsOptions) => {
 		"worklet";
 		const props = getProps();
-		syncGroupActiveMember(params?.group, params?.id);
+		const id = params?.id;
+		const group = params?.group;
+		syncGroupActiveMember(group, id);
 
 		const resolved = buildBoundsOptions({
 			props,
-			id: params?.id,
-			group: params?.group,
+			id,
+			group,
 			overrides: params,
 			mode: "style",
 			resolveBoundTag,
 		});
 
 		const computed = computeForResolvedOptions(resolved, props);
-
-		const zoomBaseOptions = {
-			anchor: params?.anchor,
-			scaleMode: params?.scaleMode,
-			target: params?.target,
-		};
-		let cachedNavigationPairProps: BoundsFrameProps | undefined;
-		let cachedNavigationPairTag = "";
-		let cachedNavigationPair: ResolvedTransitionPair | undefined;
-
-		const resolveNavigationPair = (
-			tag: string,
-			frameProps: BoundsFrameProps,
-		): ResolvedTransitionPair | undefined => {
-			"worklet";
-			if (!tag) return undefined;
-
-			if (
-				cachedNavigationPairProps === frameProps &&
-				cachedNavigationPairTag === tag
-			) {
-				return cachedNavigationPair;
-			}
-
-			const nextPair = BoundStore.resolveTransitionPair(tag, {
-				currentScreenKey: frameProps.current?.route.key,
-				previousScreenKey: frameProps.previous?.route.key,
-				nextScreenKey: frameProps.next?.route.key,
-				entering: !frameProps.next,
-			});
-
-			cachedNavigationPairProps = frameProps;
-			cachedNavigationPairTag = tag;
-			cachedNavigationPair = nextPair;
-
-			return nextPair;
-		};
-
-		const navigation = createZoomAccessor({
-			id: params?.id,
-			group: params?.group,
-			getProps,
-			resolveBoundTag,
-			zoomBaseOptions,
-			computeRaw: (overrides, frameProps) =>
-				(() => {
-					const currentProps = frameProps ?? getProps();
-					const resolvedNavigationOptions = buildBoundsOptions({
-						props: currentProps,
-						id: params?.id,
-						group: params?.group,
-						overrides,
-						mode: "navigation",
-						resolveBoundTag,
-					});
-					const resolvedPair = resolveNavigationPair(
-						String(resolvedNavigationOptions.id),
-						currentProps,
-					);
-
-					return computeForResolvedOptions(
-						resolvedNavigationOptions,
-						currentProps,
-						resolvedPair,
-					) as Record<string, unknown>;
-				})(),
-		});
+		// Navigation helpers are intentionally opinionated. Only the resolved
+		// tag from `id`/`group` is allowed to flow into `navigation.zoom()`;
+		// base bounds overrides like `target`, `anchor`, or `scaleMode` must not.
+		const navigationTag = resolveBoundTag({ id, group });
 
 		const target = Object.isExtensible(computed) ? computed : { ...computed };
 
 		Object.defineProperty(target, "navigation", {
-			value: navigation,
+			value: {
+				zoom: (options?: BoundsNavigationZoomOptions) => {
+					"worklet";
+					return buildZoomStyles({
+						props: getProps(),
+						resolvedTag: navigationTag,
+						zoomOptions: options,
+					});
+				},
+			},
 			enumerable: false,
 			configurable: true,
 		});