Add direct-event fast path to EventTarget dispatch (rnIsDirect) (#57448)

packages/react-native/scripts/featureflags/ReactNativeFeatureFlags.config.js

@@ -1014,6 +1014,17 @@ const definitions: FeatureFlagDefinitions = {
       },
       ossReleaseStage: 'none',
     },
+    enableDirectEventsInEventTarget: {
+      defaultValue: false,
+      metadata: {
+        dateAdded: '2026-07-06',
+        description:
+          'When enabled (together with enableNativeEventTargetEventDispatching), direct events (those that neither bubble nor capture, such as onLayout) are dispatched only to the target node via a fast path that skips construction and traversal of the ancestor event path.',
+        expectedReleaseValue: true,
+        purpose: 'experimentation',
+      },
+      ossReleaseStage: 'none',
+    },
     enableImperativeEvents: {
       defaultValue: false,
       metadata: {

packages/react-native/src/private/featureflags/ReactNativeFeatureFlags.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<2be1f76084eb85288987229421d7585f>>
+ * @generated SignedSource<<ff39edecf287d3fe3638da2f71e6bd1c>>
  * @flow strict
  * @noformat
  */
@@ -33,6 +33,7 @@ export type ReactNativeFeatureFlagsJsOnly = Readonly<{
   animatedForceNativeDriver: Getter<boolean>,
   animatedShouldSyncValueBeforeStartCallback: Getter<boolean>,
   deferFlatListFocusChangeRenderUpdate: Getter<boolean>,
+  enableDirectEventsInEventTarget: Getter<boolean>,
   enableImperativeEvents: Getter<boolean>,
   enableNativeEventTargetEventDispatching: Getter<boolean>,
   externalElementInspectionEnabled: Getter<boolean>,
@@ -161,6 +162,11 @@ export const animatedShouldSyncValueBeforeStartCallback: Getter<boolean> = creat
  */
 export const deferFlatListFocusChangeRenderUpdate: Getter<boolean> = createJavaScriptFlagGetter('deferFlatListFocusChangeRenderUpdate', false);
 
+/**
+ * When enabled (together with enableNativeEventTargetEventDispatching), direct events (those that neither bubble nor capture, such as onLayout) are dispatched only to the target node via a fast path that skips construction and traversal of the ancestor event path.
+ */
+export const enableDirectEventsInEventTarget: Getter<boolean> = createJavaScriptFlagGetter('enableDirectEventsInEventTarget', false);
+
 /**
  * When enabled, ReactNativeElement and ReadOnlyText expose the public EventTarget API (addEventListener, removeEventListener, dispatchEvent). When disabled, those methods are removed from those final classes.
  */

packages/react-native/src/private/renderer/core/__tests__/EventDispatching-benchmark-itest.js

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  *
  * @fantom_flags enableNativeEventTargetEventDispatching:*
+ * @fantom_flags enableDirectEventsInEventTarget:*
  * @flow strict-local
  * @format
  */
@@ -39,6 +40,29 @@ function createNestedViews(
   );
 }
 
+// `onLayout` is a direct (non-bubbling) event, so only the leaf needs a
+// handler; ancestors never receive the layout event.
+function createNestedViewsWithLayout(
+  depth: number,
+  innerRef: {current: React.ElementRef<typeof View> | null},
+): React.MixedElement {
+  if (depth === 0) {
+    return (
+      <View
+        ref={innerRef}
+        collapsable={false}
+        onLayout={() => {}}
+        style={{width: 10, height: 10}}
+      />
+    );
+  }
+  return (
+    <View collapsable={false}>
+      {createNestedViewsWithLayout(depth - 1, innerRef)}
+    </View>
+  );
+}
+
 const {isOSS} = Fantom.getConstants();
 
 if (isOSS) {
@@ -322,5 +346,92 @@ if (isOSS) {
           root.destroy();
         },
       },
+    )
+    .test(
+      'dispatch onLayout event, flat (1 handler)',
+      () => {
+        Fantom.dispatchNativeEvent(
+          ref,
+          'onLayout',
+          {layout: {x: 0, y: 0, width: 100, height: 50}},
+          {
+            category: Fantom.NativeEventCategory.Discrete,
+          },
+        );
+      },
+      {
+        beforeAll: () => {
+          ref = React.createRef();
+          root = Fantom.createRoot();
+          Fantom.runTask(() => {
+            root.render(
+              <View
+                ref={ref}
+                collapsable={false}
+                onLayout={() => {}}
+                style={{width: 10, height: 10}}
+              />,
+            );
+          });
+          // Flush the layout events emitted during the initial layout pass so
+          // they are not measured as part of the dispatched event below.
+          Fantom.flushAllNativeEvents();
+        },
+        afterAll: () => {
+          root.destroy();
+        },
+      },
+    )
+    .test(
+      'dispatch onLayout event, nested 10 deep (direct, no bubbling)',
+      () => {
+        Fantom.dispatchNativeEvent(
+          ref,
+          'onLayout',
+          {layout: {x: 0, y: 0, width: 100, height: 50}},
+          {
+            category: Fantom.NativeEventCategory.Discrete,
+          },
+        );
+      },
+      {
+        beforeAll: () => {
+          ref = React.createRef();
+          root = Fantom.createRoot();
+          Fantom.runTask(() => {
+            root.render(createNestedViewsWithLayout(10, ref));
+          });
+          Fantom.flushAllNativeEvents();
+        },
+        afterAll: () => {
+          root.destroy();
+        },
+      },
+    )
+    .test(
+      'dispatch onLayout event, nested 50 deep (direct, no bubbling)',
+      () => {
+        Fantom.dispatchNativeEvent(
+          ref,
+          'onLayout',
+          {layout: {x: 0, y: 0, width: 100, height: 50}},
+          {
+            category: Fantom.NativeEventCategory.Discrete,
+          },
+        );
+      },
+      {
+        beforeAll: () => {
+          ref = React.createRef();
+          root = Fantom.createRoot();
+          Fantom.runTask(() => {
+            root.render(createNestedViewsWithLayout(50, ref));
+          });
+          Fantom.flushAllNativeEvents();
+        },
+        afterAll: () => {
+          root.destroy();
+        },
+      },
     );
 }

