react-native-worklets 0.0.1-alpha → 0.1.0

package/Common/cpp/worklets/Tools/ThreadSafeQueue.h

@@ -0,0 +1,49 @@
+#pragma once
+
+#include <condition_variable>
+#include <mutex>
+#include <queue>
+#include <utility>
+
+namespace worklets {
+
+//
+// Copyright (c) 2013 Juan Palacios juan.palacios.puyana@gmail.com
+// Subject to the BSD 2-Clause License
+// - see < https://opensource.org/license/bsd-2-clause/ >
+//
+template <typename T>
+class ThreadSafeQueue {
+ public:
+  T pop() {
+    std::unique_lock<std::mutex> mlock(mutex_);
+    while (queue_.empty()) {
+      cond_.wait(mlock);
+    }
+    const auto item = queue_.front();
+    queue_.pop();
+    return item;
+  }
+
+  void push(T &&item) {
+    std::unique_lock<std::mutex> mlock(mutex_);
+    queue_.push(std::move(item));
+    mlock.unlock();
+    cond_.notify_one();
+  }
+
+  bool empty() const {
+    std::unique_lock<std::mutex> mlock(mutex_);
+    const auto res = queue_.empty();
+    mlock.unlock();
+    cond_.notify_one();
+    return res;
+  }
+
+ private:
+  std::queue<T> queue_;
+  mutable std::mutex mutex_;
+  mutable std::condition_variable cond_;
+};
+
+} // namespace worklets

package/Common/cpp/worklets/Tools/UIScheduler.cpp

@@ -0,0 +1,19 @@
+#include <worklets/Tools/UIScheduler.h>
+
+#include <utility>
+
+namespace worklets {
+
+void UIScheduler::scheduleOnUI(std::function<void()> job) {
+  uiJobs_.push(std::move(job));
+}
+
+void UIScheduler::triggerUI() {
+  scheduledOnUI_ = false;
+  while (!uiJobs_.empty()) {
+    const auto job = uiJobs_.pop();
+    job();
+  }
+}
+
+} // namespace worklets

package/Common/cpp/worklets/Tools/UIScheduler.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include <worklets/Tools/ThreadSafeQueue.h>
+
+#include <ReactCommon/CallInvoker.h>
+
+#include <atomic>
+
+namespace worklets {
+
+class UIScheduler {
+ public:
+  virtual void scheduleOnUI(std::function<void()> job);
+  virtual void triggerUI();
+  virtual ~UIScheduler() = default;
+
+ protected:
+  std::atomic<bool> scheduledOnUI_{false};
+  ThreadSafeQueue<std::function<void()>> uiJobs_;
+};
+
+} // namespace worklets

package/Common/cpp/worklets/Tools/WorkletEventHandler.cpp

@@ -0,0 +1,29 @@
+#include <worklets/Tools/WorkletEventHandler.h>
+
+namespace worklets {
+
+void WorkletEventHandler::process(
+    const std::shared_ptr<WorkletRuntime> &workletRuntime,
+    const double eventTimestamp,
+    const jsi::Value &eventValue) const {
+  workletRuntime->runGuarded(
+      handlerFunction_, jsi::Value(eventTimestamp), eventValue);
+}
+
+uint64_t WorkletEventHandler::getHandlerId() const {
+  return handlerId_;
+}
+
+const std::string &WorkletEventHandler::getEventName() const {
+  return eventName_;
+}
+
+uint64_t WorkletEventHandler::getEmitterReactTag() const {
+  return emitterReactTag_;
+}
+
+bool WorkletEventHandler::shouldIgnoreEmitterReactTag() const {
+  return emitterReactTag_ == -1;
+}
+
+} // namespace worklets

