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

Summary:
Direct events (those that neither bubble nor capture, such as `onLayout`) were still dispatched through the full W3C event-path algorithm when using the EventTarget-based dispatcher: the path was built by walking every ancestor up to the root, and the capture phase then iterated over all of them, even though a direct event only ever fires on its target. This made direct-event dispatch scale with tree depth (O(depth)).

This introduces a "direct" event mode on `Event`:

- A new RN-specific `rnIsDirect` option on `EventInit` (with a matching `rnIsDirect` getter). A direct event has only an `AT_TARGET` phase and an event path containing just the target node.
- Construction validation: an event cannot be both `rnIsDirect` and `bubbles`; the constructor throws a `TypeError` for that combination.
- When `rnIsDirect` is set, the event path is restricted to the target, so dispatch skips the ancestor walk and capture-phase traversal (O(1)).

The renderer opts native direct events into this fast path (behind a runtime gate) by tagging them with `rnIsDirect` at the dispatch site. Bubbling events that merely skip bubbling (e.g. `onPointerEnter`) still have a capture phase and are intentionally not treated as direct.

This is gated and defaults off, so there is no behavior change by default.

Benchmark results (median dispatch latency for the new `onLayout` direct-event benchmarks; all use the same stable-tree setup so depth is directly comparable):

| onLayout dispatch | EventTarget off (baseline) | EventTarget on, direct off | EventTarget on, direct on |
| --- | --- | --- | --- |
| flat (1 handler) | 12.7us | 20.7us | 18.2us |
| nested 10 deep | 12.7us | 33.4us | 18.1us |
| nested 50 deep | 12.7us | 82.2us | 18.2us |

Without the fast path, EventTarget dispatch of a direct event scales with tree depth (20.7us -> 33.4us -> 82.2us). The fast path restores O(1): dispatch cost is flat across depth (~18us) and the nested-50-deep case drops from ~82.2us to ~18.2us (~4.5x faster), approaching the legacy baseline (~12.7us). The EventTarget-off numbers are unchanged by the direct-events flag, confirming the flag is correctly gated.

Changelog: [Internal]

Differential Revision: D110759162

Author: rubennorte

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);
+        },
+      );
+    });
   },
 );