react-native-webgpu 0.13.1 → 0.14.1

package/android/CMakeLists.txt

@@ -54,6 +54,7 @@ add_library(${PACKAGE_NAME} SHARED
     ../cpp/rnwgpu/api/GPUComputePipeline.cpp
     ../cpp/rnwgpu/api/GPUCanvasContext.cpp
     ../cpp/rnwgpu/RNWebGPUManager.cpp
+    ../cpp/rnwgpu/WebGPURuntime.cpp
     ../cpp/jsi/Promise.cpp
     ../cpp/jsi/JSICache.cpp
     ../cpp/rnwgpu/async/RuntimeContext.cpp

package/android/cpp/AndroidPlatformContext.h

@@ -131,15 +131,6 @@ public:
     }
   }
 
-  wgpu::Surface makeSurface(wgpu::Instance instance, void *window, int width,
-                            int height) override {
-    wgpu::SurfaceSourceAndroidNativeWindow androidSurfaceDesc;
-    androidSurfaceDesc.window = reinterpret_cast<ANativeWindow *>(window);
-    wgpu::SurfaceDescriptor surfaceDescriptor;
-    surfaceDescriptor.nextInChain = &androidSurfaceDesc;
-    return instance.CreateSurface(&surfaceDescriptor);
-  }
-
   ImageData createImageBitmap(std::string blobId, double offset,
                               double size) override {
     jni::Environment::ensureCurrentThreadIsAttached();

package/android/cpp/cpp-adapter.cpp

@@ -17,6 +17,7 @@
 #include "AndroidPlatformContext.h"
 #include "GPUCanvasContext.h"
 #include "RNWebGPUManager.h"
+#include "WebGPURuntime.h"
 
 #define LOG_TAG "WebGPUModule"
 
@@ -116,9 +117,9 @@ extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUView_onSurfaceCreate(
     return;
   }
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
-  auto gpu = manager->_gpu;
-  auto surface = manager->_platformContext->makeSurface(
-      gpu, window, static_cast<int>(width), static_cast<int>(height));
+  auto &runtime = rnwgpu::WebGPURuntime::shared();
+  auto gpu = runtime.instance();
+  auto surface = runtime.makeSurface(window);
   // Find-or-create + attach runs atomically under the registry lock so a
   // concurrent destroyContext cannot orphan this surface.
   auto info = registry.attachSurface(
@@ -212,7 +213,8 @@ Java_com_webgpu_WebGPUHardwareBufferView_nEnablePool(JNIEnv *env, jobject thiz,
                                                      jint dpH) {
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
   auto info = registry.getSurfaceInfoOrCreate(
-      contextId, manager->_gpu, static_cast<int>(dpW), static_cast<int>(dpH));
+      contextId, rnwgpu::WebGPURuntime::shared().instance(),
+      static_cast<int>(dpW), static_cast<int>(dpH));
   auto waker = std::make_shared<HardwareBufferViewWaker>(env, thiz);
   info->setPoolFrameReadyCallback([waker]() { (*waker)(); });
   info->enablePool(static_cast<int>(dpW), static_cast<int>(dpH));

package/android/src/main/java/com/webgpu/WebGPUView.java

@@ -27,6 +27,14 @@ public class WebGPUView extends ReactViewGroup implements WebGPUAPI {
 
   WebGPUView(Context context) {
     super(context);
+    // ReactViewGroup disables clipChildren (RN overflow is handled with canvas
+    // clipping instead). Android copies the parent's clipChildren into each
+    // child's RenderNode.clipToBounds, and HWUI treats a damaged node without
+    // it as unbounded damage (RenderNode::damageSelf). The TextureView and
+    // HardwareBufferView children invalidate on every frame, so without this
+    // every non-opaque canvas frame repaints the whole window. Our only child
+    // exactly fills this view, so clipping it changes nothing visually.
+    setClipChildren(true);
   }
 
   public void setContextId(int contextId) {

package/apple/ApplePlatformContext.h

@@ -20,9 +20,6 @@ public:
                     std::function<void(ImageData)> onSuccess,
                     std::function<void(std::string)> onError) override;
 
-  wgpu::Surface makeSurface(wgpu::Instance instance, void *surface, int width,
-                            int height) override;
-
   ImageData createImageBitmap(std::string blobId, double offset,
                               double size) override;
 

package/apple/ApplePlatformContext.mm

@@ -209,16 +209,6 @@ void ApplePlatformContext::snapshotView(
   });
 }
 
-wgpu::Surface ApplePlatformContext::makeSurface(wgpu::Instance instance,
-                                                void *surface, int width,
-                                                int height) {
-  wgpu::SurfaceSourceMetalLayer metalSurfaceDesc;
-  metalSurfaceDesc.layer = surface;
-  wgpu::SurfaceDescriptor surfaceDescriptor;
-  surfaceDescriptor.nextInChain = &metalSurfaceDesc;
-  return instance.CreateSurface(&surfaceDescriptor);
-}
-
 static std::span<const uint8_t> nsDataToSpan(NSData *data) {
   return {static_cast<const uint8_t *>(data.bytes), data.length};
 }

package/apple/MetalView.mm

@@ -1,4 +1,5 @@
 #import "MetalView.h"
+#import "WebGPURuntime.h"
 #import "webgpu/webgpu_cpp.h"
 
 @implementation MetalView {
@@ -32,9 +33,9 @@
   // dealloc runs. Balanced by the releaser below.
   void *nativeSurface = (void *)CFBridgingRetain(self.layer);
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
-  auto gpu = manager->_gpu;
-  auto surface = manager->_platformContext->makeSurface(
-      gpu, nativeSurface, size.width, size.height);
+  auto &runtime = rnwgpu::WebGPURuntime::shared();
+  auto gpu = runtime.instance();
+  auto surface = runtime.makeSurface(nativeSurface);
   // Find-or-create + attach runs atomically under the registry lock so a
   // concurrent destroyContext cannot orphan this surface.
   auto info = registry.attachSurface(

package/cpp/jsi/JSIConverter.h

@@ -13,6 +13,7 @@
 
 #include "WGPULogger.h"
 
+#include "EnforceRange.h"
 #include "EnumMapper.h"
 #include "Promise.h"
 
@@ -49,7 +50,7 @@ private:
 // int <> number
 template <> struct JSIConverter<int> {
   static int fromJSI(jsi::Runtime&, const jsi::Value& arg, bool outOfBound) {
-    return static_cast<int>(arg.asNumber());
+    return enforceRange<int>(arg.asNumber());
   }
   static jsi::Value toJSI(jsi::Runtime&, int arg) {
     return jsi::Value(arg);
@@ -89,8 +90,7 @@ template <typename T>
 struct JSIConverter<T, std::enable_if_t<!std::is_same_v<T, uint64_t> && std::is_same_v<T, size_t>>> {
   static size_t fromJSI(jsi::Runtime& runtime, const jsi::Value& arg, bool outOfBound) {
       if (arg.isNumber()) {
-          double value = arg.asNumber();
-          return static_cast<size_t>(value);
+          return enforceRange<size_t>(arg.asNumber());
       } else {
           return arg.asBigInt(runtime).asInt64(runtime);
       }
@@ -103,9 +103,8 @@ struct JSIConverter<T, std::enable_if_t<!std::is_same_v<T, uint64_t> && std::is_
 
 // uint32_t <> double
 template <> struct JSIConverter<uint32_t> {
-  static double fromJSI(jsi::Runtime& runtime, const jsi::Value& arg, bool outOfBound) {
-      double value = arg.asNumber();
-      return static_cast<uint32_t>(value);
+  static uint32_t fromJSI(jsi::Runtime& runtime, const jsi::Value& arg, bool outOfBound) {
+      return enforceRange<uint32_t>(arg.asNumber());
   }
   static jsi::Value toJSI(jsi::Runtime& runtime, uint32_t arg) {
       return jsi::Value(static_cast<double>(arg));
@@ -116,11 +115,7 @@ template <> struct JSIConverter<uint32_t> {
 template <> struct JSIConverter<uint64_t> {
   static uint64_t fromJSI(jsi::Runtime& runtime, const jsi::Value& arg, bool outOfBound) {
     if (arg.isNumber()) {
-      double value = arg.asNumber();
-      if (value < 0 || value > MAX_SAFE_INTEGER) {
-        throw jsi::JSError(runtime, "Number out of range for uint64_t");
-      }
-      return static_cast<uint64_t>(value);
+      return enforceRange<uint64_t>(arg.asNumber());
     } else {
       return arg.asBigInt(runtime).getUint64(runtime);
     }

package/cpp/jsi/NativeObject.h

@@ -15,6 +15,7 @@
 #include <unordered_map>
 #include <utility>
 
+#include "EnforceRange.h"
 #include "JSICache.h"
 #include "WGPULogger.h"
 
@@ -33,6 +34,22 @@ namespace jsi = facebook::jsi;
 // Forward declaration
 template <typename Derived> class NativeObject;
 
+/**
+ * Non-template base of every NativeObject. It is what lets code that does not
+ * know the concrete class (the worklet serializer helper below) tell a WebGPU
+ * object from any other object carrying jsi::NativeState, and read its brand.
+ */
+class NativeObjectBase : public jsi::NativeState {
+public:
+  /** The class brand (Derived::CLASS_NAME), e.g. "GPUBuffer". */
+  const char *getClassName() const { return _name; }
+
+protected:
+  explicit NativeObjectBase(const char *name) : _name(name) {}
+
+  const char *_name;
+};
+
 /**
  * Registry mapping a NativeObject class brand (CLASS_NAME) to a reconstructor
  * that rebuilds a fully functional JS object (prototype + native state) on
@@ -92,8 +109,9 @@ private:
  * - The NativeState from the original object
  * - The brand name for prototype reconstruction
  *
- * Usage pattern with registerCustomSerializable:
- * - pack(): Call WebGPU.box(obj) to create a BoxedWebGPUObject (HostObject)
+ * Usage pattern with registerCustomSerializable (see
+ * src/external/reanimated/registerWebGPUForReanimated.ts):
+ * - pack(): WebGPUWorkletHelpers::box(obj) creates a BoxedWebGPUObject
  * - The HostObject is serialized by Worklets and transferred to UI runtime
  * - unpack(): Call boxed.unbox() to get the object's wrapper on that runtime
  *   (cached per runtime, see NativeObject::create), prototype included
@@ -149,6 +167,75 @@ private:
   std::string _brand;
 };
 
+/**
+ * The native half of the worklet serializer registered in
+ * src/external/reanimated/registerWebGPUForReanimated.ts:
+ *
+ * - isNativeObject(value): true only for objects whose NativeState is a
+ *   NativeObjectBase. Other native-state objects (Skia objects, worklets' own
+ *   serializable refs) and objects that merely inherit from a WebGPU prototype
+ *   (Object.create(device)) are rejected, and no JS property is ever read, so
+ *   getters and Proxy traps of unrelated objects never run.
+ * - box(value): wraps the object into a BoxedWebGPUObject, branded with its
+ *   class name, for unbox() on the target runtime.
+ *
+ * One instance is installed on the main runtime as
+ * globalThis.__webgpuWorkletHelpers and captured by the serializer's
+ * determine/pack worklets. Worklets hands a HostObject to every runtime by
+ * reference, so the helper is available wherever a WebGPU object gets captured
+ * (Reanimated UI runtime, createWorkletRuntime, Vision Camera frame
+ * processors) without installing anything on those runtimes.
+ */
+class WebGPUWorkletHelpers : public jsi::HostObject {
+public:
+  jsi::Value get(jsi::Runtime &runtime, const jsi::PropNameID &name) override {
+    auto propName = name.utf8(runtime);
+    if (propName == "isNativeObject") {
+      return jsi::Function::createFromHostFunction(
+          runtime, name, 1,
+          [](jsi::Runtime &rt, const jsi::Value & /*thisVal*/,
+             const jsi::Value *args, size_t count) -> jsi::Value {
+            return jsi::Value(
+                count > 0 && args[0].isObject() &&
+                args[0].getObject(rt).hasNativeState<NativeObjectBase>(rt));
+          });
+    }
+    if (propName == "box") {
+      return jsi::Function::createFromHostFunction(
+          runtime, name, 1,
+          [](jsi::Runtime &rt, const jsi::Value & /*thisVal*/,
+             const jsi::Value *args, size_t count) -> jsi::Value {
+            if (count < 1 || !args[0].isObject()) {
+              throw jsi::JSError(rt, "box() expects a WebGPU object");
+            }
+            auto obj = args[0].getObject(rt);
+            if (!obj.hasNativeState<NativeObjectBase>(rt)) {
+              throw jsi::JSError(rt, "box() expects a WebGPU object");
+            }
+            auto state = obj.getNativeState<NativeObjectBase>(rt);
+            return jsi::Object::createFromHostObject(
+                rt, std::make_shared<BoxedWebGPUObject>(state,
+                                                        state->getClassName()));
+          });
+    }
+    return jsi::Value::undefined();
+  }
+
+  void set(jsi::Runtime &runtime, const jsi::PropNameID & /*name*/,
+           const jsi::Value & /*value*/) override {
+    throw jsi::JSError(runtime, "__webgpuWorkletHelpers is read-only");
+  }
+
+  std::vector<jsi::PropNameID>
+  getPropertyNames(jsi::Runtime &runtime) override {
+    std::vector<jsi::PropNameID> names;
+    names.reserve(2);
+    names.push_back(jsi::PropNameID::forUtf8(runtime, "isNativeObject"));
+    names.push_back(jsi::PropNameID::forUtf8(runtime, "box"));
+    return names;
+  }
+};
+
 /**
  * Base class for native objects using the NativeState pattern.
  *
@@ -178,7 +265,7 @@ private:
  * ```
  */
 template <typename Derived>
-class NativeObject : public jsi::NativeState,
+class NativeObject : public NativeObjectBase,
                      public std::enable_shared_from_this<Derived> {
 public:
   // Marker type for SFINAE detection in JSIConverter
@@ -450,7 +537,7 @@ public:
   jsi::Runtime *getCreationRuntime() const { return _creationRuntime; }
 
 protected:
-  explicit NativeObject(const char *name) : _name(name) {
+  explicit NativeObject(const char *name) : NativeObjectBase(name) {
 #if DEBUG && RNF_ENABLE_LOGS
     Logger::logToConsole("NativeObject", "(MEMORY) Creating %s... ✅", _name);
 #endif
@@ -462,13 +549,30 @@ protected:
 #endif
   }
 
-  const char *_name;
   jsi::Runtime *_creationRuntime = nullptr;
 
   // ============================================================
   // Helper methods for definePrototype() implementations
   // ============================================================
 
+  /**
+   * Runs a host function body, turning a RangeTypeError (a JS number outside
+   * its WebIDL [EnforceRange] integer range, see EnforceRange.h) into a JS
+   * TypeError, as browsers throw for the same input. Everything else
+   * propagates unchanged.
+   */
+  template <typename Body>
+  static jsi::Value withWebIDLConversions(jsi::Runtime &runtime, Body &&body) {
+    try {
+      return body();
+    } catch (const RangeTypeError &error) {
+      auto typeError = runtime.global().getPropertyAsFunction(runtime, "TypeError");
+      throw jsi::JSError(runtime,
+                         typeError.callAsConstructor(
+                             runtime, jsi::String::createFromUtf8(runtime, error.what())));
+    }
+  }
+
   /**
    * Install a method on the prototype.
    */
@@ -481,8 +585,10 @@ protected:
         [method](jsi::Runtime &rt, const jsi::Value &thisVal,
                  const jsi::Value *args, size_t count) -> jsi::Value {
           auto native = Derived::fromValue(rt, thisVal);
-          return callMethod(native.get(), method, rt, args,
-                            std::index_sequence_for<Args...>{}, count);
+          return withWebIDLConversions(rt, [&] {
+            return callMethod(native.get(), method, rt, args,
+                              std::index_sequence_for<Args...>{}, count);
+          });
         });
     prototype.setProperty(runtime, name, func);
   }
@@ -503,9 +609,11 @@ protected:
         [method](jsi::Runtime &rt, const jsi::Value &thisVal,
                  const jsi::Value *args, size_t count) -> jsi::Value {
           auto native = Derived::fromValue(rt, thisVal);
-          return callMethodWithRuntime(native.get(), method, rt, args,
-                                       std::index_sequence_for<Args...>{},
-                                       count);
+          return withWebIDLConversions(rt, [&] {
+            return callMethodWithRuntime(native.get(), method, rt, args,
+                                         std::index_sequence_for<Args...>{},
+                                         count);
+          });
         });
     prototype.setProperty(runtime, name, func);
   }
@@ -563,10 +671,12 @@ protected:
             throw jsi::JSError(rt, "Setter requires a value argument");
           }
           auto native = Derived::fromValue(rt, thisVal);
-          auto value =
-              rnwgpu::JSIConverter<std::decay_t<ValueType>>::fromJSI(rt, args[0], false);
-          (native.get()->*setter)(std::move(value));
-          return jsi::Value::undefined();
+          return withWebIDLConversions(rt, [&] {
+            auto value =
+                rnwgpu::JSIConverter<std::decay_t<ValueType>>::fromJSI(rt, args[0], false);
+            (native.get()->*setter)(std::move(value));
+            return jsi::Value::undefined();
+          });
         });
 
     // Use Object.defineProperty to create a proper setter
@@ -624,10 +734,12 @@ protected:
             throw jsi::JSError(rt, "Setter requires a value argument");
           }
           auto native = Derived::fromValue(rt, thisVal);
-          auto value =
-              rnwgpu::JSIConverter<std::decay_t<ValueType>>::fromJSI(rt, args[0], false);
-          (native.get()->*setter)(std::move(value));
-          return jsi::Value::undefined();
+          return withWebIDLConversions(rt, [&] {
+            auto value =
+                rnwgpu::JSIConverter<std::decay_t<ValueType>>::fromJSI(rt, args[0], false);
+            (native.get()->*setter)(std::move(value));
+            return jsi::Value::undefined();
+          });
         });
 
     auto objectCtor = runtime.global().getPropertyAsObject(runtime, "Object");

package/cpp/rnwgpu/EnforceRange.h

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <limits>
+#include <stdexcept>
+#include <string>
+#include <type_traits>
+
+namespace rnwgpu {
+
+// Thrown when a JS number cannot be converted to a WebIDL [EnforceRange]
+// integer. The host function wrappers in NativeObject rethrow it as a JS
+// TypeError, which is what browsers throw for the same input.
+class RangeTypeError : public std::invalid_argument {
+public:
+  using std::invalid_argument::invalid_argument;
+};
+
+namespace detail {
+
+// The WebIDL name of the integer type, for the same message Chrome produces.
+template <typename T> constexpr const char *webIDLIntegerName() {
+  if constexpr (sizeof(T) == 1) {
+    return std::is_signed_v<T> ? "byte" : "octet";
+  } else if constexpr (sizeof(T) == 2) {
+    return std::is_signed_v<T> ? "short" : "unsigned short";
+  } else if constexpr (sizeof(T) == 4) {
+    return std::is_signed_v<T> ? "long" : "unsigned long";
+  } else {
+    return std::is_signed_v<T> ? "long long" : "unsigned long long";
+  }
+}
+
+} // namespace detail
+
+// WebIDL [EnforceRange] conversion of a JS number to an integer
+// (https://webidl.spec.whatwg.org/#abstract-opdef-converttoint): non-finite
+// values and values outside the type's range are rejected, fractions are
+// truncated toward zero. 64-bit types are limited to the integers a double
+// holds exactly, [-(2^53 - 1), 2^53 - 1], as the spec requires.
+//
+// WebGPU marks nearly every integer it takes [EnforceRange] (GPUSize32,
+// GPUIndex32, GPUSize64, GPUIntegerCoordinate, GPUSignedOffset32,
+// GPUStencilValue, GPUSampleMask, GPUDepthBias). The flag constants
+// (GPUBufferUsageFlags and friends) are plain `unsigned long` and are not
+// converted here.
+template <typename T> T enforceRange(double value) {
+  static_assert(std::is_integral_v<T> && !std::is_same_v<T, bool>,
+                "enforceRange converts to integer types only");
+  constexpr double kMaxSafeInteger = 9007199254740991.0;
+  constexpr double kLower = std::max(
+      static_cast<double>(std::numeric_limits<T>::min()), -kMaxSafeInteger);
+  constexpr double kUpper = std::min(
+      static_cast<double>(std::numeric_limits<T>::max()), kMaxSafeInteger);
+  if (!std::isfinite(value)) {
+    throw RangeTypeError("The provided double value is non-finite.");
+  }
+  const double integer = std::trunc(value);
+  if (integer < kLower || integer > kUpper) {
+    throw RangeTypeError(std::string("Value is outside the '") +
+                         detail::webIDLIntegerName<T>() + "' value range.");
+  }
+  return static_cast<T>(integer);
+}
+
+} // namespace rnwgpu

package/cpp/rnwgpu/PlatformContext.h

@@ -142,8 +142,6 @@ public:
                             std::function<void(ImageData)> onSuccess,
                             std::function<void(std::string)> onError) = 0;
 
-  virtual wgpu::Surface makeSurface(wgpu::Instance instance, void *surface,
-                                    int width, int height) = 0;
   virtual ImageData createImageBitmap(std::string blobId, double offset,
                                       double size) = 0;
 

package/cpp/rnwgpu/RNWebGPUManager.cpp

@@ -141,101 +141,13 @@ RNWebGPUManager::RNWebGPUManager(
 }
 
 void RNWebGPUManager::installWebGPUWorkletHelpers(jsi::Runtime &runtime) {
-  // __webgpuIsWebGPUObject - checks if a value is a WebGPU NativeObject
-  auto isWebGPUObjectFunc = jsi::Function::createFromHostFunction(
-      runtime, jsi::PropNameID::forUtf8(runtime, "__webgpuIsWebGPUObject"), 1,
-      [](jsi::Runtime &rt, const jsi::Value & /*thisVal*/,
-         const jsi::Value *args, size_t count) -> jsi::Value {
-        if (count < 1 || !args[0].isObject()) {
-          return jsi::Value(false);
-        }
-        auto obj = args[0].getObject(rt);
-
-        // Check if it has native state
-        if (!obj.hasNativeState(rt)) {
-          return jsi::Value(false);
-        }
-
-        // Check if it has Symbol.toStringTag on its prototype (WebGPU objects
-        // do)
-        auto objectCtor = rt.global().getPropertyAsObject(rt, "Object");
-        auto getPrototypeOf =
-            objectCtor.getPropertyAsFunction(rt, "getPrototypeOf");
-        auto proto = getPrototypeOf.call(rt, obj);
-
-        if (!proto.isObject()) {
-          return jsi::Value(false);
-        }
-
-        auto protoObj = proto.getObject(rt);
-        auto symbolCtor = rt.global().getPropertyAsObject(rt, "Symbol");
-        auto toStringTag = symbolCtor.getProperty(rt, "toStringTag");
-        if (toStringTag.isUndefined()) {
-          return jsi::Value(false);
-        }
-
-        auto getOwnPropertyDescriptor =
-            objectCtor.getPropertyAsFunction(rt, "getOwnPropertyDescriptor");
-        auto desc = getOwnPropertyDescriptor.call(rt, protoObj, toStringTag);
-        return jsi::Value(desc.isObject());
-      });
-  runtime.global().setProperty(runtime, "__webgpuIsWebGPUObject",
-                               std::move(isWebGPUObjectFunc));
-
-  // __webgpuBox - boxes a WebGPU object for Worklets serialization
-  auto boxFunc = jsi::Function::createFromHostFunction(
-      runtime, jsi::PropNameID::forUtf8(runtime, "__webgpuBox"), 1,
-      [](jsi::Runtime &rt, const jsi::Value & /*thisVal*/,
-         const jsi::Value *args, size_t count) -> jsi::Value {
-        if (count < 1 || !args[0].isObject()) {
-          throw jsi::JSError(rt,
-                             "__webgpuBox() requires a WebGPU object argument");
-        }
-
-        auto obj = args[0].getObject(rt);
-
-        // Check if it has native state
-        if (!obj.hasNativeState(rt)) {
-          throw jsi::JSError(
-              rt, "Object has no native state - not a WebGPU object");
-        }
-
-        // Get the brand name from Symbol.toStringTag on the prototype
-        auto objectCtor = rt.global().getPropertyAsObject(rt, "Object");
-        auto getPrototypeOf =
-            objectCtor.getPropertyAsFunction(rt, "getPrototypeOf");
-        auto proto = getPrototypeOf.call(rt, obj);
-
-        std::string brand;
-        if (proto.isObject()) {
-          auto protoObj = proto.getObject(rt);
-          auto symbolCtor = rt.global().getPropertyAsObject(rt, "Symbol");
-          auto toStringTag = symbolCtor.getProperty(rt, "toStringTag");
-          if (!toStringTag.isUndefined()) {
-            auto getOwnPropertyDescriptor = objectCtor.getPropertyAsFunction(
-                rt, "getOwnPropertyDescriptor");
-            auto desc =
-                getOwnPropertyDescriptor.call(rt, protoObj, toStringTag);
-            if (desc.isObject()) {
-              auto descObj = desc.getObject(rt);
-              auto value = descObj.getProperty(rt, "value");
-              if (value.isString()) {
-                brand = value.getString(rt).utf8(rt);
-              }
-            }
-          }
-        }
-
-        if (brand.empty()) {
-          throw jsi::JSError(rt, "Cannot determine WebGPU object type - no "
-                                 "Symbol.toStringTag found");
-        }
-
-        auto nativeState = obj.getNativeState(rt);
-        auto boxed = std::make_shared<BoxedWebGPUObject>(nativeState, brand);
-        return jsi::Object::createFromHostObject(rt, boxed);
-      });
-  runtime.global().setProperty(runtime, "__webgpuBox", std::move(boxFunc));
+  // The serializer worklets capture this object by closure; worklets passes a
+  // HostObject to every runtime by reference, so installing it here, on the
+  // main runtime, is enough (see WebGPUWorkletHelpers).
+  runtime.global().setProperty(
+      runtime, "__webgpuWorkletHelpers",
+      jsi::Object::createFromHostObject(
+          runtime, std::make_shared<WebGPUWorkletHelpers>()));
 }
 
 void RNWebGPUManager::flushPendingSurfaceTransition(

package/cpp/rnwgpu/RNWebGPUManager.h

@@ -28,9 +28,10 @@ public:
   ~RNWebGPUManager();
 
   /**
-   * Install global helper functions for Worklets serialization.
-   * This installs __webgpuIsWebGPUObject and __webgpuBox on the global object.
-   * Can be called on any runtime (main JS, UI, or custom worklet runtimes).
+   * Installs globalThis.__webgpuWorkletHelpers, the HostObject the worklet
+   * serializer (registerWebGPUForReanimated) captures to detect and box
+   * WebGPU objects. Only needed on the main runtime: the serializer worklets
+   * carry it to every other runtime by reference. See WebGPUWorkletHelpers.
    */
   static void installWebGPUWorkletHelpers(jsi::Runtime &runtime);