react-native-webgpu 0.10.1 → 0.10.3

package/Package.swift

@@ -1,54 +1,27 @@
-// swift-tools-version: 5.9
+// swift-tools-version: 6.0
 // Generated by scripts/generate-package-swift.ts — do not edit by hand.
 // Re-run that script after a new Dawn release to update the URL/checksum below.
-import Foundation
-import PackageDescription
-
-// Integration model: a local Swift package next to a CocoaPods install.
 //
-// This manifest targets React Native 0.81+ (the package's peer range), where
-// React Native's own headers and the RNWgpuViewSpec codegen output only exist
-// inside the consuming app's CocoaPods install. Add this package as a local
-// Swift Package dependency in place of the react-native-webgpu pod (export
-// RNWGPU_USE_SPM=1 for `pod install`) and keep running `pod install` for
-// everything else. The header search paths below point into that Pods
-// directory. They can only be expressed as `unsafeFlags`, and SwiftPM rejects
-// unsafeFlags in anything but a path dependency, so this package can only be
-// consumed locally, never by URL and version.
+// SwiftPM manifest for react-native-webgpu. iOS only.
+// Additive: the CocoaPods podspec remains the supported default.
 //
-// React Native 0.87 added SwiftPM autolinking. There, a dependency shipping
-// its own Package.swift is treated as self-managed and referenced directly,
-// and it consumes React Native's headers as SwiftPM products (ReactHeaders,
-// ReactNativeHeaders, ReactNativeDependenciesHeaders, plus ReactAppHeaders
-// from the app's generated codegen package) with no CocoaPods at all. This
-// manifest does not implement that model yet: on a 0.87+ app that has opted
-// into SwiftPM autolinking it is picked up as self-managed but cannot find
-// React Native's headers. Keep CocoaPods for React Native on those apps.
+// React Native 0.87+ references a library that ships its own Package.swift
+// through a symlink at <app>/ios/build/generated/autolinking/libs/<name>, and
+// resolves the relative paths below against that symlink. They are the same
+// for every standard app, because the symlink location is. Earlier React
+// Native releases have no SwiftPM autolinking: keep CocoaPods there.
 
-// Absolute location of this package. Xcode may hand over a symlink (React
-// Native 0.87's autolinker does), so resolve it before deriving sibling paths.
+import Foundation
+import PackageDescription
+
+// Absolute location of this package. Xcode passes the autolinking symlink as
+// the package directory, so resolve it before deriving sibling paths.
 let packageRoot = URL(fileURLWithPath: Context.packageDirectory)
   .resolvingSymlinksInPath().path
 let sibling = { (relative: String) -> String in
   URL(fileURLWithPath: "\(packageRoot)/\(relative)").standardized.path
 }
 
-// Where the consuming app's Pods live. PODS_ROOT is exported by Xcode.app for
-// a real build, but never by plain `xcodebuild`, and never while Xcode indexes
-// the manifest before a first build. SwiftPM also caches manifest evaluations,
-// so an evaluation that ran without it would otherwise be cached with an empty
-// include list and surface later as header-not-found errors. Fall back to
-// where Pods sit relative to this package for every standard app layout, so
-// the result is the same with or without the environment variable.
-let podsRootCandidates = [
-  sibling("../../ios/Pods"), // consumer: <app>/node_modules/react-native-webgpu
-  sibling("../../apps/spm-example/ios/Pods"), // this monorepo
-]
-let podsRoot =
-  ProcessInfo.processInfo.environment["PODS_ROOT"]
-  ?? podsRootCandidates.first { FileManager.default.fileExists(atPath: $0) }
-  ?? podsRootCandidates[0]
-
 // Skia Graphite and WebGPU must link the exact same Dawn, or the pair links
 // fine and crashes at runtime. react-native-skia's podspec enforces this at
 // `pod install` time by comparing its libs/.dawn-version against this
@@ -79,57 +52,6 @@ for skia in skiaCandidates {
   break
 }
 
