@flighthq/displayobject-wgpu 0.1.0

package/src/wgpuCache.test.ts

@@ -0,0 +1,230 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { createMatrix } from '@flighthq/geometry';
+import { createRenderCache, createRenderState, RenderCacheKind, useRenderCache } from '@flighthq/render';
+import type * as WgpuRenderWgpuModule from '@flighthq/render-wgpu';
+import type { WgpuRenderState, WgpuRenderTarget } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { scopeModuleMocks } from './moduleMockTestHelper';
+import type * as WgpuCacheModule from './wgpuCache';
+import type * as WgpuDisplayObjectModule from './wgpuDisplayObject';
+import type * as WgpuSpriteBatchModule from './wgpuSpriteBatch';
+
+// The GPU render-target lifecycle (@flighthq/render-wgpu) and the two local collaborators
+// ./wgpuSpriteBatch and ./wgpuDisplayObject are stubbed so cache orchestration can be unit-tested
+// without a real GPU pipeline: createWgpuRenderTarget returns a plain descriptor, and the composite,
+// batch-flush, and subtree-render calls become spies for the call and ordering assertions below.
+// The mocks are scoped to this file's dynamic import of ./wgpuCache and unmocked in afterAll, so
+// under a shared (isolate:false) worker they never leak into the real render-wgpu / displayobject-
+// wgpu consumers. The mocked functions are read back from the same dynamic imports so the handles
+// the assertions observe are the exact vi.fn instances the cache module calls.
+let createWgpuCacheState: typeof WgpuCacheModule.createWgpuCacheState;
+let defaultWgpuRenderCacheRenderer: typeof WgpuCacheModule.defaultWgpuRenderCacheRenderer;
+let enableWgpuRenderCache: typeof WgpuCacheModule.enableWgpuRenderCache;
+let ensureWgpuRenderCacheTarget: typeof WgpuCacheModule.ensureWgpuRenderCacheTarget;
+let getWgpuRenderCacheTarget: typeof WgpuCacheModule.getWgpuRenderCacheTarget;
+let refreshWgpuRenderCache: typeof WgpuCacheModule.refreshWgpuRenderCache;
+let releaseWgpuRenderCache: typeof WgpuCacheModule.releaseWgpuRenderCache;
+let createWgpuRenderStateRuntime: typeof WgpuRenderWgpuModule.createWgpuRenderStateRuntime;
+let getWgpuRenderStateRuntime: typeof WgpuRenderWgpuModule.getWgpuRenderStateRuntime;
+let destroyWgpuRenderTarget: typeof WgpuRenderWgpuModule.destroyWgpuRenderTarget;
+let drawWgpuRenderTargetResult: typeof WgpuRenderWgpuModule.drawWgpuRenderTargetResult;
+let renderWgpuDisplayObject: typeof WgpuDisplayObjectModule.renderWgpuDisplayObject;
+let flushWgpuSpriteBatch: typeof WgpuSpriteBatchModule.flushWgpuSpriteBatch;
+
+// EntityRuntimeKey (Symbol.for) and RenderCacheKind (a string) are identity-stable across the
+// registry reset scopeModuleMocks performs, and cache adapters are stored on the state, not module-
+// level, so the statically-imported @flighthq/render still interoperates with the re-evaluated
+// subject even though the subject re-imports @flighthq/render under the reset.
+scopeModuleMocks(['./wgpuSpriteBatch', '@flighthq/render-wgpu', './wgpuDisplayObject']);
+
+beforeAll(async () => {
+  vi.doMock('./wgpuSpriteBatch', async (importOriginal) => {
+    const actual = await importOriginal<typeof WgpuSpriteBatchModule>();
+    return { ...actual, flushWgpuSpriteBatch: vi.fn() };
+  });
+  vi.doMock('@flighthq/render-wgpu', async (importOriginal) => {
+    const actual = await importOriginal<typeof WgpuRenderWgpuModule>();
+    return {
+      ...actual,
+      beginWgpuRenderTarget: vi.fn(),
+      createWgpuRenderTarget: vi.fn(
+        (_state: unknown, width: number, height: number): WgpuRenderTarget => ({
+          bindGroup: {} as GPUBindGroup,
+          depthStencilTexture: {} as GPUTexture,
+          depthStencilView: {} as GPUTextureView,
+          texture: {} as GPUTexture,
+          view: {} as GPUTextureView,
+          format: 'bgra8unorm',
+          width,
+          height,
+        }),
+      ),
+      destroyWgpuRenderTarget: vi.fn(),
+      drawWgpuRenderTargetResult: vi.fn(),
+      endWgpuRenderTarget: vi.fn(),
+      resizeWgpuRenderTarget: vi.fn((_state: unknown, target: WgpuRenderTarget, width: number, height: number) => {
+        target.width = width;
+        target.height = height;
+      }),
+    };
+  });
+  vi.doMock('./wgpuDisplayObject', async (importOriginal) => {
+    const actual = await importOriginal<typeof WgpuDisplayObjectModule>();
+    return { ...actual, renderWgpuDisplayObject: vi.fn() };
+  });
+
+  ({ createWgpuRenderStateRuntime, getWgpuRenderStateRuntime, destroyWgpuRenderTarget, drawWgpuRenderTargetResult } =
+    await import('@flighthq/render-wgpu'));
+  ({ flushWgpuSpriteBatch } = await import('./wgpuSpriteBatch'));
+  ({ renderWgpuDisplayObject } = await import('./wgpuDisplayObject'));
+  ({
+    createWgpuCacheState,
+    defaultWgpuRenderCacheRenderer,
+    enableWgpuRenderCache,
+    ensureWgpuRenderCacheTarget,
+    getWgpuRenderCacheTarget,
+    refreshWgpuRenderCache,
+    releaseWgpuRenderCache,
+  } = await import('./wgpuCache'));
+});
+
+function fakeScreen(options = {}): WgpuRenderState {
+  const state = createRenderState(options) as unknown as WgpuRenderState;
+  (state as any).device = {} as GPUDevice;
+  state[EntityRuntimeKey] = createWgpuRenderStateRuntime();
+  getWgpuRenderStateRuntime(state).currentBlendMode = null;
+  return state;
+}
+
+function makeCacheNode(source: unknown): any {
+  return { source, kind: RenderCacheKind, transform2D: createMatrix(), alpha: 1, blendMode: null };
+}
+
+describe('createWgpuCacheState', () => {
+  it('copies renderers and shares the GPU device but keeps its own node map', () => {
+    const screen = fakeScreen();
+    enableWgpuRenderCache(screen);
+    const cacheState = createWgpuCacheState(screen);
+    expect(getWgpuRenderStateRuntime(cacheState).rendererMap.get(RenderCacheKind)).toBe(defaultWgpuRenderCacheRenderer);
+    expect((cacheState as any).device).toBe((screen as any).device);
+    expect(getWgpuRenderStateRuntime(cacheState).renderProxyMap).not.toBe(
+      getWgpuRenderStateRuntime(screen).renderProxyMap,
+    );
+  });
+});
+
+describe('defaultWgpuRenderCacheRenderer', () => {
+  it('does nothing when no cache is attached to the source', () => {
+    const state = fakeScreen();
+    defaultWgpuRenderCacheRenderer.submit(state, makeCacheNode(createDisplayObject()));
+    expect(drawWgpuRenderTargetResult).not.toHaveBeenCalled();
+  });
+
+  it('composites the cache target attached to the source node', () => {
+    const state = fakeScreen();
+    const obj = createDisplayObject();
+    const cache = createRenderCache();
+    useRenderCache(state, obj, cache);
+    const target = ensureWgpuRenderCacheTarget(state, cache, 16, 16);
+    defaultWgpuRenderCacheRenderer.submit(state, makeCacheNode(obj));
+    expect(drawWgpuRenderTargetResult).toHaveBeenCalledWith(state, expect.anything(), target, expect.anything());
+  });
+
+  it('flushes pending batched geometry before the immediate composite', () => {
+    const state = fakeScreen();
+    const obj = createDisplayObject();
+    const cache = createRenderCache();
+    useRenderCache(state, obj, cache);
+    ensureWgpuRenderCacheTarget(state, cache, 16, 16);
+    defaultWgpuRenderCacheRenderer.submit(state, makeCacheNode(obj));
+    // The composite draws an immediate quad outside the sprite batch; geometry submitted earlier in
+    // the walk must be drained first, or the immediate quad interleaves with the un-flushed batch's
+    // instance buffer and bind-group state and corrupts it.
+    expect(flushWgpuSpriteBatch).toHaveBeenCalledWith(state);
+    expect((flushWgpuSpriteBatch as any).mock.invocationCallOrder[0]).toBeLessThan(
+      (drawWgpuRenderTargetResult as any).mock.invocationCallOrder[0],
+    );
+  });
+});
+
+describe('enableWgpuRenderCache', () => {
+  it('registers the renderer for the render cache kind', () => {
+    const state = fakeScreen();
+    enableWgpuRenderCache(state);
+    expect(getWgpuRenderStateRuntime(state).rendererMap.get(RenderCacheKind)).toBe(defaultWgpuRenderCacheRenderer);
+  });
+});
+
+describe('ensureWgpuRenderCacheTarget', () => {
+  it('creates a target sized to the request', () => {
+    const state = fakeScreen();
+    const target = ensureWgpuRenderCacheTarget(state, createRenderCache(), 64, 32);
+    expect(target.width).toBe(64);
+    expect(target.height).toBe(32);
+  });
+
+  it('reuses and resizes the same target on subsequent calls', () => {
+    const state = fakeScreen();
+    const cache = createRenderCache();
+    const first = ensureWgpuRenderCacheTarget(state, cache, 64, 32);
+    const second = ensureWgpuRenderCacheTarget(state, cache, 16, 16);
+    expect(second).toBe(first);
+    expect(second.width).toBe(16);
+  });
+
+  it('keeps targets isolated per state for the same handle', () => {
+    const stateA = fakeScreen();
+    const stateB = fakeScreen();
+    const cache = createRenderCache();
+    expect(ensureWgpuRenderCacheTarget(stateA, cache, 8, 8)).not.toBe(ensureWgpuRenderCacheTarget(stateB, cache, 8, 8));
+  });
+});
+
+describe('getWgpuRenderCacheTarget', () => {
+  it('returns null before a target is allocated', () => {
+    expect(getWgpuRenderCacheTarget(fakeScreen(), createRenderCache())).toBeNull();
+  });
+
+  it('returns the allocated target', () => {
+    const state = fakeScreen();
+    const cache = createRenderCache();
+    const target = ensureWgpuRenderCacheTarget(state, cache, 8, 8);
+    expect(getWgpuRenderCacheTarget(state, cache)).toBe(target);
+  });
+});
+
+describe('refreshWgpuRenderCache', () => {
+  it('bakes on the first call and allocates the target on the screen state', () => {
+    const screen = fakeScreen();
+    const cacheState = createWgpuCacheState(screen);
+    const cache = createRenderCache();
+    const obj = createDisplayObject();
+    const rebaked = refreshWgpuRenderCache(cacheState, cache, obj, { padding: 5 });
+    expect(rebaked).toBe(true);
+    expect(renderWgpuDisplayObject).toHaveBeenCalled();
+    const target = getWgpuRenderCacheTarget(screen, cache);
+    expect(target).not.toBeNull();
+    expect(target!.width).toBe(10);
+  });
+
+  it('skips the bake under requiresInvalidation when nothing changed', () => {
+    const screen = fakeScreen({ sceneGraphSyncPolicy: 'requiresInvalidation' });
+    const cacheState = createWgpuCacheState(screen);
+    const cache = createRenderCache();
+    const obj = createDisplayObject();
+    refreshWgpuRenderCache(cacheState, cache, obj, { padding: 5 });
+    expect(refreshWgpuRenderCache(cacheState, cache, obj, { padding: 5 })).toBe(false);
+  });
+});
+
+describe('releaseWgpuRenderCache', () => {
+  it('destroys and drops the target for the cache', () => {
+    const state = fakeScreen();
+    const cache = createRenderCache();
+    const target = ensureWgpuRenderCacheTarget(state, cache, 8, 8);
+    releaseWgpuRenderCache(state, cache);
+    expect(destroyWgpuRenderTarget).toHaveBeenCalledWith(state, target);
+    expect(getWgpuRenderCacheTarget(state, cache)).toBeNull();
+  });
+});

