[Web] Activate ScrollView's native gesture on real scroll instead of pointer distance (#4420)

## Description

On web, `NativeViewGestureHandler` activated after ~`15px` of pointer
movement in any direction, even though the browser does the scrolling
itself. A vertical `ScrollView` would claim horizontal drags, and once
active, `InteractionManager` failed any `Pan` whose activation criteria
(`minDistance`, `activeOffsetX`, ...) delayed activation past the slop -
such pans could never activate inside a `ScrollView` or `FlatList`.

This PR adds `ScrollEventManager` which delivers the view's `scroll`
events to handlers via a new `onScroll` hook. Handlers with the
`ScrollView` role now activate only when the view actually scrolls, with
a `2px` pointer travel requirement that ignores momentum-scroll ticks
after a touch meant to stop a fling.

> [!IMPORTANT]
> This covers only new, hook based API

## Test plan

- Unit tests for scroll-driven activation, the momentum guard and the
unchanged legacy path
- Pan activation criteria screen: all boxes activate per their criteria
inside the ScrollView, negatives stay inactive, scrolling works
- Buttons in FlatList screen: scrolling from a button doesn't fire a
press, taps do; tap-to-stop-momentum fires nothing and the next tap
works


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

```tsx
import React, { useRef, useState } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import {
  GestureDetector,
  ScrollView,
  usePanGesture,
} from 'react-native-gesture-handler';
import Animated, {
  interpolateColor,
  useAnimatedStyle,
  useSharedValue,
  withTiming,
} from 'react-native-reanimated';

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

type PanConfig = Parameters<typeof usePanGesture>[0];

type DraggableBoxProps = {
  label: string;
  comment: string;
  config?: PanConfig;
  onActivated: (label: string) => void;
};

function DraggableBox({ label, comment, config, onActivated }: DraggableBoxProps) {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const colorProgress = useSharedValue(0);

  const panGesture = usePanGesture({
    minDistance: config?.minDistance,
    minVelocity: config?.minVelocity,
    activeOffsetX: config?.activeOffsetX,
    maxPointers: config?.maxPointers,
    runOnJS: true,
    onActivate: () => {
      colorProgress.value = withTiming(1, { duration: 100 });
      onActivated(label);
    },
    onUpdate: (event) => {
      translateX.value = event.translationX;
      translateY.value = event.translationY;
    },
    onFinalize: () => {
      colorProgress.value = withTiming(0, { duration: 100 });
      translateX.value = withTiming(0);
      translateY.value = withTiming(0);
    },
  });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [
      { translateX: translateX.value },
      { translateY: translateY.value },
    ],
    backgroundColor: interpolateColor(
      colorProgress.value,
      [0, 1],
      [COLORS.NAVY, COLORS.GREEN]
    ),
  }));

  return (
    <View style={[commonStyles.subcontainer, styles.entry]}>
      <GestureDetector gesture={panGesture}>
        <Animated.View style={[styles.box, animatedStyle]}>
          <Text style={styles.label}>{label}</Text>
        </Animated.View>
      </GestureDetector>
      <Text style={commonStyles.instructions}>{comment}</Text>
    </View>
  );
}

export default function PanActivationCriteriaExample() {
  const [maxPointers, setMaxPointers] = useState(1);
  const feedbackRef = useRef<FeedbackHandle>(null);

  const onActivated = (label: string) =>
    feedbackRef.current?.showMessage(`Activated: ${label}`);

  return (
    <View style={styles.container}>
      <ScrollView style={styles.scroll}>
        <Text style={commonStyles.instructions}>
          Each box turns green the moment its pan activates. Drag each one and
          verify the activation criteria are respected.
        </Text>
        <DraggableBox
          label="minDistance: 100"
          comment="Should activate only after the finger travels 100pt in any direction."
          config={{ minDistance: 100 }}
          onActivated={onActivated}
        />
        <DraggableBox
          label="minVelocity: 800"
          comment="Should activate only on a fast drag (over 800pt/s), regardless of direction. Slow drags must never activate."
          config={{ minVelocity: 800 }}
          onActivated={onActivated}
        />
        <DraggableBox
          label="activeOffsetX: ±60"
          comment="Should activate only after moving 60pt horizontally. Vertical drags must not activate."
          config={{ activeOffsetX: [-60, 60] }}
          onActivated={onActivated}
        />
        <View style={styles.updateSection}>
          <DraggableBox
            label={`minDistance: 120\nmaxPointers: ${maxPointers}`}
            comment="Explicit minDistance combined with another prop updated at runtime. After pressing the button below, activation must still require 120pt of travel — partial config updates must not reset minDistance."
            config={{ minDistance: 120, maxPointers }}
            onActivated={onActivated}
          />
          <Button
            title="Update unrelated prop (maxPointers)"
            onPress={() => setMaxPointers((prev) => (prev === 1 ? 2 : 1))}
          />
        </View>
      </ScrollView>
      <View style={styles.feedbackOverlay} pointerEvents="none">
        <Feedback ref={feedbackRef} duration={2000} />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  scroll: {
    paddingVertical: 24,
  },
  feedbackOverlay: {
    position: 'absolute',
    bottom: 20,
    alignSelf: 'center',
  },
  entry: {
    paddingVertical: 24,
    gap: 12,
  },
  box: {
    width: 150,
    height: 150,
    borderRadius: 20,
    justifyContent: 'center',
    alignItems: 'center',
  },
  label: {
    color: 'white',
    fontWeight: '600',
    textAlign: 'center',
  },
  updateSection: {
    paddingBottom: 32,
  },
});
```

