fix: reduce redundant updates for handlers and gestures

- Implement copy-on-commit for worklets, gestures, and spread props to avoid background-side mutation.
- Prevent _execId churn for stable references, reducing redundant native patches.
- Fix gesture removal cleanup when removed from spread props.
- Add regression tests for execId churn and gesture cleanup.
- Add changeset for @lynx-js/react-runtime.

Author: Yradex

.changeset/fix-react-runtime-execid-churn.md

@@ -0,0 +1,9 @@
+---
+"@lynx-js/react-runtime": patch
+---
+
+fix: reduce redundant updates for main-thread handlers and gestures
+
+- Updates are faster when the main-thread event handler or gesture object is stable across rerenders (fewer unnecessary native updates).
+- Spread props rerenders that don't semantically change the handler/gesture no longer trigger redundant updates.
+- Removing a gesture from spread props reliably clears the gesture state on the target element.

packages/react/runtime/__test__/gesture/prepareGestureForCommit.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { prepareGestureForCommit } from '../../src/gesture/processGestureBagkround';
+
+describe('prepareGestureForCommit', () => {
+  it('does not mutate input gesture and supports non-object callbacks', () => {
+    const gesture = {
+      id: 1,
+      type: 0,
+      callbacks: {
+        onUpdate: null,
+      },
+      __isGesture: true,
+      toJSON() {
+        const { toJSON, ...rest } = this;
+        return {
+          ...rest,
+          __isSerialized: true,
+        };
+      },
+    };
+
+    const committed = prepareGestureForCommit(gesture);
+    expect(committed).not.toBe(gesture);
+    expect(committed.callbacks).not.toBe(gesture.callbacks);
+    expect(committed.callbacks.onUpdate).toBe(null);
+
+    // Committed payload should serialize itself, not rely on the original object's toJSON.
+    const json = committed.toJSON();
+    expect(json.__isSerialized).toBe(true);
+  });
+});

packages/react/runtime/__test__/gesture/processGesture-remove.test.js

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { processGesture } from '../../src/gesture/processGesture';
+
+describe('processGesture', () => {
+  const originalSetAttribute = globalThis.__SetAttribute;
+
+  afterEach(() => {
+    globalThis.__SetAttribute = originalSetAttribute;
+  });
+
+  it('clears native gesture state when gesture is removed', () => {
+    const setAttribute = vi.fn();
+    globalThis.__SetAttribute = setAttribute;
+
+    const dom = {};
+    const oldGesture = {
+      type: 0,
+      __isSerialized: true,
+    };
+
+    processGesture(dom, undefined, oldGesture, false);
+
+    expect(setAttribute).toHaveBeenCalledWith(dom, 'has-react-gesture', null);
+    expect(setAttribute).toHaveBeenCalledWith(dom, 'flatten', null);
+    expect(setAttribute).toHaveBeenCalledWith(dom, 'gesture', null);
+  });
+
+  it('does not clear native state when domSet=true', () => {
+    const setAttribute = vi.fn();
+    globalThis.__SetAttribute = setAttribute;
+
+    const dom = {};
+    const oldGesture = {
+      type: 0,
+      __isSerialized: true,
+    };
+
+    processGesture(dom, undefined, oldGesture, false, { domSet: true });
+    expect(setAttribute).not.toHaveBeenCalled();
+  });
+
+  it('does not clear native state when oldGesture is not serialized', () => {
+    const setAttribute = vi.fn();
+    globalThis.__SetAttribute = setAttribute;
+
+    const dom = {};
+    const oldGesture = {
+      type: 0,
+      __isSerialized: false,
+    };
+
+    processGesture(dom, undefined, oldGesture, false);
+    expect(setAttribute).not.toHaveBeenCalled();
+  });
+});

packages/react/runtime/__test__/snapshot/mtf-execid-churn.test.jsx