package/Common/cpp/worklets/Tools/WorkletEventHandler.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include <worklets/SharedItems/Shareables.h>
+#include <worklets/WorkletRuntime/WorkletRuntime.h>
+
+#include <jsi/jsi.h>
+
+#include <memory>
+#include <string>
+
+using namespace facebook;
+
+namespace worklets {
+
+class WorkletEventHandler {
+  const uint64_t handlerId_;
+  const uint64_t emitterReactTag_;
+  const std::string eventName_;
+  const std::shared_ptr<ShareableWorklet> handlerFunction_;
+
+ public:
+  WorkletEventHandler(
+      const uint64_t handlerId,
+      const std::string &eventName,
+      const uint64_t emitterReactTag,
+      const std::shared_ptr<ShareableWorklet> &handlerFunction)
+      : handlerId_(handlerId),
+        emitterReactTag_(emitterReactTag),
+        eventName_(eventName),
+        handlerFunction_(handlerFunction) {}
+  void process(
+      const std::shared_ptr<WorkletRuntime> &workletRuntime,
+      double eventTimestamp,
+      const jsi::Value &eventValue) const;
+  uint64_t getHandlerId() const;
+  const std::string &getEventName() const;
+  uint64_t getEmitterReactTag() const;
+  bool shouldIgnoreEmitterReactTag() const;
+};
+
+} // namespace worklets

package/Common/cpp/worklets/Tools/WorkletsJSIUtils.cpp

@@ -0,0 +1,26 @@
+#include <worklets/Tools/WorkletsJSIUtils.h>
+#include <vector>
+
+using namespace facebook;
+
+namespace worklets::jsi_utils {
+
+jsi::Array convertStringToArray(
+    jsi::Runtime &rt,
+    const std::string &value,
+    const unsigned int expectedSize) {
+  std::vector<float> transformMatrixList;
+  std::istringstream stringStream(value);
+  std::copy(
+      std::istream_iterator<float>(stringStream),
+      std::istream_iterator<float>(),
+      std::back_inserter(transformMatrixList));
+  assert(transformMatrixList.size() == expectedSize);
+  jsi::Array matrix(rt, expectedSize);
+  for (unsigned int i = 0; i < expectedSize; i++) {
+    matrix.setValueAtIndex(rt, i, transformMatrixList[i]);
+  }
+  return matrix;
+}
+
+} // namespace worklets::jsi_utils

package/Common/cpp/worklets/Tools/WorkletsJSIUtils.h

