@jbrowse/render-core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/hal/webgpuHal.js

@@ -1,9 +1,10 @@
 /// <reference types="@webgpu/types" />
-import { syncCanvasSize } from '../canvas2dUtils.js';
+import { getDpr, syncCanvasSize } from '../canvas2dUtils.js';
 import { canvasConfiguredBy, canvasContextError, noteCanvasConfigured, noteCanvasContext, } from '../canvasContext.js';
+import { createGpuSurfaceLostError } from '../gpuContextLostError.js';
 import { getGpuDevice } from '../gpuDevice.js';
-import { STANDARD_BLEND_STATE, createUniformOnlyBindGroup, createVertexBuffer, toGpuVertexFormat, } from '../webgpuUtils.js';
-import { getDeviceLayouts, getOrBuildPipeline } from './deviceGpuCache.js';
+import { createVertexBuffer } from '../webgpuUtils.js';
+import { bindGroupLayoutEntries, getOrBuildPipeline, getPassLayout, pipelineRecipe, } from './deviceGpuCache.js';
 import { GpuHalBase } from './gpuHalBase.js';
 class ShaderCompileError extends Error {
     constructor(passId, details) {
@@ -11,21 +12,15 @@ class ShaderCompileError extends Error {
         this.name = 'ShaderCompileError';
     }
 }
-// Maximum number of writeUniforms() calls per frame. Each call occupies one
-// aligned slot in the uniform ring buffer.
+// Each writeUniforms() call in a frame occupies one aligned slot in the uniform
+// ring, a GPU buffer and a CPU staging array per display, each slot sized by
+// the largest struct a registered pass declares. A frame is measured using 2-4
+// slots, so a ring starts at INITIAL_UNIFORM_SLOTS and doubles when a frame asks
+// for more: agent-docs/reference/ARCHITECTURAL_LIMITS.md §"The uniform ring".
 //
-// The ring is allocated eagerly at this many slots, as a GPU buffer AND a CPU
-// staging array, whether a renderer writes 4 slots or 1900 — so the cost is
-// per display and is the aligned uniform size that decides it, not the slot
-// count. A display whose uniform fits the 256-byte minimum alignment pays
-// 512 KB each side; alignments' 864-byte uniform aligns to 1024, so 2 MiB each
-// side. Trivial once, per-track at ten open alignments tracks.
-//
-// Exhausting it does not throw: the write is dropped and its draws render
-// against the previous batch's uniforms, which is wrong data rather than stale
-// data. If we ever hit the cap, switch to a dynamic-growth buffer (recreate
-// buffer + every region's bind group) rather than just bumping the constant
-// again.
+// Past MAX_UNIFORM_SLOTS a write is dropped and its draws render against
+// another batch's uniforms, without an error.
+const INITIAL_UNIFORM_SLOTS = 16;
 const MAX_UNIFORM_SLOTS = 2048;
 // Warn while there is still headroom, because the cap itself is not a place to
 // find out. A renderer's per-frame write count is rarely one number: alignments
@@ -35,58 +30,22 @@ const MAX_UNIFORM_SLOTS = 2048;
 // the "~50 writes/frame" this file used to claim, and nothing reported the
 // difference between 50 and 1900.
 const UNIFORM_SLOT_WARN_AT = MAX_UNIFORM_SLOTS / 2;
-function gpuBlendState(bs) {
-    // Max ignores its factors, but WebGPU still validates them and rejects
-    // anything but 'one' on both channels ("Destination blend factor ... is
-    // defined and not BlendFactor::One when blend operation is
-    // BlendOperation::Max"). Same blend as webgl2Hal's bare glBlendEquation(MAX).
-    const max = { srcFactor: 'one', dstFactor: 'one', operation: 'max' };
-    // Otherwise RGB uses the caller-supplied factors and alpha always accumulates
-    // through ONE / ONE_MINUS_SRC_ALPHA (matches webgl2Hal.applyBlendState).
-    return bs.op === 'max'
-        ? { color: max, alpha: max }
-        : {
-            color: { srcFactor: bs.srcFactor, dstFactor: bs.dstFactor },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
-        };
-}
-// Every pass reads per-instance data from a vertex buffer (no storage binding
-// at 0) because Slang-generated shaders cross-compile to GLSL ES, which has no
-// SSBOs. The two @group(0) layouts a pass is built against — uniform-only, and
-// uniform + texture + sampler — belong to the device, not to this HAL, and live
-// in `deviceGpuCache.ts` with the pipelines.
-async function buildPipeline(device, desc, layouts, sampleCount) {
-    const module = device.createShaderModule({ code: desc.wgslSource });
+// Every pass reads per-instance data from a vertex buffer, because Slang's
+// GLSL ES target has no SSBOs.
+async function buildPipeline(device, recipe, passId) {
+    const module = device.createShaderModule({ code: recipe.wgslSource });
     const info = await module.getCompilationInfo();
     const errors = info.messages.filter(m => m.type === 'error');
     if (errors.length > 0) {
         const details = errors
             .map(m => `line ${m.lineNum}: ${m.message}`)
             .join('; ');
-        throw new ShaderCompileError(desc.id, details);
-    }
-    const blend = desc.blend
-        ? desc.blendState
-            ? gpuBlendState(desc.blendState)
-            : STANDARD_BLEND_STATE
-        : undefined;
-    // Every pass feeds @location(N) inputs from a bound vertex buffer.
-    const vertexBuffers = [
-        {
-            arrayStride: desc.instanceStride,
-            stepMode: 'instance',
-            attributes: desc.vertexAttributes.map((attr, i) => ({
-                shaderLocation: i,
-                offset: attr.offsetBytes,
-                format: toGpuVertexFormat(attr),
-            })),
-        },
-    ];
+        throw new ShaderCompileError(passId, details);
+    }
+    const { blend } = recipe;
     return device.createRenderPipelineAsync({
-        layout: desc.textures?.length
-            ? layouts.texturedPipelineLayout
-            : layouts.uniformOnlyPipelineLayout,
-        vertex: { module, entryPoint: 'vs_main', buffers: vertexBuffers },
+        layout: getPassLayout(device, recipe.bindGroupLayout).pipelineLayout,
+        vertex: { module, entryPoint: 'vs_main', buffers: [recipe.vertexBuffer] },
         fragment: {
             module,
             entryPoint: 'fs_main',
@@ -97,17 +56,18 @@ async function buildPipeline(device, desc, layouts, sampleCount) {
                 },
             ],
         },
-        primitive: { topology: desc.topology ?? 'triangle-list' },
-        multisample: sampleCount === 1 ? undefined : { count: sampleCount },
+        primitive: { topology: recipe.topology },
+        multisample: recipe.sampleCount === 1 ? undefined : { count: recipe.sampleCount },
     });
 }
