Ensure no gesture is used across multiple detectors (#4285)

## Description

Currently there's no error when the same gesture is used in multiple
detectors. This may results in a bug, e.g. on Android and iOS only last
detector captures gestures, on web all of them. This PR adds JS side
check whether instance of a gesture was passed into more than one
detector.

> [!NOTE]
> The example below crashes on web, in reattaching scenario. However,
this seems to be unrelated to this PR, so I left that for a follow-up.

## Test plan

<details>
<summary>Tested on the following code:</summary>

```tsx
import { useRef, useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';
import { GestureDetector, useTapGesture } from 'react-native-gesture-handler';

import type { FeedbackHandle } from '../../../common';
import { COLORS, commonStyles, Feedback } from '../../../common';

type Mode = 'separate' | 'reattach' | 'shared';

// Demonstrates the guard that forbids attaching a single gesture instance to
// more than one GestureDetector at a time.
//
// - "Separate gestures (OK)"     -> each detector gets its own gesture.
// - "Reattach mode (OK)"         -> tapping the ⭐ box moves the SAME gesture to
//                                   the other detector. The detector losing it
//                                   releases it before the other claims it, so
//                                   it never throws. The ⭐ badge and its tap
//                                   counter travel with the instance, so you can
//                                   see it is literally the same gesture moving.
// - "Share one gesture (throws)" -> the SAME gesture is rendered in BOTH
//                                   detectors at once. This is the misuse we
//                                   catch - it throws on the second detector.
export default function SharedGestureExample() {
  const [mode, setMode] = useState<Mode>('separate');
  // In reattach mode, which detector currently holds the shared gesture.
  const [sharedOnTop, setSharedOnTop] = useState(true);
  // Tap count of the shared gesture - kept in a ref so incrementing it does not
  // trigger a second state update (the setSharedOnTop re-render reads it fresh).
  const sharedTapsRef = useRef(0);
  const feedbackRef = useRef<FeedbackHandle>(null);

  const sharedGesture = useTapGesture({
    onActivate: () => {
      sharedTapsRef.current += 1;
      // Tapping the box that holds the shared gesture moves (reattaches) it to
      // the other detector - exactly one detector ever holds it, so no throw.
      setSharedOnTop((prev) => !prev);
      feedbackRef.current?.showMessage('⭐ shared gesture tapped → moving');
    },
    runOnJS: true,
  });

  const topOwnGesture = useTapGesture({
    onActivate: () => feedbackRef.current?.showMessage('top gesture tapped'),
    runOnJS: true,
  });

  const bottomOwnGesture = useTapGesture({
    onActivate: () => feedbackRef.current?.showMessage('bottom gesture tapped'),
    runOnJS: true,
  });

  // Single placeholder used by whichever box does NOT currently hold the shared
  // gesture in reattach mode (mirrors the existing `reattaching` example).
  const placeholderGesture = useTapGesture({
    onActivate: () => feedbackRef.current?.showMessage('inert box tapped'),
    runOnJS: true,
  });

  // Decide which gesture each detector receives, and whether it's the shared one.
  let topGesture = topOwnGesture;
  let bottomGesture = bottomOwnGesture;
  let topHasShared = false;
  let bottomHasShared = false;

  if (mode === 'shared') {
    // Same instance in both detectors at the same time -> throws.
    topGesture = sharedGesture;
    bottomGesture = sharedGesture;
    topHasShared = true;
    bottomHasShared = true;
  } else if (mode === 'reattach') {
    // Exactly one detector holds the shared gesture at any moment -> allowed.
    topGesture = sharedOnTop ? sharedGesture : placeholderGesture;
    bottomGesture = sharedOnTop ? placeholderGesture : sharedGesture;
    topHasShared = sharedOnTop;
    bottomHasShared = !sharedOnTop;
  }

  return (
    <View style={commonStyles.centerView}>
      <View style={styles.controls}>
        <Button
          label="Separate gestures (OK)"
          onPress={() => setMode('separate')}
        />
        <Button
          label="Reattach mode (OK)"
          onPress={() => {
            setMode('reattach');
            setSharedOnTop(true);
          }}
        />
        <Button
          label="Share one gesture (throws)"
          danger
          onPress={() => setMode('shared')}
        />
      </View>

      <Text style={styles.status}>
        mode: {mode}
        {mode === 'reattach'
          ? ` · tap the ⭐ box to move the shared gesture`
          : ''}
      </Text>

      <GestureDetector gesture={topGesture}>
        <Box
          title="Top"
          color={COLORS.NAVY}
          hasShared={topHasShared}
          sharedTaps={sharedTapsRef.current}
        />
      </GestureDetector>

      <GestureDetector gesture={bottomGesture}>
        <Box
          title="Bottom"
          color={COLORS.GREEN}
          hasShared={bottomHasShared}
          sharedTaps={sharedTapsRef.current}
        />
      </GestureDetector>

      <Feedback ref={feedbackRef} />
    </View>
  );
}

function Box({
  title,
  color,
  hasShared,
  sharedTaps,
}: {
  title: string;
  color: string;
  hasShared: boolean;
  sharedTaps: number;
}) {
  return (
    <View
      style={[
        commonStyles.box,
        { backgroundColor: color },
        hasShared && styles.boxWithShared,
      ]}>
      <Text style={styles.boxText}>{title}</Text>
      {hasShared ? (
        <Text style={styles.badge}>
          ⭐ shared{'\n'}
          {sharedTaps} taps
        </Text>
      ) : (
        <Text style={styles.boxSubText}>own gesture</Text>
      )}
    </View>
  );
}

function Button({
  label,
  onPress,
  danger,
}: {
  label: string;
  onPress: () => void;
  danger?: boolean;
}) {
  return (
    <Pressable
      onPress={onPress}
      style={[styles.button, danger && styles.buttonDanger]}>
      <Text style={styles.buttonText}>{label}</Text>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  controls: {
    gap: 8,
    marginBottom: 24,
    width: '100%',
    paddingHorizontal: 16,
  },
  button: {
    backgroundColor: COLORS.NAVY,
    paddingVertical: 12,
    borderRadius: 10,
    alignItems: 'center',
  },
  buttonDanger: {
    backgroundColor: COLORS.RED,
  },
  buttonText: {
    color: 'white',
    fontWeight: '600',
  },
  status: {
    marginBottom: 16,
    color: COLORS.NAVY,
    fontWeight: '600',
  },
  boxWithShared: {
    borderWidth: 4,
    borderColor: COLORS.KINDA_YELLOW,
  },
  boxText: {
    color: 'white',
    fontWeight: '700',
    fontSize: 18,
  },
  boxSubText: {
    color: 'white',
    opacity: 0.8,
    marginTop: 4,
  },
  badge: {
    color: COLORS.KINDA_YELLOW,
    fontWeight: '700',
    textAlign: 'center',
    marginTop: 4,
  },
});
```

</details>

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

packages/react-native-gesture-handler/src/__tests__/Errors.test.tsx

@@ -83,6 +83,94 @@ describe('VirtualDetector', () => {
   });
 });
 