@@ -0,0 +1,199 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <sstream>
+#include <string>
+#include <tuple>
+#include <utility>
+
+using namespace facebook;
+
+namespace worklets::jsi_utils {
+
+// `get` functions take a pointer to `jsi::Value` and
+// call an appropriate method to cast to the native type
+template <typename T>
+inline T get(jsi::Runtime &rt, const jsi::Value *value);
+
+template <>
+inline double get<double>(jsi::Runtime &, const jsi::Value *value) {
+  return value->asNumber();
+}
+
+template <>
+inline int get<int>(jsi::Runtime &, const jsi::Value *value) {
+  return value->asNumber();
+}
+
+template <>
+inline bool get<bool>(jsi::Runtime &, const jsi::Value *value) {
+  if (!value->isBool()) {
+    throw jsi::JSINativeException("[Worklets] Expected a boolean.");
+  }
+  return value->getBool();
+}
+
+template <>
+inline jsi::Object get<jsi::Object>(jsi::Runtime &rt, const jsi::Value *value) {
+  return value->asObject(rt);
+}
+
+template <>
+inline jsi::Value const &get<jsi::Value const &>(
+    jsi::Runtime &,
+    const jsi::Value *value) {
+  return *value;
+}
+
+// `convertArgs` functions take a variadic template parameter of target (C++)
+// argument types `Targs` and a `jsi::Value` array `args`, and converts `args`
+// to a tuple of typed C++ arguments to be passed to the native implementation.
+// This is accomplished by dispatching (at compile time) to the correct
+// implementation based on the first type of `Targs`, using SFINAE to select the
+// correct specialization, and concatenating with the result of recursion on the
+// rest of `Targs`
+
+// BEGIN implementations for `convertArgs` specializations.
+// specialization for empty `Targs` - returns an empty tuple
+template <typename... Args>
+inline std::enable_if_t<(sizeof...(Args) == 0), std::tuple<>> convertArgs(
+    jsi::Runtime &,
+    const jsi::Value *) {
+  return std::make_tuple();
+}
+
+// calls `get<First>` on the first argument to retrieve the native type,
+// then calls recursively on the rest of `args`
+// and returns the concatenation of results
+template <typename T, typename... Rest>
+inline std::tuple<T, Rest...> convertArgs(
+    jsi::Runtime &rt,
+    const jsi::Value *args) {
+  auto arg = std::tuple<T>(get<T>(rt, args));
+  auto rest = convertArgs<Rest...>(rt, std::next(args));
+  return std::tuple_cat(std::move(arg), std::move(rest));
+}
+// END implementations for `convertArgs` specializations.
+
+// returns a tuple with the result of casting `args` to appropriate
+// native C++ types needed to call `function`
+template <typename Ret, typename... Args>
+std::tuple<Args...> getArgsForFunction(
+    std::function<Ret(Args...)>,
+    jsi::Runtime &rt,
+    const jsi::Value *args,
+    const size_t count) {
+  assert(sizeof...(Args) == count);
+  return convertArgs<Args...>(rt, args);
+}
+
+// returns a tuple with the result of casting `args` to appropriate
+// native C++ types needed to call `function`,
+// passing `rt` as the first argument
+template <typename Ret, typename... Args>
+std::tuple<jsi::Runtime &, Args...> getArgsForFunction(
+    std::function<Ret(jsi::Runtime &, Args...)>,
+    jsi::Runtime &rt,
+    const jsi::Value *args,
+    const size_t count) {
+  assert(sizeof...(Args) == count);
+  return std::tuple_cat(std::tie(rt), convertArgs<Args...>(rt, args));
+}
+
+// calls `function` with `args`
+template <typename Ret, typename... Args>
+inline jsi::Value apply(
+    std::function<Ret(Args...)> function,
+    std::tuple<Args...> args) {
+  return std::apply(function, std::move(args));
+}
+
+// calls string-returning `function` with `args`,
+// and returns the string
+template <typename... Args>
+inline jsi::Value apply(
+    jsi::Runtime &rt,
+    std::function<std::string(Args...)> function,
+    std::tuple<Args...> args) {
+  return jsi::String::createFromUtf8(rt, std::apply(function, std::move(args)));
+}
+
+// calls void-returning `function` with `args`,
+// and returns `undefined`
+template <typename... Args>
+inline jsi::Value apply(
+    std::function<void(Args...)> function,
+    std::tuple<Args...> args) {
+  std::apply(function, std::move(args));
+  return jsi::Value::undefined();
+}
+
+// returns a function with JSI calling convention
+// from a native function `function`
+template <typename Fun>
+jsi::HostFunctionType createHostFunction(Fun function) {
+  return [function](
+             jsi::Runtime &rt,
+             const jsi::Value &,
+             const jsi::Value *args,
+             const size_t count) {
+    auto argz = getArgsForFunction(function, rt, args, count);
+    return apply(function, std::move(argz));
+  };
+}
+
+// returns a function with JSI calling convention
+// from a native function `function` returning a string
+template <typename... Args>
+jsi::HostFunctionType createHostFunction(
+    std::function<std::string(Args...)> function) {
+  return [function](
+             jsi::Runtime &rt,
+             const jsi::Value &,
+             const jsi::Value *args,
+             const size_t count) {
+    auto argz = getArgsForFunction(function, rt, args, count);
+    return apply(rt, function, std::move(argz));
+  };
+}
+
+// used to determine if `function<Ret(Args...)>`
+// takes `Runtime &` as its first argument
+template <typename... Args>
+struct takes_runtime {
+  static constexpr size_t value = 0;
+};
+
+// specialization for `function<Ret(Runtime &, Rest...)`
+template <typename... Rest>
+struct takes_runtime<jsi::Runtime &, Rest...> {
+  static constexpr size_t value = 1;
+};
+
+// creates a JSI compatible function from `function`
+// and installs it as a global function named `name`
+// in the `rt` JS runtime
+template <typename Ret, typename... Args>
+void installJsiFunction(
+    jsi::Runtime &rt,
+    std::string_view name,
+    std::function<Ret(Args...)> function) {
+  auto clb = createHostFunction(function);
+  auto argsCount = sizeof...(Args) - takes_runtime<Args...>::value;
+  jsi::Value jsiFunction = jsi::Function::createFromHostFunction(
+      rt, jsi::PropNameID::forAscii(rt, name.data()), argsCount, clb);
+  rt.global().setProperty(rt, name.data(), jsiFunction);
+}
+
+// this should take care of passing types convertible to `function`
+template <typename Fun>
+void installJsiFunction(jsi::Runtime &rt, std::string_view name, Fun function) {
+  installJsiFunction(rt, name, std::function(std::forward<Fun>(function)));
+}
+
+jsi::Array convertStringToArray(
+    jsi::Runtime &rt,
+    const std::string &value,
+    const unsigned int expectedSize);
+
+} // namespace worklets::jsi_utils