-// Resolve every declared pass to its pipeline, taking the device-wide cache's
-// answer wherever another display of this type already built one. Still every
-// pass up front rather than on first draw — the WebGL2 side compiles lazily
-// (`getPass`) and this side does not; see ARCHITECTURAL_LIMITS.md §"Every
-// WebGPU display resolves its whole pass list before it can paint".
+// Every declared pass up front, unlike WebGL2's first-draw link; see
+// ARCHITECTURAL_LIMITS.md §"Every WebGPU display resolves its whole pass list
+// before it can paint". Each pass compiles as soon as its own WGSL arrives.
 async function resolvePipelines(device, descriptors, sampleCount) {
-    const built = await Promise.all(descriptors.map(desc => getOrBuildPipeline(device, desc, sampleCount, (layouts, count) => buildPipeline(device, desc, layouts, count))));
+    const built = await Promise.all(descriptors.map(async (desc) => {
+        const { WGSL_SOURCE } = await desc.source.wgsl();
+        return getOrBuildPipeline(device, pipelineRecipe(desc, WGSL_SOURCE, sampleCount), recipe => buildPipeline(device, recipe, desc.id));
+    }));
     return new Map(descriptors.map((desc, i) => [desc.id, built[i]]));
 }
 // Behavioral parity with WebGL2Hal is enforced by tests, not by this file:
