fix(iOS, Stack v4): Fix reattaching screens which have preventNativeDismiss set (#3886)

## Description

When a user triggers a native back gesture on iOS, UIKit automatically
removes the screen from its parent. For screens where
`preventNativeDismiss` is set to true, the screen might be reattached to
the hierarchy, what's causing state desynchronization between JS and
native, because natively we're filtering out this screen from
`viewControllers` that was introduced in:
#3584

Note: I intentionally added this check only to 'card' presentation. For
modals, `preventNativeDismiss` is fired before detaching the modal from
the hierarchy, so the issue with reattaching isn't reproducible.

Closes:
#3885

## Changes

- excluded screens that have `preventNativeDismiss` option set from our
solution for preventing reattaching screens that were removed from the
hierarchy

## Before & after - visual documentation

| Before | After |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/3571ff56-e3be-4ea1-ad60-f57974efa59f"
/> | <video
src="https://github.com/user-attachments/assets/79a79c29-504e-4657-bbf9-ff0e079a6490"
/> |

## Test plan

Added Test3885, performed regression testing on Test2559

## Checklist

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

Author: t0maboro

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

@@ -0,0 +1,87 @@
+import * as React from 'react';
+import { View, Text, StyleSheet, Alert, Pressable } from 'react-native';
+import {
+  NavigationContainer,
+  ParamListBase,
+  usePreventRemove,
+} from '@react-navigation/native';
+import {
+  createNativeStackNavigator,
+  NativeStackNavigationProp,
+} from '@react-navigation/native-stack';
+import Colors from '@apps/shared/styling/Colors';
+
+type NavigationProps = {
+  navigation: NativeStackNavigationProp<ParamListBase>;
+};
+
+function HomeScreen({ navigation }: NavigationProps) {
+  return (
+    <View style={styles.container}>
+      <Text>Home Screen</Text>
+
+      <Pressable onPress={() => navigation.navigate('Login')}>
+        <Text style={styles.linkText}>Go to Login</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+function LoginScreen({ navigation }: NavigationProps) {
+  const hasUnsavedChanges = true;
+
+  usePreventRemove(hasUnsavedChanges, ({ data }) => {
+    Alert.alert('Unsaved changes', 'Discard and exit?', [
+      { text: 'No', style: 'cancel' },
+      {
+        text: 'Yes',
+        style: 'destructive',
+        onPress: () => navigation.dispatch(data.action),
+      },
+    ]);
+  });
+
+  return (
+    <View style={styles.container}>
+      <Text>Login Screen</Text>
+      <Pressable onPress={() => navigation.goBack()}>
+        <Text style={styles.linkText}>Try to go back</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const Stack = createNativeStackNavigator();
+
+export default function App() {
+  return (
+    <NavigationContainer>
+      <Stack.Navigator>
+        <Stack.Screen
+          name="Home"
+          component={HomeScreen}
+          options={{ title: 'Home' }}
+        />
+        <Stack.Screen
+          name="Login"
+          component={LoginScreen}
+          options={{ title: 'Login' }}
+        />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 20,
+  },
+  linkText: {
+    color: Colors.BlueDark100,
+    fontSize: 16,
+    fontWeight: '600',
+  },
+});

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

@@ -190,6 +190,7 @@ export { default as Test3816 } from './Test3816';
 export { default as Test3833 } from './Test3833';
 export { default as Test3835 } from './Test3835';
 export { default as Test3867 } from './Test3867';
+export { default as Test3885 } from './Test3885';
 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/RNSScreenStack.mm

@@ -703,7 +703,15 @@ - (void)updateContainer
           /// quickly. Since view recycling is disabled, once we detect that a screen has been removed from the view
           /// hierarchy, it won't be reused. This allows us to safely filter out dismissed screens from screens coming
           /// from JS state via `controllers`.
-          if (_iosPreventReattachmentOfDismissedScreens && screen.controller.isRemovedFromParent) {
+          ///
+          /// Note: screens with `preventNativeDismiss` are intentionally excluded from this guard.
+          /// When `preventNativeDismiss` is set and the user triggers a native back gesture, UIKit removes
+          /// the screen from its parent. We then need to reattach it so that the `preventNativeDismiss`
+          /// callback fires correctly on the JS side. This breaks the general assumption that a screen
+          /// removed from the hierarchy will never be reattached.
+          /// See: https://github.com/software-mansion/react-native-screens/issues/3885
+          if (_iosPreventReattachmentOfDismissedScreens && screen.controller.isRemovedFromParent &&
+              !screen.preventNativeDismiss) {
             continue;
           }
           [pushControllers addObject:screen.controller];