feat: add MainThreadValue

.changeset/better-pigs-run.md

@@ -0,0 +1,42 @@
+---
+'@lynx-js/react': patch
+---
+
+Add support for `MainThreadValue` to enable Main Thread Persistent Data other than `MainThreadRef`, to make library developers able to create their own main thread values.
+
+```
+// Library code
+import { MainThreadValue } from '@lynx-js/react'
+
+class MotionValue extends MainThreadValue {
+  static type = '@example/motion-value';
+
+  constructor(initValue: T) {
+    super(initValue, MotionValue.type);
+  }
+
+  get value() {
+    return this.getValueOnMainThread();
+  }
+
+  set value(v) {
+    return this.setValueOnMainThread(v);
+  }
+}
+
+MainThreadValue.register(MotionValue, MotionValue.type);
+
+export function useMotionValue<T>(initValue: T): MotionValue<T> {
+  return useMemo(() => new MotionValue(initValue), []);
+}
+
+// User code
+function App() {
+  const opacity = useMotionValue(1);
+
+  function handleTap() {
+    'main thread'
+    opacity.value = 123
+  }
+}
+```

examples/react/src/App.tsx

@@ -1,28 +1,80 @@
-import { useCallback, useEffect, useState } from '@lynx-js/react';
+import {
+  runOnMainThread,
+  useCallback,
+  useEffect,
+  useState,
+} from '@lynx-js/react';
 
-import './App.css';
 import arrow from './assets/arrow.png';
 import lynxLogo from './assets/lynx-logo.png';
 import reactLynxLogo from './assets/react-logo.png';
+import { useMotionValue } from './MotionValue.js';
+
+import './App.css';
 
 export function App() {
   const [alterLogo, setAlterLogo] = useState(false);
 
+  // NEW: MotionValue POC (uses .value) - demonstrates extensible main thread values!
+  const opacity = useMotionValue(1);
+  const tapCount = useMotionValue(0);
+
   useEffect(() => {
     console.info('Hello, ReactLynx');
+
+    let unsubscribeHandle: (() => void) | undefined;
+
+    runOnMainThread(() => {
+      'main thread';
+
+      // Demo: Subscribe to value changes (main thread only)
+      const unsubscribe = opacity.subscribe((newValue) => {
+        console.info('Opacity changed to:', newValue);
+      });
+
+      // Demo: Subscribe to value changes (main thread only)
+      const unsubscribeTapCount = tapCount.subscribe((newValue) => {
+        console.info('TapCount changed to:', newValue);
+      });
+
+      return () => {
+        unsubscribe();
+        unsubscribeTapCount();
+      };
+    })().then((res) => {
+      unsubscribeHandle = res as () => void;
+    }).catch(_err => {
+      // omitted
+    });
+
+    return () => {
+      void runOnMainThread(unsubscribeHandle!)();
+    };
   }, []);
 
   const onTap = useCallback(() => {
     'background-only';
     setAlterLogo(prevAlterLogo => !prevAlterLogo);
   }, []);
 
+  // Demo: MotionValue in tap handler
+  const onLogoTap = () => {
+    'main thread';
+    tapCount.value += 1;
+    // Animate opacity based on tap count
+    opacity.value = 0.5 + (tapCount.value % 2) * 0.5;
+  };
+
   return (
     <view>
       <view className='Background' />
       <view className='App'>
         <view className='Banner'>
-          <view className='Logo' bindtap={onTap}>
+          <view
+            className='Logo'
+            bindtap={onTap}
+            main-thread:bindtap={onLogoTap}
+          >
             {alterLogo
               ? <image src={reactLynxLogo} className='Logo--react' />
               : <image src={lynxLogo} className='Logo--lynx' />}

examples/react/src/MotionValue.ts

@@ -0,0 +1,63 @@
+/**
+ * MotionValue POC using the MainThreadValue base class.
+ *
+ * This demonstrates how third-party packages can create their own
+ * main thread value types by extending MainThreadValue.
+ */
+import { MainThreadValue, useMemo } from '@lynx-js/react';
+
+/**
+ * A simple motion value that can be accessed on the main thread.
+ * Uses `.value` instead of `.current` to demonstrate the new extensibility.
+ */
+export class MotionValue<T> extends MainThreadValue<T> {
+  private _subscribers: Set<(value: T) => void> = new Set();
+
+  constructor(initValue: T, type = '@example/motion-value') {
+    super(initValue, type);
+  }
+
+  /**
+   * Get the current value. Only works on main thread.
+   */
+  get value(): T {
+    try {
+      return this.getValueOnMainThread();
+    } catch (_e) {
+      // Allow access on background thread for capture (returns undefined/garbage, which is ignored)
+      return this._initValue;
+    }
+  }
+
+  /**
+   * Set the current value. Only works on main thread.
+   * Notifies all subscribers when value changes.
+   */
+  set value(v: T) {
+    this.setValueOnMainThread(v);
+    // Notify subscribers
+    this._subscribers.forEach(cb => cb(v));
+  }
+
+  /**
+   * Subscribe to value changes.
+   * @param callback - Called with the new value when it changes
+   * @returns Unsubscribe function
+   */
+  subscribe(callback: (value: T) => void): () => void {
+    this._subscribers.add(callback);
+    return () => {
+      this._subscribers.delete(callback);
+    };
+  }
+}
+
+// Register for runtime hydration
+MainThreadValue.register(MotionValue, '@example/motion-value');
+
+/**
+ * Hook to create a MotionValue that persists across renders.
+ */
+export function useMotionValue<T>(initValue: T): MotionValue<T> {
+  return useMemo(() => new MotionValue(initValue), []);
+}

packages/react/runtime/src/index.ts

@@ -84,3 +84,4 @@ export {
 };
 
 export * from './lynx-api.js';
+export { workletCapture } from './worklet/capture.js';

packages/react/runtime/src/internal.ts

@@ -70,3 +70,4 @@ export { transformToWorklet } from './worklet/call/transformToWorklet.js';
 export { registerWorkletOnBackground } from './worklet/hmr.js';
 
 export { loadWorkletRuntime } from '@lynx-js/react/worklet-runtime/bindings';
+export { workletCapture } from './worklet/capture.js';

packages/react/runtime/src/lynx-api.ts

@@ -462,3 +462,4 @@ export { useLynxGlobalEventListener } from './hooks/useLynxGlobalEventListener.j
 export { runOnBackground } from './worklet/call/runOnBackground.js';
 export { runOnMainThread } from './worklet/call/runOnMainThread.js';
 export { MainThreadRef, useMainThreadRef } from './worklet/ref/workletRef.js';
+export { MainThreadValue } from './worklet/ref/mainThreadValue.js';

packages/react/runtime/src/worklet/capture.ts

@@ -0,0 +1,25 @@
+// 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.
+
+/**
+ * Worklet capture helper function.
+ * Called by SWC plugin to preserve MainThreadValue objects during closure extraction.
+ * @internal
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Called by generated code with dynamic args
+export function workletCapture(
+  obj: unknown,
+  ...args: unknown[]
+): unknown {
+  // If it's a Main Thread Value (e.g. MotionValue), return it (ID will be serialized)
+  if (obj && typeof obj === 'object' && (obj as { __MT_PERSIST__?: boolean }).__MT_PERSIST__) {
+    return obj;
+  }
+  // Otherwise, reconstruct a lightweight object with only the captured properties
+  const result: Record<string, unknown> = {};
+  for (let i = 0; i < args.length; i += 2) {
+    result[args[i] as string] = args[i + 1];
+  }
+  return result;
+}