@flighthq/render-wgpu 0.1.0

package/src/wgpuRenderState.test.ts

@@ -0,0 +1,88 @@
+import {
+  createWgpuRenderStateRuntime,
+  destroyWgpuRenderState,
+  getWgpuRenderStateRuntime,
+  isWgpuSupported,
+} from './wgpuRenderState';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('createWgpuRenderState', () => {
+  it('returns a render state with device and context', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(state.device).toBeDefined();
+    expect(state.context).toBeDefined();
+  });
+
+  it('sets allowSmoothing to true by default', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(state.allowSmoothing).toBe(true);
+  });
+
+  it('initialises uniform ring buffer', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    expect(runtime.uniformBuffer).toBeDefined();
+    expect(runtime.uniformData).toBeInstanceOf(Float32Array);
+    expect(runtime.uniformOffset).toBe(0);
+  });
+
+  it('stores the canvas', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(state.canvas).toBeInstanceOf(HTMLCanvasElement);
+  });
+
+  it('starts with null renderPass and commandEncoder', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    expect(runtime.renderPass).toBeNull();
+    expect(runtime.commandEncoder).toBeNull();
+  });
+});
+
+describe('createWgpuRenderStateRuntime', () => {
+  it('returns a runtime carrying the base entity-runtime binding slot', () => {
+    const runtime = createWgpuRenderStateRuntime();
+    expect(runtime.binding).toBeNull();
+  });
+});
+
+describe('destroyWgpuRenderState', () => {
+  it('destroys the state-owned uniform buffer', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    const destroy = vi.spyOn(runtime.uniformBuffer, 'destroy');
+
+    destroyWgpuRenderState(state);
+
+    expect(destroy).toHaveBeenCalled();
+  });
+
+  it('does not throw on a fresh state with no lazily-created buffers', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(() => destroyWgpuRenderState(state)).not.toThrow();
+  });
+});
+
+describe('getWgpuRenderStateRuntime', () => {
+  it('returns the runtime attached by createWgpuRenderState', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    expect(runtime).toBeDefined();
+    expect(runtime.uniformBuffer).toBeDefined();
+  });
+
+  it('resolves the same runtime object on repeated calls', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(getWgpuRenderStateRuntime(state)).toBe(getWgpuRenderStateRuntime(state));
+  });
+});
+
+describe('isWgpuSupported', () => {
+  it('returns true when navigator.gpu is present', () => {
+    expect(isWgpuSupported()).toBe(true);
+  });
+});

package/src/wgpuRenderTarget.test.ts

