fix(webgpu): fixes per-frame memory growth (#140)

* fix(webgpu): release per-frame transients at their consumption point

Continuous WebGPU rendering leaked native heap render-proportionally: each frame
mints single-use wrappers (swapchain texture view, command encoder, render/compute
pass, command buffer) whose native Arc handle is dropped only by the V8 GC finalizer,
which a tight requestAnimationFrame loop starves. global.gc() does not flush the
finalizer tasks; backgrounding the loop drains them and the heap collapses.

Release each transient deterministically at the WebGPU-spec operation that consumes
it, with the GC finalizer kept as a backstop:

  render/compute pass -> pass.end()
  command encoder      -> encoder.finish()
  command buffer       -> queue.submit()
  swapchain view       -> the owning GPUCanvasContext.presentSurface()

The native handle lives in ArcHandle (unique_ptr + stateless custom deleter, new
ArcHandle.h, with a MutArcHandle variant for non-const C ABI releases). reset()
releases the Arc once and nulls the pointer; ~unique_ptr (run by the GC finalizer via
ObjectWrapperImpl's virtual destructor) is a no-op when already null, so exactly-once
release is a type invariant. Hand-written destructors and manual null-guards are gone;
C ABI call sites pass the raw pointer via .get(). The Rust crate is unchanged.

The swapchain view is the only transient tied to a context, so each GPUCanvasContext
tracks its own views (swapchainContext_ stamped in getCurrentTexture, registered in
GPUTexture.createView) and releases them in presentSurface(): per-context, so multiple
canvases in one isolate never drain each other's in-flight views.

JS destroy() calls are optional-chained, safe ahead of the native rebuild. Verified:
the C++ compiles and links via the Android NDK toolchain (Gradle assembleRelease).

* refactor(webgpu): own every native handle via ArcHandle (no hand-written dtors)

Convert the remaining 21 persistent WebGPU wrappers to hold their Rust Arc handle in
ArcHandle/MutArcHandle, the same primitive as the five transients. Each hand-written
destructor that called a raw canvas_native_webgpu_*_release is gone; the unique_ptr
member releases the handle once on destruction, so the GC path is unchanged in
behavior but the lifecycle now lives in the type. Accessors and C ABI call sites use
handle.get(); GPUImpl's null-guarded release and GPUCanvasContextImpl's release (which
keeps its raf_.reset() ordering) fold into the same model.

Behavior-preserving cleanup: these objects are not minted per frame and do not soak;
this removes duplicated release bookkeeping and makes all 26 WebGPU wrappers
consistent. Verified compiling via the Android NDK toolchain.

* fix(webgpu): free per-present read-back command encoder and buffer

presentSurface copies the swapchain texture into the read-back texture every frame
(toDataURL support) using a command encoder + command buffer, but never dropped
them, so they accumulated in wgpu-core's registry render-proportionally — a
native-heap leak. Drop the command buffer after submit and the encoder after the
copy, mirroring gpu_queue.rs::queue_submit.

Confirmed on a Moto G 2025: symbolized heapprofd named present_surface as the top
net-retained allocator; the drops remove it (~0.31 -> ~0.18 MB/s under continuous
render).

* fix(webgpu): release the swapchain GPUTexture wrapper at present

getCurrentTexture() returns a fresh per-frame GPUTexture wrapper holding an Arc
clone of the surface texture; its only non-deterministic free path was the GC
finalizer, which a tight render loop starves. Track the per-context swapchain
textures and drop their native handle at presentSurface() (the texture's point of
death) via a JS-exposed __releaseHandle on GPUTextureImpl that decrements the Arc.

__releaseHandle is distinct from destroy(): destroy() frees the GPU texture and must
never run on the swapchain texture; __releaseHandle only drops our wrapper's handle.
Completes deterministic per-frame release for the swapchain path.

* fix(webgpu): drop the swapchain texture and its clear_view at frame end

getCurrentTexture() registers a wgpu Texture (carrying an auto-created surface
clear_view) in wgpu-core's hub each frame. surface present()/discard() only release
the acquired-texture ref; the hub registry holds a second ref that must be dropped
explicitly. CanvasGPUTexture::drop only did this for the None (app-created) branch —
the Some (surface) branch was a no-op with its discard commented out, so the
per-frame swapchain texture and its clear image view leaked in the hub every frame.
Symbolized heapprofd named surface_get_current_texture (present.rs:220, ash
create_image_view) as the top remaining grower.

Drop the surface texture in the Some branch (and discard first if it was acquired
but never presented). The discard's error is logged rather than fatally aborted —
the original code used handle_error_fatal, which crashes the process from within
Drop and is almost certainly why this cleanup was commented out, trading a crash for
a leak.

Verified on a Moto G 2025: continuous-render foreground soak goes from ~0.18 MB/s to
+0.002 MB/s over 5 minutes (flat; matches the blank-app baseline). This was the last
of three native leaks (per-frame wrapper Arcs; read-back encoder/buffer; this).

* style(webgpu): tighten inline comments to repo conventions

Trim the explanatory comment blocks added with the leak fixes down to terse
one-liners matching the surrounding code. No behavior change.

Author: thejustinwalsh

crates/canvas-c/src/webgpu/gpu_canvas_context.rs

@@ -1495,9 +1495,13 @@ pub unsafe extern "C" fn canvas_native_webgpu_context_present_surface(
                             if error.is_none() {
                                 global.queue_submit(data.device.queue.queue.id, &[id]).ok();
                             }
+
+                            global.command_buffer_drop(id);
                         }
                         Err(_) => {}
                     }
+
+                    global.command_encoder_drop(encoder);
                 }
             }
         };

