Fix gesture relations after freeze (#4244)

## Description

#3763 fixed memory leak where gestures would keep stale references in
their relations array. However, this approach introduced a bug where
relations wouldn't be applied after freezing (like `freezeOnBlur` from
`react-native-screens`). This PR addresses this issue by fixing
incorrectly applied relations without re-introducing memory-leaks.

To do so, we create snapshot of relations at first render. It is later
used to prepare relations during next renders.

Fixes #4238

## Test plan

<details>
<summary>Tested on the following reproduction</summary>

```tsx
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import React from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';
import {
  Gesture,
  GestureDetector,
  GestureHandlerRootView,
} from 'react-native-gesture-handler';
import { enableFreeze } from 'react-native-screens';

enableFreeze(true);

type RootStackParamList = {
  Tabs: undefined;
};

type TabParamList = {
  TabOne: undefined;
  TabTwo: undefined;
  Leak: undefined;
};

const Stack = createNativeStackNavigator<RootStackParamList>();
const Tab = createBottomTabNavigator<TabParamList>();

function TabOneScreen() {
  const outerTap = Gesture.Tap().onStart(() => void console.log('outer tap'));
  const innerTap = Gesture.Tap()
    .onStart(() => void console.log('inner tap'))
    .simultaneousWithExternalGesture(outerTap);

  return (
    <View style={styles.screen1}>
      <GestureDetector gesture={outerTap}>
        <GestureDetector gesture={innerTap}>
          <View style={{ width: 100, height: 100, backgroundColor: 'red' }} />
        </GestureDetector>
      </GestureDetector>
    </View>
  );
}

// Demonstrates that when the composition's partner gesture changes across
// renders, the stable gesture's resolved relation follows the CURRENT partner
// and never accumulates the old one. `stableTap` is a single instance reused
// across renders (memoized); only the partner it is composed with changes.
function TabTwoScreen() {
  const [useB, switchPartner] = React.useReducer((value) => !value, false);

  const stableTap = React.useMemo(() => Gesture.Tap(), []);
  const partnerA = React.useMemo(
    () => Gesture.Tap().onStart(() => void console.log('▶ partner A')),
    []
  );
  const partnerB = React.useMemo(
    () => Gesture.Tap().onStart(() => void console.log('▶ partner B')),
    []
  );

  const activePartner = useB ? partnerB : partnerA;

  // Re-bind the log each render so it reports the partner that is active now.
  // We identify each stored relation by object identity (which partner gesture
  // it points at), because the GestureDetector recycles native handler slots by
  // position - so the numeric `tag` stays the same across a switch even though
  // the partner reference correctly changes from A to B. The key things to watch
  // are that `partner` follows the active one and the array length stays 1
  // (no stale accumulation).
  stableTap.onStart(() => {
    const resolved = (stableTap.config.simultaneousWith ?? []).map((ref) => ({
      partner: ref === partnerA ? 'A' : ref === partnerB ? 'B' : '?',
      tag: (ref as { handlerTag?: number }).handlerTag,
    }));
    console.log(
      `▶ stable tap | active=${useB ? 'B' : 'A'} resolved=${JSON.stringify(
        resolved
      )}`
    );
  });

  // Recreated every render because it depends on state — this is exactly the
  // case where the partner array passed into the composition changes.
  const composed = Gesture.Simultaneous(stableTap, activePartner);

  return (
    <View style={styles.screen2}>
      <GestureDetector gesture={composed}>
        <View style={styles.box}>
          <Text style={styles.boxLabel}>Tap me</Text>
          <Text style={styles.boxLabel}>partner: {useB ? 'B' : 'A'}</Text>
        </View>
      </GestureDetector>
      <Pressable onPress={switchPartner} style={styles.button}>
        <Text style={styles.buttonLabel}>Switch partner</Text>
      </Pressable>
    </View>
  );
}

// Reproduces the scenario from the #3763 memory-leak fix: a stable (memoized)
// gesture composed with a gesture that is recreated on every render and captures
// a large allocation. If relations accumulated, `stable.config.simultaneousWith`
// would grow by one on every render and pin every transient gesture (and its
// `bigMemory`) in memory forever. With the fix it stays at exactly 1, so each
// previous transient gesture becomes collectible.
function LeakScreen() {
  const [renders, rerender] = React.useReducer((value) => value + 1, 0);

  // Stable instance — survives every render. This is the gesture that used to
  // accumulate references to each render's transient partner.
  const stable = React.useMemo(() => Gesture.Pan(), []);

  // Fresh big allocation + fresh transient gesture on every render. The gesture
  // captures `bigMemory`, so anything retaining the gesture also retains it.
  const bigMemory = new Array(500_000).fill(renders);
  const transient = Gesture.Pan().onStart(() => void bigMemory.length);

  const composed = Gesture.Simultaneous(stable, transient);

  // Direct proxy for the leak: how many partner references `stable` is holding.
  // Stays 1 with the fix; grew by one per render before it.
  const relationsHeld = stable.config.simultaneousWith?.length ?? 0;
  console.log(`leak check | renders=${renders} relationsHeld=${relationsHeld}`);

  // Drives many *separate* renders (and therefore many prepares) so the count
  // is easy to watch. Plain dispatch-in-a-loop would be batched into one render.
  const stress = React.useCallback(() => {
    let count = 0;
    const id = setInterval(() => {
      rerender();
      count += 1;
      if (count >= 100) {
        clearInterval(id);
      }
    }, 16);
  }, []);

  return (
    <View style={styles.screen2}>
      <GestureDetector gesture={composed}>
        <View style={styles.box}>
          <Text style={styles.boxLabel}>renders: {renders}</Text>
          <Text style={styles.boxLabel}>relations held: {relationsHeld}</Text>
        </View>
      </GestureDetector>
      <Pressable onPress={rerender} style={styles.button}>
        <Text style={styles.buttonLabel}>Re-render once</Text>
      </Pressable>
      <Pressable onPress={stress} style={styles.button}>
        <Text style={styles.buttonLabel}>Re-render x100</Text>
      </Pressable>
    </View>
  );
}

function TabsScreen() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="TabOne" component={TabOneScreen} />
      <Tab.Screen name="TabTwo" component={TabTwoScreen} />
      <Tab.Screen name="Leak" component={LeakScreen} />
    </Tab.Navigator>
  );
}

const App = () => {
  return (
    <GestureHandlerRootView style={styles.root}>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen
            name="Tabs"
            component={TabsScreen}
            options={{ headerShown: false }}
          />
        </Stack.Navigator>
      </NavigationContainer>
    </GestureHandlerRootView>
  );
};

export default App;

const styles = StyleSheet.create({
  root: {
    flex: 1,
  },
  screen1: {
    flex: 1,
    backgroundColor: '#f9f',
  },
  screen2: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    gap: 12,
  },
  box: {
    width: 200,
    height: 200,
    backgroundColor: 'red',
    alignItems: 'center',
    justifyContent: 'center',
    gap: 8,
    borderRadius: 12,
  },
  boxLabel: {
    color: 'white',
    fontWeight: '600',
  },
  button: {
    paddingVertical: 12,
    paddingHorizontal: 20,
    backgroundColor: '#333',
    borderRadius: 8,
  },
  buttonLabel: {
    color: 'white',
    fontWeight: '600',
  },
});
```

