@shopify/react-native-skia 2.6.6 → 2.6.8

package/cpp/rnwgpu/api/GPUQueue.h

@@ -8,8 +8,8 @@
 
 #include "jsi2/NativeObject.h"
 
-#include "rnwgpu/async/AsyncRunner.h"
 #include "rnwgpu/async/AsyncTaskHandle.h"
+#include "rnwgpu/async/RuntimeContext.h"
 
 #include "webgpu/webgpu_cpp.h"
 
@@ -31,7 +31,7 @@ public:
   static constexpr const char *CLASS_NAME = "GPUQueue";
 
   explicit GPUQueue(wgpu::Queue instance,
-                    std::shared_ptr<async::AsyncRunner> async,
+                    std::shared_ptr<async::RuntimeContext> async,
                     std::string label)
       : NativeObject(CLASS_NAME), _instance(instance), _async(async),
         _label(label) {}
@@ -77,7 +77,7 @@ public:
 
 private:
   wgpu::Queue _instance;
-  std::shared_ptr<async::AsyncRunner> _async;
+  std::shared_ptr<async::RuntimeContext> _async;
   std::string _label;
 };
 

package/cpp/rnwgpu/api/GPUShaderModule.h

@@ -7,8 +7,8 @@
 
 #include "jsi2/NativeObject.h"
 
-#include "rnwgpu/async/AsyncRunner.h"
 #include "rnwgpu/async/AsyncTaskHandle.h"
+#include "rnwgpu/async/RuntimeContext.h"
 
 #include "webgpu/webgpu_cpp.h"
 
@@ -23,7 +23,7 @@ public:
   static constexpr const char *CLASS_NAME = "GPUShaderModule";
 
   explicit GPUShaderModule(wgpu::ShaderModule instance,
-                           std::shared_ptr<async::AsyncRunner> async,
+                           std::shared_ptr<async::RuntimeContext> async,
                            std::string label)
       : NativeObject(CLASS_NAME), _instance(instance), _async(async),
         _label(label) {}
@@ -59,7 +59,7 @@ public:
 
 private:
   wgpu::ShaderModule _instance;
-  std::shared_ptr<async::AsyncRunner> _async;
+  std::shared_ptr<async::RuntimeContext> _async;
   std::string _label;
 };
 

package/cpp/rnwgpu/api/WebGPUConstants.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include "descriptors/GPUBufferUsage.h"
+#include "descriptors/GPUColorWrite.h"
+#include "descriptors/GPUMapMode.h"
+#include "descriptors/GPUShaderStage.h"
+#include "descriptors/GPUTextureUsage.h"
+
+namespace rnwgpu {
+
+namespace jsi = facebook::jsi;
+
+// Installs the WebGPU flag constants (GPUBufferUsage, GPUColorWrite, GPUMapMode,
+// GPUShaderStage, GPUTextureUsage) as plain JS objects on `runtime`'s global.
+//
+// The numeric values are derived from the Dawn wgpu::*Usage enums (single source
+// of truth in C++), so this is safe to call on ANY runtime: the main JS runtime
+// at install time, and any worklet runtime (Reanimated UI, dedicated worklet
+// runtimes, Vision Camera frame processors) via the global `installWebGPU()`
+// host function. It is idempotent: re-installing overwrites the globals with
+// equal values.
+inline void installWebGPUConstants(jsi::Runtime &runtime) {
+  auto global = runtime.global();
+  global.setProperty(runtime, "GPUBufferUsage",
+                     GPUBufferUsage::create(runtime));
+  global.setProperty(runtime, "GPUColorWrite", GPUColorWrite::create(runtime));
+  global.setProperty(runtime, "GPUMapMode", GPUMapMode::create(runtime));
+  global.setProperty(runtime, "GPUShaderStage",
+                     GPUShaderStage::create(runtime));
+  global.setProperty(runtime, "GPUTextureUsage",
+                     GPUTextureUsage::create(runtime));
+}
+
+} // namespace rnwgpu

package/cpp/rnwgpu/async/AsyncTaskHandle.cpp

@@ -1,11 +1,14 @@
 #include "AsyncTaskHandle.h"
 
+#include <memory>
 #include <string>
 #include <utility>
 
+#include <ReactCommon/CallInvoker.h>
+
 #include "jsi2/Promise.h"
 