-// Static-library Pods layout. With `use_frameworks!` CocoaPods keeps headers
-// inside each framework instead and none of these paths exist; the podspec
-// refuses RNWGPU_USE_SPM in that mode.
-let publicHeaders = "\(podsRoot)/Headers/Public"
-let privateHeaders = "\(podsRoot)/Headers/Private"
-let headerSearchPaths = [
-  publicHeaders,
-  // Yoga's headers are CocoaPods-private (apps aren't meant to use Yoga's
-  // C++ API directly), but React-Fabric's view props headers include them
-  // transitively.
-  "\(privateHeaders)/Yoga",
-  "\(publicHeaders)/React-Core",
-  "\(publicHeaders)/React-jsi",
-  "\(publicHeaders)/React-callinvoker",
-  "\(publicHeaders)/React-NativeModulesApple",
-  "\(publicHeaders)/React-RCTFabric",
-  "\(publicHeaders)/ReactCodegen",
-  "\(publicHeaders)/RCT-Folly",
-  "\(publicHeaders)/RCTRequired",
-  "\(publicHeaders)/RCTTypeSafety",
-  "\(publicHeaders)/FBLazyVector",
-  "\(publicHeaders)/ReactCommon",
-  "\(publicHeaders)/React-Fabric",
-  "\(publicHeaders)/React-graphics",
-  "\(publicHeaders)/React-utils",
-  "\(publicHeaders)/React-featureflags",
-  "\(publicHeaders)/React-rendererdebug",
-  "\(publicHeaders)/React-debug",
-  "\(publicHeaders)/React-timing",
-  "\(publicHeaders)/React-runtimescheduler",
-  "\(publicHeaders)/React-rendererconsistency",
-  "\(publicHeaders)/React-performancetimeline",
-  "\(publicHeaders)/React-runtimeexecutor",
-  "\(publicHeaders)/React-cxxreact",
-  "\(publicHeaders)/hermes-engine",
-  "\(publicHeaders)/glog",
-  "\(publicHeaders)/DoubleConversion",
-  "\(publicHeaders)/fmt",
-  "\(publicHeaders)/fast_float",
-]
-// The only unsafe flags left: .headerSearchPath cannot escape the target
-// path, and these live in the app's Pods directory.
-let cFamilyIncludeFlags = headerSearchPaths.map { "-I\($0)" }
-let follyDefines: [(name: String, value: String?)] = [
-  ("FOLLY_NO_CONFIG", nil),
-  ("FOLLY_MOBILE", "1"),
-  ("FOLLY_USE_LIBCPP", "1"),
-  ("FOLLY_CFG_NO_COROUTINES", "1"),
-  ("FOLLY_HAVE_CLOCK_GETTIME", "1"),
-]
-
 // Unlike a native Xcode target, SwiftPM doesn't generate an implicit
 // per-target header map, so quoted includes only resolve within the
 // including file's own directory. The sources use bare cross-directory