packages/react-native/src/private/renderer/core/__tests__/EventTargetDispatching-itest.js

@@ -6,6 +6,7 @@
  *
  * @fantom_flags enableNativeEventTargetEventDispatching:*
  * @fantom_flags enableImperativeEvents:*
+ * @fantom_flags enableDirectEventsInEventTarget:*
  * @flow strict-local
  * @format
  */
@@ -22,6 +23,7 @@ import * as Fantom from '@react-native/fantom';
 import * as React from 'react';
 import {View} from 'react-native';
 import * as ReactNativeFeatureFlags from 'react-native/src/private/featureflags/ReactNativeFeatureFlags';
+import Event from 'react-native/src/private/webapis/dom/events/Event';
 
 // Temporary cast until ReadOnlyNode extends EventTarget ungated.
 function asEventTarget(node: ?interface {}): ReadOnlyNodeWithEventTarget {
@@ -33,6 +35,28 @@ function asEventTarget(node: ?interface {}): ReadOnlyNodeWithEventTarget {
   return node;
 }
 
+function createNestedViewsWithLayout(
+  depth: number,
+  innerRef: {current: React.ElementRef<typeof View> | null},
+  onLayout: () => void,
+): React.MixedElement {
+  if (depth === 0) {
+    return (
+      <View
+        ref={innerRef}
+        collapsable={false}
+        onLayout={onLayout}
+        style={{width: 10, height: 10}}
+      />
+    );
+  }
+  return (
+    <View collapsable={false}>
+      {createNestedViewsWithLayout(depth - 1, innerRef, onLayout)}
+    </View>
+  );
+}
+
 const {isOSS} = Fantom.getConstants();
 
 (isOSS ? describe.skip : describe)(
@@ -1626,5 +1650,174 @@ const {isOSS} = Fantom.getConstants();
         expect(parentSpy.mock.calls.length - parentCallsBefore).toBe(0);
       });
     });