-#include "AsyncRunner.h"
+#include "RuntimeContext.h"
 
 namespace rnwgpu::async {
 
@@ -13,8 +16,8 @@ using Action = std::function<void(jsi::Runtime &, rnwgpu::Promise &)>;
 
 struct AsyncTaskHandle::State
     : public std::enable_shared_from_this<AsyncTaskHandle::State> {
-  State(std::shared_ptr<AsyncRunner> runner, bool keepPumping)
-      : runner(std::move(runner)), keepPumping(keepPumping) {}
+  State(std::shared_ptr<RuntimeContext> context, bool keepPumping)
+      : context(std::move(context)), keepPumping(keepPumping) {}
 
   void settle(Action action);
   void attachPromise(const std::shared_ptr<rnwgpu::Promise> &promise);
@@ -26,12 +29,12 @@ struct AsyncTaskHandle::State
   std::shared_ptr<rnwgpu::Promise> currentPromise();
 
   std::mutex mutex;
-  std::weak_ptr<AsyncRunner> runner;
+  std::shared_ptr<RuntimeContext> context;
+  bool keepPumping;
   std::shared_ptr<rnwgpu::Promise> promise;
   std::optional<Action> pendingAction;
   bool settled = false;
   std::shared_ptr<State> keepAlive;
-  bool keepPumping;
 };
 
 // MARK: - State helpers
@@ -77,30 +80,60 @@ void AsyncTaskHandle::State::attachPromise(
 }
 
 void AsyncTaskHandle::State::schedule(Action action) {
-  auto runnerRef = runner.lock();
-  if (!runnerRef) {
+  auto promiseRef = currentPromise();
+  if (!promiseRef) {
     return;
   }
 
-  auto promiseRef = currentPromise();
-  if (!promiseRef) {
-    runnerRef->onTaskSettled(keepPumping);
+  if (!context) {
+    // No context (shouldn't happen): best-effort inline settle.
+    action(promiseRef->runtime, *promiseRef);
+    std::lock_guard<std::mutex> lock(mutex);
+    keepAlive.reset();
     return;
   }
 
-  auto dispatcherRef = runnerRef->dispatcher();
-  if (!dispatcherRef) {
-    runnerRef->onTaskSettled(keepPumping);
+  auto self = shared_from_this();
+
+  if (!keepPumping) {
+    // Spontaneous task (e.g. device.lost): not driven by the ProcessEvents pump.
+    // Settle on the owning runtime's JS thread via its CallInvoker, which is
+    // wired only for the main JS runtime. A device created on a worklet runtime
+    // has no invoker, so its device.lost is dropped (best-effort; see the
+    // Threading model). invokeAsync runs the closure on the main JS thread,
+    // where promiseRef->runtime lives for a main-runtime device.
+    auto invoker = context->callInvoker();
+    if (invoker) {
+      invoker->invokeAsync(
+          [self, action = std::move(action), promiseRef]() mutable {
+            action(promiseRef->runtime, *promiseRef);
+            std::lock_guard<std::mutex> lock(self->mutex);
+            self->keepAlive.reset();
+          });
+    } else {
+      std::lock_guard<std::mutex> lock(mutex);
+      keepAlive.reset();
+    }
     return;
   }
 
-  dispatcherRef->post([self = shared_from_this(), action = std::move(action),
-                       runnerRef, promiseRef](jsi::Runtime &runtime) mutable {
-    runnerRef->onTaskSettled(self->keepPumping);
-    action(runtime, *promiseRef);
-    std::lock_guard<std::mutex> lock(self->mutex);
-    self->keepAlive.reset();
-  });
+  // Pumping task (request/response op). The resolve/reject callback may fire on
+  // a thread that is NOT the owning runtime's thread: with a shared
+  // wgpu::Instance, another runtime's ProcessEvents() pump can consume this Dawn
+  // event. Touching the Promise's runtime off-thread would corrupt Hermes. So we
+  // deposit the actual settle (the only JSI-touching work) into the owning
+  // context's mailbox; the context drains it on its own thread during its next
+  // tick. The deposited closure captures only C++ state and runs no JSI until
+  // drained, so depositing from any thread is safe.
+  context->postSettle(
+      [self, action = std::move(action), promiseRef]() mutable {
+        action(promiseRef->runtime, *promiseRef);
+        if (self->context) {
+          self->context->onTaskSettled(/*keepPumping=*/true);
+        }
+        std::lock_guard<std::mutex> lock(self->mutex);
+        self->keepAlive.reset();
+      });
 }
 
 AsyncTaskHandle::ResolveFunction
@@ -149,9 +182,9 @@ AsyncTaskHandle::AsyncTaskHandle(std::shared_ptr<State> state)
 bool AsyncTaskHandle::valid() const { return _state != nullptr; }
 
 AsyncTaskHandle
-AsyncTaskHandle::create(const std::shared_ptr<AsyncRunner> &runner,
+AsyncTaskHandle::create(const std::shared_ptr<RuntimeContext> &context,
                         bool keepPumping) {
-  auto state = std::make_shared<State>(runner, keepPumping);
+  auto state = std::make_shared<State>(context, keepPumping);
   state->keepAlive = state;
   return AsyncTaskHandle(std::move(state));
 }

package/cpp/rnwgpu/async/AsyncTaskHandle.h

@@ -8,19 +8,22 @@
 
 #include <jsi/jsi.h>
 
-#include "AsyncDispatcher.h"
-
 namespace rnwgpu {
 class Promise;
 }
 
 namespace rnwgpu::async {
 
-class AsyncRunner;
+class RuntimeContext;
 
 /**
  * Represents a pending asynchronous WebGPU operation that can be converted into
  * a JavaScript Promise.
+ *
+ * In the ProcessEvents model the resolve/reject callbacks are invoked on the
+ * owning runtime's own thread (synchronously from instance.ProcessEvents()
+ * during the RuntimeContext tick, or synchronously from postTask), so the
+ * Promise is settled directly without any thread marshalling.
  */
 class AsyncTaskHandle {
 public:
@@ -34,7 +37,7 @@ public:
   AsyncTaskHandle();
 
   /**
-   * Internal constructor used by AsyncRunner.
+   * Internal constructor used by RuntimeContext.
    */
   explicit AsyncTaskHandle(std::shared_ptr<State> state);
 
@@ -45,7 +48,7 @@ public:
 
   void attachPromise(const std::shared_ptr<rnwgpu::Promise> &promise) const;
 
-  static AsyncTaskHandle create(const std::shared_ptr<AsyncRunner> &runner,
+  static AsyncTaskHandle create(const std::shared_ptr<RuntimeContext> &context,
                                 bool keepPumping);
 
 private:

package/cpp/rnwgpu/async/RuntimeContext.cpp

@@ -0,0 +1,194 @@
+#include "RuntimeContext.h"
+
+#include <memory>
+#include <stdexcept>
+#include <utility>
+
+#include <ReactCommon/CallInvoker.h>
+
+#include "AsyncTaskHandle.h"
+
+namespace rnwgpu::async {
+
+namespace {
+struct RuntimeData {
+  std::shared_ptr<RuntimeContext> context;
+};
+
+// The main JS runtime and its CallInvoker, registered once on install. The
+// context created for sMainRuntime gets sMainInvoker; spontaneous events
+// (device.lost) on a main-runtime device are delivered through it without the
+// pump. Worklet runtimes have no invoker (best-effort, see the header doc).
+jsi::Runtime *sMainRuntime = nullptr;
+std::shared_ptr<facebook::react::CallInvoker> sMainInvoker;
+
+// Serializes ProcessEvents() across all runtimes that share a wgpu::Instance.
+// Held only across the ProcessEvents call itself, never while running JS /
+// mailbox settle-actions, so it cannot deadlock against the per-context mailbox
+// mutex.
+std::mutex &processEventsMutex() {
+  static std::mutex mutex;
+  return mutex;
+}
+} // namespace
+
+void RuntimeContext::registerMainRuntime(
+    jsi::Runtime *runtime,
+    std::shared_ptr<facebook::react::CallInvoker> invoker) {
+  sMainRuntime = runtime;
+  sMainInvoker = std::move(invoker);
+}
+
+RuntimeContext::RuntimeContext(jsi::Runtime &runtime, wgpu::Instance instance)
+    : _runtime(runtime), _instance(std::move(instance)) {}
+
+std::shared_ptr<RuntimeContext> RuntimeContext::get(jsi::Runtime &runtime) {
+  auto data = runtime.getRuntimeData(runtimeDataUUID());
+  if (!data) {
+    return nullptr;
+  }
+  return std::static_pointer_cast<RuntimeData>(data)->context;
+}
+
+std::shared_ptr<RuntimeContext>
+RuntimeContext::getOrCreate(jsi::Runtime &runtime, wgpu::Instance instance) {
+  if (auto existing = get(runtime)) {
+    return existing;
+  }
+  auto context = std::make_shared<RuntimeContext>(runtime, std::move(instance));
+  // Only the main JS runtime's context carries the CallInvoker; it is used to
+  // deliver spontaneous events (device.lost) without the pump.
+  if (&runtime == sMainRuntime) {
+    context->_callInvoker = sMainInvoker;
+  }
+  auto data = std::make_shared<RuntimeData>();
+  data->context = context;
+  runtime.setRuntimeData(runtimeDataUUID(), data);
+  return context;
+}
+
+AsyncTaskHandle RuntimeContext::postTask(const TaskCallback &callback,
+                                         bool keepPumping) {
+  auto handle = AsyncTaskHandle::create(shared_from_this(), keepPumping);
+  if (!handle.valid()) {
+    throw std::runtime_error("Failed to create AsyncTaskHandle.");
+  }
+
+  // Only pumping tasks (request/response ops) drive the ProcessEvents pump.
+  // Spontaneous tasks (keepPumping == false, e.g. device.lost) never touch the
+  // pump: they settle via the CallInvoker (see AsyncTaskHandle::State::schedule).
+  if (keepPumping) {
+    _pumpTasks.fetch_add(1, std::memory_order_acq_rel);
+    requestTick();
+  }
+
+  auto resolve = handle.createResolveFunction();
+  auto reject = handle.createRejectFunction();
+  try {
+    callback(resolve, reject);
+  } catch (const std::exception &exception) {
+    reject(exception.what());
+  } catch (...) {
+    reject("Unknown native error in RuntimeContext::postTask.");
+  }
+  return handle;
+}
+
+void RuntimeContext::onTaskSettled(bool keepPumping) {
+  if (keepPumping) {
+    _pumpTasks.fetch_sub(1, std::memory_order_acq_rel);
+  }
+}
+
+void RuntimeContext::postSettle(std::function<void()> job) {
+  if (!job) {
+    return;
+  }
+  std::lock_guard<std::mutex> lock(_mailboxMutex);
+  _mailbox.push_back(std::move(job));
+}
+
+void RuntimeContext::drainMailbox() {
+  std::vector<std::function<void()>> jobs;
+  {
+    std::lock_guard<std::mutex> lock(_mailboxMutex);
+    jobs.swap(_mailbox);
+  }
+  // Run settle-actions on this (the owning) thread, NOT under the ProcessEvents
+  // mutex, so JS continuations never execute while the pump lock is held.
+  for (auto &job : jobs) {
+    job();
+  }
+}
+
+void RuntimeContext::requestTick() {
+  bool expected = false;
+  if (!_tickScheduled.compare_exchange_strong(expected, true,
+                                              std::memory_order_acq_rel)) {
+    return;
+  }
+
+  // The pump only ever runs while a request/response op is outstanding, so it
+  // always schedules as soon as possible (delay 0). postTask and tick both run
+  // on the owning runtime's thread, so we schedule the next tick directly via
+  // that runtime's own timer. setTimeout is available on the main RN runtime and
+  // on worklet runtimes (backed by the worklets EventLoop); setImmediate /
+  // queueMicrotask are fallbacks. We do NOT use queueMicrotask as the primary
+  // mechanism: a self-rescheduling microtask never yields the microtask
+  // checkpoint, starving the runtime's task loop.
+  auto self = shared_from_this();
+  jsi::Runtime &rt = _runtime;
+  auto tickCallback = jsi::Function::createFromHostFunction(
+      rt, jsi::PropNameID::forAscii(rt, "RNWGPUAsyncTick"), 0,
+      [self](jsi::Runtime & /*runtime*/, const jsi::Value & /*thisVal*/,
+             const jsi::Value * /*args*/, size_t /*count*/) -> jsi::Value {
+        self->tick();
+        return jsi::Value::undefined();
+      });
+
+  auto global = rt.global();
+  auto setTimeoutValue = global.getProperty(rt, "setTimeout");
+  if (setTimeoutValue.isObject() &&
+      setTimeoutValue.asObject(rt).isFunction(rt)) {
+    setTimeoutValue.asObject(rt).asFunction(rt).call(
+        rt, jsi::Value(rt, tickCallback), jsi::Value(0.0));
+    return;
+  }
+  auto setImmediateValue = global.getProperty(rt, "setImmediate");
+  if (setImmediateValue.isObject() &&
+      setImmediateValue.asObject(rt).isFunction(rt)) {
+    setImmediateValue.asObject(rt).asFunction(rt).call(
+        rt, jsi::Value(rt, tickCallback));
+    return;
+  }
+  rt.queueMicrotask(std::move(tickCallback));
+}
+
+void RuntimeContext::tick() {
+  _tickScheduled.store(false, std::memory_order_release);
+  {
+    // Serialize ProcessEvents across runtimes sharing this instance. Callbacks
+    // fired here only deposit into mailboxes (postSettle), they do not run JS.
+    std::lock_guard<std::mutex> lock(processEventsMutex());
+    _instance.ProcessEvents();
+  }
+  // Settle this runtime's ready promises on this thread, outside the pump lock.
+  drainMailbox();
+  // Keep pumping only while a "pumping" task (active async work) is outstanding.
+  // Non-pumping tasks (e.g. device.lost) intentionally do NOT keep the pump
+  // alive: we prioritise battery over catching a device.lost fired while idle.
+  if (_pumpTasks.load(std::memory_order_acquire) > 0) {
+    requestTick();
+  }
+}
+
+jsi::UUID RuntimeContext::runtimeDataUUID() {
+  // Fixed, unique key for storing the RuntimeContext in the runtime's
+  // runtimeData. Must not collide with other runtimeData consumers (e.g.
+  // react-native-worklets' weakRuntimeUUID).
+  static const jsi::UUID uuid{0x7b9a3c10, 0x4d2e, 0x4f8a, 0x9c3d,
+                              0x1f6e5a2b8c40};
+  return uuid;
+}
+
+} // namespace rnwgpu::async

package/cpp/rnwgpu/async/RuntimeContext.h

@@ -0,0 +1,121 @@
+#pragma once
+
+#include <atomic>
+#include <cstddef>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <vector>
+
+#include <jsi/jsi.h>
+
+#include "AsyncTaskHandle.h"
+
+#include "webgpu/webgpu_cpp.h"
+
+namespace jsi = facebook::jsi;
+
+namespace facebook::react {
+class CallInvoker;
+} // namespace facebook::react
+
+namespace rnwgpu::async {
+
+/**
+ * Per-runtime coordinator for asynchronous WebGPU operations.
+ *
+ * Each JS runtime that uses WebGPU gets its own RuntimeContext, stored in the
+ * runtime's runtimeData. Async Dawn operations are registered with
+ * CallbackMode::AllowProcessEvents and driven to completion by pumping
+ * `instance.ProcessEvents()` on the runtime's OWN thread via a self-
+ * rescheduling tick (scheduled through that runtime's setTimeout). Because
+ * ProcessEvents invokes the Dawn callbacks synchronously on the pumping thread,
+ * the JS Promise is settled directly on the owning runtime, with no background
+ * thread and no cross-thread hop.
+ *
+ * The pump only runs while at least one "pumping" task is outstanding, so it
+ * costs nothing when idle and stops cleanly.
+ *
+ * Spontaneous events (keepPumping = false): events that may fire at any time,
+ * independent of any request/response op (today only GPUDevice::getLost, whose
+ * Dawn callback is registered AllowSpontaneous). These are NOT driven by the
+ * pump. Instead their settle is marshalled onto the owning runtime's JS thread
+ * via that runtime's CallInvoker, which is wired only for the MAIN JS runtime
+ * (callInvoker()). A device created on a worklet runtime has no invoker, so its
+ * device.lost is best-effort and may never fire.
+ *
+ * Shared-instance safety (mailbox): multiple runtimes may share one
+ * wgpu::Instance. ProcessEvents() drains the whole instance queue and fires
+ * callbacks on the calling thread, which may NOT be the owning runtime's thread
+ * for a given promise. So a settled callback never touches JSI inline; it
+ * deposits a settle-action (a plain C++ closure, no JSI) into the OWNING
+ * context's thread-safe mailbox via postSettle(), and each context drains its
+ * own mailbox on its own thread during tick(). ProcessEvents() itself is
+ * serialized across runtimes by a process-wide mutex, since concurrent
+ * ProcessEvents on one instance is not guaranteed reentrant.
+ *
+ * Threading contract: a RuntimeContext must only be pumped from the runtime it
+ * was created for. Create and use a GPUDevice (and the buffers/queues derived
+ * from it) on the same runtime that requested the adapter.
+ */
+class RuntimeContext : public std::enable_shared_from_this<RuntimeContext> {
+public:
+  using TaskCallback =
+      std::function<void(const AsyncTaskHandle::ResolveFunction &,
+                         const AsyncTaskHandle::RejectFunction &)>;
+
+  RuntimeContext(jsi::Runtime &runtime, wgpu::Instance instance);
+
+  static std::shared_ptr<RuntimeContext> get(jsi::Runtime &runtime);
+  static std::shared_ptr<RuntimeContext> getOrCreate(jsi::Runtime &runtime,
+                                                     wgpu::Instance instance);
+
+  // Register the main JS runtime and its CallInvoker. The RuntimeContext created
+  // for this runtime gets the invoker (callInvoker() returns it); every other
+  // runtime's context returns null. Called once from RNSkManager on install.
+  static void
+  registerMainRuntime(jsi::Runtime *runtime,
+                      std::shared_ptr<facebook::react::CallInvoker> invoker);
+
+  // CallInvoker for this runtime's JS thread, or null. Non-null only for the
+  // main JS runtime; used to deliver spontaneous events (device.lost) without
+  // the pump. See the class doc.
+  const std::shared_ptr<facebook::react::CallInvoker> &callInvoker() const {
+    return _callInvoker;
+  }
+
+  // The wgpu::Instance bound to this runtime.
+  wgpu::Instance instance() const { return _instance; }
+
+  AsyncTaskHandle postTask(const TaskCallback &callback,
+                           bool keepPumping = true);
+
+  // Deposit a settle-action to run on THIS context's runtime thread. Thread-safe
+  // (callable from any thread, e.g. another runtime that pumped ProcessEvents).
+  // The job must not touch JSI until it runs (it runs during drainMailbox on the
+  // owning thread).
+  void postSettle(std::function<void()> job);
+
+  // Invoked by a drained settle-action when its task settles. Runs on the owning
+  // runtime's thread.
+  void onTaskSettled(bool keepPumping);
+
+private:
+  static jsi::UUID runtimeDataUUID();
+
+  void requestTick();
+  void tick();
+  void drainMailbox();
+
+  jsi::Runtime &_runtime;
+  wgpu::Instance _instance;
+  // Non-null only for the main JS runtime's context (see registerMainRuntime).
+  std::shared_ptr<facebook::react::CallInvoker> _callInvoker;
+  std::atomic<std::size_t> _pumpTasks{0};
+  std::atomic<bool> _tickScheduled{false};
+
+  std::mutex _mailboxMutex;
+  std::vector<std::function<void()>> _mailbox;
+};
+
+} // namespace rnwgpu::async

package/lib/commonjs/skia/types/WebGPU.d.ts

@@ -1,4 +1,35 @@
 import type { NativeBuffer } from "./NativeBuffer";
+/**
+ * Make the WebGPU flag constants (`GPUBufferUsage`, `GPUColorWrite`,
+ * `GPUMapMode`, `GPUShaderStage`, `GPUTextureUsage`) available on the runtime
+ * that calls this.
+ *
+ * The native module installs these globals on the main JS runtime, but worklet
+ * runtimes (Reanimated UI, dedicated worklet runtimes, Vision Camera frame
+ * processors) start without them, so referencing the bare global inside a
+ * worklet yields `undefined`. Call `installWebGPU()` once at the top of a
+ * worklet to install them there:
+ *
+ * ```tsx
+ * import { installWebGPU } from "@shopify/react-native-skia";
+ *
+ * const work = (device: GPUDevice) => {
+ *   "worklet";
+ *   installWebGPU();
+ *   device.createBuffer({
+ *     usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+ *   });
+ * };
+ * ```
+ *
+ * `installWebGPU` is a native host function. When captured into a worklet, the
+ * Worklets serializer re-creates it on the worklet runtime, so calling it there
+ * installs the constants on that runtime. The values come from the native
+ * `wgpu::*Usage` enums, so they stay a single source of truth across runtimes.
+ * Calling it on a runtime that already has the constants is a safe no-op, and on
+ * web (where the constants are always global) it is a no-op too.
+ */
+export declare const installWebGPU: () => void;
 /**
  * Descriptor for {@link GPUDevice.importExternalTexture} when the source is a
  * Skia NativeBuffer (Skia has no WebCodecs `VideoFrame`).