Pass empty callbacks to UI when runOnJS is true (#4326)

## Description

Currently we call
[`useReanimatedEventHandler`](https://github.com/software-mansion/react-native-gesture-handler/blob/f922b3b23c23ae9e5d77e6d716f7d6f8c02fe9b5/packages/react-native-gesture-handler/src/v3/hooks/useGestureCallbacks.ts#L57)
with original callbacks from config. However, objects captured in the
callbacks' closures will be frozen by Reanimated as they will be passed
to UI, even if `runOnJS` is set to `true`. This triggers warning from
worklets, as well as prevents modification of objects in closure.

```
[Worklets] Tried to modify key `current` of an object which has been already passed to a worklet.
```

To fix that, we pass empty callbacks when `runOnJS` is `true`. 

## Test plan

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

```tsx
import React, { useCallback, useMemo, useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';
import { GestureDetector, usePanGesture } from 'react-native-gesture-handler';
import { useSharedValue } from 'react-native-reanimated';
import { scheduleOnRN } from 'react-native-worklets';

// Empirical test matrix for the `runOnJS` noop-substitution fix.
//
// Pad A - static `runOnJS: true`. Callbacks mutate a plain `session` object;
//   before the fix dev builds froze it ("0 updates in ~1.7T ms" + warnings).
//   Expected: real numbers, no `Tried to modify key` warnings.
//
// Pad B - `runOnJS` driven by React state, toggled by the button below it.
//   Callbacks report which runtime executed them. Expected: "JS runtime"
//   while ON, then after toggling OFF the real callbacks must be re-registered
//   on the UI runtime - a drag must report "UI runtime". If the lazy swap
//   were broken, the UI path would fire the registered noops and the status
//   would never update.
//
// Pad C - `runOnJS` as a SharedValue, flipped by writing `sv.value` directly
//   (no re-render). Expected: "JS runtime" while true, "UI runtime" after the
//   flip - proving the SharedValue path still eagerly registers the real
//   callbacks and toggles without React involvement.

function runtimeName() {
  'worklet';
  return (globalThis as { _WORKLET?: boolean })._WORKLET
    ? 'UI runtime'
    : 'JS runtime';
}

export default function EmptyExample() {
  // --- Pad A: static runOnJS: true, plain mutable object ---
  const [summaryA, setSummaryA] = useState('drag to measure');
  const session = useMemo(() => ({ startTime: 0, updateCount: 0 }), []);

  const panA = usePanGesture({
    onActivate: () => {
      session.startTime = Date.now();
      session.updateCount = 0;
    },
    onUpdate: () => {
      session.updateCount += 1;
    },
    onDeactivate: () => {
      const duration = Date.now() - session.startTime;
      setSummaryA(`${session.updateCount} updates in ${duration} ms`);
    },
    runOnJS: true,
  });

  // --- Pad B: runOnJS toggled through React state ---
  const [jsModeB, setJsModeB] = useState(true);
  const [statusB, setStatusB] = useState('drag to check');

  const reportB = useCallback((runtime: string) => {
    setStatusB(`activated on ${runtime}`);
  }, []);

  const panB = usePanGesture({
    onActivate: () => {
      scheduleOnRN(reportB, runtimeName());
    },
    runOnJS: jsModeB,
  });

  // --- Pad C: runOnJS as a SharedValue, flipped without a re-render ---
  const jsModeC = useSharedValue(true);
  const [statusC, setStatusC] = useState('drag to check');

  const reportC = useCallback((runtime: string) => {
    setStatusC(`activated on ${runtime}`);
  }, []);

  const panC = usePanGesture({
    onActivate: () => {
      scheduleOnRN(reportC, runtimeName());
    },
    runOnJS: jsModeC,
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={panA}>
        <View style={styles.pad}>
          <Text style={styles.padLabel}>Pad A - static true</Text>
        </View>
      </GestureDetector>
      <Text style={styles.status}>{summaryA}</Text>

      <GestureDetector gesture={panB}>
        <View style={styles.pad}>
          <Text style={styles.padLabel}>Pad B - state toggle</Text>
        </View>
      </GestureDetector>
      <Text style={styles.status}>{statusB}</Text>
      <Pressable
        style={styles.button}
        onPress={() => setJsModeB((prev) => !prev)}>
        <Text style={styles.buttonLabel}>
          {`B: runOnJS is ${jsModeB ? 'ON' : 'OFF'} - toggle`}
        </Text>
      </Pressable>

      <GestureDetector gesture={panC}>
        <View style={styles.pad}>
          <Text style={styles.padLabel}>Pad C - SharedValue toggle</Text>
        </View>
      </GestureDetector>
      <Text style={styles.status}>{statusC}</Text>
      <Pressable
        style={styles.button}
        onPress={() => {
          jsModeC.value = !jsModeC.value;
        }}>
        <Text style={styles.buttonLabel}>
          C: flip SharedValue (no rerender)
        </Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    padding: 20,
  },
  pad: {
    alignSelf: 'stretch',
    height: 110,
    borderRadius: 12,
    backgroundColor: '#eef',
    borderWidth: StyleSheet.hairlineWidth,
    borderColor: '#99a',
    justifyContent: 'center',
    alignItems: 'center',
  },
  padLabel: {
    color: '#667',
    fontSize: 15,
  },
  status: {
    marginTop: 6,
    marginBottom: 12,
    textAlign: 'center',
    color: '#666',
  },
  button: {
    alignSelf: 'center',
    paddingHorizontal: 16,
    paddingVertical: 8,
    borderRadius: 8,
    backgroundColor: '#dde',
    marginBottom: 16,
  },
  buttonLabel: {
    color: '#334',
  },
});
```

</details>

Author: m-bert

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

@@ -0,0 +1,123 @@
+import { renderHook } from '@testing-library/react-native';
+
+import { useTapGesture } from '../v3/hooks/gestures';
+import type { SharedValue } from '../v3/types';
+
+jest.mock('../handlers/gestures/reanimatedWrapper', () => {
+  const Reanimated = {
+    useHandler: jest.fn(() => ({
+      doDependenciesDiffer: false,
+      context: { lastUpdateEvent: undefined },
+    })),
+    useEvent: jest.fn(() => jest.fn()),
+    isSharedValue: (value: unknown): boolean =>
+      value !== null && typeof value === 'object' && 'value' in value,
+    isWorkletFunction: (value: unknown): boolean =>
+      typeof value === 'function' && '__workletHash' in value,
+    makeMutable: <T,>(value: T) => ({ value }),
+    runOnUI: () => jest.fn(),
+    runOnJS:
+      (fn: (...args: unknown[]) => unknown) =>
+      (...args: unknown[]) =>
+        fn(...args),
+    useSharedValue: <T,>(value: T) => ({ value }),
+    setGestureState: jest.fn(),
+  };
+
+  return { Reanimated };
+});
+
+const { Reanimated: MockedReanimated } = jest.requireMock(
+  '../handlers/gestures/reanimatedWrapper'
+) as unknown as { Reanimated: { useHandler: jest.Mock } };
+
+const lastHandlers = () =>
+  MockedReanimated.useHandler.mock.calls.at(-1)?.[0] as Record<string, unknown>;
+
+const makeFakeSharedValue = (value: boolean) =>
+  ({
+    value,
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    modify: jest.fn(),
+  }) as unknown as SharedValue<boolean>;
+
+// When `runOnJS` is statically `true`, the Reanimated event path can never
+// receive events, so user callbacks must not be serialized to the UI runtime
+// (in dev, Worklets freezes every plain object captured in their closures,
+// silently dropping later writes). These tests guard the substitution in
+// `useGestureCallbacks` and the re-registration when `runOnJS` changes.
+describe('[API v3] Reanimated handler registration vs runOnJS', () => {
+  beforeEach(() => {
+    MockedReanimated.useHandler.mockClear();
+  });
+
+  test('registers an empty handler set when runOnJS is statically true', () => {
+    const onActivate = jest.fn();
+
+    renderHook(() => useTapGesture({ onActivate, runOnJS: true }));
+
+    expect(MockedReanimated.useHandler).toHaveBeenCalled();
+    for (const call of MockedReanimated.useHandler.mock.calls) {
+      expect(Object.keys(call[0] as object)).toHaveLength(0);
+    }
+  });
+
+  test('registers real callbacks when runOnJS is not set', () => {
+    const onActivate = jest.fn();
+
+    renderHook(() => useTapGesture({ onActivate }));
+
+    expect(lastHandlers().onActivate).toBe(onActivate);
+  });
+
+  test('registers real callbacks when runOnJS is false', () => {
+    const onActivate = jest.fn();
+
+    renderHook(() => useTapGesture({ onActivate, runOnJS: false }));
+
+    expect(lastHandlers().onActivate).toBe(onActivate);
+  });
+
+  test('re-registers real callbacks when runOnJS changes from true to false', () => {
+    const onActivate = jest.fn();
+
+    const { rerender } = renderHook(
+      ({ runOnJS }: { runOnJS: boolean }) =>
+        useTapGesture({ onActivate, runOnJS }),
+      { initialProps: { runOnJS: true } }
+    );
+
+    expect(Object.keys(lastHandlers())).toHaveLength(0);
+
+    rerender({ runOnJS: false });
+
+    expect(lastHandlers().onActivate).toBe(onActivate);
+  });
+
+  test('swaps back to the empty handler set when runOnJS returns to true', () => {
+    const onActivate = jest.fn();
+
+    const { rerender } = renderHook(
+      ({ runOnJS }: { runOnJS: boolean }) =>
+        useTapGesture({ onActivate, runOnJS }),
+      { initialProps: { runOnJS: false } }
+    );
+
+    expect(lastHandlers().onActivate).toBe(onActivate);
+
+    rerender({ runOnJS: true });
+
+    expect(Object.keys(lastHandlers())).toHaveLength(0);
+  });
+
+  test('keeps real callbacks when runOnJS is a SharedValue holding true', () => {
+    const onActivate = jest.fn();
+
+    renderHook(() =>
+      useTapGesture({ onActivate, runOnJS: makeFakeSharedValue(true) })
+    );
+
+    expect(lastHandlers().onActivate).toBe(onActivate);
+  });
+});

packages/react-native-gesture-handler/src/v3/hooks/useGestureCallbacks.ts

@@ -13,6 +13,8 @@ import {
   useMemoizedGestureCallbacks,
 } from './utils';
 
+const EMPTY_UI_CALLBACKS = {};
+
 function guardJSAnimatedEvent(handler: (...args: unknown[]) => void) {
   return (...args: unknown[]) => {
     try {
@@ -51,12 +53,22 @@ export function useGestureCallbacks<
   let reanimatedEventHandler;
 
   if (!config.disableReanimated) {
+    // Passing callbacks to UI runtime when `runOnJS` is true would freeze
+    // the closure, so we pass an empty object instead.
+    //
+    // This check is true only when `runOnJS` is a constant or a React state.
+    // When `runOnJS` is a SharedValue, we pass original callbacks.
+    const uiCallbacks =
+      config.runOnJS === true
+        ? (EMPTY_UI_CALLBACKS as typeof callbacks)
+        : callbacks;
+
     // eslint-disable-next-line react-hooks/rules-of-hooks
-    const reanimatedHandler = Reanimated?.useHandler(callbacks);
+    const reanimatedHandler = Reanimated?.useHandler(uiCallbacks);
     // eslint-disable-next-line react-hooks/rules-of-hooks
     reanimatedEventHandler = useReanimatedEventHandler(
       handlerTag,
-      callbacks,
+      uiCallbacks,
       reanimatedHandler,
       config.changeEventCalculator,
       config.fillInDefaultValues