@flighthq/render-wgpu 0.5.1-next.1069.554a2ac → 0.5.1-next.1201.9b49dee

package/src/{wgpuBackground.test.ts → wgpuFrame.test.ts}

@@ -1,14 +1,7 @@
-import {
-  beginWgpuFrame,
-  renderWgpuBackground,
-  retireWgpuBuffer,
-  retireWgpuTexture,
-  submitWgpuRenderPass,
-  withWgpuFrameBorrow,
-} from './wgpuBackground';
+import { beginWgpuFrame, retireWgpuBuffer, retireWgpuTexture, submitWgpuFrame, withWgpuFrameBorrow } from './wgpuFrame';
 import { createWgpuPipeline } from './wgpuPipeline';
 import { createWgpuOffscreenRenderState, getWgpuRenderStateRuntime } from './wgpuRenderState';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
 
 beforeAll(() => installWgpuMock());
 
@@ -22,15 +15,6 @@ describe('beginWgpuFrame', () => {
   });
 });
 
-describe('renderWgpuBackground', () => {
-  it('opens the presentation pass on the current surface', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    expect(getWgpuRenderStateRuntime(state).renderPass).not.toBeNull();
-    submitWgpuRenderPass(state);
-  });
-});
-
 describe('retireWgpuBuffer', () => {
   it('adds the buffer to the post-submit destruction ledger', async () => {
     const state = await createWgpuRenderStateForTest();
@@ -49,13 +33,43 @@ describe('retireWgpuTexture', () => {
   });
 });
 
-describe('submitWgpuRenderPass', () => {
+describe('submitWgpuFrame', () => {
   it('submits and closes the active frame', async () => {
     const state = await createWgpuRenderStateForTest();
     beginWgpuFrame(state);
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
     expect(getWgpuRenderStateRuntime(state).commandEncoder).toBeNull();
   });
+
+  it('closes a pass the caller left open rather than carrying its encoder into the next frame', async () => {
+    const state = await createWgpuRenderStateForTest();
+    beginWgpuFrame(state);
+    beginWgpuScreenRenderPassForTest(state);
+    expect(getWgpuRenderStateRuntime(state).renderPass).not.toBeNull();
+
+    submitWgpuFrame(state);
+
+    const runtime = getWgpuRenderStateRuntime(state);
+    expect(runtime.renderPass).toBeNull();
+    expect(runtime.passStack).toEqual([]);
+    expect(runtime.currentRenderTarget).toBeNull();
+    expect(runtime.renderTargetViewport).toBeNull();
+  });
+  // A frame that only drew into texture targets has no screen to resolve or capture. Skipping that work
+  // is not an optimization: the capture texture still holds the LAST VISIBLE frame, so encoding a copy
+  // here would overwrite the readback buffer with a stale picture that a caller would read as current.
+  it('resolves and captures nothing when the frame never touched a screen target', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    beginWgpuFrame(state);
+    const encoder = runtime.commandEncoder!;
+    const copyToBuffer = vi.spyOn(encoder, 'copyTextureToBuffer');
+
+    expect(runtime.frameScreenTarget).toBeNull();
+    submitWgpuFrame(state);
+
+    expect(copyToBuffer).not.toHaveBeenCalled();
+  });
 });
 
 describe('withWgpuFrameBorrow', () => {

package/src/wgpuFullscreenPass.test.ts

@@ -1,12 +1,12 @@
-import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
+import { submitWgpuFrame } from './wgpuFrame';
 import {
   createWgpuFullscreenPipeline,
   destroyWgpuFullscreenPipeline,
   drawWgpuFullscreenPass,
   initializeWgpuFullscreenPipeline,
 } from './wgpuFullscreenPass';
-import { createWgpuRenderTarget } from './wgpuRenderTarget';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { createWgpuTextureRenderTarget } from './wgpuTextureRenderTarget';
 
 beforeAll(() => {
   installWgpuMock();
@@ -49,17 +49,17 @@ describe('destroyWgpuFullscreenPipeline', () => {
 describe('drawWgpuFullscreenPass', () => {
   it('does not throw when render pass is open and no uniforms', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const pipeline = createWgpuFullscreenPipeline(state, SIMPLE_FRAGMENT_WGSL, 1);
-    const target = createWgpuRenderTarget(state, 64, 64);
+    const target = createWgpuTextureRenderTarget(state, 64, 64);
     expect(() => drawWgpuFullscreenPass(state, pipeline, [target], null)).not.toThrow();
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 
   it('is a no-op when render pass is not open', async () => {
     const state = await createWgpuRenderStateForTest();
     const pipeline = createWgpuFullscreenPipeline(state, SIMPLE_FRAGMENT_WGSL, 1);
-    const target = createWgpuRenderTarget(state, 64, 64);
+    const target = createWgpuTextureRenderTarget(state, 64, 64);
     expect(() => drawWgpuFullscreenPass(state, pipeline, [target], null)).not.toThrow();
   });
 });

package/src/wgpuHost.test.ts

@@ -1,5 +1,5 @@
 import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
-import type { Entity, WgpuHostAcquisition, WgpuHostBackend } from '@flighthq/types/contract';
+import type { Entity, WgpuHostAcquisition, HostWgpuProvider } from '@flighthq/types/contract';
 import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
 
 import {
@@ -12,23 +12,25 @@ import {
 } from './wgpuHost';
 import { createEmptyWgpuRegistries, createWgpuPipeline } from './wgpuPipeline';
 import {
+  createWgpuAcquisition,
   createWgpuRenderState,
-  createWgpuRenderStateFromCanvasElement,
   destroyWgpuRenderState,
+  releaseWgpuAcquisition,
 } from './wgpuRenderState';
 import { installWgpuMock } from './wgpuTestHelper';
 
-function fakeBackend(): WgpuHostBackend {
+function fakeBackend(): HostWgpuProvider {
   return entityBackend({
     acquire: vi.fn(),
+    attachSurface: vi.fn(() => null),
     isSupported: vi.fn(() => true),
     release: vi.fn(),
   });
 }
 
-function entityBackend(fields: Omit<WgpuHostBackend, keyof Entity>): WgpuHostBackend {
+function entityBackend(fields: Omit<HostWgpuProvider, keyof Entity>): HostWgpuProvider {
   return (() => {
-    const out = allocateEntity<WgpuHostBackend>();
+    const out = allocateEntity<HostWgpuProvider>();
     Object.assign(out, fields);
     return finishEntity(out);
   })();
@@ -126,72 +128,43 @@ describe('setWgpuHostBackend', () => {
   it('routes acquisition and release through the same selected backend', async () => {
     const web = createWebWgpuHostBackend();
     const acquired = await web.acquire(document.createElement('canvas'), {});
-    // Flight-owned: the state acquired these, so destroying it releases them. The caller-owned case is the
-    // opposite assertion and lives in its own test below.
     const acquisition = allocateEntity<WgpuHostAcquisition>();
     Object.assign(acquisition, acquired);
-    acquisition.ownership = 'flight' as const;
+    acquisition.ownership = 'caller' as const;
     const backend = entityBackend({
       acquire: vi.fn(async () => acquisition),
+      attachSurface: vi.fn(() => null),
       isSupported: vi.fn(() => true),
       release: vi.fn(),
     });
     const canvas = document.createElement('canvas');
     setWgpuHostBackend(backend);
 
-    const state = await createWgpuRenderStateFromCanvasElement(canvas, _pipeline);
-    expect(backend.acquire).toHaveBeenCalledWith(canvas, { format: undefined, powerPreference: undefined });
-    expect(state.context).toBe(acquisition.context);
-    expect(state.device).toBe(acquisition.device);
-    expect(state.format).toBe(acquisition.format);
-    destroyWgpuRenderState(state);
-    expect(backend.release).toHaveBeenCalledOnce();
-    expect(backend.release).toHaveBeenCalledWith(acquisition);
-
-    web.release(acquired);
-  });
-
-  it('releases flight-owned handles through the selected backend when initialization fails', async () => {
-    const web = createWebWgpuHostBackend();
-    const acquired = await web.acquire(document.createElement('canvas'), {});
-    const acquisition = allocateEntity<WgpuHostAcquisition>();
-    Object.assign(acquisition, acquired);
-    acquisition.ownership = 'flight' as const;
-    const configure = vi.spyOn(acquisition.context, 'configure').mockImplementationOnce(() => {
-      throw new Error('configure failed');
-    });
-    const backend = entityBackend({
-      acquire: vi.fn(async () => acquisition),
-      isSupported: vi.fn(() => true),
-      release: vi.fn(),
-    });
-    setWgpuHostBackend(backend);
+    const routed = await createWgpuAcquisition(canvas);
+    expect(backend.acquire).toHaveBeenCalledWith(canvas, {});
+    expect(routed?.device).toBe(acquisition.device);
+    expect(routed?.format).toBe(acquisition.format);
 
-    expect(() => createWgpuRenderState(acquisition, _pipeline)).toThrow('configure failed');
+    releaseWgpuAcquisition(acquisition);
     expect(backend.release).toHaveBeenCalledOnce();
     expect(backend.release).toHaveBeenCalledWith(acquisition);
 
-    configure.mockRestore();
     web.release(acquired);
   });
 
-  // ★ O2. The previous shape of this test used a CALLER-owned acquisition and asserted release WAS called,
-  // with a `vi.fn()` release that could not destroy anything — so it passed whether or not ownership was
-  // honoured. Flight now refuses to release borrowed handles even while unwinding a failure, and the
-  // backend here is deliberately one that would destroy them if asked.
-  it('O2: never releases caller-owned handles when initialization fails, whatever the backend does', async () => {
+  // ★ A RENDER STATE OWNS NO HOST HANDLES AT ALL. It used to be built from an acquisition and had to
+  // decide, on every path including a failed construction, whether to release handles the caller might
+  // still be using — a decision no state is in a position to make correctly. It now takes the device
+  // alone, so there is nothing to get wrong: destroying a state cannot reach a context or a device, and
+  // the caller's handles outlive it by construction rather than by policy.
+  it('never releases host handles when a state built on the device is destroyed', async () => {
     const web = createWebWgpuHostBackend();
     const acquired = await web.acquire(document.createElement('canvas'), {});
-    const acquisition = allocateEntity<WgpuHostAcquisition>();
-    Object.assign(acquisition, acquired);
-    acquisition.ownership = 'caller' as const;
-    const configure = vi.spyOn(acquisition.context, 'configure').mockImplementationOnce(() => {
-      throw new Error('configure failed');
-    });
-    const destroy = vi.spyOn(acquisition.device, 'destroy');
-    const unconfigure = vi.spyOn(acquisition.context, 'unconfigure');
+    const destroy = vi.spyOn(acquired.device, 'destroy');
+    const unconfigure = vi.spyOn(acquired.context, 'unconfigure');
     const backend = entityBackend({
-      acquire: vi.fn(async () => acquisition),
+      acquire: vi.fn(async () => acquired),
+      attachSurface: vi.fn(() => null),
       isSupported: vi.fn(() => true),
       release: vi.fn((held) => {
         held.context.unconfigure();
@@ -200,43 +173,16 @@ describe('setWgpuHostBackend', () => {
     });
     setWgpuHostBackend(backend);
 
-    expect(() => createWgpuRenderState(acquisition, _pipeline)).toThrow('configure failed');
-    expect(backend.release).not.toHaveBeenCalled();
-    expect(destroy).not.toHaveBeenCalled();
-    expect(unconfigure).not.toHaveBeenCalled();
-
-    configure.mockRestore();
-    destroy.mockRestore();
-    unconfigure.mockRestore();
-    web.release(acquired);
-  });
-
-  // ★ O1. The destroy path, against a backend whose release really destroys.
-  it('O1: never releases caller-owned handles when the state is destroyed', async () => {
-    const web = createWebWgpuHostBackend();
-    const acquired = await web.acquire(document.createElement('canvas'), {});
-    const acquisition = allocateEntity<WgpuHostAcquisition>();
-    Object.assign(acquisition, acquired);
-    acquisition.ownership = 'caller' as const;
-    const destroy = vi.spyOn(acquisition.device, 'destroy');
-    const backend = entityBackend({
-      acquire: vi.fn(async () => acquisition),
-      isSupported: vi.fn(() => true),
-      release: vi.fn((held) => {
-        held.device.destroy();
-      }),
-    });
-    setWgpuHostBackend(backend);
-
-    const state = createWgpuRenderState(acquisition, _pipeline);
-    destroyWgpuRenderState(state);
+    destroyWgpuRenderState(createWgpuRenderState(acquired.device, _pipeline));
 
     expect(backend.release).not.toHaveBeenCalled();
     expect(destroy).not.toHaveBeenCalled();
+    expect(unconfigure).not.toHaveBeenCalled();
     // The handles are still usable, which is the property the caller actually cares about.
-    expect(acquisition.device.createBuffer({ size: 4, usage: GPUBufferUsage.COPY_DST }).size).toBe(4);
+    expect(acquired.device.createBuffer({ size: 4, usage: GPUBufferUsage.COPY_DST }).size).toBe(4);
 
     destroy.mockRestore();
+    unconfigure.mockRestore();
     web.release(acquired);
   });
 

package/src/wgpuRenderPass.test.ts

@@ -0,0 +1,258 @@
+import { createMatrix } from '@flighthq/geometry/contract';
+
+import { beginWgpuFrame, submitWgpuFrame } from './wgpuFrame';
+import {
+  beginWgpuRenderPass,
+  endWgpuRenderPass,
+  getWgpuActiveRenderPass,
+  getWgpuRenderPassViewport,
+  resumeWgpuRenderPass,
+  setWgpuRenderTransform2D,
+  suspendWgpuRenderPass,
+} from './wgpuRenderPass';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import {
+  beginWgpuScreenRenderPassForTest,
+  createWgpuRenderStateForTest,
+  createWgpuScreenRenderTargetForTest,
+  installWgpuMock,
+} from './wgpuTestHelper';
+import { createWgpuTextureRenderTarget } from './wgpuTextureRenderTarget';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('beginWgpuRenderPass', () => {
+  it('reports the target extent as the pass viewport', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const pass = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 64, 64));
+
+    expect(pass.viewport.width).toBe(64);
+    expect(getWgpuRenderStateRuntime(state).renderTargetViewport?.width).toBe(64);
+
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
+  });
+
+  // The viewport is LOGICAL, not the storage extent. A supersampled target is allocated at 2x per axis,
+  // and a projection that divided by that physical width would map logical x = 800 to NDC 0 — the scene
+  // filling a quarter of its own target, which is exactly the defect the derived scale exists to prevent.
+  it('reports the logical extent for a supersampled target, not its physical storage', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const target = createWgpuTextureRenderTarget(state, 400, 300, state.format, 'srgb', 4);
+    const pass = beginWgpuRenderPass(state, target);
+
+    expect(target.width).toBe(800);
+    expect(pass.viewport).toEqual({ height: 300, width: 400 });
+
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
+  });
+
+  it('passes float RGBA clear values through to the GPU color attachment', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const beginRenderPass = vi.spyOn(getWgpuRenderStateRuntime(state).commandEncoder!, 'beginRenderPass');
+    const target = createWgpuTextureRenderTarget(state, 32, 32, state.format, 'linear');
+
+    const pass = beginWgpuRenderPass(state, target, { color: [0.25, 0.5, 0.75, 1.0] });
+
+    const attachment = Array.from(beginRenderPass.mock.calls.at(-1)![0].colorAttachments)[0]!;
+    const clearValue = attachment.clearValue as GPUColorDict;
+    expect([clearValue.r, clearValue.g, clearValue.b, clearValue.a]).toEqual([0.25, 0.5, 0.75, 1.0]);
+    expect(attachment.loadOp).toBe('clear');
+
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
+  });
+
+  it('preserves the target when no clear is given', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const beginRenderPass = vi.spyOn(getWgpuRenderStateRuntime(state).commandEncoder!, 'beginRenderPass');
+
+    const pass = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 32, 32));
+
+    const attachment = Array.from(beginRenderPass.mock.calls.at(-1)![0].colorAttachments)[0]!;
+    expect(attachment.loadOp).toBe('load');
+
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
+  });
+
+  it('opens the frame when none is open, and leaves an explicitly opened frame to its owner', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const owning = beginWgpuScreenRenderPassForTest(state);
+    expect(owning.ownsFrame).toBe(true);
+    endWgpuRenderPass(owning);
+    expect(getWgpuRenderStateRuntime(state).commandEncoder).toBeNull();
+
+    beginWgpuFrame(state);
+    const borrowed = beginWgpuScreenRenderPassForTest(state);
+    expect(borrowed.ownsFrame).toBe(false);
+    endWgpuRenderPass(borrowed);
+    // The frame outlives the pass, which is what lets a shadow pass and a screen pass share one submit.
+    expect(getWgpuRenderStateRuntime(state).commandEncoder).not.toBeNull();
+    submitWgpuFrame(state);
+  });
+});
+
+describe('endWgpuRenderPass', () => {
+  it('restores the enclosing target, viewport, and clip state', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    const outer = beginWgpuRenderPass(state, screen, { color: [0, 0, 0, 0] });
+    const runtime = getWgpuRenderStateRuntime(state);
+    runtime.currentScissorRect = { height: 10, width: 10, x: 0, y: 0 };
+
+    const inner = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 32, 32));
+    expect(runtime.currentScissorRect).toBeNull();
+    endWgpuRenderPass(inner);
+
+    expect(runtime.currentRenderTarget).toBe(screen);
+    expect(runtime.renderTargetViewport).toEqual({ height: 600, width: 800 });
+    expect(runtime.currentScissorRect).toEqual({ height: 10, width: 10, x: 0, y: 0 });
+
+    endWgpuRenderPass(outer);
+    expect(runtime.currentRenderTarget).toBeNull();
+    expect(runtime.renderTargetViewport).toBeNull();
+  });
+
+  it('resumes the enclosing pass with a fresh encoder that preserves its pixels', async () => {
+    // A WebGPU pass encoder cannot be reopened, so the enclosing pass is re-recorded — and it must load
+    // rather than clear, or every nested offscreen pass would wipe the frame that surrounds it.
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    const suspendedEncoder = outer.encoder;
+
+    const inner = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 32, 32));
+    expect(outer.encoder).toBeNull();
+    const beginRenderPass = vi.spyOn(runtime.commandEncoder!, 'beginRenderPass');
+    endWgpuRenderPass(inner);
+
+    expect(outer.encoder).not.toBeNull();
+    expect(outer.encoder).not.toBe(suspendedEncoder);
+    expect(runtime.renderPass).toBe(outer.encoder);
+    expect(Array.from(beginRenderPass.mock.calls.at(-1)![0].colorAttachments)[0]!.loadOp).toBe('load');
+
+    endWgpuRenderPass(outer);
+  });
+
+  it('submits the frame it opened, and only that frame', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const inner = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 16, 16));
+
+    endWgpuRenderPass(inner);
+    expect(getWgpuRenderStateRuntime(state).commandEncoder).not.toBeNull();
+
+    endWgpuRenderPass(outer);
+    expect(getWgpuRenderStateRuntime(state).commandEncoder).toBeNull();
+  });
+
+  it('refuses a pass that is not the innermost open one', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const inner = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 16, 16));
+
+    expect(() => endWgpuRenderPass(outer)).toThrow(/innermost open pass/);
+
+    endWgpuRenderPass(inner);
+    endWgpuRenderPass(outer);
+  });
+});
+
+describe('getWgpuActiveRenderPass', () => {
+  it('names the innermost open pass and nothing outside a bracket', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(getWgpuActiveRenderPass(state)).toBeNull();
+
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    expect(getWgpuActiveRenderPass(state)).toBe(outer);
+    const inner = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 16, 16));
+    expect(getWgpuActiveRenderPass(state)).toBe(inner);
+
+    endWgpuRenderPass(inner);
+    expect(getWgpuActiveRenderPass(state)).toBe(outer);
+    endWgpuRenderPass(outer);
+    expect(getWgpuActiveRenderPass(state)).toBeNull();
+  });
+});
+
+describe('getWgpuRenderPassViewport', () => {
+  it('throws outside a pass rather than inventing a canvas-sized default', async () => {
+    // A draw with no target bound is API misuse; a default extent would hide it until the picture came
+    // out the wrong size, with nothing in the failure naming the missing begin.
+    const state = await createWgpuRenderStateForTest();
+    expect(() => getWgpuRenderPassViewport(state)).toThrow(/beginWgpuRenderPass/);
+  });
+
+  it('reports the innermost pass extent', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    expect(getWgpuRenderPassViewport(state)).toEqual({ height: 600, width: 800 });
+
+    const inner = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 40, 20));
+    expect(getWgpuRenderPassViewport(state)).toEqual({ height: 20, width: 40 });
+
+    endWgpuRenderPass(inner);
+    endWgpuRenderPass(outer);
+  });
+});
+
+describe('resumeWgpuRenderPass', () => {
+  it('reopens a suspended pass over the same target', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pass = beginWgpuScreenRenderPassForTest(state);
+    const target = pass.target;
+    suspendWgpuRenderPass(pass);
+
+    resumeWgpuRenderPass(pass);
+
+    expect(pass.encoder).not.toBeNull();
+    expect(pass.target).toBe(target);
+    expect(getWgpuRenderStateRuntime(state).renderPass).toBe(pass.encoder);
+    endWgpuRenderPass(pass);
+  });
+});
+
+describe('setWgpuRenderTransform2D', () => {
+  it('installs a copy of the transform, restored by the enclosing pass', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const original = state.renderTransform2D;
+    const bake = createMatrix();
+    bake.tx = 42;
+
+    const pass = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 32, 32));
+    setWgpuRenderTransform2D(pass, bake);
+    expect(state.renderTransform2D?.tx).toBe(42);
+    expect(state.renderTransform2D).not.toBe(bake);
+    endWgpuRenderPass(pass);
+
+    expect(state.renderTransform2D).toBe(original);
+    endWgpuRenderPass(outer);
+  });
+});
+
+describe('suspendWgpuRenderPass', () => {
+  it('closes the encoder while leaving the pass open', async () => {
+    // The effect pipeline records its own fullscreen passes into the frame, which it can only do while
+    // no other pass encoder is recording.
+    const state = await createWgpuRenderStateForTest();
+    const pass = beginWgpuScreenRenderPassForTest(state);
+
+    suspendWgpuRenderPass(pass);
+
+    expect(pass.encoder).toBeNull();
+    expect(getWgpuRenderStateRuntime(state).renderPass).toBeNull();
+    expect(getWgpuActiveRenderPass(state)).toBe(pass);
+
+    resumeWgpuRenderPass(pass);
+    endWgpuRenderPass(pass);
+  });
+});