package/Common/cpp/worklets/WorkletRuntime/RNRuntimeWorkletDecorator.cpp

@@ -0,0 +1,20 @@
+#include <worklets/WorkletRuntime/RNRuntimeWorkletDecorator.h>
+
+namespace worklets {
+
+void RNRuntimeWorkletDecorator::decorate(
+    jsi::Runtime &rnRuntime,
+    const std::shared_ptr<WorkletsModuleProxy> &workletsModuleProxy) {
+  rnRuntime.global().setProperty(rnRuntime, "_WORKLET", false);
+
+  // TODO: Remove _IS_FABRIC sometime in the future
+  // react-native-screens 4.9.0 depends on it
+  rnRuntime.global().setProperty(rnRuntime, "_IS_FABRIC", true);
+
+  rnRuntime.global().setProperty(
+      rnRuntime,
+      "__workletsModuleProxy",
+      jsi::Object::createFromHostObject(rnRuntime, workletsModuleProxy));
+}
+
+} // namespace worklets

package/Common/cpp/worklets/WorkletRuntime/RNRuntimeWorkletDecorator.h

@@ -0,0 +1,19 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <worklets/NativeModules/WorkletsModuleProxy.h>
+#include <memory>
+
+using namespace facebook;
+
+namespace worklets {
+
+class RNRuntimeWorkletDecorator {
+  // TODO: Rename to `RNRuntimeWorkletsDecorator` or something more suitable.
+ public:
+  static void decorate(
+      jsi::Runtime &rnRuntime,
+      const std::shared_ptr<WorkletsModuleProxy> &workletsModuleProxy);
+};
+
+} // namespace worklets

package/Common/cpp/worklets/WorkletRuntime/RuntimeInitialization.md