@@ -0,0 +1,120 @@
+import { createMatrix } from '@flighthq/geometry';
+
+import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import {
+  beginWgpuRenderTarget,
+  createWgpuRenderTarget,
+  destroyWgpuRenderTarget,
+  drawWgpuRenderTargetResult,
+  endWgpuRenderTarget,
+  resizeWgpuRenderTarget,
+} from './wgpuRenderTarget';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('beginWgpuRenderTarget', () => {
+  it('sets the render target viewport', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const target = createWgpuRenderTarget(state, 64, 64);
+    beginWgpuRenderTarget(state, target, createMatrix());
+    expect(getWgpuRenderStateRuntime(state).renderTargetViewport?.width).toBe(64);
+    endWgpuRenderTarget(state);
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('beginWgpuRenderTarget / endWgpuRenderTarget', () => {
+  it('switches the render target and restores it', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+
+    const target = createWgpuRenderTarget(state, 128, 128);
+    const transform = createMatrix();
+    beginWgpuRenderTarget(state, target, transform);
+
+    const runtime = getWgpuRenderStateRuntime(state);
+    expect(runtime.renderTargetViewport?.width).toBe(128);
+
+    endWgpuRenderTarget(state);
+    expect(runtime.renderTargetViewport).toBeNull();
+
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('createWgpuRenderTarget', () => {
+  it('returns a target with texture, view, bind group, and depth-stencil', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuRenderTarget(state, 256, 256);
+    expect(target.texture).toBeDefined();
+    expect(target.view).toBeDefined();
+    expect(target.bindGroup).toBeDefined();
+    expect(target.depthStencilTexture).toBeDefined();
+    expect(target.width).toBe(256);
+    expect(target.height).toBe(256);
+  });
+
+  it('clamps to minimum 1×1', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuRenderTarget(state, 0, 0);
+    expect(target.width).toBe(1);
+    expect(target.height).toBe(1);
+  });
+});
+
+describe('destroyWgpuRenderTarget', () => {
+  it('calls destroy on texture and depth-stencil', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuRenderTarget(state, 64, 64);
+    const destroyTexture = vi.spyOn(target.texture, 'destroy');
+    const destroyDepth = vi.spyOn(target.depthStencilTexture, 'destroy');
+    destroyWgpuRenderTarget(state, target);
+    expect(destroyTexture).toHaveBeenCalled();
+    expect(destroyDepth).toHaveBeenCalled();
+  });
+});
+
+describe('drawWgpuRenderTargetResult', () => {
+  it('does not throw with an open render pass', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const target = createWgpuRenderTarget(state, 64, 64);
+    const fakeNode = {
+      alpha: 1,
+      material: null,
+      transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    };
+    expect(() => drawWgpuRenderTargetResult(state, fakeNode, target, createMatrix())).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('endWgpuRenderTarget', () => {
+  it('restores null renderTargetViewport', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const target = createWgpuRenderTarget(state, 32, 32);
+    beginWgpuRenderTarget(state, target, createMatrix());
+    endWgpuRenderTarget(state);
+    expect(getWgpuRenderStateRuntime(state).renderTargetViewport).toBeNull();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('resizeWgpuRenderTarget', () => {
+  it('updates width, height, and bind group', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuRenderTarget(state, 64, 64);
+    const previousBindGroup = target.bindGroup;
+    resizeWgpuRenderTarget(state, target, 200, 150);
+    expect(target.width).toBe(200);
+    expect(target.height).toBe(150);
+    expect(target.bindGroup).toBeDefined();
+    expect(target.bindGroup).not.toBe(previousBindGroup);
+  });
+});

package/src/wgpuRenderTargetPool.test.ts

@@ -0,0 +1,58 @@
+import {
+  acquireWgpuRenderTarget,
+  createWgpuRenderTargetPool,
+  destroyWgpuRenderTargetPool,
+  releaseWgpuRenderTarget,
+} from './wgpuRenderTargetPool';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('acquireWgpuRenderTarget', () => {
+  it('reuses a released target matching width, height, and format', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTargetPool();
+    const first = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64 });
+    releaseWgpuRenderTarget(pool, first);
+    const second = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64 });
+    expect(second).toBe(first);
+  });
+
+  it('allocates a distinct target when no free target matches the format', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTargetPool();
+    const eight = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64 });
+    releaseWgpuRenderTarget(pool, eight);
+    const hdr = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64, format: 'rgba16float' });
+    expect(hdr).not.toBe(eight);
+    expect(hdr.format).toBe('rgba16float');
+  });
+});
+
+describe('createWgpuRenderTargetPool', () => {
+  it('starts with an empty free list', () => {
+    expect(createWgpuRenderTargetPool().free).toEqual([]);
+  });
+});
+
+describe('destroyWgpuRenderTargetPool', () => {
+  it('clears the free list', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTargetPool();
+    releaseWgpuRenderTarget(pool, acquireWgpuRenderTarget(state, pool, { width: 32, height: 32 }));
+    destroyWgpuRenderTargetPool(state, pool);
+    expect(pool.free.length).toBe(0);
+  });
+});
+
+describe('releaseWgpuRenderTarget', () => {
+  it('returns the target to the free list', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTargetPool();
+    const target = acquireWgpuRenderTarget(state, pool, { width: 16, height: 16 });
+    releaseWgpuRenderTarget(pool, target);
+    expect(pool.free).toContain(target);
+  });
+});

package/src/wgpuScissor.test.ts

