feat(react): support ET updateCardData bridge

packages/react/runtime/__test__/core/lynx-update-data.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { NativeUpdateDataType, updateCardData } from '../../src/core/lynx-update-data.js';
+import { LynxTestEventEmitter } from '../test-utils/lynx-event-emitter.js';
+
+describe('updateCardData', () => {
+  let originalInitData: typeof lynx.__initData;
+  let originalReportError: typeof lynx.reportError;
+  let originalGetJSModule: typeof lynx.getJSModule;
+  let emitter: LynxTestEventEmitter;
+
+  beforeEach(() => {
+    originalInitData = lynx.__initData;
+    originalReportError = lynx.reportError;
+    originalGetJSModule = lynx.getJSModule;
+    emitter = new LynxTestEventEmitter();
+    lynx.__initData = {};
+    lynx.reportError = vi.fn();
+    lynx.getJSModule = vi.fn((moduleName: string) => {
+      if (moduleName === 'GlobalEventEmitter') {
+        return emitter;
+      }
+      return originalGetJSModule(moduleName);
+    }) as typeof lynx.getJSModule;
+  });
+
+  afterEach(() => {
+    lynx.__initData = originalInitData;
+    lynx.reportError = originalReportError;
+    lynx.getJSModule = originalGetJSModule;
+  });
+
+  it('COW merges update data and emits the current patch data', () => {
+    const previousInitData = { msg: 'init', stable: true };
+    const listener = vi.fn();
+    lynx.__initData = previousInitData;
+    emitter.addListener('onDataChanged', listener);
+
+    updateCardData({
+      msg: 'update',
+      next: 1,
+    });
+
+    expect(lynx.__initData).toEqual({ msg: 'update', stable: true, next: 1 });
+    expect(lynx.__initData).not.toBe(previousInitData);
+    expect(listener).toHaveBeenCalledWith({ msg: 'update', next: 1 });
+    expect(lynx.reportError).not.toHaveBeenCalled();
+  });
+
+  it('clears existing initData before RESET updates', () => {
+    const listener = vi.fn();
+    lynx.__initData = { stale: true, msg: 'init' };
+    emitter.addListener('onDataChanged', listener);
+
+    updateCardData(
+      { msg: 'reset' },
+      { type: NativeUpdateDataType.RESET },
+    );
+
+    expect(lynx.__initData).toEqual({ msg: 'reset' });
+    expect(listener).toHaveBeenCalledWith({ msg: 'reset' });
+  });
+
+  it('keeps Snapshot-compatible loose RESET matching', () => {
+    const listener = vi.fn();
+    lynx.__initData = { stale: true, msg: 'init' };
+    emitter.addListener('onDataChanged', listener);
+
+    updateCardData(
+      { msg: 'reset' },
+      { type: '1' as unknown as NativeUpdateDataType },
+    );
+
+    expect(lynx.__initData).toEqual({ msg: 'reset' });
+    expect(listener).toHaveBeenCalledWith({ msg: 'reset' });
+  });
+
+  it('reports and strips __lynx_timing_flag from the merged data and emitted patch', () => {
+    const listener = vi.fn();
+    lynx.__initData = { msg: 'init' };
+    emitter.addListener('onDataChanged', listener);
+
+    updateCardData({
+      msg: 'update',
+      __lynx_timing_flag: '__lynx_timing_actual_fmp',
+    });
+
+    expect(lynx.__initData).toEqual({ msg: 'update' });
+    expect(listener).toHaveBeenCalledWith({ msg: 'update' });
+    expect(lynx.reportError).toHaveBeenCalledTimes(1);
+    expect(lynx.reportError).toHaveBeenCalledWith(
+      new Error(
+        'Received unsupported updateData with `__lynx_timing_flag` (value "__lynx_timing_actual_fmp"), the timing flag is ignored',
+      ),
+    );
+  });
+});

packages/react/runtime/__test__/element-template/fixtures/background/init-data-update/index.tsx

@@ -0,0 +1,11 @@
+import { useInitData } from '@lynx-js/react/element-template';
+
+export function App(): JSX.Element {
+  const data = useInitData() as { msg?: string };
+
+  return (
+    <view>
+      <text>{data.msg}</text>
+    </view>
+  );
+}

packages/react/runtime/__test__/element-template/native/index.test.ts

@@ -30,6 +30,7 @@ describe('element-template native index wiring', () => {
     vi.doUnmock('../../../src/element-template/debug/profile.js');
     vi.doUnmock('../../../src/element-template/lynx/env.js');
     vi.doUnmock('../../../src/element-template/lynx/performance.js');
+    vi.doUnmock('../../../src/core/lynx-update-data.js');
     vi.doUnmock('../../../src/element-template/runtime/page/root-instance.js');
   });
 
