@flighthq/scene2d-wgpu 0.2.1-next.840.857425c

package/src/wgpuCache.test.ts

@@ -0,0 +1,272 @@
+import { createMatrix } from '@flighthq/geometry';
+import { createRenderCache, createRenderState, RenderCacheKind, useRenderCache } from '@flighthq/render';
+import type * as WgpuRenderWgpuModule from '@flighthq/render-wgpu';
+import { createDisplayObject } from '@flighthq/scene2d';
+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 WgpuNode2DModule from './wgpuNode2D';
+import type * as WgpuSpriteBatchModule from './wgpuSpriteBatch';
+
+// The GPU render-target lifecycle (@flighthq/render-wgpu) and the two local collaborators
+// ./wgpuSpriteBatch and ./wgpuNode2D 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 / scene2d-
+// 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 beginWgpuFrame: typeof WgpuRenderWgpuModule.beginWgpuFrame;
+let destroyWgpuRenderTarget: typeof WgpuRenderWgpuModule.destroyWgpuRenderTarget;
+let drawWgpuRenderTargetResult: typeof WgpuRenderWgpuModule.drawWgpuRenderTargetResult;
+let submitWgpuRenderPass: typeof WgpuRenderWgpuModule.submitWgpuRenderPass;
+let renderWgpuScene2D: typeof WgpuNode2DModule.renderWgpuScene2D;
+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', './wgpuNode2D']);
+
+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,
+      beginWgpuFrame: vi.fn((state: WgpuRenderState) => {
+        getWgpuRenderStateRuntime(state).commandEncoder = {} as GPUCommandEncoder;
+      }),
+      beginWgpuRenderPass: vi.fn(),
+      setWgpuRenderTransform2D: vi.fn(),
+      createWgpuRenderTarget: vi.fn(
+        (_state: unknown, width: number, height: number): WgpuRenderTarget => ({
+          bindGroup: {} as GPUBindGroup,
+          colorSpace: 'srgb',
+          depthStencilTexture: {} as GPUTexture,
+          depthStencilView: {} as GPUTextureView,
+          texture: {} as GPUTexture,
+          view: {} as GPUTextureView,
+          format: 'bgra8unorm',
+          clearColors: [],
+          clearDepth: 1,
+          width,
+          height,
+        }),
+      ),
+      destroyWgpuRenderTarget: vi.fn(),
+      drawWgpuRenderTargetResult: vi.fn(),
+      endWgpuRenderPass: vi.fn(),
+      resizeWgpuRenderTarget: vi.fn((_state: unknown, target: WgpuRenderTarget, width: number, height: number) => {
+        target.width = width;
+        target.height = height;
+      }),
+      submitWgpuRenderPass: vi.fn((state: WgpuRenderState) => {
+        getWgpuRenderStateRuntime(state).commandEncoder = null;
+      }),
+    };
+  });
+  vi.doMock('./wgpuNode2D', async (importOriginal) => {
+    const actual = await importOriginal<typeof WgpuNode2DModule>();
+    return { ...actual, renderWgpuScene2D: vi.fn() };
+  });
+
+  ({
+    beginWgpuFrame,
+    createWgpuRenderStateRuntime,
+    destroyWgpuRenderTarget,
+    drawWgpuRenderTargetResult,
+    getWgpuRenderStateRuntime,
+    submitWgpuRenderPass,
+  } = await import('@flighthq/render-wgpu'));
+  ({ flushWgpuSpriteBatch } = await import('./wgpuSpriteBatch'));
+  ({ renderWgpuScene2D } = await import('./wgpuNode2D'));
+  ({
+    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();
+  const runtime = getWgpuRenderStateRuntime(state);
+  runtime.commandEncoder = null;
+  runtime.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('opens and submits a standalone frame when called outside the visible frame', () => {
+    const screen = fakeScreen();
+    const cacheState = createWgpuCacheState(screen);
+    refreshWgpuRenderCache(cacheState, createRenderCache(), createDisplayObject(), { padding: 5 });
+    expect(beginWgpuFrame).toHaveBeenCalledWith(screen);
+    expect(submitWgpuRenderPass).toHaveBeenCalledWith(screen);
+    expect(getWgpuRenderStateRuntime(screen).commandEncoder).toBeNull();
+  });
+
+  it('records into an active application frame without submitting it', () => {
+    const screen = fakeScreen();
+    const encoder = {} as GPUCommandEncoder;
+    getWgpuRenderStateRuntime(screen).commandEncoder = encoder;
+    const cacheState = createWgpuCacheState(screen);
+    vi.mocked(beginWgpuFrame).mockClear();
+    vi.mocked(submitWgpuRenderPass).mockClear();
+    refreshWgpuRenderCache(cacheState, createRenderCache(), createDisplayObject(), { padding: 5 });
+    expect(beginWgpuFrame).not.toHaveBeenCalled();
+    expect(submitWgpuRenderPass).not.toHaveBeenCalled();
+    expect(getWgpuRenderStateRuntime(screen).commandEncoder).toBe(encoder);
+  });
+
+  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(renderWgpuScene2D).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/wgpuColorAdjustment.test.ts

@@ -0,0 +1,120 @@
+import { createImageResource } from '@flighthq/image';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import type { ColorTransform } from '@flighthq/types';
+
+import { enableWgpuColorAdjustment } from './wgpuColorAdjustment';
+import { defaultWgpuMaterialRenderer } from './wgpuDefaultMaterial';
+import {
+  flushWgpuSpriteBatch,
+  prepareWgpuSpriteBatchWrite,
+  recordWgpuSpriteBatchColorTransform,
+} from './wgpuSpriteBatch';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+function ct(
+  redMultiplier = 1,
+  greenMultiplier = 1,
+  blueMultiplier = 1,
+  alphaMultiplier = 1,
+  redOffset = 0,
+  greenOffset = 0,
+  blueOffset = 0,
+  alphaOffset = 0,
+): ColorTransform {
+  return {
+    redMultiplier,
+    greenMultiplier,
+    blueMultiplier,
+    alphaMultiplier,
+    redOffset,
+    greenOffset,
+    blueOffset,
+    alphaOffset,
+  } as ColorTransform;
+}
+
+const CT_MODE_NONE = 0;
+const CT_MODE_UNIFORM = 1;
+const CT_MODE_PER_INSTANCE = 2;
+
+describe('enableWgpuColorAdjustment', () => {
+  it('installs the fold so recorded tints drive the color-adjustment state machine', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    enableWgpuColorAdjustment(state);
+    expect(runtime.wgpuColorAdjustmentFold).toBeDefined();
+    expect(runtime.wgpuColorAdjustmentFold).not.toBeNull();
+  });
+
+  it('is idempotent', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    enableWgpuColorAdjustment(state);
+    const fold = runtime.wgpuColorAdjustmentFold;
+    enableWgpuColorAdjustment(state);
+    expect(runtime.wgpuColorAdjustmentFold).toBe(fold);
+  });
+
+  it('stays untinted (mode NONE) when no instance carries a color transform', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    enableWgpuColorAdjustment(state);
+    recordWgpuSpriteBatchColorTransform(state, null, 0);
+    recordWgpuSpriteBatchColorTransform(state, null, 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_NONE);
+  });
+
+  it('uses one whole-batch uniform when every instance shares one tint', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    enableWgpuColorAdjustment(state);
+    const tint = ct(0.5);
+    recordWgpuSpriteBatchColorTransform(state, tint, 0);
+    recordWgpuSpriteBatchColorTransform(state, tint, 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_UNIFORM);
+    expect(runtime.spriteBatchUniformColorTransform).toBe(tint);
+  });
+
+  it('promotes to per-instance (never splits) when tints diverge, back-filling the earlier tint', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    enableWgpuColorAdjustment(state);
+    recordWgpuSpriteBatchColorTransform(state, ct(0.5), 0);
+    recordWgpuSpriteBatchColorTransform(state, ct(0.25), 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_PER_INSTANCE);
+    expect(runtime.spriteBatchColorTransformData![0]).toBe(0.5);
+    expect(runtime.spriteBatchColorTransformData![8]).toBe(0.25);
+  });
+
+  it('promotes with identity fill when a tinted instance follows an untinted one', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    enableWgpuColorAdjustment(state);
+    recordWgpuSpriteBatchColorTransform(state, null, 0);
+    recordWgpuSpriteBatchColorTransform(state, ct(0.5), 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_PER_INSTANCE);
+    expect(runtime.spriteBatchColorTransformData![0]).toBe(1);
+    expect(runtime.spriteBatchColorTransformData![8]).toBe(0.5);
+  });
+
+  it('replicates the uniform tint per instance on flush', async () => {
+    const state = await createWgpuRenderStateForTest();
+    enableWgpuColorAdjustment(state);
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    const tex = createImageResource(document.createElement('img'));
+    prepareWgpuSpriteBatchWrite(state, tex, null, null, defaultWgpuMaterialRenderer, 2);
+    recordWgpuSpriteBatchColorTransform(state, ct(0.5), 0);
+    recordWgpuSpriteBatchColorTransform(state, ct(0.5), 1);
+    runtime.spriteBatchCount = 2;
+    flushWgpuSpriteBatch(state);
+    expect(runtime.spriteBatchColorTransformData![0]).toBe(0.5);
+    expect(runtime.spriteBatchColorTransformData![8]).toBe(0.5);
+    submitWgpuRenderPass(state);
+  });
+});

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/wgpuNode2D.test.ts

@@ -0,0 +1,36 @@
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createDisplayObject } from '@flighthq/scene2d';
+
+import { defaultWgpuScene2DRenderer, drawWgpuScene2D, renderWgpuScene2D } from './wgpuNode2D';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('defaultWgpuScene2DRenderer', () => {
+  it('has createData and draw functions', () => {
+    expect(typeof defaultWgpuScene2DRenderer.createData).toBe('function');
+    expect(typeof defaultWgpuScene2DRenderer.submit).toBe('function');
+  });
+});
+
+describe('drawWgpuScene2D', () => {
+  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(() => drawWgpuScene2D(state, renderProxy)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('renderWgpuScene2D', () => {
+  it('traverses a display object without error', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const root = createDisplayObject();
+    expect(() => renderWgpuScene2D(state, root)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});