@@ -0,0 +1,97 @@
+import { renderWgpuBackground } from './wgpuBackground';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { applyWgpuScissorRect, popWgpuScissorRect, pushWgpuScissorRect } from './wgpuScissor';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('applyWgpuScissorRect', () => {
+  it('calls setScissorRect on the pass when a rect is active', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(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;
+    applyWgpuScissorRect(state, fakePass);
+    expect(calls.length).toBe(1);
+    expect(calls[0]).toEqual([10, 20, 100, 50]);
+  });
+
+  it('is a no-op when currentScissorRect is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const calls: number[][] = [];
+    const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as GPURenderPassEncoder;
+    applyWgpuScissorRect(state, fakePass);
+    expect(calls.length).toBe(0);
+  });
+
+  it('clamps dimensions to at least 1×1', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(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;
+    applyWgpuScissorRect(state, fakePass);
+    expect(calls[0]).toEqual([0, 0, 1, 1]);
+  });
+});
+
+describe('popWgpuScissorRect', () => {
+  it('is a no-op when the stack is empty', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(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);
+    const r1 = { x: 0, y: 0, width: 100, height: 100 };
+    const r2 = { x: 10, y: 10, width: 50, height: 50 };
+    pushWgpuScissorRect(state, r1);
+    pushWgpuScissorRect(state, r2);
+    popWgpuScissorRect(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    expect(runtime.currentScissorRect).toEqual(r1);
+    popWgpuScissorRect(state);
+    expect(runtime.currentScissorRect).toBeNull();
+  });
+});
+
+describe('pushWgpuScissorRect', () => {
+  it('sets currentScissorRect on first push', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const rect = { x: 5, y: 10, width: 80, height: 40 };
+    pushWgpuScissorRect(state, rect);
+    expect(getWgpuRenderStateRuntime(state).currentScissorRect).toEqual(rect);
+  });
+
+  it('stacks previous rect when pushing a second rect', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const r1 = { x: 0, y: 0, width: 100, height: 100 };
+    const r2 = { x: 20, y: 20, width: 60, height: 60 };
+    pushWgpuScissorRect(state, r1);
+    pushWgpuScissorRect(state, r2);
+    const runtime = getWgpuRenderStateRuntime(state);
+    expect(runtime.currentScissorRect).toEqual(r2);
+    expect(runtime.scissorStack.length).toBe(1);
+    expect(runtime.scissorStack[0]).toEqual(r1);
+  });
+
+  it('copies the rect so mutation of the original does not affect the pushed value', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const rect = { x: 0, y: 0, width: 50, height: 50 };
+    pushWgpuScissorRect(state, rect);
+    rect.width = 999;
+    expect(getWgpuRenderStateRuntime(state).currentScissorRect?.width).toBe(50);
+  });
+});

package/src/wgpuShader.test.ts