@@ -124,30 +84,30 @@ export class WebGPUHal extends GpuHalBase {
     canvas;
     context;
     pipelines;
+    // Each pass's textures, by the sampler that reads each.
     passTextures = new Map();
-    // One bind group per textured pass, built lazily by `getBindGroup` and
-    // dropped when `uploadTexture` swaps that pass's texture. Uniform-only passes
-    // are not stored here — they all share `uniformOnlyBindGroup`.
+    // Every pass's bind group, by the pass drawn. A pass that binds no texture
+    // has one from construction, shared with each pass over the same layout; a
+    // textured pass gets its own when its texture arrives, dropped when
+    // `uploadTexture` replaces the texture. The layouts are the device's, shared
+    // with every display on it; the groups are this HAL's, since they name its
+    // uniform ring buffer.
     passBindGroups = new Map();
-    // The device's layouts, not this HAL's — shared with every other display on
-    // the same device. The bind GROUPS above stay per-HAL: they reference this
-    // HAL's uniform ring buffer.
-    layouts;
     // Uniform ring buffer: holds up to MAX_UNIFORM_SLOTS sets of uniforms so
     // that all draw calls in a frame can reference different uniform data via
     // dynamic offsets, enabling a single command encoder + submit per frame.
     alignedUniformSize;
     uniformRingBuffer;
     uniformStaging;
+    uniformSlots = INITIAL_UNIFORM_SLOTS;
     uniformSlot = 0;
+    // Rings this frame outgrew, each with the staged bytes its encoded draws
+    // read: written at submit, released after it.
+    outgrownRings = [];
     // Once per HAL, not once per frame: at 60fps a per-frame warning is a
     // console the developer stops reading, and the fact is about the renderer
     // rather than about this frame.
     warnedUniformSlots = false;
-    // Shared bind group for every uniform-only pass — only references
-    // `uniformRingBuffer` (via dynamic offset at draw time), so one instance
-    // serves all passes/regions instead of allocating a fresh one per upload.
-    uniformOnlyBindGroup;
     // Samples per pixel this display renders at, stated by whoever built it (see
     // `RenderingBackendOptions.sampleCount`). Every render-pass, texture and
     // pipeline decision below reads it, so the two shapes cannot mismatch — and
@@ -175,7 +135,7 @@ export class WebGPUHal extends GpuHalBase {
      * selection spanning two sections re-uploads `OVERLAY_REGION` once per
      * section, inside the block loop.
      *
-     * Deferring is what makes mid-frame replacement legal instead of merely
+     * Deferring the destroy makes mid-frame replacement legal instead of merely
      * warned about; synteny's `ensureUploaded` has always deleted a pass mid-frame
      * that the open pass never referenced, and that case was never the bug.
      */
@@ -196,26 +156,93 @@ export class WebGPUHal extends GpuHalBase {
     // than once per frame, and a reconfigure that failed is not attempted again.
     warnedSwapChainLoss = false;
     swapChainUnrecoverable = false;
-    constructor(device, canvas, context, descriptors, uniformByteSize, sampleCount, pipelines, layouts) {
+    reportedSurfaceFailure = false;
+    constructor(device, canvas, context, descriptors, sampleCount, pipelines) {
         super(descriptors, 'WebGPUHal');
         this.device = device;
         this.canvas = canvas;
         this.context = context;
         this.pipelines = pipelines;
-        this.layouts = layouts;
         this.sampleCount = sampleCount;
         // Align uniform slots to device requirements for dynamic offsets
         const alignment = device.limits.minUniformBufferOffsetAlignment;
-        this.alignedUniformSize = Math.ceil(uniformByteSize / alignment) * alignment;
-        const ringSize = MAX_UNIFORM_SLOTS * this.alignedUniformSize;
-        this.uniformRingBuffer = device.createBuffer({
-            size: ringSize,
-            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-        });
+        this.alignedUniformSize =
+            Math.ceil(this.uniformByteSize / alignment) * alignment;
+        const ringSize = this.uniformSlots * this.alignedUniformSize;
+        this.uniformRingBuffer = this.createRing(ringSize);
         this.uniformStaging = new Uint8Array(ringSize);
-        this.uniformOnlyBindGroup = createUniformOnlyBindGroup(device, layouts.uniformOnlyBindGroupLayout, this.uniformRingBuffer, this.alignedUniformSize);
+        this.bindUntexturedPasses();
         this.configureContext();
     }
+    createRing(size) {
+        return this.device.createBuffer({
+            size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+    // Every pass's bind group names the ring buffer, so a new ring rebinds them:
+    // an untextured pass here, a textured one on its next draw (`bindTexture`).
+    bindUntexturedPasses() {
+        const byLayout = new Map();
+        for (const desc of this.descriptors.values()) {
+            if (desc.bindings.some(b => b.kind === 'texture')) {
+                this.passBindGroups.delete(desc.id);
+                continue;
+            }
+            const layout = this.bindGroupLayoutOf(desc.bindings);
+            let group = byLayout.get(layout);
+            if (!group) {
+                group = this.createBindGroup(desc.bindings, layout);
+                byLayout.set(layout, group);
+            }
+            this.passBindGroups.set(desc.id, group);
+        }
+    }
+    // Doubles the ring mid-frame. The draws already encoded bind the old buffer,
+    // so it takes the slots staged so far at submit and is released after.
+    growRing() {
+        const bytes = this.uniformSlot * this.alignedUniformSize;
+        this.outgrownRings.push({ buffer: this.uniformRingBuffer, bytes });
+        this.destroyWhenIdle(this.uniformRingBuffer);
+        this.uniformSlots = Math.min(this.uniformSlots * 2, MAX_UNIFORM_SLOTS);
+        const size = this.uniformSlots * this.alignedUniformSize;
+        this.uniformRingBuffer = this.createRing(size);
+        const staging = new Uint8Array(size);
+        staging.set(this.uniformStaging.subarray(0, bytes));
+        this.uniformStaging = staging;
+        this.bindUntexturedPasses();
+    }
+    bindGroupLayoutOf(bindings) {
+        return getPassLayout(this.device, bindGroupLayoutEntries(bindings))
+            .bindGroupLayout;
+    }
+    // One entry per binding in the pass's table, the same table its layout was
+    // built from, so the group cannot name a binding the layout lacks.
+    createBindGroup(bindings, layout, textures) {
+        return this.device.createBindGroup({
+            layout,
+            entries: bindings.map(b => ({
+                binding: b.index,
+                resource: this.bindingResource(b, textures?.get(b.name)),
+            })),
+        });
+    }
+    bindingResource(b, texture) {
+        if (b.kind === 'uniform') {
+            return {
+                buffer: this.uniformRingBuffer,
+                offset: 0,
+                size: this.alignedUniformSize,
+            };
+        }
+        if (texture && b.kind === 'texture') {
+            return texture.texture.createView();
+        }
+        if (texture && b.kind === 'sampler') {
+            return texture.sampler;
+        }
+        throw new Error(`[WebGPUHal] nothing to bind for the ${b.kind} '${b.name}' at binding ${b.index}`);
+    }
     limits() {
         const { maxBufferSize, maxTextureDimension2D } = this.device.limits;
         return {
@@ -245,17 +272,16 @@ export class WebGPUHal extends GpuHalBase {
         });
         noteCanvasConfigured(this.canvas, this);
     }
-    static async create(canvas, descriptors, uniformByteSize, sampleCount) {
+    static async create(canvas, descriptors, sampleCount) {
         const device = await getGpuDevice();
         if (!device) {
             return null;
         }
         // Resolve pipelines BEFORE acquiring the canvas's webgpu context. A canvas's
-        // context type is permanent once acquired, so if shader compilation throws
-        // here the canvas stays pristine and createGpuHal's WebGL2 fallback can
-        // still claim it — otherwise a partial WebGPU init would drop us all the way
-        // to Canvas2D on a WebGL2-capable machine.
-        const layouts = getDeviceLayouts(device);
+        // context type is permanent once acquired, so if a shader fails to load or
+        // compile here the canvas stays pristine and createGpuHal's WebGL2 fallback
+        // can still claim it — otherwise a partial WebGPU init would drop us all the
+        // way to Canvas2D on a WebGL2-capable machine.
         const pipelines = await resolvePipelines(device, descriptors, sampleCount);
         const context = canvas.getContext('webgpu');
         if (!context) {
@@ -266,9 +292,14 @@ export class WebGPUHal extends GpuHalBase {
             throw canvasContextError(canvas, 'webgpu');
         }
         noteCanvasContext(canvas, 'webgpu');
-        return new WebGPUHal(device, canvas, context, descriptors, uniformByteSize, sampleCount, pipelines, layouts);
+        return new WebGPUHal(device, canvas, context, descriptors, sampleCount, pipelines);
     }
     resize(width, height) {
+        // A render autorun can fire between `dispose` and the model dropping its
+        // backend reference, and nothing destroys what a disposed HAL allocates.
+        if (this.disposed) {
+            return { x: getDpr(), y: getDpr() };
+        }
         const { changed, scale } = syncCanvasSize(this.canvas, width, height);
         // `!this.msaaTexture` covers the first frame and a rebuild that bailed. At
         // sampleCount 1 there is never a texture, so without the count in the
@@ -279,6 +310,11 @@ export class WebGPUHal extends GpuHalBase {
         }
         return scale;
     }
+    releaseRenderTargets() {
+        if (!this.disposed) {
+            this.recreateMsaaTexture(0, 0);
+        }
+    }
     recreateMsaaTexture(width, height) {
         this.msaaTexture?.destroy();
         this.msaaTexture = null;
@@ -309,50 +345,32 @@ export class WebGPUHal extends GpuHalBase {
      * (and a dropped draw) the moment one side samples a texture.
      *
      * Nothing in a bind group varies per region either: it references the
-     * HAL-wide uniform ring buffer plus the pass's own texture/sampler. So
-     * uniform-only passes all share `uniformOnlyBindGroup`, and a textured pass
-     * gets exactly one, cached until `uploadTexture` replaces its texture.
-     * Returns undefined when a pass needs a texture that hasn't arrived yet;
-     * drawPass skips those.
+     * HAL-wide uniform ring buffer plus the pass's own texture/sampler. Returns
+     * undefined when a pass needs a texture that hasn't arrived yet; drawPass
+     * skips those.
      */
     getBindGroup(passId) {
-        const tb = this.descriptors.get(passId)?.textures?.[0];
-        if (tb) {
-            let bindGroup = this.passBindGroups.get(passId);
-            if (!bindGroup) {
-                const texState = this.passTextures.get(passId);
-                if (texState) {
-                    bindGroup = this.device.createBindGroup({
-                        layout: this.layouts.texturedBindGroupLayout,
-                        entries: [
-                            {
-                                binding: 1,
-                                resource: {
-                                    buffer: this.uniformRingBuffer,
-                                    offset: 0,
-                                    size: this.alignedUniformSize,
-                                },
-                            },
-                            {
-                                binding: tb.textureBinding,
-                                resource: texState.texture.createView(),
-                            },
-                            { binding: tb.samplerBinding, resource: texState.sampler },
-                        ],
-                    });
-                    this.passBindGroups.set(passId, bindGroup);
-                }
-            }
-            return bindGroup;
+        return this.passBindGroups.get(passId) ?? this.bindTexture(passId);
+    }
+    // Built once every texture the pass samples has arrived.
+    bindTexture(passId) {
+        const textures = this.passTextures.get(passId);
+        const desc = this.descriptors.get(passId);
+        if (!textures ||
+            !desc ||
+            desc.bindings.some(b => b.kind === 'texture' && !textures.has(b.name))) {
+            return undefined;
         }
-        return this.uniformOnlyBindGroup;
+        const group = this.createBindGroup(desc.bindings, this.bindGroupLayoutOf(desc.bindings), textures);
+        this.passBindGroups.set(passId, group);
+        return group;
     }
     /**
      * The one place a GPU resource this HAL owns is released — see
      * {@link pendingDestroy} for why the frame decides when.
      *
      * Every buffer release routes here through the `RegionRegistry` destroy hook,
-     * so `uploadBuffer`, `deleteBuffer`, `deleteRegion`, `pruneRegions` and
+     * so `uploadBuffer`, `deleteBuffer`, `deleteRegion` and
      * `dispose` are all covered without any of them knowing a frame is open.
      */
     destroyWhenIdle(resource) {
@@ -370,29 +388,42 @@ export class WebGPUHal extends GpuHalBase {
         this.pendingDestroy.length = 0;
     }
     createTexture(passId, binding, data, width, height) {
-        const existing = this.passTextures.get(passId);
+        let byName = this.passTextures.get(passId);
+        if (!byName) {
+            byName = new Map();
+            this.passTextures.set(passId, byName);
+        }
+        const existing = byName.get(binding.name);
         if (existing) {
-            // Same hazard as a buffer, one step further from a live caller: every
-            // `uploadTexture` in tree is a colour ramp written from an upload autorun
-            // (hic's `LinearHicDisplay/model.ts`, variants' `LDDisplay/shared.ts`),
-            // which never runs inside a frame. Routing it through the same deferral
-            // costs nothing and keeps "replaced mid-frame" from being a hazard again
-            // the first time a renderer builds a texture from render state.
+            // Same hazard as a buffer, and no longer a hypothetical one: every
+            // `uploadTexture` in tree is a colour ramp, and since the ramp became a
+            // `defineMark` `texture` they are all written by `GpuMarkBackend`'s
+            // `bindRamp` from inside `drawRegion` — mid-frame, between an encoded
+            // draw and its submit. The deferral is what makes replacing one there
+            // safe.
             this.destroyWhenIdle(existing.texture);
         }
+        const bytes = data instanceof Uint8Array;
         const texture = this.device.createTexture({
             size: [width, height],
             format: 'rgba8unorm',
-            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+            usage: GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_DST |
+                (bytes ? 0 : GPUTextureUsage.RENDER_ATTACHMENT),
         });
-        this.device.queue.writeTexture({ texture }, data, { bytesPerRow: width * 4 }, { width, height });
+        if (bytes) {
+            this.device.queue.writeTexture({ texture }, data, { bytesPerRow: width * 4 }, { width, height });
+        }
+        else {
+            this.device.queue.copyExternalImageToTexture({ source: data }, { texture, premultipliedAlpha: true }, { width, height });
+        }
         const sampler = this.device.createSampler({
             magFilter: binding.filter,
             minFilter: binding.filter,
             addressModeU: 'clamp-to-edge',
             addressModeV: 'clamp-to-edge',
         });
-        this.passTextures.set(passId, { texture, sampler });
+        byName.set(binding.name, { texture, sampler });
         // Drop the cached bind group so the next draw rebuilds it against the new
         // texture (and so a pass drawn before its first texture arrived stops
         // being skipped).
@@ -401,14 +432,17 @@ export class WebGPUHal extends GpuHalBase {
     writeUniforms(data) {
         if (this.currentEncoder) {
             // Inside a frame: stage data at the current slot for batched upload
-            if (this.uniformSlot >= MAX_UNIFORM_SLOTS) {
+            if (this.uniformSlot >= this.uniformSlots &&
+                this.uniformSlots < MAX_UNIFORM_SLOTS) {
+                this.growRing();
+            }
+            if (this.uniformSlot >= this.uniformSlots) {
                 console.error(`[WebGPUHal] uniform ring buffer exhausted at ${MAX_UNIFORM_SLOTS} ` +
                     `writeUniforms calls in one frame — this write is dropped, so the ` +
                     `paired draw renders with the previous batch's uniforms (wrong ` +
                     `data, not last-frame-stale). This indicates a renderer doing far ` +
                     `more per-frame uniform writes than expected; investigate the call ` +
-                    `site before raising the cap (and consider switching to a ` +
-                    `dynamic-growth ring buffer).`);
+                    `site before raising the cap.`);
                 return;
             }
             const offset = this.uniformSlot * this.alignedUniformSize;
@@ -471,6 +505,21 @@ export class WebGPUHal extends GpuHalBase {
             }
         }
     }
+    /**
+     * Once per HAL, not once per frame: the refusal holds for every frame at this
+     * canvas size, and dotplot and synteny keep their canvas mounted through a
+     * `renderError`, so a per-frame report there never stops.
+     *
+     * Not terminal — a refusal tracks the canvas dimensions, so a resize can clear
+     * it. `swapChainUnrecoverable` stays for the case it was written for.
+     */
+    reportSurfaceFailure(message) {
+        if (this.reportedSurfaceFailure) {
+            return;
+        }
+        this.reportedSurfaceFailure = true;
+        this.oom.reportClassified(createGpuSurfaceLostError(message));
+    }
     beginFrame(clearR, clearG, clearB, clearA = 1) {
         // Skip the frame entirely rather than encode one that cannot be valid.
         // Zero-size canvas: nothing to draw. Missing MSAA target while MSAA is
@@ -486,10 +535,23 @@ export class WebGPUHal extends GpuHalBase {
             (this.sampleCount > 1 && !this.msaaView)) {
             return;
         }
-        // Before the error scopes, so a failed acquisition needs no unwinding: the
-        // scopes stay pushed iff an encoder is created, which is what endFrame's
-        // early-return on !currentEncoder is paired with.
+        // A driver can refuse the canvas image without throwing — Dawn returns an
+        // error texture and an error view, and the frame encodes against it — so the
+        // acquisition needs a scope, and its own rather than the frame's: those stay
+        // pushed iff an encoder is created, and one left on the device's stack
+        // swallows every later frame's errors. Popped before the guard below, so
+        // every path balances. Awaiting the pop here would suspend across a
+        // GPU-process round trip and destroy the canvas texture mid-frame.
+        this.device.pushErrorScope('validation');
         const textureView = this.acquireTextureView();
+        void this.device
+            .popErrorScope()
+            .then(err => {
+            if (err) {
+                this.reportSurfaceFailure(err.message);
+            }
+        })
+            .catch(() => { });
         if (!textureView) {
             return;
         }
@@ -526,7 +588,7 @@ export class WebGPUHal extends GpuHalBase {
             ],
         });
     }
-    drawPass(passId, regionKey, bufferPassId) {
+    drawPass(passId, regionKey, bufferPassId, verticesPerInstance) {
         if (!this.currentPass) {
             return;
         }
@@ -561,7 +623,7 @@ export class WebGPUHal extends GpuHalBase {
         this.currentPass.setPipeline(pipeline);
         this.currentPass.setBindGroup(0, bindGroup, [dynamicOffset]);
         this.currentPass.setVertexBuffer(0, regionBuf.dataBuffer);
-        this.currentPass.draw(desc.verticesPerInstance, regionBuf.count);
+        this.currentPass.draw(verticesPerInstance ?? desc.verticesPerInstance, regionBuf.count);
     }
     /**
      * Close the frame's state whether the submit landed or threw.
@@ -594,6 +656,7 @@ export class WebGPUHal extends GpuHalBase {
         this.currentPass = null;
         this.currentEncoder = null;
         this.currentTextureView = null;
+        this.outgrownRings.length = 0;
         this.drainPendingDestroy();
     }
     endFrame() {
@@ -606,6 +669,9 @@ export class WebGPUHal extends GpuHalBase {
             if (this.currentPass) {
                 this.currentPass.end();
             }
+            for (const ring of this.outgrownRings) {
+                this.device.queue.writeBuffer(ring.buffer, 0, this.uniformStaging, 0, ring.bytes);
+            }
             if (slotAtSubmit > 0) {
                 const uploadSize = slotAtSubmit * this.alignedUniformSize;
                 this.device.queue.writeBuffer(this.uniformRingBuffer, 0, this.uniformStaging, 0, uploadSize);
@@ -704,8 +770,10 @@ export class WebGPUHal extends GpuHalBase {
         }
         this.regions.deleteAll();
         this.uniformRingBuffer.destroy();
-        for (const ts of this.passTextures.values()) {
-            ts.texture.destroy();
+        for (const byName of this.passTextures.values()) {
+            for (const ts of byName.values()) {
+                ts.texture.destroy();
+            }
         }
         this.passTextures.clear();
         this.passBindGroups.clear();

package/esm/installUpload.d.ts

@@ -15,6 +15,16 @@ export interface CellTarget<K, Encoded> {
     upload(key: K, data: Encoded): void;
     release(key: K): void;
 }
+/**
+ * The other half of what this installer needs off a backend, and the half every
+ * backend gets for free by extending `GpuRenderingBackendBase` or
+ * `Canvas2DRenderingBackendBase`. Named apart from `CellTarget` because it has
+ * nothing to do with cells: the installer passes it straight through as the
+ * lifecycle's `releaseTargets` callback.
+ */
+export interface TargetRelease {
+    releaseOffscreenTargets(): void;
+}
 /**
  * What the backend takes, read off the backend, which is the direction the
  * overloads have to check in: the payload reaching `upload` must be assignable
@@ -74,18 +84,21 @@ export declare function oneCell<K, T>(key: K, value: T | undefined | null): Read
  *
  * **Calling again only swaps the backend.** Displays wire this from
  * `startRenderingBackend`, which fires again on every context-loss recovery;
- * the diff and the encode cache live in the setup thunk and survive it.
+ * the diff and the encode memo live in the setup thunk and survive it.
+ *
+ * `encode` runs through `createEncodeMemo`. A display that needs the encoded
+ * map itself holds that memo in a `.views` closure and hands identity cells.
  *
  * @see installUpload.test.ts for the upload, encode and release counts.
  * @see ADR-078 for why this is one autorun and a diff.
  */
-export declare function installUpload<K, Data extends EncodedOf<B>, B extends CellTarget<K, unknown>>(self: LifecycleHost, backend: B, spec: {
+export declare function installUpload<K, Data extends EncodedOf<B>, B extends CellTarget<K, unknown> & TargetRelease>(self: LifecycleHost, backend: B, spec: {
     cells: () => ReadonlyMap<K, Data>;
     render: (backend: B, encoded: ReadonlyMap<K, Data>) => boolean;
     encode?: never;
     inputs?: never;
 }): void;
-export declare function installUpload<K, Data, Props, B extends CellTarget<K, unknown>>(self: LifecycleHost, backend: B, spec: UploadSpec<K, Data, Props, EncodedOf<B>, B> & {
+export declare function installUpload<K, Data, Props, B extends CellTarget<K, unknown> & TargetRelease>(self: LifecycleHost, backend: B, spec: UploadSpec<K, Data, Props, EncodedOf<B>, B> & {
     encode: (data: Data, props: Props, key: K) => EncodedOf<B>;
 }): void;
 export {};