@@ -121,6 +122,7 @@ describe('element-template native index wiring', () => {
     const publishEvent = vi.fn();
     const publicComponentEvent = vi.fn();
     const resetEventStateForRuntime = vi.fn();
+    const updateCardData = vi.fn();
 
     vi.doMock('../../../src/element-template/native/main-thread-api.js', () => ({
       injectCalledByNative,
@@ -149,6 +151,9 @@ describe('element-template native index wiring', () => {
     vi.doMock('../../../src/element-template/lynx/performance.js', () => ({
       initTimingAPI,
     }));
+    vi.doMock('../../../src/core/lynx-update-data.js', () => ({
+      updateCardData,
+    }));
     vi.doMock('../../../src/element-template/runtime/page/root-instance.js', () => ({
       setRoot,
     }));
@@ -179,6 +184,7 @@ describe('element-template native index wiring', () => {
     expect(globalThis.lynxCoreInject.tt.callDestroyLifetimeFun).toBe(callDestroyLifetimeFun);
     expect(globalThis.lynxCoreInject.tt.publishEvent).toBe(publishEvent);
     expect(globalThis.lynxCoreInject.tt.publicComponentEvent).toBe(publicComponentEvent);
+    expect(globalThis.lynxCoreInject.tt.updateCardData).toBe(updateCardData);
 
     expect(injectCalledByNative).not.toHaveBeenCalled();
     expect(installElementTemplatePatchListener).not.toHaveBeenCalled();

packages/react/runtime/__test__/element-template/runtime/background/commit-hook.test.ts

@@ -158,6 +158,11 @@ describe('ElementTemplate commit hook', () => {
     });
     envManager.switchToBackground();
     expect(globalCommitContext.flushOptions).toEqual({});
+
+    options.__c?.({} as unknown as object, []);
+    envManager.switchToMainThread();
+    expect(updateEvents).toHaveLength(1);
+    envManager.switchToBackground();
   });
 
   it('dispatches triggerDataUpdated when useInitData observes a data change', () => {
@@ -279,6 +284,51 @@ describe('ElementTemplate commit hook', () => {
     }
   });
 
+  it('dispatches one data-updated payload for multiple initData readers', () => {
+    const dataChange = installDataChangeHarness();
+    let first: unknown;
+    let second: unknown;
+    let consumed: unknown;
+
+    try {
+      function App() {
+        first = useInitData();
+        second = useInitData();
+        return createElement(
+          InitDataProvider,
+          null,
+          createElement(InitDataConsumer, null, (initData: { msg?: string }) => {
+            consumed = initData;
+            return createElement('view');
+          }),
+        );
+      }
+
+      lynx.__initData = { msg: 'before' };
+      root.render(createElement(App, null));
+      expect(first).toEqual({ msg: 'before' });
+      expect(second).toEqual({ msg: 'before' });
+      expect(consumed).toEqual({ msg: 'before' });
+
+      markElementTemplateHydrated();
+      lynx.__initData = { msg: 'after' };
+      dataChange.emitDataChanged();
+      dataChange.flushScheduledRenders();
+
+      expect(first).toEqual({ msg: 'after' });
+      expect(second).toEqual({ msg: 'after' });
+      expect(consumed).toEqual({ msg: 'after' });
+      envManager.switchToMainThread();
+      expect(updateEvents).toHaveLength(1);
+      expect(updateEvents[0]).toMatchObject({
+        ops: [],
+        flushOptions: { triggerDataUpdated: true },
+      });
+    } finally {
+      dataChange.restore();
+    }
+  });
+
   it('skips dispatch before hydration', () => {
     globalCommitContext.ops = createRawTextOps(1, 'hello');
 
@@ -394,6 +444,27 @@ describe('ElementTemplate commit hook', () => {
     }));
   });
 
+  it('dispatches data-updated payload while flushing ref-only effects', () => {
+    const ref = vi.fn();
+    markElementTemplateHydrated();
+    globalCommitContext.flushOptions = { triggerDataUpdated: true };
+    queueRefAttrUpdate(null, ref, -2, 0);
+
+    options.__c?.({} as unknown as object, []);
+
+    envManager.switchToMainThread();
+    expect(updateEvents).toEqual([
+      {
+        ops: [],
+        flushOptions: { triggerDataUpdated: true },
+      },
+    ]);
+    envManager.switchToBackground();
+    expect(ref).toHaveBeenCalledWith(expect.objectContaining({
+      selector: '[ref=-2-0]',
+    }));
+  });
+
   it('flushes pre-hydration ref effects on commit without dispatching native ops', () => {
     const ref = vi.fn();
     queueRefAttrUpdate(null, ref, 1, 0);

packages/react/runtime/__test__/element-template/runtime/background/init-data-compiled-fixtures.test.tsx

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createElement } from 'preact';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  installElementTemplateCommitHook,
+  resetElementTemplateCommitState,
+} from '../../../../src/element-template/background/commit-hook.js';
+import {
+  installElementTemplateHydrationListener,
+  resetElementTemplateHydrationListener,
+} from '../../../../src/element-template/background/hydration-listener.js';
+import { root } from '../../../../src/element-template/index.js';
+import { updateCardData } from '../../../../src/core/lynx-update-data.js';
+import {
+  installElementTemplatePatchListener,
+  resetElementTemplatePatchListener,
+} from '../../../../src/element-template/native/patch-listener.js';
+import { ElementTemplateLifecycleConstant } from '../../../../src/element-template/protocol/lifecycle-constant.js';
+import type { ElementTemplateUpdateCommitContext } from '../../../../src/element-template/protocol/types.js';
+import { __page } from '../../../../src/element-template/runtime/page/page.js';
+import { clearEtAttrPlanMap } from '../../../../src/element-template/runtime/template/attr-slot-plan.js';
+import { LynxTestEventEmitter } from '../../../test-utils/lynx-event-emitter.js';
+import { compileFixtureSource } from '../../test-utils/debug/compiledFixtureCompiler.js';
+import { loadCompiledFixtureModule } from '../../test-utils/debug/compiledFixtureModule.js';
+import type { CompiledFixtureModuleExports } from '../../test-utils/debug/compiledFixtureModule.js';
+import { primeCompiledFixtureTemplates } from '../../test-utils/debug/compiledFixtureRegistry.js';
+import { ElementTemplateEnvManager } from '../../test-utils/debug/envManager.js';
+import { serializeToJSX } from '../../test-utils/debug/serializer.js';
+
+declare const renderPage: (data?: Record<string, unknown>) => void;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const FIXTURE = path.resolve(__dirname, '../../fixtures/background/init-data-update/index.tsx');
+
+function waitForRender(): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, 0));
+}
+
+async function loadCompiledInitDataFixture(): Promise<{
+  backgroundModule: CompiledFixtureModuleExports;
+  mainModule: CompiledFixtureModuleExports;
+}> {
+  const mainArtifact = await compileFixtureSource(FIXTURE, { target: 'LEPUS' });
+  primeCompiledFixtureTemplates(mainArtifact);
+  const mainModule = await loadCompiledFixtureModule(mainArtifact);
+
+  const backgroundArtifact = await compileFixtureSource(FIXTURE, { target: 'JS' });
+  const backgroundModule = await loadCompiledFixtureModule(backgroundArtifact);
+
+  return { backgroundModule, mainModule };
+}
+
+describe('Compiled ET InitData updateData fixture', () => {
+  const envManager = new ElementTemplateEnvManager();
+  let originalLynx: typeof lynx;
+  let emitter: LynxTestEventEmitter;
+  let updateEvents: ElementTemplateUpdateCommitContext[] = [];
+
+  const onUpdate = (event: { data: unknown }) => {
+    updateEvents.push(event.data as ElementTemplateUpdateCommitContext);
+  };
+
+  function installInitData(initData: Record<string, unknown>): void {
+    const baseLynx = globalThis.lynx;
+    vi.stubGlobal('lynx', {
+      ...baseLynx,
+      __initData: initData,
+      getJSModule(moduleName: string) {
+        if (moduleName === 'GlobalEventEmitter') {
+          return emitter;
+        }
+        return baseLynx.getJSModule?.(moduleName);
+      },
+    });
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    originalLynx = globalThis.lynx;
+    emitter = new LynxTestEventEmitter();
+    updateEvents = [];
+    resetElementTemplateCommitState();
+    clearEtAttrPlanMap();
+    envManager.resetEnv('background');
+    envManager.setUseElementTemplate(true);
+    installInitData({ msg: 'init' });
+    installElementTemplateCommitHook();
+    installElementTemplateHydrationListener();
+
+    envManager.switchToMainThread();
+    installElementTemplatePatchListener();
+    lynx.getJSContext().addEventListener(ElementTemplateLifecycleConstant.update, onUpdate);
+    envManager.switchToBackground();
+  });
+
+  afterEach(() => {
+    envManager.switchToMainThread();
+    lynx.getJSContext().removeEventListener(ElementTemplateLifecycleConstant.update, onUpdate);
+    resetElementTemplatePatchListener();
+    envManager.switchToBackground();
+    resetElementTemplateHydrationListener();
+    resetElementTemplateCommitState();
+    envManager.setUseElementTemplate(false);
+    vi.stubGlobal('lynx', originalLynx);
+  });
+
+  it('updates raw text after hydrated background updateCardData', async () => {
+    const { backgroundModule, mainModule } = await loadCompiledInitDataFixture();
+
+    envManager.switchToBackground();
+    root.render(createElement(backgroundModule.App));
+
+    envManager.switchToMainThread();
+    root.render(createElement(mainModule.App));
+    renderPage({ msg: 'init' });
+    expect(serializeToJSX(__page)).toContain('init');
+
+    envManager.switchToBackground();
+    updateEvents = [];
+    updateCardData({ msg: 'update' });
+    await waitForRender();
+
+    envManager.switchToMainThread();
+    expect(updateEvents.at(-1)?.flushOptions).toMatchObject({ triggerDataUpdated: true });
+    expect(updateEvents.at(-1)?.ops.length).toBeGreaterThan(0);
+    expect(serializeToJSX(__page)).toContain('update');
+    expect((__FlushElementTree as unknown as { mock: { calls: unknown[][] } }).mock.calls.at(-1)?.[1]).toMatchObject({
+      triggerDataUpdated: true,
+    });
+  });
+});