docs: add runOnRuntime page and extend createWorkletRuntime page

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # createWorkletRuntime
@@ -69,6 +69,8 @@ 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](/docs/fundamentals/glossary#shared-value) 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-reanimated/docs/threading/runOnRuntime.mdx

@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# runOnRuntime
+
+`runOnRuntime` lets you asynchronously run [workletized](/docs/fundamentals/glossary#to-workletize) functions on a separate worklet runtime on a separate thread.
+
+## Reference
+
+```javascript
+import { createWorkletRuntime, runOnRuntime } from 'react-native-reanimated';
+
+const workletRuntime = createWorkletRuntime('background');
+
+function App() {
+  // E.g. in event handler or in an effect
+  // highlight-next-line
+  runOnRuntime(workletRuntime, (greeting) => {
+    console.log(`${greeting} from a separate thread`);
+    // highlight-next-line
+  })('Howdy');
+
+  // ...
+}
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+function runOnRuntime<A extends any[], R>(
+  workletRuntime: WorkletRuntime,
+  fn: (...args: A) => R
+): (...args: Parameters<typeof fn>) => void;
+```
+
+</details>
+
+### Arguments
+
+#### workletRuntime
+
+A reference to worklet runtime created with [`createWorkletRuntime`](/docs/threading/createWorkletRuntime).
+
+#### fn
+
+A reference to a function you want to execute on the [UI thread](/docs/fundamentals/glossary#ui-thread) from the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread). Arguments to your function have to be passed to the function returned from `runOnUI` i.e. `runOnUI(myWorklet)(10);`.
+
+### Returns
+
+`runOnRuntime` returns a function that accepts arguments for the function passed as the first argument.
+
+:::info
+Don't forget to call the function returned from `runOnRuntime`.
+:::
+
+## Remarks
+
+- It's a common mistake to execute function inside of `runOnRuntime` like this: ~~`runOnRuntime(myWorklet(10))()`~~. Here, the correct usage would be `runOnRuntime(myWorklet)(10)`.
+
+- The callback passed as the argument will not be [workletized](/docs/fundamentals/glossary#to-workletize) automatically. You need to add `'worklet';` directive manually to allow the function to be run on the [UI thread](/docs/fundamentals/glossary#ui-thread).
+
+- 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-reanimated/versioned_docs/version-3.x/threading/createWorkletRuntime.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # createWorkletRuntime
@@ -69,6 +69,8 @@ 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](/docs/fundamentals/glossary#shared-value) 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-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx

@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# runOnRuntime
+
+`runOnRuntime` lets you asynchronously run [workletized](/docs/fundamentals/glossary#to-workletize) functions on a separate worklet runtime on a separate thread.
+
+## Reference
+
+```javascript
+import { createWorkletRuntime, runOnRuntime } from 'react-native-reanimated';
+
+const workletRuntime = createWorkletRuntime('background');
+
+function App() {
+  // E.g. in event handler or in an effect
+  // highlight-next-line
+  runOnRuntime(workletRuntime, (greeting) => {
+    console.log(`${greeting} from a separate thread`);
+    // highlight-next-line
+  })('Howdy');
+
+  // ...
+}
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+function runOnRuntime<A extends any[], R>(
+  workletRuntime: WorkletRuntime,
+  fn: (...args: A) => R
+): (...args: Parameters<typeof fn>) => void;
+```
+
+</details>
+
+### Arguments
+
+#### workletRuntime
+
+A reference to worklet runtime created with [`createWorkletRuntime`](/docs/threading/createWorkletRuntime).
+
+#### fn
+
+A reference to a function you want to execute on the [UI thread](/docs/fundamentals/glossary#ui-thread) from the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread). Arguments to your function have to be passed to the function returned from `runOnUI` i.e. `runOnUI(myWorklet)(10);`.
+
+### Returns
+
+`runOnRuntime` returns a function that accepts arguments for the function passed as the first argument.
+
+:::info
+Don't forget to call the function returned from `runOnRuntime`.
+:::
+
+## Remarks
+
+- It's a common mistake to execute function inside of `runOnRuntime` like this: ~~`runOnRuntime(myWorklet(10))()`~~. Here, the correct usage would be `runOnRuntime(myWorklet)(10)`.
+
+- The callback passed as the argument will not be [workletized](/docs/fundamentals/glossary#to-workletize) automatically. You need to add `'worklet';` directive manually to allow the function to be run on the [UI thread](/docs/fundamentals/glossary#ui-thread).
+
+- 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 />