feat: Serializable docs

packages/docs-worklets/docs/fundamentals/glossary.mdx

@@ -79,8 +79,10 @@ The plugin performs automatic [workletization](/docs/fundamentals/glossary#to-wo
 
 You can learn the details by reading the [Reanimated Babel plugin README](https://github.com/software-mansion/react-native-reanimated/blob/main/packages/react-native-worklets/plugin/README-dev.md).
 
-## Shareable
+## Serializable
 
-<DeprecatedBanner />
+A Serializable is an object that represents a JavaScript value that can be copied between [Worklet Runtimes](/docs/fundamentals/glossary/#worklet-runtime). JavaScript values cannot be passed to other runtimes without prior serialization.
 
-A `Shareable` is an object which can be assigned to a specific [Worklet Runtime](/docs/fundamentals/glossary#worklet-runtime), where it's shared across worklets in the same runtime.
+## SerializableRef
+
+A `SerializableRef` is a reference to a `Serializable` object.

packages/docs-worklets/docs/memory/createSerializabe.mdx

@@ -0,0 +1,81 @@
+---
+sidebar_position: 1
+---
+
+# createSerializable
+
+`createSerializable` recursively converts JavaScript values into serializable references that can be used on different Runtimes than RN Runtime.
+The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Serializable`.
+It handles various data types including primitives, objects, arrays, functions, and special cases like host objects and worklets.
+To prevent misconceptions Worklets library freezes the original value for object-like values and for arrays.
+
+![Serializable](/img/serializable.png)
+<figcaption style={{ textAlign: 'center' }}>Serializable flow diagram</figcaption>
+
+**Functions like `runOnUI`, `runOnRuntime`, `runOnJS`, `executeOnUIRuntimeSync` and `runOnUIAsync` automatically convert values to `Serializable` references.**
+
+## Usage
+
+```tsx
+import { createSerializable, runOnUI } from 'react-native-worklets';
+
+const object = {
+  a: 1,
+  b: 2,
+  c: 4,
+};
+
+object.c = 3; // <-- Correct: you can modify the object before serializing it
+
+createSerializable(object);
+
+object.a = 10; // <-- Warning: You can't mutate the object after serializing it
+
+runOnUI(() => {
+  object.a = 10; // <-- Warning: You can't mutate the object after serializing it
+  console.log(object); // { a: 1, b: 2, c: 3 }
+})();
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+type SerializableRef<T = unknown> = {
+  __serializableRef: true;
+  __nativeStateSerializableJSRef: T;
+};
+
+function createSerializable<T>(value: T): SerializableRef<T> {
+  return value as SerializableRef<T>;
+}
+```
+
+</details>
+
+## Remarks
+
+- The function automatically detects the type of the input value and applies appropriate serialization strategies. 
+
+Supported types:
+  | Type | Supported |
+  |------|-----------|
+  | string | ✅ |
+  | number | ✅ |
+  | boolean | ✅ |
+  | object | ✅ |
+  | array | ✅ |
+  | function (non-worklet) | ✅ |
+  | HostObject | ✅ |
+  | worklet | ✅ |
+  | Map | ✅ |
+  | Set | ✅ |
+  | ArrayBuffer | ✅ |
+  | RegExp | ✅ |
+  | Cyclic objects | ❌ |
+  | Objects with custom prototype | ❌ |
+
+- For objects and arrays, it recursively processes nested properties
+- The function includes cycle detection to prevent infinite recursion
+- Objects are frozen after serialization to prevent accidental modifications that won't propagate to the Serializable
+- Functions that aren't worklets are serialized as references to function instances on the respective runtime

packages/docs-worklets/docs/memory/isSerializableRef.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 2
+---
+
+# isSerializableRef
+
+`isSerializableRef` checks if a value is a serializable reference.
+
+## Reference
+
+```javascript
+import { isSerializableRef, createSerializable } from 'react-native-worklets';
+
+const object = {
+  a: 1,
+};
+
+const serializableRef = createSerializable(object);
+
+console.log(isSerializableRef(serializableRef)); // true
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+function isSerializableRef(value: unknown): value is SerializableRef
+```
+</details>

packages/docs-worklets/docs/memory/makeShareable.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
 ---
 
 # makeShareable

packages/docs-worklets/docs/memory/makeShareableCloneOnUIRecursive.mdx

@@ -1,9 +1,11 @@
 ---
-sidebar_position: 3
+sidebar_position: 5
 ---
 
 # makeShareableCloneOnUIRecursive
 
+<DeprecatedBanner />
+
 `makeShareableCloneOnUIRecursive` recursively converts JavaScript values into shareable references that can be used on different Runtimes than UI Runtime.
 The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Shareable`. 
 To prevent misconceptions about it we freeze the original value for object-like values and for arrays.
@@ -49,7 +51,3 @@ function makeShareableCloneOnUIRecursive<T>(
 ```
 
 </details>
-
-## Platform compatibility
-
-<PlatformCompatibility android ios web />

packages/docs-worklets/docs/memory/makeShareableCloneRecursive.mdx

@@ -1,9 +1,11 @@
 ---
-sidebar_position: 2
+sidebar_position: 4
 ---
 
 # makeShareableCloneRecursive
 
+<DeprecatedBanner text="⚠️ This function is deprecated and will be removed in the next major release. Use createSerializable instead." />
+
 `makeShareableCloneRecursive` recursively converts JavaScript values into shareable references that can be used on different Runtimes than RN Runtime.
 The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Shareable`. 
 To prevent misconceptions about it we freeze the original value for object-like values and for arrays.
@@ -41,7 +43,3 @@ function makeShareableCloneRecursive<T>(value: T): ShareableRef<T> {
 ```
 
 </details>
-
-## Platform compatibility
-
-<PlatformCompatibility android ios web />

packages/docs-worklets/docs/threading/createWorkletRuntime.mdx

@@ -70,7 +70,3 @@ An optional worklet that will be run synchronously on the same thread immediatel
 - You can use Chrome DevTools to debug the runtime (Hermes only). The runtime will appear in the devices list as `name` passed to `createWorkletRuntime`.
 
 - Shared values are only partially supported in worklet runtimes. If you want to write to a shared value from the RN runtime and read it on the worklet runtime, you need to perform the assignment using [`runOnRuntime`](/docs/threading/runOnRuntime). Otherwise, the value will be updated only in the RN and UI runtimes.
-
-## Platform compatibility
-
-<PlatformCompatibility android ios />

packages/docs-worklets/docs/threading/executeOnUIRuntimeSync.mdx

@@ -52,7 +52,3 @@ Don't forget to call the function returned from `executeOnUIRuntimeSync`.
 - The callback passed as the argument is automatically [workletized](/docs/fundamentals/glossary#to-workletize) and ready to be run on the [UI thread](/docs/fundamentals/glossary#ui-thread).
 
 - Make sure not to execute `executeOnUIRuntimeSync` on the UI thread as this will result in an error.
-
-## Platform compatibility
-
-<PlatformCompatibility android ios web />

packages/docs-worklets/docs/threading/runOnJS.mdx

@@ -72,7 +72,3 @@ withTiming(0, {}, () => {
 - It's a common mistake to execute function inside of runOnJS like this: ~~`runOnJS(setValue(10))()`~~. Here, the correct usage would be `runOnJS(setValue)(10)`.
 
 - It's safe to run functions via `runOnJS` on the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread), as this has no effect.
-
-## Platform compatibility
-
-<PlatformCompatibility android ios web />

packages/docs-worklets/docs/threading/runOnRuntime.mdx

@@ -64,7 +64,3 @@ Don't forget to call the function returned from `runOnRuntime`.
 - You may call `runOnRuntime` on any runtime, including the RN runtime, UI runtime and other worklet runtimes.
 
 - The function passed to `runOnRuntime` will be added to an execution queue on a separate thread and executed asynchronously on the specified worklet runtime. The functions will be executed in the order they were added to the queue.
-
-## Platform compatibility
-
-<PlatformCompatibility android ios />

packages/docs-worklets/docs/threading/runOnUI.mdx

@@ -72,7 +72,3 @@ import RunOnUISrc from '!!raw-loader!@site/src/examples/RunOnUI';
 - Make sure not to execute `runOnUI` on the UI thread as this will result in an error.
 
 - In browsers there's no separate UI thread available. Because of that, on the Web, `runOnUI` behaves similarly to `requestAnimationFrame`. It creates a function that, when called, will be scheduled to run with given arguments on next animation frame.
-
-## Platform compatibility
-
-<PlatformCompatibility android ios web />

packages/docs-worklets/docs/threading/runOnUIAsync.mdx

@@ -45,7 +45,3 @@ A reference to a function you want to execute on the UI thread. Arguments to you
 - The callback passed as the argument is automatically [workletized](/docs/fundamentals/glossary#to-workletize) and ready to be run on the [UI thread](/docs/fundamentals/glossary#ui-thread).
 
 - Make sure not to execute `runOnUIAsync` on the UI thread as this will result in an error.
-
-## Platform compatibility
-
-<PlatformCompatibility android ios web />

packages/docs-worklets/src/theme/MDXComponents.js

@@ -1,7 +1,6 @@
 // Import the original mapper
 import MDXComponents from '@theme-original/MDXComponents';
 import InteractiveExample from '@site/src/components/InteractiveExample';
-import PlatformCompatibility from '@site/src/components/PlatformCompatibility';
 import { Yes, No, Version, Spacer } from '@site/src/components/Compatibility';
 import Indent from '@site/src/components/Indent';
 import DeprecatedBanner from '@site/src/components/DeprecatedBanner';
@@ -12,7 +11,6 @@ export default {
   // Map the "<Highlight>" tag to our Highlight component
   // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
   InteractiveExample,
-  PlatformCompatibility,
   Yes,
   No,
   Version,