@flighthq/render-wgpu 0.5.1-next.973.788d3d7 → 0.6.0

package/src/wgpuDeviceLoss.test.ts

@@ -1,35 +1,42 @@
+import { EntityRuntimeKey } from '@flighthq/entity/contract';
 import { connectSignal, createSignal } from '@flighthq/signals/contract';
-import type { WgpuDeviceRuntime, WgpuRenderState } from '@flighthq/types/contract';
-import { EntityRuntimeKey } from '@flighthq/types/contract';
 
+import type {
+  WgpuDevice,
+  WgpuDeviceLostInfo,
+  WgpuDeviceLostReason,
+  WgpuDeviceRuntime,
+  WgpuRenderState,
+} from './contract.render-wgpu-types.ts';
 import {
   disposeWgpuDeviceSignals,
   enableWgpuDeviceSignals,
   getWgpuDeviceLoss,
   isWgpuDeviceLost,
   observeWgpuDeviceLoss,
-} from './wgpuDeviceLoss';
+} from './wgpuDeviceLoss.ts';
 import {
   createWgpuDeviceState,
   createWgpuOffscreenRenderState,
   createWgpuRenderStateRuntime,
   getWgpuRenderStateRuntime,
-} from './wgpuRenderState';
+} from './wgpuRenderState.ts';
 
 // A device whose loss the test drives by hand. `lost` is the only member the observer reads, so the
 // rest of GPUDevice stays absent on purpose: a probe that needed a full device would be testing the
 // mock. `resolveLost` stands in for the driver resolving the real terminal promise.