@@ -0,0 +1,140 @@
+import { renderWgpuBackground } from './wgpuBackground';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import {
+  createWgpuBindGroupLayouts,
+  createWgpuPipelineLayout,
+  getActiveWgpuPipeline,
+  getWgpuPipeline,
+  setWgpuMatrixFromTransform,
+  UNIFORM_BYTE_SIZE,
+  writeWgpuMatrixOnlyUniforms,
+  writeWgpuQuadUniforms,
+} from './wgpuShader';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('createWgpuBindGroupLayouts', () => {
+  it('returns uniformBindGroupLayout and textureBindGroupLayout', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const layouts = createWgpuBindGroupLayouts(state.device);
+    expect(layouts.uniformBindGroupLayout).toBeDefined();
+    expect(layouts.textureBindGroupLayout).toBeDefined();
+  });
+});
+
+describe('createWgpuPipelineLayout', () => {
+  it('returns a pipeline layout', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    const layout = createWgpuPipelineLayout(
+      state.device,
+      runtime.uniformBindGroupLayout,
+      runtime.textureBindGroupLayout,
+    );
+    expect(layout).toBeDefined();
+  });
+});
+
+describe('getActiveWgpuPipeline', () => {
+  it('returns the normal pipeline when no mask is active', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    runtime.currentMaskDepth = 0;
+    runtime.maskWriteMode = false;
+    const pipeline = getActiveWgpuPipeline(state);
+    expect(pipeline).toBeDefined();
+  });
+});
+
+describe('getWgpuPipeline', () => {
+  it('returns a cached pipeline on second call', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const p1 = getWgpuPipeline(state, null, 'normal');
+    const p2 = getWgpuPipeline(state, null, 'normal');
+    expect(p1).toBe(p2);
+  });
+
+  it('returns different pipelines for different stencil modes', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const normal = getWgpuPipeline(state, null, 'normal');
+    const maskwrite = getWgpuPipeline(state, null, 'maskwrite');
+    expect(normal).not.toBe(maskwrite);
+  });
+});
+
+describe('setWgpuMatrixFromTransform', () => {
+  it('builds a column-major clip-space matrix from an identity transform', () => {
+    const m = new Float32Array(9);
+    setWgpuMatrixFromTransform(m, { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 }, { width: 2, height: 2 });
+    // Identity scale on a 2×2 viewport: a*iw=1, -d*ih=-1, tx*iw-1=-1, -ty*ih+1=1
+    expect(m[0]).toBeCloseTo(1);
+    expect(m[4]).toBeCloseTo(-1);
+    expect(m[6]).toBeCloseTo(-1);
+    expect(m[7]).toBeCloseTo(1);
+  });
+
+  it('builds a distinct out from aliased inputs (out === input matrix)', () => {
+    const m = new Float32Array(9);
+    setWgpuMatrixFromTransform(m, { a: 2, b: 0, c: 0, d: 2, tx: 100, ty: 50 }, { width: 400, height: 300 });
+    expect(m[0]).toBeCloseTo(2 * (2 / 400));
+  });
+});
+
+describe('UNIFORM_BYTE_SIZE', () => {
+  it('is 128 bytes', () => {
+    expect(UNIFORM_BYTE_SIZE).toBe(128);
+  });
+});
+
+describe('writeWgpuMatrixOnlyUniforms', () => {
+  it('advances uniformOffset', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    renderWgpuBackground(state);
+    const before = runtime.uniformOffset;
+    const fakeNode = { alpha: 1, useColorTransform: false, colorTransform: null };
+    const t = { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
+    writeWgpuMatrixOnlyUniforms(state, fakeNode as never, t, 0, 0, 10, 10, 0, 0, 1, 1);
+    expect(runtime.uniformOffset).toBe(before + runtime.uniformStride);
+  });
+});
+
+describe('writeWgpuQuadUniforms', () => {
+  it('advances uniformOffset by uniformStride', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    renderWgpuBackground(state);
+    const before = runtime.uniformOffset;
+    const fakeNode = {
+      alpha: 1,
+      useColorTransform: false,
+      colorTransform: null,
+      transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    };
+    writeWgpuQuadUniforms(state, fakeNode, null, 0, 0, 100, 100, 0, 0, 1, 1);
+    expect(runtime.uniformOffset).toBe(before + runtime.uniformStride);
+  });
+
+  it('writes quad coordinates into uniform data at float offset 24', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    renderWgpuBackground(state);
+    const fakeNode = {
+      alpha: 0.5,
+      useColorTransform: false,
+      colorTransform: null,
+      transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    };
+    const offset = writeWgpuQuadUniforms(state, fakeNode, null, 10, 20, 30, 40, 0.1, 0.2, 0.9, 0.8);
+    const floatBase = offset >> 2;
+    expect(runtime.uniformData[floatBase + 24]).toBeCloseTo(10);
+    expect(runtime.uniformData[floatBase + 25]).toBeCloseTo(20);
+    expect(runtime.uniformData[floatBase + 26]).toBeCloseTo(30);
+    expect(runtime.uniformData[floatBase + 27]).toBeCloseTo(40);
+    expect(runtime.uniformData[floatBase + 28]).toBeCloseTo(0.1);
+    expect(runtime.uniformData[floatBase + 12]).toBeCloseTo(0.5); // alpha
+  });
+});

package/src/wgpuShaderBinding.test.ts

