@flighthq/effects-canvas 0.3.0-next.906.07cea63 → 0.3.0

package/src/canvasBlendEffect.test.ts

@@ -0,0 +1,235 @@
+import { createCanvasRenderState, createCanvasRenderTarget } from '@flighthq/scene2d-canvas/contract';
+import type { BlendEffect, CanvasRenderState, CanvasRenderTarget } from '@flighthq/types/contract';
+
+import {
+  applyBlendEffectToCanvas,
+  defaultCanvasBlendEffectRunner,
+  getCanvasBlendEffectBackdrop,
+  getCanvasBlendEffectCompositeOperation,
+  registerCanvasBlendEffect,
+  registerCanvasBlendEffectBackdrop,
+  unregisterCanvasBlendEffectBackdrop,
+} from './canvasBlendEffect';
+import { getCanvasRenderEffectRunner } from './canvasRenderEffectRegistry';
+
+// These tests assert the DRAW CONTRACT, not pixels, and that is deliberate rather than a shortcut.
+// jsdom's 2D context accepts every call and every globalCompositeOperation but rasterizes nothing — a
+// fillRect followed by getImageData reads back transparent black — so a pixel assertion here would
+// either pass vacuously or fail for a reason that has nothing to do with the effect. What IS verifiable
+// in this environment is the sequence of operations the recipe issues, which carries the substantive
+// claims: that the backdrop is laid down before the layer (every non-commutative mode gives a different
+// image if that order flips), that the mode maps to the right native operation, and that opacity reaches
+// globalAlpha. Real pixels belong to the functional/browser suite.
+function recordDraws(target: Readonly<CanvasRenderTarget>): string[] {
+  const drawn: string[] = [];
+  const context = target.context;
+  vi.spyOn(context, 'drawImage').mockImplementation(((image: CanvasImageSource) => {
+    // Captured at call time, because the recipe changes both between the two draws.
+    drawn.push(
+      `${(image as HTMLCanvasElement).id || 'canvas'}|${context.globalCompositeOperation}|${context.globalAlpha}`,
+    );
+  }) as typeof context.drawImage);
+  return drawn;
+}
+
+function scene(): { state: CanvasRenderState; source: CanvasRenderTarget; dest: CanvasRenderTarget } {
+  const state = createCanvasRenderState(document.createElement('canvas'));
+  const source = createCanvasRenderTarget(4, 4);
+  const dest = createCanvasRenderTarget(4, 4);
+  source.canvas.id = 'source';
+  dest.canvas.id = 'dest';
+  return { state, source, dest };
+}
+
+function backdropTarget(): CanvasRenderTarget {
+  const backdrop = createCanvasRenderTarget(4, 4);
+  backdrop.canvas.id = 'backdrop';
+  return backdrop;
+}
+
+function blendEffect(over: Partial<BlendEffect> = {}): BlendEffect {
+  return { kind: 'BlendEffect', mode: 'Overlay', ...over } as BlendEffect;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('applyBlendEffectToCanvas', () => {
+  it('draws the backdrop first and then the layer under the named mode', () => {
+    const { state, source, dest } = scene();
+    const backdrop = backdropTarget();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdrop);
+    const drawn = recordDraws(dest);
+
+    applyBlendEffectToCanvas(state, source, dest, blendEffect({ mode: 'Overlay', backdropKey: 'scene' }));
+
+    // Order is the assertion. The backdrop is the destination the mode reads, so it must already be in
+    // dest when the layer lands; drawn the other way round every non-commutative mode blends backwards.
+    expect(drawn).toEqual(['backdrop|source-over|1', 'source|overlay|1']);
+  });
+
+  it('scales the layer with globalAlpha when the effect carries an opacity', () => {
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    const drawn = recordDraws(dest);
+
+    applyBlendEffectToCanvas(state, source, dest, blendEffect({ backdropKey: 'scene', opacity: 0.25 }));
+
+    // Only the layer is scaled — the backdrop is the destination and must go down at full strength.
+    expect(drawn).toEqual(['backdrop|source-over|1', 'source|overlay|0.25']);
+  });
+
+  it('passes the layer through unblended when the named backdrop is not registered', () => {
+    const { state, source, dest } = scene();
+    const drawn = recordDraws(dest);
+
+    applyBlendEffectToCanvas(state, source, dest, blendEffect({ backdropKey: 'absent' }));
+
+    // One draw, source-over: an unregistered key blends over an implicit transparent backdrop, which
+    // reduces to a passthrough. Matches the GL contract, which gates its second sampler the same way.
+    expect(drawn).toEqual(['source|source-over|1']);
+  });
+
+  it('passes the layer through unblended when the effect names no backdrop at all', () => {
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    const drawn = recordDraws(dest);
+
+    applyBlendEffectToCanvas(state, source, dest, blendEffect());
+
+    // A registered backdrop the effect does not name must not be picked up implicitly.
+    expect(drawn).toEqual(['source|source-over|1']);
+  });
+});
+
+describe('defaultCanvasBlendEffectRunner', () => {
+  it('applies the blend through the pipeline context', () => {
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    const drawn = recordDraws(dest);
+
+    defaultCanvasBlendEffectRunner(
+      { state, source, dest, pool: { free: [], inUse: [] } },
+      blendEffect({ mode: 'Screen', backdropKey: 'scene' }),
+    );
+
+    // 'Screen' is NOT an AdvancedBlendMode — it is in the fixed-function BlendMode enum — so it has no
+    // entry here and must fall back rather than reach a native 'screen' operation by coincidence.
+    expect(drawn).toEqual(['backdrop|source-over|1', 'source|source-over|1']);
+  });
+});
+
+describe('getCanvasBlendEffectBackdrop', () => {
+  it('returns the registered target for its key', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    const backdrop = backdropTarget();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdrop);
+
+    expect(getCanvasBlendEffectBackdrop(state, 'scene')).toBe(backdrop);
+  });
+
+  it('returns null for an unregistered key and for a null key', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+
+    expect(getCanvasBlendEffectBackdrop(state, 'other')).toBe(null);
+    expect(getCanvasBlendEffectBackdrop(state, null)).toBe(null);
+  });
+
+  it('returns null before anything has been registered on the state', () => {
+    // The registry slot is absent until first use, so the query must not assume a map exists.
+    const state = createCanvasRenderState(document.createElement('canvas'));
+
+    expect(getCanvasBlendEffectBackdrop(state, 'scene')).toBe(null);
+  });
+
+  it('keeps backdrops separate per render state', () => {
+    const first = createCanvasRenderState(document.createElement('canvas'));
+    const second = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasBlendEffectBackdrop(first, 'scene', backdropTarget());
+
+    expect(getCanvasBlendEffectBackdrop(second, 'scene')).toBe(null);
+  });
+});
+
+describe('getCanvasBlendEffectCompositeOperation', () => {
+  it('maps every AdvancedBlendMode to a native operation', () => {
+    // All eleven, including the four non-separable HSL modes, which is the reason Canvas needs no blend
+    // math of its own. A mode missing from the table would silently become a passthrough.
+    expect(
+      [
+        'Color',
+        'ColorBurn',
+        'ColorDodge',
+        'Difference',
+        'Exclusion',
+        'HardLight',
+        'Hue',
+        'Luminosity',
+        'Overlay',
+        'Saturation',
+        'SoftLight',
+      ].map(getCanvasBlendEffectCompositeOperation),
+    ).toEqual([
+      'color',
+      'color-burn',
+      'color-dodge',
+      'difference',
+      'exclusion',
+      'hard-light',
+      'hue',
+      'luminosity',
+      'overlay',
+      'saturation',
+      'soft-light',
+    ]);
+  });
+
+  it('falls back to source-over for a mode it does not know', () => {
+    expect(getCanvasBlendEffectCompositeOperation('acme.Sparkle')).toBe('source-over');
+  });
+});
+
+describe('registerCanvasBlendEffect', () => {
+  it('registers the default runner under the BlendEffect kind', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasBlendEffect(state);
+
+    expect(getCanvasRenderEffectRunner(state, 'BlendEffect')).toBe(defaultCanvasBlendEffectRunner);
+  });
+});
+
+describe('registerCanvasBlendEffectBackdrop', () => {
+  it('replaces the target already held under the same key', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    const replacement = backdropTarget();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    registerCanvasBlendEffectBackdrop(state, 'scene', replacement);
+
+    expect(getCanvasBlendEffectBackdrop(state, 'scene')).toBe(replacement);
+  });
+});
+
+describe('unregisterCanvasBlendEffectBackdrop', () => {
+  it('drops the registered target and reports that one was present', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+
+    expect(unregisterCanvasBlendEffectBackdrop(state, 'scene')).toBe(true);
+    expect(getCanvasBlendEffectBackdrop(state, 'scene')).toBe(null);
+  });
+
+  it('reports false for a key that was never registered', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+
+    expect(unregisterCanvasBlendEffectBackdrop(state, 'other')).toBe(false);
+  });
+
+  it('reports false before anything has been registered on the state', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+
+    expect(unregisterCanvasBlendEffectBackdrop(state, 'scene')).toBe(false);
+  });
+});

