Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

packages/react/worklet-runtime/src/bindings/types.ts (1)

70-72: EventCtx is fine; consider documenting and minor naming tidy-up

• Add a brief JSDoc explaining the bitmask semantics and when it’s populated (via event propagation methods).
• Optional: drop the quotes around the property name for consistency with other interfaces.

.changeset/clear-crabs-swim.md (1)

5-25: Good changeset; call out SDK requirement and return wrapper behavior

Explicitly document:

• Minimum Lynx SDK 3.5 for stopPropagation/stopImmediatePropagation.
• When an event object is the first argument, worklets return { returnValue, __EventReturnResult } (wrapped), otherwise raw value.

Apply this edit for clarity:

 Add `event.stopPropagation` and `event.stopImmediatePropagation` in MTS, to help with event propagation control
+
+- Requires Lynx SDK >= 3.5.
+- When a worklet is invoked with an event object (first argument has `target` and `currentTarget`),
+  its return is wrapped as `{ returnValue, __EventReturnResult }`. Otherwise, the raw return value is used.

As per coding guidelines

packages/react/worklet-runtime/__test__/eventPropagation.test.js (2)

23-25: Use mockRestore instead of mockReset

Restore the original console.warn after tests to avoid leaking spies across suites.

-  afterAll(() => {
-    consoleMock.mockReset();
-  });
+  afterAll(() => {
+    consoleMock.mockRestore();
+  });

---

27-80: Prefer EventResult constants in assertions

Import and assert against EventResult to avoid magic numbers and keep tests resilient to future bit changes.

-import { initWorklet } from '../src/workletRuntime';
+import { initWorklet } from '../src/workletRuntime';
+import { EventResult } from '../src/eventPropagation';

-  expect(ret).toMatchObject({
-    returnValue: undefined,
-    __EventReturnResult: 1,
-  });
+  expect(ret).toMatchObject({
+    returnValue: undefined,
+    __EventReturnResult: EventResult.kStopPropagationMask,
+  });
…
-  expect(ret).toMatchObject({
-    returnValue: undefined,
-    __EventReturnResult: 2,
-  });
+  expect(ret).toMatchObject({
+    returnValue: undefined,
+    __EventReturnResult: EventResult.kStopImmediatePropagationMask,
+  });
…
-  expect(ret).toMatchObject({
-    returnValue: undefined,
-    __EventReturnResult: 0x1 | 0x2,
-  });
+  expect(ret).toMatchObject({
+    returnValue: undefined,
+    __EventReturnResult: EventResult.kStopPropagationMask | EventResult.kStopImmediatePropagationMask,
+  });

packages/react/worklet-runtime/src/eventPropagation.ts (3)

8-14: Expose a typed alias for the bitmask (optional)

Define and export a type to reflect valid mask values and aid consumers/tests.

 export const EventResult = {
   kDefault: 0x0,
   kStopPropagationMask: 0x1,
   kStopImmediatePropagationMask: 0x2,
 } as const;
+
+export type EventReturnResult = typeof EventResult[keyof typeof EventResult];

---

17-26: Tighten event detection (optional)

Guard against null and limit to own properties to avoid prototype pollution issues.

