@react-native-gpui/worklets 0.0.0-stage → 0.13.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@react-native-gpui/worklets` are listed here. Each version's section becomes the notes of its GitHub release.
+
+## 0.13.0-alpha.1 - 2026-11-12
+
+- Added a hook that runs after each frame's animation callbacks, which Reanimated uses to apply its pending updates.
+
+## 0.13.0-alpha.0 - 2026-11-01
+
+- First release, for `react-native-worklets` 0.13.x.
+- Runs worklets on desktop, driven by the renderer's frame clock.
+- Works with the npm release of `react-native-worklets`: the C++ fixes it needs for MSVC and Linux are applied to a copy in the build directory.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Streetwriters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @react-native-gpui/worklets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Adapter for [`react-native-worklets`](https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-worklets) (MIT): runs worklets on desktop, driven by the renderer's frame clock.
+
+Part of [react-native-gpui](https://github.com/streetwriters/react-native-gpui), React Native for macOS, Windows and Linux.
+
+## Install
+
+Install it next to `react-native-worklets`:
+
+```sh
+npm install react-native-worklets@0.13.x @react-native-gpui/worklets
+```
+
+Install the regular npm release of `react-native-worklets`. Its C++ needs small fixes to build with MSVC and on Linux; this package applies them to a copy in the desktop build directory and never changes `node_modules`.
+
+Keep using `react-native-worklets` as you do on iOS and Android; its JavaScript API is unchanged. Autolinking builds the desktop side when the app is built.
+
+## Documentation
+
+[Supported libraries](https://streetwriters.github.io/react-native-gpui/docs/supported-libraries)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/desktop/CMakeLists.txt

@@ -0,0 +1,52 @@
+if(NOT RN_GPUI_PROJECT_ROOT)
+  message(FATAL_ERROR
+    "@react-native-gpui/worklets was added by the platform; RN_GPUI_PROJECT_ROOT must be set by its build.rs")
+endif()
+set(_gpui_app_root "${RN_GPUI_PROJECT_ROOT}")
+find_program(_gpui_node node REQUIRED)
+execute_process(
+  COMMAND "${_gpui_node}" -e "process.stdout.write(require.resolve('react-native-worklets/package.json', {paths: [process.argv[1]]}))" "${_gpui_app_root}"
+  RESULT_VARIABLE _worklets_resolve_result
+  OUTPUT_VARIABLE _worklets_package_json
+  OUTPUT_STRIP_TRAILING_WHITESPACE)
+if(NOT _worklets_resolve_result EQUAL 0 OR NOT EXISTS "${_worklets_package_json}")
+  message(FATAL_ERROR "react-native-worklets could not be resolved from ${_gpui_app_root}")
+endif()
+get_filename_component(_worklets_root "${_worklets_package_json}" DIRECTORY)
+set(_worklets_common "${_worklets_root}/Common/cpp")
+if(NOT EXISTS "${_worklets_common}/worklets/NativeModules/WorkletsModuleProxy.h")
+  message(FATAL_ERROR "react-native-worklets 0.13.x was not found in ${_gpui_app_root} or any ancestor node_modules directory")
+endif()
+
+# Upstream's C++ does not build with MSVC or on Linux as published; compile a
+# patched copy in the build tree and leave node_modules untouched.
+set(_worklets_patch "${CMAKE_CURRENT_LIST_DIR}/patches/react-native-worklets-0.13.0.patch")
+execute_process(
+  COMMAND "${_gpui_node}" "${CMAKE_CURRENT_LIST_DIR}/patch-sources.mjs"
+    "${_worklets_root}" "${_worklets_patch}"
+    "${CMAKE_BINARY_DIR}/rn-gpui-patched/react-native-worklets"
+  RESULT_VARIABLE _worklets_patch_result
+  OUTPUT_VARIABLE _worklets_common
+  ERROR_VARIABLE _worklets_patch_error
+  OUTPUT_STRIP_TRAILING_WHITESPACE)
+if(NOT _worklets_patch_result EQUAL 0)
+  message(FATAL_ERROR "${_worklets_patch_error}")
+endif()
+set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
+  "${_worklets_patch}" "${_worklets_package_json}")
+
+file(GLOB_RECURSE _worklets_sources CONFIGURE_DEPENDS "${_worklets_common}/worklets/*.cpp")
+set_property(GLOBAL APPEND PROPERTY RN_GPUI_APP_CPP_SOURCES
+  ${_worklets_sources}
+  "${CMAKE_CURRENT_LIST_DIR}/cpp/GPUIWorkletsModule.cpp"
+  "${CMAKE_CURRENT_LIST_DIR}/cpp/GPUIPlatformLogger.cpp")
+set_property(GLOBAL APPEND PROPERTY RN_GPUI_APP_CPP_INCLUDE_DIRS
+  "${_worklets_common}"
+  "${_worklets_root}")
+set_property(GLOBAL APPEND PROPERTY RN_GPUI_APP_CPP_DEFINITIONS
+  "WORKLETS_VERSION=0.13.0")
+# The frame hook is how worklets see every frame; the platform compiles this
+# glue only because the package is installed.
+set_property(GLOBAL APPEND PROPERTY RN_GPUI_PACKAGE_MODULE_SOURCES
+  "${CMAKE_CURRENT_LIST_DIR}/cpp/GpuiWorkletsFrameModule.cpp")
+set_property(GLOBAL APPEND PROPERTY RN_GPUI_PACKAGE_MODULE_INSTALLERS worklets)

package/desktop/cpp/GPUIPlatformLogger.cpp

@@ -0,0 +1,27 @@
+#include <worklets/Tools/PlatformLogger.h>
+
+#include <glog/logging.h>
+
+namespace worklets {
+
+void PlatformLogger::log(const char* str) {
+  LOG(INFO) << str;
+}
+
+void PlatformLogger::log(const std::string& str) {
+  LOG(INFO) << str;
+}
+
+void PlatformLogger::log(const double value) {
+  LOG(INFO) << value;
+}
+
+void PlatformLogger::log(const int value) {
+  LOG(INFO) << value;
+}
+
+void PlatformLogger::log(const bool value) {
+  LOG(INFO) << (value ? "true" : "false");
+}
+
+} // namespace worklets

package/desktop/cpp/GPUIWorkletsModule.cpp

@@ -0,0 +1,353 @@
+#include "GPUIWorkletsModule.h"
+
+#include "rn-gpui-sys/src/lib.rs.h"
+
+#include <glog/logging.h>
+#include <worklets/Tools/JSLogger.h>
+#include <worklets/WorkletRuntime/RuntimeBindings.h>
+#include <worklets/WorkletRuntime/WorkletRuntime.h>
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <cstdlib>
+#include <stdexcept>
+#include <thread>
+#include <utility>
+
+#include "GpuiModules.h"
+
+namespace {
+bool animationTracingEnabled() {
+  static const bool enabled = std::getenv("RN_GPUI_DEBUG_ANIMATION") != nullptr;
+  return enabled;
+}
+
+std::mutex moduleMutex;
+std::weak_ptr<gpui_worklets::Module> moduleInstance;
+std::atomic<uint64_t> workletFrames{0};
+std::atomic<uint64_t> workletRafRequests{0};
+
+class GPUIScheduler final : public worklets::UIScheduler {
+ protected:
+  bool queryIsOnUIThread() const override {
+    return gpui_worklets::isOnMainThread();
+  }
+
+ public:
+  void scheduleOnUI(std::function<void()> job) override {
+    static std::atomic<uint64_t> scheduled{0};
+    const auto count = ++scheduled;
+    if (animationTracingEnabled() && count <= 5) {
+      LOG(INFO) << "[gpui-worklets] scheduleOnUI count=" << count
+                << " onUI=" << isOnUIThread();
+    }
+    if (isOnUIThread()) {
+      job();
+      return;
+    }
+    UIScheduler::scheduleOnUI(std::move(job));
+    rngpui::requestFrames("worklets", true);
+  }
+};
+
+worklets::RuntimeBindings::NativeLoggingHook nativeLoggingHook() {
+  return [](facebook::jsi::Runtime& runtime,
+            const facebook::jsi::Value&,
+            const facebook::jsi::Value* args,
+            size_t count) -> facebook::jsi::Value {
+    if (count != 2) {
+      throw std::invalid_argument("nativeLoggingHook takes 2 arguments");
+    }
+    const auto message = args[0].asString(runtime).utf8(runtime);
+    LOG(INFO) << "[worklet] " << message;
+    return facebook::jsi::Value::undefined();
+  };
+}
+} // namespace
+
+namespace gpui_worklets {
+namespace {
+std::mutex uiThreadMutex;
+std::thread::id uiThreadId;
+} // namespace
+
+bool isOnMainThread() {
+  // The runtime records the main thread before its loop runs. `onFrame` only
+  // notes it once a frame arrives, and `UIScheduler::isOnUIThread` caches the
+  // first answer per thread: a query that comes first, such as a layout
+  // animation flush, would pin "not the UI thread" on the main thread for good.
+  if (rngpui::rn_gpui_is_main_thread()) {
+    return true;
+  }
+  std::lock_guard<std::mutex> lock(uiThreadMutex);
+  return uiThreadId != std::thread::id{} &&
+      uiThreadId == std::this_thread::get_id();
+}
+
+void noteMainThread() {
+  std::lock_guard<std::mutex> lock(uiThreadMutex);
+  if (uiThreadId == std::thread::id{}) {
+    uiThreadId = std::this_thread::get_id();
+  }
+}
+
+Module::Module(std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+    : NativeWorkletsModuleSpec(std::move(jsInvoker)) {}
+
+Module::~Module() {
+  rngpui::reportPendingWork("worklets", 0);
+  rngpui::requestFrames("worklets", false);
+  if (initializer_) {
+    initializer_->invalidate();
+  }
+  std::lock_guard<std::mutex> lock(moduleMutex);
+  if (moduleInstance.lock().get() == this) {
+    moduleInstance.reset();
+  }
+}
+
+void Module::initialize(facebook::jsi::Runtime& runtime) {
+  if (initializer_)
+    return;
+  uiScheduler_ = std::make_shared<GPUIScheduler>();
+  runtimeStatus_ = std::make_shared<worklets::RNRuntimeStatus>();
+  jsScheduler_ = std::make_shared<worklets::JSScheduler>(
+      runtime, jsInvoker_, [] { return true; });
+  std::weak_ptr<Module> weakModule = shared_from_this();
+  auto runtimeBindings =
+      std::make_shared<worklets::RuntimeBindings>(worklets::RuntimeBindings{
+          .requestAnimationFrame =
+              [weakModule](std::function<void(double)> callback) {
+                if (auto module = weakModule.lock()) {
+                  module->requestAnimationFrame(std::move(callback));
+                }
+              },
+          .nativeLoggingHook = nativeLoggingHook(),
+          .networkingBackend = nullptr,
+      });
+  initializer_ = std::make_shared<worklets::WorkletsModuleProxyInitializer>(
+      jsScheduler_, uiScheduler_, runtimeBindings, runtimeStatus_);
+  LOG(INFO) << "[gpui-worklets] initialized runtime bindings";
+  auto initializer = initializer_;
+  std::thread([initializer] { initializer->prepareProxy(); }).detach();
+}
+
+bool Module::installTurboModule(
+    facebook::jsi::Runtime& runtime,
+    bool bundleModeEnabled) {
+  initialize(runtime);
+  if (bundleModeEnabled) {
+    throw facebook::jsi::JSError(
+        runtime, "GPUI Worklets does not support Bundle Mode yet");
+  }
+  proxy_ = initializer_->finalize(runtime, false, {});
+  LOG(INFO) << "[gpui-worklets] WorkletsModule installed";
+  return true;
+}
+
+bool Module::prepareBundleMode(facebook::jsi::Runtime& runtime) {
+  throw facebook::jsi::JSError(
+      runtime, "GPUI Worklets does not support Bundle Mode yet");
+}
+
+bool Module::start(facebook::jsi::Runtime& runtime) {
+  if (!proxy_)
+    throw facebook::jsi::JSError(
+        runtime, "WorkletsModule.installTurboModule must run before start");
+  proxy_->start();
+  LOG(INFO) << "[gpui-worklets] UI runtime started";
+  return true;
+}
+
+bool Module::toggleSlowAnimationsOnUIRuntime(facebook::jsi::Runtime&) {
+  return false;
+}
+
+void Module::requestAnimationFrame(std::function<void(double)> callback) {
+  const auto count = ++workletRafRequests;
+  if (animationTracingEnabled() && count <= 5) {
+    LOG(INFO) << "[gpui-worklets] requestAnimationFrame count=" << count;
+  }
+  {
+    std::lock_guard<std::mutex> lock(callbacksMutex_);
+    frameCallbacks_.push_back(std::move(callback));
+  }
+  rngpui::requestFrames("worklets", true);
+}
+
+void Module::setAfterFrame(std::function<void()> afterFrame) {
+  std::lock_guard<std::mutex> lock(callbacksMutex_);
+  afterFrame_ = std::move(afterFrame);
+}
+
+void Module::onFrame(double timestampMs) {
+  const auto count = ++workletFrames;
+  if (animationTracingEnabled()) {
+    static double windowStartMs = timestampMs;
+    static double previousFrameMs = timestampMs;
+    static double maximumGapMs = 0;
+    maximumGapMs = std::max(maximumGapMs, timestampMs - previousFrameMs);
+    previousFrameMs = timestampMs;
+    if (count % 60 == 0) {
+      LOG(INFO) << "[gpui-worklets] native frame cadence frames=60 elapsed_ms="
+                << timestampMs - windowStartMs
+                << " max_frame_gap_ms=" << maximumGapMs;
+      windowStartMs = timestampMs;
+      maximumGapMs = 0;
+    }
+  }
+  if (animationTracingEnabled() && (count <= 5 || count % 600 == 0)) {
+    LOG(INFO) << "[gpui-worklets] GPUI frame count=" << count;
+  }
+  // Frame callbacks are platform entry points, outside Worklets' guarded
+  // invocation paths. Report JS exceptions on RN rather than unwinding across
+  // the CXX boundary and terminating the desktop process.
+  const auto reportError = [this](const facebook::jsi::JSError& error) {
+    LOG(ERROR) << "[gpui-worklets] " << error.what();
+    worklets::JSLogger::reportFatalErrorOnJS(
+        jsScheduler_,
+        {.message = error.getMessage(),
+         .stack = error.getStack(),
+         .name = "WorkletsError"});
+  };
+  try {
+    if (uiScheduler_)
+      uiScheduler_->triggerUI();
+  } catch (const facebook::jsi::JSError& error) {
+    reportError(error);
+  }
+  // Worklets has a perpetual native heartbeat even when its JS RAF queue is
+  // empty. Test synchronization observes application callbacks, not that beat.
+  if (std::getenv("RN_GPUI_TEST_DRIVER")) {
+    if (auto runtime = uiRuntime()) {
+      runtime->runSync([](facebook::jsi::Runtime& rt) {
+        auto global = rt.global();
+        if (!global.hasProperty(rt, "requestAnimationFrame") ||
+            (global.hasProperty(rt, "__gpuiTestRaf") &&
+             facebook::jsi::Value::strictEquals(
+                 rt,
+                 global.getProperty(rt, "requestAnimationFrame"),
+                 global.getProperty(rt, "__gpuiTestRaf"))))
+          return;
+        global.setProperty(
+            rt,
+            "__gpuiReportPendingRaf",
+            facebook::jsi::Function::createFromHostFunction(
+                rt,
+                facebook::jsi::PropNameID::forAscii(
+                    rt, "__gpuiReportPendingRaf"),
+                1,
+                [](facebook::jsi::Runtime&,
+                   const facebook::jsi::Value&,
+                   const facebook::jsi::Value* args,
+                   size_t count) {
+                  if (count == 1 && args[0].isNumber())
+                    rngpui::reportPendingWork(
+                        "worklets", static_cast<uint64_t>(args[0].getNumber()));
+                  return facebook::jsi::Value::undefined();
+                }));
+        rt.evaluateJavaScript(
+            std::make_shared<facebook::jsi::StringBuffer>(R"JS(
+          (() => {
+            const raf = globalThis.requestAnimationFrame;
+            const cancel = globalThis.cancelAnimationFrame;
+            const pending = new Set();
+            const report = () => globalThis.__gpuiReportPendingRaf(pending.size);
+            globalThis.requestAnimationFrame = callback => {
+              let id;
+              id = raf(timestamp => {
+                pending.delete(id); report(); callback(timestamp);
+              });
+              pending.add(id); report(); return id;
+            };
+            globalThis.cancelAnimationFrame = id => {
+              pending.delete(id); report(); cancel(id);
+            };
+            globalThis.__gpuiTestRaf = globalThis.requestAnimationFrame;
+            report();
+          })();
+        )JS"),
+            "gpui-test-raf.js");
+      });
+    }
+  }
+  std::vector<std::function<void(double)>> callbacks;
+  {
+    std::lock_guard<std::mutex> lock(callbacksMutex_);
+    callbacks.swap(frameCallbacks_);
+  }
+  if (animationTracingEnabled() && !callbacks.empty() &&
+      (count <= 5 || count % 60 == 0)) {
+    LOG(INFO) << "[gpui-worklets] callbacks on frame=" << callbacks.size();
+  }
+  for (auto& callback : callbacks) {
+    try {
+      callback(timestampMs);
+    } catch (const facebook::jsi::JSError& error) {
+      reportError(error);
+    }
+  }
+  std::function<void()> afterFrame;
+  {
+    std::lock_guard<std::mutex> lock(callbacksMutex_);
+    afterFrame = afterFrame_;
+  }
+  if (afterFrame) {
+    try {
+      afterFrame();
+    } catch (const facebook::jsi::JSError& error) {
+      reportError(error);
+    }
+  }
+  {
+    std::lock_guard<std::mutex> lock(callbacksMutex_);
+    if (frameCallbacks_.empty()) {
+      rngpui::requestFrames("worklets", false);
+    }
+  }
+}
+
+std::shared_ptr<worklets::WorkletRuntime> Module::uiRuntime() const {
+  return proxy_ ? proxy_->getUIWorkletRuntime() : nullptr;
+}
+
+std::shared_ptr<worklets::UIScheduler> Module::uiScheduler() const {
+  return uiScheduler_;
+}
+
+void onFrame(double timestampMs) {
+  noteMainThread();
+  std::shared_ptr<Module> module;
+  {
+    std::lock_guard<std::mutex> lock(moduleMutex);
+    module = moduleInstance.lock();
+  }
+  if (module)
+    module->onFrame(timestampMs);
+}
+
+std::shared_ptr<Module> currentModule() {
+  std::lock_guard<std::mutex> lock(moduleMutex);
+  return moduleInstance.lock();
+}
+
+std::shared_ptr<facebook::react::TurboModule> createModule(
+    const std::string& name,
+    std::shared_ptr<facebook::react::CallInvoker> jsInvoker) {
+  if (name != Module::kModuleName)
+    return nullptr;
+  auto module = std::make_shared<Module>(std::move(jsInvoker));
+  {
+    std::lock_guard<std::mutex> lock(moduleMutex);
+    moduleInstance = module;
+  }
+  return module;
+}
+} // namespace gpui_worklets
+
+std::shared_ptr<facebook::react::TurboModule> create_gpui_worklets_module(
+    const std::string& name,
+    std::shared_ptr<facebook::react::CallInvoker> jsInvoker) {
+  return gpui_worklets::createModule(name, std::move(jsInvoker));
+}

package/desktop/cpp/GPUIWorkletsModule.h

@@ -0,0 +1,64 @@
+#pragma once
+
+#include <GPUIWorkletsSpec.h>
+#include <ReactCommon/CallInvoker.h>
+#include <ReactCommon/TurboModule.h>
+#include <worklets/NativeModules/WorkletsModuleProxy.h>
+#include <worklets/NativeModules/WorkletsModuleProxyInitializer.h>
+#include <worklets/Tools/JSScheduler.h>
+#include <worklets/Tools/RNRuntimeStatus.h>
+#include <worklets/Tools/UIScheduler.h>
+
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <vector>
+
+namespace gpui_worklets {
+bool isOnMainThread();
+void noteMainThread();
+
+class Module final : public facebook::react::NativeWorkletsModuleSpec<Module> {
+ public:
+  explicit Module(std::shared_ptr<facebook::react::CallInvoker> jsInvoker);
+  ~Module() override;
+
+  void onFrame(double timestampMs);
+  void requestAnimationFrame(std::function<void(double)> callback);
+  /// Runs after every frame's animation callbacks, as the display link's
+  /// handler does on iOS.
+  void setAfterFrame(std::function<void()> afterFrame);
+  std::shared_ptr<worklets::WorkletRuntime> uiRuntime() const;
+  std::shared_ptr<worklets::UIScheduler> uiScheduler() const;
+
+  bool installTurboModule(
+      facebook::jsi::Runtime& runtime,
+      bool bundleModeEnabled);
+  bool prepareBundleMode(facebook::jsi::Runtime& runtime);
+  bool start(facebook::jsi::Runtime& runtime);
+  bool toggleSlowAnimationsOnUIRuntime(facebook::jsi::Runtime& runtime);
+
+ private:
+  void initialize(facebook::jsi::Runtime& runtime);
+
+  std::shared_ptr<worklets::UIScheduler> uiScheduler_;
+  std::shared_ptr<worklets::JSScheduler> jsScheduler_;
+  std::shared_ptr<worklets::RNRuntimeStatus> runtimeStatus_;
+  std::shared_ptr<worklets::WorkletsModuleProxyInitializer> initializer_;
+  std::shared_ptr<worklets::WorkletsModuleProxy> proxy_;
+  std::mutex callbacksMutex_;
+  std::vector<std::function<void(double)>> frameCallbacks_;
+  std::function<void()> afterFrame_;
+};
+
+void onFrame(double timestampMs);
+std::shared_ptr<Module> currentModule();
+std::shared_ptr<facebook::react::TurboModule> createModule(
+    const std::string& name,
+    std::shared_ptr<facebook::react::CallInvoker> jsInvoker);
+
+} // namespace gpui_worklets
+
+std::shared_ptr<facebook::react::TurboModule> create_gpui_worklets_module(
+    const std::string& name,
+    std::shared_ptr<facebook::react::CallInvoker> jsInvoker);

package/desktop/cpp/GpuiWorkletsFrameModule.cpp

@@ -0,0 +1,13 @@
+#include "GpuiModules.h"
+
+namespace gpui_worklets {
+void onFrame(double timestampMs);
+}
+
+namespace rngpui {
+void rn_gpui_install_worklets_module() {
+  registerFrameCallback(
+      [](double timestampMs) { gpui_worklets::onFrame(timestampMs); });
+}
+
+} // namespace rngpui

package/desktop/patch-sources.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Copies an upstream package's `Common/cpp` into a build directory and applies a
+// unified diff to the copy, so the app's node_modules is never modified.
+//
+//   node patch-sources.mjs <package root> <patch file> <output dir>
+//
+// Prints the patched `Common/cpp` directory. The copy is reused while the
+// package version and the patch are unchanged.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Parses a unified diff into files, each with its hunks. */
+export function parsePatch(text) {
+  const files = [];
+  let file = null;
+  let hunk = null;
+  // Lines still expected in the current hunk, from its header counts.
+  let oldLeft = 0;
+  let newLeft = 0;
+  for (const line of text.replace(/\r\n/gu, '\n').split('\n')) {
+    if (hunk !== null && (oldLeft > 0 || newLeft > 0)) {
+      const kind = line.length === 0 ? ' ' : line[0];
+      const body = line.slice(1);
+      if (kind === ' ' || kind === '-') {
+        hunk.old.push(body);
+        oldLeft--;
+      }
+      if (kind === ' ' || kind === '+') {
+        hunk.new.push(body);
+        newLeft--;
+      }
+      if (kind === '\\') continue;
+    } else if (line.startsWith('--- ')) {
+      file = { path: null, hunks: [] };
+      files.push(file);
+      hunk = null;
+    } else if (line.startsWith('+++ ') && file !== null) {
+      file.path = line.slice(4).split('\t')[0].replace(/^b\//u, '');
+    } else if (line.startsWith('@@ ') && file !== null) {
+      const match = /^@@ -(\d+)(?:,(\d+))? \+\d+(?:,(\d+))? @@/u.exec(line);
+      if (match === null) throw new Error(`bad hunk header: ${line}`);
+      hunk = { start: Number(match[1]), old: [], new: [] };
+      oldLeft = match[2] === undefined ? 1 : Number(match[2]);
+      newLeft = match[3] === undefined ? 1 : Number(match[3]);
+      file.hunks.push(hunk);
+    }
+  }
+  return files;
+}
+
+function matchesAt(lines, block, at) {
+  if (at < 0 || at + block.length > lines.length) return false;
+  return block.every((line, i) => lines[at + i] === line);
+}
+
+/** The line nearest `expected` where `block` starts, or -1. */
+function find(lines, block, expected) {
+  for (let delta = 0; delta <= lines.length; delta++) {
+    if (matchesAt(lines, block, expected - delta)) return expected - delta;
+    if (matchesAt(lines, block, expected + delta)) return expected + delta;
+  }
+  return -1;
+}
+
+/**
+ * Applies one file's hunks to its text, keeping its line endings. A hunk whose
+ * result is already present
+ * is skipped, so sources that carry the fix upstream still build; any other
+ * mismatch throws.
+ */
+export function applyHunks(text, hunks, name) {
+  const crlf = text.includes('\r\n');
+  const lines = text.replace(/\r\n/gu, '\n').split('\n');
+  let offset = 0;
+  for (const hunk of hunks) {
+    const expected = Math.max(hunk.start - 1, 0) + offset;
+    const at = find(lines, hunk.old, expected);
+    if (at !== -1) {
+      lines.splice(at, hunk.old.length, ...hunk.new);
+      offset = at - (hunk.start - 1) + hunk.new.length - hunk.old.length;
+      continue;
+    }
+    const applied = find(lines, hunk.new, expected);
+    if (applied === -1) {
+      throw new Error(`${name}: hunk at line ${hunk.start} does not apply`);
+    }
+    offset = applied - (hunk.start - 1);
+  }
+  return lines.join(crlf ? '\r\n' : '\n');
+}
+
+function main([packageRoot, patchFile, outputDir]) {
+  if (!packageRoot || !patchFile || !outputDir) {
+    throw new Error(
+      'usage: patch-sources.mjs <package root> <patch file> <output dir>',
+    );
+  }
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
+  );
+  const patch = fs.readFileSync(patchFile, 'utf8');
+  const stamp = createHash('sha256')
+    .update(`${manifest.name}@${manifest.version}\n`)
+    .update(patch)
+    .digest('hex');
+  const target = path.join(outputDir, 'Common', 'cpp');
+  const stampFile = path.join(outputDir, '.patched');
+  const current = fs.existsSync(stampFile)
+    ? fs.readFileSync(stampFile, 'utf8')
+    : '';
+  if (current !== stamp) {
+    fs.rmSync(outputDir, { recursive: true, force: true });
+    fs.cpSync(path.join(packageRoot, 'Common', 'cpp'), target, {
+      recursive: true,
+    });
+    for (const file of parsePatch(patch)) {
+      const full = path.join(target, file.path);
+      const original = fs.existsSync(full) ? fs.readFileSync(full, 'utf8') : '';
+      let patched;
+      try {
+        patched = applyHunks(original, file.hunks, file.path);
+      } catch (error) {
+        fs.rmSync(outputDir, { recursive: true, force: true });
+        throw new Error(
+          `${path.basename(patchFile)} does not apply to ${manifest.name}@${manifest.version}: ${error.message}`,
+        );
+      }
+      fs.mkdirSync(path.dirname(full), { recursive: true });
+      fs.writeFileSync(full, patched);
+    }
+    fs.writeFileSync(stampFile, stamp);
+  }
+  // CMake reads backslashes as escapes.
+  process.stdout.write(target.split(path.sep).join('/'));
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+}

package/desktop/patches/react-native-worklets-0.13.0.patch

@@ -0,0 +1,107 @@
+--- a/worklets/RunLoop/AsyncQueueImpl.cpp
++++ b/worklets/RunLoop/AsyncQueueImpl.cpp
+@@ -4,6 +4,10 @@
+ #include <fbjni/fbjni.h>
+ #endif // ANDROID
+ 
++#if defined(__APPLE__) || defined(__linux__)
++#include <pthread.h>
++#endif
++
+ #include <memory>
+ #include <queue>
+ #include <string>
+@@ -69,7 +73,11 @@
+     pthread_setname_np(pthread_self(), name.c_str());
+     jni::ThreadScope::WithClassLoader([state]() { AsyncQueueImpl::runLoop(state); });
+ #else
++#if defined(__APPLE__)
+     pthread_setname_np(name.c_str());
++#elif defined(__linux__)
++    pthread_setname_np(pthread_self(), name.substr(0, 15).c_str());
++#endif
+     AsyncQueueImpl::runLoop(state);
+ #endif // ANDROID
+   });
+--- a/worklets/RunLoop/EventLoop.cpp
++++ b/worklets/RunLoop/EventLoop.cpp
+@@ -1,5 +1,6 @@
+ #include <worklets/RunLoop/EventLoop.h>
+ 
++#include <algorithm>
+ #include <memory>
+ #include <string>
+ #include <thread>
+--- a/worklets/Tools/JSISerializer.cpp
++++ b/worklets/Tools/JSISerializer.cpp
+@@ -1,7 +1,10 @@
+ #include <worklets/Tools/JSISerializer.h>
+ 
++#ifndef _MSC_VER
+ #include <cxxabi.h>
++#endif
+ 
++#include <algorithm>
+ #include <memory>
+ #include <sstream>
+ #include <string>
+@@ -116,15 +119,20 @@
+ }
+ 
+ std::string JSISerializer::stringifyHostObject(jsi::HostObject &hostObject) {
++#ifdef _MSC_VER
++  const char *hostObjClassName = typeid(hostObject).name();
++#else
+   int status = -1;
+-  std::unique_ptr<char, decltype(&std::free)> hostObjClassName(
++  std::unique_ptr<char, decltype(&std::free)> demangled(
+       abi::__cxa_demangle(typeid(hostObject).name(), nullptr, nullptr, &status), std::free);
+   if (status != 0) {
+     return "[jsi::HostObject]";
+   }
++  const char *hostObjClassName = demangled.get();
++#endif
+ 
+   std::stringstream ss;
+-  ss << "[jsi::HostObject(" << hostObjClassName.get() << ")";
++  ss << "[jsi::HostObject(" << hostObjClassName << ")";
+ 
+   auto props = hostObject.getPropertyNames(rt_);
+   auto propsCount = props.size();
+--- a/worklets/Tools/SingleInstanceChecker.h
++++ b/worklets/Tools/SingleInstanceChecker.h
+@@ -4,7 +4,9 @@
+ 
+ #include <react/debug/react_native_assert.h>
+ 
++#ifndef _MSC_VER
+ #include <cxxabi.h>
++#endif
+ 
+ #include <atomic>
+ #include <cassert>
+@@ -50,10 +52,14 @@
+ 
+ template <class T>
+ SingleInstanceChecker<T>::SingleInstanceChecker() {
++#ifdef _MSC_VER
++  std::string className = typeid(T).name();
++#else
+   int status = 0;
+   char *demangled = __cxxabiv1::__cxa_demangle(typeid(T).name(), nullptr, nullptr, &status);
+   std::string className = (status == 0 && demangled != nullptr) ? demangled : typeid(T).name();
+   std::free(demangled);
++#endif
+ 
+   // React Native can spawn up to two instances of a Native Module at the same
+   // time. This happens during a reload when a new instance of React Native is
+--- a/worklets/Tools/WorkletsJSIUtils.cpp
++++ b/worklets/Tools/WorkletsJSIUtils.cpp
+@@ -2,6 +2,7 @@
+ 
+ #include <react/debug/react_native_assert.h>
+ 
++#include <iterator>
+ #include <memory>
+ #include <sstream>
+ #include <string>

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@react-native-gpui/worklets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.13.0-alpha.1",
+  "description": "Adapter for react-native-worklets (MIT): runs worklets on desktop, driven by the renderer's frame clock",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/streetwriters/react-native-gpui-modules.git",
+    "directory": "modules/worklets"
+  },
+  "homepage": "https://github.com/streetwriters/react-native-gpui-modules/tree/main/modules/worklets#readme",
+  "bugs": {
+    "url": "https://github.com/streetwriters/react-native-gpui-modules/issues"
+  },
+  "files": [
+    "desktop",
+    "react-native.config.js",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "!**/*.test.js",
+    "!**/*.test.mjs",
+    "!**/*.test.ts",
+    "!**/*.test.cjs"
+  ],
+  "peerDependencies": {
+    "react-native": "0.87.x",
+    "react-native-worklets": "0.13.x"
+  },
+  "codegenConfig": {
+    "name": "GPUIWorkletsSpec",
+    "type": "modules",
+    "jsSrcsDir": "src"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      desktop: {
+        cmake: 'desktop',
+        cppProvider: 'create_gpui_worklets_module',
+      },
+    },
+  },
+};

package/src/NativeWorkletsModule.ts

@@ -0,0 +1,10 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+export interface Spec extends TurboModule {
+  installTurboModule(bundleModeEnabled: boolean): boolean;
+  prepareBundleMode(): boolean;
+  toggleSlowAnimationsOnUIRuntime(): boolean;
+  start(): boolean;
+}
+
+export default TurboModuleRegistry.get<Spec>('WorkletsModule');