feat(Worklets): custom serialization support (#8600)

## Summary

Adding a feature to register Custom Serializables - a way to transfer
objects between runtimes that can't be trivially serialized or
deserialized - like primitives, or objects without circular references,
containing only primitives. The user can register that certain objects
need "packing" before serializing and "unpacking" after deserialization.

For the time being the API is going to be JS only. For an object to be
considered a potential Custom Serializable it __must have a custom
prototype, different than just `Object`__.

### API

The user registers a Custom Serializable with the
`registerCustomSerializable` function:

```ts
function registerCustomSerializable<
  TValue extends object,
  TSerialized extends object,
>(registrationData: RegistrationData<TValue, TSerialized>);

type RegistrationData<
  TValue extends object,
  TSerialized extends object,
> = {
  name: string;
  determine: (value: object) => value is TValue;
  pack: (value: TValue) => TSerialized;
  unpack: (value: TSerialized) => TValue;
};
```

where:

- `name` is the user-specified name for the Custom Serializable. It's
used to prevent registering the same Custom Serializable twice, i.e.
during hot-reload.
- `determine` is a __worklet__ that receives an `object` type and
returns a boolean that tells if the object is an instance of `TValue`,
that is a known type for packing and unpacking.
- `pack` is a __worklet__ that receives a `TValue` that passed the
`determine` checks and returns an object that can be trivially
serialized, `TPacked`.
- `unpack` is a __worklet__ that receives a `TPacked` objects and
unpacks it to the `TValue` object for future use.

All these functions are called by Worklets, so the packing and unpacking
process is hidden from them.

### Example use (with Nitro Hybrid Objects)

```ts
import { createMMKV, type MMKV } from 'react-native-mmkv';
import { type HybridObject, NitroModules } from 'react-native-nitro-modules';
import type { BoxedHybridObject } from 'react-native-nitro-modules';
import { registerCustomSerializable, scheduleOnUI } from 'react-native-worklets';

const storage: createMMKV(); // MMKV instance can't be trivially serialized, it has a custom prototype.
storage.set('key', 42);

const determine = (value: object) => {
  'worklet';
  return NitroModules.isHybridObject(value); // `NitroModules.isHybridObject` is the source of truth.
};

const pack = (value: HybridObject<never>) => {
  'worklet';
  return NitroModules.box(value); // `.box()` method creates a HostObject, which is trivially serializable.
};

const unpack = (value: BoxedHybridObject<HybridObject<never>>) => {
  'worklet';
  return value.unbox(); // `.unbox()` method extracts the HostObject to an object with the customn prototype.
};

registerCustomSerializable({
  name: 'nitro::HybridObject',
  determine,
  pack,
  unpack,
});

scheduleOnUI(() => {
  'worklet';
  const value = storage.getNumber('key'); // `storage` was implicitly packed on the RN Runtime and unpacked on the UI Runtime.
  console.log(value); // 42
});
```

### Implementation details

React Native runtime is the source of truth here. When a new type of a
Serializable is registered, the registration data is __forwarded
synchronously to all active runtimes__ and registered there. This way
all runtimes are consistent and all of them can accept/send the new type
of an object. The registrations are supposed to be rare so I don't think
we should consider it a bottleneck.

Registrations are also saved in new `MemoryManager` class. When a new
Worklet Runtime is created `MemoryManager` loads all Custom Serializable
info on it.

## Test plan

Added runtime test suite.

---

Docs will land after we decide if the current form of the API is
sufficient.

Author: tjzel

apps/common-app/package.json

@@ -35,6 +35,8 @@
     "react": "19.1.1",
     "react-dom": "19.1.1",
     "react-native-gesture-handler": "2.28.0",
+    "react-native-mmkv": "4.0.0",
+    "react-native-nitro-modules": "0.31.9",
     "react-native-pager-view": "7.0.0",
     "react-native-reanimated": "workspace:*",
     "react-native-safe-area-context": "5.6.1",

apps/common-app/src/apps/reanimated/examples/RuntimeTests/RuntimeTestsExample.tsx

@@ -48,6 +48,8 @@ export default function RuntimeTestsExample() {
             require('./tests/memory/createSerializableOnUI.test');
             require('./tests/memory/isSerializableRef.test');
             require('./tests/memory/synchronizable.test');
+            require('./tests/memory/customSerializable.test');
+            require('./tests/memory/hybridObjectSupport.test');
           },
         },
         {

apps/common-app/src/apps/reanimated/examples/RuntimeTests/tests/memory/customSerializable.test.tsx

@@ -0,0 +1,266 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { describe, expect, notify, test, waitForNotification } from '../../ReJest/RuntimeTestsApi';
+import {
+  createSerializable,
+  createSynchronizable,
+  createWorkletRuntime,
+  registerCustomSerializable,
+  runOnUISync,
+  scheduleOnRN,
+  scheduleOnRuntime,
+  scheduleOnUI,
+} from 'react-native-worklets';
+
+type IGlobalConstructorCarrier = {
+  __isCustomObject: true;
+  constructor: any;
+};
+
+function GlobalConstructorCarrierFactory(constructor: any) {
+  'worklet';
+  // Workaround because `new` keyword is reserved for Worklet Classes...
+  const GlobalConstructorCarrier = function GlobalConstructorCarrier(
+    this: IGlobalConstructorCarrier,
+    constructor: any,
+  ) {
+    this.__isCustomObject = true;
+    this.constructor = constructor;
+  } as unknown as {
+    new (constructor: any): IGlobalConstructorCarrier;
+  };
+
+  return new GlobalConstructorCarrier(constructor);
+}
+
+const determine = (value: object): value is IGlobalConstructorCarrier => {
+  'worklet';
+  return (value as Record<string, unknown>).__isCustomObject === true;
+};
+
+const pack = (value: IGlobalConstructorCarrier) => {
+  'worklet';
+  const constructorName = value.constructor.name;
+  return { constructorName };
+};
+
+const unpack = (value: { constructorName: string }) => {
+  'worklet';
+  return GlobalConstructorCarrierFactory((globalThis as any)[value.constructorName]);
+};
+
+describe('Test CustomSerializables', () => {
+  test('registers without failure', () => {
+    // Arrange
+    let error = false;
+
+    // Act
+    try {
+      registerCustomSerializable({
+        name: 'registration test',
+        determine,
+        pack,
+        unpack,
+      });
+    } catch {
+      error = true;
+    }
+
+    // Assert
+    expect(error).toBe(false);
+  });
+
+  test('serializes custom object on RN Runtime', () => {
+    // Arrange
+    const testObject = GlobalConstructorCarrierFactory(Array);
+    let serialized: object | null = null;
+
+    // Act
+    serialized = createSerializable(testObject);
+
+    // Assert
+    expect(serialized).not.toBe(null);
+  });
+
+  test('serializes custom object on RN Runtime and deserializes on UI', () => {
+    // Arrange
+    const testObject = GlobalConstructorCarrierFactory(Array);
+
+    // Act
+    const pass = runOnUISync(() => {
+      'worklet';
+      return testObject.constructor === Array;
+    });
+
+    expect(pass).toBe(true);
+  });
+
+  test('serializes custom object on the UI Runtime and deserializes on RN', () => {
+    // Arrange
+
+    const testObject = runOnUISync(() => {
+      'worklet';
+      return GlobalConstructorCarrierFactory(Array);
+    });
+
+    // Act
+    const pass = testObject.constructor === Array;
+
+    // Assert
+    expect(pass).toBe(true);
+  });
+
+  test('passes object back and forth between RN and UI runtimes', () => {
+    // Arrange
+
+    const testObject = GlobalConstructorCarrierFactory(Array);
+
+    // Act
+    const testObject2 = runOnUISync(() => {
+      'worklet';
+      return testObject;
+    });
+
+    const pass = testObject2.constructor === Array;
+
+    // Assert
+    expect(pass).toBe(true);
+  });
+
+  test('serializes custom object on RN Runtime and deserializes on custom Worklet Runtime', async () => {
+    // Arrange
+    const testObject = GlobalConstructorCarrierFactory(Array);
+    const runtime = createWorkletRuntime();
+    const pass = createSynchronizable(false);
+    const notificationName = 'done';
+
+    // Act
+    scheduleOnRuntime(runtime, () => {
+      'worklet';
+      pass.setBlocking(testObject.constructor === Array);
+      notify(notificationName);
+    });
+
+    await waitForNotification(notificationName);
+
+    // Assert
+    expect(pass.getBlocking()).toBe(true);
+  });
+
+  test('serializes custom object on custom Worklet Runtime and deserializes on RN', async () => {
+    // Arrange
+    const runtime = createWorkletRuntime();
+    let testObject: IGlobalConstructorCarrier | null = null;
+    const notificationName = 'done';
+
+    const setReturnValue = (value: any) => (testObject = value);
+
+    // Act
+    scheduleOnRuntime(runtime, () => {
+      'worklet';
+      const testObject = GlobalConstructorCarrierFactory(Array);
+      scheduleOnRN(setReturnValue, testObject);
+      notify(notificationName);
+    });
+
+    await waitForNotification(notificationName);
+
+    const pass = testObject!.constructor === Array;
+
+    // Assert
+    expect(pass).toBe(true);
+  });
+
+  test('propagates new registrations to all runtimes', async () => {
+    // Arrange
+    const preRuntime = createWorkletRuntime();
+
+    type IGlobalConstructorCarrier2 = {
+      __isCustomObject2: true;
+      constructor: any;
+    };
+
+    function GlobalConstructorCarrierFactory2(constructor: any) {
+      'worklet';
+      // Workaround because `new` keyword is reserved for Worklet Classes...
+      const GlobalConstructorCarrier2 = function GlobalConstructorCarrier2(
+        this: IGlobalConstructorCarrier2,
+        constructor: any,
+      ) {
+        this.__isCustomObject2 = true;
+        this.constructor = constructor;
+      } as unknown as {
+        new (constructor: any): IGlobalConstructorCarrier2;
+      };
+
+      return new GlobalConstructorCarrier2(constructor);
+    }
+
+    const determine2 = (value: object): value is IGlobalConstructorCarrier2 => {
+      'worklet';
+      return (value as Record<string, unknown>).__isCustomObject2 === true;
+    };
+
+    registerCustomSerializable({
+      name: 'propagation test',
+      determine: determine2 as unknown as typeof determine,
+      pack,
+      unpack,
+    });
+
+    const postRuntime = createWorkletRuntime();
+
+    const uiNotificationName = 'ui_done';
+    const preRuntimeNotificationName = 'pre_done';
+    const postRuntimeNotificationName = 'post_done';
+
+    let uiPass = false;
+    const setUiPass = (value: boolean) => {
+      uiPass = value;
+    };
+    let preRuntimePass = false;
+    const setPreRuntimePass = (value: boolean) => {
+      preRuntimePass = value;
+    };
+    let postRuntimePass = false;
+    const setPostRuntimePass = (value: boolean) => {
+      postRuntimePass = value;
+    };
+
+    // Act
+    scheduleOnUI(() => {
+      'worklet';
+      const testObject = GlobalConstructorCarrierFactory2(Array);
+      const pass = testObject.constructor === Array;
+      scheduleOnRN(setUiPass, pass);
+      notify(uiNotificationName);
+    });
+
+    scheduleOnRuntime(preRuntime, () => {
+      'worklet';
+      const testObject = GlobalConstructorCarrierFactory2(Array);
+      const pass = testObject.constructor === Array;
+      scheduleOnRN(setPreRuntimePass, pass);
+      notify(preRuntimeNotificationName);
+    });
+
+    scheduleOnRuntime(postRuntime, () => {
+      'worklet';
+      const testObject = GlobalConstructorCarrierFactory2(Array);
+      const pass = testObject.constructor === Array;
+      scheduleOnRN(setPostRuntimePass, pass);
+      notify(postRuntimeNotificationName);
+    });
+
+    await waitForNotification(uiNotificationName);
+    await waitForNotification(preRuntimeNotificationName);
+    await waitForNotification(postRuntimeNotificationName);
+
+    // Assert
+    expect(uiPass).toBe(true);
+    expect(preRuntimePass).toBe(true);
+    expect(postRuntimePass).toBe(true);
+  });
+});