@@ -0,0 +1,201 @@
+import { render } from 'preact';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useState } from '../../src/index';
+import { replaceCommitHook } from '../../src/lifecycle/patch/commit';
+import { injectUpdateMainThread } from '../../src/lifecycle/patch/updateMainThread';
+import { __root } from '../../src/root';
+import { setupPage } from '../../src/snapshot';
+import { globalEnvManager } from '../utils/envManager';
+import { elementTree, waitSchedule } from '../utils/nativeMethod';
+
+function getSnapshotPatchFromPatchUpdateCall(call) {
+  const obj = call[1];
+  const parsed = JSON.parse(obj.data);
+  return parsed.patchList?.[0]?.snapshotPatch;
+}
+
+beforeAll(() => {
+  setupPage(__CreatePage('0', 0));
+  injectUpdateMainThread();
+  replaceCommitHook();
+});
+
+beforeEach(() => {
+  globalEnvManager.resetEnv();
+  SystemInfo.lynxSdkVersion = '999.999';
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  elementTree.clear();
+});
+
+describe('Patch size / execId churn', () => {
+  it('MTF: stable ctx reference should not generate snapshotPatch', async function() {
+    const mtf = {
+      _wkltId: '835d:450ef:stable',
+    };
+
+    let bump_;
+    function Comp() {
+      const [, setTick] = useState(0);
+      bump_ = () => {
+        setTick(v => v + 1);
+      };
+      return (
+        <view>
+          <text main-thread:bindtap={mtf}>1</text>
+        </view>
+      );
+    }
+
+    // main thread render
+    {
+      __root.__jsx = <Comp />;
+      renderPage();
+    }
+
+    // background render
+    {
+      globalEnvManager.switchToBackground();
+      render(<Comp />, __root);
+    }
+
+    // hydrate
+    {
+      lynxCoreInject.tt.OnLifecycleEvent(...globalThis.__OnLifecycleEvent.mock.calls[0]);
+
+      globalEnvManager.switchToMainThread();
+      const rLynxChange = lynx.getNativeApp().callLepusMethod.mock.calls[0];
+      globalThis[rLynxChange[0]](rLynxChange[1]);
+    }
+
+    // rerender with no semantic changes
+    {
+      globalEnvManager.switchToBackground();
+      lynx.getNativeApp().callLepusMethod.mockClear();
+      bump_();
+      await waitSchedule();
+
+      globalEnvManager.switchToMainThread();
+      const rLynxChange = lynx.getNativeApp().callLepusMethod.mock.calls[0];
+      expect(getSnapshotPatchFromPatchUpdateCall(rLynxChange)).toBeUndefined();
+    }
+  });
+
+  it('spread: stable semantics should not generate snapshotPatch', async function() {
+    let bump_;
+    function Comp() {
+      const [, setTick] = useState(0);
+      bump_ = () => {
+        setTick(v => v + 1);
+      };
+      // Simulate typical compiled output: a fresh ctx object each render.
+      // `_wkltId` stays the same, but runtime injects `_execId`, causing patch churn.
+      const spread = {
+        'main-thread:bindtap': {
+          _wkltId: '835d:450ef:stable',
+        },
+      };
+      return (
+        <view>
+          <text {...spread}>1</text>
+        </view>
+      );
+    }
+
+    // main thread render
+    {
+      __root.__jsx = <Comp />;
+      renderPage();
+    }
+
+    // background render
+    {
+      globalEnvManager.switchToBackground();
+      render(<Comp />, __root);
+    }
+
+    // hydrate
+    {
+      lynxCoreInject.tt.OnLifecycleEvent(...globalThis.__OnLifecycleEvent.mock.calls[0]);
+
+      globalEnvManager.switchToMainThread();
+      const rLynxChange = lynx.getNativeApp().callLepusMethod.mock.calls[0];
+      globalThis[rLynxChange[0]](rLynxChange[1]);
+    }
+
+    // rerender with no semantic changes
+    {
+      globalEnvManager.switchToBackground();
+      lynx.getNativeApp().callLepusMethod.mockClear();
+      bump_();
+      await waitSchedule();
+
+      globalEnvManager.switchToMainThread();
+      const rLynxChange = lynx.getNativeApp().callLepusMethod.mock.calls[0];
+      expect(getSnapshotPatchFromPatchUpdateCall(rLynxChange)).toBeUndefined();
+    }
+  });
+
+  it('gesture: stable gesture reference should not generate snapshotPatch', async function() {
+    const stableGesture = {
+      id: 1,
+      type: 0,
+      callbacks: {
+        onUpdate: {
+          _wkltId: 'bdd4:dd564:stable',
+        },
+      },
+      __isGesture: true,
+      toJSON() {
+        const { toJSON, ...rest } = this;
+        return {
+          ...rest,
+          __isSerialized: true,
+        };
+      },
+    };
+
+    function Comp(_props) {
+      return (
+        <view>
+          <text main-thread:gesture={stableGesture}>1</text>
+        </view>
+      );
+    }
+
+    // main thread render
+    {
+      __root.__jsx = <Comp tick={0} />;
+      renderPage();
+    }
+
+    // background render
+    {
+      globalEnvManager.switchToBackground();
+      render(<Comp tick={0} />, __root);
+    }
+
+    // hydrate
+    {
+      lynxCoreInject.tt.OnLifecycleEvent(...globalThis.__OnLifecycleEvent.mock.calls[0]);
+
+      globalEnvManager.switchToMainThread();
+      const rLynxChange = lynx.getNativeApp().callLepusMethod.mock.calls[0];
+      globalThis[rLynxChange[0]](rLynxChange[1]);
+    }
+
+    // rerender with no semantic changes
+    {
+      globalEnvManager.switchToBackground();
+      lynx.getNativeApp().callLepusMethod.mockClear();
+      render(<Comp tick={1} />, __root);
+
+      globalEnvManager.switchToMainThread();
+      const rLynxChange = lynx.getNativeApp().callLepusMethod.mock.calls[0];
+      expect(getSnapshotPatchFromPatchUpdateCall(rLynxChange)).toBeUndefined();
+    }
+  });
+});