[General] Link late-mounted gesture objects and skip mount reactions without external relations (#4562)

## Description

Follow-up to #4546.

A relation that holds a gesture object
(`simultaneousWithExternalGesture(gesture)`) to a gesture mounted by a
different detector in a later commit never links on native. When the
outer detector attaches, the object still has tag -1, and the mount
listener only matches ref entries, so nothing re-sends the config once
the object gets its tag. The relation stays dead until the outer
detector happens to re-render, which hides the problem.

The listener now also matches gesture objects by identity: the mount
event carries the very object stored in the relation. Composition fills
relations with sibling gesture objects, so without a guard every
composed detector would update itself on mount. The listener skips
mounts of the detector's own gestures, which requires assigning
`attachedGestures` before the mount events fire in `attachHandlers`.

Most detectors have nothing that can resolve late, yet every one of them
still walks its relations on every mount of every other gesture.
`AttachedGestureState` gets a `hasExternalRelations` flag, computed in
the attach and update microtasks. It is true only when some relation
entry is a ref or a gesture object owned by another detector; numeric
tags and composition siblings never resolve late. Detectors with the
flag unset return from the listener immediately. On a screen with 300
`LegacyPressable`s, mounting 50 more spent 38 ms in mount listeners
before and 5.5 ms after.

## Test plan

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

```tsx
import React, {
  useLayoutEffect,
  useRef,
  useState,
  useSyncExternalStore,
} from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import type { GestureType } from 'react-native-gesture-handler';
import {
  Gesture,
  GestureDetector,
  LegacyPressable,
} from 'react-native-gesture-handler';

// #4540 follow-up demo (v2 detector only, v3 has no MountRegistry).
//
// Late relations: the OUTER pan declares `simultaneousWithExternalGesture` to
// an INNER pan whose detector mounts later (toggle). Without the link the inner
// (deeper) pan wins and the outer counter never moves; with it both update.
//   Row 1: relation holds the inner Gesture OBJECT (fixed by the follow-up).
//   Row 2: relation holds a REF filled by `withRef` (fixed by PR #4546).
//
// Perf: N composed background detectors (LegacyPressable = Simultaneous of 3)
// plus "mount 50 more", timing the commit of the newly mounted batch.

// Tiny external store so the outer detectors never re-render: a v2 detector
// re-sends its config on every re-render, which would repair the relation in
// the same commit the inner gesture mounts and hide the bug.
type Counters = {
  outerObj: number;
  innerObj: number;
  outerRef: number;
  innerRef: number;
};
const store = {
  mounted: false,
  counters: {
    outerObj: 0,
    innerObj: 0,
    outerRef: 0,
    innerRef: 0,
  } as Counters,
  listeners: new Set<() => void>(),
  subscribe: (listener: () => void) => {
    store.listeners.add(listener);
    return () => store.listeners.delete(listener);
  },
  emit: () => {
    store.listeners.forEach((l) => l());
  },
  toggle: () => {
    store.mounted = !store.mounted;
    store.emit();
  },
  bump: (key: keyof Counters) => {
    store.counters = { ...store.counters, [key]: store.counters[key] + 1 };
    store.emit();
  },
};

// Row 1: gesture object relation.
const innerPanObj = Gesture.Pan()
  .runOnJS(true)
  .onUpdate(() => store.bump('innerObj'));
const outerPanObj = Gesture.Pan()
  .runOnJS(true)
  .simultaneousWithExternalGesture(innerPanObj)
  .onUpdate(() => store.bump('outerObj'));

// Row 2: ref relation.
const innerRefHolder: React.MutableRefObject<GestureType | undefined> = {
  current: undefined,
};
const innerPanRef = Gesture.Pan()
  .runOnJS(true)
  .withRef(innerRefHolder)
  .onUpdate(() => store.bump('innerRef'));
const outerPanRef = Gesture.Pan()
  .runOnJS(true)
  .simultaneousWithExternalGesture(innerRefHolder)
  .onUpdate(() => store.bump('outerRef'));

function InnerSlot({ inner }: { inner: GestureType }) {
  const mounted = useSyncExternalStore(store.subscribe, () => store.mounted);

  return mounted ? (
    <GestureDetector gesture={inner}>
      <View style={styles.inner} />
    </GestureDetector>
  ) : (
    <View style={[styles.inner, styles.innerPlaceholder]} />
  );
}

function CounterLabel({
  prefix,
  outerKey,
  innerKey,
}: {
  prefix: string;
  outerKey: keyof Counters;
  innerKey: keyof Counters;
}) {
  const counters = useSyncExternalStore(store.subscribe, () => store.counters);

  return (
    <Text style={styles.label}>
      {`${prefix}  outer ${counters[outerKey]} / inner ${counters[innerKey]}`}
    </Text>
  );
}

function ToggleButton() {
  const mounted = useSyncExternalStore(store.subscribe, () => store.mounted);

  return (
    <Button
      title={mounted ? 'Unmount inner pans' : 'Mount inner pans'}
      onPress={store.toggle}
      testID="toggleInner"
    />
  );
}

function LateRelations() {
  return (
    <View style={styles.section}>
      <ToggleButton />
      <View style={styles.row}>
        <CounterLabel prefix="object" outerKey="outerObj" innerKey="innerObj" />
        <GestureDetector gesture={outerPanObj}>
          <View style={styles.outer}>
            <InnerSlot inner={innerPanObj} />
          </View>
        </GestureDetector>
      </View>
      <View style={styles.row}>
        <CounterLabel prefix="ref   " outerKey="outerRef" innerKey="innerRef" />
        <GestureDetector gesture={outerPanRef}>
          <View style={styles.outer}>
            <InnerSlot inner={innerPanRef} />
          </View>
        </GestureDetector>
      </View>
      <Text style={styles.hint}>
        Pan the dark inner box. Both counters move only when the outer pan is
        linked to the inner one.
      </Text>
    </View>
  );
}

const BACKGROUND = 300;
const BATCH = 50;

function Batch({ onCommit }: { onCommit: () => void }) {
  useLayoutEffect(onCommit, [onCommit]);
  return (
    <View style={styles.grid}>
      {Array.from({ length: BATCH }, (_, i) => (
        <LegacyPressable key={i} style={styles.cell} />
      ))}
    </View>
  );
}

function MountPerf() {
  const [batches, setBatches] = useState(0);
  const [lastMs, setLastMs] = useState<number | null>(null);
  const start = useRef(0);

  const onCommit = () => {
    if (start.current !== 0) {
      setLastMs(Math.round(performance.now() - start.current));
      start.current = 0;
    }
  };

  return (
    <View style={styles.section}>
      <Button
        title={`Mount ${BATCH} more (${batches} batches)`}
        onPress={() => {
          start.current = performance.now();
          setBatches((b) => b + 1);
        }}
        testID="mountBatch"
      />
      <Text style={styles.label}>
        {BACKGROUND} background composed detectors, last batch:{' '}
        {lastMs === null ? '-' : `${lastMs} ms`}
      </Text>
      <View style={styles.grid}>
        {Array.from({ length: BACKGROUND }, (_, i) => (
          <LegacyPressable key={i} style={styles.cell} />
        ))}
      </View>
      {Array.from({ length: batches }, (_, i) => (
        <Batch key={i} onCommit={onCommit} />
      ))}
    </View>
  );
}

export default function EmptyExample() {
  return (
    <View style={styles.container}>
      <LateRelations />
      <MountPerf />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16, gap: 24 },
  section: { gap: 8 },
  row: { flexDirection: 'row', alignItems: 'center', gap: 12 },
  label: { fontVariant: ['tabular-nums'], width: 180 },
  hint: { opacity: 0.6, fontSize: 12 },
  outer: {
    width: 120,
    height: 80,
    backgroundColor: '#b7d1ff',
    alignItems: 'center',
    justifyContent: 'center',
  },
  inner: { width: 70, height: 50, backgroundColor: '#1e3a8a' },
  innerPlaceholder: { backgroundColor: 'transparent', borderWidth: 1 },
  grid: { flexDirection: 'row', flexWrap: 'wrap' },
  cell: { width: 6, height: 6, margin: 1, backgroundColor: '#ddd' },
});
```

</details>

Author: m-bert

packages/react-native-gesture-handler/src/__tests__/useMountReactions.test.ts

@@ -1,8 +1,11 @@
 import { renderHook } from '@testing-library/react-native';
 import type { Platform as PlatformModule } from 'react-native';
 
+import type { GestureType } from '../handlers/gestures/gesture';
+import { BaseGesture } from '../handlers/gestures/gesture';
 import type { AttachedGestureState } from '../handlers/gestures/GestureDetector/types';
 import { useMountReactions } from '../handlers/gestures/GestureDetector/useMountReactions';
+import { hasExternalRelations } from '../handlers/gestures/GestureDetector/utils';
 import { MountRegistry } from '../mountRegistry';
 
 // The relation scan used to resolve entries through `transformIntoHandlerTags`,
@@ -36,13 +39,21 @@ const stateWithRelation = (
     animatedHandlers: null,
     shouldUseReanimated: false,
     isMounted: true,
+    hasExternalRelations: true,
   }) as unknown as AttachedGestureState;
 
 const mount = (handlerTag: number) =>
   MountRegistry.gestureHandlerWillMount({
     handlerTag,
   } as unknown as React.Component);
 