package/src/canvasBloomEffect.test.ts

@@ -1,4 +1,8 @@
-import { applyBloomEffectToCanvas, defaultCanvasBloomEffectRunner } from './canvasBloomEffect';
+import {
+  applyBloomEffectToCanvas,
+  defaultCanvasBloomEffectRunner,
+  registerCanvasBloomEffect,
+} from './canvasBloomEffect';
 
 describe('applyBloomEffectToCanvas', () => {
   it('is a function', () => {
@@ -11,3 +15,7 @@ describe('defaultCanvasBloomEffectRunner', () => {
     expect(typeof defaultCanvasBloomEffectRunner).toBe('function');
   });
 });
+
+describe('registerCanvasBloomEffect', () => {
+  it('is a function', () => expect(registerCanvasBloomEffect).toBeTypeOf('function'));
+});

package/src/canvasBlurEffect.test.ts

@@ -1,4 +1,7 @@
-import { applyBlurEffectToCanvas, defaultCanvasBlurEffectRunner } from './canvasBlurEffect';
+import { createCanvasRenderState } from '@flighthq/scene2d-canvas/contract';
+
+import { applyBlurEffectToCanvas, defaultCanvasBlurEffectRunner, registerCanvasBlurEffect } from './canvasBlurEffect';
+import { getCanvasRenderEffectRunner } from './canvasRenderEffectRegistry';
 
 describe('applyBlurEffectToCanvas', () => {
   it('is a function', () => {
@@ -11,3 +14,11 @@ describe('defaultCanvasBlurEffectRunner', () => {
     expect(typeof defaultCanvasBlurEffectRunner).toBe('function');
   });
 });
+
+describe('registerCanvasBlurEffect', () => {
+  it('registers the default runner under the BlurEffect kind', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasBlurEffect(state);
+    expect(getCanvasRenderEffectRunner(state, 'BlurEffect')).toBe(defaultCanvasBlurEffectRunner);
+  });
+});

package/src/canvasColorMatrixPass.test.ts

@@ -1,22 +1,72 @@
-import { applyColorMatrixPassToCanvas } from './canvasColorMatrixPass';
+import type { CanvasRenderTarget } from '@flighthq/types/contract';
 
-const { drawCanvasImageDataPass } = vi.hoisted(() => ({ drawCanvasImageDataPass: vi.fn() }));
+import { applyColorMatrixPassToCanvas, applyColorMatrixToImageDataBytes } from './canvasColorMatrixPass';
 
-vi.mock('./canvasEffectCompositing', () => ({ drawCanvasImageDataPass }));
+// Minimal stand-ins for the two canvas contexts drawCanvasImageDataPass touches. Using plain objects
+// rather than substituting the compositing module keeps the wiring assertion independent of module
+// load order, which matters because the suite runs non-isolated (one module registry per worker).
+function createStubTargets(pixels: ReadonlyArray<number>): {
+  dest: CanvasRenderTarget;
+  written: { data: Uint8ClampedArray | null };
+  source: CanvasRenderTarget;
+} {
+  const imageData = { data: new Uint8ClampedArray(pixels) };
+  const written: { data: Uint8ClampedArray | null } = { data: null };
+  const source = {
+    context: { getImageData: () => imageData },
+    height: 1,
+    width: pixels.length / 4,
+  } as unknown as CanvasRenderTarget;
+  const dest = {
+    context: {
+      clearRect: () => {},
+      filter: 'none',
+      globalAlpha: 1,
+      globalCompositeOperation: 'source-over',
+      putImageData: (written_: { data: Uint8ClampedArray }) => {
+        written.data = written_.data;
+      },
+      restore: () => {},
+      save: () => {},
+      setTransform: () => {},
+    },
+    height: 1,
+    width: pixels.length / 4,
+  } as unknown as CanvasRenderTarget;
+  return { dest, source, written };
+}
+
+const BIAS_MATRIX = [1, 0, 0, 0, 0.5, 0, 1, 0, 0, 0.25, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0];
 
 describe('applyColorMatrixPassToCanvas', () => {
   it('is a function', () => {
     expect(typeof applyColorMatrixPassToCanvas).toBe('function');
   });
 
+  it('reads the source pixels, applies the matrix, and writes the result to the destination', () => {
+    const { dest, source, written } = createStubTargets([0, 0, 0, 255]);
+    applyColorMatrixPassToCanvas(source, dest, BIAS_MATRIX);
+    expect(written.data).not.toBeNull();
+    expect(Array.from(written.data!)).toEqual([128, 64, 0, 255]);
+  });
+});
+
+describe('applyColorMatrixToImageDataBytes', () => {
   it('converts normalized-linear matrix bias to the ImageData byte domain', () => {
-    drawCanvasImageDataPass.mockImplementationOnce((_dest, _source, transform) => {
-      const data = new Uint8ClampedArray([0, 0, 0, 255]);
-      transform(data, 1);
-      expect(Array.from(data)).toEqual([128, 64, 0, 255]);
-    });
-    const matrix = [1, 0, 0, 0, 0.5, 0, 1, 0, 0, 0.25, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0];
-    applyColorMatrixPassToCanvas({} as never, {} as never, matrix);
-    expect(drawCanvasImageDataPass).toHaveBeenCalledOnce();
+    const data = new Uint8ClampedArray([0, 0, 0, 255]);
+    applyColorMatrixToImageDataBytes(data, 1, BIAS_MATRIX);
+    expect(Array.from(data)).toEqual([128, 64, 0, 255]);
+  });
+
+  it('applies the matrix to every pixel in the run', () => {
+    const data = new Uint8ClampedArray([0, 0, 0, 255, 0, 0, 0, 255]);
+    applyColorMatrixToImageDataBytes(data, 2, BIAS_MATRIX);
+    expect(Array.from(data)).toEqual([128, 64, 0, 255, 128, 64, 0, 255]);
+  });
+
+  it('treats absent matrix entries as zero', () => {
+    const data = new Uint8ClampedArray([200, 200, 200, 255]);
+    applyColorMatrixToImageDataBytes(data, 1, []);
+    expect(Array.from(data)).toEqual([0, 0, 0, 0]);
   });
 });

package/src/canvasCompositeEffect.test.ts

@@ -0,0 +1,181 @@
+import { createCanvasRenderState, createCanvasRenderTarget } from '@flighthq/scene2d-canvas/contract';
+import type { CanvasRenderState, CanvasRenderTarget, CompositeEffect } from '@flighthq/types/contract';
+
+import { registerCanvasBlendEffectBackdrop } from './canvasBlendEffect';
+import {
+  applyCompositeEffectToCanvas,
+  defaultCanvasCompositeEffectRunner,
+  getCanvasCompositeEffectOperation,
+  registerCanvasCompositeEffect,
+} from './canvasCompositeEffect';
+import { getCanvasRenderEffectRunner } from './canvasRenderEffectRegistry';
+
+// Draw-contract assertions rather than pixels, for the reason spelled out in canvasBlendEffect.test.ts:
+// jsdom's 2D context accepts every call and rasterizes nothing, so a pixel assertion would pass
+// vacuously. What is verifiable — and what carries the correctness claims — is which images are drawn,
+// in what order, and under which globalCompositeOperation.
+function recordDraws(target: Readonly<CanvasRenderTarget>): string[] {
+  const drawn: string[] = [];
+  const context = target.context;
+  vi.spyOn(context, 'drawImage').mockImplementation(((image: CanvasImageSource) => {
+    drawn.push(`${(image as HTMLCanvasElement).id || 'canvas'}|${context.globalCompositeOperation}`);
+  }) as typeof context.drawImage);
+  return drawn;
+}
+
+function scene(): { state: CanvasRenderState; source: CanvasRenderTarget; dest: CanvasRenderTarget } {
+  const state = createCanvasRenderState(document.createElement('canvas'));
+  const source = createCanvasRenderTarget(4, 4);
+  const dest = createCanvasRenderTarget(4, 4);
+  source.canvas.id = 'source';
+  dest.canvas.id = 'dest';
+  return { state, source, dest };
+}
+
+function backdropTarget(): CanvasRenderTarget {
+  const backdrop = createCanvasRenderTarget(4, 4);
+  backdrop.canvas.id = 'backdrop';
+  return backdrop;
+}
+
+function compositeEffect(over: Partial<CompositeEffect> = {}): CompositeEffect {
+  return { kind: 'CompositeEffect', operator: 'SourceOver', ...over } as CompositeEffect;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('applyCompositeEffectToCanvas', () => {
+  it('draws the backdrop first and then the layer under the named operator', () => {
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    const drawn = recordDraws(dest);
+
+    applyCompositeEffectToCanvas(
+      state,
+      source,
+      dest,
+      compositeEffect({ operator: 'DestinationOut', backdropKey: 'scene' }),
+    );
+
+    // The backdrop is the destination every Porter-Duff operator is defined against, so it must be in
+    // the target before the layer lands. DestinationOut is the classic erase: reversing the order would
+    // punch the hole in the wrong image.
+    expect(drawn).toEqual(['backdrop|source-over', 'source|destination-out']);
+  });
+
+  it('composites against a transparent destination when the named backdrop is not registered', () => {
+    const { state, source, dest } = scene();
+    const drawn = recordDraws(dest);
+
+    applyCompositeEffectToCanvas(state, source, dest, compositeEffect({ operator: 'SourceIn', backdropKey: 'absent' }));
+
+    // Still draws, and still under SourceIn — an absent backdrop is a transparent DESTINATION, not a
+    // reason to skip the composite. SourceIn against zero coverage correctly yields nothing, which is
+    // the operator doing its job rather than a fallback.
+    expect(drawn).toEqual(['source|source-in']);
+  });
+
+  it('reads no backdrop the effect has not named', () => {
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    const drawn = recordDraws(dest);
+
+    applyCompositeEffectToCanvas(state, source, dest, compositeEffect());
+
+    expect(drawn).toEqual(['source|source-over']);
+  });
+
+  it('shares the backdrop registry with BlendEffect rather than keeping its own', () => {
+    // Registered through the Blend entry point and read by the Composite pass, which is the GL contract:
+    // both effects resolve their backdrop through the same per-state registry.
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'shared', backdropTarget());
+    const drawn = recordDraws(dest);
+
+    applyCompositeEffectToCanvas(state, source, dest, compositeEffect({ operator: 'Xor', backdropKey: 'shared' }));
+
+    expect(drawn).toEqual(['backdrop|source-over', 'source|xor']);
+  });
+
+  it('draws neither input for Clear, even with a backdrop registered', () => {
+    // Clear means both coverage factors are zero, so the cleared target IS the result. Drawing the
+    // backdrop first and only skipping the layer would leave the backdrop showing through.
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    const drawn = recordDraws(dest);
+    const cleared = vi.spyOn(dest.context, 'clearRect');
+
+    applyCompositeEffectToCanvas(state, source, dest, compositeEffect({ operator: 'Clear', backdropKey: 'scene' }));
+
+    expect(drawn).toEqual([]);
+    expect(cleared).toHaveBeenCalledWith(0, 0, 4, 4);
+  });
+});
+
+describe('defaultCanvasCompositeEffectRunner', () => {
+  it('applies the composite through the pipeline context', () => {
+    const { state, source, dest } = scene();
+    registerCanvasBlendEffectBackdrop(state, 'scene', backdropTarget());
+    const drawn = recordDraws(dest);
+
+    defaultCanvasCompositeEffectRunner(
+      { state, source, dest, pool: { free: [], inUse: [] } },
+      compositeEffect({ operator: 'DestinationOver', backdropKey: 'scene' }),
+    );
+
+    expect(drawn).toEqual(['backdrop|source-over', 'source|destination-over']);
+  });
+});
+
+describe('getCanvasCompositeEffectOperation', () => {
+  it('maps every operator Canvas realizes natively', () => {
+    // Ten of the eleven. Canvas 2D owns this vocabulary, so each is a direct rename of the same
+    // Porter-Duff term; a missing entry would silently become SourceOver and composite the wrong way.
+    expect(
+      [
+        'Copy',
+        'DestinationAtop',
+        'DestinationIn',
+        'DestinationOut',
+        'DestinationOver',
+        'SourceAtop',
+        'SourceIn',
+        'SourceOut',
+        'SourceOver',
+        'Xor',
+      ].map(getCanvasCompositeEffectOperation),
+    ).toEqual([
+      'copy',
+      'destination-atop',
+      'destination-in',
+      'destination-out',
+      'destination-over',
+      'source-atop',
+      'source-in',
+      'source-out',
+      'source-over',
+      'xor',
+    ]);
+  });
+
+  it('falls back to source-over for an operator it does not know', () => {
+    expect(getCanvasCompositeEffectOperation('acme.Dissolve')).toBe('source-over');
+  });
+
+  it('has no entry for Clear, which the pass handles by clearing instead', () => {
+    // Pinned so that "adding the missing Clear entry" cannot look like a fix: Canvas has no 'clear'
+    // operation, and an entry here would route Clear into a draw the operator is defined not to make.
+    expect(getCanvasCompositeEffectOperation('Clear')).toBe('source-over');
+  });
+});
+
+describe('registerCanvasCompositeEffect', () => {
+  it('registers the default runner under the CompositeEffect kind', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasCompositeEffect(state);
+
+    expect(getCanvasRenderEffectRunner(state, 'CompositeEffect')).toBe(defaultCanvasCompositeEffectRunner);
+  });
+});

package/src/canvasDropShadowEffect.test.ts

@@ -28,7 +28,11 @@ vi.mock('./canvasSourceModeCompositing', () => ({
   drawCanvasTintedAlphaMask: vi.fn(),
 }));
 
-import { applyDropShadowEffectToCanvas, defaultCanvasDropShadowEffectRunner } from './canvasDropShadowEffect';
+import {
+  applyDropShadowEffectToCanvas,
+  defaultCanvasDropShadowEffectRunner,
+  registerCanvasDropShadowEffect,
+} from './canvasDropShadowEffect';
 import { drawCanvasEffectPass } from './canvasEffectCompositing';
 import { compositeCanvasSourceMode } from './canvasSourceModeCompositing';
 
@@ -72,17 +76,20 @@ describe('defaultCanvasDropShadowEffectRunner', () => {
   });
 });
 