-export function isEventObject(ctx: ClosureValueType[]): ctx is [EventLike, ...ClosureValueType[]] {
-  if (!Array.isArray(ctx) || typeof ctx[0] !== 'object') {
+export function isEventObject(ctx: ClosureValueType[]): ctx is [EventLike, ...ClosureValueType[]] {
+  if (!Array.isArray(ctx) || ctx[0] == null || typeof ctx[0] !== 'object') {
     return false;
   }
-  const eventObj = ctx[0] as Record<string, ClosureValueType>;
-  if (eventObj && 'target' in eventObj && 'currentTarget' in eventObj) {
+  const eventObj = ctx[0] as Record<string, ClosureValueType>;
+  if (Object.prototype.hasOwnProperty.call(eventObj, 'target')
+    && Object.prototype.hasOwnProperty.call(eventObj, 'currentTarget')) {
     return true;
   }
   return false;
 }

---

32-52: Define non-enumerable methods and avoid overwriting preexisting ones

Prevents polluting event payloads during iteration and avoids clobbering existing API if present.

 export function addEventPropagationMethods(ctx: [EventLike, ...ClosureValueType[]], eventCtx: EventCtx): void {
   const eventObj = ctx[0];

-  // Add stopPropagation method
-  eventObj['stopPropagation'] = function() {
+  // Add stopPropagation method
+  if (!('stopPropagation' in eventObj)) {
+    Object.defineProperty(eventObj, 'stopPropagation', {
+      enumerable: false,
+      configurable: true,
+      writable: true,
+      value: function() {
     if (!isSdkVersionGt(3, 4)) {
       throw new Error('stopPropagation requires Lynx sdk version 3.5');
     }
     eventCtx._eventReturnResult = (eventCtx._eventReturnResult ?? EventResult.kDefault)
       | EventResult.kStopPropagationMask;
-  };
+      },
+    });
+  }

   // Add stopImmediatePropagation method
-  eventObj['stopImmediatePropagation'] = function() {
+  if (!('stopImmediatePropagation' in eventObj)) {
+    Object.defineProperty(eventObj, 'stopImmediatePropagation', {
+      enumerable: false,
+      configurable: true,
+      writable: true,
+      value: function() {
     if (!isSdkVersionGt(3, 4)) {
       throw new Error('stopImmediatePropagation requires Lynx sdk version 3.5');
     }
     eventCtx._eventReturnResult = (eventCtx._eventReturnResult ?? EventResult.kDefault)
       | EventResult.kStopImmediatePropagationMask;
-  };
+      },
+    });
+  }
 }

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

packages/react/worklet-runtime/__test__/eventPropagation.test.js (5)

24-26: Restore the spy instead of just resetting it.

Use mockRestore() to avoid leaking the spied method across suites.

 afterAll(() => {
-  consoleMock.mockReset();
+  consoleMock.mockRestore();
 });

---

28-28: Rename test titles to the current field name.

Titles still say “__EventReturnResult”. Align with eventReturnResult.

-it('stopPropagation should have __EventReturnResult be 1', async () => {
+it('stopPropagation should have eventReturnResult be 1', async () => {

-it('stopImmediatePropagation should have __EventReturnResult be 2', async () => {
+it('stopImmediatePropagation should have eventReturnResult be 2', async () => {

-it('call stopPropagation and stopImmediatePropagation should have __EventReturnResult be 3', async () => {
+it('call stopPropagation and stopImmediatePropagation should have eventReturnResult be 3', async () => {

Also applies to: 48-48, 68-68

---

30-34: Remove no-op bind() calls inside the worklet fns.

_workletMap['1'].bind(this) return value is unused and has no effect.

-      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
 
       event.stopPropagation();

-      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
       event.stopImmediatePropagation();

Also applies to: 50-53, 70-74, 95-97, 115-118

---

4-9: Assert with exported bitmask constants to avoid magic numbers.

Import EventResult and use the flags in expectations.

 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';
+import { EventResult } from '../src/eventPropagation';
@@
     expect(ret).toMatchObject({
       returnValue: undefined,
-      eventReturnResult: 1,
+      eventReturnResult: EventResult.kStopPropagationMask,
     });
@@
     expect(ret).toMatchObject({
       returnValue: undefined,
-      eventReturnResult: 2,
+      eventReturnResult: EventResult.kStopImmediatePropagationMask,
     });
@@
     expect(ret).toMatchObject({
       returnValue: undefined,
-      eventReturnResult: 0x1 | 0x2,
+      eventReturnResult:
+        EventResult.kStopPropagationMask | EventResult.kStopImmediatePropagationMask,
     });

Also applies to: 42-45, 62-65, 83-86

---

87-88: Optional: Add a baseline test for “no calls ⇒ 0”.

This will assert default behavior. Requires runtime to coalesce undefined to 0 (see runtime comment).

   });
 
+  it('no propagation calls should have eventReturnResult be 0', async () => {
+    initWorklet();
+    const fn = vi.fn(function(event) {
+      // intentionally do nothing
+    });
+    globalThis.registerWorklet('main-thread', '1', fn);
+    const ret = globalThis.runWorklet(
+      { _wkltId: '1' },
+      [{ target: {}, currentTarget: {} }],
+      { source: RunWorkletSource.EVENT },
+    );
+    expect(ret).toMatchObject({
+      returnValue: undefined,
+      eventReturnResult: 0,
+    });
+  });

packages/react/worklet-runtime/src/workletRuntime.ts (2)

76-81: Compute event detection once and default eventReturnResult to 0.

Prevents inconsistencies if the event object is mutated during handler execution and guarantees a numeric return for event-sourced invocations.

-  const eventCtx: EventCtx = {};
-
-  if (isEventObject(params_, options)) {
-    addEventPropagationMethods(params_, eventCtx);
-  }
+  const eventCtx: EventCtx = {};
+  const isEvent = isEventObject(params_, options);
+  if (isEvent) {
+    // Narrow to `[event, ...rest]` for augmentation; object shape is not relied upon further.
+    addEventPropagationMethods(
+      params_ as [Record<string, ClosureValueType>, ...ClosureValueType[]],
+      eventCtx,
+    );
+  }
   const result = profile('runWorklet', () => worklet(...params_));
 
-  const eventReturnResult = eventCtx._eventReturnResult;
+  const eventReturnResult = eventCtx._eventReturnResult ?? 0;
 
-  // Check if any event object has _eventResult set and include it in return
-  if (isEventObject(params_, options)) {
+  // For event-sourced invocations, always include the propagation bitmask.
+  if (isEvent) {
     return {
       returnValue: result,
-      eventReturnResult: eventReturnResult,
+      eventReturnResult,
     };
   }

Also applies to: 83-91

---

85-86: Comment drift.

The comment mentions “include if set,” but code now always returns eventReturnResult for event runs. Update comment or condition for clarity.

-  // Check if any event object has _eventResult set and include it in return
+  // For event-sourced invocations, include the propagation bitmask in the return value.

packages/react/worklet-runtime/src/eventPropagation.ts (2)

22-29: Tighten and simplify the type guard.

Minor simplification; keeps semantics identical.

-  if (!Array.isArray(ctx) || typeof ctx[0] !== 'object' || ctx[0] === null) {
-    return false;
-  }
-  if (options && options.source === RunWorkletSource.EVENT) {
-    return true;
-  }
-  return false;
+  return (
+    Array.isArray(ctx) &&
+    typeof ctx[0] === 'object' &&
+    ctx[0] !== null &&
+    options?.source === RunWorkletSource.EVENT
+  );

---

39-56: Define propagation methods as non-enumerable.

Prevents polluting user iteration over event fields and avoids accidental serialization of helper functions.

-  // Add stopPropagation method
-  eventObj['stopPropagation'] = function() {
-    if (!isSdkVersionGt(3, 4)) {
-      throw new Error('stopPropagation requires Lynx sdk version 3.5');
-    }
-    eventCtx._eventReturnResult = (eventCtx._eventReturnResult ?? EventResult.kDefault)
-      | EventResult.kStopPropagationMask;
-  };
+  // Add stopPropagation method
+  Object.defineProperty(eventObj, 'stopPropagation', {
+    value: function stopPropagation() {
+      if (!isSdkVersionGt(3, 4)) {
+        throw new Error('stopPropagation requires Lynx sdk version 3.5');
+      }
+      eventCtx._eventReturnResult =
+        (eventCtx._eventReturnResult ?? EventResult.kDefault) | EventResult.kStopPropagationMask;
+    },
+    enumerable: false,
+    configurable: true,
+  });
@@
-  // Add stopImmediatePropagation method
-  eventObj['stopImmediatePropagation'] = function() {
-    if (!isSdkVersionGt(3, 4)) {
-      throw new Error('stopImmediatePropagation requires Lynx sdk version 3.5');
-    }
-    eventCtx._eventReturnResult = (eventCtx._eventReturnResult ?? EventResult.kDefault)
-      | EventResult.kStopImmediatePropagationMask;
-  };
+  // Add stopImmediatePropagation method
+  Object.defineProperty(eventObj, 'stopImmediatePropagation', {
+    value: function stopImmediatePropagation() {
+      if (!isSdkVersionGt(3, 4)) {
+        throw new Error('stopImmediatePropagation requires Lynx sdk version 3.5');
+      }
+      eventCtx._eventReturnResult =
+        (eventCtx._eventReturnResult ?? EventResult.kDefault) |
+        EventResult.kStopImmediatePropagationMask;
+    },
+    enumerable: false,
+    configurable: true,
+  });

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

.changeset/clear-crabs-swim.md (1)

18-23: Define handleOuterTap in the snippet

The example references handleOuterTap, but it isn’t defined anywhere in the block. When readers paste this into their project (or docs tooling renders it with type checking), they’ll hit an undefined identifier. Please add a minimal stub (e.g., function handleOuterTap() { 'main thread'; }) to keep the sample self-contained.

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

.changeset/clear-crabs-swim.md (2)

7-25: Complete the example by defining handleOuterTap; fix minor comment casing.

Add a no-op outer handler so the snippet is self-contained, and use “Outer tap” (lowercase) for readability.

 function App() {
+  function handleOuterTap(event: MainThread.TouchEvent) {
+    'main thread';
+    // outer handler won't run when inner handler stops propagation
+  }
   function handleInnerTap(event: MainThread.TouchEvent) {
     'main thread';
     event.stopPropagation();
     // Or stop immediate propagation with
     // event.stopImmediatePropagation();
   }

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

---

27-27: Specify the minimum version in the note.

Replace “latest” with the first released version containing this feature (e.g., “@lynx-js/react >= X.Y.Z”) once known.

packages/react/worklet-runtime/__test__/eventPropagation.test.js (2)

28-28: Update test titles to match the current return key.

Reflect eventReturnResult in descriptions.

-it('stopPropagation should have __EventReturnResult be 1', async () => {
+it('stopPropagation should have eventReturnResult be 1', async () => {

-it('stopImmediatePropagation should have __EventReturnResult be 2', async () => {
+it('stopImmediatePropagation should have eventReturnResult be 2', async () => {

-it('call stopPropagation and stopImmediatePropagation should have __EventReturnResult be 3', async () => {
+it('calling both should have eventReturnResult be 3', async () => {

Also applies to: 48-48, 68-68

---

30-34: Remove no-op bind() lines for clarity.

These bind() calls return a function that’s never used; they add noise without affecting behavior.

-    const fn = vi.fn(function(event) {
-      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
-
-      event.stopPropagation();
-    });
+    const fn = vi.fn(function(event) {
+      event.stopPropagation();
+    });

-    const fn = vi.fn(function(event) {
-      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
-      event.stopImmediatePropagation();
-    });
+    const fn = vi.fn(function(event) {
+      event.stopImmediatePropagation();
+    });

-    const fn = vi.fn(function(event) {
-      globalThis.lynxWorkletImpl._workletMap['1'].bind(this);
-      event.stopImmediatePropagation();
-      event.stopPropagation();
-    });
+    const fn = vi.fn(function(event) {
+      event.stopImmediatePropagation();
+      event.stopPropagation();
+    });

Also applies to: 50-53, 70-74

packages/react/worklet-runtime/src/workletRuntime.ts (3)

60-63: Consider forwarding options through the legacy delay path.

Even if the legacy _lepusWorkletHash branch isn’t used today, threading options keeps APIs consistent and future-proof.

-    delayExecUntilJsReady(ctx._lepusWorkletHash, params);
+    delayExecUntilJsReady(ctx._lepusWorkletHash, params, options);

Additionally (outside this diff), update delayWorkletEvent.ts to accept and pass options?: RunWorkletOptions through to runWorkletImpl(...).

---

80-85: Default eventReturnResult to 0 for a stable numeric type.

Prevents undefined when no propagation method is called, simplifying consumers.

     return {
       returnValue: result,
-      eventReturnResult: eventCtx._eventReturnResult,
+      eventReturnResult: eventCtx._eventReturnResult ?? 0,
     };

---

52-55: Document the return shape change in JSDoc.

Clarify that event invocations return { returnValue, eventReturnResult }, otherwise the raw result.

  * @param params worklet params.
- * @param options run worklet options.
+ * @param options run worklet options. When `options.source === RunWorkletSource.EVENT`,
+ *   the return value is `{ returnValue, eventReturnResult }`; otherwise it is the worklet’s raw return.

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Learnt from: f0rdream
PR: lynx-family/lynx-stack#1835
File: packages/react/worklet-runtime/src/workletRuntime.ts:52-55
Timestamp: 2025-09-28T08:46:43.167Z
Learning: The legacy worklet path with `_lepusWorkletHash` in `packages/react/worklet-runtime/src/workletRuntime.ts` is preserved for compatibility with MTS (Mini-app Threading Service) that doesn't support Initial Frame Rendering. This path will not be touched in current implementations.

Learnt from: upupming
PR: lynx-family/lynx-stack#1305
File: packages/testing-library/testing-environment/src/index.ts:255-258
Timestamp: 2025-08-11T05:57:18.212Z
Learning: In the ReactLynx testing environment (`packages/testing-library/testing-environment/src/index.ts`), the dual assignment pattern `target.console.method = console.method = () => {}` is required for rstest compatibility. This is because rstest provides `console` in an IIFE (Immediately Invoked Function Expression), and both the target and global console need to have these methods defined for proper test execution.

packages/react/worklet-runtime/__test__/workletRuntime.test.js (1)

341-355: Strengthen assertions for event helpers

Also assert they’re functions (not just defined) to catch shape regressions.

Apply this diff:

-      expect(event.stopPropagation).toBeDefined();
-      expect(event.stopImmediatePropagation).toBeDefined();
+      expect(typeof event.stopPropagation).toBe('function');
+      expect(typeof event.stopImmediatePropagation).toBe('function');

packages/react/worklet-runtime/__test__/eventPropagation.test.js (4)

6-9: Assert with named bitmasks instead of magic numbers

Import EventResult and use its masks in expectations for clarity and durability.

Apply this diff:

 import { initApiEnv } from '../src/api/lynxApi';
 import { RunWorkletSource } from '../src/bindings/types';
 import { initWorklet } from '../src/workletRuntime';
+import { EventResult } from '../src/eventPropagation';

---

28-46: Rename test to reflect eventReturnResult and use constants

Update the title (old __EventReturnResult wording) and assert via EventResult.kStopPropagationMask.

Apply this diff:

-  it('stopPropagation should have __EventReturnResult be 1', async () => {
+  it('stopPropagation should set eventReturnResult to kStopPropagationMask', async () => {
@@
-    expect(ret).toMatchObject({
-      returnValue: undefined,
-      eventReturnResult: 1,
-    });
+    expect(ret).toMatchObject({
+      returnValue: undefined,
+      eventReturnResult: EventResult.kStopPropagationMask,
+    });

---

48-66: Likewise for stopImmediatePropagation

Use the named mask and fix the title.

Apply this diff:

-  it('stopImmediatePropagation should have __EventReturnResult be 2', async () => {
+  it('stopImmediatePropagation should set eventReturnResult to kStopImmediatePropagationMask', async () => {
@@
-    expect(ret).toMatchObject({
-      returnValue: undefined,
-      eventReturnResult: 2,
-    });
+    expect(ret).toMatchObject({
+      returnValue: undefined,
+      eventReturnResult: EventResult.kStopImmediatePropagationMask,
+    });

---

68-88: Combine masks via constants in the “both-called” case

Prefer constants over 0x1 | 0x2 and refresh the title.

Apply this diff:

-  it('call stopPropagation and stopImmediatePropagation should have __EventReturnResult be 3', async () => {
+  it('calling both should OR eventReturnResult masks', async () => {
@@
-    expect(ret).toMatchObject({
-      returnValue: undefined,
-      eventReturnResult: 0x1 | 0x2,
-    });
+    expect(ret).toMatchObject({
+      returnValue: undefined,
+      eventReturnResult:
+        EventResult.kStopPropagationMask | EventResult.kStopImmediatePropagationMask,
+    });

packages/react/worklet-runtime/src/eventPropagation.ts (1)

43-53: Optional: make helper methods non‑enumerable

To align with DOM Event semantics and avoid polluting object iteration, define properties as non‑enumerable.

Apply this diff:

-  eventObj['stopPropagation'] = stopPropagation as unknown as ClosureValueType;
+  Object.defineProperty(eventObj, 'stopPropagation', {
+    value: stopPropagation,
+    enumerable: false,
+  });
@@
-  eventObj['stopImmediatePropagation'] =
-    stopImmediatePropagation as unknown as ClosureValueType;
+  Object.defineProperty(eventObj, 'stopImmediatePropagation', {
+    value: stopImmediatePropagation,
+    enumerable: false,
+  });

packages/react/worklet-runtime/src/workletRuntime.ts (1)

54-64: Legacy lepus path drops options (FYI)

The _lepusWorkletHash branch doesn’t forward options, so EVENT helpers wouldn’t attach if this path were used. If this path truly isn’t touched in current MTS flows, no action needed; otherwise consider threading options through delayExecUntilJsReady.

Based on learnings

-    delayExecUntilJsReady(ctx._lepusWorkletHash, params);
+    // If legacy path is exercised, forward options as well.
+    delayExecUntilJsReady(ctx._lepusWorkletHash, params, options);

Note: would also require updating delayWorkletEvent.ts to carry options to runWorkletImpl.

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Learnt from: f0rdream
PR: lynx-family/lynx-stack#1835
File: packages/react/worklet-runtime/src/workletRuntime.ts:52-55
Timestamp: 2025-09-28T08:46:43.167Z
Learning: The legacy worklet path with `_lepusWorkletHash` in `packages/react/worklet-runtime/src/workletRuntime.ts` is preserved for compatibility with MTS (Mini-app Threading Service) that doesn't support Initial Frame Rendering. This path will not be touched in current implementations.

Learnt from: upupming
PR: lynx-family/lynx-stack#1305
File: packages/testing-library/testing-environment/src/index.ts:255-258
Timestamp: 2025-08-11T05:57:18.212Z
Learning: In the ReactLynx testing environment (`packages/testing-library/testing-environment/src/index.ts`), the dual assignment pattern `target.console.method = console.method = () => {}` is required for rstest compatibility. This is because rstest provides `console` in an IIFE (Immediately Invoked Function Expression), and both the target and global console need to have these methods defined for proper test execution.