@flighthq/scene2d-wgpu 0.3.0-next.906.07cea63 → 0.3.0

package/src/wgpuMeshShapeRenderer.test.ts

@@ -0,0 +1,167 @@
+import type * as FlightNodeModule from '@flighthq/node/contract';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu/contract';
+import { createWgpuRenderStateForTest, installWgpuMock, renderWgpuBackground } from '@flighthq/render-wgpu/contract';
+import { enableRenderRegistryGuards, explainRenderRegistryMisses } from '@flighthq/render/contract';
+import {
+  appendShapeBeginFill,
+  appendShapeBeginGradientFill,
+  appendShapeEndFill,
+  appendShapeRectangle,
+  createShape,
+} from '@flighthq/shape/contract';
+import type { RenderProxy2D } from '@flighthq/types/contract';
+import { BatchFormat, RenderRegistry } from '@flighthq/types/contract';
+
+import { scopeModuleMocks } from './moduleMockTestHelper';
+import type * as WgpuMeshShapeModule from './wgpuMeshShapeRenderer';
+import { registerWgpuShapeRasterizer } from './wgpuShapeRasterizer';
+
+let defaultWgpuMeshShapeRenderer: typeof WgpuMeshShapeModule.defaultWgpuMeshShapeRenderer;
+let drawWgpuMeshShape: typeof WgpuMeshShapeModule.drawWgpuMeshShape;
+
+scopeModuleMocks(['@flighthq/node']);
+
+beforeAll(async () => {
+  vi.doMock('@flighthq/node/contract', async (importOriginal) => ({
+    ...(await importOriginal<typeof FlightNodeModule>()),
+    getNodeLocalBoundsRectangle: () => ({ x: 0, y: 0, width: 64, height: 48 }),
+    getNodeLocalContentRevision: (source: any) => source?.data?.version ?? 0,
+  }));
+  ({ defaultWgpuMeshShapeRenderer, drawWgpuMeshShape } = await import('./wgpuMeshShapeRenderer'));
+  installWgpuMock();
+});
+
+function makeShapeData() {
+  return {
+    surface: null,
+    lastContentId: -1,
+    lastPixelRatio: 0,
+    lastW: 0,
+    lastH: 0,
+    meshVersion: -1,
+    meshes: null,
+    meshBuffers: {
+      vertexBuffers: [],
+      vertexCapacities: [],
+      indexBuffers: [],
+      indexCapacities: [],
+      uniformBuffers: [],
+      bindGroups: [],
+      colorScaleBiasUniformBuffers: [],
+      colorScaleBiasBindGroups: [],
+    },
+  };
+}
+
+function makeShapeProxy(data: Record<string, unknown>, rendererData: unknown = makeShapeData()): RenderProxy2D {
+  return {
+    source: { data: { commands: [], version: 0, ...data } },
+    blendMode: 0,
+    alpha: 1,
+    material: null,
+    materialData: null,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    rendererData,
+  } as unknown as RenderProxy2D;
+}
+
+function makeMeshPassSpy(): GPURenderPassEncoder {
+  return {
+    setPipeline: vi.fn(),
+    setBindGroup: vi.fn(),
+    setVertexBuffer: vi.fn(),
+    setIndexBuffer: vi.fn(),
+    setStencilReference: vi.fn(),
+    draw: vi.fn(),
+    drawIndexed: vi.fn(),
+    end: vi.fn(),
+  } as unknown as GPURenderPassEncoder;
+}
+
+function gradientShape() {
+  const shape = createShape();
+  appendShapeBeginGradientFill(shape, 'linear', [0xff0000, 0x0000ff], [1, 1], [0, 255], null);
+  appendShapeRectangle(shape, 8, 8, 32, 24);
+  appendShapeEndFill(shape);
+  return shape;
+}
+
+describe('defaultWgpuMeshShapeRenderer', () => {
+  it('declares BatchFormat.Quad and the shared shape data lifecycle', () => {
+    expect(defaultWgpuMeshShapeRenderer.format).toBe(BatchFormat.Quad);
+    expect(typeof defaultWgpuMeshShapeRenderer.createData).toBe('function');
+    expect(typeof defaultWgpuMeshShapeRenderer.destroyData).toBe('function');
+  });
+
+  it('never rasterizes, even with a rasterizer registered and a fill that cannot tessellate', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    getWgpuRenderStateRuntime(state).renderPass = makeMeshPassSpy();
+    const rasterizer = vi.fn();
+    registerWgpuShapeRasterizer(state, rasterizer);
+
+    defaultWgpuMeshShapeRenderer.submit!(
+      state,
+      makeShapeProxy({ commands: gradientShape().data.commands, version: 1 }),
+    );
+
+    expect(rasterizer).not.toHaveBeenCalled();
+  });
+
+  it('reports a ShapeRasterizer miss rather than silently dropping an untessellatable fill', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    getWgpuRenderStateRuntime(state).renderPass = makeMeshPassSpy();
+    enableRenderRegistryGuards(state);
+
+    defaultWgpuMeshShapeRenderer.submit!(
+      state,
+      makeShapeProxy({ commands: gradientShape().data.commands, version: 1 }),
+    );
+
+    expect(explainRenderRegistryMisses(state).misses).toContainEqual({
+      kind: 'Shape',
+      registry: RenderRegistry.ShapeRasterizer,
+    });
+  });
+});
+
+describe('drawWgpuMeshShape', () => {
+  it('draws a solid fill as a GPU mesh and reports that it drew', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const pass = makeMeshPassSpy();
+    getWgpuRenderStateRuntime(state).renderPass = pass;
+    const shape = createShape();
+    appendShapeBeginFill(shape, 0x00cc00);
+    appendShapeRectangle(shape, 8, 8, 32, 24);
+    appendShapeEndFill(shape);
+
+    expect(drawWgpuMeshShape(state, makeShapeProxy({ commands: shape.data.commands, version: 1 }))).toBe(true);
+    expect(pass.drawIndexed).toHaveBeenCalled();
+  });
+
+  it('reports false for a fill with no tessellated form, which is the hybrid fall-through signal', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    getWgpuRenderStateRuntime(state).renderPass = makeMeshPassSpy();
+    expect(drawWgpuMeshShape(state, makeShapeProxy({ commands: gradientShape().data.commands, version: 1 }))).toBe(
+      false,
+    );
+  });
+
+  it('reports false with no render pass, an empty command list, or absent renderer data', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const shape = createShape();
+    appendShapeBeginFill(shape, 0x00cc00);
+    appendShapeRectangle(shape, 8, 8, 32, 24);
+    appendShapeEndFill(shape);
+
+    getWgpuRenderStateRuntime(state).renderPass = null;
+    expect(drawWgpuMeshShape(state, makeShapeProxy({ commands: shape.data.commands, version: 1 }))).toBe(false);
+    getWgpuRenderStateRuntime(state).renderPass = makeMeshPassSpy();
+    expect(drawWgpuMeshShape(state, makeShapeProxy({ commands: [], version: 1 }))).toBe(false);
+    expect(drawWgpuMeshShape(state, makeShapeProxy({ commands: shape.data.commands, version: 1 }, null))).toBe(false);
+  });
+});

