@flighthq/render-wgpu 0.5.1-next.920.da8f530 → 0.6.0

package/src/wgpuScissor.test.ts

@@ -1,12 +1,14 @@
-import { renderWgpuBackground } from './wgpuBackground';
-import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import type { WgpuRenderPassEncoder } from './contract.render-wgpu-types.ts';
+import { beginWgpuRenderPass, endWgpuRenderPass } from './wgpuRenderPass.ts';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
 import {
   applyWgpuScissorRect,
   popWgpuScissorRect,
   pushWgpuScissorRect,
   setWgpuRenderPassScissorRect,
-} from './wgpuScissor';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+} from './wgpuScissor.ts';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
+import { createWgpuTextureRenderTarget } from './wgpuTextureRenderTarget.ts';
 
 beforeAll(() => {
   installWgpuMock();
@@ -15,11 +17,11 @@ beforeAll(() => {
 describe('applyWgpuScissorRect', () => {
   it('calls setScissorRect on the pass when a rect is active', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const runtime = getWgpuRenderStateRuntime(state);
     runtime.currentScissorRect = { x: 10, y: 20, width: 100, height: 50 };
     const calls: number[][] = [];
-    const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as GPURenderPassEncoder;
+    const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as WgpuRenderPassEncoder;
     applyWgpuScissorRect(state, fakePass);
     expect(calls.length).toBe(1);
     expect(calls[0]).toEqual([10, 20, 100, 50]);
@@ -27,20 +29,20 @@ describe('applyWgpuScissorRect', () => {
 
   it('is a no-op when currentScissorRect is null', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const calls: number[][] = [];
-    const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as GPURenderPassEncoder;
+    const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as WgpuRenderPassEncoder;
     applyWgpuScissorRect(state, fakePass);
     expect(calls.length).toBe(0);
   });
 
   it('clamps dimensions to at least 1×1', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const runtime = getWgpuRenderStateRuntime(state);
     runtime.currentScissorRect = { x: 0, y: 0, width: 0, height: 0 };
     const calls: number[][] = [];
-    const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as GPURenderPassEncoder;
+    const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as WgpuRenderPassEncoder;
     applyWgpuScissorRect(state, fakePass);
     expect(calls[0]).toEqual([0, 0, 1, 1]);
   });
@@ -49,14 +51,14 @@ describe('applyWgpuScissorRect', () => {
 describe('popWgpuScissorRect', () => {
   it('is a no-op when the stack is empty', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     expect(() => popWgpuScissorRect(state)).not.toThrow();
     expect(getWgpuRenderStateRuntime(state).currentScissorRect).toBeNull();
   });
 
   it('restores the previous rect after a push/pop pair', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const r1 = { x: 0, y: 0, width: 100, height: 100 };
     const r2 = { x: 10, y: 10, width: 50, height: 50 };
     pushWgpuScissorRect(state, r1);
@@ -72,7 +74,7 @@ describe('popWgpuScissorRect', () => {
 describe('pushWgpuScissorRect', () => {
   it('sets currentScissorRect on first push', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const rect = { x: 5, y: 10, width: 80, height: 40 };
     pushWgpuScissorRect(state, rect);
     expect(getWgpuRenderStateRuntime(state).currentScissorRect).toEqual(rect);
@@ -80,7 +82,7 @@ describe('pushWgpuScissorRect', () => {
 
   it('stacks previous rect when pushing a second rect', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const r1 = { x: 0, y: 0, width: 100, height: 100 };
     const r2 = { x: 20, y: 20, width: 60, height: 60 };
     pushWgpuScissorRect(state, r1);
@@ -93,7 +95,7 @@ describe('pushWgpuScissorRect', () => {
 
   it('copies the rect so mutation of the original does not affect the pushed value', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const rect = { x: 0, y: 0, width: 50, height: 50 };
     pushWgpuScissorRect(state, rect);
     rect.width = 999;
@@ -102,13 +104,42 @@ describe('pushWgpuScissorRect', () => {
 });
 
 describe('setWgpuRenderPassScissorRect', () => {
-  it('scales logical coordinates on the acquired supersample surface', async () => {
-    const state = await createWgpuRenderStateForTest({ antialias: true });
-    renderWgpuBackground(state);
+  it('scales logical coordinates onto a supersampled screen surface', async () => {
+    const state = await createWgpuRenderStateForTest();
+    beginWgpuScreenRenderPassForTest(state, { color: [0, 0, 0, 0] }, { antialias: true });
+    const setScissorRect = vi.fn();
+
+    setWgpuRenderPassScissorRect(state, { setScissorRect } as unknown as WgpuRenderPassEncoder, 3, 5, 7, 11);
+
+    expect(setScissorRect).toHaveBeenCalledWith(6, 10, 14, 22);
+  });
+
+  // Logical is one coordinate space, so a supersampled OFFSCREEN target scales its scissors by the same
+  // factor its storage was grown by. It previously passed them through unscaled while the screen scaled
+  // them, which left a clip inside a sampleCount-4 effect target covering a quarter of its intended area.
+  it('scales them onto a supersampled texture target by the same rule', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const pass = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 64, 64, state.format, 'srgb', 4));
     const setScissorRect = vi.fn();
 
-    setWgpuRenderPassScissorRect(state, { setScissorRect } as unknown as GPURenderPassEncoder, 3, 5, 7, 11);
+    setWgpuRenderPassScissorRect(state, { setScissorRect } as unknown as WgpuRenderPassEncoder, 3, 5, 7, 11);
 
     expect(setScissorRect).toHaveBeenCalledWith(6, 10, 14, 22);
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
+  });
+
+  it('passes them through unscaled on a target with no supersample', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const pass = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 64, 64));
+    const setScissorRect = vi.fn();
+
+    setWgpuRenderPassScissorRect(state, { setScissorRect } as unknown as WgpuRenderPassEncoder, 3, 5, 7, 11);
+
+    expect(setScissorRect).toHaveBeenCalledWith(3, 5, 7, 11);
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
   });
 });

package/src/wgpuScreenAntialias.test.ts

@@ -0,0 +1,65 @@
+import type { WgpuCommandEncoder, WgpuRenderPassDescriptor } from './contract.render-wgpu-types.ts';
+import { beginWgpuRenderPass, endWgpuRenderPass } from './wgpuRenderPass.ts';
+import { enableWgpuScreenRenderTargetAntialias } from './wgpuScreenAntialias.ts';
+import { bindWgpuScreenRenderTarget } from './wgpuScreenRenderTarget.ts';
+import {
+  createWgpuRenderStateForTest,
+  createWgpuScreenRenderTargetForTest,
+  installWgpuMock,
+} from './wgpuTestHelper.ts';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('enableWgpuScreenRenderTargetAntialias', () => {
+  // ★ THE COST IS OPT-IN, AND THAT IS THE POINT OF THE SLOTS. A screen target that was never asked for
+  // antialiasing carries no resolve hook, so the module holding the resolve pipeline and its shader is
+  // unreachable from an ordinary frame loop and tree-shakes out of the bundle entirely.
+  it('installs the hooks a plain screen target does not carry', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+
+    expect(screen.antialias).toBe(false);
+    expect(screen.acquireAntialiasView).toBeNull();
+    expect(screen.encodeAntialiasResolve).toBeNull();
+
+    enableWgpuScreenRenderTargetAntialias(screen);
+
+    expect(screen.antialias).toBe(true);
+    expect(screen.acquireAntialiasView).not.toBeNull();
+    expect(screen.encodeAntialiasResolve).not.toBeNull();
+  });
+
+  it('draws into supersample storage twice the surface extent', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state, { antialias: true }, 400, 300);
+
+    const view = bindWgpuScreenRenderTarget(state, screen);
+
+    expect(screen.width).toBe(800);
+    expect(view).toBe(screen.antialiasView);
+    expect(view).not.toBe(screen.presentationView);
+    expect(screen.antialiasTexture?.width).toBe(800);
+  });
+
+  it('resolves the supersample texture into the presentation view', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state, { antialias: true });
+    const pass = beginWgpuRenderPass(state, screen, { color: [0, 0, 0, 0] });
+    const presentationView = screen.presentationView;
+    const encoded: WgpuRenderPassDescriptor[] = [];
+    const encoder = {
+      beginRenderPass: (descriptor: WgpuRenderPassDescriptor) => {
+        encoded.push(descriptor);
+        return { draw: () => {}, end: () => {}, setBindGroup: () => {}, setPipeline: () => {} };
+      },
+    } as unknown as WgpuCommandEncoder;
+
+    screen.encodeAntialiasResolve!(state, screen, encoder);
+
+    expect(encoded.length).toBe(1);
+    expect(Array.from(encoded[0]!.colorAttachments)[0]!.view).toBe(presentationView);
+    endWgpuRenderPass(pass);
+  });
+});

package/src/wgpuScreenCapture.test.ts

@@ -0,0 +1,165 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import type {
+  WgpuBuffer,
+  WgpuBufferMapState,
+  WgpuCommandEncoder,
+  WgpuScreenRenderTarget,
+} from './contract.render-wgpu-types.ts';
+import { beginWgpuRenderPass, endWgpuRenderPass } from './wgpuRenderPass.ts';
+import {
+  createBitmapFromWgpuScreenRenderTarget,
+  enableWgpuScreenRenderTargetCapture,
+  encodeWgpuScreenRenderTargetCapture,
+} from './wgpuScreenCapture.ts';
+import {
+  createWgpuRenderStateForTest,
+  createWgpuScreenRenderTargetForTest,
+  installWgpuMock,
+} from './wgpuTestHelper.ts';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('createBitmapFromWgpuScreenRenderTarget', () => {
+  it('throws when capture was never enabled (no buffer to read)', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    await expect(createBitmapFromWgpuScreenRenderTarget(screen)).rejects.toThrow(/enableWgpuScreenRenderTargetCapture/);
+  });
+
+  it('reads the mapped buffer within the bound', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    installCaptureBuffer(screen, () => Promise.resolve());
+
+    const bitmap = await createBitmapFromWgpuScreenRenderTarget(screen, 1_000);
+
+    expect(bitmap.width).toBe(1);
+    expect(bitmap.height).toBe(1);
+  });
+
+  it('fails by name when the buffer never maps, instead of awaiting forever', async () => {
+    // The driver failure this bounds: mapAsync neither resolves nor rejects. Before the bound, the
+    // caller sat here until something outside it gave up and reported a stall with no location.
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    installCaptureBuffer(screen, () => new Promise<void>(() => {}));
+
+    await expect(createBitmapFromWgpuScreenRenderTarget(screen, 25)).rejects.toThrow(/did not map within 25ms/);
+  });
+
+  it('leaves the wait unbounded when the caller passes 0', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    let settle = (): void => {};
+    installCaptureBuffer(screen, () => new Promise<void>((resolve) => (settle = resolve)));
+
+    let done = false;
+    const pending = createBitmapFromWgpuScreenRenderTarget(screen, 0).then(() => (done = true));
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    expect(done).toBe(false);
+
+    settle();
+    await pending;
+    expect(done).toBe(true);
+  });
+});
+
+describe('enableWgpuScreenRenderTargetCapture', () => {
+  it('sets the capture flag on the screen target', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    expect(screen.captureEnabled).toBe(false);
+    enableWgpuScreenRenderTargetCapture(screen);
+    expect(screen.captureEnabled).toBe(true);
+  });
+
+  it('redirects the frame into an offscreen texture rather than the swap chain', async () => {
+    // The whole reason capture exists: software and headless adapters never present the swap chain, and
+    // its texture reads back as zeros, so a captured frame must be drawn somewhere readable instead.
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    expect(screen.captureTexture).toBeNull();
+
+    enableWgpuScreenRenderTargetCapture(screen);
+    endWgpuRenderPass(beginWgpuRenderPass(state, screen, { color: [0, 0, 0, 0] }));
+
+    expect(screen.captureTexture).not.toBeNull();
+  });
+});
+
+describe('encodeWgpuScreenRenderTargetCapture', () => {
+  it('is a no-op when capture is disabled', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+    let copied = false;
+    const encoder = { copyTextureToBuffer: () => (copied = true) } as unknown as WgpuCommandEncoder;
+    encodeWgpuScreenRenderTargetCapture(screen, encoder);
+    expect(copied).toBe(false);
+  });
+
+  it('skips the copy while a readback holds the buffer, and resumes once it lets go', async () => {
+    // The writer/reader handshake over the single retained buffer: an animating scene must not keep
+    // enqueueing copies into a buffer a readback has mapped or is waiting to map.
+    const state = await createWgpuRenderStateForTest();
+    const screen = captureReadyScreenRenderTarget(state);
+    let mapState: WgpuBufferMapState = 'unmapped';
+    installCaptureBuffer(screen, () => Promise.resolve());
+    Object.defineProperty(screen.captureBuffer, 'mapState', { get: () => mapState });
+
+    let copies = 0;
+    const encoder = { copyTextureToBuffer: () => copies++ } as unknown as WgpuCommandEncoder;
+
+    mapState = 'pending';
+    encodeWgpuScreenRenderTargetCapture(screen, encoder);
+    mapState = 'mapped';
+    encodeWgpuScreenRenderTargetCapture(screen, encoder);
+    expect(copies).toBe(0);
+
+    mapState = 'unmapped';
+    encodeWgpuScreenRenderTargetCapture(screen, encoder);
+    expect(copies).toBe(1);
+  });
+
+  it('still copies when the implementation reports no map state at all', async () => {
+    // Fails safe in the direction that keeps capturing: an undefined mapState must not read as "busy"
+    // and silence every copy for the rest of the run.
+    const state = await createWgpuRenderStateForTest();
+    const screen = captureReadyScreenRenderTarget(state);
+    installCaptureBuffer(screen, () => Promise.resolve());
+    Object.defineProperty(screen.captureBuffer, 'mapState', { get: () => undefined });
+
+    let copies = 0;
+    encodeWgpuScreenRenderTargetCapture(screen, {
+      copyTextureToBuffer: () => copies++,
+    } as unknown as WgpuCommandEncoder);
+
+    expect(copies).toBe(1);
+  });
+});
+
+// A screen target that has drawn one captured frame, so its capture texture exists.
+function captureReadyScreenRenderTarget(
+  state: Awaited<ReturnType<typeof createWgpuRenderStateForTest>>,
+): WgpuScreenRenderTarget {
+  const screen = createWgpuScreenRenderTargetForTest(state);
+  enableWgpuScreenRenderTargetCapture(screen);
+  endWgpuRenderPass(beginWgpuRenderPass(state, screen, { color: [0, 0, 0, 0] }));
+  return screen;
+}
+
+// Installs a 1x1 retained capture buffer whose map step the caller controls, so the map bound can be
+// exercised without a GPU. The mock device's buffers carry no map surface of their own.
+function installCaptureBuffer(target: WgpuScreenRenderTarget, mapAsync: () => Promise<void>): void {
+  target.captureBuffer = {
+    mapAsync,
+    getMappedRange: () => new ArrayBuffer(256),
+    unmap: () => {},
+    destroy: () => {},
+  } as unknown as WgpuBuffer;
+  target.captureWidth = 1;
+  target.captureHeight = 1;
+  target.captureBytesPerRow = 256;
+}

package/src/wgpuScreenRenderTarget.test.ts

@@ -0,0 +1,172 @@
+import { allocateEntity } from '@flighthq/entity/contract';
+import type { EntityConstruction } from '@flighthq/entity/contract';
+import type { Surface } from '@flighthq/surface/contract';
+
+import { createTestWgpuSurface, testWgpuHost } from './wgpuHost.ts';
+import { beginWgpuRenderPass, endWgpuRenderPass } from './wgpuRenderPass.ts';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
+import {
+  bindWgpuScreenRenderTarget,
+  createWgpuScreenRenderTarget,
+  destroyWgpuScreenRenderTarget,
+  endWgpuScreenRenderTargetFrame,
+  initializeWgpuScreenRenderTarget,
+  isWgpuScreenRenderTarget,
+  syncWgpuScreenRenderTargetExtent,
+} from './wgpuScreenRenderTarget.ts';
+import {
+  createWgpuRenderStateForTest,
+  createWgpuScreenRenderTargetForTest,
+  installWgpuMock,
+} from './wgpuTestHelper.ts';
+import { createWgpuTextureRenderTarget } from './wgpuTextureRenderTarget.ts';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+const _webBackend = testWgpuHost;
+
+describe('bindWgpuScreenRenderTarget', () => {
+  it('acquires one swap-chain view per frame and releases it at the end of the frame', async () => {
+    // Nothing may hold a swap-chain view across frames — that is the property that makes a screen target
+    // unsampleable — so the view is acquired inside the frame and dropped when it is submitted.
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+
+    const first = bindWgpuScreenRenderTarget(state, screen);
+    expect(bindWgpuScreenRenderTarget(state, screen)).toBe(first);
+    expect(screen.presentationView).toBe(first);
+
+    endWgpuScreenRenderTargetFrame(screen);
+    expect(screen.presentationView).toBeNull();
+  });
+
+  it('follows a surface that resized between frames', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const canvas = document.createElement('canvas');
+    canvas.width = 320;
+    canvas.height = 240;
+    const screen = createWgpuScreenRenderTarget(_webBackend, state.device, createTestWgpuSurface(canvas), {
+      format: state.format,
+    });
+
+    canvas.width = 640;
+    canvas.height = 480;
+    bindWgpuScreenRenderTarget(state, screen);
+
+    expect(screen.width).toBe(640);
+    expect(screen.height).toBe(480);
+    expect(screen.depthStencilTexture.width).toBe(640);
+  });
+
+  it('draws into supersample storage when the target is antialiased', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state, { antialias: true }, 400, 300);
+
+    const view = bindWgpuScreenRenderTarget(state, screen);
+
+    expect(screen.width).toBe(800);
+    expect(view).toBe(screen.antialiasView);
+    expect(view).not.toBe(screen.presentationView);
+    expect(screen.antialiasTexture?.width).toBe(800);
+  });
+});
+
+describe('createWgpuScreenRenderTarget', () => {
+  it('configures the surface context and declares one color attachment', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const canvas = document.createElement('canvas');
+    canvas.width = 800;
+    canvas.height = 600;
+    const target = createTestWgpuSurface(canvas);
+    const context = canvas.getContext('webgpu')!;
+    const configure = vi.spyOn(context, 'configure');
+
+    const screen = createWgpuScreenRenderTarget(_webBackend, state.device, target, { format: 'rgba8unorm' });
+
+    expect(configure).toHaveBeenCalledOnce();
+    expect(configure.mock.calls[0]![0].format).toBe('rgba8unorm');
+    expect(screen.context).toBe(context);
+    expect(screen.colorAttachments).toBe(1);
+    expect(screen.format).toBe('rgba8unorm');
+    expect(screen.width).toBe(800);
+    expect(screen.height).toBe(600);
+  });
+
+  it('reports a surface the host cannot present rather than returning a target that cannot bind', async () => {
+    const state = await createWgpuRenderStateForTest();
+    // A surface whose drawable is not a canvas: the host cannot present through it, which is the same
+    // sentinel as a surface it never allocated.
+    const unregisteredTarget = createTestWgpuSurface(document.createElement('div') as unknown as HTMLCanvasElement);
+
+    expect(() => createWgpuScreenRenderTarget(_webBackend, state.device, unregisteredTarget)).toThrow(
+      /cannot present WebGPU/,
+    );
+  });
+});
+
+describe('destroyWgpuScreenRenderTarget', () => {
+  it('frees the storage it owns and unconfigures the context', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state, { antialias: true });
+    bindWgpuScreenRenderTarget(state, screen);
+    const depth = vi.spyOn(screen.depthStencilTexture, 'destroy');
+    const antialias = vi.spyOn(screen.antialiasTexture!, 'destroy');
+    const unconfigure = vi.spyOn(screen.context, 'unconfigure');
+
+    destroyWgpuScreenRenderTarget(screen);
+
+    expect(depth).toHaveBeenCalledOnce();
+    expect(antialias).toHaveBeenCalledOnce();
+    expect(unconfigure).toHaveBeenCalledOnce();
+    expect(screen.antialiasView).toBeNull();
+    expect(screen.presentationView).toBeNull();
+  });
+});
+
+describe('endWgpuScreenRenderTargetFrame', () => {
+  it('is what a submitted frame calls, leaving no view behind', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const screen = createWgpuScreenRenderTargetForTest(state);
+
+    endWgpuRenderPass(beginWgpuRenderPass(state, screen, { color: [0, 0, 0, 0] }));
+
+    expect(screen.presentationView).toBeNull();
+    expect(getWgpuRenderStateRuntime(state).frameScreenTarget).toBeNull();
+  });
+});
+
+describe('initializeWgpuScreenRenderTarget', () => {
+  it('is the construction initializer of createWgpuScreenRenderTarget', () => {
+    expect(typeof initializeWgpuScreenRenderTarget).toBe('function');
+  });
+});
+
+describe('isWgpuScreenRenderTarget', () => {
+  it('separates the two realizations by the field that says where the pixels live', async () => {
+    const state = await createWgpuRenderStateForTest();
+
+    expect(isWgpuScreenRenderTarget(createWgpuScreenRenderTargetForTest(state))).toBe(true);
+    expect(isWgpuScreenRenderTarget(createWgpuTextureRenderTarget(state, 16, 16))).toBe(false);
+  });
+});
+
+describe('syncWgpuScreenRenderTargetExtent', () => {
+  it('follows the surface without a resize call', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const canvas = document.createElement('canvas');
+    canvas.width = 320;
+    canvas.height = 240;
+    const screen = createWgpuScreenRenderTarget(_webBackend, state.device, createTestWgpuSurface(canvas), {
+      format: state.format,
+    });
+
+    canvas.width = 500;
+    canvas.height = 400;
+    syncWgpuScreenRenderTargetExtent(screen);
+
+    expect(screen.width).toBe(500);
+    expect(screen.height).toBe(400);
+  });
+});