@@ -0,0 +1,191 @@
+# Hermes Runtime initialization
+
+_Last updated_: 13/09/2022 by @Kwasow
+
+This document describes the current way of initializing Hermes and connecting
+it to the debugger. The work I did was mainly based on
+
+[HermesExecutorFactory.cpp](https://github.com/facebook/react-native/blob/main/packages/react-native/ReactCommon/hermes/executor/HermesExecutorFactory.cpp)
+from React Native.
+
+## Runtime initialization
+
+If you take a look at `NativeProxy` (both on Android and iOS) you'll find
+that it only makes a call to `ReanimatedRuntime::make(jsQueue)`. This
+static function will return the correct runtime based on the user's configuration.
+
+The initialization process is pretty simple and has only been moved out of
+`NativeProxy` into `ReanimatedRuntime` without any major changes.
+
+## Hermes runtime debugging
+
+To enable debugging on the Hermes runtime we need to do two things:
+
+1. Include source maps in JavaScript files
+
+This part is done purely in JavaScript via the Babel plugin. The `makeWorklet`
+function received an AST tree, which is aware of the modifications it made to
+the code and therefore can generate the necessary source maps. It is important
+that when we want to create a string from the AST we use the `generate` function
+and enable source map generation so line mappings are not lost. Then when
+transforming that code (ex. with `transformSync`) we have to pass the source
+map as input so it can be updated.
+
+Source map settings should always be set to `inline` so they are automatically
+appended to the source code. The generated source map will be a base64 encoded
+json.
+
+A workletized function would look like this (after formattings):
+
+```js
+function _f(number) {
+  console.log(_WORKLET, number);
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJtYXBwaW5ncyI6IkFBYXNCLFNBQUNBLEVBQUQsQ0FBQ0EsTUFBRCxFQUFvQjtBQUV0Q0MsU0FBTyxDQUFDQyxHQUFSRCxDQUFZRSxRQUFaRixFQUFzQkQsTUFBdEJDO0FBRmtCIiwibmFtZXMiOlsibnVtYmVyIiwiY29uc29sZSIsImxvZyIsIl9XT1JLTEVUIl0sInNvdXJjZXMiOlsiL1VzZXJzL2thcm9sL0dpdC9yZWFjdC1uYXRpdmUtcmVhbmltYXRlZC9GYWJyaWNFeGFtcGxlL3NyYy9Xb3JrbGV0RXhhbXBsZS50c3giXSwic291cmNlc0NvbnRlbnQiOlsiLyogZ2xvYmFsIF9XT1JLTEVUICovXG5pbXBvcnQgeyBCdXR0b24sIFZpZXcsIFN0eWxlU2hlZXQgfSBmcm9tICdyZWFjdC1uYXRpdmUnO1xuaW1wb3J0IHtcbiAgcnVuT25KUyxcbiAgcnVuT25VSSxcbiAgdXNlRGVyaXZlZFZhbHVlLFxuICB1c2VTaGFyZWRWYWx1ZSxcbn0gZnJvbSAncmVhY3QtbmF0aXZlLXJlYW5pbWF0ZWQnO1xuXG5pbXBvcnQgUmVhY3QgZnJvbSAncmVhY3QnO1xuXG5leHBvcnQgZGVmYXVsdCBmdW5jdGlvbiBXb3JrbGV0RXhhbXBsZSgpIHtcbiAgLy8gcnVuT25VSSBkZW1vXG4gIGNvbnN0IHNvbWVXb3JrbGV0ID0gKG51bWJlcjogbnVtYmVyKSA9PiB7XG4gICAgJ3dvcmtsZXQnO1xuICAgIGNvbnNvbGUubG9nKF9XT1JLTEVULCBudW1iZXIpOyAvLyBfV09SS0xFVCBzaG91bGQgYmUgdHJ1ZVxuICB9O1xuXG4gIGNvbnN0IGhhbmRsZVByZXNzMSA9ICgpID0+IHtcbiAgICBydW5PblVJKHNvbWVXb3JrbGV0KShNYXRoLnJhbmRvbSgpKTtcbiAgfTtcblxuICAvLyBydW5PbkpTIGRlbW9cbiAgY29uc3QgeCA9IHVzZVNoYXJlZFZhbHVlKDApO1xuXG4gIGNvbnN0IHNvbWVGdW5jdGlvbiA9IChudW1iZXI6IG51bWJlcikgPT4ge1xuICAgIGNvbnNvbGUubG9nKF9XT1JLTEVULCBudW1iZXIpOyAvLyBfV09SS0xFVCBzaG91bGQgYmUgZmFsc2VcbiAgfTtcblxuICB1c2VEZXJpdmVkVmFsdWUoKCkgPT4ge1xuICAgIHJ1bk9uSlMoc29tZUZ1bmN0aW9uKSh4LnZhbHVlKTtcbiAgfSk7XG5cbiAgY29uc3QgaGFuZGxlUHJlc3MyID0gKCkgPT4ge1xuICAgIHgudmFsdWUgPSBNYXRoLnJhbmRvbSgpO1xuICB9O1xuXG4gIHJldHVybiAoXG4gICAgPFZpZXcgc3R5bGU9e3N0eWxlcy5jb250YWluZXJ9PlxuICAgICAgPEJ1dHRvbiBvblByZXNzPXtoYW5kbGVQcmVzczF9IHRpdGxlPVwicnVuT25VSSBkZW1vXCIgLz5cbiAgICAgIDxCdXR0b24gb25QcmVzcz17aGFuZGxlUHJlc3MyfSB0aXRsZT1cInJ1bk9uSlMgZGVtb1wiIC8+XG4gICAgPC9WaWV3PlxuICApO1xufVxuXG5jb25zdCBzdHlsZXMgPSBTdHlsZVNoZWV0LmNyZWF0ZSh7XG4gIGNvbnRhaW5lcjoge1xuICAgIGZsZXg6IDEsXG4gICAgYWxpZ25JdGVtczogJ2NlbnRlcicsXG4gICAganVzdGlmeUNvbnRlbnQ6ICdjZW50ZXInLFxuICB9LFxufSk7XG4iXX0=
+```
+
+And the base64 string after decoding is:
+
+```json
+{
+  "version": 3,
+  "mappings": "AAasB,SAACA,EAAD,CAACA,MAAD,EAAoB;AAEtCC,SAAO,CAACC,GAARD,CAAYE,QAAZF,EAAsBD,MAAtBC;AAFkB",
+  "names": ["number", "console", "log", "_WORKLET"],
+  "sources": [
+    "/Users/karol/Git/react-native-reanimated/FabricExample/src/WorkletExample.tsx"
+  ],
+  "sourcesContent": [
+    "/* global _WORKLET */\nimport { Button, View, StyleSheet } from 'react-native';\nimport {\n  runOnJS,\n  runOnUI,\n  useDerivedValue,\n  useSharedValue,\n} from 'react-native-reanimated';\n\nimport React from 'react';\n\nexport default function WorkletExample() {\n  // runOnUI demo\n  const someWorklet = (number: number) => {\n    'worklet';\n    console.log(_WORKLET, number); // _WORKLET should be true\n  };\n\n  const handlePress1 = () => {\n    runOnUI(someWorklet)(Math.random());\n  };\n\n  // runOnJS demo\n  const x = useSharedValue(0);\n\n  const someFunction = (number: number) => {\n    console.log(_WORKLET, number); // _WORKLET should be false\n  };\n\n  useDerivedValue(() => {\n    runOnJS(someFunction)(x.value);\n  });\n\n  const handlePress2 = () => {\n    x.value = Math.random();\n  };\n\n  return (\n    <View style={styles.container}>\n      <Button onPress={handlePress1} title=\"runOnUI demo\" />\n      <Button onPress={handlePress2} title=\"runOnJS demo\" />\n    </View>\n  );\n}\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    alignItems: 'center',\n    justifyContent: 'center',\n  },\n});\n"
+  ]
+}
+```
+
+We run jest tests in release mode, because source maps will contain absolute
+paths, which will be different on every machine and therefore would also alter
+worklet hashes. Running in release mode prevents this.
+
+2. Enable debugging on the runtime object
+
+This is done by creating an adapter (`HermesExecutorRuntimeAdapter` inside of
+`WorkletHermesRuntime.cpp`) which holds the runtime and allows the debugger
+to communicate with it. The adapter is managed by a `Connection` (`ConnectionDemux`)
+object, but this is not important in our case. We just have to make a call
+to `facebook::hermes::inspector::chrome::enableDebugging()` and pass the adapter
+and runtime name as parameters.
+
+It is important to also `disableDebugging()` before the runtime is destroyed.
+Failing to do so will probably crash the app as the debugger will try to
+connect to a non-existent runtime.
+
+The runtime should also be destroyed before the Reanimated module, because
+otherwise there might be weird BAD_ACCESS errors when the gc gets it
+hand on the runtime.
+
+## Metro endpoint
+
+Flipper and Chrome DevTools in general use the `localhost:8081/json` (where `8081`
+is the port metro is running on) endpoint of metro to get the list of debuggable
+targets (runtimes). For a normal React Native app the output would look something
+like this:
+
+```json
+[
+  {
+    "id": "0-1",
+    "description": "org.reactjs.native.example.FabricExample",
+    "title": "Hermes React Native",
+    "faviconUrl": "https://reactjs.org/favicon.ico",
+    "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D1",
+    "type": "node",
+    "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=0&page=1",
+    "vm": "Hermes"
+  },
+  {
+    "id": "0--1",
+    "description": "org.reactjs.native.example.FabricExample",
+    "title": "React Native Experimental (Improved Chrome Reloads)",
+    "faviconUrl": "https://reactjs.org/favicon.ico",
+    "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D-1",
+    "type": "node",
+    "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=0&page=-1",
+    "vm": "don't use"
+  }
+]
+```
+
+For an Android app with Reanimated it should include the Reanimated runtime like
+this:
+
+```json
+[
+  {
+    "id": "0-2",
+    "description": "com.fabricexample",
+    "title": "Reanimated Runtime",
+    "faviconUrl": "https://reactjs.org/favicon.ico",
+    "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D3",
+    "type": "node",
+    "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=1&page=2",
+    "vm": "Hermes"
+  },
+  {
+    "id": "0-1",
+    "description": "com.fabricexample",
+    "title": "Hermes React Native",
+    "faviconUrl": "https://reactjs.org/favicon.ico",
+    "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D2",
+    "type": "node",
+    "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=1&page=1",
+    "vm": "Hermes"
+  },
+  {
+    "id": "0--1",
+    "description": "com.fabricexample",
+    "title": "React Native Experimental (Improved Chrome Reloads)",
+    "faviconUrl": "https://reactjs.org/favicon.ico",
+    "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D-1",
+    "type": "node",
+    "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=1&page=-1",
+    "vm": "don't use"
+  },
+  {
+    "id": "0--2",
+    "description": "com.fabricexample",
+    "title": "Reanimated Runtime Experimental (Improved Chrome Reloads)",
+    "faviconUrl": "https://reactjs.org/favicon.ico",
+    "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D-2",
+    "type": "node",
+    "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=1&page=-2",
+    "vm": "don't use"
+  }
+]
+```
+
+Runtimes with negative IDs are 'virtual' - they are just references to the real
+runtimes but their IDs don't change after a reload. If we were to connect to
+the normal runtime and reload the app it would crash, as the debugger would try
+to communicate with a non-existent runtime. These 'virtual' runtimes are made
+and managed by metro (PR: [facebook/metro#864](https://github.com/facebook/metro/pull/864)).
+
+## Known issues
+
+**IFrame sandboxing**
+
+Source maps always define a `sources` array, which contain names of files used
+to generate the source map. For Chrome DevTools this is sufficient as it will
+read files from disk, but the `IFrame` interface used by Flipper is sandboxed
+and doesn't allow filesystem access. Therefore we also need to include the files
+content in the `sourcesContent` array.
+
+**Chrome version 105.0.5195.102 doesn't load source maps**
+
+This version of Chrome introduced a regression into DevTools that broke source
+maps loading for node.js apps. This issue is not caused by Reanimated in any
+way and should be fixed by Chrome developers in later versions.
+
+The issue was tracked here: https://bugs.chromium.org/p/chromium/issues/detail?id=1358497
+
+**App reloads don't work**
+
+On iOS the app will crash on every reload if a debugger is connected to the runtime.
+On Android it will also crash but only after a few reloads.

package/Common/cpp/worklets/WorkletRuntime/UIRuntimeDecorator.cpp

@@ -0,0 +1,19 @@
+#include <worklets/Tools/WorkletsJSIUtils.h>
+#include <worklets/WorkletRuntime/UIRuntimeDecorator.h>
+
+#include <utility>
+
+namespace worklets {
+
+void UIRuntimeDecorator::decorate(
+    facebook::jsi::Runtime &uiRuntime,
+    std::function<
+        void(facebook::jsi::Runtime &rt, const facebook::jsi::Value &callback)>
+        &&requestAnimationFrame) {
+  uiRuntime.global().setProperty(uiRuntime, "_UI", true);
+
+  jsi_utils::installJsiFunction(
+      uiRuntime, "requestAnimationFrame", std::move(requestAnimationFrame));
+}
+
+} // namespace worklets

package/Common/cpp/worklets/WorkletRuntime/UIRuntimeDecorator.h

@@ -0,0 +1,16 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+namespace worklets {
+
+class UIRuntimeDecorator {
+ public:
+  static void decorate(
+      facebook::jsi::Runtime &uiRuntime,
+      std::function<void(
+          facebook::jsi::Runtime &rt,
+          const facebook::jsi::Value &callback)> &&requestAnimationFrame);
+};
+
+} // namespace worklets