+const gestureObject = (handlerTag: number, config: object = {}) => {
+  const gesture = Object.create(BaseGesture.prototype) as GestureType;
+  gesture.handlerTag = handlerTag;
+  gesture.config = config as GestureType['config'];
+  return gesture;
+};
+
 describe('useMountReactions', () => {
   const relationKeys: RelationKey[] = [
     'blocksHandlers',
@@ -97,14 +108,12 @@ describe('useMountReactions', () => {
     unmount();
   });
 
-  test('ignores entries that already carried their tag when the detector attached', () => {
+  test('ignores raw tags, which cannot change after the detector attached', () => {
     const updateDetector = jest.fn();
-    // A gesture object and a raw tag are both resolved by the time the detector
-    // attaches, so mounting cannot change what they point at.
     const { unmount } = renderHook(() =>
       useMountReactions(
         updateDetector,
-        stateWithRelation('simultaneousWith', [{ handlerTag: 42 }, 42])
+        stateWithRelation('simultaneousWith', [42])
       )
     );
 
@@ -114,6 +123,77 @@ describe('useMountReactions', () => {
     unmount();
   });
 
+  test('updates the detector when a gesture object in a relation mounts later', () => {
+    const updateDetector = jest.fn();
+    // The object had no tag when this detector attached; its own detector
+    // assigns one in `initialize` and then fires the mount event with it.
+    const external = gestureObject(-1);
+    const { unmount } = renderHook(() =>
+      useMountReactions(
+        updateDetector,
+        stateWithRelation('simultaneousWith', [external])
+      )
+    );
+
+    external.handlerTag = 42;
+    MountRegistry.gestureWillMount(external);
+
+    expect(updateDetector).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  test('does not match a different gesture object with the same tag', () => {
+    const updateDetector = jest.fn();
+    const { unmount } = renderHook(() =>
+      useMountReactions(
+        updateDetector,
+        stateWithRelation('simultaneousWith', [gestureObject(42)])
+      )
+    );
+
+    MountRegistry.gestureWillMount(gestureObject(42));
+
+    expect(updateDetector).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  test('skips the mount of its own gestures', () => {
+    const updateDetector = jest.fn();
+    // Composition fills relations with sibling gestures, so without the guard
+    // every composed detector would update itself on mount.
+    const first = gestureObject(1);
+    const second = gestureObject(2);
+    first.config = { simultaneousWith: [second] } as GestureType['config'];
+    second.config = { simultaneousWith: [first] } as GestureType['config'];
+    const state = stateWithRelation('simultaneousWith', []);
+    state.attachedGestures = [first, second];
+    const { unmount } = renderHook(() =>
+      useMountReactions(updateDetector, state)
+    );
+
+    MountRegistry.gestureWillMount(first);
+    MountRegistry.gestureWillMount(second);
+
+    expect(updateDetector).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  test('skips the scan when the detector has no external relations', () => {
+    const updateDetector = jest.fn();
+    const state = stateWithRelation('simultaneousWith', [
+      { current: { handlerTag: 42 } },
+    ]);
+    state.hasExternalRelations = false;
+    const { unmount } = renderHook(() =>
+      useMountReactions(updateDetector, state)
+    );
+
+    mount(42);
+
+    expect(updateDetector).not.toHaveBeenCalled();
+    unmount();
+  });
+
   test('does not update a detector that is already unmounted', () => {
     const updateDetector = jest.fn();
     const state = stateWithRelation('simultaneousWith', [
@@ -130,3 +210,37 @@ describe('useMountReactions', () => {
     unmount();
   });
 });
+
+describe('hasExternalRelations', () => {
+  test('is false without relations or with raw tags only', () => {
+    expect(hasExternalRelations([gestureObject(1)])).toBe(false);
+    expect(
+      hasExternalRelations([gestureObject(1, { requireToFail: [7] })])
+    ).toBe(false);
+  });
+
+  test('is false when relations only point at sibling gestures', () => {
+    const first = gestureObject(1);
+    const second = gestureObject(2);
+    first.config = { simultaneousWith: [second] } as GestureType['config'];
+    second.config = { simultaneousWith: [first] } as GestureType['config'];
+
+    expect(hasExternalRelations([first, second])).toBe(false);
+  });
+
+  test('is true for a ref', () => {
+    expect(
+      hasExternalRelations([
+        gestureObject(1, { blocksHandlers: [{ current: null }] }),
+      ])
+    ).toBe(true);
+  });
+
+  test('is true for a gesture object attached by another detector', () => {
+    expect(
+      hasExternalRelations([
+        gestureObject(1, { simultaneousWith: [gestureObject(2)] }),
+      ])
+    ).toBe(true);
+  });
+});

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

@@ -16,6 +16,7 @@ import {
   ALLOWED_PROPS,
   checkGestureCallbacksForWorklets,
   extractGestureRelations,
+  hasExternalRelations,
 } from './utils';
 
 interface AttachHandlersConfig {
@@ -55,6 +56,9 @@ export function attachHandlers({
     registerHandler(handler.handlerTag, handler, handler.config.testId);
   }
 
+  // React to every mount until the microtask below classifies the new gesture set
+  preparedGesture.hasExternalRelations = true;
+
   // Use queueMicrotask to extract handlerTags, because all refs should be initialized
   // when it's ran
   ghQueueMicrotask(() => {
@@ -73,9 +77,16 @@ export function attachHandlers({
       );
     }
 
+    preparedGesture.hasExternalRelations =
+      hasExternalRelations(gesturesToAttach);
+
     scheduleFlushOperations();
   });
 
+  // Set before the mount events below fire, so this detector's own mount
+  // listener can tell its gestures apart from external ones
+  preparedGesture.attachedGestures = gesturesToAttach;
+
   for (const gesture of gesturesToAttach) {
     const actionType = gesture.shouldUseReanimated
       ? ActionType.REANIMATED_WORKLET
@@ -101,8 +112,6 @@ export function attachHandlers({
     MountRegistry.gestureWillMount(gesture);
   }
 
-  preparedGesture.attachedGestures = gesturesToAttach;
-
   if (preparedGesture.animatedHandlers) {
     const isAnimatedGesture = (g: GestureType) => g.shouldUseReanimated;
 

packages/react-native-gesture-handler/src/handlers/gestures/GestureDetector/index.tsx

@@ -117,6 +117,10 @@ export const GestureDetector = (props: GestureDetectorProps) => {
     animatedHandlers: null,
     shouldUseReanimated: shouldUseReanimated,
     isMounted: false,
+    // The real value is computed in the attach microtask, which runs after
+    // this commit's effects. Until then react to every mount, so a relation
+    // to a gesture mounting in the same commit is never skipped.
+    hasExternalRelations: true,
   }).current;
 
   const updateAttachedGestures = useDetectorUpdater(

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

@@ -14,6 +14,9 @@ export interface AttachedGestureState {
   shouldUseReanimated: boolean;
   // Whether the GestureDetector is mounted
   isMounted: boolean;
+  // Whether any attached gesture has a relation to a gesture outside this
+  // detector (a ref or a gesture object), which may resolve on a later mount
+  hasExternalRelations: boolean;
 }
 
 export interface GestureDetectorState {

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

@@ -9,6 +9,7 @@ import {
   ALLOWED_PROPS,
   checkGestureCallbacksForWorklets,
   extractGestureRelations,
+  hasExternalRelations,
 } from './utils';
 
 export function updateHandlers(
@@ -33,6 +34,9 @@ export function updateHandlers(
   // Store attached gestures to avoid crash when gestures changed after queueing micro task
   const attachedGestures = preparedGesture.attachedGestures;
 
+  // React to every mount until the microtask below classifies the new gesture set
+  preparedGesture.hasExternalRelations = true;
+
   // Use queueMicrotask to extract handlerTags, because when it's ran, all refs should be updated
   // and handlerTags in BaseGesture references should be updated in the loop above (we need to wait
   // in case of external relations)
@@ -78,6 +82,10 @@ export function updateHandlers(
       registerHandler(handler.handlerTag, handler, handler.config.testId);
     }
 
+    // Classify the new instances: their configs reference the new siblings,
+    // which the old attached objects would mistake for external gestures
+    preparedGesture.hasExternalRelations = hasExternalRelations(newGestures);
+
     if (preparedGesture.animatedHandlers && shouldUpdateSharedValueIfUsed) {
       const newHandlersValue = attachedGestures
         .filter((g) => g.shouldUseReanimated) // Ignore gestures that shouldn't run on UI

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

@@ -1,23 +1,27 @@
 import { useEffect } from 'react';
 
+import type { GestureMountListener } from '../../../mountRegistry';
 import { MountRegistry } from '../../../mountRegistry';
 import type { GestureRef } from '../gesture';
 import type { AttachedGestureState } from './types';
 
+type MountedGesture = Parameters<GestureMountListener>[0];
+
 function shouldUpdateDetector(
   relation: GestureRef[] | undefined,
-  gesture: { handlerTag: number }
+  gesture: MountedGesture
 ) {
   if (relation === undefined) {
     return false;
   }
 
   for (const entry of relation) {
-    // Only refs can start pointing at a different handler after the detector
-    // attached, because `current` is filled in when the gesture they point at
-    // mounts. Gestures and numeric tags already carry their tag by then, so a
-    // mount can never change what they resolve to and scanning them is wasted
-    // work on every mount of every detector.
+    // A gesture object gets its tag in `initialize`, when its own detector
+    // attaches. The mount event carries that very object, so identity is enough.
+    if (entry === gesture) {
+      return true;
+    }
+
     if (entry === null || typeof entry !== 'object' || !('current' in entry)) {
       continue;
     }
@@ -44,6 +48,17 @@ export function useMountReactions(
         return;
       }
 
+      // Nothing here can resolve late, skip the scan (most detectors)
+      if (!state.hasExternalRelations) {
+        return;
+      }
+
+      // Own gestures are resolved by the attach microtask, and on a reattach
+      // they would match the sibling entries added by composition
+      if (state.attachedGestures.includes(gesture as never)) {
+        return;
+      }
+
       // At this point the ref in the gesture config should be updated, so we can check if one of the gestures
       // set in a relation with the gesture got mounted. If so, we need to update the detector to propagate
       // the changes to the native side.

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

@@ -64,6 +64,42 @@ function extractValidHandlerTags(interactionGroup: GestureRef[] | undefined) {
   );
 }
 
+// Relations that may resolve to a different handler after this detector attached:
+// refs (filled when the target mounts) and gesture objects attached by another
+// detector (they get a tag in `initialize`). Siblings added by composition are
+// attached together with the gesture, so they never resolve late.
+export function hasExternalRelations(gestures: GestureType[]) {
+  const ownGestures = new Set(gestures);
+
+  for (const gesture of gestures) {
+    const relations = [
+      gesture.config.blocksHandlers,
+      gesture.config.requireToFail,
+      gesture.config.simultaneousWith,
+    ];
+
+    for (const relation of relations) {
+      if (relation === undefined) {
+        continue;
+      }
+
+      for (const entry of relation) {
+        if (typeof entry === 'number') {
+          continue;
+        }
+
+        // Anything but our own gesture object is external: a ref, or a gesture
+        // attached by another detector
+        if (!(entry instanceof BaseGesture) || !ownGestures.has(entry)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
 export function extractGestureRelations(gesture: GestureType) {
   const requireToFail = extractValidHandlerTags(gesture.config.requireToFail);
   const simultaneousWith = extractValidHandlerTags(