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

package/src/enableGlRenderEffectGuards.test.ts

@@ -12,6 +12,12 @@ import {
   disableGlRenderEffectGuards,
   enableGlRenderEffectGuards,
 } from './enableGlRenderEffectGuards';
+import { registerGlCustomShaderSource } from './glCustomShaderEffect';
+import {
+  beginGlRenderEffectPipeline,
+  createGlRenderEffectPipeline,
+  endGlRenderEffectPipeline,
+} from './glRenderEffectPipeline';
 import { registerGlRenderEffect } from './glRenderEffectRegistry';
 import { applyGlRenderEffectsToRenderTexture } from './glRenderTextureEffect';
 
@@ -93,6 +99,71 @@ describe('enableGlRenderEffectGuards', () => {
     expect(messageOf(entries[0])).toContain('handle the false return');
   });
 
+  it('WARNS that re-registered shader source will NOT run, because the program is cached by key', () => {
+    const state = createState();
+    enableGlRenderEffectGuards(state);
+
+    const entries = captureLog(() => {
+      registerGlCustomShaderSource(state, 'test.reregistered-a', 'void main() { o_color = vec4(1.0); }');
+      // Nothing fails and nothing throws — the edit simply never reaches the GPU.
+      registerGlCustomShaderSource(state, 'test.reregistered-a', 'void main() { o_color = vec4(0.0); }');
+    });
+
+    expect(entries.length).toBe(1);
+    expect(messageOf(entries[0])).toContain('will NOT run');
+    expect(messageOf(entries[0])).toContain('test.reregistered-a');
+
+    // Negative control for the guard itself: with the guard OFF the same sequence says nothing, so the
+    // assertion above is measuring the guard rather than some other source of log traffic.
+    disableGlRenderEffectGuards(state);
+    const afterDisable = captureLog(() => {
+      registerGlCustomShaderSource(state, 'test.reregistered-b', 'void main() { o_color = vec4(1.0); }');
+      registerGlCustomShaderSource(state, 'test.reregistered-b', 'void main() { o_color = vec4(0.0); }');
+    });
+    expect(afterDisable.length).toBe(0);
+  });
+
+  it('WARNS that an unresolvable effect COPIED THROUGH rather than being dropped', () => {
+    const state = createState();
+    registerGlRenderEffect(state, 'test.unresolved-a', noopRunner, () => false);
+    enableGlRenderEffectGuards(state);
+
+    const entries = captureLog(() => {
+      // It returns TRUE and writes dest — the pass ran, it just did nothing. That is the whole hazard.
+      expect(applyChain(state, ['test.unresolved-a'])).toBe(true);
+    });
+
+    expect(entries.length).toBe(1);
+    // The wrong picture is passthrough, not drop; saying "dropped" here would send the reader to the
+    // registration call, which is already correct.
+    expect(messageOf(entries[0])).toContain('COPIED THE INPUT THROUGH UNCHANGED');
+    expect(messageOf(entries[0])).not.toContain('SKIPPED');
+  });
+
+  it('WARNS that a pipeline pass DROPPED an effect kind with no runner, once per kind', () => {
+    const state = createState();
+    enableGlRenderEffectGuards(state);
+    const pipeline = createGlRenderEffectPipeline(state);
+
+    const entries = captureLog(() => {
+      beginGlRenderEffectPipeline(state, pipeline);
+      endGlRenderEffectPipeline(state, pipeline, [{ kind: 'test.pipeline-dropped-kind' } as RenderEffect]);
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(messageOf(entries[0])).toContain('test.pipeline-dropped-kind');
+    expect(messageOf(entries[0])).toContain('SKIPPED');
+
+    // Once per KIND, not once per frame: a chain missing the same effect every frame is one
+    // observation, and a warning that repeated per frame would be its own defect.
+    const again = captureLog(() => {
+      beginGlRenderEffectPipeline(state, pipeline);
+      endGlRenderEffectPipeline(state, pipeline, [{ kind: 'test.pipeline-dropped-kind' } as RenderEffect]);
+    });
+
+    expect(again).toHaveLength(0);
+  });
+
   it('stays SILENT for an empty chain, which is a no-op the caller asked for rather than a miss', () => {
     const state = createState();
     enableGlRenderEffectGuards(state);

package/src/glBevelEffect.test.ts

@@ -1,9 +1,107 @@
+// The highlight/shadow colors are packed RGBA and their alpha multiplies the matching *Alpha field, the
+// same arithmetic BitmapBevelOptions has always used offscreen. The composite shader still takes RGB plus
+// one alpha, so the split happens in the runner — which makes the uniform the only place the migration is
+// observable, and the reason this file mocks the draw seam rather than asserting on pixels.
+const glMock = vi.hoisted(() => ({
+  uniform1f: vi.fn(),
+  uniform2f: vi.fn(),
+  uniform4f: vi.fn(),
+}));
+
+vi.hoisted(() => {
+  vi.resetModules();
+});
+
+vi.mock('@flighthq/render-gl/contract', () => {
+  let nextTargetId = 0;
+  return {
+    acquireGlRenderTarget: vi.fn((_state, _pool, descriptor) => ({
+      ...descriptor,
+      id: `scratch-${nextTargetId++}`,
+      texture: {},
+    })),
+    clearGlRenderTarget: vi.fn(),
+    compileGlFullscreenProgram: vi.fn(() => ({
+      locHighlight: 'u_highlight',
+      locShadow: 'u_shadow',
+      program: {},
+    })),
+    drawGlFullscreenPass: vi.fn((_state, _loc, _textures, _dest, setUniforms) => {
+      setUniforms(glMock as never, {} as never);
+    }),
+    releaseGlRenderTarget: vi.fn(),
+  };
+});
+
+vi.mock('./glEffectBlitShader', () => ({
+  applyGlEffectBlitOffsetPass: vi.fn(),
+  applyGlEffectBlitPass: vi.fn(),
+  applyGlEffectErasePass: vi.fn(),
+}));
+
+vi.mock('./glEffectBoxBlur', () => ({
+  applyGlEffectBoxBlur: vi.fn(),
+}));
+
+vi.mock('./glEffectTintShader', () => ({
+  applyGlEffectTintPass: vi.fn(),
+}));
+
 import { applyBevelEffectToGl, defaultGlBevelEffectRunner, registerGlBevelEffect } from './glBevelEffect';
 
+// The runner caches its compiled locations per `state.gl`, and looks the uniform names up itself, so the
+// fake context must answer getUniformLocation with the name — which is also what makes the assertions
+// below readable as uniform names rather than opaque handles.
+const state = { gl: { getUniformLocation: (_program: unknown, name: string) => name } } as never;
+const target = { height: 4, texture: {}, width: 4 } as never;
+const pool = { free: [], inUse: [] } as never;
+
+function uniformFor(name: string): readonly number[] {
+  const call = glMock.uniform4f.mock.calls.find((entry) => entry[0] === name);
+  if (call === undefined) throw new Error(`no uniform4f call for ${name}`);
+  return call.slice(1) as readonly number[];
+}
+
 describe('applyBevelEffectToGl', () => {
   it('is a function', () => {
     expect(typeof applyBevelEffectToGl).toBe('function');
   });
+
+  it('splits each packed RGBA color into composite RGB and an alpha multiplied by its *Alpha field', () => {
+    glMock.uniform4f.mockClear();
+
+    applyBevelEffectToGl(state, target, target, pool, {
+      highlightAlpha: 0.5,
+      highlightColor: 0x9d55ff80,
+      kind: 'BevelEffect',
+      shadowAlpha: 1,
+      shadowColor: 0x102030c0,
+    });
+
+    // Under the 24-bit reading these same values would light the bevel 0x55ff80 and shade it 0x2030c0 —
+    // both different colors, both plausible, at full opacity. That is the 0x44ffee failure shape built
+    // into the API surface by construction rather than by a typo, which is what this unification removes.
+    const [highlightRed, highlightGreen, highlightBlue, highlightAlpha] = uniformFor('u_highlight');
+    expect(highlightRed).toBeCloseTo(0x9d / 255, 5);
+    expect(highlightGreen).toBeCloseTo(0x55 / 255, 5);
+    expect(highlightBlue).toBeCloseTo(1, 5);
+    expect(highlightAlpha).toBeCloseTo((0x80 / 255) * 0.5, 5);
+
+    const [shadowRed, shadowGreen, shadowBlue, shadowAlpha] = uniformFor('u_shadow');
+    expect(shadowRed).toBeCloseTo(0x10 / 255, 5);
+    expect(shadowGreen).toBeCloseTo(0x20 / 255, 5);
+    expect(shadowBlue).toBeCloseTo(0x30 / 255, 5);
+    expect(shadowAlpha).toBeCloseTo(0xc0 / 255, 5);
+  });
+
+  it('defaults to opaque white over opaque black, the pair the pre-migration defaults produced', () => {
+    glMock.uniform4f.mockClear();
+
+    applyBevelEffectToGl(state, target, target, pool, { kind: 'BevelEffect' });
+
+    expect(uniformFor('u_highlight')).toEqual([1, 1, 1, 1]);
+    expect(uniformFor('u_shadow')).toEqual([0, 0, 0, 1]);
+  });
 });
 
 describe('defaultGlBevelEffectRunner', () => {

package/src/glConvolutionEffect.test.ts

@@ -1,13 +1,73 @@
+// The edge color is the one part of this runner with a channel ORDER to get wrong, and it carried a
+// packing — 0xAARRGGBB, alpha in the high byte — that no other color in the SDK used. The uniform
+// assertion below is what makes the order a fact rather than a reading of four shift expressions.
+const glMock = vi.hoisted(() => ({
+  getUniformLocation: vi.fn((_program: unknown, name: string) => name),
+  uniform1f: vi.fn(),
+  uniform1fv: vi.fn(),
+  uniform1i: vi.fn(),
+  uniform2f: vi.fn(),
+  uniform4f: vi.fn(),
+}));
+
+vi.hoisted(() => {
+  vi.resetModules();
+});
+
+vi.mock('@flighthq/render-gl/contract', () => ({
+  drawGlFullscreenPass: vi.fn((_state, _program, _textures, _dest, setUniforms) => {
+    setUniforms(glMock as never, { program: {} } as never);
+  }),
+}));
+
+vi.mock('./glEffectProgramCache', () => ({
+  getGlEffectProgram: vi.fn(() => ({ program: {} })),
+}));
+
 import {
   applyConvolutionEffectToGl,
   defaultGlConvolutionEffectRunner,
   registerGlConvolutionEffect,
 } from './glConvolutionEffect';
 
+const target = { height: 4, texture: {}, width: 4 } as never;
+
 describe('applyConvolutionEffectToGl', () => {
   it('is a function', () => {
     expect(typeof applyConvolutionEffectToGl).toBe('function');
   });
+
+  it('binds the edge color as packed RGBA, not as the ARGB it once carried', () => {
+    glMock.uniform4f.mockClear();
+    applyConvolutionEffectToGl({} as never, target, target, {
+      color: 0x44ffee80,
+      kind: 'ConvolutionEffect',
+      matrix: [1],
+      matrixX: 1,
+      matrixY: 1,
+    });
+
+    // 0x44 0xff 0xee 0x80 read in that order. The previous packing produced (1, 0.933, 0.502, 0.267)
+    // from this same value — every channel shifted one place, and still a valid-looking color.
+    const [, red, green, blue, alpha] = glMock.uniform4f.mock.calls.find((call) => call[0] === 'u_edgeColor')!;
+    expect(red).toBeCloseTo(0x44 / 255, 5);
+    expect(green).toBeCloseTo(1, 5);
+    expect(blue).toBeCloseTo(0xee / 255, 5);
+    expect(alpha).toBeCloseTo(0x80 / 255, 5);
+  });
+
+  it('defaults the edge color to transparent black when the effect omits it', () => {
+    glMock.uniform4f.mockClear();
+    applyConvolutionEffectToGl({} as never, target, target, {
+      kind: 'ConvolutionEffect',
+      matrix: [1],
+      matrixX: 1,
+      matrixY: 1,
+    });
+
+    const call = glMock.uniform4f.mock.calls.find((entry) => entry[0] === 'u_edgeColor')!;
+    expect(call.slice(1)).toEqual([0, 0, 0, 0]);
+  });
 });
 
 describe('defaultGlConvolutionEffectRunner', () => {

package/src/glCustomShaderEffect.test.ts

@@ -1,17 +1,24 @@
+import { getRegistryTableEntry } from '@flighthq/registry/contract';
+import {
+  copyGlRenderStateRegistrations,
+  createGlRenderStateRuntime,
+  getGlRenderStateRuntime,
+} from '@flighthq/render-gl/contract';
 import type { GlRenderState } from '@flighthq/types/contract';
+import { EntityRuntimeKey } from '@flighthq/types/contract';
 
 import {
   applyCustomShaderEffectToGl,
   defaultGlCustomShaderEffectRunner,
   getGlCustomShaderSource,
+  isGlCustomShaderEffectResolvable,
   registerGlCustomShaderSource,
   registerGlCustomShaderEffect,
+  setGlCustomShaderSourceGuard,
 } from './glCustomShaderEffect';
 
-// The source registry is a plain WeakMap keyed by the render state, with no GL calls, so a bare
-// object stands in for a state. The compile/draw path is exercised by the functional render suite.
 function makeState(): GlRenderState {
-  return {} as GlRenderState;
+  return { [EntityRuntimeKey]: createGlRenderStateRuntime() } as unknown as GlRenderState;
 }
 
 const FRAGMENT_SRC = `#version 300 es
@@ -52,6 +59,32 @@ describe('getGlCustomShaderSource', () => {
   });
 });
 
+describe('isGlCustomShaderEffectResolvable', () => {
+  it('is false for a shaderKey with no registered source, which is the identity-passthrough case', () => {
+    const state = makeState();
+    expect(isGlCustomShaderEffectResolvable(state, { kind: 'CustomShaderEffect', shaderKey: 'ripple' } as never)).toBe(
+      false,
+    );
+  });
+
+  it('is true once the key names registered source', () => {
+    const state = makeState();
+    registerGlCustomShaderSource(state, 'ripple', FRAGMENT_SRC);
+    expect(isGlCustomShaderEffectResolvable(state, { kind: 'CustomShaderEffect', shaderKey: 'ripple' } as never)).toBe(
+      true,
+    );
+  });
+
+  it('answers per effect instance, so two effects of this kind can disagree', () => {
+    const state = makeState();
+    registerGlCustomShaderSource(state, 'ripple', FRAGMENT_SRC);
+    const registered = { kind: 'CustomShaderEffect', shaderKey: 'ripple' } as never;
+    const missing = { kind: 'CustomShaderEffect', shaderKey: 'absent' } as never;
+    expect(isGlCustomShaderEffectResolvable(state, registered)).toBe(true);
+    expect(isGlCustomShaderEffectResolvable(state, missing)).toBe(false);
+  });
+});
+
 describe('registerGlCustomShaderEffect', () => {
   it('is a separately importable registration primitive', () => {
     expect(registerGlCustomShaderEffect).toBeTypeOf('function');
@@ -72,4 +105,77 @@ describe('registerGlCustomShaderSource', () => {
     registerGlCustomShaderSource(state, 'ripple', replacement);
     expect(getGlCustomShaderSource(state, 'ripple')).toBe(replacement);
   });
+
+  it('replaces the persistent table while an explicitly copied state retains its snapshot', () => {
+    const screen = makeState();
+    const derived = makeState();
+    const replacement = FRAGMENT_SRC.replace('texture(u_texture0, v_texCoord)', 'vec4(1.0)');
+    registerGlCustomShaderSource(screen, 'ripple', FRAGMENT_SRC);
+    const snapshot = getGlRenderStateRuntime(screen).registries.customEffectShaders;
+
+    copyGlRenderStateRegistrations(derived, screen);
+    registerGlCustomShaderSource(screen, 'ripple', replacement);
+
+    expect(getGlRenderStateRuntime(derived).registries.customEffectShaders).toBe(snapshot);
+    expect(getGlRenderStateRuntime(screen).registries.customEffectShaders).not.toBe(snapshot);
+    expect(getRegistryTableEntry(snapshot, 'ripple')).toBe(FRAGMENT_SRC);
+    expect(getGlCustomShaderSource(derived, 'ripple')).toBe(FRAGMENT_SRC);
+    expect(getGlCustomShaderSource(screen, 'ripple')).toBe(replacement);
+  });
+});
+
+describe('setGlCustomShaderSourceGuard', () => {
+  it('fires with both sources when a key is overwritten with DIFFERENT source', () => {
+    const state = makeState();
+    const replacement = FRAGMENT_SRC.replace('texture(u_texture0, v_texCoord)', 'vec4(1.0)');
+    const calls: { key: string; previous: string; next: string }[] = [];
+    setGlCustomShaderSourceGuard(state, (_state, key, previous, next) => calls.push({ key, next, previous }));
+
+    registerGlCustomShaderSource(state, 'ripple', FRAGMENT_SRC);
+    registerGlCustomShaderSource(state, 'ripple', replacement);
+
+    // Both sources, because the whole point is that the NEXT one never reaches the GPU.
+    expect(calls).toEqual([{ key: 'ripple', next: replacement, previous: FRAGMENT_SRC }]);
+    // Non-vacuous: the registry still took the write, so the guard reports rather than blocks.
+    expect(getGlCustomShaderSource(state, 'ripple')).toBe(replacement);
+  });
+
+  it('stays SILENT on the first registration of a key, which compiles the source it names', () => {
+    const state = makeState();
+    let calls = 0;
+    setGlCustomShaderSourceGuard(state, () => calls++);
+
+    registerGlCustomShaderSource(state, 'ripple', FRAGMENT_SRC);
+
+    expect(calls).toBe(0);
+    expect(getGlCustomShaderSource(state, 'ripple')).toBe(FRAGMENT_SRC);
+  });
+
+  it('stays SILENT when the SAME source is registered again, which changes nothing', () => {
+    const state = makeState();
+    let calls = 0;
+    setGlCustomShaderSourceGuard(state, () => calls++);
+
+    registerGlCustomShaderSource(state, 'ripple', FRAGMENT_SRC);
+    registerGlCustomShaderSource(state, 'ripple', FRAGMENT_SRC);
+
+    // The cached program IS this source, so warning here would train readers to ignore the crumb.
+    expect(calls).toBe(0);
+  });
+
+  it('stops firing once cleared, and never fires for a state that never installed one', () => {
+    const state = makeState();
+    const other = makeState();
+    const replacement = FRAGMENT_SRC.replace('texture(u_texture0, v_texCoord)', 'vec4(1.0)');
+    let calls = 0;
+    setGlCustomShaderSourceGuard(state, () => calls++);
+    setGlCustomShaderSourceGuard(state, null);
+
+    registerGlCustomShaderSource(state, 'ripple', FRAGMENT_SRC);
+    registerGlCustomShaderSource(state, 'ripple', replacement);
+    registerGlCustomShaderSource(other, 'ripple', FRAGMENT_SRC);
+    registerGlCustomShaderSource(other, 'ripple', replacement);
+
+    expect(calls).toBe(0);
+  });
 });

package/src/glDropShadowEffect.test.ts

@@ -35,6 +35,7 @@ import {
   registerGlDropShadowEffect,
 } from './glDropShadowEffect';
 import { applyGlEffectBlitPass, applyGlEffectErasePass } from './glEffectBlitShader';
+import { applyGlEffectTintPass } from './glEffectTintShader';
 
 describe('applyDropShadowEffectToGl', () => {
   it('is a function', () => {
@@ -51,6 +52,24 @@ describe('applyDropShadowEffectToGl', () => {
     expect(applyGlEffectErasePass).not.toHaveBeenCalled();
   });
 
+  // Piece 3 landed this as a split at the call site, because the tint pass still spoke 24-bit RGB and was
+  // shared with effects that had not migrated. Now that every one of them carries packed RGBA, the pass
+  // itself folds the color's alpha and the call site hands the value over untouched — one decode point
+  // instead of five, and this assertion is what pins which of the two contracts is live.
+  it('hands the packed color and the effect alpha to the tint pass without splitting either', () => {
+    vi.mocked(applyGlEffectTintPass).mockClear();
+
+    applyDropShadowEffectToGl(createState(), createTarget('source'), createTarget('dest'), createPool(), {
+      alpha: 0.5,
+      color: 0x9d55ff80,
+      kind: 'DropShadowEffect',
+    });
+
+    const call = vi.mocked(applyGlEffectTintPass).mock.calls[0]!;
+    expect(call[3]).toBe(0x9d55ff80);
+    expect(call[4]).toBeCloseTo(0.5, 5);
+  });
+
   it('hides the source when sourceMode is hide', () => {
     const source = createTarget('source');
     const dest = createTarget('dest');

package/src/glEffectTintShader.test.ts

@@ -1,13 +1,79 @@
+// This pass is the single decode point for every tinted effect on this backend — drop shadow, outer glow,
+// and the neutral white field the bevels lay down. That is what the piece-4 unification bought: the
+// channel order and the alpha fold are asserted once, here, instead of at each of five call sites.
+const glMock = vi.hoisted(() => ({
+  ONE: 1,
+  ZERO: 0,
+  blendFunc: vi.fn(),
+  uniform1f: vi.fn(),
+  uniform3f: vi.fn(),
+}));
+
+vi.hoisted(() => {
+  vi.resetModules();
+});
+
+vi.mock('@flighthq/render-gl/contract', () => ({
+  compileGlFullscreenProgram: vi.fn(() => ({
+    locAlpha: 'u_alpha',
+    locColor: 'u_color',
+    locStrength: 'u_strength',
+    program: {},
+  })),
+  drawGlFullscreenPass: vi.fn((_state, _loc, _textures, _dest, setUniforms) => {
+    setUniforms(glMock as never, {} as never);
+  }),
+}));
+
 import { applyGlEffectInvertTintPass, applyGlEffectTintPass } from './glEffectTintShader';
 
+const state = { gl: { getUniformLocation: (_program: unknown, name: string) => name } } as never;
+const target = { height: 4, texture: {}, width: 4 } as never;
+
 describe('applyGlEffectInvertTintPass', () => {
   it('is a function', () => {
     expect(typeof applyGlEffectInvertTintPass).toBe('function');
   });
+
+  it('reads the packed color and folds its alpha, the same contract as the non-inverted pass', () => {
+    glMock.uniform3f.mockClear();
+    glMock.uniform1f.mockClear();
+
+    applyGlEffectInvertTintPass(state, target, target, 0x9d55ff80, 0.5, 1);
+
+    const [, red, green, blue] = glMock.uniform3f.mock.calls.find((call) => call[0] === 'u_color')!;
+    expect(red).toBeCloseTo(0x9d / 255, 5);
+    expect(green).toBeCloseTo(0x55 / 255, 5);
+    expect(blue).toBeCloseTo(1, 5);
+    expect(glMock.uniform1f.mock.calls.find((call) => call[0] === 'u_alpha')![1]).toBeCloseTo((0x80 / 255) * 0.5, 5);
+  });
 });
 
 describe('applyGlEffectTintPass', () => {
   it('is a function', () => {
     expect(typeof applyGlEffectTintPass).toBe('function');
   });
+
+  it('splits a packed RGBA color into the shader RGB and an alpha multiplied by the caller alpha', () => {
+    glMock.uniform3f.mockClear();
+    glMock.uniform1f.mockClear();
+
+    applyGlEffectTintPass(state, target, target, 0x9d55ff80, 0.5, 1);
+
+    // Under the 24-bit reading this pass carried before piece 4, the same value tinted 0x55ff80 at a
+    // full 0.5 — a different color at twice the opacity, and nothing in the frame to say which was meant.
+    const [, red, green, blue] = glMock.uniform3f.mock.calls.find((call) => call[0] === 'u_color')!;
+    expect(red).toBeCloseTo(0x9d / 255, 5);
+    expect(green).toBeCloseTo(0x55 / 255, 5);
+    expect(blue).toBeCloseTo(1, 5);
+    expect(glMock.uniform1f.mock.calls.find((call) => call[0] === 'u_alpha')![1]).toBeCloseTo((0x80 / 255) * 0.5, 5);
+  });
+
+  it('passes an opaque tint through at exactly the caller alpha', () => {
+    glMock.uniform1f.mockClear();
+
+    applyGlEffectTintPass(state, target, target, 0xffffffff, 0.25, 1);
+
+    expect(glMock.uniform1f.mock.calls.find((call) => call[0] === 'u_alpha')![1]).toBeCloseTo(0.25, 5);
+  });
 });

package/src/glInnerGlowEffect.test.ts

@@ -76,7 +76,7 @@ describe('applyInnerGlowEffectToGl', () => {
 
     applyInnerGlowEffectToGl(createState(), source, dest, createPool(), {
       kind: 'InnerGlowEffect',
-      color: 0xff0000,
+      color: 0xff0000ff,
       sourceMode: 'hide',
       strength: 2,
     });

package/src/glInnerShadowEffect.test.ts

@@ -77,7 +77,7 @@ describe('applyInnerShadowEffectToGl', () => {
 
     applyInnerShadowEffectToGl(createState(), source, dest, createPool(), {
       kind: 'InnerShadowEffect',
-      color: 0,
+      color: 0x000000ff,
       sourceMode: 'hide',
     });
 

package/src/glRenderEffectPipeline.test.ts

@@ -1,10 +1,12 @@
 import { createGlRenderState, endGlRenderPass } from '@flighthq/render-gl/contract';
+import type { RenderEffect } from '@flighthq/types/contract';
 
 import {
   beginGlRenderEffectPipeline,
   createGlRenderEffectPipeline,
   destroyGlRenderEffectPipeline,
   endGlRenderEffectPipeline,
+  setGlRenderEffectPipelineSkipGuard,
   setGlRenderEffectVelocityTexture,
 } from './glRenderEffectPipeline';
 
@@ -45,6 +47,29 @@ describe('endGlRenderEffectPipeline', () => {
   });
 });
 
+describe('setGlRenderEffectPipelineSkipGuard', () => {
+  it('reports every effect kind the pass drops, and goes silent again when cleared', () => {
+    const state = createGlRenderState(document.createElement('canvas'));
+    const pipeline = createGlRenderEffectPipeline(state);
+    const dropped: string[] = [];
+    const chain = [{ kind: 'test.pipeline-skip-seam' } as RenderEffect];
+
+    setGlRenderEffectPipelineSkipGuard(state, (_state, kind) => dropped.push(kind));
+    beginGlRenderEffectPipeline(state, pipeline);
+    endGlRenderEffectPipeline(state, pipeline, chain);
+
+    expect(dropped).toEqual(['test.pipeline-skip-seam']);
+
+    // Clearing must restore the original silence exactly: the seam is the ONLY path by which a dropped
+    // effect is observable, so a stale guard would be the difference between a diagnostic and a leak.
+    setGlRenderEffectPipelineSkipGuard(state, null);
+    beginGlRenderEffectPipeline(state, pipeline);
+    endGlRenderEffectPipeline(state, pipeline, chain);
+
+    expect(dropped).toEqual(['test.pipeline-skip-seam']);
+  });
+});
+
 describe('setGlRenderEffectVelocityTexture', () => {
   it('is a function', () => {
     expect(typeof setGlRenderEffectVelocityTexture).toBe('function');

package/src/glRenderEffectRegistry.test.ts

@@ -1,7 +1,13 @@
 import { createGlRenderState } from '@flighthq/render-gl/contract';
-import type { GlRenderState } from '@flighthq/types/contract';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl/contract';
+import type { GlRenderState, RenderEffect } from '@flighthq/types/contract';
 
-import { getGlRenderEffectRunner, hasGlRenderEffectRunner, registerGlRenderEffect } from './glRenderEffectRegistry';
+import {
+  getGlRenderEffectRunner,
+  hasGlRenderEffectRunner,
+  isGlRenderEffectResolvable,
+  registerGlRenderEffect,
+} from './glRenderEffectRegistry';
 
 describe('getGlRenderEffectRunner', () => {
   it('is a function', () => {
@@ -32,6 +38,26 @@ describe('hasGlRenderEffectRunner', () => {
   });
 });
 
+describe('isGlRenderEffectResolvable', () => {
+  it('treats a kind registered without a resolver as always resolvable', () => {
+    const state = createState();
+    registerGlRenderEffect(state, 'ResolvableTestEffect', vi.fn());
+    expect(isGlRenderEffectResolvable(state, effect('ResolvableTestEffect'))).toBe(true);
+  });
+
+  it('asks the registered resolver, per effect instance', () => {
+    const state = createState();
+    registerGlRenderEffect(state, 'ResolverTestEffect', vi.fn(), (_state, candidate) => 'key' in candidate);
+    expect(isGlRenderEffectResolvable(state, effect('ResolverTestEffect'))).toBe(false);
+    expect(isGlRenderEffectResolvable(state, effect('ResolverTestEffect', { key: 'k' }))).toBe(true);
+  });
+
+  it('reports an unregistered kind as unresolvable, since there is nothing to resolve it with', () => {
+    const state = createState();
+    expect(isGlRenderEffectResolvable(state, effect('NeverRegisteredEffect'))).toBe(false);
+  });
+});
+
 describe('registerGlRenderEffect', () => {
   it('is a function', () => {
     expect(typeof registerGlRenderEffect).toBe('function');
@@ -40,8 +66,11 @@ describe('registerGlRenderEffect', () => {
   it('registers and retrieves a runner', () => {
     const state = createState();
     const runner = vi.fn();
+    const before = getGlRenderStateRuntime(state).registries.renderEffects;
     registerGlRenderEffect(state, 'TestEffect', runner);
     expect(getGlRenderEffectRunner(state, 'TestEffect')).toBe(runner);
+    expect(getGlRenderStateRuntime(state).registries.renderEffects).not.toBe(before);
+    expect(before.entries.size).toBe(0);
   });
 
   it('overwrites an existing runner under the same kind', () => {
@@ -49,8 +78,13 @@ describe('registerGlRenderEffect', () => {
     const runnerA = vi.fn();
     const runnerB = vi.fn();
     registerGlRenderEffect(state, 'TestEffect2', runnerA);
+    const before = getGlRenderStateRuntime(state).registries.renderEffects;
     registerGlRenderEffect(state, 'TestEffect2', runnerB);
     expect(getGlRenderEffectRunner(state, 'TestEffect2')).toBe(runnerB);
+    expect(before.entries.get('TestEffect2')).toEqual({
+      state: 'bound',
+      value: { isResolvable: undefined, runner: runnerA },
+    });
   });
 });
 
@@ -60,3 +94,7 @@ function createState(): GlRenderState {
   canvas.height = 16;
   return createGlRenderState(canvas);
 }
+
+function effect(kind: string, extra: Readonly<Record<string, unknown>> = {}): Readonly<RenderEffect> {
+  return { kind, ...extra } as unknown as Readonly<RenderEffect>;
+}