@@ -153,10 +75,19 @@ let internalHeaderDirs = [
 ]
 
 let package = Package(
-  name: "react-native-webgpu",
-  platforms: [.iOS("15.1"), .macOS("11.0")],
+  name: "ReactNativeWebGPU",
+  // SwiftPM refuses to link a product whose floor is above the depending
+  // target's. React Native's generated Autolinked aggregate hardcodes iOS 15.0
+  // (react-native#58379 derives it from the app instead), so this must not
+  // exceed 15.0; a lower floor is always accepted.
+  platforms: [.iOS(.v15)],
   products: [
-    .library(name: "react-native-webgpu", targets: ["react-native-webgpu"])
+    // Autolinking looks this name up verbatim; react-native.config.js pins it.
+    .library(name: "ReactNativeWebGPU", targets: ["ReactNativeWebGPU"])
+  ],
+  dependencies: [
+    .package(name: "React-GeneratedCode", path: "../../../ios"),
+    .package(name: "ReactNative", path: "../../../../xcframeworks"),
   ],
   targets: [
     // Dawn's compiled WebGPU implementation. The xcframework embeds the
@@ -168,18 +99,41 @@ let package = Package(
       checksum: "896575ffbc99610198a83d061f8c5a2789139b7f16c669fbf3a9f7a7ac9be123"
     ),
     .target(
-      name: "react-native-webgpu",
-      dependencies: ["WebGPUDawn"],
+      name: "ReactNativeWebGPU",
+      dependencies: [
+        .product(name: "ReactHeaders", package: "ReactNative"),
+        .product(name: "ReactNativeHeaders", package: "ReactNative"),
+        .product(name: "ReactNativeDependenciesHeaders", package: "ReactNative"),
+        // RNWgpuViewSpec, generated by the app's codegen run.
+        .product(name: "ReactAppHeaders", package: "React-GeneratedCode"),
+        "WebGPUDawn",
+      ],
+      // apple/ and cpp/ have no common ancestor below the package root, and
+      // .headerSearchPath cannot escape the target path.
       path: ".",
+      // Explicit, so SwiftPM never walks node_modules, lib, android, or the
+      // headers-only cpp/webgpu and cpp/dawn trees.
       sources: ["apple", "cpp/jsi", "cpp/rnwgpu"],
+      // SwiftPM requires a public headers directory inside the target and
+      // defaults to "include", which this package does not have.
       publicHeadersPath: "apple",
-      cSettings: internalHeaderDirs.map { CSetting.headerSearchPath($0) }
-        + follyDefines.map { CSetting.define($0.name, to: $0.value) }
-        + [.unsafeFlags(cFamilyIncludeFlags)],
-      cxxSettings: internalHeaderDirs.map { CXXSetting.headerSearchPath($0) }
-        + follyDefines.map { CXXSetting.define($0.name, to: $0.value) }
-        + [.unsafeFlags(cFamilyIncludeFlags)],
+      cxxSettings: internalHeaderDirs.map { CXXSetting.headerSearchPath($0) } + [
+        // CocoaPods forces both project-wide; the SwiftPM path defines neither.
+        // React Native's headers gate on them, and the prebuilt React.framework
+        // was built with both, so the module must see the same declarations.
+        .define("RCT_NEW_ARCH_ENABLED", to: "1"),
+        .define("RCT_REMOVE_LEGACY_ARCH", to: "1"),
+
+        // React's prebuilt C++ ABI is NDEBUG-gated (DebugStringConvertible's
+        // vtable and ShadowNode layout diverge). Omitting either breaks the
+        // Release link.
+        .define("DEBUG", .when(configuration: .debug)),
+        .define("NDEBUG", .when(configuration: .release)),
+      ],
       linkerSettings: [
+        // VideoPlayer uses AVFoundation / CoreMedia, shared-texture surfaces
+        // use CoreVideo (CVPixelBuffer), and ImageIO provides CGImageSource,
+        // the image decoder behind createImageBitmap.
         .linkedFramework("AVFoundation"),
         .linkedFramework("CoreMedia"),
         .linkedFramework("CoreVideo"),
@@ -187,5 +141,6 @@ let package = Package(
       ]
     ),
   ],
+  // React Native's headers need C++20.
   cxxLanguageStandard: .cxx20
 )

package/android/cpp/cpp-adapter.cpp

@@ -6,6 +6,7 @@
 #include <jsi/jsi.h>
 
 #include <ReactCommon/CallInvokerHolder.h>
+#include <android/hardware_buffer_jni.h>
 #include <android/native_window_jni.h>
 #include <webgpu/webgpu_cpp.h>
 
@@ -25,7 +26,8 @@ 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,
@@ -91,3 +93,142 @@ extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUView_onViewDestroyed(
   }
   registry.removeSurfaceInfo(contextId);
 }
