feat: add event.stopPropagation (#1835)

Add `event.stopPropagation` and `event.stopImmediatePropagation` in MTS,
to help with event propagation control

```typescript
function App() {
  function handleInnerTap(event: MainThread.TouchEvent) {
    'main thread';
    event.stopPropagation();
    // Or stop immediate propagation with
    // event.stopImmediatePropagation();
  }

  // OuterTap will not be triggered
  return (
    <view main-thread:bindtap={handleOuterTap}>
      <view main-thread:bindtap={handleInnerTap}>
        <text>Hello, world</text>
      </view>
    </view>
  );
}
```

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Event objects now support stopPropagation and stopImmediatePropagation
and expose combined propagation result.

- **Bug Fixes**
- Removed an obsolete runtime warning related to stopPropagation
handling.

- **Documentation**
- Added usage example and changelog guidance; note to update related SDK
in lazy-loading setups.

- **Tests**
- Added tests validating propagation methods, event-result wrapping, and
SDK gating.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

## Checklist

<!--- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).
- [x] Changeset added, and when a BREAKING CHANGE occurs, it needs to be
clearly marked (or not required).

Author: f0rdream

.changeset/clear-crabs-swim.md

@@ -0,0 +1,27 @@
+---
+'@lynx-js/react': patch
+---
+
+Add `event.stopPropagation` and `event.stopImmediatePropagation` in MTS, to help with event propagation control
+
+```tsx
+function App() {
+  function handleInnerTap(event: MainThread.TouchEvent) {
+    'main thread';
+    event.stopPropagation();
+    // Or stop immediate propagation with
+    // event.stopImmediatePropagation();
+  }
+
+  // OuterTap will not be triggered
+  return (
+    <view main-thread:bindtap={handleOuterTap}>
+      <view main-thread:bindtap={handleInnerTap}>
+        <text>Hello, world</text>
+      </view>
+    </view>
+  );
+}
+```
+
+Note, if this feature is used in [Lazy Loading Standalone Project](https://lynxjs.org/react/code-splitting.html#lazy-loading-standalone-project), both the Producer and the Consumer should update to latest version of `@lynx-js/react` to make sure the feature is available.

packages/react/transform/crates/swc_plugin_compat/lib.rs

@@ -1043,22 +1043,8 @@ where
   }
 
   fn visit_mut_call_expr(&mut self, n: &mut CallExpr) {
-    // check if it is e.stopPropagation()
     if let Callee::Expr(e) = &mut n.callee {
       if let Expr::Member(m) = &**e {
-        // check if it is e.stopPropagation
-        if let MemberProp::Ident(id) = &m.prop {
-          if id.sym == "stopPropagation" {
-            HANDLER.with(|handler| {
-              handler
-              .struct_span_warn(
-                n.span,
-                "BROKEN: e.stopPropagation() takes no effect and MUST be migrated in ReactLynx 3.0",
-              )
-              .emit()
-            });
-          }
-        }
         if let Expr::This(_) = &*m.obj {
           if let MemberProp::Ident(id) = &m.prop {
             match id.sym.to_string().as_str() {

packages/react/worklet-runtime/__test__/eventPropagation.test.js

@@ -0,0 +1,88 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { initApiEnv } from '../src/api/lynxApi';
+import { RunWorkletSource } from '../src/bindings/types';
+import { initWorklet } from '../src/workletRuntime';
+
+describe('EventPropagation', () => {
+  const consoleMock = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+  beforeEach(() => {
+    globalThis.SystemInfo = {
+      lynxSdkVersion: '3.5',
+    };
+    delete globalThis.lynxWorkletImpl;
+    globalThis.lynx = {
+      requestAnimationFrame: vi.fn(),
+    };
+    initApiEnv();
+  });
+
+  afterAll(() => {
+    consoleMock.mockReset();
+  });
+
+  it('stopPropagation should have __EventReturnResult be 1', async () => {
+    initWorklet();
+    const fn = vi.fn(function(event) {
+      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
+
+      event.stopPropagation();
+    });
+    globalThis.registerWorklet('main-thread', '1', fn);
+    const ret = globalThis.runWorklet({ _wkltId: '1' }, [{
+      target: {},
+      currentTarget: {},
+    }], {
+      source: RunWorkletSource.EVENT,
+    });
+    expect(ret).toMatchObject({
+      returnValue: undefined,
+      eventReturnResult: 1,
+    });
+  });
+
+  it('stopImmediatePropagation should have __EventReturnResult be 2', async () => {
+    initWorklet();
+    const fn = vi.fn(function(event) {
+      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
+      event.stopImmediatePropagation();
+    });
+
+    globalThis.registerWorklet('main-thread', '1', fn);
+    const ret = globalThis.runWorklet({ _wkltId: '1' }, [{
+      target: {},
+      currentTarget: {},
+    }], {
+      source: RunWorkletSource.EVENT,
+    });
+    expect(ret).toMatchObject({
+      returnValue: undefined,
+      eventReturnResult: 2,
+    });
+  });
+
+  it('call stopPropagation and stopImmediatePropagation should have __EventReturnResult be 3', async () => {
+    initWorklet();
+    const fn = vi.fn(function(event) {
+      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
+      event.stopImmediatePropagation();
+      event.stopPropagation();
+    });
+
+    globalThis.registerWorklet('main-thread', '1', fn);
+    const ret = globalThis.runWorklet({ _wkltId: '1' }, [{
+      target: {},
+      currentTarget: {},
+    }], {
+      source: RunWorkletSource.EVENT,
+    });
+    expect(ret).toMatchObject({
+      returnValue: undefined,
+      eventReturnResult: 0x1 | 0x2,
+    });
+  });
+});

packages/react/worklet-runtime/__test__/workletRuntime.test.js

@@ -5,6 +5,7 @@ import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { Element } from '../src/api/element';
 import { initApiEnv } from '../src/api/lynxApi';
+import { RunWorkletSource } from '../src/bindings/types';
 import { updateWorkletRefInitValueChanges } from '../src/workletRef';
 import { initWorklet } from '../src/workletRuntime';
 
@@ -336,6 +337,58 @@ describe('Worklet', () => {
     globalThis.runWorklet(worklet2Ctx, [2]);
     expect(worklet2).toBeCalledWith(2);
   });
+
+  it('event object should have stopPropagation and stopImmediatePropagation', async () => {
+    initWorklet();
+    const fn = vi.fn(function(event) {
+      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
+      expect(event.stopPropagation).toBeDefined();
+      expect(event.stopImmediatePropagation).toBeDefined();
+    });
+    globalThis.registerWorklet('main-thread', '1', fn);
+    globalThis.runWorklet({ _wkltId: '1' }, [{
+      target: {},
+      currentTarget: {},
+    }], {
+      source: RunWorkletSource.EVENT,
+    });
+  });
+
+  it('event object should have returnValue wrapped', async () => {
+    initWorklet();
+    const fn = vi.fn(function() {
+      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
+
+      return 1;
+    });
+
+    globalThis.registerWorklet('main-thread', '1', fn);
+    const ret = globalThis.runWorklet({ _wkltId: '1' }, [{
+      target: {},
+      currentTarget: {},
+    }], {
+      source: RunWorkletSource.EVENT,
+    });
+
+    expect(ret).toMatchObject({
+      returnValue: 1,
+      eventReturnResult: undefined,
+    });
+  });
+
+  it('non event object should not have returnValue wrapped', async () => {
+    initWorklet();
+    const fn = vi.fn(function() {
+      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
+
+      return 1;
+    });
+
+    globalThis.registerWorklet('main-thread', '1', fn);
+    const ret = globalThis.runWorklet({ _wkltId: '1' }, [1, 2]);
+
+    expect(ret).toBe(1);
+  });
 });
 
 it('requestAnimationFrame should throw error before 2.16', async () => {

packages/react/worklet-runtime/src/bindings/types.ts

@@ -66,3 +66,17 @@ export interface JsFnHandle {
    */
   _delayIndices?: number[];
 }
+
+export interface EventCtx {
+  _eventReturnResult?: number;
+}
+
+export enum RunWorkletSource {
+  NONE = 0,
+  EVENT = 1,
+  GESTURE = 2,
+}
+
+export interface RunWorkletOptions {
+  source: RunWorkletSource;
+}

packages/react/worklet-runtime/src/eventPropagation.ts

@@ -0,0 +1,56 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import type { ClosureValueType, EventCtx, RunWorkletOptions } from './bindings/types.js';
+import { RunWorkletSource } from './bindings/types.js';
+
+// EventResult enum values
+export const EventResult = {
+  kDefault: 0x0,
+  kStopPropagationMask: 0x1,
+  kStopImmediatePropagationMask: 0x2,
+} as const;
+
+type EventLike = Record<string, ClosureValueType>;
+
+export function isEventObject(
+  ctx: ClosureValueType[],
+  options?: RunWorkletOptions,
+): ctx is [EventLike, ...ClosureValueType[]] {
+  if (!Array.isArray(ctx) || typeof ctx[0] !== 'object' || ctx[0] === null) {
+    return false;
+  }
+  if (options && options.source === RunWorkletSource.EVENT) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Add event methods to an event object if needed
+ * @param ctx The event object to enhance
+ * @param options The run worklet options
+ * @returns A tuple of boolean and the event return result
+ */
+export function addEventMethodsIfNeeded(ctx: ClosureValueType[], options?: RunWorkletOptions): [boolean, EventCtx] {
+  if (!isEventObject(ctx, options)) {
+    return [false, {}];
+  }
+  const eventCtx: EventCtx = {};
+  const eventObj = ctx[0];
+
+  // Add stopPropagation method
+  eventObj['stopPropagation'] = function() {
+    eventCtx._eventReturnResult = (eventCtx._eventReturnResult ?? EventResult.kDefault)
+      | EventResult.kStopPropagationMask;
+  };
+
+  // Add stopImmediatePropagation method
+  eventObj['stopImmediatePropagation'] = function() {
+    eventCtx._eventReturnResult = (eventCtx._eventReturnResult ?? EventResult.kDefault)
+      | EventResult.kStopImmediatePropagationMask;
+  };
+
+  return [true, eventCtx];
+}

packages/react/worklet-runtime/src/workletRuntime.ts

@@ -2,10 +2,11 @@
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
 import { Element } from './api/element.js';
-import type { ClosureValueType, Worklet, WorkletRefImpl } from './bindings/types.js';
+import type { ClosureValueType, RunWorkletOptions, Worklet, WorkletRefImpl } from './bindings/types.js';
 import { initRunOnBackgroundDelay } from './delayRunOnBackground.js';
 import { delayExecUntilJsReady, initEventDelay } from './delayWorkletEvent.js';
 import { initEomImpl } from './eomImpl.js';
+import { addEventMethodsIfNeeded } from './eventPropagation.js';
 import { hydrateCtx } from './hydrate.js';
 import { JsFunctionLifecycleManager, isRunOnBackgroundEnabled } from './jsFunctionLifecycle.js';
 import { runRunOnMainThreadTask } from './runOnMainThread.js';
@@ -48,8 +49,9 @@ function registerWorklet(_type: string, id: string, worklet: (...args: unknown[]
  * Native event touch handler will call this function.
  * @param ctx worklet object.
  * @param params worklet params.
+ * @param options run worklet options.
  */
-function runWorklet(ctx: Worklet, params: ClosureValueType[]): unknown {
+function runWorklet(ctx: Worklet, params: ClosureValueType[], options?: RunWorkletOptions): unknown {
   if (!validateWorklet(ctx)) {
     console.warn('Worklet: Invalid worklet object: ' + JSON.stringify(ctx));
     return;
@@ -58,10 +60,10 @@ function runWorklet(ctx: Worklet, params: ClosureValueType[]): unknown {
     delayExecUntilJsReady(ctx._lepusWorkletHash, params);
     return;
   }
-  return runWorkletImpl(ctx, params);
+  return runWorkletImpl(ctx, params, options);
 }
 
-function runWorkletImpl(ctx: Worklet, params: ClosureValueType[]): unknown {
+function runWorkletImpl(ctx: Worklet, params: ClosureValueType[], options?: RunWorkletOptions): unknown {
   const worklet: (...args: unknown[]) => unknown = profile(
     'transformWorkletCtx ' + ctx._wkltId,
     () => transformWorklet(ctx, true),
@@ -70,7 +72,19 @@ function runWorkletImpl(ctx: Worklet, params: ClosureValueType[]): unknown {
     'transformWorkletParams',
     () => transformWorklet(params || [], false),
   );
-  return profile('runWorklet', () => worklet(...params_));
+
+  const [hasEventMethods, eventCtx] = addEventMethodsIfNeeded(params_, options);
+
+  const result = profile('runWorklet', () => worklet(...params_));
+
+  if (hasEventMethods) {
+    return {
+      returnValue: result,
+      eventReturnResult: eventCtx._eventReturnResult,
+    };
+  }
+
+  return result;
 }
 
 function validateWorklet(ctx: unknown): ctx is Worklet {
@@ -107,6 +121,7 @@ function transformWorklet(
   if (isWorklet) {
     workletCache.set(ctx, worklet.main);
   }
+
   return worklet.main;
 }