</details>

Author: m-bert

packages/react-native-gesture-handler/src/handlers/gestures/GestureDetector/utils.ts

@@ -65,20 +65,16 @@ function extractValidHandlerTags(interactionGroup: GestureRef[] | undefined) {
 }
 
 export function extractGestureRelations(gesture: GestureType) {
-  gesture.config.requireToFail = extractValidHandlerTags(
-    gesture.config.requireToFail
-  );
-  gesture.config.simultaneousWith = extractValidHandlerTags(
+  const requireToFail = extractValidHandlerTags(gesture.config.requireToFail);
+  const simultaneousWith = extractValidHandlerTags(
     gesture.config.simultaneousWith
   );
-  gesture.config.blocksHandlers = extractValidHandlerTags(
-    gesture.config.blocksHandlers
-  );
+  const blocksHandlers = extractValidHandlerTags(gesture.config.blocksHandlers);
 
   return {
-    waitFor: gesture.config.requireToFail,
-    simultaneousHandlers: gesture.config.simultaneousWith,
-    blocksHandlers: gesture.config.blocksHandlers,
+    waitFor: requireToFail,
+    simultaneousHandlers: simultaneousWith,
+    blocksHandlers: blocksHandlers,
   };
 }
 

packages/react-native-gesture-handler/src/handlers/gestures/gesture.ts

@@ -137,6 +137,17 @@ export abstract class BaseGesture<
   public handlerTag = -1;
   public handlerName = '';
   public config: BaseGestureConfig = {};
+  // Snapshot of the relations defined directly on this gesture (e.g. via
+  // `simultaneousWithExternalGesture`), captured before any composition extends
+  // them. Composition rebuilds the relation config from this snapshot on every
+  // `prepare`, so repeated renders don't accumulate references to gestures from
+  // previous renders (memory leak, see #3763), while keeping the original
+  // references so relations stay re-resolvable after a remount, such as a
+  // `react-freeze` unfreeze (see #4238).
+  public relationsSnapshot?: {
+    simultaneousWith: GestureRef[] | undefined;
+    requireToFail: GestureRef[] | undefined;
+  };
   public handlers: HandlerCallbacks<EventPayloadT> = {
     gestureId: -1,
     handlerTag: -1,

packages/react-native-gesture-handler/src/handlers/gestures/gestureComposition.ts

@@ -31,16 +31,29 @@ export class ComposedGesture extends Gesture {
     requireGesturesToFail: GestureType[]
   ) {
     if (gesture instanceof BaseGesture) {
+      // Capture the relations defined directly on the gesture before composition
+      // extends them, then always rebuild from that snapshot. Otherwise, when the
+      // gesture is stable (e.g. wrapped in `useMemo`) but the composition is
+      // recreated on every render, the relations would keep accumulating
+      // references to gestures from previous renders, leaking memory (see #3763).
+      // We keep the original references (instead of collapsing them to handler
+      // tags) so relations can still be re-resolved after a remount, such as a
+      // `react-freeze` unfreeze (see #4238).
+      gesture.relationsSnapshot ??= {
+        simultaneousWith: gesture.config.simultaneousWith,
+        requireToFail: gesture.config.requireToFail,
+      };
+
       const newConfig = { ...gesture.config };
 
       // No need to extend `blocksHandlers` here, because it's not changed in composition.
       // The same effect is achieved by reversing the order of 2 gestures in `Exclusive`
       newConfig.simultaneousWith = extendRelation(
-        newConfig.simultaneousWith,
+        gesture.relationsSnapshot.simultaneousWith,
         simultaneousGestures
       );
       newConfig.requireToFail = extendRelation(
-        newConfig.requireToFail,
+        gesture.relationsSnapshot.requireToFail,
         requireGesturesToFail
       );