@flighthq/render-wgpu 0.3.0 → 0.3.1-next.1041.35b950c

package/src/wgpuDraw.test.ts

@@ -111,6 +111,22 @@ describe('bindWgpuBitmapTexture', () => {
     bindWgpuBitmapTexture(state, image);
     expect(createTexture).toHaveBeenCalled();
   });
+
+  it('RETIRES the outgoing texture on a version bump rather than destroying it', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const image = bitmap(2, 1);
+    const outgoing = bindWgpuBitmapTexture(state, image).texture;
+
+    image.version = 2;
+    bindWgpuBitmapTexture(state, image);
+
+    // A version bump rewrites the cached entry IN PLACE, so a bind group recorded earlier in the frame
+    // still points at `outgoing`. The frame's submit is deferred; destroying a texture a recorded command
+    // buffer references fails that submit and blanks the whole frame, so it has to wait for post-submit.
+    // This guards a hazard with no reproduction of its own — without the test there is nothing to stop
+    // the deferral being read as pointless indirection and reverted.
+    expect(getWgpuRenderStateRuntime(state).retiredTextures).toContain(outgoing);
+  });
 });
 
 describe('bindWgpuCompressedImageTexture', () => {

package/src/wgpuMaterialRegistry.test.ts

@@ -8,7 +8,7 @@ import {
   registerWgpuMaterialRenderer,
   resolveWgpuMaterialRenderer,
 } from './wgpuMaterialRegistry';
-import { createWgpuRenderStateRuntime } from './wgpuRenderState';
+import { createWgpuRenderStateRuntime, getWgpuRenderStateRuntime } from './wgpuRenderState';
 
 const TestKind = 'TestMaterial';
 const testRenderer: WgpuMaterialRenderer = { instanceFloatCount: 0, getShaderModule: () => ({}) as GPUShaderModule };
@@ -33,8 +33,23 @@ describe('getWgpuMaterialRenderer', () => {
 describe('registerWgpuMaterialRenderer', () => {
   it('registers a renderer retrievable by kind', () => {
     const state = makeState();
+    const before = getWgpuRenderStateRuntime(state).registries.materialRenderers;
     registerWgpuMaterialRenderer(state, TestKind, testRenderer);
     expect(getWgpuMaterialRenderer(state, TestKind)).toBe(testRenderer);
+    expect(getWgpuRenderStateRuntime(state).registries.materialRenderers).not.toBe(before);
+    expect(before.entries.size).toBe(0);
+  });
+
+  it('is last-write-wins without mutating the earlier snapshot', () => {
+    const state = makeState();
+    const replacement: WgpuMaterialRenderer = { instanceFloatCount: 0, getShaderModule: () => ({}) as GPUShaderModule };
+    registerWgpuMaterialRenderer(state, TestKind, testRenderer);
+    const before = getWgpuRenderStateRuntime(state).registries.materialRenderers;
+
+    registerWgpuMaterialRenderer(state, TestKind, replacement);
+
+    expect(getWgpuMaterialRenderer(state, TestKind)).toBe(replacement);
+    expect(before.entries.get(TestKind)).toEqual({ state: 'bound', value: testRenderer });
   });
 });
 

package/src/wgpuRenderState.test.ts

@@ -1,22 +1,43 @@
 import { createEntity } from '@flighthq/entity/contract';
+import {
+  createKeyedTable,
+  getRegistryTableEntry,
+  hasRegistryTableEntry,
+  withRegistryTableEntry,
+} from '@flighthq/registry/contract';
 import {
   copyAllRenderersFromRenderState,
+  enableColorAdjustmentGuards,
+  enableColorAdjustments,
+  getColorAdjustmentUnsupportedGuard,
   getRenderStateRuntime,
   prepareScene2DRender,
   registerRenderer,
 } from '@flighthq/render/contract';
 import { createDisplayObject } from '@flighthq/scene2d/contract';
+import type {
+  RenderEffectPaddingResolver,
+  RenderRootGuard,
+  RenderState,
+  WgpuColorAdjustmentMaterialFeature,
+  WgpuColorAdjustmentMaterialFeatureGuard,
+} from '@flighthq/types/contract';
+import { RegistryEntryState } from '@flighthq/types/contract';
 
 import { beginWgpuFrame } from './wgpuBackground';
+import { registerWgpuCompressedTextureDecoder, registerWgpuCompressedTextureUpload } from './wgpuCompressedTexture';
 import { registerWgpuMaterialRenderer } from './wgpuMaterialRegistry';
 import {
   copyWgpuRenderStateRegistrations,
   createWgpuOffscreenRenderState,
   createWgpuRenderStateRuntime,
   destroyWgpuRenderState,
+  getWgpuColorAdjustmentMaterialFeature,
+  getWgpuColorAdjustmentMaterialFeatureGuard,
   getWgpuRenderStateRuntime,
   getWgpuSampler,
   isWgpuSupported,
+  resolveWgpuApplyBlendMode,
 } from './wgpuRenderState';
 import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
 import { registerWgpuTextureResolver } from './wgpuTextureResolver';
@@ -25,20 +46,113 @@ beforeAll(() => {
   installWgpuMock();
 });
 
+function getPaddingResolver(state: RenderState, kind: string): RenderEffectPaddingResolver | null {
+  const table = getRenderStateRuntime(state).registries.effectPaddingResolvers;
+  return table === undefined ? null : getRegistryTableEntry(table, kind);
+}
+
+function registerPaddingResolver(state: RenderState, kind: string, resolver: RenderEffectPaddingResolver): void {
+  const runtime = getRenderStateRuntime(state);
+  runtime.registries.effectPaddingResolvers = withRegistryTableEntry(
+    runtime.registries.effectPaddingResolvers ??
+      createKeyedTable<RenderEffectPaddingResolver>('RenderEffectPaddingResolver', 'Zero'),
+    kind,
+    resolver,
+  );
+}
+
 describe('copyWgpuRenderStateRegistrations', () => {
   it('copies late Wgpu registrations only when explicitly requested', async () => {
     const screen = await createWgpuRenderStateForTest();
     const offscreen = createWgpuOffscreenRenderState(screen);
+    const materialRenderer = { instanceFloatCount: 0, getShaderModule: vi.fn() } as never;
+    const offscreenMaterialRenderer = { instanceFloatCount: 0, getShaderModule: vi.fn() } as never;
+    const decoder = vi.fn(() => new Uint8ClampedArray(4));
     const resolver = vi.fn(() => null);
+    registerWgpuCompressedTextureDecoder(screen, decoder);
+    registerWgpuCompressedTextureUpload(screen);
+    registerWgpuMaterialRenderer(screen, 'acme.LateMaterial', materialRenderer);
     registerWgpuTextureResolver(screen, 'acme.LateTexture', resolver);
 
-    expect(getWgpuRenderStateRuntime(offscreen).wgpuTextureResolverRegistry?.has('acme.LateTexture')).not.toBe(true);
+    expect(
+      hasRegistryTableEntry(getWgpuRenderStateRuntime(offscreen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(false);
+    expect(
+      hasRegistryTableEntry(getWgpuRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(false);
+    expect(getWgpuRenderStateRuntime(offscreen).registries.compressedTextureDecoder.entry).toBeNull();
+    expect(getWgpuRenderStateRuntime(offscreen).registries.compressedTextureUpload.entry).toBeNull();
     copyWgpuRenderStateRegistrations(offscreen, screen);
-    expect(getWgpuRenderStateRuntime(offscreen).wgpuTextureResolverRegistry?.get('acme.LateTexture')).toBe(resolver);
+    expect(
+      getRegistryTableEntry(getWgpuRenderStateRuntime(offscreen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(materialRenderer);
+    expect(
+      getRegistryTableEntry(getWgpuRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(resolver);
+    expect(getWgpuRenderStateRuntime(offscreen).registries.compressedTextureDecoder).toBe(
+      getWgpuRenderStateRuntime(screen).registries.compressedTextureDecoder,
+    );
+    expect(getWgpuRenderStateRuntime(offscreen).registries.compressedTextureDecoder.entry).toEqual({
+      state: RegistryEntryState.Bound,
+      value: decoder,
+    });
+    expect(getWgpuRenderStateRuntime(offscreen).registries.compressedTextureUpload).toBe(
+      getWgpuRenderStateRuntime(screen).registries.compressedTextureUpload,
+    );
+    registerWgpuMaterialRenderer(offscreen, 'acme.LateMaterial', offscreenMaterialRenderer);
+    registerWgpuCompressedTextureDecoder(offscreen, null);
+    registerWgpuCompressedTextureUpload(offscreen, null);
+    registerWgpuTextureResolver(offscreen, 'acme.LateTexture', null);
+    expect(
+      getRegistryTableEntry(getWgpuRenderStateRuntime(offscreen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(offscreenMaterialRenderer);
+    expect(
+      getRegistryTableEntry(getWgpuRenderStateRuntime(screen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(materialRenderer);
+    expect(
+      hasRegistryTableEntry(getWgpuRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(false);
+    expect(
+      getRegistryTableEntry(getWgpuRenderStateRuntime(screen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(resolver);
+    expect(getWgpuRenderStateRuntime(offscreen).registries.compressedTextureDecoder.entry).toBeNull();
+    expect(getWgpuRenderStateRuntime(screen).registries.compressedTextureDecoder.entry?.state).toBe(
+      RegistryEntryState.Bound,
+    );
+    expect(getWgpuRenderStateRuntime(offscreen).registries.compressedTextureUpload.entry).toBeNull();
+    expect(getWgpuRenderStateRuntime(screen).registries.compressedTextureUpload.entry?.state).toBe(
+      RegistryEntryState.Bound,
+    );
   });
 });
 
 describe('createWgpuOffscreenRenderState', () => {
+  it('resolves late screen blend-mode wiring explicitly until locally overridden', async () => {
+    const screen = await createWgpuRenderStateForTest();
+    const offscreen = createWgpuOffscreenRenderState(screen);
+    const nested = createWgpuOffscreenRenderState(offscreen);
+    const screenHook = vi.fn();
+    const laterScreenHook = vi.fn();
+    const offscreenHook = vi.fn();
+
+    expect(offscreen.applyBlendMode).toBeNull();
+    expect(Object.getOwnPropertyDescriptor(offscreen, 'applyBlendMode')?.get).toBeUndefined();
+    expect(resolveWgpuApplyBlendMode(offscreen)).toBeNull();
+    screen.applyBlendMode = screenHook;
+    expect(offscreen.applyBlendMode).toBeNull();
+    expect(resolveWgpuApplyBlendMode(offscreen)).toBe(screenHook);
+    expect(resolveWgpuApplyBlendMode(nested)).toBe(screenHook);
+
+    offscreen.applyBlendMode = offscreenHook;
+    screen.applyBlendMode = laterScreenHook;
+    expect(resolveWgpuApplyBlendMode(offscreen)).toBe(offscreenHook);
+    expect(resolveWgpuApplyBlendMode(nested)).toBe(offscreenHook);
+
+    copyWgpuRenderStateRegistrations(offscreen, screen);
+    expect(offscreen.applyBlendMode).toBeNull();
+    expect(resolveWgpuApplyBlendMode(offscreen)).toBe(laterScreenHook);
+  });
+
   it('shares device resources while snapshotting independent registration policy', async () => {
     const screen = await createWgpuRenderStateForTest();
     const renderer = { createData: () => null, submit: vi.fn() };
@@ -46,11 +160,43 @@ describe('createWgpuOffscreenRenderState', () => {
     const paddingResolver = vi.fn(() => ({ bottom: 1, left: 1, right: 1, top: 1 }));
     const textureResolver = vi.fn(() => null);
     const effectRunner = vi.fn();
+    const colorAdjustmentFeature: WgpuColorAdjustmentMaterialFeature = {
+      fragmentShaderChunk: '',
+      matrixFragmentShaderChunk: '',
+      record: vi.fn(),
+      resolveFlush: vi.fn(() => null),
+    };
+    const colorAdjustmentFeatureGuard: WgpuColorAdjustmentMaterialFeatureGuard = vi.fn();
+    const renderRootGuard: RenderRootGuard = 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]]);
+    enableColorAdjustments(screen);
+    enableColorAdjustmentGuards(screen);
+    registerPaddingResolver(screen, 'acme.Effect', paddingResolver);
+    getWgpuRenderStateRuntime(screen).registries.colorAdjustmentFeature = {
+      entry: { state: RegistryEntryState.Bound, value: colorAdjustmentFeature },
+      onMiss: 'Disabled',
+      registry: 'WgpuColorAdjustmentFeature',
+      shape: 'slot',
+    };
+    getWgpuRenderStateRuntime(screen).registries.colorAdjustmentFeatureGuard = {
+      entry: { state: RegistryEntryState.Bound, value: colorAdjustmentFeatureGuard },
+      onMiss: 'Disabled',
+      registry: 'WgpuColorAdjustmentFeatureGuard',
+      shape: 'slot',
+    };
+    getWgpuRenderStateRuntime(screen).registries.renderRootGuard = {
+      entry: { state: RegistryEntryState.Bound, value: renderRootGuard },
+      onMiss: 'Disabled',
+      registry: 'RenderRootGuard',
+      shape: 'slot',
+    };
+    getWgpuRenderStateRuntime(screen).registries.renderEffects = withRegistryTableEntry(
+      getWgpuRenderStateRuntime(screen).registries.renderEffects,
+      'acme.Effect',
+      effectRunner as never,
+    );
     getWgpuRenderStateRuntime(screen).wgpuRenderTextureCache = new WeakMap();
 
     const offscreen = createWgpuOffscreenRenderState(screen);
@@ -64,18 +210,71 @@ describe('createWgpuOffscreenRenderState', () => {
     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.registries.renderers).toBe(screenRuntime.registries.renderers);
+    expect(offscreenRuntime.registries).not.toBe(screenRuntime.registries);
+    expect(offscreenRuntime.registries.colorAdjustmentFeature).toBe(screenRuntime.registries.colorAdjustmentFeature);
+    expect(getWgpuColorAdjustmentMaterialFeature(offscreen)).toBe(colorAdjustmentFeature);
+    expect(offscreenRuntime.registries.colorAdjustmentFeatureGuard).toBe(
+      screenRuntime.registries.colorAdjustmentFeatureGuard,
+    );
+    expect(getWgpuColorAdjustmentMaterialFeatureGuard(offscreen)).toBe(colorAdjustmentFeatureGuard);
+    const sharedColorFeatureGuard = offscreenRuntime.registries.colorAdjustmentFeatureGuard;
+    screenRuntime.registries.colorAdjustmentFeatureGuard = undefined;
+    expect(getWgpuColorAdjustmentMaterialFeatureGuard(screen)).toBeNull();
+    expect(offscreenRuntime.registries.colorAdjustmentFeatureGuard).toBe(sharedColorFeatureGuard);
+    expect(getWgpuColorAdjustmentMaterialFeatureGuard(offscreen)).toBe(colorAdjustmentFeatureGuard);
+    const sharedColorFeature = offscreenRuntime.registries.colorAdjustmentFeature;
+    screenRuntime.registries.colorAdjustmentFeature = undefined;
+    expect(getWgpuColorAdjustmentMaterialFeature(screen)).toBeNull();
+    expect(offscreenRuntime.registries.colorAdjustmentFeature).toBe(sharedColorFeature);
+    expect(getWgpuColorAdjustmentMaterialFeature(offscreen)).toBe(colorAdjustmentFeature);
+    expect(offscreenRuntime.registries.colorAdjustments).toBe(screenRuntime.registries.colorAdjustments);
+    expect(offscreenRuntime.registries.colorAdjustmentUnsupportedGuard).toBe(
+      screenRuntime.registries.colorAdjustmentUnsupportedGuard,
+    );
+    expect(getColorAdjustmentUnsupportedGuard(offscreen)).not.toBeNull();
+    const sharedUnsupportedGuard = offscreenRuntime.registries.colorAdjustmentUnsupportedGuard;
+    screenRuntime.registries.colorAdjustmentUnsupportedGuard = undefined;
+    expect(getColorAdjustmentUnsupportedGuard(screen)).toBeNull();
+    expect(offscreenRuntime.registries.colorAdjustmentUnsupportedGuard).toBe(sharedUnsupportedGuard);
+    expect(getColorAdjustmentUnsupportedGuard(offscreen)).not.toBeNull();
+    expect(offscreenRuntime.registries.renderRootGuard).toBe(screenRuntime.registries.renderRootGuard);
+    expect(offscreenRuntime.registries.renderRootGuard?.entry).toEqual({
+      state: RegistryEntryState.Bound,
+      value: renderRootGuard,
+    });
+    const sharedRenderRootGuard = offscreenRuntime.registries.renderRootGuard;
+    screenRuntime.registries.renderRootGuard = undefined;
+    expect(screenRuntime.registries.renderRootGuard).toBeUndefined();
+    expect(offscreenRuntime.registries.renderRootGuard).toBe(sharedRenderRootGuard);
+    expect(
+      getRegistryTableEntry(
+        offscreenRuntime.registries.renderRootGuard!,
+        offscreenRuntime.registries.renderRootGuard!.registry,
+      ),
+    ).toBe(renderRootGuard);
+    expect(offscreenRuntime.registries.compressedTextureDecoder).toBe(
+      screenRuntime.registries.compressedTextureDecoder,
     );
-    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);
+    expect(offscreenRuntime.registries.compressedTextureUpload).toBe(screenRuntime.registries.compressedTextureUpload);
+    expect(offscreenRuntime.registries.customMaterialShaders).toBe(screenRuntime.registries.customMaterialShaders);
+    expect(offscreenRuntime.registries.materialRenderers).toBe(screenRuntime.registries.materialRenderers);
+    expect(offscreenRuntime.registries.meshMaterialRenderers).toBe(screenRuntime.registries.meshMaterialRenderers);
+    expect(offscreenRuntime.registries.modifierSnippets).toBe(screenRuntime.registries.modifierSnippets);
+    expect(offscreenRuntime.registries.modifierSnippetRevision).toBe(screenRuntime.registries.modifierSnippetRevision);
+    expect(offscreenRuntime.registries.renderEffects).toBe(screenRuntime.registries.renderEffects);
+    expect(offscreenRuntime.registries.shapeRasterizer).toBe(screenRuntime.registries.shapeRasterizer);
+    expect(offscreenRuntime.registries.strokeTessellator).toBe(screenRuntime.registries.strokeTessellator);
+    expect(offscreenRuntime.registries.textureResolvers).toBe(screenRuntime.registries.textureResolvers);
+    expect(offscreenRuntime.registries.velocityWriters).toBe(screenRuntime.registries.velocityWriters);
+    expect(offscreenRuntime.registries.effectPaddingResolvers).toBe(screenRuntime.registries.effectPaddingResolvers);
+    expect(getRegistryTableEntry(offscreenRuntime.registries.renderers, 'acme.Node')).toBe(renderer);
+    expect(getRegistryTableEntry(offscreenRuntime.registries.materialRenderers, 'acme.Material')).toBe(
+      materialRenderer,
+    );
+    expect(getRegistryTableEntry(offscreenRuntime.registries.textureResolvers, 'acme.Texture')).toBe(textureResolver);
+    expect(getRegistryTableEntry(offscreenRuntime.registries.renderEffects, 'acme.Effect')).toBe(effectRunner);
+    expect(getPaddingResolver(offscreen, 'acme.Effect')).toBe(paddingResolver);
   });
 
   it('owns an independent encoder and proxy tree', async () => {
@@ -120,17 +319,17 @@ describe('createWgpuOffscreenRenderState', () => {
     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]]);
+    registerPaddingResolver(screen, 'acme.LateEffect', paddingResolver);
 
-    expect(getRenderStateRuntime(offscreen).rendererMap.has('acme.LateNode')).toBe(false);
-    expect(getRenderStateRuntime(offscreen).renderEffectPaddingResolverRegistry?.has('acme.LateEffect')).not.toBe(true);
+    expect(hasRegistryTableEntry(getRenderStateRuntime(offscreen).registries.renderers, 'acme.LateNode')).toBe(false);
+    expect(getPaddingResolver(offscreen, 'acme.LateEffect')).toBeNull();
 
     copyAllRenderersFromRenderState(offscreen, screen);
     copyWgpuRenderStateRegistrations(offscreen, screen);
-    expect(getRenderStateRuntime(offscreen).rendererMap.get('acme.LateNode')).toBe(renderer);
-    expect(getRenderStateRuntime(offscreen).renderEffectPaddingResolverRegistry?.get('acme.LateEffect')).toBe(
-      paddingResolver,
+    expect(getRegistryTableEntry(getRenderStateRuntime(offscreen).registries.renderers, 'acme.LateNode')).toBe(
+      renderer,
     );
+    expect(getPaddingResolver(offscreen, 'acme.LateEffect')).toBe(paddingResolver);
   });
 });
 
@@ -168,9 +367,70 @@ describe('createWgpuRenderState', () => {
 });
 
 describe('createWgpuRenderStateRuntime', () => {
-  it('returns a runtime carrying the base entity-runtime binding slot', () => {
+  it('returns a runtime with the base binding slot and empty named registration tables', () => {
     const runtime = createWgpuRenderStateRuntime();
     expect(runtime.binding).toBeNull();
+    expect(runtime.registries.customMaterialShaders).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'WgpuCustomMaterialShader',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.customMaterialShaders.entries.size).toBe(0);
+    expect(runtime.registries.materialRenderers).toMatchObject({
+      onMiss: 'StandardMaterial',
+      registry: 'WgpuMaterialRenderer',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.materialRenderers.entries.size).toBe(0);
+    expect(runtime.registries.meshMaterialRenderers).toMatchObject({
+      onMiss: 'StandardMaterial',
+      registry: 'WgpuMeshMaterialRenderer',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.meshMaterialRenderers.entries.size).toBe(0);
+    expect(runtime.registries.modifierSnippets).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'WgpuModifierSnippet',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.modifierSnippets.entries.size).toBe(0);
+    expect(runtime.registries.modifierSnippetRevision).toBe(0);
+    expect(runtime.registries.renderEffects).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'WgpuRenderEffect',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.compressedTextureDecoder).toEqual({
+      entry: null,
+      onMiss: 'Unregistered',
+      registry: 'WgpuCompressedTextureDecoder',
+      shape: 'slot',
+    });
+    expect(runtime.registries.colorAdjustments).toBeUndefined();
+    expect(runtime.registries.compressedTextureUpload).toEqual({
+      entry: null,
+      onMiss: 'Unregistered',
+      registry: 'WgpuCompressedTextureUpload',
+      shape: 'slot',
+    });
+    expect(runtime.registries.shapeRasterizer).toEqual({
+      entry: null,
+      onMiss: 'Unregistered',
+      registry: 'WgpuShapeRasterizer',
+      shape: 'slot',
+    });
+    expect(runtime.registries.strokeTessellator).toEqual({
+      entry: null,
+      onMiss: 'Rasterize',
+      registry: 'StrokeTessellator',
+      shape: 'slot',
+    });
+    expect(runtime.registries.velocityWriters).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'WgpuVelocityWriter',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.velocityWriters.entries.size).toBe(0);
   });
 });
 
@@ -191,6 +451,55 @@ describe('destroyWgpuRenderState', () => {
   });
 });
 
+describe('getWgpuColorAdjustmentMaterialFeature', () => {
+  it('resolves only a bound feature entry', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const feature: WgpuColorAdjustmentMaterialFeature = {
+      fragmentShaderChunk: '',
+      matrixFragmentShaderChunk: '',
+      record: vi.fn(),
+      resolveFlush: vi.fn(() => null),
+    };
+    const runtime = getWgpuRenderStateRuntime(state);
+
+    expect(getWgpuColorAdjustmentMaterialFeature(state)).toBeNull();
+    runtime.registries.colorAdjustmentFeature = {
+      entry: { state: RegistryEntryState.Bound, value: feature },
+      onMiss: 'Disabled',
+      registry: 'WgpuColorAdjustmentFeature',
+      shape: 'slot',
+    };
+    expect(getWgpuColorAdjustmentMaterialFeature(state)).toBe(feature);
+    runtime.registries.colorAdjustmentFeature = {
+      ...runtime.registries.colorAdjustmentFeature,
+      entry: { state: RegistryEntryState.Tombstoned },
+    };
+    expect(getWgpuColorAdjustmentMaterialFeature(state)).toBeNull();
+  });
+});
+
+describe('getWgpuColorAdjustmentMaterialFeatureGuard', () => {
+  it('resolves only a bound guard entry', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const guard: WgpuColorAdjustmentMaterialFeatureGuard = vi.fn();
+    const runtime = getWgpuRenderStateRuntime(state);
+
+    expect(getWgpuColorAdjustmentMaterialFeatureGuard(state)).toBeNull();
+    runtime.registries.colorAdjustmentFeatureGuard = {
+      entry: { state: RegistryEntryState.Bound, value: guard },
+      onMiss: 'Disabled',
+      registry: 'WgpuColorAdjustmentFeatureGuard',
+      shape: 'slot',
+    };
+    expect(getWgpuColorAdjustmentMaterialFeatureGuard(state)).toBe(guard);
+    runtime.registries.colorAdjustmentFeatureGuard = {
+      ...runtime.registries.colorAdjustmentFeatureGuard,
+      entry: { state: RegistryEntryState.Tombstoned },
+    };
+    expect(getWgpuColorAdjustmentMaterialFeatureGuard(state)).toBeNull();
+  });
+});
+
 describe('getWgpuRenderStateRuntime', () => {
   it('returns the runtime attached by createWgpuRenderState', async () => {
     const state = await createWgpuRenderStateForTest();
@@ -265,3 +574,12 @@ describe('isWgpuSupported', () => {
     expect(isWgpuSupported()).toBe(true);
   });
 });
+
+describe('resolveWgpuApplyBlendMode', () => {
+  it('returns a hook installed directly on the state', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const hook = vi.fn();
+    state.applyBlendMode = hook;
+    expect(resolveWgpuApplyBlendMode(state)).toBe(hook);
+  });
+});

package/src/wgpuTestHelper.test.ts

@@ -0,0 +1,64 @@
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('installWgpuMock', () => {
+  it('accepts aligned writeBuffer data using typed-array element units', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const buffer = state.device.createBuffer({ size: 8, usage: GPUBufferUsage.COPY_DST });
+
+    expect(() => state.device.queue.writeBuffer(buffer, 0, new Uint16Array([0, 1, 2]), 0, 2)).not.toThrow();
+  });
+
+  it('rejects writeBuffer content whose byte length is not a multiple of four', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const buffer = state.device.createBuffer({ size: 8, usage: GPUBufferUsage.COPY_DST });
+
+    expect(() => state.device.queue.writeBuffer(buffer, 0, new Uint16Array([0, 1, 2]))).toThrow(
+      expect.objectContaining({ name: 'OperationError' }),
+    );
+  });
+
+  it('rejects writeBuffer source ranges and destination offsets outside the API contract', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const buffer = state.device.createBuffer({ size: 8, usage: GPUBufferUsage.COPY_DST });
+
+    expect(() => state.device.queue.writeBuffer(buffer, 0, new Uint32Array([0]), 2)).toThrow(
+      /data range is out of bounds/,
+    );
+    expect(() => state.device.queue.writeBuffer(buffer, 2, new Uint32Array([0]))).toThrow(
+      /bufferOffset must be a non-negative multiple of 4/,
+    );
+  });
+
+  it('rejects writeBuffer destinations without enough COPY_DST storage', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const tooSmall = state.device.createBuffer({ size: 4, usage: GPUBufferUsage.COPY_DST });
+    const wrongUsage = state.device.createBuffer({ size: 8, usage: GPUBufferUsage.VERTEX });
+
+    expect(() => state.device.queue.writeBuffer(tooSmall, 0, new Uint32Array([0, 1]))).toThrow(
+      /destination range exceeds the buffer size/,
+    );
+    expect(() => state.device.queue.writeBuffer(wrongUsage, 0, new Uint32Array([0]))).toThrow(
+      /must have COPY_DST usage/,
+    );
+  });
+
+  it('rejects writeTexture data smaller than an rgba8 copy requires', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const texture = state.device.createTexture({
+      size: [2, 2, 1],
+      format: 'rgba8unorm',
+      usage: GPUTextureUsage.COPY_DST,
+    });
+
+    expect(() =>
+      state.device.queue.writeTexture({ texture }, new Uint8Array(15), { bytesPerRow: 8, rowsPerImage: 2 }, [2, 2, 1]),
+    ).toThrow(expect.objectContaining({ name: 'OperationError' }));
+    expect(() =>
+      state.device.queue.writeTexture({ texture }, new Uint8Array(16), { bytesPerRow: 8, rowsPerImage: 2 }, [2, 2, 1]),
+    ).not.toThrow();
+  });
+});

package/src/wgpuTextureResolver.test.ts

@@ -1,4 +1,5 @@
 import { createEntity } from '@flighthq/entity/contract';
+import { getRegistryTableKeys } from '@flighthq/registry/contract';
 import type { Image, RenderTexture, Texture, TextureSource } from '@flighthq/types/contract';
 import {
   BitmapTextureSourceKind,
@@ -83,11 +84,17 @@ function renderTexture(): RenderTexture {
   return texture as RenderTexture;
 }
 
+function registeredTextureSourceKinds(state: Parameters<typeof getWgpuRenderStateRuntime>[0]): string[] {
+  const kinds: string[] = [];
+  getRegistryTableKeys(kinds, getWgpuRenderStateRuntime(state).registries.textureResolvers);
+  return kinds;
+}
+
 describe('registerStandardWgpuTextureResolvers', () => {
   it('registers bitmap, image, and render texture sources without compressed images', async () => {
     const state = await createWgpuRenderStateForTest();
     registerStandardWgpuTextureResolvers(state);
-    expect([...getWgpuRenderStateRuntime(state).wgpuTextureResolverRegistry!.keys()]).toEqual([
+    expect(registeredTextureSourceKinds(state)).toEqual([
       BitmapTextureSourceKind,
       ImageTextureSourceKind,
       RenderTargetTextureSourceKind,
@@ -99,9 +106,7 @@ describe('registerWgpuBitmapTextureResolver', () => {
   it('registers only the Bitmap source key', async () => {
     const state = await createWgpuRenderStateForTest();
     registerWgpuBitmapTextureResolver(state);
-    expect([...getWgpuRenderStateRuntime(state).wgpuTextureResolverRegistry!.keys()]).toEqual([
-      BitmapTextureSourceKind,
-    ]);
+    expect(registeredTextureSourceKinds(state)).toEqual([BitmapTextureSourceKind]);
   });
 });
 
@@ -109,9 +114,7 @@ describe('registerWgpuCompressedImageTextureResolver', () => {
   it('registers only the CompressedImage source key', async () => {
     const state = await createWgpuRenderStateForTest();
     registerWgpuCompressedImageTextureResolver(state);
-    expect([...getWgpuRenderStateRuntime(state).wgpuTextureResolverRegistry!.keys()]).toEqual([
-      CompressedImageTextureSourceKind,
-    ]);
+    expect(registeredTextureSourceKinds(state)).toEqual([CompressedImageTextureSourceKind]);
   });
 });