react-native-screen-transitions 3.13.0-beta.0 → 3.13.0-beta.1

package/src/shared/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/shared/components/boundary/hooks/use-measurer.ts

@@ -3,7 +3,7 @@ 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 { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
@@ -41,7 +41,8 @@ export const useMeasurer = ({
 
 	const scrollState = ScrollStore.getValue(currentScreenKey, "coordination");
 	const scrollMetadata = ScrollStore.getValue(currentScreenKey, "metadata");
-	const { visibilityBlocked } = useScreenSlots();
+	const screenSlotStore = useScreenSlotStore();
+	const { visibilityBlocked } = screenSlotStore;
 
 	return useCallback(
 		(target) => {

package/src/shared/components/boundary/portal/components/boundary-content-portal/hooks/use-boundary-content-portal-attachment.ts

@@ -1,7 +1,10 @@
 import { useAnimatedProps, useSharedValue } from "react-native-reanimated";
 import { useStack } from "../../../../../../hooks/navigation/use-stack";
 import { useDescriptorsStore } from "../../../../../../providers/screen/descriptors";
-import { useScreenSlots } from "../../../../../../providers/screen/styles";
+import {
+	useOptionalScreenSlotStore,
+	useScreenSlotStore,
+} from "../../../../../../providers/screen/styles";
 import { hasCloseTransitionFinished } from "../../../../../../providers/screen/styles/helpers/transition-visual-state";
 import { AnimationStore } from "../../../../../../stores/animation.store";
 import { getLinkKeyFromTag } from "../../../../../../stores/bounds/helpers/link-pairs.helpers";
@@ -26,7 +29,7 @@ interface UseBoundaryContentPortalAttachmentParams {
 export const useBoundaryContentPortalAttachment = ({
 	boundaryId,
 }: UseBoundaryContentPortalAttachmentParams) => {
-	const { slotsMap } = useScreenSlots();
+	const slotsMap = useScreenSlotStore((store) => store.slotsMap);
 
 	const currentScreenKey = useDescriptorsStore(
 		(s) => s.derivations.currentScreenKey,
@@ -43,7 +46,7 @@ export const useBoundaryContentPortalAttachment = ({
 	const resolvedSourcePairKey = sourcePairKey ?? transitionSourcePairKey;
 	const resolvedDestinationScreenKey =
 		nextScreenKey ?? transitionDestinationScreenKey;
-	const destinationSlots = useScreenSlots(
+	const destinationSlots = useOptionalScreenSlotStore(
 		resolvedDestinationScreenKey ?? currentScreenKey,
 	);
 	const unavailableInterpolatorReady = useSharedValue(0);

package/src/shared/components/boundary/portal/components/boundary-portal/hooks/use-boundary-portal-attachment.ts

@@ -1,7 +1,7 @@
 import { useIsFocused } from "@react-navigation/native";
 import { useAnimatedProps, useSharedValue } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../../../../providers/screen/descriptors";
-import { useScreenSlots } from "../../../../../../providers/screen/styles";
+import { useScreenSlotStore } from "../../../../../../providers/screen/styles";
 import { pairs } from "../../../../../../stores/bounds/internals/state";
 import { useBoundaryRootStore } from "../../../../providers/boundary-root.provider";
 import { PORTAL_HOST_NAME_RESET_VALUE } from "../../../utils/naming";
@@ -18,10 +18,6 @@ export const useBoundaryPortalAttachment = ({
 	boundaryId,
 }: UseBoundaryPortalAttachmentParams) => {
 	const localMeasurement = useBoundaryRootStore((root) => {
-		if (!root) {
-			throw new Error("Boundary portal attachment requires a boundary root.");
-		}
-
 		return root.localMeasurement;
 	});
 	const currentScreenKey = useDescriptorsStore(
@@ -31,7 +27,7 @@ export const useBoundaryPortalAttachment = ({
 	// A leaf that is still selected in its own one-screen stack becomes unfocused
 	// when any ancestor route is covered.
 	const focused = useIsFocused();
-	const { slotsMap } = useScreenSlots();
+	const slotsMap = useScreenSlotStore((store) => store.slotsMap);
 	const portalHostName = useSharedValue<string | null>(null);
 	const portalHostReady = useSharedValue<string | null>(null);
 	const escapeHostKey = useActiveHostKey(currentScreenKey);

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

@@ -14,7 +14,7 @@ import {
 	useComposedSlotStyles,
 	useSlotStackingStyles,
 } from "../../../providers/screen/styles";
-import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
+import { useOptionalBlankStackStore } 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";
@@ -68,10 +68,14 @@ type BoundaryRootProviderProps = Pick<
 	targetStyle?: unknown;
 };
 
-export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
-	"BoundaryRoot",
-	{ guarded: false },
-)<BoundaryRootProviderProps, BoundaryRootContextValue>(
+export const {
+	BoundaryRootProvider,
+	useBoundaryRootStore,
+	useOptionalBoundaryRootStore,
+} = createProvider("BoundaryRoot")<
+	BoundaryRootProviderProps,
+	BoundaryRootContextValue
+>(
 	({
 		children,
 		config,
@@ -98,7 +102,7 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 		const currentScreenKey = useDescriptorsStore(
 			(s) => s.derivations.currentScreenKey,
 		);
-		const isCurrentScreenClosing = useBlankStackStore(
+		const isCurrentScreenClosing = useOptionalBlankStackStore(
 			(store) =>
 				portalRuntime.handoff &&
 				store?.scenesByKey[currentScreenKey]?.activity === "closing",

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

@@ -1,6 +1,19 @@
 import { updateDerivations } from "../../../providers/screen/animation/helpers/derivations";
 import type { ScreenInterpolatorFrame } from "../../../providers/screen/animation/helpers/pipeline";
 
+export const shouldUseOverlayGestureDriver = (
+	overlayFrame: ScreenInterpolatorFrame,
+	driverFrame: ScreenInterpolatorFrame,
+): boolean => {
+	"worklet";
+	const gesture = overlayFrame.current.gesture;
+
+	return (
+		driverFrame.current.route.key !== overlayFrame.current.route.key &&
+		!!(gesture.dragging || gesture.dismissing || gesture.settling)
+	);
+};
+
 export const createOverlayInterpolatorFrame = ({
 	overlayFrame,
 	driverFrame,
@@ -22,7 +35,7 @@ export const createOverlayInterpolatorFrame = ({
 	};
 
 	updateDerivations(frame);
-	frame.stackProgress = frame.progress;
+	frame.stackProgress = overlayFrame.stackProgress;
 	frame.logicallySettled = frame.active.settled;
 
 	return frame;

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

@@ -74,8 +74,33 @@ export function getFloatOverlayTransitions(
 ): FloatOverlayTransitionEntry[] {
 	const topScene = scenes[scenes.length - 1];
 
-	return overlayStack.map((entry, index) => ({
-		...entry,
-		driverScene: overlayStack[index + 1]?.scene ?? topScene ?? entry.scene,
-	}));
+	return overlayStack.map((entry, index) => {
+		const nextEntry = overlayStack[index + 1];
+		let nextPresentedEntry: FloatOverlayEntry | undefined;
+
+		for (
+			let nextIndex = index + 1;
+			nextIndex < overlayStack.length;
+			nextIndex++
+		) {
+			const candidate = overlayStack[nextIndex];
+			if (candidate?.scene.activity !== "closing") {
+				nextPresentedEntry = candidate;
+				break;
+			}
+		}
+
+		const driverScene =
+			entry.scene.activity === "closing" && nextEntry
+				? entry.scene
+				: (nextPresentedEntry?.scene ??
+					nextEntry?.scene ??
+					topScene ??
+					entry.scene);
+
+		return {
+			...entry,
+			driverScene,
+		};
+	});
 }

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

@@ -15,11 +15,15 @@ import type {
 	ScreenStyleInterpolator,
 } from "../../../types/animation.types";
 import { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
-import { createOverlayInterpolatorFrame } from "../helpers/create-overlay-interpolator-frame";
+import {
+	createOverlayInterpolatorFrame,
+	shouldUseOverlayGestureDriver,
+} from "../helpers/create-overlay-interpolator-frame";
 import { runOverlaySlotInterpolator } from "../helpers/run-overlay-slot-interpolator";
 
 export const useOverlaySlot = ({
 	overlayAnimationStore,
+	overlayInterpolator,
 	driverAnimationStore,
 	previousOverlayAnimationStore,
 	driverInterpolator,
@@ -27,6 +31,7 @@ export const useOverlaySlot = ({
 	isIncoming,
 }: {
 	overlayAnimationStore: ScreenAnimationContextValue;
+	overlayInterpolator: ScreenStyleInterpolator | undefined;
 	driverAnimationStore: ScreenAnimationContextValue;
 	previousOverlayAnimationStore?: ScreenAnimationContextValue;
 	driverInterpolator: ScreenStyleInterpolator | undefined;
@@ -34,11 +39,16 @@ export const useOverlaySlot = ({
 	isIncoming: boolean;
 }) => {
 	const { height } = useWindowDimensions();
-	const transition = useBuildTransitionAccessor(driverAnimationStore);
+	const overlayTransition = useBuildTransitionAccessor(overlayAnimationStore);
+	const driverTransition = useBuildTransitionAccessor(driverAnimationStore);
 
 	const interpolatorSharedValues = useMemo(
-		() => collectInterpolatorSharedValues([driverInterpolator]),
-		[driverInterpolator],
+		() =>
+			collectInterpolatorSharedValues([
+				overlayInterpolator,
+				driverInterpolator,
+			]),
+		[overlayInterpolator, driverInterpolator],
 	);
 
 	const overlaySlot = useDerivedValue<
@@ -53,17 +63,25 @@ export const useOverlaySlot = ({
 			interpolatorSharedValues[index]?.get();
 		}
 
+		const overlayFrame = overlayAnimationStore.screenInterpolatorProps.get();
+		const driverFrame = driverAnimationStore.screenInterpolatorProps.get();
+		const overlayOwnsGesture = shouldUseOverlayGestureDriver(
+			overlayFrame,
+			driverFrame,
+		);
 		const frame = createOverlayInterpolatorFrame({
-			overlayFrame: overlayAnimationStore.screenInterpolatorProps.get(),
-			driverFrame: driverAnimationStore.screenInterpolatorProps.get(),
+			overlayFrame,
+			driverFrame: overlayOwnsGesture ? overlayFrame : driverFrame,
 			previousOverlayFrame:
 				previousOverlayAnimationStore?.screenInterpolatorProps.get(),
 		});
 
 		return runOverlaySlotInterpolator({
 			frame,
-			interpolator: driverInterpolator,
-			transition,
+			interpolator: overlayOwnsGesture
+				? overlayInterpolator
+				: driverInterpolator,
+			transition: overlayOwnsGesture ? overlayTransition : driverTransition,
 		});
 	});
 

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

@@ -7,11 +7,11 @@ import { StyleSheet, View } from "react-native";
 import Animated, { useDerivedValue } from "react-native-reanimated";
 import { snapDescriptorToIndex } from "../../../animation/snap-to";
 import { useStack } from "../../../hooks/navigation/use-stack";
-import { useScreenAnimationStore } from "../../../providers/screen/animation";
+import { useOptionalScreenAnimationStore } from "../../../providers/screen/animation";
 import type { ScreenAnimationContextValue } from "../../../providers/screen/animation/animation.provider";
 import {
 	type ScreenSlotContextValue,
-	useScreenSlots,
+	useOptionalScreenSlotStore,
 } from "../../../providers/screen/styles/slot.provider";
 import type { OverlayProps } from "../../../types/overlay.types";
 import type {
@@ -39,12 +39,16 @@ export const OverlayHost = memo(function OverlayHost({
 	activity,
 	layerIndex,
 }: OverlayHostProps) {
-	const overlayAnimationStore = useScreenAnimationStore(scene.route.key);
-	const driverAnimationStore = useScreenAnimationStore(driverScene.route.key);
-	const previousOverlayAnimationStore = useScreenAnimationStore(
+	const overlayAnimationStore = useOptionalScreenAnimationStore(
+		scene.route.key,
+	);
+	const driverAnimationStore = useOptionalScreenAnimationStore(
+		driverScene.route.key,
+	);
+	const previousOverlayAnimationStore = useOptionalScreenAnimationStore(
 		previousOverlayScene?.route.key ?? scene.route.key,
 	);
-	const driverSlots = useScreenSlots(driverScene.route.key);
+	const driverSlots = useOptionalScreenSlotStore(driverScene.route.key);
 	const overlayComponentRef = useRef(scene.descriptor.options.overlay);
 	const OverlayComponent = overlayComponentRef.current;
 	const readyResourcesRef = useRef<ReadyOverlayResources | null>(null);
@@ -105,6 +109,7 @@ function ReadyOverlayHost({
 	const focusedDescriptor = focusedScene?.descriptor;
 	const { animatedProps, animatedStyle } = useOverlaySlot({
 		overlayAnimationStore,
+		overlayInterpolator: scene.descriptor.options.screenStyleInterpolator,
 		driverAnimationStore,
 		previousOverlayAnimationStore: previousOverlayAnimationStore ?? undefined,
 		driverInterpolator: driverScene.descriptor.options.screenStyleInterpolator,

package/src/shared/components/screen-container/layers/content.tsx

@@ -1,10 +1,9 @@
-/** biome-ignore-all lint/style/noNonNullAssertion: <Screen gesture is under the gesture context, so this will always exist.> */
 import { type ComponentType, memo, useMemo } from "react";
 import { StyleSheet, View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../providers/screen/descriptors";
-import { useGestureStore } from "../../../providers/screen/gestures";
+import { useScreenGestureStore } from "../../../providers/screen/gestures";
 import { useSlotProps, useSlotStyles } from "../../../providers/screen/styles";
 import type { ScreenContentComponentProps } from "../../../types";
 import { ScreenFallbackHost } from "../../boundary/portal/components/boundary-portal/components/host";
@@ -21,7 +20,7 @@ type Props = {
 
 export const ContentLayer = memo(
 	({ children, pointerEvents, isBackdropActive }: Props) => {
-		const gestureContext = useGestureStore();
+		const gestureContext = useScreenGestureStore();
 		const ContentComponent = useDescriptorsStore(
 			(store) => store.options.contentComponent,
 		);
@@ -71,7 +70,7 @@ export const ContentLayer = memo(
 		);
 
 		return (
-			<GestureDetector gesture={gestureContext!.detectorGesture}>
+			<GestureDetector gesture={gestureContext.detectorGesture}>
 				{AnimatedContentComponent ? (
 					<AnimatedContentComponent
 						style={contentStyles}

package/src/shared/components/screen-lifecycle/hooks/use-close-transition-intent.ts

@@ -2,11 +2,9 @@ import { useLayoutEffect, useMemo, useRef } from "react";
 import { useNavigationHelpers } from "../../../hooks/navigation/use-navigation-helpers";
 import useStableCallback from "../../../hooks/use-stable-callback";
 import { hasTransitionsEnabled } from "../../../providers/screen/animation/helpers/has-transitions-enabled";
-import {
-	type BaseDescriptor,
-	useDescriptorsStore,
-} from "../../../providers/screen/descriptors";
-import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import { useCurrentScreenRelationships } from "../../../providers/screen/use-current-screen-relationships";
+import { useOptionalBlankStackStore } from "../../../providers/stack/blank-stack.provider";
 import { useStackCoreStore } from "../../../providers/stack/core.provider";
 import { GestureStore } from "../../../stores/gesture.store";
 import { StackType } from "../../../types/stack.types";
@@ -24,18 +22,16 @@ export function useCloseTransitionIntent(current: BaseDescriptor): {
 	completeClose: () => void;
 } {
 	const routeKey = current.route.key;
+	const flags = useStackCoreStore((store) => store.flags);
 	const { STACK_TYPE: stackType, TRANSITIONS_ALWAYS_ON: transitionsAlwaysOn } =
-		useStackCoreStore((store) => store.flags);
-	const handleCloseRoute = useBlankStackStore(
+		flags;
+	const handleCloseRoute = useOptionalBlankStackStore(
 		(store) => store?.handleCloseRoute,
 	);
-	const isBlankStackClosing = useBlankStackStore(
+	const isBlankStackClosing = useOptionalBlankStackStore(
 		(store) => store?.scenesByKey[routeKey]?.activity === "closing",
 	);
-	const ancestorKeys = useDescriptorsStore(
-		(store) => store.derivations.ancestorKeys,
-	);
-	const parentScreenKey = ancestorKeys[0];
+	const { parentScreenKey } = useCurrentScreenRelationships();
 	const { dismissScreen, requestDismiss } = useNavigationHelpers();
 	const pendingActionRef = useRef<any>(null);
 

package/src/shared/factories/screen-topology/create-screen-topology.ts

@@ -0,0 +1,199 @@
+import type {
+	ActiveScreenRegistration,
+	ScreenRelationships,
+	ScreenTopology,
+	ScreenTopologyRegistration,
+} from "./types";
+
+type ScreenNode = {
+	parentScreenKey: string | null;
+	activeChildScreenKeys: string[];
+};
+
+const EMPTY_RELATIONSHIPS: ScreenRelationships = {
+	parentScreenKey: null,
+	activeChildScreenKey: null,
+};
+
+const areRelationshipsEqual = (
+	left: ScreenRelationships,
+	right: ScreenRelationships,
+): boolean =>
+	left.parentScreenKey === right.parentScreenKey &&
+	left.activeChildScreenKey === right.activeChildScreenKey;
+
+export const createScreenTopology = (): ScreenTopology => {
+	const nodes = new Map<string, ScreenNode>();
+	const listenersByScreenKey = new Map<string, Set<() => void>>();
+	const relationshipCache = new Map<string, ScreenRelationships>();
+
+	const getNode = (screenKey: string) => nodes.get(screenKey);
+	const ensureNode = (screenKey: string) => {
+		const existing = getNode(screenKey);
+		if (existing) return existing;
+
+		const node: ScreenNode = {
+			parentScreenKey: null,
+			activeChildScreenKeys: [],
+		};
+		nodes.set(screenKey, node);
+		return node;
+	};
+
+	const removeNodeIfEmpty = (screenKey: string) => {
+		const node = getNode(screenKey);
+		if (
+			node &&
+			!node.parentScreenKey &&
+			node.activeChildScreenKeys.length === 0
+		) {
+			nodes.delete(screenKey);
+		}
+	};
+
+	const getParent = (screenKey: string) =>
+		getNode(screenKey)?.parentScreenKey ?? null;
+
+	const getActiveChild = (screenKey: string) => {
+		const activeChildScreenKeys = getNode(screenKey)?.activeChildScreenKeys;
+		return activeChildScreenKeys?.[activeChildScreenKeys.length - 1] ?? null;
+	};
+
+	const materializeRelationships = (screenKey: string): ScreenRelationships => {
+		const parentScreenKey = getParent(screenKey);
+		const activeChildScreenKey = getActiveChild(screenKey);
+
+		if (!parentScreenKey && !activeChildScreenKey) {
+			return EMPTY_RELATIONSHIPS;
+		}
+
+		return { parentScreenKey, activeChildScreenKey };
+	};
+
+	const getRelationships = (screenKey: string) => {
+		const cached = relationshipCache.get(screenKey);
+		if (cached) return cached;
+
+		const relationships = materializeRelationships(screenKey);
+		relationshipCache.set(screenKey, relationships);
+		return relationships;
+	};
+
+	const mutate = (affectedScreenKeys: Set<string>, mutation: () => void) => {
+		const previousRelationships = new Map<string, ScreenRelationships>();
+		for (const screenKey of affectedScreenKeys) {
+			if (listenersByScreenKey.has(screenKey)) {
+				previousRelationships.set(screenKey, getRelationships(screenKey));
+			}
+		}
+
+		mutation();
+		for (const screenKey of affectedScreenKeys) {
+			relationshipCache.delete(screenKey);
+		}
+
+		for (const [screenKey, previous] of previousRelationships) {
+			const listeners = listenersByScreenKey.get(screenKey);
+			if (!listeners) continue;
+
+			const next = getRelationships(screenKey);
+			if (areRelationshipsEqual(previous, next)) {
+				relationshipCache.set(screenKey, previous);
+				continue;
+			}
+
+			for (const listener of listeners) listener();
+		}
+	};
+
+	const register = ({
+		screenKey,
+		parentScreenKey,
+	}: ScreenTopologyRegistration) => {
+		mutate(new Set([screenKey]), () => {
+			ensureNode(screenKey).parentScreenKey = parentScreenKey ?? null;
+		});
+	};
+
+	const unregister = (screenKey: string) => {
+		const node = getNode(screenKey);
+		if (!node) return;
+
+		const affectedScreenKeys = new Set([screenKey]);
+		if (node.parentScreenKey) {
+			affectedScreenKeys.add(node.parentScreenKey);
+		}
+
+		mutate(affectedScreenKeys, () => {
+			if (node.parentScreenKey) {
+				const parent = getNode(node.parentScreenKey);
+				if (parent) {
+					parent.activeChildScreenKeys = parent.activeChildScreenKeys.filter(
+						(activeScreenKey) => activeScreenKey !== screenKey,
+					);
+				}
+				removeNodeIfEmpty(node.parentScreenKey);
+			}
+
+			nodes.delete(screenKey);
+		});
+	};
+
+	const activate = (registration: ActiveScreenRegistration) => {
+		if (getParent(registration.screenKey) !== registration.parentScreenKey) {
+			throw new Error(
+				"Screen topology can only activate a direct containment child.",
+			);
+		}
+
+		const affectedScreenKeys = new Set([registration.parentScreenKey]);
+		mutate(affectedScreenKeys, () => {
+			const parent = ensureNode(registration.parentScreenKey);
+			parent.activeChildScreenKeys = [
+				...parent.activeChildScreenKeys.filter(
+					(screenKey) => screenKey !== registration.screenKey,
+				),
+				registration.screenKey,
+			];
+		});
+
+		return () => {
+			const parent = getNode(registration.parentScreenKey);
+			if (!parent?.activeChildScreenKeys.includes(registration.screenKey)) {
+				return;
+			}
+
+			mutate(affectedScreenKeys, () => {
+				parent.activeChildScreenKeys = parent.activeChildScreenKeys.filter(
+					(screenKey) => screenKey !== registration.screenKey,
+				);
+				removeNodeIfEmpty(registration.parentScreenKey);
+			});
+		};
+	};
+
+	return {
+		register,
+		unregister,
+		activate,
+		getRelationships,
+		subscribe: (screenKey, listener) => {
+			const listeners =
+				listenersByScreenKey.get(screenKey) ?? new Set<() => void>();
+			listeners.add(listener);
+			listenersByScreenKey.set(screenKey, listeners);
+
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size === 0) {
+					listenersByScreenKey.delete(screenKey);
+					if (!getNode(screenKey)) {
+						relationshipCache.delete(screenKey);
+					}
+				}
+			};
+		},
+	};
+};
+
+export const screenTopology = createScreenTopology();

package/src/shared/factories/screen-topology/index.ts

@@ -0,0 +1,16 @@
+export {
+	createScreenTopology,
+	screenTopology,
+} from "./create-screen-topology";
+export type {
+	ActiveScreenRegistration,
+	ScreenRelationships,
+	ScreenTopology,
+	ScreenTopologyRegistration,
+} from "./types";
+export { useScreenRelationships } from "./use-screen-relationships";
+export {
+	registerWorkletScreen,
+	screenBelongsToScope,
+	unregisterWorkletScreen,
+} from "./worklet";

package/src/shared/factories/screen-topology/types.ts

@@ -0,0 +1,22 @@
+export type ScreenTopologyRegistration = {
+	screenKey: string;
+	parentScreenKey?: string;
+};
+
+export type ActiveScreenRegistration = {
+	parentScreenKey: string;
+	screenKey: string;
+};
+
+export type ScreenRelationships = Readonly<{
+	parentScreenKey: string | null;
+	activeChildScreenKey: string | null;
+}>;
+
+export type ScreenTopology = {
+	register(registration: ScreenTopologyRegistration): void;
+	unregister(screenKey: string): void;
+	activate(registration: ActiveScreenRegistration): () => void;
+	getRelationships(screenKey: string): ScreenRelationships;
+	subscribe(screenKey: string, listener: () => void): () => void;
+};

package/src/shared/factories/screen-topology/use-screen-relationships.ts

@@ -0,0 +1,15 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { screenTopology } from "./create-screen-topology";
+
+export const useScreenRelationships = (screenKey: string) => {
+	const subscribe = useCallback(
+		(listener: () => void) => screenTopology.subscribe(screenKey, listener),
+		[screenKey],
+	);
+	const getSnapshot = useCallback(
+		() => screenTopology.getRelationships(screenKey),
+		[screenKey],
+	);
+
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};