package/src/wgpuShader.test.ts

@@ -1,7 +1,8 @@
-import { AdvancedBlendMode, BlendMode } from '@flighthq/types/contract';
+import { AdvancedBlendMode } from '@flighthq/effects/contract';
+import { BlendMode } from '@flighthq/materials/contract';
 
-import { renderWgpuBackground } from './wgpuBackground';
-import { getWgpuRenderStateDeviceResources, getWgpuRenderStateRuntime } from './wgpuRenderState';
+import type { WgpuRenderPipelineDescriptor } from './contract.render-wgpu-types.ts';
+import { getWgpuRenderStateDeviceResources, getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
 import {
   UNIFORM_BYTE_SIZE,
   createWgpuBindGroupLayouts,
@@ -13,8 +14,8 @@ import {
   setWgpuMatrixFromTransform,
   writeWgpuMatrixOnlyUniforms,
   writeWgpuQuadUniforms,
-} from './wgpuShader';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+} from './wgpuShader.ts';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
 
 beforeAll(() => {
   installWgpuMock();
@@ -95,7 +96,7 @@ describe('getWgpuPipeline', () => {
     const state = await createWgpuRenderStateForTest();
     const blendOf = (mode: BlendMode) =>
       [
-        ...(getWgpuPipeline(state, mode, 'normal') as unknown as { __descriptor: GPURenderPipelineDescriptor })
+        ...(getWgpuPipeline(state, mode, 'normal') as unknown as { __descriptor: WgpuRenderPipelineDescriptor })
           .__descriptor.fragment!.targets,
       ][0]!.blend!.color;
     expect(blendOf(BlendMode.Normal)).toEqual({ srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' });
@@ -114,7 +115,7 @@ describe('getWgpuPipeline', () => {
     const state = await createWgpuRenderStateForTest();
     const blendOf = (mode: BlendMode) =>
       [
-        ...(getWgpuPipeline(state, mode, 'normal') as unknown as { __descriptor: GPURenderPipelineDescriptor })
+        ...(getWgpuPipeline(state, mode, 'normal') as unknown as { __descriptor: WgpuRenderPipelineDescriptor })
           .__descriptor.fragment!.targets,
       ][0]!.blend!.color;
     expect(blendOf(AdvancedBlendMode.Overlay)).toEqual({
@@ -164,7 +165,7 @@ describe('writeWgpuMatrixOnlyUniforms', () => {
   it('advances uniformOffset', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const before = runtime.uniformOffset;
     const fakeNode = { alpha: 1, useColorScaleBias: false, colorScaleBias: null };
     const t = { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
@@ -176,7 +177,7 @@ describe('writeWgpuQuadUniforms', () => {
   it('advances uniformOffset by uniformStride', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const before = runtime.uniformOffset;
     const fakeNode = {
       alpha: 1,
@@ -191,7 +192,7 @@ describe('writeWgpuQuadUniforms', () => {
   it('writes quad coordinates into uniform data at float offset 24', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const fakeNode = {
       alpha: 0.5,
       useColorScaleBias: false,
@@ -211,7 +212,7 @@ describe('writeWgpuQuadUniforms', () => {
   it('writes the native straight-alpha texture flag at u32 offset 14', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const fakeNode = {
       alpha: 1,
       useColorScaleBias: false,

package/src/wgpuShaderBinding.test.ts

@@ -1,10 +1,10 @@
 import { getOrCreateRenderProxy2D } from '@flighthq/render/contract';
 import { createSprite } from '@flighthq/scene2d/contract';
-import type { WgpuBitmapShader } from '@flighthq/types/contract';
 
-import { getWgpuRenderStateRuntime } from './wgpuRenderState';
-import { getWgpuShader, resolveWgpuShader, setWgpuShader } from './wgpuShaderBinding';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import type { WgpuBitmapShader } from './contract.render-wgpu-types.ts';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
+import { getWgpuShader, resolveWgpuShader, setWgpuShader } from './wgpuShaderBinding.ts';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
 
 beforeAll(() => {
   installWgpuMock();

package/src/wgpuShaderRegistry.test.ts

@@ -1,8 +1,7 @@
-import type { WgpuBitmapShader } from '@flighthq/types/contract';
-
-import { getWgpuRenderStateRuntime } from './wgpuRenderState';
-import { registerWgpuBitmapShader } from './wgpuShaderRegistry';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import type { WgpuBitmapShader } from './contract.render-wgpu-types.ts';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
+import { registerWgpuBitmapShader } from './wgpuShaderRegistry.ts';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
 
 beforeAll(() => {
   installWgpuMock();