@flighthq/render-wgpu 0.3.0-next.906.07cea63 → 0.3.1-next.209.43ef1bc

package/src/wgpuRenderState.test.ts

@@ -1,4 +1,17 @@
+import { createEntity } from '@flighthq/entity/contract';
 import {
+  copyAllRenderersFromRenderState,
+  getRenderStateRuntime,
+  prepareScene2DRender,
+  registerRenderer,
+} from '@flighthq/render/contract';
+import { createDisplayObject } from '@flighthq/scene2d/contract';
+
+import { beginWgpuFrame } from './wgpuBackground';
+import { registerWgpuMaterialRenderer } from './wgpuMaterialRegistry';
+import {
+  copyWgpuRenderStateRegistrations,
+  createWgpuOffscreenRenderState,
   createWgpuRenderStateRuntime,
   destroyWgpuRenderState,
   getWgpuRenderStateRuntime,
@@ -6,11 +19,121 @@ import {
   isWgpuSupported,
 } from './wgpuRenderState';
 import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { registerWgpuTextureResolver } from './wgpuTextureResolver';
 
 beforeAll(() => {
   installWgpuMock();
 });
 
+describe('copyWgpuRenderStateRegistrations', () => {
+  it('copies late Wgpu registrations only when explicitly requested', async () => {
+    const screen = await createWgpuRenderStateForTest();
+    const offscreen = createWgpuOffscreenRenderState(screen);
+    const resolver = vi.fn(() => null);
+    registerWgpuTextureResolver(screen, 'acme.LateTexture', resolver);
+
+    expect(getWgpuRenderStateRuntime(offscreen).wgpuTextureResolverRegistry?.has('acme.LateTexture')).not.toBe(true);
+    copyWgpuRenderStateRegistrations(offscreen, screen);
+    expect(getWgpuRenderStateRuntime(offscreen).wgpuTextureResolverRegistry?.get('acme.LateTexture')).toBe(resolver);
+  });
+});
+
+describe('createWgpuOffscreenRenderState', () => {
+  it('shares device resources while snapshotting independent registration policy', async () => {
+    const screen = await createWgpuRenderStateForTest();
+    const renderer = { createData: () => null, submit: vi.fn() };
+    const materialRenderer = { instanceFloatCount: 0, getShaderModule: vi.fn() } as never;
+    const paddingResolver = vi.fn(() => ({ bottom: 1, left: 1, right: 1, top: 1 }));
+    const textureResolver = vi.fn(() => null);
+    const effectRunner = vi.fn();
+    registerRenderer(screen, 'acme.Node', renderer);
+    registerWgpuMaterialRenderer(screen, 'acme.Material', materialRenderer);
+    registerWgpuTextureResolver(screen, 'acme.Texture', textureResolver);
+    getRenderStateRuntime(screen).renderEffectPaddingResolverRegistry = new Map([['acme.Effect', paddingResolver]]);
+    getWgpuRenderStateRuntime(screen).wgpuRenderEffectRegistry = new Map([['acme.Effect', effectRunner]]);
+    getWgpuRenderStateRuntime(screen).wgpuRenderTextureCache = new WeakMap();
+
+    const offscreen = createWgpuOffscreenRenderState(screen);
+    const screenRuntime = getWgpuRenderStateRuntime(screen);
+    const offscreenRuntime = getWgpuRenderStateRuntime(offscreen);
+
+    expect(offscreen.device).toBe(screen.device);
+    expect(offscreen.canvas).toBe(screen.canvas);
+    expect(offscreenRuntime.pipelineCache).toBe(screenRuntime.pipelineCache);
+    expect(offscreenRuntime.textureCache).toBe(screenRuntime.textureCache);
+    expect(offscreenRuntime.wgpuRenderTextureCache).toBe(screenRuntime.wgpuRenderTextureCache);
+    expect(offscreenRuntime.uniformBindGroupLayout).toBe(screenRuntime.uniformBindGroupLayout);
+    expect(offscreenRuntime.uniformBuffer).not.toBe(screenRuntime.uniformBuffer);
+    expect(offscreenRuntime.rendererMap).not.toBe(screenRuntime.rendererMap);
+    expect(offscreenRuntime.materialRendererMap).not.toBe(screenRuntime.materialRendererMap);
+    expect(offscreenRuntime.wgpuTextureResolverRegistry).not.toBe(screenRuntime.wgpuTextureResolverRegistry);
+    expect(offscreenRuntime.wgpuRenderEffectRegistry).not.toBe(screenRuntime.wgpuRenderEffectRegistry);
+    expect(offscreenRuntime.renderEffectPaddingResolverRegistry).not.toBe(
+      screenRuntime.renderEffectPaddingResolverRegistry,
+    );
+    expect(offscreenRuntime.rendererMap.get('acme.Node')).toBe(renderer);
+    expect(offscreenRuntime.materialRendererMap?.get('acme.Material')).toBe(materialRenderer);
+    expect(offscreenRuntime.wgpuTextureResolverRegistry?.get('acme.Texture')).toBe(textureResolver);
+    expect(offscreenRuntime.wgpuRenderEffectRegistry?.get('acme.Effect')).toBe(effectRunner);
+    expect(offscreenRuntime.renderEffectPaddingResolverRegistry?.get('acme.Effect')).toBe(paddingResolver);
+  });
+
+  it('owns an independent encoder and proxy tree', async () => {
+    const screen = await createWgpuRenderStateForTest();
+    const offscreen = createWgpuOffscreenRenderState(screen);
+    const root = createDisplayObject();
+    registerRenderer(offscreen, root.kind, { createData: () => createEntity({}), submit: vi.fn() });
+    prepareScene2DRender(offscreen, root);
+    beginWgpuFrame(screen);
+    beginWgpuFrame(offscreen);
+
+    expect(getRenderStateRuntime(offscreen).renderProxyMap).not.toBe(getRenderStateRuntime(screen).renderProxyMap);
+    expect(getWgpuRenderStateRuntime(offscreen).commandEncoder).not.toBe(
+      getWgpuRenderStateRuntime(screen).commandEncoder,
+    );
+  });
+
+  it('destroys derived renderer data and its own uniform ring without freeing the screen ring', async () => {
+    const screen = await createWgpuRenderStateForTest();
+    const root = createDisplayObject();
+    const destroyData = vi.fn();
+    registerRenderer(screen, root.kind, {
+      createData: () => createEntity({}),
+      destroyData,
+      submit: vi.fn(),
+    });
+    const offscreen = createWgpuOffscreenRenderState(screen);
+    prepareScene2DRender(offscreen, root);
+    const screenDestroy = vi.spyOn(getWgpuRenderStateRuntime(screen).uniformBuffer, 'destroy');
+    const offscreenDestroy = vi.spyOn(getWgpuRenderStateRuntime(offscreen).uniformBuffer, 'destroy');
+
+    destroyWgpuRenderState(offscreen);
+
+    expect(destroyData).toHaveBeenCalledOnce();
+    expect(offscreenDestroy).toHaveBeenCalledOnce();
+    expect(screenDestroy).not.toHaveBeenCalled();
+  });
+
+  it('requires explicit re-copy for renderers and padding registered after derivation', async () => {
+    const screen = await createWgpuRenderStateForTest();
+    const offscreen = createWgpuOffscreenRenderState(screen);
+    const renderer = { createData: () => null, submit: vi.fn() };
+    const paddingResolver = vi.fn(() => ({ bottom: 2, left: 2, right: 2, top: 2 }));
+    registerRenderer(screen, 'acme.LateNode', renderer);
+    getRenderStateRuntime(screen).renderEffectPaddingResolverRegistry = new Map([['acme.LateEffect', paddingResolver]]);
+
+    expect(getRenderStateRuntime(offscreen).rendererMap.has('acme.LateNode')).toBe(false);
+    expect(getRenderStateRuntime(offscreen).renderEffectPaddingResolverRegistry?.has('acme.LateEffect')).not.toBe(true);
+
+    copyAllRenderersFromRenderState(offscreen, screen);
+    copyWgpuRenderStateRegistrations(offscreen, screen);
+    expect(getRenderStateRuntime(offscreen).rendererMap.get('acme.LateNode')).toBe(renderer);
+    expect(getRenderStateRuntime(offscreen).renderEffectPaddingResolverRegistry?.get('acme.LateEffect')).toBe(
+      paddingResolver,
+    );
+  });
+});
+
 describe('createWgpuRenderState', () => {
   it('returns a render state with device and context', async () => {
     const state = await createWgpuRenderStateForTest();
@@ -85,8 +208,8 @@ describe('getWgpuRenderStateRuntime', () => {
 describe('getWgpuSampler', () => {
   it('caches a sampler per filter+wrap+mip+anisotropy config and reuses it (one createSampler)', async () => {
     const state = await createWgpuRenderStateForTest();
-    const a = getWgpuSampler(state, 'linear', 'repeat', 'repeat');
-    const b = getWgpuSampler(state, 'linear', 'repeat', 'repeat');
+    const a = getWgpuSampler(state, 'linear', 'linear', 'repeat', 'repeat');
+    const b = getWgpuSampler(state, 'linear', 'linear', 'repeat', 'repeat');
     expect(a).toBe(b);
     // The cache is keyed by a packed NUMBER (no per-call string allocation), and one config caches once.
     expect([...getWgpuRenderStateRuntime(state).samplerCache.keys()].every((k) => typeof k === 'number')).toBe(true);
@@ -95,17 +218,17 @@ describe('getWgpuSampler', () => {
 
   it('returns a distinct sampler for a different wrap or filter', async () => {
     const state = await createWgpuRenderStateForTest();
-    const repeat = getWgpuSampler(state, 'linear', 'repeat', 'repeat');
-    const clamp = getWgpuSampler(state, 'linear', 'clamp-to-edge', 'clamp-to-edge');
-    const nearest = getWgpuSampler(state, 'nearest', 'repeat', 'repeat');
+    const repeat = getWgpuSampler(state, 'linear', 'linear', 'repeat', 'repeat');
+    const clamp = getWgpuSampler(state, 'linear', 'linear', 'clamp-to-edge', 'clamp-to-edge');
+    const nearest = getWgpuSampler(state, 'nearest', 'nearest', 'repeat', 'repeat');
     expect(repeat).not.toBe(clamp);
     expect(repeat).not.toBe(nearest);
   });
 
   it('keys the mip filter separately so a trilinear sampler differs from a non-mip one', async () => {
     const state = await createWgpuRenderStateForTest();
-    const noMip = getWgpuSampler(state, 'linear', 'repeat', 'repeat');
-    const trilinear = getWgpuSampler(state, 'linear', 'repeat', 'repeat', 'linear');
+    const noMip = getWgpuSampler(state, 'linear', 'linear', 'repeat', 'repeat');
+    const trilinear = getWgpuSampler(state, 'linear', 'linear', 'repeat', 'repeat', 'linear');
     expect(noMip).not.toBe(trilinear);
     expect(getWgpuRenderStateRuntime(state).samplerCache.size).toBe(2);
   });
@@ -114,18 +237,27 @@ describe('getWgpuSampler', () => {
     // WebGPU rejects maxAnisotropy > 1 unless min/mag/mip are all linear, so a nearest+aniso request
     // collapses to the SAME sampler as the explicit linear/trilinear anisotropic request.
     const state = await createWgpuRenderStateForTest();
-    const collapsed = getWgpuSampler(state, 'nearest', 'clamp-to-edge', 'clamp-to-edge', undefined, 8);
-    const explicit = getWgpuSampler(state, 'linear', 'clamp-to-edge', 'clamp-to-edge', 'linear', 8);
+    const collapsed = getWgpuSampler(state, 'nearest', 'nearest', 'clamp-to-edge', 'clamp-to-edge', undefined, 8);
+    const explicit = getWgpuSampler(state, 'linear', 'linear', 'clamp-to-edge', 'clamp-to-edge', 'linear', 8);
     expect(collapsed).toBe(explicit);
   });
 
   it('floors and clamps the anisotropy level into the cache key', async () => {
     const state = await createWgpuRenderStateForTest();
-    const a = getWgpuSampler(state, 'linear', 'repeat', 'repeat', 'linear', 4.9);
-    const b = getWgpuSampler(state, 'linear', 'repeat', 'repeat', 'linear', 4);
+    const a = getWgpuSampler(state, 'linear', 'linear', 'repeat', 'repeat', 'linear', 4.9);
+    const b = getWgpuSampler(state, 'linear', 'linear', 'repeat', 'repeat', 'linear', 4);
     expect(a).toBe(b);
     expect(getWgpuRenderStateRuntime(state).samplerCache.size).toBe(1);
   });
+
+  it('keeps independent minification and magnification filters', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const createSampler = vi.spyOn(state.device, 'createSampler');
+    getWgpuSampler(state, 'nearest', 'linear', 'repeat', 'repeat');
+    expect(createSampler).toHaveBeenLastCalledWith(
+      expect.objectContaining({ minFilter: 'nearest', magFilter: 'linear' }),
+    );
+  });
 });
 
 describe('isWgpuSupported', () => {

package/src/wgpuRenderTarget.test.ts

@@ -155,6 +155,20 @@ describe('endWgpuRenderPass', () => {
 });
 
 describe('resizeWgpuRenderTarget', () => {
+  it('preserves the allocation when dimensions are unchanged', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuRenderTarget(state, 64, 64);
+    const texture = target.texture;
+    const depthStencilTexture = target.depthStencilTexture;
+    const bindGroup = target.bindGroup;
+
+    resizeWgpuRenderTarget(state, target, 64, 64);
+
+    expect(target.texture).toBe(texture);
+    expect(target.depthStencilTexture).toBe(depthStencilTexture);
+    expect(target.bindGroup).toBe(bindGroup);
+  });
+
   it('updates width, height, and bind group', async () => {
     const state = await createWgpuRenderStateForTest();
     const target = createWgpuRenderTarget(state, 64, 64);

package/src/wgpuRenderTexture.test.ts

@@ -0,0 +1,165 @@
+import type { RenderTexture } from '@flighthq/types/contract';
+import { RenderTargetTextureSourceKind } from '@flighthq/types/contract';
+
+import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import {
+  bindWgpuRenderTexture,
+  destroyWgpuRenderTexture,
+  explainWgpuRenderTexture,
+  getWgpuRenderTextureTarget,
+  invalidateWgpuRenderTexture,
+  isWgpuRenderTextureReady,
+  renderIntoWgpuRenderTexture,
+  setWgpuRenderTextureGuard,
+  writeWgpuRenderTextureTarget,
+} from './wgpuRenderTexture';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+function texture(): RenderTexture {
+  return {
+    colorSpace: 'linear',
+    flipX: false,
+    flipY: false,
+    sampler: {
+      anisotropy: 1,
+      magFilter: 'linear',
+      minFilter: 'linear',
+      mipmaps: false,
+      wrapU: 'clamp-to-edge',
+      wrapV: 'clamp-to-edge',
+    },
+    dimension: '2d',
+    source: { height: 8, kind: RenderTargetTextureSourceKind, version: 0, width: 8 },
+    uvOffset: { x: 0, y: 0 },
+    uvRotation: 0,
+    uvScale: { x: 1, y: 1 },
+    version: 0,
+  } as unknown as RenderTexture;
+}
+
+describe('bindWgpuRenderTexture', () => {
+  it('returns null before render and the state-owned target after render', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+    expect(bindWgpuRenderTexture(state, renderTexture)).toBeNull();
+
+    renderWgpuBackground(state);
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+    expect(bindWgpuRenderTexture(state, renderTexture)).not.toBeNull();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('destroyWgpuRenderTexture', () => {
+  it('destroys and removes the hidden target', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+    renderWgpuBackground(state);
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+    const entry = getWgpuRenderStateRuntime(state).wgpuRenderTextureCache!.get(renderTexture)!;
+    const destroy = vi.spyOn(entry.target.texture, 'destroy');
+
+    destroyWgpuRenderTexture(state, renderTexture);
+    expect(destroy).toHaveBeenCalled();
+    expect(bindWgpuRenderTexture(state, renderTexture)).toBeNull();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('explainWgpuRenderTexture', () => {
+  it('reports source dimensions and lifecycle status before allocation', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(explainWgpuRenderTexture(state, texture())).toEqual({ height: 8, status: 'unrendered', width: 8 });
+  });
+});
+
+describe('getWgpuRenderTextureTarget', () => {
+  it('returns the hidden target only after a completed write', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+
+    expect(getWgpuRenderTextureTarget(state, renderTexture)).toBeNull();
+    writeWgpuRenderTextureTarget(state, renderTexture, () => {});
+    expect(getWgpuRenderTextureTarget(state, renderTexture)).not.toBeNull();
+  });
+});
+
+describe('invalidateWgpuRenderTexture', () => {
+  it('makes published content unavailable without destroying its target', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+    writeWgpuRenderTextureTarget(state, renderTexture, () => {});
+    const target = getWgpuRenderTextureTarget(state, renderTexture)!;
+    const destroy = vi.spyOn(target.texture, 'destroy');
+
+    invalidateWgpuRenderTexture(state, renderTexture);
+
+    expect(getWgpuRenderTextureTarget(state, renderTexture)).toBeNull();
+    expect(destroy).not.toHaveBeenCalled();
+  });
+});
+
+describe('isWgpuRenderTextureReady', () => {
+  it('tracks the successful rendered-content transition', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+    expect(isWgpuRenderTextureReady(state, renderTexture)).toBe(false);
+    renderWgpuBackground(state);
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+    expect(isWgpuRenderTextureReady(state, renderTexture)).toBe(true);
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('renderIntoWgpuRenderTexture', () => {
+  it('restores the enclosing pass and bumps version after success', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+    renderWgpuBackground(state);
+    const enclosingPass = getWgpuRenderStateRuntime(state).renderPass;
+
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+
+    expect(renderTexture.version).toBe(1);
+    expect(renderTexture.colorSpace).toBe('linear');
+    expect(getWgpuRenderStateRuntime(state).renderPass).not.toBeNull();
+    expect(getWgpuRenderStateRuntime(state).renderPass).not.toBe(enclosingPass);
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('setWgpuRenderTextureGuard', () => {
+  it('installs and removes the lifecycle diagnostic callback', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+    const guard = vi.fn();
+
+    setWgpuRenderTextureGuard(state, guard);
+    bindWgpuRenderTexture(state, renderTexture);
+    expect(guard).toHaveBeenCalledOnce();
+
+    setWgpuRenderTextureGuard(state, null);
+    bindWgpuRenderTexture(state, renderTexture);
+    expect(guard).toHaveBeenCalledOnce();
+  });
+});
+
+describe('writeWgpuRenderTextureTarget', () => {
+  it('passes the hidden target to the producer and publishes the completed write', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const renderTexture = texture();
+    const producer = vi.fn();
+
+    writeWgpuRenderTextureTarget(state, renderTexture, producer);
+
+    expect(producer).toHaveBeenCalledOnce();
+    expect(producer.mock.calls[0][0]).toBe(getWgpuRenderTextureTarget(state, renderTexture));
+    expect(renderTexture.version).toBe(1);
+    expect(isWgpuRenderTextureReady(state, renderTexture)).toBe(true);
+  });
+});

package/src/wgpuRenderTexturePool.test.ts

@@ -0,0 +1,146 @@
+import {
+  explainWgpuRenderTexture,
+  getWgpuRenderTextureTarget,
+  isWgpuRenderTextureReady,
+  writeWgpuRenderTextureTarget,
+} from './wgpuRenderTexture';
+import {
+  acquireWgpuRenderTexture,
+  createWgpuRenderTexturePool,
+  destroyWgpuRenderTexturePool,
+  releaseWgpuRenderTexture,
+  withWgpuRenderTextures,
+} from './wgpuRenderTexturePool';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => installWgpuMock());
+
+describe('acquireWgpuRenderTexture', () => {
+  it('reuses a released handle and reapplies dimensions before the next write', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTexturePool();
+    const first = acquireWgpuRenderTexture(state, pool, { width: 32, height: 16 });
+    writeWgpuRenderTextureTarget(state, first, () => {});
+    releaseWgpuRenderTexture(state, pool, first);
+
+    expect(explainWgpuRenderTexture(state, first).status).toBe('released');
+    expect(isWgpuRenderTextureReady(state, first)).toBe(false);
+
+    const second = acquireWgpuRenderTexture(state, pool, { width: 80, height: 48 });
+    expect(second).toBe(first);
+    expect(second.source.width).toBe(80);
+    expect(second.source.height).toBe(48);
+    expect(explainWgpuRenderTexture(state, second).status).toBe('unrendered');
+
+    writeWgpuRenderTextureTarget(state, second, () => {});
+    expect(explainWgpuRenderTexture(state, second)).toEqual({ width: 80, height: 48, status: 'ready' });
+  });
+
+  it('resets a released slab view before exposing the next logical target', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTexturePool();
+    const slabView = acquireWgpuRenderTexture(state, pool, { width: 720, height: 480 });
+    slabView.flipX = true;
+    slabView.flipY = true;
+    slabView.uvOffset.x = 140 / 720;
+    slabView.uvOffset.y = 160 / 480;
+    slabView.uvRotation = Math.PI / 2;
+    slabView.uvScale.x = 100 / 720;
+    slabView.uvScale.y = 80 / 480;
+    releaseWgpuRenderTexture(state, pool, slabView);
+
+    const logicalTarget = acquireWgpuRenderTexture(state, pool, { width: 100, height: 80 });
+
+    expect(logicalTarget).toBe(slabView);
+    expect(logicalTarget).toMatchObject({
+      flipX: false,
+      flipY: false,
+      uvOffset: { x: 0, y: 0 },
+      uvRotation: 0,
+      uvScale: { x: 1, y: 1 },
+    });
+  });
+
+  it('does not allow a pool to cross GPU devices', async () => {
+    const a = await createWgpuRenderStateForTest();
+    const b = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTexturePool();
+    acquireWgpuRenderTexture(a, pool, { width: 8, height: 8 });
+
+    expect(() => acquireWgpuRenderTexture(b, pool, { width: 8, height: 8 })).toThrow('cannot cross GPU devices');
+  });
+});
+
+describe('createWgpuRenderTexturePool', () => {
+  it('creates an empty device-unbound pool', () => {
+    const pool = createWgpuRenderTexturePool();
+    expect(pool.device).toBeNull();
+    expect(pool.destroyed).toBe(false);
+    expect(pool.free).toEqual([]);
+    expect(pool.leased.size).toBe(0);
+  });
+});
+
+describe('destroyWgpuRenderTexturePool', () => {
+  it('destroys hidden targets for free and outstanding leases', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTexturePool();
+    const free = acquireWgpuRenderTexture(state, pool, { width: 8, height: 8 });
+    const leased = acquireWgpuRenderTexture(state, pool, { width: 16, height: 16 });
+    writeWgpuRenderTextureTarget(state, free, () => {});
+    writeWgpuRenderTextureTarget(state, leased, () => {});
+    const destroyFree = vi.spyOn(getWgpuRenderTextureTarget(state, free)!.texture, 'destroy');
+    const destroyLeased = vi.spyOn(getWgpuRenderTextureTarget(state, leased)!.texture, 'destroy');
+    releaseWgpuRenderTexture(state, pool, free);
+
+    destroyWgpuRenderTexturePool(state, pool);
+
+    expect(destroyFree).toHaveBeenCalledOnce();
+    expect(destroyLeased).toHaveBeenCalledOnce();
+    expect(pool.free).toHaveLength(0);
+    expect(pool.leased.size).toBe(0);
+  });
+
+  it('rejects acquisition after destruction', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTexturePool();
+    destroyWgpuRenderTexturePool(state, pool);
+    expect(() => acquireWgpuRenderTexture(state, pool, { width: 8, height: 8 })).toThrow('has been destroyed');
+  });
+});
+
+describe('releaseWgpuRenderTexture', () => {
+  it('rejects a double release', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTexturePool();
+    const texture = acquireWgpuRenderTexture(state, pool, { width: 8, height: 8 });
+    releaseWgpuRenderTexture(state, pool, texture);
+
+    expect(() => releaseWgpuRenderTexture(state, pool, texture)).toThrow('texture is not leased');
+  });
+});
+
+describe('withWgpuRenderTextures', () => {
+  it('releases every lease when the bracket callback throws', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const pool = createWgpuRenderTexturePool();
+
+    expect(() =>
+      withWgpuRenderTextures(
+        state,
+        pool,
+        [
+          { width: 8, height: 8 },
+          { width: 8, height: 8 },
+          { width: 8, height: 8 },
+        ],
+        () => {
+          throw new Error('capture failed');
+        },
+      ),
+    ).toThrow('capture failed');
+
+    expect(pool.leased.size).toBe(0);
+    expect(pool.free).toHaveLength(3);
+  });
+});

package/src/wgpuShaderBinding.test.ts

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