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

package/src/shared/types/overlay.types.ts

@@ -1,18 +1,7 @@
 import type { Route } from "@react-navigation/native";
 import type { DerivedValue } from "react-native-reanimated";
-import type {
-	OverlayInterpolationProps,
-	ScreenInterpolationProps,
-} from "./animation.types";
 import type { ScreenTransitionConfig } from "./screen.types";
 
-/**
- * @deprecated Overlay mode is no longer needed. Overlays now always render as "float" mode.
- * For per-screen overlays, render an absolute-positioned view directly in your screen component
- * and use `useScreenAnimation()` to access animation values.
- */
-export type OverlayMode = "float" | "screen";
-
 /**
  * Props passed to overlay components.
  * Generic over the navigation type since different stacks have different navigation props.
@@ -23,7 +12,7 @@ export type OverlayMode = "float" | "screen";
  */
 export type OverlayScreenState<TNavigation = unknown> = Omit<
 	OverlayProps<TNavigation>,
-	"progress" | "overlayAnimation" | "screenAnimation"
+	"progress"
 > & {
 	index: number;
 	snapTo: (index: number) => void;
@@ -65,20 +54,4 @@ export type OverlayProps<TNavigation = unknown> = {
 	 * This is equivalent to `useScreenAnimation().stackProgress`.
 	 */
 	progress: DerivedValue<number>;
-
-	/**
-	 * Animation values for the overlay.
-	 *
-	 * @deprecated Use `progress` prop or `useScreenAnimation()` instead.
-	 * This prop will be removed in a future version.
-	 */
-	overlayAnimation: DerivedValue<OverlayInterpolationProps>;
-
-	/**
-	 * Animation values for the screen.
-	 *
-	 * @deprecated Use `useScreenAnimation()` hook directly instead.
-	 * This prop will be removed in a future version.
-	 */
-	screenAnimation: DerivedValue<ScreenInterpolationProps>;
 };

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

@@ -4,7 +4,7 @@ import type {
 	TransitionSpec,
 } from "./animation.types";
 import type { GestureActivationArea, GestureDirection } from "./gesture.types";
-import type { OverlayMode, OverlayProps } from "./overlay.types";
+import type { OverlayProps } from "./overlay.types";
 
 export type Layout = {
 	width: number;
@@ -12,6 +12,15 @@ export type Layout = {
 };
 
 export type ScreenKey = string;
+export type SheetScrollGestureBehavior =
+	| "expand-and-collapse"
+	| "collapse-only";
+
+/**
+ * A single snap point value. Either a fraction of screen height (0–1) or
+ * `'auto'` to snap to the intrinsic height of the screen content.
+ */
+export type SnapPoint = number | "auto";
 
 export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	/**
@@ -27,10 +36,13 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * </Transition.View>
 	 *
 	 * // In your screenStyleInterpolator:
-	 * return {
-	 *   'hero-image': {
-	 *     opacity: interpolate(progress, [0, 1], [0, 1]),
-	 *     transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }]
+	 * screenStyleInterpolator: ({ progress }) => {
+	 *   "worklet";
+	 *   return {
+	 *     'hero-image': {
+	 *       opacity: interpolate(progress, [0, 1], [0, 1]),
+	 *       transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }]
+	 *     }
 	 *   }
 	 * }
 	 */
@@ -81,6 +93,13 @@ export type ScreenTransitionConfig = {
 	 * (e.g. `bounds().navigation.zoom()`) is ready from the first frame.
 	 *
 	 * Requires `@react-native-masked-view/masked-view` to be installed.
+	 *
+	 * @default false
+	 */
+	navigationMaskEnabled?: boolean;
+
+	/**
+	 * @deprecated Use `navigationMaskEnabled` instead.
 	 */
 	maskEnabled?: boolean;
 
@@ -157,20 +176,9 @@ export type ScreenTransitionConfig = {
 
 	/**
 	 * Function that returns a React Element to display as an overlay.
-	 * For container overlays (overlayMode: 'container'), use ContainerOverlayProps which includes children.
 	 */
 	overlay?: (props: OverlayProps) => React.ReactNode;
 
-	/**
-	 * How the overlay is positioned relative to screens.
-	 *
-	 * @deprecated This option is no longer needed. Overlays now always render as "float" mode
-	 * (single persistent overlay above all screens). For per-screen overlays, render an
-	 * absolute-positioned view directly in your screen component and use `useScreenAnimation()`
-	 * to access animation values.
-	 */
-	overlayMode?: OverlayMode;
-
 	/**
 	 * Whether to show the overlay. The overlay is shown by default when `overlay` is provided.
 	 * Setting this to `false` hides the overlay.
@@ -190,15 +198,21 @@ export type ScreenTransitionConfig = {
 	experimental_enableHighRefreshRate?: boolean;
 
 	/**
-	 * Describes heights where a screen can rest, as fractions of screen height.
-	 * Pass an array of ascending values from 0 to 1.
+	 * Describes heights where a screen can rest, as fractions of screen height,
+	 * or `'auto'` to snap to the intrinsic height of the screen content.
+	 *
+	 * Pass an array of ascending values from 0 to 1, or `'auto'`.
+	 * The `'auto'` value measures the content's natural height after layout and
+	 * converts it to the equivalent fraction of the screen height.
 	 *
 	 * @example
-	 * snapPoints={[0.5, 1.0]} // 50% and 100% of screen height
+	 * snapPoints={[0.5, 1.0]}     // 50% and 100% of screen height
+	 * snapPoints={['auto']}       // snap to content height
+	 * snapPoints={['auto', 1.0]}  // content height or full screen
 	 *
 	 * @default [1.0]
 	 */
-	snapPoints?: number[];
+	snapPoints?: SnapPoint[];
 
 	/**
 	 * The initial snap point index when the screen opens.
@@ -208,16 +222,25 @@ export type ScreenTransitionConfig = {
 	initialSnapIndex?: number;
 
 	/**
-	 * Controls whether swiping to expand the sheet works from within a ScrollView.
-	 *
-	 * - `true` (Apple Maps style): Swiping up at scroll top expands the sheet
-	 * - `false` (Instagram style): Expand only works via deadspace (non-scrollable areas)
+	 * Controls how nested scroll content hands gestures off to a snap sheet.
 	 *
-	 * Collapse (swipe down at scroll top) always works regardless of this setting.
+	 * - `"expand-and-collapse"` (Apple Maps style): Swiping up at scroll boundary expands the sheet,
+	 *   and swiping down at scroll boundary collapses or dismisses it
+	 * - `"collapse-only"` (Instagram style): Expand only works via deadspace; collapse/dismiss via
+	 *   nested scroll content still works at boundary
 	 *
 	 * Only applies to screens with `snapPoints` configured.
 	 *
-	 * @default true
+	 * @default "expand-and-collapse"
+	 */
+	sheetScrollGestureBehavior?: SheetScrollGestureBehavior;
+
+	/**
+	 * @deprecated Use `sheetScrollGestureBehavior` instead.
+	 *
+	 * Mapping:
+	 * - `true` -> `"expand-and-collapse"`
+	 * - `false` -> `"collapse-only"`
 	 */
 	expandViaScrollView?: boolean;
 
@@ -254,12 +277,15 @@ export type ScreenTransitionConfig = {
 	 *
 	 * @example
 	 * backdropComponent: BlurView,
-	 * screenStyleInterpolator: ({ progress }) => ({
-	 *   backdrop: {
-	 *     style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
-	 *     props: { intensity: interpolate(progress, [0, 1], [0, 80]) },
-	 *   },
-	 * })
+	 * screenStyleInterpolator: ({ progress }) => {
+	 *   "worklet";
+	 *   return {
+	 *     backdrop: {
+	 *       style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
+	 *       props: { intensity: interpolate(progress, [0, 1], [0, 80]) },
+	 *     },
+	 *   };
+	 * }
 	 *
 	 * @default undefined
 	 */
@@ -276,12 +302,15 @@ export type ScreenTransitionConfig = {
 	 *
 	 * @example
 	 * surfaceComponent: SquircleView,
-	 * screenStyleInterpolator: ({ progress }) => ({
-	 *   surface: {
-	 *     style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
-	 *     props: { cornerRadius: 24, cornerSmoothing: 0.7 },
-	 *   },
-	 * })
+	 * screenStyleInterpolator: ({ progress }) => {
+	 *   "worklet";
+	 *   return {
+	 *     surface: {
+	 *       style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
+	 *       props: { cornerRadius: 24, cornerSmoothing: 0.7 },
+	 *     },
+	 *   };
+	 * }
 	 *
 	 * @default undefined
 	 */

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

@@ -58,6 +58,9 @@ export const animateToProgress = ({
 	if (!config) {
 		animating.set(FALSE);
 		progress.set(value);
+		if (!isClosing) {
+			entering.set(FALSE);
+		}
 
 		if (onAnimationFinish) {
 			runOnJS(onAnimationFinish)(true);
@@ -71,6 +74,10 @@ export const animateToProgress = ({
 			"worklet";
 			if (!finished) return;
 
+			if (!isClosing) {
+				entering.set(FALSE);
+			}
+
 			if (onAnimationFinish) {
 				runOnJS(onAnimationFinish)(finished);
 			}

package/src/shared/utils/bounds/helpers/build-bounds-options.ts

@@ -1,12 +1,12 @@
 import { BoundStore } from "../../../stores/bounds";
 import type { ScreenInterpolationProps } from "../../../types/animation.types";
-import type { BoundsOptions } from "../types/options";
+import type { BoundId, BoundsOptions } from "../types/options";
 import { DEFAULT_BOUNDS_OPTIONS } from "./constants";
 import type { ResolveBoundTagParams } from "./resolve-bound-tag";
 
 type BuildBoundsOptionsParams = {
 	props: Omit<ScreenInterpolationProps, "bounds">;
-	id?: string;
+	id?: BoundId;
 	group?: string;
 	overrides?: Partial<BoundsOptions>;
 	mode?: "style" | "navigation";

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

@@ -12,7 +12,11 @@ import {
 } from "../../../stores/bounds";
 import type { ScreenTransitionState } from "../../../types/animation.types";
 import type { Layout } from "../../../types/screen.types";
-import type { BoundsComputeParams, BoundsOptions } from "../types/options";
+import type {
+	BoundId,
+	BoundsComputeParams,
+	BoundsOptions,
+} from "../types/options";
 import {
 	computeContentTransformGeometry,
 	computeRelativeGeometry,
@@ -27,7 +31,7 @@ import {
 } from "./style-composers";
 
 const resolveBounds = (params: {
-	id: string;
+	id: BoundId;
 	previous?: ScreenTransitionState;
 	current?: ScreenTransitionState;
 	next?: ScreenTransitionState;
@@ -51,7 +55,7 @@ const resolveBounds = (params: {
 
 	const resolvedPair =
 		params.resolvedPair ??
-		BoundStore.resolveTransitionPair(params.id, {
+		BoundStore.resolveTransitionPair(String(params.id), {
 			currentScreenKey,
 			previousScreenKey,
 			nextScreenKey,
@@ -66,6 +70,11 @@ const resolveBounds = (params: {
 			start: null,
 			end: null,
 			entering,
+			currentScreenKey,
+			sourceScreenKey: resolvedPair.sourceScreenKey,
+			destinationScreenKey: resolvedPair.destinationScreenKey,
+			hasTargetOverride,
+			usedSnapshotDestination: resolvedPair.usedSnapshotDestination,
 		};
 	}
 
@@ -75,6 +84,11 @@ const resolveBounds = (params: {
 			start: null,
 			end: null,
 			entering,
+			currentScreenKey,
+			sourceScreenKey: resolvedPair.sourceScreenKey,
+			destinationScreenKey: resolvedPair.destinationScreenKey,
+			hasTargetOverride,
+			usedSnapshotDestination: resolvedPair.usedSnapshotDestination,
 		};
 	}
 
@@ -94,6 +108,11 @@ const resolveBounds = (params: {
 		start,
 		end,
 		entering,
+		currentScreenKey,
+		sourceScreenKey: resolvedPair.sourceScreenKey,
+		destinationScreenKey: resolvedPair.destinationScreenKey,
+		hasTargetOverride,
+		usedSnapshotDestination: resolvedPair.usedSnapshotDestination,
 	};
 };
 
@@ -111,7 +130,16 @@ export const computeBoundStyles = (
 		return EMPTY_BOUND_HELPER_RESULT;
 	}
 
-	const { start, end, entering } = resolveBounds({
+	const {
+		start,
+		end,
+		entering,
+		currentScreenKey,
+		sourceScreenKey,
+		destinationScreenKey,
+		hasTargetOverride,
+		usedSnapshotDestination,
+	} = resolveBounds({
 		id,
 		previous,
 		current,
@@ -131,9 +159,20 @@ export const computeBoundStyles = (
 	const ranges: readonly [number, number] = entering ? ENTER_RANGE : EXIT_RANGE;
 
 	if (computeOptions.method === "content") {
+		const ignoresSnapshotDestinationOwnership =
+			hasTargetOverride &&
+			usedSnapshotDestination &&
+			destinationScreenKey === sourceScreenKey;
+		const currentOwnsSource =
+			!!currentScreenKey &&
+			currentScreenKey === sourceScreenKey &&
+			(currentScreenKey !== destinationScreenKey ||
+				ignoresSnapshotDestinationOwnership);
+		const contentStart = currentOwnsSource ? end : start;
+		const contentEnd = currentOwnsSource ? start : end;
 		const geometry = computeContentTransformGeometry({
-			start,
-			end,
+			start: contentStart,
+			end: contentEnd,
 			entering,
 			dimensions,
 			anchor: computeOptions.anchor,
@@ -141,10 +180,10 @@ export const computeBoundStyles = (
 		});
 
 		return composeContentStyle({
-			start,
+			start: contentStart,
 			progress,
 			ranges,
-			end,
+			end: contentEnd,
 			geometry,
 			computeOptions,
 		});

package/src/shared/utils/bounds/helpers/geometry.ts

@@ -95,8 +95,9 @@ export function computeRelativeGeometry({
 	return { dx, dy, scaleX, scaleY, entering };
 }
 /**
- * Computes the transform to apply to the entire destination screen so that
- * its bound (end) matches the source bound (start) at progress start.
+ * Computes the transform to apply to the current screen so that its owned
+ * bound (`end`) matches the paired target bound (`start`) at the aligned
+ * phase of the transition.
  */
 export function computeContentTransformGeometry({
 	start,

package/src/shared/utils/bounds/helpers/interpolators.ts

@@ -2,6 +2,7 @@ import type { MeasuredDimensions } from "react-native-reanimated";
 import { ENTER_RANGE, EXIT_RANGE } from "../../../constants";
 import { BoundStore } from "../../../stores/bounds";
 import type { ScreenInterpolationProps } from "../../../types/animation.types";
+import type { BoundId } from "../types/options";
 import { interpolateClamped } from "./interpolate";
 import { interpolateLinkStyle } from "./interpolate-style";
 import type { LinkAccessor } from "./link-accessor";
@@ -18,7 +19,7 @@ export const createInterpolators = ({
 	"worklet";
 
 	const interpolateStyle = (
-		tag: string,
+		tag: BoundId,
 		property: string,
 		fallback?: number,
 	): number => {
@@ -32,7 +33,7 @@ export const createInterpolators = ({
 	};
 
 	const interpolateBoundsFromSnapshot = (
-		tag: string,
+		tag: BoundId,
 		property: keyof MeasuredDimensions,
 		targetKey: string,
 		fallback?: number,
@@ -44,11 +45,12 @@ export const createInterpolators = ({
 		const range = entering ? ENTER_RANGE : EXIT_RANGE;
 		const currentKey = props.current?.route?.key;
 		const fb = fallback ?? 0;
+		const normalizedTag = String(tag);
 
 		const currentSnapshot = currentKey
-			? BoundStore.getSnapshot(tag, currentKey)
+			? BoundStore.getSnapshot(normalizedTag, currentKey)
 			: null;
-		const targetSnapshot = BoundStore.getSnapshot(tag, targetKey);
+		const targetSnapshot = BoundStore.getSnapshot(normalizedTag, targetKey);
 
 		const currentValue = currentSnapshot?.bounds?.[property] ?? fb;
 		const targetValue = targetSnapshot?.bounds?.[property] ?? fb;
@@ -60,7 +62,7 @@ export const createInterpolators = ({
 	};
 
 	const interpolateBoundsFromLink = (
-		tag: string,
+		tag: BoundId,
 		property: keyof MeasuredDimensions,
 		fallback?: number,
 	): number => {
@@ -82,7 +84,7 @@ export const createInterpolators = ({
 	};
 
 	const interpolateBounds = (
-		tag: string,
+		tag: BoundId,
 		property: keyof MeasuredDimensions,
 		fallbackOrTargetKey?: number | string,
 		fallback?: number,

package/src/shared/utils/bounds/helpers/link-accessor.ts

@@ -1,27 +1,31 @@
 import { BoundStore, type Snapshot } from "../../../stores/bounds";
 import type { ScreenInterpolationProps } from "../../../types/animation.types";
 import type { BoundsLink } from "../../../types/bounds.types";
+import type { BoundId } from "../types/options";
 
 type GetProps = () => Omit<ScreenInterpolationProps, "bounds">;
 
 export type LinkAccessor = {
-	getSnapshot: (tag: string, key?: string) => Snapshot | null;
-	getLink: (tag: string) => BoundsLink | null;
+	getSnapshot: (tag: BoundId, key?: string) => Snapshot | null;
+	getLink: (tag: BoundId) => BoundsLink | null;
 };
 
 export const createLinkAccessor = (getProps: GetProps): LinkAccessor => {
 	"worklet";
 
-	const getSnapshot = (tag: string, key?: string): Snapshot | null => {
+	const getSnapshot = (tag: BoundId, key?: string): Snapshot | null => {
 		"worklet";
 		if (!key) return null;
-		return BoundStore.getSnapshot(tag, key);
+		return BoundStore.getSnapshot(String(tag), key);
 	};
 
-	const getLink = (tag: string): BoundsLink | null => {
+	const getLink = (tag: BoundId): BoundsLink | null => {
 		"worklet";
 		const props = getProps();
-		const link = BoundStore.getActiveLink(tag, props.current?.route.key);
+		const link = BoundStore.getActiveLink(
+			String(tag),
+			props.current?.route.key,
+		);
 		if (!link) return null;
 		return {
 			source: link.source

package/src/shared/utils/bounds/helpers/resolve-bound-tag.ts

@@ -1,7 +1,7 @@
-import { BoundStore } from "../../../stores/bounds";
+import type { BoundId } from "../types/options";
 
 export type ResolveBoundTagParams = {
-	id?: string;
+	id?: BoundId;
 	group?: string;
 };
 
@@ -11,16 +11,13 @@ export const resolveBoundTag = ({
 }: ResolveBoundTagParams): string | undefined => {
 	"worklet";
 
-	if (!id) return id;
+	if (id === undefined || id === null || id === "") return undefined;
 
-	if (!group) {
-		return id;
-	}
+	const normalizedId = String(id);
 
-	const currentActiveId = BoundStore.getGroupActiveId(group);
-	if (currentActiveId !== id) {
-		BoundStore.setGroupActiveId(group, id);
+	if (!group) {
+		return normalizedId;
 	}
 
-	return `${group}:${id}`;
+	return `${group}:${normalizedId}`;
 };

package/src/shared/utils/bounds/helpers/style-composers.ts

@@ -22,9 +22,10 @@ export type ElementComposeParams = {
 };
 
 /**
- * Screen-level content transform params (for aligning destination bound to source).
- * - start/end: absolute window bounds for the shared id (source/destination)
- * - geometry: precomputed screen-level tx/ty/sx/sy plus ranges/entering
+ * Screen-level content transform params.
+ * - start/end: absolute window bounds for the paired target and the current
+ *   screen-owned bound
+ * - geometry: precomputed screen-level tx/ty/scale plus ranges/entering
  * - interp: function to interpolate between numbers using the correct progress range
  */
 type ContentComposeParams = {

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

@@ -5,12 +5,24 @@ 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 { createNavigationAccessor } from "./helpers/navigation-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";
+
+const syncGroupActiveMember = (group?: string, id?: string | number) => {
+	"worklet";
+	if (!group) return;
+	if (id === undefined || id === null || id === "") return;
+
+	const normalizedId = String(id);
+	if (BoundStore.getGroupActiveId(group) === normalizedId) return;
+
+	BoundStore.setGroupActiveId(group, normalizedId);
+};
 
 export const createBoundsAccessor = (
-	getProps: () => Omit<ScreenInterpolationProps, "bounds">,
+	getProps: () => BoundsFrameProps,
 ): BoundsAccessor => {
 	"worklet";
 
@@ -37,6 +49,7 @@ export const createBoundsAccessor = (
 	const computeElementBoundsStyles = (params?: BoundsOptions) => {
 		"worklet";
 		const props = getProps();
+		syncGroupActiveMember(params?.group, params?.id);
 
 		const resolved = buildBoundsOptions({
 			props,
@@ -47,24 +60,20 @@ export const createBoundsAccessor = (
 			resolveBoundTag,
 		});
 
-		const computed = computeForResolvedOptions(resolved, props) as Record<
-			string,
-			unknown
-		>;
+		const computed = computeForResolvedOptions(resolved, props);
+
 		const zoomBaseOptions = {
 			anchor: params?.anchor,
 			scaleMode: params?.scaleMode,
 			target: params?.target,
 		};
-		let cachedNavigationPairProps:
-			| Omit<ScreenInterpolationProps, "bounds">
-			| undefined;
+		let cachedNavigationPairProps: BoundsFrameProps | undefined;
 		let cachedNavigationPairTag = "";
 		let cachedNavigationPair: ResolvedTransitionPair | undefined;
 
 		const resolveNavigationPair = (
 			tag: string,
-			frameProps: Omit<ScreenInterpolationProps, "bounds">,
+			frameProps: BoundsFrameProps,
 		): ResolvedTransitionPair | undefined => {
 			"worklet";
 			if (!tag) return undefined;
@@ -90,7 +99,7 @@ export const createBoundsAccessor = (
 			return nextPair;
 		};
 
-		const navigation = createNavigationAccessor({
+		const navigation = createZoomAccessor({
 			id: params?.id,
 			group: params?.group,
 			getProps,
@@ -108,7 +117,7 @@ export const createBoundsAccessor = (
 						resolveBoundTag,
 					});
 					const resolvedPair = resolveNavigationPair(
-						resolvedNavigationOptions.id,
+						String(resolvedNavigationOptions.id),
 						currentProps,
 					);
 
@@ -128,7 +137,7 @@ export const createBoundsAccessor = (
 			configurable: true,
 		});
 
-		return target as typeof computed & { navigation: typeof navigation };
+		return target;
 	};
 
 	const { getSnapshot, getLink } = createLinkAccessor(getProps);

package/src/shared/utils/bounds/types/frame-props.ts

@@ -0,0 +1,5 @@
+import type { ScreenInterpolationProps } from "../../../types/animation.types";
+
+export type BoundsFrameProps = Omit<ScreenInterpolationProps, "bounds"> & {
+	navigationMaskEnabled: boolean;
+};

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

@@ -3,6 +3,8 @@ import type { ScreenTransitionState } from "../../../types/animation.types";
 import type { BoundsMethod } from "../../../types/bounds.types";
 import type { Layout } from "../../../types/screen.types";
 
+export type BoundId = string | number;
+
 export type BoundsAnchor =
 	| "topLeading"
 	| "top"
@@ -21,7 +23,7 @@ type BoundsTarget = "bound" | "fullscreen" | MeasuredDimensions;
 type BoundsSpace = "relative" | "absolute";
 
 export type BoundsComputeParams = {
-	id?: string;
+	id?: BoundId;
 	previous?: ScreenTransitionState;
 	current: ScreenTransitionState;
 	next?: ScreenTransitionState;
@@ -81,7 +83,7 @@ export type BoundsOptions = {
 	 * The ID of the bound to compute bounds for.
 	 * When `group` is also provided, this is the member id within the group (not the combined tag).
 	 */
-	id: string;
+	id: BoundId;
 
 	/**
 	 * Optional group name for collection/list scenarios.
@@ -101,8 +103,8 @@ export type BoundsOptions = {
 	 *
 	 * - "transform": translates and scales (scaleX/scaleY), no width/height size
 	 * - "size": translates and sizes (width/height), no scaleX/scaleY
-	 * - "content": screen-level content transform that aligns the destination screen
-	 *   so the target bound matches the source at progress start
+	 * - "content": screen-level content transform that aligns the current screen
+	 *   so its bound matches the paired target bound during the transition
 	 * @default "transform"
 	 */
 	method?: BoundsMethod;