-function makeLosableDevice(): { device: GPUDevice; resolveLost: (reason: GPUDeviceLostReason) => void } {
-  let resolveLost!: (reason: GPUDeviceLostReason) => void;
-  const lost = new Promise<GPUDeviceLostInfo>((resolve) => {
-    resolveLost = (reason) => resolve({ message: `lost: ${reason}`, reason } as GPUDeviceLostInfo);
+function makeLosableDevice(): { device: WgpuDevice; resolveLost: (reason: WgpuDeviceLostReason) => void } {
+  let resolveLost!: (reason: WgpuDeviceLostReason) => void;
+  const lost = new Promise<WgpuDeviceLostInfo>((resolve) => {
+    resolveLost = (reason) => resolve({ message: `lost: ${reason}`, reason } as WgpuDeviceLostInfo);
   });
-  return { device: { destroy: () => {}, lost } as unknown as GPUDevice, resolveLost };
+  return { device: { destroy: () => {}, lost } as unknown as WgpuDevice, resolveLost };
 }
 
-function makeStateOn(device: GPUDevice): WgpuRenderState {
-  const state = { applyBlendMode: null } as unknown as WgpuRenderState;
-  state[EntityRuntimeKey] = createWgpuRenderStateRuntime(createWgpuDeviceState(device));
+function makeStateOn(device: WgpuDevice): WgpuRenderState {
+  const deviceState = createWgpuDeviceState(device);
+  const state = { applyBlendMode: null, deviceState } as unknown as WgpuRenderState;
+  state[EntityRuntimeKey] = createWgpuRenderStateRuntime(deviceState);
   return state;
 }
 
@@ -51,7 +58,7 @@ describe('createWgpuOffscreenRenderState', () => {
   it('reports a method-tight device-lost outcome instead of deriving on a dead device', async () => {
     const { device, resolveLost } = makeLosableDevice();
     const screen = makeStateOn(device);
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     const result = createWgpuOffscreenRenderState(screen);
     expect(result.reason).toBe('device-lost');
@@ -95,7 +102,7 @@ describe('getWgpuDeviceLoss', () => {
     connectSignal(enableWgpuDeviceSignals(state).onDeviceLost, () => {
       emissions += 1;
     });
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     expect(emissions).toBe(1);
     expect(getWgpuDeviceLoss(state)?.reason).toBe('unknown');
@@ -111,7 +118,7 @@ describe('getWgpuDeviceLoss', () => {
     connectSignal(enableWgpuDeviceSignals(state).onDeviceLost, () => {
       emissions += 1;
     });
-    resolveLost('destroyed' as GPUDeviceLostReason);
+    resolveLost('destroyed' as WgpuDeviceLostReason);
     await settle();
     expect(emissions).toBe(0);
     expect(getWgpuDeviceLoss(state)?.reason).toBe('destroyed');
@@ -127,7 +134,7 @@ describe('getWgpuDeviceLoss', () => {
     connectSignal(enableWgpuDeviceSignals(screen).onDeviceLost, () => {
       emissions += 1;
     });
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     expect(emissions).toBe(1);
     expect(isWgpuDeviceLost(screen)).toBe(true);
@@ -139,7 +146,7 @@ describe('getWgpuDeviceLoss', () => {
   it('reports the terminal fact to a state created after the loss', async () => {
     const { device, resolveLost } = makeLosableDevice();
     const screen = makeStateOn(device);
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     const late = makeAliasOf(screen);
     expect(isWgpuDeviceLost(late)).toBe(true);
@@ -151,7 +158,7 @@ describe('getWgpuDeviceLoss', () => {
   // that, so it is asserted rather than assumed.
   it('records a loss that resolved before the device tier was ever constructed', async () => {
     const { device, resolveLost } = makeLosableDevice();
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     const state = makeStateOn(device);
     let emissions = 0;
@@ -171,7 +178,7 @@ describe('getWgpuDeviceLoss', () => {
   // A device with no `lost` member is reachable today — `createWgpuDeviceState({} as GPUDevice)` is
   // used by existing tests, and the host seam accepts caller-supplied handles from native hosts.
   it('treats a device with no lost promise as live rather than throwing', () => {
-    const state = makeStateOn({ destroy: () => {} } as unknown as GPUDevice);
+    const state = makeStateOn({ destroy: () => {} } as unknown as WgpuDevice);
     expect(isWgpuDeviceLost(state)).toBe(false);
   });
 });
@@ -183,7 +190,7 @@ describe('isWgpuDeviceLost', () => {
     const { device, resolveLost } = makeLosableDevice();
     const state = makeStateOn(device);
     enableWgpuDeviceSignals(state);
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     const deviceRuntime = getWgpuRenderStateRuntime(state).context;
     const holdsState = Object.values(deviceRuntime as unknown as Record<string, unknown>).some(
       (value) => value === state || (Array.isArray(value) && value.includes(state)),
@@ -195,7 +202,7 @@ describe('isWgpuDeviceLost', () => {
     const { device, resolveLost } = makeLosableDevice();
     const state = makeStateOn(device);
     expect(isWgpuDeviceLost(state)).toBe(false);
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     expect(isWgpuDeviceLost(state)).toBe(true);
   });
@@ -206,7 +213,7 @@ describe('observeWgpuDeviceLoss', () => {
     const { device, resolveLost } = makeLosableDevice();
     const deviceRuntime = { device, lost: null, signals: null } as unknown as WgpuDeviceRuntime;
     observeWgpuDeviceLoss(deviceRuntime);
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     expect(deviceRuntime.lost?.reason).toBe('unknown');
   });
@@ -218,7 +225,7 @@ describe('observeWgpuDeviceLoss', () => {
     const deviceRuntime = {
       device,
       lost: null,
-      signals: { onDeviceLost: createSignal<(info: GPUDeviceLostInfo) => void>() },
+      signals: { onDeviceLost: createSignal<WgpuDeviceLostInfo>() },
     } as unknown as WgpuDeviceRuntime;
     let emissions = 0;
     connectSignal(deviceRuntime.signals!.onDeviceLost, () => {
@@ -226,7 +233,7 @@ describe('observeWgpuDeviceLoss', () => {
     });
     observeWgpuDeviceLoss(deviceRuntime);
     observeWgpuDeviceLoss(deviceRuntime);
-    resolveLost('unknown' as GPUDeviceLostReason);
+    resolveLost('unknown' as WgpuDeviceLostReason);
     await settle();
     await settle();
     expect(emissions).toBe(1);

package/src/wgpuDraw.test.ts

@@ -1,22 +1,18 @@
+import type { Bitmap } from '@flighthq/bitmap/contract';
+import type { CompressedImageResource, ImageResource } from '@flighthq/image/contract';
+import { BlendMode } from '@flighthq/materials/contract';
 import { getOrCreateRenderProxy2D, prepareScene2DRender } from '@flighthq/render/contract';
 import { createSprite } from '@flighthq/scene2d/contract';
 import { getTextureSource } from '@flighthq/texture/contract';
-import type {
-  Bitmap,
-  CompressedImageResource,
-  ImageResource,
-  Texture,
-  WgpuTextureEntry,
-} from '@flighthq/types/contract';
+import type { Texture } from '@flighthq/texture/contract';
 import {
   BitmapTextureSourceKind,
-  BlendMode,
   CompressedImageTextureSourceKind,
   ImageTextureSourceKind,
-} from '@flighthq/types/contract';
+} from '@flighthq/texture/contract';
 
-import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
-import { registerWgpuCompressedTextureDecoder, registerWgpuCompressedTextureUpload } from './wgpuCompressedTexture';
+import type { WgpuTextureEntry } from './contract.render-wgpu-types.ts';
+import { registerWgpuCompressedTextureDecoder, registerWgpuCompressedTextureUpload } from './wgpuCompressedTexture.ts';
 import {
   applyWgpuBlendMode,
   bindWgpuBitmapTexture,
@@ -35,10 +31,11 @@ import {
   submitWgpuQuadDraw,
   updateWgpuTextureEntry,
   warmWgpuPipelines,
-} from './wgpuDraw';
-import { registerWgpuMipmapGeneration } from './wgpuMipmap';
-import { getWgpuRenderStateDeviceResources, getWgpuRenderStateRuntime } from './wgpuRenderState';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+} from './wgpuDraw.ts';
+import { submitWgpuFrame } from './wgpuFrame.ts';
+import { registerWgpuMipmapGeneration } from './wgpuMipmap.ts';
+import { getWgpuRenderStateDeviceResources, getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
 
 beforeAll(() => {
   installWgpuMock();
@@ -53,7 +50,7 @@ function bitmap(size: number, version: number): Bitmap {
   return {
     alphaType: 'straight',
     colorSpace: 'srgb',
-    data: new Uint8ClampedArray(size * size * 4),
+    data: new Uint8Array(size * size * 4),
     format: 'rgba8unorm',
     height: size,
     kind: BitmapTextureSourceKind,
@@ -185,8 +182,8 @@ describe('bindWgpuBitmapTexture mip allocation identity', () => {
 describe('bindWgpuCompressedImageTexture', () => {
   it('routes through the registered compressed upload seam', async () => {
     const state = await createWgpuRenderStateForTest();
-    const decode = vi.fn(() => new Uint8ClampedArray(4 * 4 * 4));
-    registerWgpuCompressedTextureUpload(state);
+    const decode = vi.fn(() => new Uint8Array(4 * 4 * 4));
+    registerWgpuCompressedTextureUpload(state, true);
     registerWgpuCompressedTextureDecoder(state, decode);
     const entry = bindWgpuCompressedImageTexture(state, compressedBc3Image());
     expect(entry?.texture).toBeDefined();
@@ -426,7 +423,7 @@ describe('destroyWgpuVideoTexture', () => {
 describe('drawWgpuQuad', () => {
   it('does not throw when render pass is open', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const bitmap = createSprite();
     prepareScene2DRender(state, bitmap);
     const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
@@ -435,14 +432,14 @@ describe('drawWgpuQuad', () => {
     canvas.height = 4;
     const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
     expect(() => drawWgpuQuad(state, renderProxy, entry, 0, 0, 4, 4, 0, 0, 1, 1)).not.toThrow();
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 });
 
 describe('drawWgpuQuadWithTransform', () => {
   it('does not throw when render pass is open', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const bitmap = createSprite();
     prepareScene2DRender(state, bitmap);
     const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
@@ -452,7 +449,7 @@ describe('drawWgpuQuadWithTransform', () => {
     const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
     const t = { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
     expect(() => drawWgpuQuadWithTransform(state, renderProxy, t, entry, 0, 0, 4, 4, 0, 0, 1, 1)).not.toThrow();
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 });
 
@@ -568,13 +565,13 @@ describe('resolveWgpuSmoothingBindGroup', () => {
 describe('submitWgpuQuadDraw', () => {
   it('does not throw when render pass is open', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const canvas = document.createElement('canvas');
     canvas.width = 4;
     canvas.height = 4;
     const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
     expect(() => submitWgpuQuadDraw(state, 0, resolveWgpuSmoothingBindGroup(state, entry, null))).not.toThrow();
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 
   it('is a no-op when render pass is null', async () => {

package/src/wgpuExternalImageSource.test.ts

@@ -1,5 +1,6 @@
-import { isWgpuExternalImageSourceReady, tryCopyWgpuExternalImageToTexture } from './wgpuExternalImageSource';
-import { createReadyImageElementForTest } from './wgpuTestHelper';
+import type { WgpuExternalImageSource, WgpuQueue, WgpuTexture } from './contract.render-wgpu-types.ts';
+import { isWgpuExternalImageSourceReady, tryCopyWgpuExternalImageToTexture } from './wgpuExternalImageSource.ts';
+import { createReadyImageElementForTest } from './wgpuTestHelper.ts';
 
 describe('isWgpuExternalImageSourceReady', () => {
   it('accepts a dimension-valid canvas without probing or binding its context', () => {
@@ -30,15 +31,15 @@ describe('isWgpuExternalImageSourceReady', () => {
   });
 
   it('rejects an unrecognized source instead of failing open', () => {
-    expect(isWgpuExternalImageSourceReady({} as GPUCopyExternalImageSource, 1, 1)).toBe(false);
+    expect(isWgpuExternalImageSourceReady({} as WgpuExternalImageSource, 1, 1)).toBe(false);
   });
 });
 
 describe('tryCopyWgpuExternalImageToTexture', () => {
   it('copies a ready source', () => {
     const copyExternalImageToTexture = vi.fn();
-    const queue = { copyExternalImageToTexture } as unknown as GPUQueue;
-    const texture = {} as GPUTexture;
+    const queue = { copyExternalImageToTexture } as unknown as WgpuQueue;
+    const texture = {} as WgpuTexture;
     const source = createReadyImageElementForTest(4, 4);
     expect(tryCopyWgpuExternalImageToTexture(queue, { source }, { texture }, 4, 4)).toBe(true);
     expect(copyExternalImageToTexture).toHaveBeenCalledWith({ source }, { texture }, [4, 4, 1]);
@@ -51,8 +52,8 @@ describe('tryCopyWgpuExternalImageToTexture', () => {
     const copyExternalImageToTexture = vi.fn(() => {
       throw new DOMException('canvas has no rendering context', 'OperationError');
     });
-    const queue = { copyExternalImageToTexture } as unknown as GPUQueue;
-    expect(tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as GPUTexture }, 4, 4)).toBe(
+    const queue = { copyExternalImageToTexture } as unknown as WgpuQueue;
+    expect(tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as WgpuTexture }, 4, 4)).toBe(
       false,
     );
   });
@@ -66,8 +67,8 @@ describe('tryCopyWgpuExternalImageToTexture', () => {
         "Failed to execute 'copyExternalImageToTexture' on 'GPUQueue': Failed to copy content from external image.",
       );
     });
-    const queue = { copyExternalImageToTexture } as unknown as GPUQueue;
-    expect(tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as GPUTexture }, 4, 4)).toBe(
+    const queue = { copyExternalImageToTexture } as unknown as WgpuQueue;
+    expect(tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as WgpuTexture }, 4, 4)).toBe(
       false,
     );
   });
@@ -81,9 +82,9 @@ describe('tryCopyWgpuExternalImageToTexture', () => {
       copyExternalImageToTexture: vi.fn(() => {
         throw error;
       }),
-    } as unknown as GPUQueue;
+    } as unknown as WgpuQueue;
     expect(() =>
-      tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as GPUTexture }, 4, 4),
+      tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as WgpuTexture }, 4, 4),
     ).toThrow(error);
   });
 });

package/src/wgpuExternalTexture.test.ts

@@ -1,14 +1,15 @@
 import { getTextureSourceKind } from '@flighthq/texture/contract';
-import { ExternalTextureSourceKind } from '@flighthq/types/contract';
+import { ExternalTextureSourceKind } from '@flighthq/texture/contract';
 
+import type { WgpuTexture } from './contract.render-wgpu-types.ts';
 import {
   createExternalWgpuTexture,
   disposeExternalWgpuTexture,
   initializeExternalWgpuTextureEntry,
   initializeExternalWgpuTextureSource,
-} from './wgpuExternalTexture';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
-import { resolveWgpuTexture } from './wgpuTextureResolver';
+} from './wgpuExternalTexture.ts';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
+import { resolveWgpuTexture } from './wgpuTextureResolver.ts';
 
 beforeAll(() => {
   installWgpuMock();
@@ -18,7 +19,7 @@ describe('createExternalWgpuTexture', () => {
   it('resolves a borrowed handle and forgets it without destroying the allocation', async () => {
     const state = await createWgpuRenderStateForTest();
     const destroy = vi.fn();
-    const handle = { createView: vi.fn(() => ({})), destroy } as unknown as GPUTexture;
+    const handle = { createView: vi.fn(() => ({})), destroy } as unknown as WgpuTexture;
     const texture = createExternalWgpuTexture(state, handle, { height: 16, width: 32 });
 
     expect(getTextureSourceKind(texture)).toBe(ExternalTextureSourceKind);
@@ -32,7 +33,7 @@ describe('createExternalWgpuTexture', () => {
 describe('disposeExternalWgpuTexture', () => {
   it('returns false after the borrowed handle has already been forgotten', async () => {
     const state = await createWgpuRenderStateForTest();
-    const handle = { createView: () => ({}) } as unknown as GPUTexture;
+    const handle = { createView: () => ({}) } as unknown as WgpuTexture;
     const texture = createExternalWgpuTexture(state, handle, { height: 1, width: 1 });
     expect(disposeExternalWgpuTexture(state, texture)).toBe(true);
     expect(disposeExternalWgpuTexture(state, texture)).toBe(false);

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

@@ -1,14 +1,13 @@
+import type { WgpuBuffer, WgpuTexture } from './contract.render-wgpu-types.ts';
 import {
   beginWgpuFrame,
-  renderWgpuBackground,
   retireWgpuBuffer,
   retireWgpuTexture,
-  submitWgpuRenderPass,
+  submitWgpuFrame,
   withWgpuFrameBorrow,
-} from './wgpuBackground';
-import { createWgpuPipeline } from './wgpuPipeline';
-import { createWgpuOffscreenRenderState, getWgpuRenderStateRuntime } from './wgpuRenderState';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+} from './wgpuFrame.ts';
+import { createWgpuOffscreenRenderState, getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
 
 beforeAll(() => installWgpuMock());
 
@@ -22,19 +21,10 @@ 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();
-    const buffer = { destroy: vi.fn() } as unknown as GPUBuffer;
+    const buffer = { destroy: vi.fn() } as unknown as WgpuBuffer;
     retireWgpuBuffer(state, buffer);
     expect(getWgpuRenderStateRuntime(state).retiredBuffers).toEqual([buffer]);
   });
@@ -43,29 +33,58 @@ describe('retireWgpuBuffer', () => {
 describe('retireWgpuTexture', () => {
   it('adds the texture to the post-submit destruction ledger', async () => {
     const state = await createWgpuRenderStateForTest();
-    const texture = { destroy: vi.fn() } as unknown as GPUTexture;
+    const texture = { destroy: vi.fn() } as unknown as WgpuTexture;
     retireWgpuTexture(state, texture);
     expect(getWgpuRenderStateRuntime(state).retiredTextures).toEqual([texture]);
   });
 });
 
-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', () => {
   it('returns callback values and closes a standalone frame', async () => {
     const screen = await createWgpuRenderStateForTest();
-    const offscreen = createWgpuOffscreenRenderState(
-      screen.deviceState,
-      createWgpuPipeline(getWgpuRenderStateRuntime(screen).registries),
-      { format: screen.format },
-    );
+    const offscreen = createWgpuOffscreenRenderState(screen.deviceState, {
+      ...getWgpuRenderStateRuntime(screen).registries,
+      format: screen.format,
+    });
 
     expect(withWgpuFrameBorrow(screen, offscreen, () => 42)).toBe(42);
     expect(getWgpuRenderStateRuntime(screen).commandEncoder).toBeNull();
@@ -75,11 +94,10 @@ describe('withWgpuFrameBorrow', () => {
   it('rejects a borrower owned by a different GPU device', async () => {
     const owner = await createWgpuRenderStateForTest();
     const other = await createWgpuRenderStateForTest();
-    const borrower = createWgpuOffscreenRenderState(
-      other.deviceState,
-      createWgpuPipeline(getWgpuRenderStateRuntime(other).registries),
-      { format: other.format },
-    );
+    const borrower = createWgpuOffscreenRenderState(other.deviceState, {
+      ...getWgpuRenderStateRuntime(other).registries,
+      format: other.format,
+    });
 
     expect(() => withWgpuFrameBorrow(owner, borrower, () => {})).toThrow(/same GPU device/);
     expect(getWgpuRenderStateRuntime(owner).commandEncoder).toBeNull();

package/src/wgpuFullscreenPass.test.ts

@@ -1,12 +1,12 @@
-import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
+import { submitWgpuFrame } from './wgpuFrame.ts';
 import {
   createWgpuFullscreenPipeline,
   destroyWgpuFullscreenPipeline,
   drawWgpuFullscreenPass,
   initializeWgpuFullscreenPipeline,
-} from './wgpuFullscreenPass';
-import { createWgpuRenderTarget } from './wgpuRenderTarget';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+} from './wgpuFullscreenPass.ts';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
+import { createWgpuTextureRenderTarget } from './wgpuTextureRenderTarget.ts';
 
 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();
   });
 });