+
+    describe('direct events (rnIsDirect) — Event construction validation', () => {
+      it('allows constructing a direct event that does not bubble', () => {
+        const event = new Event('layout', {rnIsDirect: true});
+        expect(event.rnIsDirect).toBe(true);
+        expect(event.bubbles).toBe(false);
+      });
+
+      it('defaults rnIsDirect to false', () => {
+        const event = new Event('layout');
+        expect(event.rnIsDirect).toBe(false);
+      });
+
+      it('throws when rnIsDirect and bubbles are both true', () => {
+        expect(() => {
+          // eslint-disable-next-line no-new
+          new Event('layout', {rnIsDirect: true, bubbles: true});
+        }).toThrow(
+          "Failed to construct 'Event': 'rnIsDirect' cannot be true when 'bubbles' is also true.",
+        );
+      });
+    });
+
+    // The dispatch-behavior tests use `addEventListener` on refs and the
+    // document element, which is only available when both
+    // `enableNativeEventTargetEventDispatching` and `enableImperativeEvents`
+    // are enabled.
+    (ReactNativeFeatureFlags.enableNativeEventTargetEventDispatching() &&
+      ReactNativeFeatureFlags.enableImperativeEvents()
+      ? describe
+      : describe.skip)('direct events (rnIsDirect) — dispatch behavior', () => {
+      it('dispatches onLayout to the target but never to ancestor onLayout props or bubble listeners', () => {
+        const root = Fantom.createRoot();
+        const childRef = React.createRef<React.ElementRef<typeof View>>();
+        const childHandler = jest.fn();
+        const parentPropHandler = jest.fn();
+        const parentImperativeBubble = jest.fn();
+
+        Fantom.runTask(() => {
+          root.render(
+            <View onLayout={parentPropHandler}>
+              <View>
+                <View>
+                  <View ref={childRef} onLayout={childHandler} />
+                </View>
+              </View>
+            </View>,
+          );
+        });
+
+        asEventTarget(root.document.documentElement).addEventListener(
+          'layout',
+          parentImperativeBubble,
+        );
+
+        // Drain mount-time layout events.
+        Fantom.flushAllNativeEvents();
+
+        const childBefore = childHandler.mock.calls.length;
+        const parentBefore = parentPropHandler.mock.calls.length;
+        const parentBubbleBefore = parentImperativeBubble.mock.calls.length;
+
+        Fantom.dispatchNativeEvent(
+          childRef,
+          'onLayout',
+          {layout: {x: 0, y: 0, width: 100, height: 50}},
+          {category: Fantom.NativeEventCategory.Discrete},
+        );
+
+        // The target's own onLayout fires exactly once.
+        expect(childHandler.mock.calls.length - childBefore).toBe(1);
+        // A direct (non-bubbling) event never reaches an ancestor's onLayout
+        // prop or an ancestor's bubble-phase listener, regardless of the fast
+        // path.
+        expect(parentPropHandler.mock.calls.length - parentBefore).toBe(0);
+        expect(
+          parentImperativeBubble.mock.calls.length - parentBubbleBefore,
+        ).toBe(0);
+      });
+
+      (ReactNativeFeatureFlags.enableDirectEventsInEventTarget()
+        ? it
+        : it.skip)(
+        'restricts the event path to the target (AT_TARGET only, no ancestor capture listeners)',
+        () => {
+          const root = Fantom.createRoot();
+          const childRef = React.createRef<React.ElementRef<typeof View>>();
+          const ancestorCapture = jest.fn();
+          let observedPhase: number | null = null;
+          let observedPathLength: number | null = null;
+          let observedCurrentIsTarget: boolean | null = null;
+
+          const handler = jest.fn((e: $FlowFixMe) => {
+            observedPhase = e.eventPhase;
+            observedPathLength = e.composedPath().length;
+            observedCurrentIsTarget = e.currentTarget === childRef.current;
+          });
+
+          Fantom.runTask(() => {
+            root.render(createNestedViewsWithLayout(5, childRef, () => {}));
+          });
+
+          asEventTarget(childRef.current).addEventListener('layout', handler);
+          asEventTarget(root.document.documentElement).addEventListener(
+            'layout',
+            ancestorCapture,
+            {capture: true},
+          );
+          Fantom.flushAllNativeEvents();
+
+          const ancestorCaptureBefore = ancestorCapture.mock.calls.length;
+
+          Fantom.dispatchNativeEvent(
+            childRef,
+            'onLayout',
+            {layout: {x: 0, y: 0, width: 100, height: 50}},
+            {category: Fantom.NativeEventCategory.Discrete},
+          );
+
+          expect(handler).toHaveBeenCalled();
+          expect(observedPhase).toBe(Event.AT_TARGET);
+          // Event path is just the target node.
+          expect(observedPathLength).toBe(1);
+          expect(observedCurrentIsTarget).toBe(true);
+          // With the fast path, the capture phase does not traverse ancestors.
+          expect(
+            ancestorCapture.mock.calls.length - ancestorCaptureBefore,
+          ).toBe(0);
+        },
+      );
+
+      (ReactNativeFeatureFlags.enableDirectEventsInEventTarget()
+        ? it.skip
+        : it)(
+        'without the fast path, the capture phase still traverses ancestors for direct events',
+        () => {
+          const root = Fantom.createRoot();
+          const childRef = React.createRef<React.ElementRef<typeof View>>();
+          const ancestorCapture = jest.fn();
+
+          Fantom.runTask(() => {
+            root.render(createNestedViewsWithLayout(5, childRef, () => {}));
+          });
+
+          asEventTarget(root.document.documentElement).addEventListener(
+            'layout',
+            ancestorCapture,
+            {capture: true},
+          );
+          Fantom.flushAllNativeEvents();
+
+          const ancestorCaptureBefore = ancestorCapture.mock.calls.length;
+
+          Fantom.dispatchNativeEvent(
+            childRef,
+            'onLayout',
+            {layout: {x: 0, y: 0, width: 100, height: 50}},
+            {category: Fantom.NativeEventCategory.Discrete},
+          );
+
+          // The DOM dispatch algorithm runs the capture phase over every
+          // ancestor even for non-bubbling events, so the ancestor capture
+          // listener fires.
+          expect(
+            ancestorCapture.mock.calls.length - ancestorCaptureBefore,
+          ).toBe(1);
+        },
+      );
+    });
   },
 );