+describe('Sharing a gesture across detectors', () => {
+  beforeEach(() => (findNodeHandle as jest.Mock).mockReturnValue(123));
+
+  test('throws when the same gesture is attached to two detectors', () => {
+    function SameGestureTwoDetectors() {
+      const tap = useTapGesture({});
+      return (
+        <GestureHandlerRootView>
+          <GestureDetector gesture={tap}>
+            <View />
+          </GestureDetector>
+          <GestureDetector gesture={tap}>
+            <View />
+          </GestureDetector>
+        </GestureHandlerRootView>
+      );
+    }
+
+    expect(() => render(<SameGestureTwoDetectors />)).toThrow(
+      'Using the same gesture instance across multiple GestureDetectors is not possible. Create a separate gesture for each detector.'
+    );
+  });
+
+  test('does not throw when the same gesture is reattached to another detector', () => {
+    // Changing the key unmounts the previous detector and mounts a new one with
+    // the same gesture - the old detector must release the gesture before the
+    // new one claims it.
+    function ReattachedGesture({ detectorKey }: { detectorKey: string }) {
+      const tap = useTapGesture({});
+      return (
+        <GestureHandlerRootView>
+          <GestureDetector key={detectorKey} gesture={tap}>
+            <View />
+          </GestureDetector>
+        </GestureHandlerRootView>
+      );
+    }
+
+    const { rerender } = render(<ReattachedGesture detectorKey="a" />);
+    expect(() => rerender(<ReattachedGesture detectorKey="b" />)).not.toThrow();
+  });
+
+  test('does not throw when gestures are swapped between two mounted detectors', () => {
+    // Prop-swap reattach: both detectors stay mounted and the two gestures
+    // trade places. The detector losing a gesture must release it (effect
+    // cleanup) before the detector gaining it claims it (effect setup).
+    function SwappedGestures({ swapped }: { swapped: boolean }) {
+      const tapA = useTapGesture({});
+      const tapB = useTapGesture({});
+      return (
+        <GestureHandlerRootView>
+          <GestureDetector gesture={swapped ? tapB : tapA}>
+            <View />
+          </GestureDetector>
+          <GestureDetector gesture={swapped ? tapA : tapB}>
+            <View />
+          </GestureDetector>
+        </GestureHandlerRootView>
+      );
+    }
+
+    const { rerender } = render(<SwappedGestures swapped={false} />);
+    expect(() => rerender(<SwappedGestures swapped />)).not.toThrow();
+  });
+
+  test('throws when the same gesture is attached to two virtual detectors', () => {
+    function SameGestureTwoVirtualDetectors() {
+      const tap = useTapGesture({});
+      return (
+        <GestureHandlerRootView>
+          <InterceptingGestureDetector>
+            <VirtualDetector gesture={tap}>
+              <View />
+            </VirtualDetector>
+            <VirtualDetector gesture={tap}>
+              <View />
+            </VirtualDetector>
+          </InterceptingGestureDetector>
+        </GestureHandlerRootView>
+      );
+    }
+
+    expect(() => render(<SameGestureTwoVirtualDetectors />)).toThrow(
+      'Using the same gesture instance across multiple GestureDetectors is not possible. Create a separate gesture for each detector.'
+    );
+  });
+});
+
 describe('Check if descendant of root view', () => {
   test('gesture detector', () => {
     function GestureDetectorNoRootView() {

packages/react-native-gesture-handler/src/v3/detectors/NativeDetector.tsx

@@ -7,6 +7,7 @@ import type { NativeDetectorProps } from './common';
 import { AnimatedNativeDetector, nativeDetectorStyles } from './common';
 import HostGestureDetector from './HostGestureDetector';
 import { ReanimatedNativeDetector } from './ReanimatedNativeDetector';
+import { useDetectorAttachmentGuard } from './useDetectorAttachmentGuard';
 import { useGestureRelationsUpdater } from './useGestureRelationsUpdater';
 import { ensureNativeDetectorComponent } from './utils';
 
@@ -38,6 +39,8 @@ export function NativeDetector<
       : [gesture.handlerTag];
   }, [gesture]);
 
+  useDetectorAttachmentGuard(handlerTags);
+
   // On web, we're triggering Reanimated callbacks ourselves, based on the type.
   // To handle this properly, we need to provide all three callbacks, so we set
   // all three to the Reanimated event handler.

packages/react-native-gesture-handler/src/v3/detectors/VirtualDetector/InterceptingGestureDetector.tsx

@@ -17,6 +17,7 @@ import type { InterceptingGestureDetectorProps } from '../common';
 import { AnimatedNativeDetector, nativeDetectorStyles } from '../common';
 import HostGestureDetector from '../HostGestureDetector';
 import { ReanimatedNativeDetector } from '../ReanimatedNativeDetector';
+import { useDetectorAttachmentGuard } from '../useDetectorAttachmentGuard';
 import { useEnsureGestureHandlerRootView } from '../useEnsureGestureHandlerRootView';
 import { useGestureRelationsUpdater } from '../useGestureRelationsUpdater';
 import { ensureNativeDetectorComponent } from '../utils';
@@ -233,6 +234,8 @@ export function InterceptingGestureDetector<
     return [];
   }, [gesture]);
 
+  useDetectorAttachmentGuard(handlerTags);
+
   // On web, we're triggering Reanimated callbacks ourselves, based on the type.
   // To handle this properly, we need to provide all three callbacks, so we set
   // all three to the Reanimated event handler.

packages/react-native-gesture-handler/src/v3/detectors/VirtualDetector/VirtualDetector.tsx

@@ -1,11 +1,12 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { findNodeHandle, Platform } from 'react-native';
 
 import { Wrap } from '../../../handlers/gestures/GestureDetector/Wrap';
 import { tagMessage } from '../../../utils';
 import { isComposedGesture } from '../../hooks/utils/relationUtils';
 import type { DetectorCallbacks, VirtualChild } from '../../types';
 import type { VirtualDetectorProps } from '../common';
+import { useDetectorAttachmentGuard } from '../useDetectorAttachmentGuard';
 import { useGestureRelationsUpdater } from '../useGestureRelationsUpdater';
 import { useNativeGestureRole } from '../useNativeGestureRole';
 import {
@@ -57,15 +58,21 @@ export function VirtualDetector<
 
   useNativeGestureRole(viewRef, props.children);
 
+  const handlerTags = useMemo(
+    () =>
+      isComposedGesture(props.gesture)
+        ? props.gesture.handlerTags
+        : [props.gesture.handlerTag],
+    [props.gesture]
+  );
+
+  useDetectorAttachmentGuard(handlerTags);
+
   useEffect(() => {
     if (viewTag === -1) {
       return;
     }
 
-    const handlerTags = isComposedGesture(props.gesture)
-      ? props.gesture.handlerTags
-      : [props.gesture.handlerTag];
-
     if (props.gesture.config.dispatchesAnimatedEvents) {
       throw new Error(
         tagMessage(
@@ -96,6 +103,7 @@ export function VirtualDetector<
   }, [
     viewTag,
     props.gesture,
+    handlerTags,
     props.userSelect,
     props.touchAction,
     props.enableContextMenu,

packages/react-native-gesture-handler/src/v3/detectors/useDetectorAttachmentGuard.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef } from 'react';
+
+import { tagMessage } from '../../utils';
+
+// Maps a gesture's handlerTag to the id of the detector currently rendering it.
+// Ownership is claimed in an effect and released in its cleanup (on unmount or
+// when handlerTags change), so moving a gesture instance between detectors works
+// as long as it isn't rendered by more than one detector at the same time.
+const detectorByHandlerTag = new Map<number, number>();
+
+let nextDetectorId = 0;
+
+export function useDetectorAttachmentGuard(handlerTags: number[]) {
+  if (!__DEV__) {
+    return;
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const detectorId = useRef(-1);
+
+  if (detectorId.current === -1) {
+    detectorId.current = nextDetectorId++;
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  useEffect(() => {
+    const id = detectorId.current;
+
+    for (const tag of handlerTags) {
+      const owner = detectorByHandlerTag.get(tag);
+
+      if (owner !== undefined && owner !== id) {
+        throw new Error(
+          tagMessage(
+            'Using the same gesture instance across multiple GestureDetectors is not possible. Create a separate gesture for each detector.'
+          )
+        );
+      }
+    }
+
+    for (const tag of handlerTags) {
+      detectorByHandlerTag.set(tag, id);
+    }
+
+    return () => {
+      for (const tag of handlerTags) {
+        if (detectorByHandlerTag.get(tag) === id) {
+          detectorByHandlerTag.delete(tag);
+        }
+      }
+    };
+  }, [handlerTags]);
+}