fix(iOS, Modal): Filter-out obsolete state updates from JS (#3760)

## Description

This PR introduces logic to collect only active (non-dismissed) modal
controllers coming from JS state.

When a Modal is dismissed on the native side, its state is sent
asynchronously to JavaScript. This can result in some race conditions
and stale updates being sent from JS to native. These outdated updates
may reference modals that were detached from the native view hierarchy.

Since view recycling is disabled, we don't expect dismissed modals to be
reattached; a new instance should be created when we push an updated
state from JS. Then the new controller instance will be initialized, so
these associated with detached screens won't be reused again. Therefore,
we can safely filter them out from the JS state on the native side. On
the JS side, the state will stabilize at some point and align with
native, once we receive all asynchronous events.

This fix is brought with an experimental feature flag
`iosPreventReattachmentOfDismissedModals` - similar to what we did for
`iosPreventReattachmentOfDismissedScreens`. You can opt out in case of
any potential regressions. I'm not using the already existing flag
deliberately. Extending its responsibility seems to be too much and may
unnecessarily force disabling other fixes, when the regression will be
touching only the modal hierarchy.

Closes:
software-mansion/react-native-screens-labs#1017

## Changes

- Added logic to mark detached modals.
- Added logic for filtering out screens dismissed natively from JS
state.

## Before & after - visual documentation

| Before | After |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/e8156173-c6d7-4d82-ab78-882e7dba77f8"
/> | <video
src="https://github.com/user-attachments/assets/c2d22d7e-0ecb-4bdf-ae59-6d7fa2370a54"
/> |

## Test plan

Added Test3760, verified the Modals test.

## Checklist

- [x] Included code example that can be used to test this change.
- [ ] Updated / created local changelog entries in relevant test files.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [x] For API changes, updated relevant public types.
- [ ] Ensured that CI passes

Author: t0maboro

FabricExample/App.tsx

@@ -7,6 +7,7 @@ featureFlags.experiment.synchronousHeaderSubviewUpdatesEnabled = false;
 featureFlags.experiment.androidResetScreenShadowStateOnOrientationChangeEnabled =
   true;
 featureFlags.experiment.iosPreventReattachmentOfDismissedScreens = true;
+featureFlags.experiment.iosPreventReattachmentOfDismissedModals = true;
 featureFlags.experiment.ios26AllowInteractionsDuringTransition = true;
 featureFlags.stable.debugLogging = true;
 

android/src/main/java/com/swmansion/rnscreens/ScreenStackViewManager.kt

@@ -74,12 +74,19 @@ class ScreenStackViewManager :
         )
 
     // iosPreventReattachmentOfDismissedScreens is not available on Android,
-    // however we must override their setters
+    // however we must override the setter
     override fun setIosPreventReattachmentOfDismissedScreens(
         view: ScreenStack?,
         value: Boolean,
     ) = Unit
 
+    // iosPreventReattachmentOfDismissedModals is not available on Android,
+    // however we must override the setter
+    override fun setIosPreventReattachmentOfDismissedModals(
+        view: ScreenStack?,
+        value: Boolean,
+    ) = Unit
+
     companion object {
         const val REACT_CLASS = "RNSScreenStack"
     }

apps/src/tests/issue-tests/Test3760.tsx

@@ -0,0 +1,92 @@
+import React from 'react';
+import { View, Text, Button, StyleSheet } from 'react-native';
+import {
+  NavigationContainer,
+  type ParamListBase,
+} from '@react-navigation/native';
+import {
+  createNativeStackNavigator,
+  type NativeStackNavigationProp,
+} from '@react-navigation/native-stack';
+import Colors from '../../shared/styling/Colors';
+
+type RouteParamList = {
+  Main: undefined;
+  ModalOne: undefined;
+  ModalTwo: undefined;
+};
+
+type NavigationProp<ParamList extends ParamListBase> = {
+  navigation: NativeStackNavigationProp<ParamList>;
+};
+
+type StackNavigationProp = NavigationProp<RouteParamList>;
+
+function MainScreen({ navigation }: StackNavigationProp) {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Main Screen</Text>
+      <View style={styles.buttonContainer}>
+        <Button
+          title="Open Modal One"
+          onPress={() => navigation.navigate('ModalOne')}
+        />
+      </View>
+      <View style={styles.buttonContainer}>
+        <Button
+          title="Open Modal Two"
+          color="green"
+          onPress={() => navigation.navigate('ModalTwo')}
+        />
+      </View>
+    </View>
+  );
+}
+
+function ModalOneScreen() {
+  return (
+    <View style={[styles.container, { backgroundColor: Colors.BlueLight20 }]}>
+      <Text style={styles.title}>This is Modal One</Text>
+    </View>
+  );
+}
+
+function ModalTwoScreen() {
+  return (
+    <View style={[styles.container, { backgroundColor: Colors.GreenLight20 }]}>
+      <Text style={styles.title}>This is Modal Two</Text>
+    </View>
+  );
+}
+
+const Stack = createNativeStackNavigator<RouteParamList>();
+
+export default function App() {
+  return (
+    <NavigationContainer>
+      <Stack.Navigator>
+        <Stack.Screen name="Main" component={MainScreen} />
+        <Stack.Group screenOptions={{ presentation: 'modal' }}>
+          <Stack.Screen name="ModalOne" component={ModalOneScreen} />
+          <Stack.Screen name="ModalTwo" component={ModalTwoScreen} />
+        </Stack.Group>
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 20,
+  },
+  title: {
+    fontSize: 24,
+    marginBottom: 16,
+  },
+  buttonContainer: {
+    marginVertical: 10,
+  },
+});

