Refactor WebGPU surface lifecycle to support latched attach (#426)

The SurfaceRegistry kept the sync getContext("webgpu") contract by falling
back to an offscreen texture when the native surface is not available yet,
but the reconciliation points were racy and crash-prone. This reworks the
lifecycle around explicit invariants:

- Registry entries now live exactly as long as their JS Canvas (contextIds
  are never reused). Native view teardown (MetalView dealloc /
  onDropViewInstance) retires the entry when a surface is attached;
  RNWebGPU.destroyContext (Canvas unmount cleanup) covers entries that never
  had one, which keeps StrictMode's simulated unmount from orphaning a live
  surface. Surface destruction alone (backgrounding, TextureView teardown)
  only detaches — fixing the orphaned-context black screen on the
  transparent/TextureView path and the SurfaceView/TextureView asymmetry.
- Surface attaches are latched by the UI thread and adopted at frame
  boundaries on the rendering thread (start of getCurrentTexture / end of
  present), so a surface is never swapped mid-frame and Dawn surface
  thread-affinity is preserved. A CallInvoker flush covers contexts that are
  not actively rendering. Detaches stay immediate (the platform is
  destroying the surface) and drop the in-flight frame at present().
- present() only presents frames whose texture was actually acquired from
  the attached surface, eliminating present-without-acquire validation
  errors around transitions.
- The offscreen->onscreen blit now checks SurfaceTexture.status, clamps the
  copy extent to the shared region, presents from the rendering thread, and
  no longer permanently widens the configured usage with CopyDst.
- getCurrentTexture checks SurfaceTexture.status (reconfigure + retry once,
  then offscreen fallback), throws a catchable JS error when called before
  configure() instead of dereferencing a null device, and clamps zero-sized
  canvases to 1x1. unconfigure() is now implemented.
- viewFormats are deep-copied into SurfaceInfo; the stored configuration
  previously kept a pointer into Convertor-owned memory that died with the
  configure() call.
- ANativeWindow references are now released (acquire in onSurfaceCreate was
  never paired), the registry is cleared on RNWebGPUManager teardown so dev
  reloads cannot alias new canvases onto stale entries, and every registry
  lookup on the native side is null-checked. Removes the unused
  WebGPUBaseView (its JNI bindings never existed) and the dead
  onSurfaceDestroy path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XLLf4VPzGb642Zp8EyNgpr

* fix(surface): close the races found by adversarial review of the attach model

Three defects confirmed by review of the latched-attach rework:

- Double-present race: between applyPendingAttach's blit submit and its
  deferred Present(), a frame could start and complete on another runtime;
  the !_frameInFlight guard missed frames that finished inside the gap and
  Present() fired with no acquired texture. A _frameEpoch counter (bumped on
  every acquire, present, configure/reconfigure/unconfigure, adoption, and
  detach) is now revalidated before the deferred present.

- destroyContext TOCTOU: hasNativeSurface() (SurfaceInfo mutex) followed by
  removeSurfaceInfo (registry mutex) was not atomic against the UI thread's
  find-or-create + attach, so a StrictMode cleanup racing a native mount
  could orphan a just-attached surface. SurfaceRegistry now provides
  attachSurface (find-or-create + attach) and removeSurfaceInfoIfDetached
  (lookup + check + erase), both atomic under the registry lock; lock order
  is registry -> SurfaceInfo on every path.

- iOS CAMetalLayer use-after-free: the latched attach stored an unretained
  layer pointer; on dev reload the registry is cleared before MetalView
  dealloc runs, so dealloc could not cancel the pending attach and the
  queued flush later touched a freed layer. The layer is now
  CFBridgingRetain'd for the lifetime of the attach and released on the main
  queue via the same releaser mechanism as Android's ANativeWindow ref.

Author: wcandillon

packages/webgpu/android/cpp/cpp-adapter.cpp

@@ -25,8 +25,7 @@ extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUModule_initializeNative(
   auto jsCallInvoker{
       facebook::jni::alias_ref<facebook::react::CallInvokerHolder::javaobject>{
           reinterpret_cast<facebook::react::CallInvokerHolder::javaobject>(
-              jsCallInvokerHolder)} -> cthis()
-          ->getCallInvoker()};
+              jsCallInvokerHolder)} -> cthis()->getCallInvoker()};
   auto platformContext =
       std::make_shared<rnwgpu::AndroidPlatformContext>(globalBlobModule);
   manager = std::make_shared<rnwgpu::RNWebGPUManager>(runtime, jsCallInvoker,
@@ -37,35 +36,58 @@ extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUView_onSurfaceChanged(
     JNIEnv *env, jobject thiz, jobject surface, jint contextId, jfloat width,
     jfloat height) {
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
-  registry.getSurfaceInfo(contextId)->resize(static_cast<int>(width),
-                                             static_cast<int>(height));
+  if (auto info = registry.getSurfaceInfo(contextId)) {
+    info->resize(static_cast<int>(width), static_cast<int>(height));
+  }
 }
 
 extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUView_onSurfaceCreate(
     JNIEnv *env, jobject thiz, jobject jSurface, jint contextId, jfloat width,
     jfloat height) {
+  if (manager == nullptr) {
+    return;
+  }
+  // ANativeWindow_fromSurface acquires a reference; SurfaceInfo releases it
+  // (via the releaser below) once it is done with the window.
   auto window = ANativeWindow_fromSurface(env, jSurface);
-  // ANativeWindow_acquire(window);
+  if (window == nullptr) {
+    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));
-  registry
-      .getSurfaceInfoOrCreate(contextId, gpu, static_cast<int>(width),
-                              static_cast<int>(height))
-      ->switchToOnscreen(window, surface);
+  // Find-or-create + attach runs atomically under the registry lock so a
+  // concurrent destroyContext cannot orphan this surface.
+  auto info = registry.attachSurface(
+      contextId, gpu, static_cast<int>(width), static_cast<int>(height), window,
+      surface, [](void *nativeSurface) {
+        ANativeWindow_release(static_cast<ANativeWindow *>(nativeSurface));
+      });
+  // The attach is adopted at the next frame boundary by the rendering thread;
+  // schedule a flush so contexts that are not currently rendering still pick
+  // it up (and present their last offscreen frame).
+  manager->flushPendingSurfaceTransition(info);
 }
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_webgpu_WebGPUView_switchToOffscreenSurface(JNIEnv *env, jobject thiz,
                                                     jint contextId) {
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
-  auto nativeSurface = registry.getSurfaceInfo(contextId)->switchToOffscreen();
-  // ANativeWindow_release(reinterpret_cast<ANativeWindow *>(nativeSurface));
+  if (auto info = registry.getSurfaceInfo(contextId)) {
+    info->switchToOffscreen();
+  }
 }
 
-extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUView_onSurfaceDestroy(
+extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUView_onViewDestroyed(
     JNIEnv *env, jobject thiz, jint contextId) {
+  // The view dies with its Canvas (contextIds are never reused), so view
+  // teardown retires the registry entry. The JS-side cleanup
+  // (RNWebGPU.destroyContext) only handles entries that never had a native
+  // surface; see RNWebGPU::destroyContext for the ownership split.
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
+  if (auto info = registry.getSurfaceInfo(contextId)) {
+    info->detachSurface();
+  }
   registry.removeSurfaceInfo(contextId);
-}
+}

packages/webgpu/android/src/main/java/com/webgpu/WebGPUAHBView.java

@@ -254,9 +254,9 @@ private void cleanupImageReader() {
   protected void onDetachedFromWindow() {
     super.onDetachedFromWindow();
 
-    // Notify WebGPU that surface is being destroyed
+    // Detach: rendering falls back to the offscreen texture until reattach.
     if (mSurfaceCreated) {
-      mApi.surfaceDestroyed();
+      mApi.surfaceOffscreen();
       mSurfaceCreated = false;
     }
 

packages/webgpu/android/src/main/java/com/webgpu/WebGPUAPI.java

@@ -4,6 +4,13 @@
 
 import com.facebook.proguard.annotations.DoNotStrip;
 
+/**
+ * Surface lifecycle events a WebGPU child view reports. The registry entry
+ * itself is owned by the JS Canvas component (created lazily, removed via
+ * RNWebGPU.destroyContext on unmount); views only attach and detach surfaces.
+ * A detached context keeps rendering into an offscreen texture whose content
+ * is blitted onto the next attached surface.
+ */
 public interface WebGPUAPI {
 
   void surfaceCreated(
@@ -14,7 +21,5 @@ void surfaceChanged(
     Surface surface
   );
 
-  void surfaceDestroyed();
-
   void surfaceOffscreen();
 }

packages/webgpu/android/src/main/java/com/webgpu/WebGPUBaseView.java

@@ -21,7 +21,9 @@ public WebGPUSurfaceView(Context context, WebGPUAPI api) {
   @Override
   protected void onDetachedFromWindow() {
     super.onDetachedFromWindow();
-    mApi.surfaceDestroyed();
+    // surfaceDestroyed() normally fires during detach as well; going offscreen
+    // is idempotent, so this is just a safety net for paths where it does not.
+    mApi.surfaceOffscreen();
   }
 
   @Override

packages/webgpu/android/src/main/java/com/webgpu/WebGPUSurfaceView.java

@@ -7,12 +7,11 @@
 import android.view.TextureView;
 import androidx.annotation.NonNull;
 
-import org.w3c.dom.Text;
-
 @SuppressLint("ViewConstructor")
 public class WebGPUTextureView extends TextureView implements TextureView.SurfaceTextureListener {
 
   WebGPUAPI mApi;
+  private Surface mSurface;
 
   public WebGPUTextureView(Context context, WebGPUAPI api) {
     super(context);
@@ -23,19 +22,24 @@ public WebGPUTextureView(Context context, WebGPUAPI api) {
 
   @Override
   public void onSurfaceTextureAvailable(@NonNull SurfaceTexture surfaceTexture, int width, int height) {
-    Surface surface = new Surface(surfaceTexture);
-    mApi.surfaceCreated(surface);
+    mSurface = new Surface(surfaceTexture);
+    mApi.surfaceCreated(mSurface);
   }
 
   @Override
   public void onSurfaceTextureSizeChanged(@NonNull SurfaceTexture surfaceTexture, int width, int height) {
-    Surface surface = new Surface(surfaceTexture);
-    mApi.surfaceChanged(surface);
+    mApi.surfaceChanged(mSurface);
   }
 
   @Override
   public boolean onSurfaceTextureDestroyed(@NonNull SurfaceTexture surfaceTexture) {
-    mApi.surfaceDestroyed();
+    // Detach first (synchronous through JNI) so the native side has dropped
+    // its window reference before we release ours.
+    mApi.surfaceOffscreen();
+    if (mSurface != null) {
+      mSurface.release();
+      mSurface = null;
+    }
     return true;
   }
 

packages/webgpu/android/src/main/java/com/webgpu/WebGPUTextureView.java

@@ -73,16 +73,19 @@ public void surfaceChanged(Surface surface) {
     onSurfaceChanged(surface, mContextId, width, height);
   }
 
-  @Override
-  public void surfaceDestroyed() {
-    onSurfaceDestroy(mContextId);
-  }
-
   @Override
   public void surfaceOffscreen() {
     switchToOffscreenSurface(mContextId);
   }
 
+  /**
+   * Called from WebGPUViewManager.onDropViewInstance when React removes this
+   * view: the view dies with its Canvas, so it retires the registry entry.
+   */
+  public void destroy() {
+    onViewDestroyed(mContextId);
+  }
+
   @DoNotStrip
   private native void onSurfaceCreate(
     Surface surface,
@@ -100,9 +103,9 @@ private native void onSurfaceChanged(
   );
 
   @DoNotStrip
-  private native void onSurfaceDestroy(int contextId);
+  private native void switchToOffscreenSurface(int contextId);
 
   @DoNotStrip
-  private native void switchToOffscreenSurface(int contextId);
+  private native void onViewDestroyed(int contextId);
 
 }

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

@@ -24,6 +24,12 @@ public WebGPUView createViewInstance(@NonNull ThemedReactContext context) {
     return new WebGPUView(context);
   }
 
+  @Override
+  public void onDropViewInstance(@NonNull WebGPUView view) {
+    super.onDropViewInstance(view);
+    view.destroy();
+  }
+
   @Override
   @ReactProp(name = "transparent")
   public void setTransparent(WebGPUView view, boolean value) {

packages/webgpu/android/src/main/java/com/webgpu/WebGPUViewManager.java

@@ -23,27 +23,52 @@ - (instancetype)init {
 - (void)configure {
   auto size = self.frame.size;
   std::shared_ptr<rnwgpu::RNWebGPUManager> manager = [WebGPUModule getManager];
-  void *nativeSurface = (__bridge void *)self.layer;
+  if (manager == nullptr) {
+    return;
+  }
+  // Retain the layer for as long as SurfaceInfo holds the pointer: the
+  // latched attach (and the flush lambda that adopts it) can outlive this
+  // view, e.g. across a dev reload where the registry is cleared before
+  // 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);
-  registry
-      .getSurfaceInfoOrCreate([_contextId intValue], gpu, size.width,
-                              size.height)
-      ->switchToOnscreen(nativeSurface, surface);
+  // Find-or-create + attach runs atomically under the registry lock so a
+  // concurrent destroyContext cannot orphan this surface.
+  auto info = registry.attachSurface(
+      [_contextId intValue], gpu, size.width, size.height, nativeSurface,
+      surface, [](void *layer) {
+        // The releaser can run on the rendering thread; CALayer teardown
+        // belongs on the main thread.
+        dispatch_async(dispatch_get_main_queue(), ^{
+          CFBridgingRelease(layer);
+        });
+      });
+  // The attach is adopted at the next frame boundary by the rendering thread;
+  // schedule a flush so contexts that are not currently rendering still pick
+  // it up (and present their last offscreen frame).
+  manager->flushPendingSurfaceTransition(info);
 }
 
 - (void)update {
   auto size = self.frame.size;
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
-  registry.getSurfaceInfo([_contextId intValue])
-      ->resize(size.width, size.height);
+  if (auto info = registry.getSurfaceInfo([_contextId intValue])) {
+    info->resize(size.width, size.height);
+  }
 }
 
 - (void)dealloc {
+  // The view dies with its Canvas (contextIds are never reused), so view
+  // teardown retires the registry entry. The JS-side cleanup
+  // (RNWebGPU.destroyContext) only handles entries that never had a native
+  // surface; see RNWebGPU::destroyContext for the ownership split.
   auto &registry = rnwgpu::SurfaceRegistry::getInstance();
-  // Remove the surface info from the registry
+  if (auto info = registry.getSurfaceInfo([_contextId intValue])) {
+    info->detachSurface();
+  }
   registry.removeSurfaceInfo([_contextId intValue]);
 }
 

packages/webgpu/apple/MetalView.mm

@@ -31,9 +31,9 @@
 #include "GPURenderPassEncoder.h"
 #include "GPURenderPipeline.h"
 #include "GPUSampler.h"
+#include "GPUShaderModule.h"
 #include "GPUSharedFence.h"
 #include "GPUSharedTextureMemory.h"
-#include "GPUShaderModule.h"
 #include "GPUSupportedLimits.h"
 #include "GPUTexture.h"
 #include "GPUTextureView.h"
@@ -237,7 +237,20 @@ void RNWebGPUManager::installWebGPUWorkletHelpers(jsi::Runtime &runtime) {
   runtime.global().setProperty(runtime, "__webgpuBox", std::move(boxFunc));
 }
 
+void RNWebGPUManager::flushPendingSurfaceTransition(
+    std::shared_ptr<SurfaceInfo> info) {
+  if (info == nullptr || _jsCallInvoker == nullptr) {
+    return;
+  }
+  _jsCallInvoker->invokeAsync(
+      [info = std::move(info)] { info->applyPendingAttach(); });
+}
+
 RNWebGPUManager::~RNWebGPUManager() {
+  // Drop all canvas registry entries: after a reload the JS side restarts its
+  // contextId counter, and stale entries would alias new canvases onto dead
+  // surfaces.
+  SurfaceRegistry::getInstance().clear();
   _jsRuntime = nullptr;
   _jsCallInvoker = nullptr;
 }