package/src/wgpuParticleEmitter2D.test.ts

@@ -1,8 +1,15 @@
 import { createParticleEmitter2D } from '@flighthq/particleemitter/contract';
-import { getWgpuRenderStateRuntime, renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu/contract';
+import {
+  getWgpuRenderStateRuntime,
+  registerWgpuCompressedImageTextureResolver,
+  renderWgpuBackground,
+  submitWgpuRenderPass,
+} from '@flighthq/render-wgpu/contract';
 import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu/contract';
 import { getRenderProxy2D, prepareScene2DRender } from '@flighthq/render/contract';
-import type { ImageResource, RenderProxy2D } from '@flighthq/types/contract';
+import { createTexture } from '@flighthq/texture/contract';
+import type { CompressedImage, RenderProxy2D } from '@flighthq/types/contract';
+import { CompressedImageTextureSourceKind } from '@flighthq/types/contract';
 
 import { defaultWgpuParticleEmitter2DRenderer, drawWgpuParticleEmitter2D } from './wgpuParticleEmitter2D';
 
@@ -36,17 +43,16 @@ describe('drawWgpuParticleEmitter2D', () => {
   it('threads a native compressed atlas straight-alpha flag through the particle uniform', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
+    registerWgpuCompressedImageTextureResolver(state);
     renderWgpuBackground(state);
     const before = runtime.uniformOffset;
     const image = {
-      alphaType: 'straight',
       compressed: { container: {}, payload: new Uint8Array() },
-      data: null,
       height: 4,
-      source: null,
+      kind: CompressedImageTextureSourceKind,
       version: 1,
       width: 4,
-    } as unknown as ImageResource;
+    } as unknown as CompressedImage;
     runtime.compressedTextureUpload = () => {
       const texture = state.device.createTexture({
         size: [4, 4],
@@ -67,7 +73,10 @@ describe('drawWgpuParticleEmitter2D', () => {
       source: {
         data: {
           alphas: new Float32Array([1]),
-          atlas: { image, regions: [{ height: 4, width: 4, x: 0, y: 0 }] },
+          atlas: {
+            regions: [{ height: 4, width: 4, x: 0, y: 0 }],
+            texture: createTexture({ dimension: '2d', source: image }),
+          },
           colors: new Float32Array([1, 1, 1]),
           ids: new Uint16Array([0]),
           particleCount: 1,

package/src/wgpuQuadBatch.test.ts

@@ -1,10 +1,10 @@
+import { createQuadBatch } from '@flighthq/quadbatch/contract';
 import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu/contract';
 import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu/contract';
 import { getRenderProxy2D, prepareScene2DRender } from '@flighthq/render/contract';
-import { createQuadBatch } from '@flighthq/sprite/contract';
 
 import { defaultWgpuQuadBatchRenderer, ensureWgpuQuadBatchResources, getWgpuQuadBatchPipeline } from './wgpuQuadBatch';
-import { flushWgpuSpriteBatch } from './wgpuSpriteBatch';
+import { flushWgpuQuadBatchWriter } from './wgpuQuadBatchWriter';
 
 beforeAll(() => {
   installWgpuMock();
@@ -31,7 +31,7 @@ describe('defaultWgpuQuadBatchRenderer.submit', () => {
 
     expect(() => {
       defaultWgpuQuadBatchRenderer.submit(state, renderProxy);
-      flushWgpuSpriteBatch(state as any);
+      flushWgpuQuadBatchWriter(state as any);
     }).not.toThrow();
     submitWgpuRenderPass(state);
   });

package/src/{wgpuSpriteBatch.test.ts → wgpuQuadBatchWriter.test.ts}

@@ -1,21 +1,20 @@
-import { createImageResource } from '@flighthq/image/contract';
 import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu/contract';
 import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu/contract';
 import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu/contract';
-import type { ColorScaleBias, Material } from '@flighthq/types/contract';
+import type { ColorScaleBias, Material, WgpuTextureEntry } from '@flighthq/types/contract';
 import { BlendMode } from '@flighthq/types/contract';
 
 import { registerWgpuColorAdjustmentMaterialFeature } from './wgpuColorAdjustmentMaterialFeature';
 import {
   ensureWgpuQuadBatchResources,
-  flushWgpuSpriteBatch,
+  flushWgpuQuadBatchWriter,
   getWgpuQuadBatchPipeline,
   getWgpuQuadBatchPreludeWGSL,
-  packWgpuSpriteBatchMaterialInstance,
-  prepareWgpuSpriteBatchWrite,
-  recordWgpuSpriteBatchColorScaleBias,
-  resetWgpuSpriteBatchBufferPool,
-} from './wgpuSpriteBatch';
+  packWgpuQuadBatchMaterialInstance,
+  prepareWgpuQuadBatchWrite,
+  recordWgpuQuadBatchColorScaleBias,
+  resetWgpuQuadBatchWriterBufferPool,
+} from './wgpuQuadBatchWriter';
 import { standardWgpuMaterialRenderer } from './wgpuStandardMaterial';
 
 beforeAll(() => {
@@ -26,6 +25,14 @@ function makeMaterial(): Material {
   return { kind: 'TestMaterial' } as Material;
 }
 
+function makeTexture(): WgpuTextureEntry {
+  return {
+    bindGroup: {} as GPUBindGroup,
+    texture: {} as GPUTexture,
+    view: {} as GPUTextureView,
+  };
+}
+
 function ct(
   redScale = 1,
   greenScale = 1,
@@ -70,11 +77,11 @@ describe('ensureWgpuQuadBatchResources', () => {
   });
 });
 
-describe('flushWgpuSpriteBatch', () => {
+describe('flushWgpuQuadBatchWriter', () => {
   it('does nothing when batch count is zero', async () => {
     const state = await createWgpuRenderStateForTest();
     renderWgpuBackground(state);
-    expect(() => flushWgpuSpriteBatch(state)).not.toThrow();
+    expect(() => flushWgpuQuadBatchWriter(state)).not.toThrow();
     submitWgpuRenderPass(state);
   });
 
@@ -82,16 +89,16 @@ describe('flushWgpuSpriteBatch', () => {
     const state = await createWgpuRenderStateForTest();
     renderWgpuBackground(state);
     const runtime = getWgpuRenderStateRuntime(state);
-    const tex = createImageResource(document.createElement('img'));
+    const tex = makeTexture();
 
-    prepareWgpuSpriteBatchWrite(state, tex, null, null, standardWgpuMaterialRenderer, 1);
-    runtime.spriteBatchCount = 1;
-    flushWgpuSpriteBatch(state);
+    prepareWgpuQuadBatchWrite(state, tex, null, null, null, standardWgpuMaterialRenderer, 1);
+    runtime.quadBatchWriterCount = 1;
+    flushWgpuQuadBatchWriter(state);
 
-    expect(runtime.spriteBatchCount).toBe(0);
-    expect(runtime.spriteBatchTexture).toBeNull();
-    expect(runtime.spriteBatchBlendMode).toBeNull();
-    expect(runtime.spriteBatchMaterial).toBeNull();
+    expect(runtime.quadBatchWriterCount).toBe(0);
+    expect(runtime.quadBatchWriterTexture).toBeNull();
+    expect(runtime.quadBatchWriterBlendMode).toBeNull();
+    expect(runtime.quadBatchWriterMaterial).toBeNull();
     submitWgpuRenderPass(state);
   });
 
@@ -101,20 +108,22 @@ describe('flushWgpuSpriteBatch', () => {
     const state = await createWgpuRenderStateForTest();
     renderWgpuBackground(state);
     const runtime = getWgpuRenderStateRuntime(state);
-    const tex1 = createImageResource(document.createElement('img'));
-    const tex2 = createImageResource(document.createElement('img'));
-
-    prepareWgpuSpriteBatchWrite(state, tex1, null, null, standardWgpuMaterialRenderer, 1);
-    runtime.spriteBatchCount = 1;
-    flushWgpuSpriteBatch(state);
-
-    prepareWgpuSpriteBatchWrite(state, tex2, null, null, standardWgpuMaterialRenderer, 1);
-    runtime.spriteBatchCount = 1;
-    flushWgpuSpriteBatch(state);
-
-    expect(runtime.spriteBatchBufferCursor).toBe(2);
-    expect(runtime.spriteBatchBufferPool[0].instanceBuffer).not.toBeNull();
-    expect(runtime.spriteBatchBufferPool[0].instanceBuffer).not.toBe(runtime.spriteBatchBufferPool[1].instanceBuffer);
+    const tex1 = makeTexture();
+    const tex2 = makeTexture();
+
+    prepareWgpuQuadBatchWrite(state, tex1, null, null, null, standardWgpuMaterialRenderer, 1);
+    runtime.quadBatchWriterCount = 1;
+    flushWgpuQuadBatchWriter(state);
+
+    prepareWgpuQuadBatchWrite(state, tex2, null, null, null, standardWgpuMaterialRenderer, 1);
+    runtime.quadBatchWriterCount = 1;
+    flushWgpuQuadBatchWriter(state);
+
+    expect(runtime.quadBatchWriterBufferCursor).toBe(2);
+    expect(runtime.quadBatchWriterBufferPool[0].instanceBuffer).not.toBeNull();
+    expect(runtime.quadBatchWriterBufferPool[0].instanceBuffer).not.toBe(
+      runtime.quadBatchWriterBufferPool[1].instanceBuffer,
+    );
     submitWgpuRenderPass(state);
   });
 });
@@ -166,19 +175,19 @@ describe('getWgpuQuadBatchPreludeWGSL', () => {
   });
 });
 
-describe('packWgpuSpriteBatchMaterialInstance', () => {
+describe('packWgpuQuadBatchMaterialInstance', () => {
   it('is a no-op when no per-instance material data is active', async () => {
     const state = await createWgpuRenderStateForTest();
-    expect(() => packWgpuSpriteBatchMaterialInstance(state, null, 0)).not.toThrow();
+    expect(() => packWgpuQuadBatchMaterialInstance(state, null, 0)).not.toThrow();
   });
 });
 
-describe('prepareWgpuSpriteBatchWrite', () => {
+describe('prepareWgpuQuadBatchWrite', () => {
   it('returns float index 0 for an empty batch', async () => {
     const state = await createWgpuRenderStateForTest();
-    const tex = createImageResource(document.createElement('img'));
+    const tex = makeTexture();
 
-    const base = prepareWgpuSpriteBatchWrite(state, tex, null, null, standardWgpuMaterialRenderer, 1);
+    const base = prepareWgpuQuadBatchWrite(state, tex, null, null, null, standardWgpuMaterialRenderer, 1);
     expect(base).toBe(0);
   });
 
@@ -186,15 +195,15 @@ describe('prepareWgpuSpriteBatchWrite', () => {
     const state = await createWgpuRenderStateForTest();
     renderWgpuBackground(state);
     const runtime = getWgpuRenderStateRuntime(state);
-    const tex1 = createImageResource(document.createElement('img'));
-    const tex2 = createImageResource(document.createElement('img'));
+    const tex1 = makeTexture();
+    const tex2 = makeTexture();
 
-    prepareWgpuSpriteBatchWrite(state, tex1, null, null, standardWgpuMaterialRenderer, 1);
-    runtime.spriteBatchCount = 1;
-    prepareWgpuSpriteBatchWrite(state, tex2, null, null, standardWgpuMaterialRenderer, 1);
+    prepareWgpuQuadBatchWrite(state, tex1, null, null, null, standardWgpuMaterialRenderer, 1);
+    runtime.quadBatchWriterCount = 1;
+    prepareWgpuQuadBatchWrite(state, tex2, null, null, null, standardWgpuMaterialRenderer, 1);
 
-    expect(runtime.spriteBatchTexture).toBe(tex2);
-    expect(runtime.spriteBatchCount).toBe(0);
+    expect(runtime.quadBatchWriterTexture).toBe(tex2);
+    expect(runtime.quadBatchWriterCount).toBe(0);
     submitWgpuRenderPass(state);
   });
 
@@ -202,41 +211,41 @@ describe('prepareWgpuSpriteBatchWrite', () => {
     const state = await createWgpuRenderStateForTest();
     renderWgpuBackground(state);
     const runtime = getWgpuRenderStateRuntime(state);
-    const tex = createImageResource(document.createElement('img'));
+    const tex = makeTexture();
     const materialA = makeMaterial();
     const materialB = makeMaterial();
 
-    prepareWgpuSpriteBatchWrite(state, tex, null, materialA, standardWgpuMaterialRenderer, 1);
-    runtime.spriteBatchCount = 1;
-    prepareWgpuSpriteBatchWrite(state, tex, null, materialB, standardWgpuMaterialRenderer, 1);
+    prepareWgpuQuadBatchWrite(state, tex, null, null, materialA, standardWgpuMaterialRenderer, 1);
+    runtime.quadBatchWriterCount = 1;
+    prepareWgpuQuadBatchWrite(state, tex, null, null, materialB, standardWgpuMaterialRenderer, 1);
 
-    expect(runtime.spriteBatchMaterial).toBe(materialB);
-    expect(runtime.spriteBatchCount).toBe(0);
+    expect(runtime.quadBatchWriterMaterial).toBe(materialB);
+    expect(runtime.quadBatchWriterCount).toBe(0);
     submitWgpuRenderPass(state);
   });
 });
 
-describe('recordWgpuSpriteBatchColorScaleBias', () => {
+describe('recordWgpuQuadBatchColorScaleBias', () => {
   it('skips the tint and records no fold state when color adjustment is not enabled', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
-    recordWgpuSpriteBatchColorScaleBias(state, ct(0.5), 0);
-    expect(runtime.spriteBatchColorScaleBiasMode ?? CT_MODE_NONE).toBe(CT_MODE_NONE);
+    recordWgpuQuadBatchColorScaleBias(state, ct(0.5), 0);
+    expect(runtime.quadBatchWriterColorScaleBiasMode ?? CT_MODE_NONE).toBe(CT_MODE_NONE);
   });
 
   it('is a no-op for an untinted instance whether or not the fold is enabled', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
-    expect(() => recordWgpuSpriteBatchColorScaleBias(state, null, 0)).not.toThrow();
-    expect(runtime.spriteBatchColorScaleBiasMode ?? CT_MODE_NONE).toBe(CT_MODE_NONE);
+    expect(() => recordWgpuQuadBatchColorScaleBias(state, null, 0)).not.toThrow();
+    expect(runtime.quadBatchWriterColorScaleBiasMode ?? CT_MODE_NONE).toBe(CT_MODE_NONE);
   });
 
   it('delegates to the installed fold when color adjustment is enabled', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
     registerWgpuColorAdjustmentMaterialFeature(state);
-    recordWgpuSpriteBatchColorScaleBias(state, ct(0.5), 0);
-    expect(runtime.spriteBatchColorScaleBiasMode).toBe(CT_MODE_UNIFORM);
+    recordWgpuQuadBatchColorScaleBias(state, ct(0.5), 0);
+    expect(runtime.quadBatchWriterColorScaleBiasMode).toBe(CT_MODE_UNIFORM);
   });
 
   it('an untinted batch on flush uses the lean material module (no fold)', async () => {
@@ -244,29 +253,29 @@ describe('recordWgpuSpriteBatchColorScaleBias', () => {
     registerWgpuColorAdjustmentMaterialFeature(state);
     renderWgpuBackground(state);
     const runtime = getWgpuRenderStateRuntime(state);
-    const tex = createImageResource(document.createElement('img'));
-    prepareWgpuSpriteBatchWrite(state, tex, null, null, standardWgpuMaterialRenderer, 1);
-    recordWgpuSpriteBatchColorScaleBias(state, null, 0);
-    runtime.spriteBatchCount = 1;
-    expect(() => flushWgpuSpriteBatch(state)).not.toThrow();
+    const tex = makeTexture();
+    prepareWgpuQuadBatchWrite(state, tex, null, null, null, standardWgpuMaterialRenderer, 1);
+    recordWgpuQuadBatchColorScaleBias(state, null, 0);
+    runtime.quadBatchWriterCount = 1;
+    expect(() => flushWgpuQuadBatchWriter(state)).not.toThrow();
     submitWgpuRenderPass(state);
   });
 });
 
-describe('resetWgpuSpriteBatchBufferPool', () => {
+describe('resetWgpuQuadBatchWriterBufferPool', () => {
   it('rewinds the pool cursor so slots are reclaimed next frame', async () => {
     const state = await createWgpuRenderStateForTest();
     renderWgpuBackground(state);
     const runtime = getWgpuRenderStateRuntime(state);
-    const tex = createImageResource(document.createElement('img'));
+    const tex = makeTexture();
 
-    prepareWgpuSpriteBatchWrite(state, tex, null, null, standardWgpuMaterialRenderer, 1);
-    runtime.spriteBatchCount = 1;
-    flushWgpuSpriteBatch(state);
-    expect(runtime.spriteBatchBufferCursor).toBe(1);
+    prepareWgpuQuadBatchWrite(state, tex, null, null, null, standardWgpuMaterialRenderer, 1);
+    runtime.quadBatchWriterCount = 1;
+    flushWgpuQuadBatchWriter(state);
+    expect(runtime.quadBatchWriterBufferCursor).toBe(1);
 
-    resetWgpuSpriteBatchBufferPool(state);
-    expect(runtime.spriteBatchBufferCursor).toBe(0);
+    resetWgpuQuadBatchWriterBufferPool(state);
+    expect(runtime.quadBatchWriterBufferCursor).toBe(0);
     submitWgpuRenderPass(state);
   });
 });

package/src/wgpuRasterShapeRenderer.test.ts

@@ -0,0 +1,156 @@
+import type * as FlightNodeModule from '@flighthq/node/contract';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu/contract';
+import { createWgpuRenderStateForTest, installWgpuMock, renderWgpuBackground } from '@flighthq/render-wgpu/contract';
+import { enableRenderRegistryGuards, explainRenderRegistryMisses } from '@flighthq/render/contract';
+import { appendShapeBeginFill, appendShapeEndFill, appendShapeRectangle, createShape } from '@flighthq/shape/contract';
+import type { RenderProxy2D } from '@flighthq/types/contract';
+import { BatchFormat, RenderRegistry } from '@flighthq/types/contract';
+
+import { scopeModuleMocks } from './moduleMockTestHelper';
+import type * as WgpuRasterShapeModule from './wgpuRasterShapeRenderer';
+import { registerWgpuShapeRasterizer } from './wgpuShapeRasterizer';
+import { registerWgpuStandardMaterial } from './wgpuStandardMaterial';
+
+let defaultWgpuRasterShapeRenderer: typeof WgpuRasterShapeModule.defaultWgpuRasterShapeRenderer;
+let drawWgpuRasterShape: typeof WgpuRasterShapeModule.drawWgpuRasterShape;
+
+scopeModuleMocks(['@flighthq/node']);
+
+beforeAll(async () => {
+  vi.doMock('@flighthq/node/contract', async (importOriginal) => ({
+    ...(await importOriginal<typeof FlightNodeModule>()),
+    getNodeLocalBoundsRectangle: () => ({ x: 0, y: 0, width: 64, height: 48 }),
+    getNodeLocalContentRevision: (source: any) => source?.data?.version ?? 0,
+  }));
+  ({ defaultWgpuRasterShapeRenderer, drawWgpuRasterShape } = await import('./wgpuRasterShapeRenderer'));
+  installWgpuMock();
+});
+
+function makeShapeData() {
+  return {
+    surface: null,
+    lastContentId: -1,
+    lastPixelRatio: 0,
+    lastW: 0,
+    lastH: 0,
+    meshVersion: -1,
+    meshes: null,
+    meshBuffers: {
+      vertexBuffers: [],
+      vertexCapacities: [],
+      indexBuffers: [],
+      indexCapacities: [],
+      uniformBuffers: [],
+      bindGroups: [],
+      colorScaleBiasUniformBuffers: [],
+      colorScaleBiasBindGroups: [],
+    },
+  };
+}
+
+function makeShapeProxy(data: Record<string, unknown>, rendererData: unknown = makeShapeData()): RenderProxy2D {
+  return {
+    source: { data: { commands: [], version: 0, ...data } },
+    blendMode: 0,
+    alpha: 1,
+    material: null,
+    materialData: null,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    rendererData,
+  } as unknown as RenderProxy2D;
+}
+
+function makeMeshPassSpy(): GPURenderPassEncoder {
+  return {
+    setPipeline: vi.fn(),
+    setBindGroup: vi.fn(),
+    setVertexBuffer: vi.fn(),
+    setIndexBuffer: vi.fn(),
+    setStencilReference: vi.fn(),
+    draw: vi.fn(),
+    drawIndexed: vi.fn(),
+    end: vi.fn(),
+  } as unknown as GPURenderPassEncoder;
+}
+
+// A plain solid rectangle — precisely the shape the mesh strategy would tessellate.
+function solidShape() {
+  const shape = createShape();
+  appendShapeBeginFill(shape, 0x00cc00);
+  appendShapeRectangle(shape, 8, 8, 32, 24);
+  appendShapeEndFill(shape);
+  return shape;
+}
+
+describe('defaultWgpuRasterShapeRenderer', () => {
+  it('declares BatchFormat.Quad and the shared shape data lifecycle', () => {
+    expect(defaultWgpuRasterShapeRenderer.format).toBe(BatchFormat.Quad);
+    expect(typeof defaultWgpuRasterShapeRenderer.createData).toBe('function');
+    expect(typeof defaultWgpuRasterShapeRenderer.destroyData).toBe('function');
+    expect(defaultWgpuRasterShapeRenderer.submit).toBe(drawWgpuRasterShape);
+  });
+});
+
+describe('drawWgpuRasterShape', () => {
+  it('rasterizes a fill the mesh path could have tessellated, which is what pinning this strategy means', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    registerWgpuStandardMaterial(state);
+    const pass = makeMeshPassSpy();
+    getWgpuRenderStateRuntime(state).renderPass = pass;
+    const rasterizer = vi.fn();
+    registerWgpuShapeRasterizer(state, rasterizer);
+
+    drawWgpuRasterShape(state, makeShapeProxy({ commands: solidShape().data.commands, version: 1 }));
+
+    expect(rasterizer).toHaveBeenCalledTimes(1);
+    expect(pass.drawIndexed).not.toHaveBeenCalled();
+    expect(getWgpuRenderStateRuntime(state).quadBatchWriterCount).toBe(1);
+  });
+
+  it('replays the whole command stream, not the subset a mesh path could not express', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    registerWgpuStandardMaterial(state);
+    getWgpuRenderStateRuntime(state).renderPass = makeMeshPassSpy();
+    const shape = solidShape();
+    let replayed: readonly unknown[] = [];
+    registerWgpuShapeRasterizer(state, (_ctx, commands) => {
+      replayed = commands;
+    });
+
+    drawWgpuRasterShape(state, makeShapeProxy({ commands: shape.data.commands, version: 1 }));
+
+    expect(replayed).toEqual(shape.data.commands);
+  });
+
+  it('reports a ShapeRasterizer miss when no rasterizer is registered', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    getWgpuRenderStateRuntime(state).renderPass = makeMeshPassSpy();
+    enableRenderRegistryGuards(state);
+
+    drawWgpuRasterShape(state, makeShapeProxy({ commands: solidShape().data.commands, version: 1 }));
+
+    expect(explainRenderRegistryMisses(state).misses).toContainEqual({
+      kind: 'Shape',
+      registry: RenderRegistry.ShapeRasterizer,
+    });
+  });
+
+  it('does nothing without a render pass, for an empty command list, or with absent renderer data', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    registerWgpuStandardMaterial(state);
+    const rasterizer = vi.fn();
+    registerWgpuShapeRasterizer(state, rasterizer);
+
+    getWgpuRenderStateRuntime(state).renderPass = null;
+    drawWgpuRasterShape(state, makeShapeProxy({ commands: solidShape().data.commands, version: 1 }));
+    getWgpuRenderStateRuntime(state).renderPass = makeMeshPassSpy();
+    drawWgpuRasterShape(state, makeShapeProxy({ commands: [], version: 1 }));
+    drawWgpuRasterShape(state, makeShapeProxy({ commands: solidShape().data.commands, version: 1 }, null));
+
+    expect(rasterizer).not.toHaveBeenCalled();
+  });
+});