crates/canvas-c/src/webgpu/gpu_texture.rs

@@ -45,28 +45,21 @@ impl Drop for CanvasGPUTexture {
         }
         match self.surface_id {
             Some(surface_id) => {
+                let global = self.instance.global();
                 let has_surface_presented = self
                     .has_surface_presented
                     .load(std::sync::atomic::Ordering::SeqCst);
 
+                // acquired but never presented: hand the image back to the swapchain
                 if !has_surface_presented {
-                    let global = self.instance.global();
-
-                    /*
-                    match global.surface_texture_discard(surface_id) {
-                        Ok(_) => {
-                            self.surface_id = None;
-                        }
-                        Err(cause) => {
-                            handle_error_fatal(
-                                global,
-                                cause,
-                                "canvas_native_webgpu_texture_release",
-                            )
-                        },
+                    if let Err(cause) = global.surface_texture_discard(surface_id) {
+                        log::warn!("surface_texture_discard failed: {cause:?}");
                     }
-                    */
                 }
+
+                // drop the hub ref so the surface texture and its clear_view are freed
+                global.texture_drop(self.texture);
+                self.surface_id = None;
             }
             None => {
                 let context = self.instance.global();

packages/canvas/WebGPU/Constants.ts

@@ -39,3 +39,5 @@ export const native_ = Symbol('[[native]]');
 export const mapState_ = Symbol('[[mapState]]');
 export const contextPtr_ = Symbol('[[contextPtr]]');
 export const adapter_ = Symbol('[[adapter]]');
+// owning GPUCanvasContext stamped on the getCurrentTexture() texture (for release at present)
+export const swapchainContext_ = Symbol('[[swapchainContext]]');

packages/canvas/WebGPU/GPUCanvasContext.ts

@@ -1,7 +1,8 @@
 import { Helpers } from '../helpers';
-import { adapter_, contextPtr_, GPUTextureUsage, native_ } from './Constants';
+import { adapter_, contextPtr_, GPUTextureUsage, native_, swapchainContext_ } from './Constants';
 import type { GPUDevice } from './GPUDevice';
 import { GPUTexture } from './GPUTexture';
+import type { GPUTextureView } from './GPUTextureView';
 import type { GPUAdapter } from './GPUAdapter';
 import type { GPUCanvasAlphaMode, GPUCanvasPresentMode, GPUExtent3D, GPUTextureFormat } from './Types';
 import type { CanvasRenderingContext } from '../common';
@@ -18,6 +19,15 @@ export class GPUCanvasContext implements CanvasRenderingContext {
 	[native_] = null;
 	[contextPtr_] = null;
 
+	// per-frame swapchain views and textures, released at the next presentSurface()
+	private _swapchainViews: GPUTextureView[] = [];
+	private _swapchainTextures: GPUTexture[] = [];
+
+	/** @internal */
+	_registerSwapchainView(view: GPUTextureView) {
+		this._swapchainViews.push(view);
+	}
+
 	constructor(context: any, contextOptions: any = {}) {
 		let nativeContext = '0';
 		if (__ANDROID__) {
@@ -176,12 +186,39 @@ export class GPUCanvasContext implements CanvasRenderingContext {
 		const result = GPUTexture.fromNative(texture);
 		if (!result) {
 			console.error('GPUCanvasContext.getCurrentTexture: native texture wrapper contained no texture');
+		} else {
+			// mark as swapchain-owned and track for release at present
+			(result as any)[swapchainContext_] = this;
+			this._swapchainTextures.push(result);
 		}
 		return result;
 	}
 
 	presentSurface(_texture?: GPUTexture) {
 		this.native.presentSurface();
+		// release this frame's swapchain views and textures (their point of death)
+		const views = this._swapchainViews;
+		if (views.length > 0) {
+			this._swapchainViews = [];
+			for (let i = 0; i < views.length; i++) {
+				const view = views[i] as any;
+				view?.[native_]?.destroy?.();
+				if (view) {
+					view[native_] = null;
+				}
+			}
+		}
+		const texs = this._swapchainTextures;
+		if (texs.length > 0) {
+			this._swapchainTextures = [];
+			for (let i = 0; i < texs.length; i++) {
+				const tex = texs[i] as any;
+				tex?.[native_]?.__releaseHandle?.();
+				if (tex) {
+					tex[native_] = null;
+				}
+			}
+		}
 	}
 
 	getCapabilities(adapter: GPUAdapter): {

packages/canvas/WebGPU/GPUCommandEncoder.ts

@@ -190,7 +190,11 @@ export class GPUCommandEncoder {
 
 	finish(descriptor?: { label?: string }) {
 		const ret = this[native_].finish(descriptor);
-		return GPUCommandBuffer.fromNative(ret);
+		const buffer = GPUCommandBuffer.fromNative(ret);
+		// finish() consumes the encoder; release it now instead of waiting for GC
+		this[native_]?.destroy?.();
+		this[native_] = null;
+		return buffer;
 	}
 
 	insertDebugMarker(markerLabel: string) {

packages/canvas/WebGPU/GPUComputePassEncoder.ts

@@ -19,7 +19,10 @@ export class GPUComputePassEncoder {
 	}
 
 	end() {
-		this[native_].end();
+		// end() consumes the pass; release it now instead of waiting for GC
+		const n = this[native_];
+		n?.end();
+		n?.destroy?.();
 		this[native_] = null;
 	}
 

packages/canvas/WebGPU/GPUQueue.ts

@@ -129,6 +129,14 @@ export class GPUQueue {
 					return command[native_];
 				}),
 			);
+			// submit() consumes the command buffers; release them now instead of via GC
+			for (let i = 0; i < commands.length; i++) {
+				const command = commands[i] as any;
+				command?.[native_]?.destroy?.();
+				if (command) {
+					command[native_] = null;
+				}
+			}
 		}
 	}
 

packages/canvas/WebGPU/GPURenderPassEncoder.ts

@@ -45,7 +45,11 @@ export class GPURenderPassEncoder {
 	}
 
 	end() {
-		this[native_].end();
+		// end() consumes the pass; release it now instead of waiting for GC
+		const n = this[native_];
+		n?.end();
+		n?.destroy?.();
+		this[native_] = null;
 	}
 
 	endOcclusionQuery() {

packages/canvas/WebGPU/GPUTexture.ts

@@ -1,4 +1,4 @@
-import { native_ } from './Constants';
+import { native_, swapchainContext_ } from './Constants';
 import { GPUTextureView } from './GPUTextureView';
 import type { GPUTextureViewDescriptor } from './Interfaces';
 
@@ -49,6 +49,12 @@ export class GPUTexture {
 
 	createView(desc?: GPUTextureViewDescriptor) {
 		const view = this[native_].createView(desc);
-		return GPUTextureView.fromNative(view);
+		const ret = GPUTextureView.fromNative(view);
+		// swapchain-texture views die at present; register them with the owning context
+		const ctx = (this as any)[swapchainContext_];
+		if (ret && ctx) {
+			ctx._registerSwapchainView(ret);
+		}
+		return ret;
 	}
 }

packages/canvas/platforms/ios/src/cpp/webgpu/ArcHandle.h

@@ -0,0 +1,37 @@
+//
+// ArcHandle.h — RAII owner for the Rust Arc handles exposed across the canvas C ABI.
+//
+
+#ifndef CANVAS_WEBGPU_ARCHANDLE_H
+#define CANVAS_WEBGPU_ARCHANDLE_H
+
+#include <memory>
+
+// unique_ptr owner for a Rust Arc handle exposed across the C ABI. reset() runs the
+// matching ..._release once and nulls the pointer; the GC finalizer's later drop is
+// then a no-op. ArcHandle for const release fns, MutArcHandle for non-const.
+template <typename T, void (*Release)(const T *)>
+struct ArcDeleter {
+    void operator()(const T *ptr) const noexcept {
+        if (ptr != nullptr) {
+            Release(ptr);
+        }
+    }
+};
+
+template <typename T, void (*Release)(const T *)>
+using ArcHandle = std::unique_ptr<const T, ArcDeleter<T, Release>>;
+
+template <typename T, void (*Release)(T *)>
+struct MutArcDeleter {
+    void operator()(T *ptr) const noexcept {
+        if (ptr != nullptr) {
+            Release(ptr);
+        }
+    }
+};
+
+template <typename T, void (*Release)(T *)>
+using MutArcHandle = std::unique_ptr<T, MutArcDeleter<T, Release>>;
+
+#endif // CANVAS_WEBGPU_ARCHANDLE_H