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

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

@@ -4,11 +4,13 @@ import {
 	type SharedValue,
 	useAnimatedReaction,
 } from "react-native-reanimated";
-import { getPairKeyForSource } from "../../../../../../stores/bounds/internals/links";
+import { pairs } from "../../../../../../stores/bounds/internals/state";
 import type { ScreenPairKey } from "../../../../../../stores/bounds/types";
 import type { NormalizedTransitionInterpolatedStyle } from "../../../../../../types/animation.types";
 import type { BoundaryLocalMeasurementValue } from "../../../../types";
 import { createBoundaryPortalHostName } from "../../../utils/naming";
+import { isTeleportEnabled } from "../../../utils/teleport-control";
+import { resolveActiveBoundaryPortalPairKey } from "../helpers/local-measurement";
 import {
 	mountPortalBoundaryHost,
 	unmountPortalBoundaryHostByName,
@@ -16,17 +18,15 @@ import {
 
 type UseActivePortalBoundaryHostParams = {
 	boundaryId: string;
-	currentScreenKey: string;
 	escapeHostKey?: string;
 	localMeasurement: BoundaryLocalMeasurementValue;
 	portalHostName: SharedValue<string | null>;
-	portalHostReady: SharedValue<boolean>;
+	portalHostReady: SharedValue<string | null>;
 	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
 };
 
 export const useActivePortalBoundaryHost = ({
 	boundaryId,
-	currentScreenKey,
 	escapeHostKey,
 	localMeasurement,
 	portalHostName,
@@ -44,13 +44,12 @@ export const useActivePortalBoundaryHost = ({
 	useAnimatedReaction(
 		() => {
 			"worklet";
-			const pairKey = getPairKeyForSource(boundaryId, currentScreenKey);
-			const measurement = localMeasurement.get();
-			if (!pairKey || measurement?.pairKey !== pairKey) {
-				return null;
-			}
-
-			return pairKey;
+			return resolveActiveBoundaryPortalPairKey(
+				localMeasurement.get(),
+				slotsMap.get()[boundaryId],
+				boundaryId,
+				pairs.get(),
+			);
 		},
 		(pairKey, previousPairKey) => {
 			"worklet";
@@ -58,6 +57,16 @@ export const useActivePortalBoundaryHost = ({
 				return;
 			}
 
+			const slot = slotsMap.get()[boundaryId];
+			if (
+				pairKey === null &&
+				localMeasurement.get() !== null &&
+				slot &&
+				!isTeleportEnabled(slot.props?.teleport)
+			) {
+				localMeasurement.set(null);
+			}
+
 			runOnJS(updateActivePairKey)(pairKey);
 		},
 	);
@@ -65,7 +74,7 @@ export const useActivePortalBoundaryHost = ({
 	useLayoutEffect(() => {
 		if (!activePairKey || !escapeHostKey) {
 			portalHostName.set(null);
-			portalHostReady.set(false);
+			portalHostReady.set(null);
 			return;
 		}
 
@@ -88,7 +97,7 @@ export const useActivePortalBoundaryHost = ({
 
 		return () => {
 			portalHostName.set(null);
-			portalHostReady.set(false);
+			portalHostReady.set(null);
 			unmountPortalBoundaryHostByName(nextPortalHostName);
 		};
 	}, [

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

@@ -1,9 +1,12 @@
+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";
-import { isTeleportEnabled } from "../../../utils/teleport-control";
+import { shouldAttachBoundaryPortal } from "../helpers/attachment";
+import { resolveActiveBoundaryPortalPairKey } from "../helpers/local-measurement";
 import { useActiveHostKey } from "../stores/host-registry.store";
 import { useActivePortalBoundaryHost } from "./use-active-portal-boundary-host";
 
@@ -15,23 +18,22 @@ 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(
 		(s) => s.derivations.currentScreenKey,
 	);
-	const { slotsMap } = useScreenSlots();
+	// React Navigation resolves focus through the entire parent navigator chain.
+	// 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 = useScreenSlotStore((store) => store.slotsMap);
 	const portalHostName = useSharedValue<string | null>(null);
-	const portalHostReady = useSharedValue(false);
+	const portalHostReady = useSharedValue<string | null>(null);
 	const escapeHostKey = useActiveHostKey(currentScreenKey);
 
 	useActivePortalBoundaryHost({
 		boundaryId,
-		currentScreenKey,
 		escapeHostKey,
 		localMeasurement,
 		portalHostName,
@@ -49,20 +51,31 @@ export const useBoundaryPortalAttachment = ({
 			...slotProps
 		} = slot?.props ?? {};
 
-		const shouldAttach =
-			slot !== undefined &&
-			isTeleportEnabled(teleport) &&
-			portalHostReady.get();
+		const activePortalHostName = portalHostName.get();
+		const shouldAttach = shouldAttachBoundaryPortal({
+			focused,
+			portalHostReady:
+				activePortalHostName !== null &&
+				portalHostReady.get() === activePortalHostName,
+			slotActive:
+				resolveActiveBoundaryPortalPairKey(
+					localMeasurement.get(),
+					slot,
+					boundaryId,
+					pairs.get(),
+				) !== null && slot !== undefined,
+			teleport,
+		});
 
 		const hostName = shouldAttach
-			? portalHostName.get()
+			? activePortalHostName
 			: PORTAL_HOST_NAME_RESET_VALUE;
 
 		return {
 			...slotProps,
 			hostName,
 		};
-	});
+	}, [focused]);
 
 	return { teleportProps };
 };

package/src/shared/components/boundary/portal/components/boundary-portal/stores/portal-boundary-host.store.ts

@@ -9,7 +9,7 @@ export type ActivePortalBoundaryHost = {
 	localMeasurement: BoundaryLocalMeasurementValue;
 	pairKey: string;
 	portalHostName: string;
-	portalHostReady: SharedValue<boolean>;
+	portalHostReady: SharedValue<string | null>;
 	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
 };
 

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/boundary/types.ts

@@ -60,7 +60,7 @@ export type MeasureTarget =
 			pairKey: ScreenPairKey;
 	  };
 
-export type MeasureBoundary = (target: MeasureTarget) => void;
+export type MeasureBoundary = (target: MeasureTarget) => boolean;
 
 export type BoundaryLocalMeasurement = {
 	bounds: MeasuredDimensions;

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();