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

package/src/glRenderState.test.ts

@@ -1,14 +1,31 @@
 import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/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 { BlendMode } from '@flighthq/types/contract';
-
-import { enableGlRenderStateGuards } from './enableGlRenderStateGuards';
+import type {
+  GlColorAdjustmentMaterialFeature,
+  GlColorAdjustmentMaterialFeatureGuard,
+  RenderEffectPaddingResolver,
+  RenderState,
+} from '@flighthq/types/contract';
+import { BlendMode, RegistryEntryState } from '@flighthq/types/contract';
+
+import { areGlRenderStateGuardsEnabled, enableGlRenderStateGuards } from './enableGlRenderStateGuards';
+import { registerGlCompressedTextureDecoder, registerGlCompressedTextureUpload } from './glCompressedTexture';
+import { isBlendModeSupported, registerGlBlendMode } from './glDraw';
 import { registerGlMaterialRenderer } from './glMaterialRegistry';
 import {
   copyGlRenderStateRegistrations,
@@ -16,6 +33,8 @@ import {
   createGlRenderState,
   createGlRenderStateRuntime,
   destroyGlRenderState,
+  getGlColorAdjustmentMaterialFeature,
+  getGlColorAdjustmentMaterialFeatureGuard,
   getGlRenderStateRuntime,
   invalidateGlRenderStateCache,
 } from './glRenderState';
@@ -31,32 +50,135 @@ function makeCanvas() {
   return { canvas, gl };
 }
 
+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('copyGlRenderStateRegistrations', () => {
   it('copies late GL registrations only when explicitly requested', () => {
     const { canvas } = makeCanvas();
     const screen = createGlRenderState(canvas);
     const offscreen = createGlOffscreenRenderState(screen);
+    const materialRenderer = { instanceFloatCount: 0, bind: vi.fn() } as never;
+    const offscreenMaterialRenderer = { instanceFloatCount: 0, bind: vi.fn() } as never;
+    const decoder = vi.fn(() => new Uint8ClampedArray(4));
     const resolver = vi.fn(() => null);
+    registerGlBlendMode(screen, 'acme.LateBlend', { src: 'ONE', dst: 'ZERO' });
+    registerGlCompressedTextureDecoder(screen, decoder);
+    registerGlCompressedTextureUpload(screen);
+    registerGlMaterialRenderer(screen, 'acme.LateMaterial', materialRenderer);
     registerGlTextureResolver(screen, 'acme.LateTexture', resolver);
 
-    expect(getGlRenderStateRuntime(offscreen).glTextureResolverRegistry?.has('acme.LateTexture')).not.toBe(true);
+    expect(isBlendModeSupported(offscreen, 'acme.LateBlend')).toBe(false);
+    expect(
+      hasRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(false);
+    expect(
+      hasRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(false);
+    expect(getGlRenderStateRuntime(offscreen).registries.compressedTextureDecoder.entry).toBeNull();
+    expect(getGlRenderStateRuntime(offscreen).registries.compressedTextureUpload.entry).toBeNull();
     copyGlRenderStateRegistrations(offscreen, screen);
-    expect(getGlRenderStateRuntime(offscreen).glTextureResolverRegistry?.get('acme.LateTexture')).toBe(resolver);
+    expect(isBlendModeSupported(offscreen, 'acme.LateBlend')).toBe(true);
+    expect(
+      getRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(materialRenderer);
+    expect(
+      getRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(resolver);
+    expect(getGlRenderStateRuntime(offscreen).registries.compressedTextureDecoder).toBe(
+      getGlRenderStateRuntime(screen).registries.compressedTextureDecoder,
+    );
+    expect(getGlRenderStateRuntime(offscreen).registries.compressedTextureDecoder.entry).toEqual({
+      state: RegistryEntryState.Bound,
+      value: decoder,
+    });
+    expect(getGlRenderStateRuntime(offscreen).registries.compressedTextureUpload).toBe(
+      getGlRenderStateRuntime(screen).registries.compressedTextureUpload,
+    );
+    registerGlMaterialRenderer(offscreen, 'acme.LateMaterial', offscreenMaterialRenderer);
+    registerGlBlendMode(offscreen, 'acme.LateBlend', { src: 'ZERO', dst: 'ONE' });
+    registerGlCompressedTextureDecoder(offscreen, null);
+    registerGlCompressedTextureUpload(offscreen, null);
+    registerGlTextureResolver(offscreen, 'acme.LateTexture', null);
+    expect(
+      getRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(offscreenMaterialRenderer);
+    expect(
+      getRegistryTableEntry(getGlRenderStateRuntime(screen).registries.materialRenderers, 'acme.LateMaterial'),
+    ).toBe(materialRenderer);
+    expect(
+      getRegistryTableEntry(getGlRenderStateRuntime(screen).registries.blendRealizations, 'acme.LateBlend'),
+    ).toEqual({ src: 'ONE', dst: 'ZERO' });
+    expect(
+      hasRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(false);
+    expect(getRegistryTableEntry(getGlRenderStateRuntime(screen).registries.textureResolvers, 'acme.LateTexture')).toBe(
+      resolver,
+    );
+    expect(getGlRenderStateRuntime(offscreen).registries.compressedTextureDecoder.entry).toBeNull();
+    expect(getGlRenderStateRuntime(screen).registries.compressedTextureDecoder.entry?.state).toBe(
+      RegistryEntryState.Bound,
+    );
+    expect(getGlRenderStateRuntime(offscreen).registries.compressedTextureUpload.entry).toBeNull();
+    expect(getGlRenderStateRuntime(screen).registries.compressedTextureUpload.entry?.state).toBe(
+      RegistryEntryState.Bound,
+    );
   });
 });
 
 describe('createGlOffscreenRenderState', () => {
-  it('shares context resources while snapshotting registration policy into independent maps', () => {
+  it('shares context resources and persistent registration snapshots through independent aggregates', () => {
     const { canvas } = makeCanvas();
     const screen = createGlRenderState(canvas);
     const renderer = { createData: () => null, submit: vi.fn() };
     const materialRenderer = { getBatchData: vi.fn(), getBatchFloats: vi.fn() } as never;
     const paddingResolver = vi.fn(() => ({ bottom: 1, left: 1, right: 1, top: 1 }));
     const textureResolver = vi.fn(() => null);
+    const effectRunner = vi.fn();
+    const colorAdjustmentFeature: GlColorAdjustmentMaterialFeature = {
+      drawShapeMeshes: vi.fn(),
+      flush: vi.fn(() => false),
+      fragmentShaderChunk: '',
+      matrixFragmentShaderChunk: '',
+      record: vi.fn(),
+    };
+    const colorAdjustmentFeatureGuard: GlColorAdjustmentMaterialFeatureGuard = vi.fn();
     registerRenderer(screen, 'acme.Node', renderer);
     registerGlMaterialRenderer(screen, 'acme.Material', materialRenderer);
     registerGlTextureResolver(screen, 'acme.Texture', textureResolver);
-    getRenderStateRuntime(screen).renderEffectPaddingResolverRegistry = new Map([['acme.Effect', paddingResolver]]);
+    enableColorAdjustments(screen);
+    enableColorAdjustmentGuards(screen);
+    enableGlRenderStateGuards(screen);
+    getGlRenderStateRuntime(screen).registries.renderEffects = withRegistryTableEntry(
+      getGlRenderStateRuntime(screen).registries.renderEffects,
+      'acme.Effect',
+      { runner: effectRunner as never },
+    );
+    registerPaddingResolver(screen, 'acme.Effect', paddingResolver);
+    getGlRenderStateRuntime(screen).registries.colorAdjustmentFeature = {
+      entry: { state: RegistryEntryState.Bound, value: colorAdjustmentFeature },
+      onMiss: 'Disabled',
+      registry: 'GlColorAdjustmentFeature',
+      shape: 'slot',
+    };
+    getGlRenderStateRuntime(screen).registries.colorAdjustmentFeatureGuard = {
+      entry: { state: RegistryEntryState.Bound, value: colorAdjustmentFeatureGuard },
+      onMiss: 'Disabled',
+      registry: 'GlColorAdjustmentFeatureGuard',
+      shape: 'slot',
+    };
     getGlRenderStateRuntime(screen).glRenderTextureCache = new WeakMap();
 
     const offscreen = createGlOffscreenRenderState(screen);
@@ -71,16 +193,67 @@ describe('createGlOffscreenRenderState', () => {
     );
     expect(offscreenRuntime.glRenderTextureCache).toBe(screenRuntime.glRenderTextureCache);
     expect(offscreenRuntime.quadIndexBuffer).toBe(screenRuntime.quadIndexBuffer);
-    expect(offscreenRuntime.rendererMap).not.toBe(screenRuntime.rendererMap);
-    expect(offscreenRuntime.materialRendererMap).not.toBe(screenRuntime.materialRendererMap);
-    expect(offscreenRuntime.glTextureResolverRegistry).not.toBe(screenRuntime.glTextureResolverRegistry);
-    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.blendRealizations).toBe(screenRuntime.registries.blendRealizations);
+    expect(offscreenRuntime.registries.colorAdjustmentFeature).toBe(screenRuntime.registries.colorAdjustmentFeature);
+    expect(getGlColorAdjustmentMaterialFeature(offscreen)).toBe(colorAdjustmentFeature);
+    expect(offscreenRuntime.registries.colorAdjustmentFeatureGuard).toBe(
+      screenRuntime.registries.colorAdjustmentFeatureGuard,
+    );
+    expect(getGlColorAdjustmentMaterialFeatureGuard(offscreen)).toBe(colorAdjustmentFeatureGuard);
+    const sharedColorFeatureGuard = offscreenRuntime.registries.colorAdjustmentFeatureGuard;
+    screenRuntime.registries.colorAdjustmentFeatureGuard = undefined;
+    expect(getGlColorAdjustmentMaterialFeatureGuard(screen)).toBeNull();
+    expect(offscreenRuntime.registries.colorAdjustmentFeatureGuard).toBe(sharedColorFeatureGuard);
+    expect(getGlColorAdjustmentMaterialFeatureGuard(offscreen)).toBe(colorAdjustmentFeatureGuard);
+    const sharedColorFeature = offscreenRuntime.registries.colorAdjustmentFeature;
+    screenRuntime.registries.colorAdjustmentFeature = undefined;
+    expect(getGlColorAdjustmentMaterialFeature(screen)).toBeNull();
+    expect(offscreenRuntime.registries.colorAdjustmentFeature).toBe(sharedColorFeature);
+    expect(getGlColorAdjustmentMaterialFeature(offscreen)).toBe(colorAdjustmentFeature);
+    expect(offscreenRuntime.registries.colorAdjustments).toBe(screenRuntime.registries.colorAdjustments);
+    expect(offscreenRuntime.registries.colorAdjustmentUnsupportedGuard).toBe(
+      screenRuntime.registries.colorAdjustmentUnsupportedGuard,
     );
-    expect(offscreenRuntime.rendererMap.get('acme.Node')).toBe(renderer);
-    expect(offscreenRuntime.materialRendererMap?.get('acme.Material')).toBe(materialRenderer);
-    expect(offscreenRuntime.glTextureResolverRegistry?.get('acme.Texture')).toBe(textureResolver);
-    expect(offscreenRuntime.renderEffectPaddingResolverRegistry?.get('acme.Effect')).toBe(paddingResolver);
+    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(areGlRenderStateGuardsEnabled(offscreen)).toBe(true);
+    const sharedRenderRootGuard = offscreenRuntime.registries.renderRootGuard;
+    screenRuntime.registries.renderRootGuard = undefined;
+    expect(screenRuntime.registries.renderRootGuard).toBeUndefined();
+    expect(offscreenRuntime.registries.renderRootGuard).toBe(sharedRenderRootGuard);
+    expect(areGlRenderStateGuardsEnabled(offscreen)).toBe(true);
+    expect(offscreenRuntime.registries.compressedTextureDecoder).toBe(
+      screenRuntime.registries.compressedTextureDecoder,
+    );
+    expect(offscreenRuntime.registries.compressedTextureUpload).toBe(screenRuntime.registries.compressedTextureUpload);
+    expect(offscreenRuntime.registries.customEffectShaders).toBe(screenRuntime.registries.customEffectShaders);
+    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.pbrExtensions).toBe(screenRuntime.registries.pbrExtensions);
+    expect(offscreenRuntime.registries.pbrExtensionRevision).toBe(screenRuntime.registries.pbrExtensionRevision);
+    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')?.runner).toBe(effectRunner);
+    expect(getPaddingResolver(offscreen, 'acme.Effect')).toBe(paddingResolver);
 
     screenRuntime.currentProgram = {} as WebGLProgram;
     expect(offscreenRuntime.currentProgram).toBe(screenRuntime.currentProgram);
@@ -95,19 +268,23 @@ describe('createGlOffscreenRenderState', () => {
     const resolver = vi.fn(() => null);
     registerRenderer(screen, 'acme.LateNode', renderer);
     registerGlTextureResolver(screen, 'acme.LateTexture', resolver);
-    getRenderStateRuntime(screen).renderEffectPaddingResolverRegistry = new Map([['acme.LateEffect', paddingResolver]]);
+    registerPaddingResolver(screen, 'acme.LateEffect', paddingResolver);
 
-    expect(getRenderStateRuntime(offscreen).rendererMap.has('acme.LateNode')).toBe(false);
-    expect(getGlRenderStateRuntime(offscreen).glTextureResolverRegistry?.has('acme.LateTexture')).not.toBe(true);
-    expect(getRenderStateRuntime(offscreen).renderEffectPaddingResolverRegistry?.has('acme.LateEffect')).not.toBe(true);
+    expect(hasRegistryTableEntry(getRenderStateRuntime(offscreen).registries.renderers, 'acme.LateNode')).toBe(false);
+    expect(
+      hasRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(false);
+    expect(getPaddingResolver(offscreen, 'acme.LateEffect')).toBeNull();
 
     copyAllRenderersFromRenderState(offscreen, screen);
     copyGlRenderStateRegistrations(offscreen, screen);
-    expect(getRenderStateRuntime(offscreen).rendererMap.get('acme.LateNode')).toBe(renderer);
-    expect(getGlRenderStateRuntime(offscreen).glTextureResolverRegistry?.get('acme.LateTexture')).toBe(resolver);
-    expect(getRenderStateRuntime(offscreen).renderEffectPaddingResolverRegistry?.get('acme.LateEffect')).toBe(
-      paddingResolver,
+    expect(getRegistryTableEntry(getRenderStateRuntime(offscreen).registries.renderers, 'acme.LateNode')).toBe(
+      renderer,
     );
+    expect(
+      getRegistryTableEntry(getGlRenderStateRuntime(offscreen).registries.textureResolvers, 'acme.LateTexture'),
+    ).toBe(resolver);
+    expect(getPaddingResolver(offscreen, 'acme.LateEffect')).toBe(paddingResolver);
   });
 
   it('keeps proxy trees independent and destroys derived renderer data without freeing shared context resources', () => {
@@ -229,9 +406,89 @@ describe('createGlRenderState', () => {
 });
 
 describe('createGlRenderStateRuntime', () => {
-  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 = createGlRenderStateRuntime();
     expect(runtime.binding).toBeNull();
+    expect(runtime.registries.blendRealizations).toMatchObject({
+      onMiss: 'Normal',
+      registry: 'GlBlendRealization',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.blendRealizations.entries.size).toBe(0);
+    expect(runtime.registries.customEffectShaders).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'GlCustomEffectShader',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.customEffectShaders.entries.size).toBe(0);
+    expect(runtime.registries.customMaterialShaders).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'GlCustomMaterialShader',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.customMaterialShaders.entries.size).toBe(0);
+    expect(runtime.registries.materialRenderers).toMatchObject({
+      onMiss: 'StandardMaterial',
+      registry: 'GlMaterialRenderer',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.materialRenderers.entries.size).toBe(0);
+    expect(runtime.registries.meshMaterialRenderers).toMatchObject({
+      onMiss: 'StandardMaterial',
+      registry: 'GlMeshMaterialRenderer',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.meshMaterialRenderers.entries.size).toBe(0);
+    expect(runtime.registries.modifierSnippets).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'GlModifierSnippet',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.modifierSnippets.entries.size).toBe(0);
+    expect(runtime.registries.modifierSnippetRevision).toBe(0);
+    expect(runtime.registries.pbrExtensions).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'GlPbrExtension',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.pbrExtensions.entries.size).toBe(0);
+    expect(runtime.registries.pbrExtensionRevision).toBe(0);
+    expect(runtime.registries.renderEffects).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'GlRenderEffect',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.compressedTextureDecoder).toEqual({
+      entry: null,
+      onMiss: 'Unregistered',
+      registry: 'GlCompressedTextureDecoder',
+      shape: 'slot',
+    });
+    expect(runtime.registries.colorAdjustments).toBeUndefined();
+    expect(runtime.registries.compressedTextureUpload).toEqual({
+      entry: null,
+      onMiss: 'Unregistered',
+      registry: 'GlCompressedTextureUpload',
+      shape: 'slot',
+    });
+    expect(runtime.registries.shapeRasterizer).toEqual({
+      entry: null,
+      onMiss: 'Unregistered',
+      registry: 'GlShapeRasterizer',
+      shape: 'slot',
+    });
+    expect(runtime.registries.strokeTessellator).toEqual({
+      entry: null,
+      onMiss: 'Rasterize',
+      registry: 'StrokeTessellator',
+      shape: 'slot',
+    });
+    expect(runtime.registries.velocityWriters).toMatchObject({
+      onMiss: 'Unregistered',
+      registry: 'GlVelocityWriter',
+      shape: 'keyed',
+    });
+    expect(runtime.registries.velocityWriters.entries.size).toBe(0);
   });
 });
 
@@ -275,6 +532,58 @@ describe('enableGlRenderStateGuards', () => {
   });
 });
 
+describe('getGlColorAdjustmentMaterialFeature', () => {
+  it('resolves only a bound feature entry', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    const feature: GlColorAdjustmentMaterialFeature = {
+      drawShapeMeshes: vi.fn(),
+      flush: vi.fn(() => false),
+      fragmentShaderChunk: '',
+      matrixFragmentShaderChunk: '',
+      record: vi.fn(),
+    };
+    const runtime = getGlRenderStateRuntime(state);
+
+    expect(getGlColorAdjustmentMaterialFeature(state)).toBeNull();
+    runtime.registries.colorAdjustmentFeature = {
+      entry: { state: RegistryEntryState.Bound, value: feature },
+      onMiss: 'Disabled',
+      registry: 'GlColorAdjustmentFeature',
+      shape: 'slot',
+    };
+    expect(getGlColorAdjustmentMaterialFeature(state)).toBe(feature);
+    runtime.registries.colorAdjustmentFeature = {
+      ...runtime.registries.colorAdjustmentFeature,
+      entry: { state: RegistryEntryState.Tombstoned },
+    };
+    expect(getGlColorAdjustmentMaterialFeature(state)).toBeNull();
+  });
+});
+
+describe('getGlColorAdjustmentMaterialFeatureGuard', () => {
+  it('resolves only a bound guard entry', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    const guard: GlColorAdjustmentMaterialFeatureGuard = vi.fn();
+    const runtime = getGlRenderStateRuntime(state);
+
+    expect(getGlColorAdjustmentMaterialFeatureGuard(state)).toBeNull();
+    runtime.registries.colorAdjustmentFeatureGuard = {
+      entry: { state: RegistryEntryState.Bound, value: guard },
+      onMiss: 'Disabled',
+      registry: 'GlColorAdjustmentFeatureGuard',
+      shape: 'slot',
+    };
+    expect(getGlColorAdjustmentMaterialFeatureGuard(state)).toBe(guard);
+    runtime.registries.colorAdjustmentFeatureGuard = {
+      ...runtime.registries.colorAdjustmentFeatureGuard,
+      entry: { state: RegistryEntryState.Tombstoned },
+    };
+    expect(getGlColorAdjustmentMaterialFeatureGuard(state)).toBeNull();
+  });
+});
+
 describe('getGlRenderStateRuntime', () => {
   it('returns the runtime attached by createGlRenderState', () => {
     const { canvas } = makeCanvas();

package/src/glRenderStateBracket.test.ts

@@ -23,6 +23,9 @@ type TestGlState = {
   blendSrcRgb: number;
   cullFace: boolean;
   cullFaceMode: number;
+  frontFace: number;
+  stencilTest: boolean;
+  stencilWriteMask: number;
   currentRenderTarget: GlRenderTarget | null;
   depthFunc: number;
   depthMask: boolean;
@@ -58,6 +61,9 @@ const OUTER_STATE: TestGlState = {
   blendSrcRgb: 1,
   cullFace: false,
   cullFaceMode: 0x0405,
+  frontFace: 0x0900, // GL_CW — a host that does not use Flight's default
+  stencilTest: true, // enabled on purpose: a fixture that starts disabled cannot tell 'restored' from 'left off'
+  stencilWriteMask: 0x0f,
   currentRenderTarget: { name: 'outer-target' } as unknown as GlRenderTarget,
   depthFunc: 0x0203,
   depthMask: false,
@@ -86,6 +92,9 @@ const MIDDLE_STATE: TestGlState = {
   blendSrcRgb: 1,
   cullFace: true,
   cullFaceMode: 0x0404,
+  frontFace: 0x0901, // GL_CCW
+  stencilTest: false,
+  stencilWriteMask: 0xff,
   currentRenderTarget: { name: 'middle-target' } as unknown as GlRenderTarget,
   depthFunc: 0x0201,
   depthMask: true,
@@ -136,6 +145,57 @@ describe('popGlRenderState', () => {
     expectTestGlState(fixture, OUTER_STATE);
   });
 
+  it('restores a two-sided stencil configuration without collapsing the back face onto the front', () => {
+    const fixture = createStatefulGl();
+    const gl = fixture.gl;
+    applyTestGlState(fixture, OUTER_STATE);
+    // A host driving two-sided stencil — the case stencilOpSeparate exists for. Every back-face value
+    // differs from its front counterpart, so a restore that writes both faces from the front's saved
+    // values cannot pass by coincidence: it would report the front correct and the back overwritten.
+    gl.stencilOpSeparate(gl.FRONT, 0x1e00, 0x1e00, 0x1e01); // KEEP, KEEP, REPLACE
+    gl.stencilOpSeparate(gl.BACK, 0x1e02, 0x1e03, 0x150a); // INCR, DECR, INVERT
+    gl.stencilFuncSeparate(gl.FRONT, 0x0201, 1, 0xf0); // LESS
+    gl.stencilFuncSeparate(gl.BACK, 0x0204, 2, 0x0f); // GREATER
+    gl.stencilMaskSeparate(gl.FRONT, 0xaa);
+    gl.stencilMaskSeparate(gl.BACK, 0x55);
+    const host = new Map(fixture.parameters);
+    pushGlRenderState(fixture.state);
+
+    // What Flight's own 2D clip pass writes: separate wrap ops per face, then a symmetric gate.
+    gl.stencilOpSeparate(gl.FRONT, 0x1e00, 0x1e00, 0x8507); // INCR_WRAP
+    gl.stencilOpSeparate(gl.BACK, 0x1e00, 0x1e00, 0x8508); // DECR_WRAP
+    gl.stencilFunc(0x0207, 0, 0xff); // ALWAYS, both faces
+    gl.stencilMask(0xff);
+    popGlRenderState(fixture.state);
+
+    for (const parameter of TWO_SIDED_STENCIL_PARAMETERS) {
+      expect([parameter, fixture.parameters.get(gl[parameter])]).toEqual([parameter, host.get(gl[parameter])]);
+    }
+  });
+
+  it('restores colour-write, clear-colour, and upload-premultiply state Flight leaves behind', () => {
+    const fixture = createStatefulGl();
+    const gl = fixture.gl;
+    applyTestGlState(fixture, OUTER_STATE);
+    // A host whose own settings all differ from both the GL defaults and from what Flight will set,
+    // so neither 'never restored' nor 'reset to the default' can pass as restoration.
+    gl.colorMask(true, false, true, false);
+    gl.clearColor(0.25, 0.5, 0.75, 1);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    pushGlRenderState(fixture.state);
+
+    // What Flight's own passes do: mask colour off while rasterizing clip coverage, clear a target,
+    // and premultiply a texture upload. None of these puts the previous value back.
+    gl.colorMask(false, false, false, false);
+    gl.clearColor(0, 0, 0, 0);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+    popGlRenderState(fixture.state);
+
+    expect(fixture.parameters.get(gl.COLOR_WRITEMASK)).toEqual([true, false, true, false]);
+    expect(fixture.parameters.get(gl.COLOR_CLEAR_VALUE)).toEqual([0.25, 0.5, 0.75, 1]);
+    expect(fixture.parameters.get(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL)).toBe(false);
+  });
+
   it('restores a non-active texture unit binding', () => {
     const fixture = createStatefulGl();
     applyTestGlState(fixture, OUTER_STATE);
@@ -207,6 +267,9 @@ function applyTestGlState(fixture: StatefulGl, values: Readonly<TestGlState>): v
   gl.depthFunc(values.depthFunc);
   setCapability(gl, gl.CULL_FACE, values.cullFace);
   gl.cullFace(values.cullFaceMode);
+  gl.frontFace(values.frontFace);
+  setCapability(gl, gl.STENCIL_TEST, values.stencilTest);
+  gl.stencilMask(values.stencilWriteMask);
   setCapability(gl, gl.BLEND, values.blend);
   gl.blendFuncSeparate(values.blendSrcRgb, values.blendDstRgb, values.blendSrcAlpha, values.blendDstAlpha);
   gl.blendEquationSeparate(values.blendEquationRgb, values.blendEquationAlpha);
@@ -244,6 +307,27 @@ function createStatefulGl(): StatefulGl & ReturnType<typeof createGlState> {
     DEPTH_FUNC: 0x0b74,
     DEPTH_WRITEMASK: 0x0b72,
     FRAMEBUFFER_BINDING: 0x8ca6,
+    FRONT_FACE: 0x0b46,
+    BACK: 0x0405,
+    COLOR_CLEAR_VALUE: 0x0c22,
+    COLOR_WRITEMASK: 0x0c23,
+    UNPACK_PREMULTIPLY_ALPHA_WEBGL: 0x9241,
+    FRONT: 0x0404,
+    STENCIL_BACK_FAIL: 0x8801,
+    STENCIL_BACK_FUNC: 0x8800,
+    STENCIL_BACK_PASS_DEPTH_FAIL: 0x8802,
+    STENCIL_BACK_PASS_DEPTH_PASS: 0x8803,
+    STENCIL_BACK_REF: 0x8ca3,
+    STENCIL_BACK_VALUE_MASK: 0x8ca4,
+    STENCIL_BACK_WRITEMASK: 0x8ca5,
+    STENCIL_FAIL: 0x0b94,
+    STENCIL_FUNC: 0x0b92,
+    STENCIL_PASS_DEPTH_FAIL: 0x0b95,
+    STENCIL_PASS_DEPTH_PASS: 0x0b96,
+    STENCIL_REF: 0x0b97,
+    STENCIL_TEST: 0x0b90,
+    STENCIL_VALUE_MASK: 0x0b93,
+    STENCIL_WRITEMASK: 0x0b98,
     SCISSOR_BOX: 0x0c10,
     TEXTURE_BINDING_2D: 0x8069,
     VERTEX_ARRAY_BINDING: 0x85b5,
@@ -271,6 +355,65 @@ function createStatefulGl(): StatefulGl & ReturnType<typeof createGlState> {
   (gl.cullFace as ReturnType<typeof vi.fn>).mockImplementation((value: number) =>
     parameters.set(gl.CULL_FACE_MODE, value),
   );
+  (gl.frontFace as ReturnType<typeof vi.fn>).mockImplementation((value: number) =>
+    parameters.set(gl.FRONT_FACE, value),
+  );
+  (gl.colorMask as ReturnType<typeof vi.fn>).mockImplementation((r: boolean, g: boolean, b: boolean, a: boolean) =>
+    parameters.set(gl.COLOR_WRITEMASK, [r, g, b, a]),
+  );
+  (gl.clearColor as ReturnType<typeof vi.fn>).mockImplementation((r: number, g: number, b: number, a: number) =>
+    parameters.set(gl.COLOR_CLEAR_VALUE, [r, g, b, a]),
+  );
+  (gl.pixelStorei as ReturnType<typeof vi.fn>).mockImplementation((parameter: number, value: unknown) =>
+    parameters.set(parameter, value),
+  );
+  // Stencil is two-faced state: the unsuffixed setters write FRONT_AND_BACK while the Separate ones
+  // write only the named face. That rule was measured against a real WebGL2 context rather than assumed
+  // here — a fake cannot be the oracle for the API it fakes. `null` is the unsuffixed, both-faces form.
+  const writeStencilMask = (face: number | null, value: number): void => {
+    if (face !== gl.BACK) parameters.set(gl.STENCIL_WRITEMASK, value);
+    if (face !== gl.FRONT) parameters.set(gl.STENCIL_BACK_WRITEMASK, value);
+  };
+  const writeStencilFunc = (face: number | null, func: number, ref: number, mask: number): void => {
+    if (face !== gl.BACK) {
+      parameters.set(gl.STENCIL_FUNC, func);
+      parameters.set(gl.STENCIL_REF, ref);
+      parameters.set(gl.STENCIL_VALUE_MASK, mask);
+    }
+    if (face !== gl.FRONT) {
+      parameters.set(gl.STENCIL_BACK_FUNC, func);
+      parameters.set(gl.STENCIL_BACK_REF, ref);
+      parameters.set(gl.STENCIL_BACK_VALUE_MASK, mask);
+    }
+  };
+  const writeStencilOp = (face: number | null, fail: number, depthFail: number, depthPass: number): void => {
+    if (face !== gl.BACK) {
+      parameters.set(gl.STENCIL_FAIL, fail);
+      parameters.set(gl.STENCIL_PASS_DEPTH_FAIL, depthFail);
+      parameters.set(gl.STENCIL_PASS_DEPTH_PASS, depthPass);
+    }
+    if (face !== gl.FRONT) {
+      parameters.set(gl.STENCIL_BACK_FAIL, fail);
+      parameters.set(gl.STENCIL_BACK_PASS_DEPTH_FAIL, depthFail);
+      parameters.set(gl.STENCIL_BACK_PASS_DEPTH_PASS, depthPass);
+    }
+  };
+  (gl.stencilMask as ReturnType<typeof vi.fn>).mockImplementation((value: number) => writeStencilMask(null, value));
+  (gl.stencilMaskSeparate as ReturnType<typeof vi.fn>).mockImplementation((face: number, value: number) =>
+    writeStencilMask(face, value),
+  );
+  (gl.stencilFunc as ReturnType<typeof vi.fn>).mockImplementation((func: number, ref: number, mask: number) =>
+    writeStencilFunc(null, func, ref, mask),
+  );
+  (gl.stencilFuncSeparate as ReturnType<typeof vi.fn>).mockImplementation(
+    (face: number, func: number, ref: number, mask: number) => writeStencilFunc(face, func, ref, mask),
+  );
+  (gl.stencilOp as ReturnType<typeof vi.fn>).mockImplementation((fail: number, dFail: number, dPass: number) =>
+    writeStencilOp(null, fail, dFail, dPass),
+  );
+  (gl.stencilOpSeparate as ReturnType<typeof vi.fn>).mockImplementation(
+    (face: number, fail: number, dFail: number, dPass: number) => writeStencilOp(face, fail, dFail, dPass),
+  );
   (gl.blendFuncSeparate as ReturnType<typeof vi.fn>).mockImplementation(
     (srcRgb: number, dstRgb: number, srcAlpha: number, dstAlpha: number) => {
       parameters.set(gl.BLEND_SRC_RGB, srcRgb);
@@ -315,6 +458,14 @@ function expectTestGlState(fixture: StatefulGl, expected: Readonly<TestGlState>)
   expect(parameters.get(gl.DEPTH_FUNC)).toBe(expected.depthFunc);
   expect(gl.isEnabled(gl.CULL_FACE)).toBe(expected.cullFace);
   expect(parameters.get(gl.CULL_FACE_MODE)).toBe(expected.cullFaceMode);
+  // The 3D mesh path picks a front face per draw from the model determinant, so this is state Flight
+  // mutates and must hand back untouched — a host set to CW must not get CCW returned.
+  expect(parameters.get(gl.FRONT_FACE)).toBe(expected.frontFace);
+  // Flight's 2D clip system rasterizes stencil masks; its internal restore is scoped to Flight's own
+  // nesting and disables the test outright when Flight had no clip, so the host-facing preservation
+  // has to happen here. The outer fixture starts ENABLED so 'restored' is distinguishable from 'left off'.
+  expect(gl.isEnabled(gl.STENCIL_TEST)).toBe(expected.stencilTest);
+  expect(parameters.get(gl.STENCIL_WRITEMASK)).toBe(expected.stencilWriteMask);
   expect(gl.isEnabled(gl.BLEND)).toBe(expected.blend);
   expect(parameters.get(gl.BLEND_SRC_RGB)).toBe(expected.blendSrcRgb);
   expect(parameters.get(gl.BLEND_DST_RGB)).toBe(expected.blendDstRgb);
@@ -347,3 +498,22 @@ function setCapability(gl: WebGL2RenderingContext, capability: number, enabled:
     gl.disable(capability);
   }
 }
+
+// Both faces of every stencil parameter the bracket saves. Naming them here rather than asserting a
+// handful keeps the list checkable against the saved-state fields by eye.
+const TWO_SIDED_STENCIL_PARAMETERS = [
+  'STENCIL_FAIL',
+  'STENCIL_BACK_FAIL',
+  'STENCIL_PASS_DEPTH_FAIL',
+  'STENCIL_BACK_PASS_DEPTH_FAIL',
+  'STENCIL_PASS_DEPTH_PASS',
+  'STENCIL_BACK_PASS_DEPTH_PASS',
+  'STENCIL_FUNC',
+  'STENCIL_BACK_FUNC',
+  'STENCIL_REF',
+  'STENCIL_BACK_REF',
+  'STENCIL_VALUE_MASK',
+  'STENCIL_BACK_VALUE_MASK',
+  'STENCIL_WRITEMASK',
+  'STENCIL_BACK_WRITEMASK',
+] as const;