package/src/wgpuClip.test.ts

@@ -0,0 +1,15 @@
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+
+import { enableWgpuClipSupport } from './wgpuClip';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('enableWgpuClipSupport', () => {
+  it('sets displayObjectClipHooks', async () => {
+    const state = await createWgpuRenderStateForTest();
+    enableWgpuClipSupport(state);
+    expect(state.displayObjectClipHooks).not.toBeNull();
+  });
+});

package/src/wgpuClipContours.test.ts

@@ -0,0 +1,101 @@
+import { createMatrix } from '@flighthq/geometry';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import type { WgpuRenderState } from '@flighthq/types';
+
+import { popWgpuClipContours, pushWgpuClipContours } from './wgpuClipContours';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+const SQUARE = [[0, 0, 50, 0, 50, 50, 0, 50]];
+
+function makePassSpy(): GPURenderPassEncoder {
+  return {
+    setPipeline: vi.fn(),
+    setBindGroup: vi.fn(),
+    setVertexBuffer: vi.fn(),
+    setStencilReference: vi.fn(),
+    draw: vi.fn(),
+  } as unknown as GPURenderPassEncoder;
+}
+
+async function makeState(): Promise<WgpuRenderState> {
+  const state = await createWgpuRenderStateForTest();
+  getWgpuRenderStateRuntime(state).renderPass = makePassSpy();
+  return state;
+}
+
+describe('popWgpuClipContours', () => {
+  it('decrements the stencil depth and pops the contour stack', async () => {
+    const state = await makeState();
+    const runtime = getWgpuRenderStateRuntime(state);
+    pushWgpuClipContours(state, SQUARE, 'nonZero', createMatrix());
+    expect(runtime.currentMaskDepth).toBe(1);
+    expect(runtime.clipContourStack.length).toBe(1);
+
+    popWgpuClipContours(state);
+
+    expect(runtime.currentMaskDepth).toBe(0);
+    expect(runtime.clipContourStack.length).toBe(0);
+  });
+
+  it('redraws the stored geometry with the erase pipeline to undo its stencil region', async () => {
+    const state = await makeState();
+    pushWgpuClipContours(state, SQUARE, 'nonZero', createMatrix());
+    const pass = getWgpuRenderStateRuntime(state).renderPass as unknown as {
+      setStencilReference: ReturnType<typeof vi.fn>;
+      draw: ReturnType<typeof vi.fn>;
+    };
+    pass.setStencilReference.mockClear();
+    pass.draw.mockClear();
+
+    popWgpuClipContours(state);
+
+    // Erase decrements the region stamped at depth 1, so the reference is the removed depth (1).
+    expect(pass.setStencilReference).toHaveBeenCalledWith(1);
+    expect(pass.draw).toHaveBeenCalled();
+  });
+});
+
+describe('pushWgpuClipContours', () => {
+  it('increments the stencil depth and records the clip on the stack', async () => {
+    const state = await makeState();
+    const runtime = getWgpuRenderStateRuntime(state);
+
+    pushWgpuClipContours(state, SQUARE, 'nonZero', createMatrix());
+
+    expect(runtime.currentMaskDepth).toBe(1);
+    expect(runtime.clipContourStack.length).toBe(1);
+    expect(runtime.clipContourStack[0].vertexCount).toBe(6); // one quad fan -> two triangles -> 6 verts
+  });
+
+  it('draws the contour with the parent depth as the stencil reference', async () => {
+    const state = await makeState();
+    const pass = getWgpuRenderStateRuntime(state).renderPass as unknown as {
+      setPipeline: ReturnType<typeof vi.fn>;
+      setStencilReference: ReturnType<typeof vi.fn>;
+      draw: ReturnType<typeof vi.fn>;
+    };
+
+    pushWgpuClipContours(state, SQUARE, 'nonZero', createMatrix());
+
+    expect(pass.setStencilReference).toHaveBeenCalledWith(0); // first clip increments from depth 0
+    expect(pass.setPipeline).toHaveBeenCalled();
+    expect(pass.draw).toHaveBeenCalled();
+  });
+
+  it('nests: a second clip increments from depth 1', async () => {
+    const state = await makeState();
+    const runtime = getWgpuRenderStateRuntime(state);
+    pushWgpuClipContours(state, SQUARE, 'nonZero', createMatrix());
+    const pass = runtime.renderPass as unknown as { setStencilReference: ReturnType<typeof vi.fn> };
+    pass.setStencilReference.mockClear();
+
+    pushWgpuClipContours(state, SQUARE, 'nonZero', createMatrix());
+
+    expect(runtime.currentMaskDepth).toBe(2);
+    expect(pass.setStencilReference).toHaveBeenCalledWith(1);
+  });
+});