apps/src/tests/issue-tests/index.ts

@@ -181,6 +181,7 @@ export { default as Test3576 } from './Test3576';
 export { default as Test3596 } from './Test3596';
 export { default as Test3611 } from './Test3611';
 export { default as Test3617 } from './Test3617';
+export { default as Test3760 } from './Test3760';
 export { default as TestScreenAnimation } from './TestScreenAnimation';
 // The following test was meant to demo the "go back" gesture using Reanimated
 // but the associated PR in react-navigation is currently put on hold

ios/RNSScreen.h

@@ -60,6 +60,7 @@ namespace react = facebook::react;
 - (CGFloat)calculateHeaderHeightIsModal:(BOOL)isModal;
 #endif
 - (BOOL)isRemovedFromParent;
+- (void)notifyPresentedControllerDismissed;
 
 @end
 

ios/RNSScreen.mm

@@ -873,6 +873,8 @@ - (void)presentationControllerDidDismiss:(UIPresentationController *)presentatio
     [RNSScreenView.viewInteractionManagerInstance enableInteractionsForLastSubtree];
   }
 
+  [_controller notifyPresentedControllerDismissed];
+
   if ([_reactSuperview respondsToSelector:@selector(presentationControllerDidDismiss:)]) {
     [_reactSuperview performSelector:@selector(presentationControllerDidDismiss:) withObject:presentationController];
   }
@@ -1945,6 +1947,11 @@ - (BOOL)isRemovedFromParent
   return _isRemovedFromParent;
 }
 
+- (void)notifyPresentedControllerDismissed
+{
+  _isRemovedFromParent = YES;
+}
+
 #pragma mark - transition progress related methods
 
 - (void)setupProgressNotification

ios/RNSScreenStack.h

@@ -44,6 +44,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic) BOOL disableSwipeBack;
 
 @property (nonatomic, readwrite) BOOL iosPreventReattachmentOfDismissedScreens;
+@property (nonatomic, readwrite) BOOL iosPreventReattachmentOfDismissedModals;
 
 #ifdef RCT_NEW_ARCH_ENABLED
 #else

ios/RNSScreenStack.mm

@@ -253,6 +253,7 @@ - (void)initCommonProps
   _controller.delegate = self;
   _sinkEventsPanGestureRecognizer = [[UIPanGestureRecognizer alloc] init];
   _iosPreventReattachmentOfDismissedScreens = YES;
+  _iosPreventReattachmentOfDismissedModals = YES;
 #if !TARGET_OS_TV && !TARGET_OS_VISION
   [self setupGestureHandlers];
 #endif
@@ -780,6 +781,17 @@ - (void)updateContainer
           }
           [pushControllers addObject:screen.controller];
         } else {
+          /// When a Modal is dismissed natively the event is sent to JS **asynchronously**.
+          /// If multiple modals are pushed/dismissed quickly, JS might send back
+          /// a delayed update containing modals that were already dismissed. Attempting to render this
+          /// stale state could force UIKit to illegally reshuffle presented controllers.
+          /// We're preventing this, identifying reshuffling as an invalid state.
+          /// Since view recycling is disabled, once we detect that a modal has been removed from the view
+          /// hierarchy, it won't be reused. This allows us to safely filter out dismissed modal from modals coming
+          /// from JS state via `controllers`.
+          if (_iosPreventReattachmentOfDismissedModals && screen.controller.isRemovedFromParent) {
+            continue;
+          }
           [modalControllers addObject:screen.controller];
         }
       }
@@ -1378,6 +1390,11 @@ - (void)updateProps:(const facebook::react::Props::Shared &)props
     [self setIosPreventReattachmentOfDismissedScreens:newScreenProps.iosPreventReattachmentOfDismissedScreens];
   }
 
+  if (newScreenProps.iosPreventReattachmentOfDismissedModals !=
+      oldScreenProps.iosPreventReattachmentOfDismissedModals) {
+    [self setIosPreventReattachmentOfDismissedModals:newScreenProps.iosPreventReattachmentOfDismissedModals];
+  }
+
   [super updateProps:props oldProps:oldProps];
 }
 
@@ -1535,6 +1552,7 @@ @implementation RNSScreenStackManager {
 
 RCT_EXPORT_VIEW_PROPERTY(onFinishTransitioning, RCTDirectEventBlock);
 RCT_EXPORT_VIEW_PROPERTY(iosPreventReattachmentOfDismissedScreens, BOOL);
+RCT_EXPORT_VIEW_PROPERTY(iosPreventReattachmentOfDismissedModals, BOOL);
 
 #ifdef RCT_NEW_ARCH_ENABLED
 #else

src/components/ScreenStack.tsx

@@ -102,6 +102,9 @@ function ScreenStack(props: ScreenStackProps) {
           iosPreventReattachmentOfDismissedScreens={
             featureFlags.experiment.iosPreventReattachmentOfDismissedScreens
           }
+          iosPreventReattachmentOfDismissedModals={
+            featureFlags.experiment.iosPreventReattachmentOfDismissedModals
+          }
           /**
            * This messy override is to conform NativeProps used by codegen and
            * our Public API. To see reasoning go to this PR:

src/fabric/ScreenStackNativeComponent.ts

@@ -8,6 +8,7 @@ type FinishTransitioningEvent = Readonly<{}>;
 
 export interface NativeProps extends ViewProps {
   iosPreventReattachmentOfDismissedScreens?: CT.WithDefault<boolean, true>;
+  iosPreventReattachmentOfDismissedModals?: CT.WithDefault<boolean, true>;
 
   onFinishTransitioning?: CT.DirectEventHandler<FinishTransitioningEvent>;
 }