-beforeEach(() => {
-  vi.clearAllMocks();
+describe('registerCanvasDropShadowEffect', () => {
+  it('is a function', () => expect(registerCanvasDropShadowEffect).toBeTypeOf('function'));
 });
 
-afterAll(() => {
-  vi.doUnmock('./canvasEffectCompositing');
-  vi.doUnmock('./canvasRenderEffectPipeline');
-  vi.doUnmock('./canvasSourceModeCompositing');
-  vi.resetModules();
+beforeEach(() => {
+  vi.clearAllMocks();
 });
 
 function createTarget(id: string, width = 32, height = 16): never {
   return { id, canvas: {}, context: {}, width, height } as never;
 }
+
+describe('registerCanvasDropShadowEffect', () => {
+  it('is a function', () => {
+    expect(typeof registerCanvasDropShadowEffect).toBe('function');
+  });
+});

package/src/canvasEffectRegistration.test.ts

@@ -0,0 +1,27 @@
+import { createCanvasRenderState } from '@flighthq/scene2d-canvas/contract';
+
+import { getCanvasRenderEffectRunner } from './canvasRenderEffectRegistry';
+import * as contractEffects from './contract';
+import * as publicEffects from './index';
+
+describe('Canvas effect registration', () => {
+  it.each([
+    ['BlendEffect', 'registerCanvasBlendEffect', 'defaultCanvasBlendEffectRunner'],
+    ['BloomEffect', 'registerCanvasBloomEffect', 'defaultCanvasBloomEffectRunner'],
+    ['BlurEffect', 'registerCanvasBlurEffect', 'defaultCanvasBlurEffectRunner'],
+    ['DropShadowEffect', 'registerCanvasDropShadowEffect', 'defaultCanvasDropShadowEffectRunner'],
+    ['FilmGrainEffect', 'registerCanvasFilmGrainEffect', 'defaultCanvasFilmGrainEffectRunner'],
+    ['OuterGlowEffect', 'registerCanvasOuterGlowEffect', 'defaultCanvasOuterGlowEffectRunner'],
+    ['PixelateEffect', 'registerCanvasPixelateEffect', 'defaultCanvasPixelateEffectRunner'],
+    ['ScanlinesEffect', 'registerCanvasScanlinesEffect', 'defaultCanvasScanlinesEffectRunner'],
+    ['VignetteEffect', 'registerCanvasVignetteEffect', 'defaultCanvasVignetteEffectRunner'],
+  ] as const)('registers the public %s runner on only the supplied state', (kind, registerName, runnerName) => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    const other = createCanvasRenderState(document.createElement('canvas'));
+
+    publicEffects[registerName](state);
+
+    expect(getCanvasRenderEffectRunner(state, kind)).toBe(contractEffects[runnerName]);
+    expect(getCanvasRenderEffectRunner(other, kind)).toBeNull();
+  });
+});

package/src/canvasFilmGrainEffect.test.ts

@@ -1,4 +1,8 @@
-import { applyFilmGrainEffectToCanvas, defaultCanvasFilmGrainEffectRunner } from './canvasFilmGrainEffect';
+import {
+  applyFilmGrainEffectToCanvas,
+  defaultCanvasFilmGrainEffectRunner,
+  registerCanvasFilmGrainEffect,
+} from './canvasFilmGrainEffect';
 
 describe('applyFilmGrainEffectToCanvas', () => {
   it('is a function', () => {
@@ -11,3 +15,7 @@ describe('defaultCanvasFilmGrainEffectRunner', () => {
     expect(typeof defaultCanvasFilmGrainEffectRunner).toBe('function');
   });
 });
+
+describe('registerCanvasFilmGrainEffect', () => {
+  it('is a function', () => expect(registerCanvasFilmGrainEffect).toBeTypeOf('function'));
+});