</details>

Author: m-bert

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

@@ -0,0 +1,215 @@
+import { ActionType } from '../ActionType';
+import { PointerType } from '../PointerType';
+import { State } from '../State';
+import { NATIVE_GESTURE_ROLE_ATTRIBUTE } from '../web/constants';
+import type IGestureHandler from '../web/handlers/IGestureHandler';
+import NativeViewGestureHandler from '../web/handlers/NativeViewGestureHandler';
+import type { AdaptedEvent } from '../web/interfaces';
+import { EventTypes, NativeGestureRole } from '../web/interfaces';
+import type { GestureHandlerDelegate } from '../web/tools/GestureHandlerDelegate';
+import GestureHandlerOrchestrator from '../web/tools/GestureHandlerOrchestrator';
+import ScrollEventManager from '../web/tools/ScrollEventManager';
+
+// The Jest environment is node — provide the minimal DOM surface the handler
+// touches (canUseDOM, instanceof HTMLElement).
+class FakeHTMLElement {
+  public style: Record<string, string> = {};
+  public scrollLeft = 0;
+  public scrollTop = 0;
+  private attributes = new Map<string, string>();
+  private listeners = new Map<string, Set<(event: unknown) => void>>();
+
+  public setAttribute(name: string, value: string): void {
+    this.attributes.set(name, value);
+  }
+  public getAttribute(name: string): string | null {
+    return this.attributes.get(name) ?? null;
+  }
+  public hasAttribute(name: string): boolean {
+    return this.attributes.has(name);
+  }
+  public addEventListener(type: string, listener: (event: unknown) => void) {
+    const listeners = this.listeners.get(type) ?? new Set();
+    listeners.add(listener);
+    this.listeners.set(type, listeners);
+  }
+  public removeEventListener(type: string, listener: (event: unknown) => void) {
+    this.listeners.get(type)?.delete(listener);
+  }
+  public dispatchEvent(type: string): void {
+    this.listeners.get(type)?.forEach((listener) => listener({ type }));
+  }
+}
+
+beforeAll(() => {
+  const globals = globalThis as Record<string, unknown>;
+  globals.HTMLElement = FakeHTMLElement;
+  globals.SVGElement = FakeHTMLElement;
+  globals.window = { document: { createElement: () => new FakeHTMLElement() } };
+});
+
+afterAll(() => {
+  const globals = globalThis as Record<string, unknown>;
+  delete globals.HTMLElement;
+  delete globals.SVGElement;
+  delete globals.window;
+});
+
+class TestNativeViewGestureHandler extends NativeViewGestureHandler {
+  public pointerDown(event: AdaptedEvent): void {
+    this.onPointerDown(event);
+  }
+
+  public pointerMove(event: AdaptedEvent): void {
+    this.onPointerMove(event);
+  }
+}
+
+function touchEvent(x: number, y: number, eventType: EventTypes): AdaptedEvent {
+  return {
+    x,
+    y,
+    offsetX: x,
+    offsetY: y,
+    pointerId: 0,
+    eventType,
+    pointerType: PointerType.TOUCH,
+    time: 0,
+  };
+}
+
+function createHandler(view: FakeHTMLElement) {
+  const delegate = {
+    view,
+    init: jest.fn(),
+    detach: jest.fn(),
+    reset: jest.fn(),
+    onActivate: jest.fn(),
+    onFail: jest.fn(),
+    onCancel: jest.fn(),
+    onEnd: jest.fn(),
+    onEnabledChange: jest.fn(),
+    updateDOM: jest.fn(),
+  } as unknown as GestureHandlerDelegate<unknown, IGestureHandler>;
+
+  const handler = new TestNativeViewGestureHandler(delegate);
+  handler.setGestureConfig({ enabled: true });
+  handler.init(1, { current: {} } as never, ActionType.NATIVE_DETECTOR);
+
+  // Route scroll events the same way the real delegate does.
+  handler.attachEventManager(
+    new ScrollEventManager(view as unknown as HTMLElement)
+  );
+
+  // The full event pipeline is not under test — silence event emission.
+  handler.sendEvent = jest.fn();
+
+  return handler;
+}
+
+describe('NativeViewGestureHandler activation', () => {
+  afterEach(() => {
+    // The orchestrator is a singleton — drop handlers recorded by the test.
+    (
+      GestureHandlerOrchestrator.instance as unknown as {
+        gestureHandlers: IGestureHandler[];
+      }
+    ).gestureHandlers = [];
+  });
+
+  test('scrollable view does not activate on pointer distance alone', () => {
+    const view = new FakeHTMLElement();
+    view.setAttribute(
+      NATIVE_GESTURE_ROLE_ATTRIBUTE,
+      NativeGestureRole.ScrollView
+    );
+    const handler = createHandler(view);
+
+    handler.pointerDown(touchEvent(100, 100, EventTypes.DOWN));
+    expect(handler.state).toBe(State.BEGAN);
+
+    handler.pointerMove(touchEvent(100, 200, EventTypes.MOVE));
+    expect(handler.state).toBe(State.BEGAN);
+  });
+
+  test('scrollable view activates when it really scrolls during a drag', () => {
+    const view = new FakeHTMLElement();
+    view.setAttribute(
+      NATIVE_GESTURE_ROLE_ATTRIBUTE,
+      NativeGestureRole.ScrollView
+    );
+    const handler = createHandler(view);
+
+    handler.pointerDown(touchEvent(100, 100, EventTypes.DOWN));
+    handler.pointerMove(touchEvent(100, 130, EventTypes.MOVE));
+
+    view.dispatchEvent('scroll');
+    expect(handler.state).toBe(State.ACTIVE);
+  });
+
+  test('scroll under a resting pointer does not activate (momentum stop)', () => {
+    const view = new FakeHTMLElement();
+    view.setAttribute(
+      NATIVE_GESTURE_ROLE_ATTRIBUTE,
+      NativeGestureRole.ScrollView
+    );
+    const handler = createHandler(view);
+
+    handler.pointerDown(touchEvent(100, 100, EventTypes.DOWN));
+    view.dispatchEvent('scroll');
+    expect(handler.state).toBe(State.BEGAN);
+
+    // Once the pointer really moves, the earlier scroll counts.
+    handler.pointerMove(touchEvent(100, 110, EventTypes.MOVE));
+    expect(handler.state).toBe(State.ACTIVE);
+  });
+
+  test('scroll with no tracked pointers is ignored', () => {
+    const view = new FakeHTMLElement();
+    view.setAttribute(
+      NATIVE_GESTURE_ROLE_ATTRIBUTE,
+      NativeGestureRole.ScrollView
+    );
+    const handler = createHandler(view);
+
+    view.dispatchEvent('scroll');
+    expect(handler.state).toBe(State.UNDETERMINED);
+  });
+
+  test('non-scrollable view keeps distance-based activation', () => {
+    const view = new FakeHTMLElement();
+    const handler = createHandler(view);
+
+    handler.pointerDown(touchEvent(100, 100, EventTypes.DOWN));
+    expect(handler.state).toBe(State.BEGAN);
+
+    handler.pointerMove(touchEvent(100, 130, EventTypes.MOVE));
+    expect(handler.state).toBe(State.ACTIVE);
+  });
+
+  test('role-less view keeps distance-based activation (scroll-driven mode is v3-only)', () => {
+    const view = new FakeHTMLElement();
+    view.style.overflowY = 'scroll';
+    const handler = createHandler(view);
+
+    handler.pointerDown(touchEvent(100, 100, EventTypes.DOWN));
+    handler.pointerMove(touchEvent(100, 130, EventTypes.MOVE));
+    expect(handler.state).toBe(State.ACTIVE);
+  });
+
+  test('scroll on a role-less view does not add an activation path', () => {
+    const view = new FakeHTMLElement();
+    view.style.overflowY = 'scroll';
+    const handler = createHandler(view);
+
+    // Below DEFAULT_TOUCH_SLOP, a scroll of the view itself must not activate
+    // a handler that is not scroll-driven (e.g. legacy ScrollView, TextInput).
+    handler.pointerDown(touchEvent(100, 100, EventTypes.DOWN));
+    handler.pointerMove(touchEvent(100, 110, EventTypes.MOVE));
+    view.dispatchEvent('scroll');
+    expect(handler.state).toBe(State.BEGAN);
+
+    handler.pointerMove(touchEvent(100, 130, EventTypes.MOVE));
+    expect(handler.state).toBe(State.ACTIVE);
+  });
+});