package/src/wgpuClipRectangle.test.ts

@@ -0,0 +1,45 @@
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+
+import { popWgpuClipRectangle, pushWgpuClipRectangle } from './wgpuClipRectangle';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('popWgpuClipRectangle', () => {
+  it('pops the scissor rect from the stack', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+
+    pushWgpuClipRectangle(state, { x: 0, y: 0, width: 50, height: 50 }, { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 });
+    popWgpuClipRectangle(state);
+
+    expect(runtime.scissorStack.length).toBe(0);
+    expect(runtime.currentScissorRect).toBeNull();
+    submitWgpuRenderPass(state);
+  });
+
+  it('is safe to pop from empty stack', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    expect(() => popWgpuClipRectangle(state)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('pushWgpuClipRectangle', () => {
+  it('pushes a scissor rect onto the stack', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+
+    pushWgpuClipRectangle(state, { x: 10, y: 10, width: 100, height: 100 }, { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 });
+
+    expect(runtime.scissorStack.length).toBe(1);
+    expect(runtime.currentScissorRect).not.toBeNull();
+    submitWgpuRenderPass(state);
+  });
+});

package/src/wgpuColorTransformMaterial.test.ts

@@ -0,0 +1,62 @@
+import { getWgpuMaterialRenderer } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import type { WgpuRenderState } from '@flighthq/types';
+import { ColorTransformMaterialKind, EntityRuntimeKey, UniformColorTransformMaterialKind } from '@flighthq/types';
+
+import {
+  colorTransformWgpuMaterialRenderer,
+  registerWgpuColorTransformMaterials,
+  uniformColorTransformWgpuMaterialRenderer,
+} from './wgpuColorTransformMaterial';
+
+function makeColorTransform(redMultiplier: number) {
+  return {
+    redMultiplier,
+    greenMultiplier: 1,
+    blueMultiplier: 1,
+    alphaMultiplier: 1,
+    redOffset: 0,
+    greenOffset: 0,
+    blueOffset: 0,
+    alphaOffset: 0,
+  };
+}
+
+describe('colorTransformWgpuMaterialRenderer', () => {
+  it('declares 8 per-instance floats', () => {
+    expect(colorTransformWgpuMaterialRenderer.instanceFloatCount).toBe(8);
+  });
+
+  it('packs the materialData color transform', () => {
+    const out = new Float32Array(8);
+    colorTransformWgpuMaterialRenderer.packInstance!(null as never, null, makeColorTransform(0.5) as never, out, 0);
+    expect(out[0]).toBe(0.5);
+  });
+
+  it('packs identity when materialData is null', () => {
+    const out = new Float32Array(8);
+    colorTransformWgpuMaterialRenderer.packInstance!(null as never, null, null, out, 0);
+    expect(Array.from(out)).toEqual([1, 1, 1, 1, 0, 0, 0, 0]);
+  });
+});
+
+describe('registerWgpuColorTransformMaterials', () => {
+  it('registers both color transform material renderers', () => {
+    const state = {} as WgpuRenderState;
+    state[EntityRuntimeKey] = createWgpuRenderStateRuntime();
+    registerWgpuColorTransformMaterials(state);
+    expect(getWgpuMaterialRenderer(state, UniformColorTransformMaterialKind)).toBe(
+      uniformColorTransformWgpuMaterialRenderer,
+    );
+    expect(getWgpuMaterialRenderer(state, ColorTransformMaterialKind)).toBe(colorTransformWgpuMaterialRenderer);
+  });
+});
+
+describe('uniformColorTransformWgpuMaterialRenderer', () => {
+  it('packs the material color transform onto the instance', () => {
+    const out = new Float32Array(8);
+    const material = { kind: UniformColorTransformMaterialKind, colorTransform: makeColorTransform(0.5) } as never;
+    uniformColorTransformWgpuMaterialRenderer.packInstance!(null as never, material, null, out, 0);
+    expect(out[0]).toBe(0.5);
+  });
+});

package/src/wgpuDefaultMaterial.test.ts

@@ -0,0 +1,21 @@
+import { getWgpuMaterialRenderer } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import type { WgpuRenderState } from '@flighthq/types';
+import { DefaultMaterialKind, EntityRuntimeKey } from '@flighthq/types';
+
+import { defaultWgpuMaterialRenderer, registerDefaultWgpuMaterial } from './wgpuDefaultMaterial';
+
+describe('defaultWgpuMaterialRenderer', () => {
+  it('declares no per-instance float data', () => {
+    expect(defaultWgpuMaterialRenderer.instanceFloatCount).toBe(0);
+  });
+});
+
+describe('registerDefaultWgpuMaterial', () => {
+  it('registers the default renderer under DefaultMaterialKind', () => {
+    const state = {} as WgpuRenderState;
+    state[EntityRuntimeKey] = createWgpuRenderStateRuntime();
+    registerDefaultWgpuMaterial(state);
+    expect(getWgpuMaterialRenderer(state, DefaultMaterialKind)).toBe(defaultWgpuMaterialRenderer);
+  });
+});

package/src/wgpuDisplayObject.test.ts

@@ -0,0 +1,36 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+
+import { defaultWgpuDisplayObjectRenderer, drawWgpuDisplayObject, renderWgpuDisplayObject } from './wgpuDisplayObject';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('defaultWgpuDisplayObjectRenderer', () => {
+  it('has createData and draw functions', () => {
+    expect(typeof defaultWgpuDisplayObjectRenderer.createData).toBe('function');
+    expect(typeof defaultWgpuDisplayObjectRenderer.submit).toBe('function');
+  });
+});
+
+describe('drawWgpuDisplayObject', () => {
+  it('is a no-op (plain display objects have no geometry)', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const renderProxy = { source: createDisplayObject() } as never;
+    expect(() => drawWgpuDisplayObject(state, renderProxy)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('renderWgpuDisplayObject', () => {
+  it('traverses a display object without error', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const root = createDisplayObject();
+    expect(() => renderWgpuDisplayObject(state, root)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});

package/src/wgpuMaterials.test.ts

@@ -0,0 +1,44 @@
+import { createBitmap } from '@flighthq/displayobject';
+import { getOrCreateRenderProxy2D, prepareDisplayObjectRender } from '@flighthq/render';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+
+import { drawWgpuColorTransformBitmap, registerWgpuColorTransformShader } from './wgpuMaterials';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('drawWgpuColorTransformBitmap', () => {
+  it('does not throw when render pass is open', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    const fakeRenderProxy = {
+      alpha: 1,
+      useColorTransform: false,
+      colorTransform: null,
+      transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+      blendMode: null,
+    };
+    expect(() => drawWgpuColorTransformBitmap(state, fakeRenderProxy, canvas, 0, 0, 4, 4, 0, 0, 1, 1)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('registerWgpuColorTransformShader', () => {
+  it('registers the color transform shader on the state', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerWgpuColorTransformShader(state);
+    expect(getWgpuRenderStateRuntime(state).colorTransformBitmapShader).toBeDefined();
+  });
+
+  it('is idempotent — calling twice does not throw', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerWgpuColorTransformShader(state);
+    expect(() => registerWgpuColorTransformShader(state)).not.toThrow();
+  });
+});

package/src/wgpuParticleEmitter.test.ts

@@ -0,0 +1,34 @@
+import { getRenderProxy2D, prepareDisplayObjectRender } from '@flighthq/render';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createParticleEmitter } from '@flighthq/sprite';
+
+import { defaultWgpuParticleEmitterRenderer, drawWgpuParticleEmitter } from './wgpuParticleEmitter';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('defaultWgpuParticleEmitterRenderer', () => {
+  it('has a createData function', () => {
+    expect(typeof defaultWgpuParticleEmitterRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function', () => {
+    expect(typeof defaultWgpuParticleEmitterRenderer.submit).toBe('function');
+  });
+});
+
+describe('drawWgpuParticleEmitter', () => {
+  it('does not throw when atlas is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+
+    const emitter = createParticleEmitter();
+    prepareDisplayObjectRender(state, emitter);
+    const renderProxy = getRenderProxy2D(state, emitter)!;
+
+    expect(() => drawWgpuParticleEmitter(state, renderProxy)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});

package/src/wgpuQuadBatch.test.ts

@@ -0,0 +1,69 @@
+import { getRenderProxy2D, prepareDisplayObjectRender } from '@flighthq/render';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createQuadBatch } from '@flighthq/sprite';
+
+import { defaultWgpuQuadBatchRenderer, ensureWgpuQuadBatchResources, getWgpuQuadBatchPipeline } from './wgpuQuadBatch';
+import { flushWgpuSpriteBatch } from './wgpuSpriteBatch';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('defaultWgpuQuadBatchRenderer', () => {
+  it('has a createData function', () => {
+    expect(typeof defaultWgpuQuadBatchRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function', () => {
+    expect(typeof defaultWgpuQuadBatchRenderer.submit).toBe('function');
+  });
+});
+
+describe('defaultWgpuQuadBatchRenderer.submit', () => {
+  it('does not throw when atlas is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+
+    const batch = createQuadBatch();
+    prepareDisplayObjectRender(state, batch);
+    const renderProxy = getRenderProxy2D(state, batch)!;
+
+    expect(() => {
+      defaultWgpuQuadBatchRenderer.submit(state, renderProxy);
+      flushWgpuSpriteBatch(state as any);
+    }).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('ensureWgpuQuadBatchResources', () => {
+  it('returns resources with bind group layouts and a pipelines WeakMap', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const resources = ensureWgpuQuadBatchResources(state);
+    expect(resources.instanceBindGroupLayout).toBeDefined();
+    expect(resources.materialBindGroupLayout).toBeDefined();
+    expect(resources.basePipelineLayout).toBeDefined();
+    expect(resources.materialPipelineLayout).toBeDefined();
+    expect(resources.pipelines).toBeInstanceOf(WeakMap);
+  });
+
+  it('is idempotent — returns the same resources on repeated calls', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const r1 = ensureWgpuQuadBatchResources(state);
+    const r2 = ensureWgpuQuadBatchResources(state);
+    expect(r1).toBe(r2);
+  });
+});
+
+describe('getWgpuQuadBatchPipeline', () => {
+  it('creates and caches a pipeline for a given shader module', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const resources = ensureWgpuQuadBatchResources(state);
+    const module = state.device.createShaderModule({ code: '' });
+    const pipeline = getWgpuQuadBatchPipeline(state, resources, module, false, null);
+    expect(pipeline).toBeDefined();
+    const pipeline2 = getWgpuQuadBatchPipeline(state, resources, module, false, null);
+    expect(pipeline2).toBe(pipeline);
+  });
+});