+
+// --- WebGPUHardwareBufferView (AHB-pool presentation)
+// ---------------------------------
+
+namespace {
+
+// Weak handle on a WebGPUHardwareBufferView used by the native fence waiter to
+// wake the UI thread when a frame is ready. Holding it weakly means a view that
+// RN has dropped is not kept alive by a SurfaceInfo that outlives it (the
+// registry keeps the SurfaceInfo until onDropViewInstance).
+struct HardwareBufferViewWaker {
+  jweak view = nullptr;
+  jmethodID onFrameReady = nullptr;
+
+  HardwareBufferViewWaker(JNIEnv *env, jobject thiz) {
+    view = env->NewWeakGlobalRef(thiz);
+    jclass cls = env->GetObjectClass(thiz);
+    onFrameReady = env->GetMethodID(cls, "onNativeFrameReady", "()V");
+    env->DeleteLocalRef(cls);
+  }
+
+  ~HardwareBufferViewWaker() {
+    // May run on the waiter or JS thread; ThreadScope attaches if needed.
+    facebook::jni::ThreadScope scope;
+    JNIEnv *env = facebook::jni::Environment::current();
+    if (env != nullptr && view != nullptr) {
+      env->DeleteWeakGlobalRef(view);
+    }
+  }
+
+  // Called on the waiter thread, outside the pool lock.
+  void operator()() const {
+    facebook::jni::ThreadScope scope;
+    JNIEnv *env = facebook::jni::Environment::current();
+    if (env == nullptr || onFrameReady == nullptr) {
+      return;
+    }
+    jobject local = env->NewLocalRef(view);
+    if (local == nullptr) {
+      return; // the view was garbage collected
+    }
+    env->CallVoidMethod(local, onFrameReady);
+    if (env->ExceptionCheck()) {
+      env->ExceptionClear();
+    }
+    env->DeleteLocalRef(local);
+  }
+};
+
+} // namespace
+
+// Turn on pool mode for this context. dpW/dpH is the canvas-client (dp) size;
+// the native pool buffers are sized from the canvas drawing buffer lazily.
+extern "C" JNIEXPORT void JNICALL
+Java_com_webgpu_WebGPUHardwareBufferView_nEnablePool(JNIEnv *env, jobject thiz,
+                                                     jint contextId, jint dpW,
+                                                     jint dpH) {
+  auto &registry = rnwgpu::SurfaceRegistry::getInstance();
+  auto info = registry.getSurfaceInfoOrCreate(
+      contextId, manager->_gpu, 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));
+}
+
+// Keep the canvas-client (dp) size in sync on resize.
+extern "C" JNIEXPORT void JNICALL
+Java_com_webgpu_WebGPUHardwareBufferView_nSetClientSize(JNIEnv *env,
+                                                        jobject thiz,
+                                                        jint contextId,
+                                                        jint dpW, jint dpH) {
+  auto &registry = rnwgpu::SurfaceRegistry::getInstance();
+  auto info = registry.getSurfaceInfo(contextId);
+  if (info != nullptr) {
+    info->setPoolClientSize(static_cast<int>(dpW), static_cast<int>(dpH));
+  }
+}
+
+// The HardwareBuffer backing a (generation, slot), for the view to wrap in a
+// Bitmap. Returns null for a retired generation.
+extern "C" JNIEXPORT jobject JNICALL
+Java_com_webgpu_WebGPUHardwareBufferView_nGetHardwareBuffer(
+    JNIEnv *env, jobject thiz, jint contextId, jint generation, jint slot) {
+  auto &registry = rnwgpu::SurfaceRegistry::getInstance();
+  auto info = registry.getSurfaceInfo(contextId);
+  if (info == nullptr) {
+    return nullptr;
+  }
+  void *ahb = info->poolBufferForDisplay(static_cast<uint32_t>(generation),
+                                         static_cast<int>(slot));
+  if (ahb == nullptr) {
+    return nullptr;
+  }
+  // toHardwareBuffer acquires its own ref for the returned jobject; the pool
+  // keeps the underlying buffer alive independently.
+  return AHardwareBuffer_toHardwareBuffer(env,
+                                          static_cast<AHardwareBuffer *>(ahb));
+}
+
+// Latest signaled frame ready to display, encoded (generation << 32 | slot), or
+// -1 when nothing is new. Called on the UI thread after onNativeFrameReady.
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_webgpu_WebGPUHardwareBufferView_nPollReady(JNIEnv *env, jobject thiz,
+                                                    jint contextId) {
+  auto &registry = rnwgpu::SurfaceRegistry::getInstance();
+  auto info = registry.getSurfaceInfo(contextId);
+  if (info == nullptr) {
+    return -1;
+  }
+  return info->poolPollReady();
+}
+
+// The view is done displaying (and holding) a slot; return it to the pool.
+extern "C" JNIEXPORT void JNICALL
+Java_com_webgpu_WebGPUHardwareBufferView_nReleaseSlot(JNIEnv *env, jobject thiz,
+                                                      jint contextId,
+                                                      jint generation,
+                                                      jint slot) {
+  auto &registry = rnwgpu::SurfaceRegistry::getInstance();
+  auto info = registry.getSurfaceInfo(contextId);
+  if (info != nullptr) {
+    info->poolReleaseSlot(static_cast<uint32_t>(generation),
+                          static_cast<int>(slot));
+  }
+}
+
+// View detached / hidden: keep the canvas alive by falling back to an offscreen
+// texture (mirrors switchToOffscreenSurface for the surface path).
+extern "C" JNIEXPORT void JNICALL
+Java_com_webgpu_WebGPUHardwareBufferView_nSwitchToOffscreen(JNIEnv *env,
+                                                            jobject thiz,
+                                                            jint contextId) {
+  auto &registry = rnwgpu::SurfaceRegistry::getInstance();
+  auto info = registry.getSurfaceInfo(contextId);
+  if (info != nullptr) {
+    info->setPoolFrameReadyCallback(nullptr);
+    info->switchToOffscreen();
+  }
+}

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