@@ -0,0 +1,62 @@
+import { createBitmap } from '@flighthq/displayobject';
+import { getOrCreateRenderProxy2D } from '@flighthq/render';
+import type { WgpuBitmapShader } from '@flighthq/types';
+
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { getWgpuShader, resolveWgpuShader, setWgpuShader } from './wgpuShaderBinding';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('getWgpuShader', () => {
+  it('returns undefined when no shader is bound', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const bitmap = createBitmap();
+    const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
+    expect(getWgpuShader(renderProxy)).toBeUndefined();
+  });
+});
+
+describe('resolveWgpuShader', () => {
+  it('returns null when no shader feature is enabled', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const bitmap = createBitmap();
+    const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
+    expect(resolveWgpuShader(state, renderProxy)).toBeNull();
+  });
+});
+
+describe('setWgpuShader', () => {
+  it('binds a shader to a display object', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const bitmap = createBitmap();
+    const fakeShader: WgpuBitmapShader = { pipeline: {} as never, bind: () => {} };
+
+    setWgpuShader(state, bitmap, fakeShader);
+
+    const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
+    expect(getWgpuShader(renderProxy)).toBe(fakeShader);
+  });
+
+  it('installs the per-node shader binding resolver', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    const bitmap = createBitmap();
+    const fakeShader: WgpuBitmapShader = { pipeline: {} as never, bind: () => {} };
+    expect(runtime.webgpuShaderBindingResolver).toBeUndefined();
+    setWgpuShader(state, bitmap, fakeShader);
+    expect(runtime.webgpuShaderBindingResolver).toBe(getWgpuShader);
+  });
+
+  it('removes the binding when shader is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const bitmap = createBitmap();
+    const fakeShader: WgpuBitmapShader = { pipeline: {} as never, bind: () => {} };
+    setWgpuShader(state, bitmap, fakeShader);
+    setWgpuShader(state, bitmap, null);
+    const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
+    expect(getWgpuShader(renderProxy)).toBeUndefined();
+  });
+});

package/src/wgpuShaderRegistry.test.ts

@@ -0,0 +1,30 @@
+import type { WgpuBitmapShader } from '@flighthq/types';
+
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { registerWgpuBitmapShader } from './wgpuShaderRegistry';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('registerWgpuBitmapShader', () => {
+  it('sets the shader as the state default', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const fakeShader = {
+      pipeline: {},
+      bind: () => {},
+    } as unknown as WgpuBitmapShader;
+    registerWgpuBitmapShader(state, fakeShader);
+    expect(getWgpuRenderStateRuntime(state).defaultBitmapShader).toBe(fakeShader);
+  });
+
+  it('replaces a previously registered shader', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const shader1 = { pipeline: {}, bind: () => {} } as unknown as WgpuBitmapShader;
+    const shader2 = { pipeline: {}, bind: () => {} } as unknown as WgpuBitmapShader;
+    registerWgpuBitmapShader(state, shader1);
+    registerWgpuBitmapShader(state, shader2);
+    expect(getWgpuRenderStateRuntime(state).defaultBitmapShader).toBe(shader2);
+  });
+});

package/src/wgpuSurface.test.ts

@@ -0,0 +1,49 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import {
+  acquireWgpuFrameCaptureTexture,
+  createSurfaceFromWgpuRenderState,
+  enableWgpuFrameCapture,
+  encodeWgpuFrameCapture,
+} from './wgpuSurface';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('acquireWgpuFrameCaptureTexture', () => {
+  it('returns null until capture is enabled, then an offscreen texture', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(acquireWgpuFrameCaptureTexture(state)).toBeNull();
+    enableWgpuFrameCapture(state);
+    expect(acquireWgpuFrameCaptureTexture(state)).not.toBeNull();
+  });
+});
+
+describe('createSurfaceFromWgpuRenderState', () => {
+  it('throws when frame capture was never enabled (no buffer to read)', async () => {
+    const state = await createWgpuRenderStateForTest();
+    await expect(createSurfaceFromWgpuRenderState(state)).rejects.toThrow(/enableWgpuFrameCapture/);
+  });
+});
+
+describe('enableWgpuFrameCapture', () => {
+  it('sets the capture flag on the render state runtime', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(getWgpuRenderStateRuntime(state).frameCaptureEnabled).toBeFalsy();
+    enableWgpuFrameCapture(state);
+    expect(getWgpuRenderStateRuntime(state).frameCaptureEnabled).toBe(true);
+  });
+});
+
+describe('encodeWgpuFrameCapture', () => {
+  it('is a no-op when capture is disabled', async () => {
+    const state = await createWgpuRenderStateForTest();
+    let copied = false;
+    const encoder = { copyTextureToBuffer: () => (copied = true) } as unknown as GPUCommandEncoder;
+    encodeWgpuFrameCapture(state, encoder);
+    expect(copied).toBe(false);
+  });
+});