packages/react-native-gesture-handler/src/web/handlers/GestureHandler.ts

@@ -143,6 +143,7 @@ export default abstract class GestureHandler implements IGestureHandler {
     manager.setOnPointerMoveOver(this.onPointerMoveOver.bind(this));
     manager.setOnPointerMoveOut(this.onPointerMoveOut.bind(this));
     manager.setOnWheel(this.onWheel.bind(this));
+    manager.setOnScroll(this.onScroll.bind(this));
 
     // The initial config is applied before the handler is attached. Honor an
     // initially disabled handler here because the delegate's enabled-change
@@ -398,6 +399,9 @@ export default abstract class GestureHandler implements IGestureHandler {
   protected onWheel(_event: AdaptedEvent): void {
     // Used only by pan gesture handler
   }
+  protected onScroll(_event: AdaptedEvent): void {
+    // Used only by native view gesture handler
+  }
   protected tryToSendMoveEvent(out: boolean, event: AdaptedEvent): void {
     if ((out && this.shouldCancelWhenOutside) || !this.enabled) {
       return;

packages/react-native-gesture-handler/src/web/handlers/NativeViewGestureHandler.ts

@@ -41,6 +41,10 @@ export default class NativeViewGestureHandler extends GestureHandler {
   private startY = 0;
   private minDistSq = DEFAULT_TOUCH_SLOP * DEFAULT_TOUCH_SLOP;
 
+  private readonly scrollActivationThresholdSq = 2 * 2;
+  private isScrollDriven = false;
+  private scrollDetected = false;
+
   private lastActiveHandlerData: HandlerData<NativeHandlerData> | null = null;
 
   private hasLongPressHandler = false;
@@ -65,6 +69,7 @@ export default class NativeViewGestureHandler extends GestureHandler {
     super.init(ref, propsRef, actionType, hostDetector);
 
     this.shouldCancelWhenOutside = true;
+    this.isScrollDriven = false;
 
     const view = this.delegate.view;
 
@@ -86,6 +91,8 @@ export default class NativeViewGestureHandler extends GestureHandler {
         this.role = NativeGestureRole.Switch;
       }
     }
+
+    this.isScrollDriven = this.role === NativeGestureRole.ScrollView;
   }
 
   public override updateGestureConfig(config: Config): void {
@@ -144,6 +151,8 @@ export default class NativeViewGestureHandler extends GestureHandler {
       return;
     }
 
+    this.scrollDetected = false;
+
     this.begin();
 
     dispatchGestureLifecycleEvent(
@@ -166,19 +175,51 @@ export default class NativeViewGestureHandler extends GestureHandler {
   protected override onPointerMove(event: AdaptedEvent): void {
     this.tracker.track(event);
 
-    const lastCoords = this.tracker.getAbsoluteCoordsAverage();
-    const dx = this.startX - lastCoords.x;
-    const dy = this.startY - lastCoords.y;
-    const distSq = dx * dx + dy * dy;
-
     if (
       this.role === NativeGestureRole.Switch ||
       this.role === NativeGestureRole.Button
     ) {
       return;
     }
 
-    if (distSq >= this.minDistSq && this.state === State.BEGAN) {
+    if (this.isScrollDriven) {
+      this.tryScrollDrivenActivation();
+      return;
+    }
+
+    if (
+      this.pointerTravelSq() >= this.minDistSq &&
+      this.state === State.BEGAN
+    ) {
+      this.activate();
+    }
+  }
+
+  private pointerTravelSq(): number {
+    const lastCoords = this.tracker.getAbsoluteCoordsAverage();
+    const dx = this.startX - lastCoords.x;
+    const dy = this.startY - lastCoords.y;
+    return dx * dx + dy * dy;
+  }
+
+  protected override onScroll(_event: AdaptedEvent): void {
+    if (!this.isScrollDriven || this.tracker.trackedPointersCount === 0) {
+      return;
+    }
+
+    this.scrollDetected = true;
+    this.tryScrollDrivenActivation();
+  }
+
+  private tryScrollDrivenActivation(): void {
+    if (!this.scrollDetected || this.state !== State.BEGAN) {
+      return;
+    }
+
+    // Require some pointer travel on top of the scroll event — momentum
+    // scrolling keeps emitting `scroll` events after a touch that was only
+    // meant to stop it, and that touch must not activate the handler.
+    if (this.pointerTravelSq() >= this.scrollActivationThresholdSq) {
       this.activate();
     }
   }
@@ -427,6 +468,7 @@ export default class NativeViewGestureHandler extends GestureHandler {
     this.lastActiveHandlerData = null;
     this.lastEventWasInside = false;
     this.longPressDetected = false;
+    this.scrollDetected = false;
   }
 
   public override onDestroy(): void {

packages/react-native-gesture-handler/src/web/tools/EventManager.ts

@@ -38,6 +38,7 @@ export default abstract class EventManager<T> {
   protected onPointerMoveOver(_event: AdaptedEvent): void {}
   protected onPointerMoveOut(_event: AdaptedEvent): void {}
   protected onWheel(_event: AdaptedEvent): void {}
+  protected onScroll(_event: AdaptedEvent): void {}
 
   public setOnPointerDown(callback: PointerEventCallback): void {
     this.onPointerDown = callback;
@@ -75,6 +76,9 @@ export default abstract class EventManager<T> {
   public setOnWheel(callback: PointerEventCallback): void {
     this.onWheel = callback;
   }
+  public setOnScroll(callback: PointerEventCallback): void {
+    this.onScroll = callback;
+  }
 
   protected markAsInBounds(pointerId: number): void {
     if (this.pointersInBounds.indexOf(pointerId) >= 0) {

packages/react-native-gesture-handler/src/web/tools/GestureHandlerWebDelegate.ts

@@ -19,6 +19,7 @@ import type {
 } from './GestureHandlerDelegate';
 import KeyboardEventManager from './KeyboardEventManager';
 import PointerEventManager from './PointerEventManager';
+import ScrollEventManager from './ScrollEventManager';
 import WheelEventManager from './WheelEventManager';
 
 interface DefaultViewStyles {
@@ -69,6 +70,7 @@ export class GestureHandlerWebDelegate
     );
     this.eventManagers.push(new KeyboardEventManager(this.view));
     this.eventManagers.push(new WheelEventManager(this.view));
+    this.eventManagers.push(new ScrollEventManager(this.view));
 
     this.eventManagers.forEach((manager) =>
       this.gestureHandler.attachEventManager(manager)