@@ -22,4 +22,6 @@ public interface WebGPUAPI {
   );
 
   void surfaceOffscreen();
+
+  int getContextId();
 }

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

@@ -0,0 +1,278 @@
+package com.webgpu;
+
+import android.annotation.SuppressLint;
+import android.content.Context;
+import android.graphics.Bitmap;
+import android.graphics.Canvas;
+import android.graphics.Paint;
+import android.graphics.Rect;
+import android.hardware.HardwareBuffer;
+import android.os.Build;
+import android.os.Handler;
+import android.os.Looper;
+import android.view.View;
+
+import androidx.annotation.Keep;
+import androidx.annotation.NonNull;
+import androidx.annotation.RequiresApi;
+
+import java.util.ArrayDeque;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * A "normal RN view" backend for the WebGPU canvas.
+ *
+ * <p>WebGPU renders into a native pool of AHardwareBuffers (sized from the canvas drawing buffer,
+ * like the swapchain) that Dawn imports as SharedTextureMemory; see SurfaceRegistry.h. Each finished
+ * buffer is drawn inline here via {@link Bitmap#wrapHardwareBuffer} + {@link Canvas#drawBitmap}, so
+ * this is a plain {@link View}: parent transforms, clipping, alpha, z-order and animations all
+ * apply, with no GL interop and no extra copy.
+ *
+ * <p>This view is a pure consumer: it enables pool mode, and whenever the native fence waiter
+ * signals that a frame is ready it asks native for the latest ready (gen, slot), wraps that buffer
+ * in a cached Bitmap, and draws it scaled to the current bounds. Acquire is rigorous (native blocks
+ * on Dawn's render-complete fence before a frame is ready); release is heuristic via a held-ring of
+ * {@link #HELD_MAX} frames.
+ */
+@RequiresApi(api = Build.VERSION_CODES.Q)
+@SuppressLint("ViewConstructor")
+public class WebGPUHardwareBufferView extends View {
+
+  private static final int HELD_MAX = 2; // displayed frames kept before release (release safety)
+
+  private final WebGPUAPI mApi;
+  private final Paint mPaint;
+  private final Rect mSrc = new Rect();
+  private final Rect mDst = new Rect();
+
+  // token (generation << 32 | slot) -> wrapped hardware Bitmap (one per slot per generation).
+  private final Map<Long, Bitmap> mBitmaps = new HashMap<>();
+  // Held-ring of displayed frame tokens (newest last). The newest is what onDraw shows.
+  private final ArrayDeque<Long> mHeld = new ArrayDeque<>();
+
+  // Native -> UI thread wake-up. The fence waiter calls onNativeFrameReady() off the UI thread;
+  // we coalesce those into at most one pending consume() on the main looper.
+  private final Handler mMainHandler = new Handler(Looper.getMainLooper());
+  private final AtomicBoolean mConsumePosted = new AtomicBoolean(false);
+  private final Runnable mConsume = this::consume;
+
+  private Bitmap mDisplayed;
+  private int mDisplayedW;
+  private int mDisplayedH;
+  private int mCurrentGen;
+
+  private boolean mAttached;
+  private boolean mEnabled;
+
+  public WebGPUHardwareBufferView(Context context, WebGPUAPI api) {
+    super(context);
+    mApi = api;
+    mPaint = new Paint(Paint.FILTER_BITMAP_FLAG);
+    setWillNotDraw(false);
+  }
+
+  private int contextId() {
+    return mApi.getContextId();
+  }
+
+  private static int genOf(long token) {
+    return (int) (token >>> 32);
+  }
+
+  private static int slotOf(long token) {
+    return (int) (token & 0xffffffffL);
+  }
+
+  // --- Sizing ----------------------------------------------------------------
+
+  private void enablePool(int w, int h) {
+    final float density = getResources().getDisplayMetrics().density;
+    nEnablePool(contextId(), Math.max(1, Math.round(w / density)),
+        Math.max(1, Math.round(h / density)));
+    mEnabled = true;
+  }
+
+  @Override
+  protected void onSizeChanged(int w, int h, int oldw, int oldh) {
+    super.onSizeChanged(w, h, oldw, oldh);
+    if (w <= 0 || h <= 0) {
+      return;
+    }
+    if (!mEnabled) {
+      enablePool(w, h);
+    } else {
+      // Native reallocates the pool from the canvas drawing buffer; we only keep the dp
+      // canvas-client size in sync so JS computes the right canvas.width/height.
+      final float density = getResources().getDisplayMetrics().density;
+      nSetClientSize(contextId(), Math.max(1, Math.round(w / density)),
+          Math.max(1, Math.round(h / density)));
+    }
+  }
+
+  // --- Consume (UI thread, woken by the native fence waiter) -----------------
+
+  /** Called from the native fence-waiter thread (see cpp-adapter.cpp) when a frame is ready. */
+  @Keep
+  private void onNativeFrameReady() {
+    if (mConsumePosted.compareAndSet(false, true)) {
+      mMainHandler.post(mConsume);
+    }
+  }
+
+  private void consume() {
+    mConsumePosted.set(false);
+    if (!mAttached) {
+      return;
+    }
+    long token = nPollReady(contextId());
+    if (token >= 0) {
+      onFrameReady(token);
+    }
+  }
+
+  private void onFrameReady(long token) {
+    final int gen = genOf(token);
+    final int slot = slotOf(token);
+
+    if (gen > mCurrentGen) {
+      mCurrentGen = gen;
+      recycleStaleGenerations();
+    }
+
+    Bitmap bmp = mBitmaps.get(token);
+    if (bmp == null) {
+      HardwareBuffer hb = nGetHardwareBuffer(contextId(), gen, slot);
+      if (hb == null) {
+        return; // generation already retired; drop this stale frame
+      }
+      // wrapHardwareBuffer takes its own ref, so the wrapper can be closed immediately.
+      bmp = Bitmap.wrapHardwareBuffer(hb, null);
+      hb.close();
+      if (bmp == null) {
+        // Cannot display this frame; hand the slot straight back so the pool
+        // does not drain (native marked it Displayed when we polled it).
+        nReleaseSlot(contextId(), gen, slot);
+        return;
+      }
+      mBitmaps.put(token, bmp);
+    }
+
+    mDisplayed = bmp;
+    mDisplayedW = bmp.getWidth();
+    mDisplayedH = bmp.getHeight();
+
+    mHeld.addLast(token);
+    while (mHeld.size() > HELD_MAX) {
+      long old = mHeld.pollFirst();
+      if (genOf(old) == mCurrentGen) {
+        // Live generation reuses slots: hand it back once HWUI has had time to sample it.
+        nReleaseSlot(contextId(), mCurrentGen, slotOf(old));
+      } else {
+        // Old generation: its slot is never re-rendered, so just drop the Bitmap.
+        recycleToken(old);
+      }
+    }
+    invalidate();
+  }
+
+  private void recycleStaleGenerations() {
+    // Keep the current and previous generation (cross-fade); recycle older cached Bitmaps that are
+    // no longer held.
+    Iterator<Map.Entry<Long, Bitmap>> it = mBitmaps.entrySet().iterator();
+    while (it.hasNext()) {
+      Map.Entry<Long, Bitmap> e = it.next();
+      if (genOf(e.getKey()) < mCurrentGen - 1 && !mHeld.contains(e.getKey())) {
+        Bitmap b = e.getValue();
+        if (b != mDisplayed && !b.isRecycled()) {
+          b.recycle();
+        }
+        it.remove();
+      }
+    }
+  }
+
+  private void recycleToken(long token) {
+    Bitmap b = mBitmaps.remove(token);
+    if (b != null && b != mDisplayed && !b.isRecycled()) {
+      b.recycle();
+    }
+  }
+
+  @Override
+  protected void onDraw(Canvas canvas) {
+    super.onDraw(canvas);
+    Bitmap bmp = mDisplayed;
+    if (bmp == null || bmp.isRecycled()) {
+      return;
+    }
+    // Always scale the last good frame to the current bounds, so a buffer that lags the view size
+    // (mid-resize) is shown stretched rather than blank.
+    mSrc.set(0, 0, mDisplayedW, mDisplayedH);
+    mDst.set(0, 0, getWidth(), getHeight());
+    canvas.drawBitmap(bmp, mSrc, mDst, mPaint);
+  }
+
+  // --- Lifecycle -------------------------------------------------------------
+
+  @Override
+  protected void onAttachedToWindow() {
+    super.onAttachedToWindow();
+    mAttached = true;
+    if (!mEnabled && getWidth() > 0 && getHeight() > 0) {
+      enablePool(getWidth(), getHeight());
+    }
+    // Pick up anything that became ready while we were detached.
+    onNativeFrameReady();
+  }
+
+  @Override
+  protected void onDetachedFromWindow() {
+    super.onDetachedFromWindow();
+    mAttached = false;
+    mEnabled = false;
+    mMainHandler.removeCallbacks(mConsume);
+    mConsumePosted.set(false);
+
+    // Keep the canvas alive offscreen, then drop all GPU resources. The
+    // SurfaceInfo stays registered so a transient detach/re-attach keeps
+    // working; WebGPUViewManager.onDropViewInstance removes it when RN drops
+    // the view for good.
+    nSwitchToOffscreen(contextId());
+
+    mDisplayed = null;
+    mHeld.clear();
+    for (Bitmap b : mBitmaps.values()) {
+      if (!b.isRecycled()) {
+        b.recycle();
+      }
+    }
+    mBitmaps.clear();
+    mCurrentGen = 0;
+  }
+
+  @Override
+  protected void onVisibilityChanged(@NonNull View changedView, int visibility) {
+    super.onVisibilityChanged(changedView, visibility);
+    if (visibility == VISIBLE && mAttached && !mEnabled
+        && getWidth() > 0 && getHeight() > 0) {
+      enablePool(getWidth(), getHeight());
+    }
+  }
+
+  // --- Native (cpp-adapter.cpp) ----------------------------------------------
+
+  private native void nEnablePool(int contextId, int dpW, int dpH);
+
+  private native void nSetClientSize(int contextId, int dpW, int dpH);
+
+  private native long nPollReady(int contextId);
+
+  private native HardwareBuffer nGetHardwareBuffer(int contextId, int generation, int slot);
+
+  private native void nReleaseSlot(int contextId, int generation, int slot);
+
+  private native void nSwitchToOffscreen(int contextId);
+}