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

package/src/canvasInnerShadowEffect.test.ts

@@ -0,0 +1,173 @@
+import { createCanvasRenderState, createCanvasRenderTarget } from '@flighthq/scene2d-canvas/contract';
+import type { CanvasRenderTarget, CanvasRenderTargetPool, InnerShadowEffect } from '@flighthq/types/contract';
+
+import {
+  applyInnerShadowEffectToCanvas,
+  defaultCanvasInnerShadowEffectRunner,
+  registerCanvasInnerShadowEffect,
+} from './canvasInnerShadowEffect';
+import { getCanvasRenderEffectRunner } from './canvasRenderEffectRegistry';
+
+// Recipe assertions rather than pixels — see canvasBlendEffect.test.ts for why jsdom forces that. Scratch
+// targets are pre-seeded into the pool so each pass is identifiable; acquisition pops from the end, so the
+// seed order is the reverse of the acquisition order.
+function seededPool(ids: readonly string[]): { pool: CanvasRenderTargetPool; targets: CanvasRenderTarget[] } {
+  const targets = ids.map((id) => {
+    const target = createCanvasRenderTarget(4, 4);
+    target.canvas.id = id;
+    return target;
+  });
+  return { pool: { free: [...targets].reverse(), inUse: [] }, targets };
+}
+
+interface Draw {
+  entry: string;
+  dx: number;
+  dy: number;
+}
+
+function recordAll(log: Draw[], targets: readonly Readonly<CanvasRenderTarget>[]): void {
+  for (const target of targets) {
+    const context = target.context;
+    const into = target.canvas.id;
+    vi.spyOn(context, 'drawImage').mockImplementation(((image: CanvasImageSource, dx?: number, dy?: number) => {
+      const from = (image as HTMLCanvasElement).id || 'canvas';
+      log.push({ entry: `${from}->${into}|${context.globalCompositeOperation}`, dx: dx ?? 0, dy: dy ?? 0 });
+    }) as typeof context.drawImage);
+    vi.spyOn(context, 'fillRect').mockImplementation((() => {
+      log.push({ entry: `fill->${into}|${context.globalCompositeOperation}`, dx: 0, dy: 0 });
+    }) as typeof context.fillRect);
+  }
+}
+
+function scene(): { source: CanvasRenderTarget; dest: CanvasRenderTarget } {
+  const source = createCanvasRenderTarget(4, 4);
+  const dest = createCanvasRenderTarget(4, 4);
+  source.canvas.id = 'source';
+  dest.canvas.id = 'dest';
+  return { source, dest };
+}
+
+function innerShadow(over: Partial<InnerShadowEffect> = {}): InnerShadowEffect {
+  return { kind: 'InnerShadowEffect', ...over } as InnerShadowEffect;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('applyInnerShadowEffectToCanvas', () => {
+  it('inverts, blurs, offsets, clips to the source, and draws over the source in that order', () => {
+    // Angle 0 so the offset is exactly (distance, 0) and the ordering assertion carries no float noise.
+    const { source, dest } = scene();
+    const { pool, targets } = seededPool(['mask', 'blurred', 'shadow']);
+    const log: Draw[] = [];
+    recordAll(log, [...targets, dest]);
+
+    applyInnerShadowEffectToCanvas(source, dest, pool, innerShadow({ angle: 0, distance: 4 }));
+
+    expect(log.map((d) => `${d.entry}|${d.dx},${d.dy}`)).toEqual([
+      'fill->mask|source-over|0,0',
+      'source->mask|destination-out|0,0',
+      'mask->blurred|source-over|0,0',
+      // Blur first, THEN offset. Offsetting the mask before blurring would smear the shadow
+      // symmetrically about the shifted edge and lose the directional falloff entirely.
+      'blurred->shadow|source-over|4,0',
+      'source->shadow|destination-in|0,0',
+      'source->dest|source-over|0,0',
+      'shadow->dest|source-over|0,0',
+    ]);
+  });
+
+  it('converts the angle from degrees when placing the offset', () => {
+    // The descriptor is authoring-layer, so its angle is degrees; treating it as radians would put a
+    // 90-degree shadow at roughly (-1.7, 3.6) instead of straight down.
+    const { source, dest } = scene();
+    const { pool, targets } = seededPool(['mask', 'blurred', 'shadow']);
+    const log: Draw[] = [];
+    recordAll(log, [...targets, dest]);
+
+    applyInnerShadowEffectToCanvas(source, dest, pool, innerShadow({ angle: 90, distance: 4 }));
+
+    const offset = log.find((d) => d.entry.startsWith('blurred->shadow'));
+    expect(offset?.dx).toBeCloseTo(0);
+    expect(offset?.dy).toBeCloseTo(4);
+  });
+
+  it('offsets into a separate target rather than onto the blurred one', () => {
+    // Drawing a target onto itself at an offset reads pixels it is concurrently writing. The third
+    // scratch target exists for exactly this, so the shift must land somewhere other than `blurred`.
+    const { source, dest } = scene();
+    const { pool, targets } = seededPool(['mask', 'blurred', 'shadow']);
+    const log: Draw[] = [];
+    recordAll(log, [...targets, dest]);
+
+    applyInnerShadowEffectToCanvas(source, dest, pool, innerShadow({ angle: 0, distance: 4 }));
+
+    expect(log.some((d) => d.entry === 'blurred->blurred|source-over')).toBe(false);
+    expect(log.some((d) => d.entry === 'blurred->shadow|source-over')).toBe(true);
+  });
+
+  it('drops the source and keeps only the shadow when sourceMode is hide', () => {
+    const { source, dest } = scene();
+    const { pool, targets } = seededPool(['mask', 'blurred', 'shadow']);
+    const log: Draw[] = [];
+    recordAll(log, [...targets, dest]);
+
+    applyInnerShadowEffectToCanvas(source, dest, pool, innerShadow({ sourceMode: 'hide' }));
+
+    expect(log.filter((d) => d.entry.endsWith('->dest|source-over')).map((d) => d.entry)).toEqual([
+      'shadow->dest|source-over',
+    ]);
+  });
+
+  it('draws the shadow once per whole unit of strength', () => {
+    const { source, dest } = scene();
+    const { pool, targets } = seededPool(['mask', 'blurred', 'shadow']);
+    const log: Draw[] = [];
+    recordAll(log, [...targets, dest]);
+
+    applyInnerShadowEffectToCanvas(source, dest, pool, innerShadow({ strength: 3 }));
+
+    expect(log.filter((d) => d.entry.startsWith('shadow->dest'))).toHaveLength(3);
+  });
+
+  it('returns all three scratch targets to the pool', () => {
+    const { source, dest } = scene();
+    const { pool } = seededPool(['mask', 'blurred', 'shadow']);
+
+    applyInnerShadowEffectToCanvas(source, dest, pool, innerShadow());
+
+    expect(pool.inUse).toHaveLength(0);
+    expect(pool.free).toHaveLength(3);
+  });
+
+  it('runs without a caller-supplied pool', () => {
+    const { source, dest } = scene();
+
+    expect(() => applyInnerShadowEffectToCanvas(source, dest, innerShadow())).not.toThrow();
+  });
+});
+
+describe('defaultCanvasInnerShadowEffectRunner', () => {
+  it('applies the shadow through the pipeline context', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    const { source, dest } = scene();
+    const { pool, targets } = seededPool(['mask', 'blurred', 'shadow']);
+    const log: Draw[] = [];
+    recordAll(log, [...targets, dest]);
+
+    defaultCanvasInnerShadowEffectRunner({ state, source, dest, pool }, innerShadow());
+
+    expect(log.map((d) => d.entry)).toContain('source->shadow|destination-in');
+  });
+});
+
+describe('registerCanvasInnerShadowEffect', () => {
+  it('registers the default runner under the InnerShadowEffect kind', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    registerCanvasInnerShadowEffect(state);
+
+    expect(getCanvasRenderEffectRunner(state, 'InnerShadowEffect')).toBe(defaultCanvasInnerShadowEffectRunner);
+  });
+});

package/src/canvasOuterGlowEffect.test.ts

@@ -29,7 +29,11 @@ vi.mock('./canvasSourceModeCompositing', () => ({
 }));
 
 import { drawCanvasEffectPass } from './canvasEffectCompositing';
-import { applyOuterGlowEffectToCanvas, defaultCanvasOuterGlowEffectRunner } from './canvasOuterGlowEffect';
+import {
+  applyOuterGlowEffectToCanvas,
+  defaultCanvasOuterGlowEffectRunner,
+  registerCanvasOuterGlowEffect,
+} from './canvasOuterGlowEffect';
 import { compositeCanvasSourceMode } from './canvasSourceModeCompositing';
 
 describe('applyOuterGlowEffectToCanvas', () => {
@@ -72,17 +76,20 @@ describe('defaultCanvasOuterGlowEffectRunner', () => {
   });
 });
 
-beforeEach(() => {
-  vi.clearAllMocks();
+describe('registerCanvasOuterGlowEffect', () => {
+  it('is a function', () => expect(registerCanvasOuterGlowEffect).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('registerCanvasOuterGlowEffect', () => {
+  it('is a function', () => {
+    expect(typeof registerCanvasOuterGlowEffect).toBe('function');
+  });
+});

package/src/canvasPixelateEffect.test.ts

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

package/src/canvasRealizedEffectRegistration.test.ts

@@ -0,0 +1,30 @@
+import { createCanvasRenderState } from '@flighthq/scene2d-canvas/contract';
+
+import { defaultCanvasBloomEffectRunner, registerCanvasBloomEffect } from './canvasBloomEffect';
+import { defaultCanvasBlurEffectRunner, registerCanvasBlurEffect } from './canvasBlurEffect';
+import { defaultCanvasDropShadowEffectRunner, registerCanvasDropShadowEffect } from './canvasDropShadowEffect';
+import { defaultCanvasFilmGrainEffectRunner, registerCanvasFilmGrainEffect } from './canvasFilmGrainEffect';
+import { defaultCanvasOuterGlowEffectRunner, registerCanvasOuterGlowEffect } from './canvasOuterGlowEffect';
+import { defaultCanvasPixelateEffectRunner, registerCanvasPixelateEffect } from './canvasPixelateEffect';
+import { getCanvasRenderEffectRunner } from './canvasRenderEffectRegistry';
+import { defaultCanvasScanlinesEffectRunner, registerCanvasScanlinesEffect } from './canvasScanlinesEffect';
+import { defaultCanvasVignetteEffectRunner, registerCanvasVignetteEffect } from './canvasVignetteEffect';
+
+const CASES = [
+  ['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;
+
+describe('realized Canvas effect registration', () => {
+  it.each(CASES)('maps %s to its leaf runner', (kind, register, runner) => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    register(state);
+    expect(getCanvasRenderEffectRunner(state, kind)).toBe(runner);
+  });
+});

package/src/canvasRenderEffectPipeline.test.ts

@@ -1,3 +1,7 @@
+import { createCanvasRenderState } from '@flighthq/scene2d-canvas/contract';
+import type { CanvasRenderEffectRunner, RenderEffect } from '@flighthq/types/contract';
+
+import { drawCanvasEffectPass } from './canvasEffectCompositing';
 import {
   acquireCanvasRenderTarget,
   beginCanvasRenderEffectPipeline,
@@ -7,6 +11,7 @@ import {
   endCanvasRenderEffectPipeline,
   releaseCanvasRenderTarget,
 } from './canvasRenderEffectPipeline';
+import { registerCanvasRenderEffect } from './canvasRenderEffectRegistry';
 
 describe('acquireCanvasRenderTarget', () => {
   it('is a function', () => {
@@ -48,6 +53,39 @@ describe('endCanvasRenderEffectPipeline', () => {
   it('is a function', () => {
     expect(typeof endCanvasRenderEffectPipeline).toBe('function');
   });
+
+  it('writes an unregistered effect destination before chaining and presenting it', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    const state = createCanvasRenderState(canvas);
+    const pipeline = createCanvasRenderEffectPipeline(state);
+    beginCanvasRenderEffectPipeline(state, pipeline);
+    const scene = pipeline.sceneTarget!;
+    scene.context.fillStyle = '#ff0000';
+    scene.context.fillRect(0, 0, 4, 4);
+
+    const realizedRunner = vi.fn<CanvasRenderEffectRunner>((ctx) => {
+      drawCanvasEffectPass(ctx.dest, ctx.source, 'none');
+    });
+    registerCanvasRenderEffect(state, 'RealizedEffect', realizedRunner);
+
+    endCanvasRenderEffectPipeline(state, pipeline, [
+      { kind: 'UnregisteredEffect' },
+      { kind: 'RealizedEffect' },
+    ] as RenderEffect[]);
+
+    const [unregisteredDest, realizedDest] = pipeline.pool.free;
+    expect(unregisteredDest).toBeDefined();
+    expect(realizedDest).toBeDefined();
+    expect(unregisteredDest!.context.drawImage).toHaveBeenCalledWith(scene.canvas, 0, 0);
+    expect(realizedRunner).toHaveBeenCalledWith(
+      expect.objectContaining({ source: unregisteredDest, dest: realizedDest }),
+      { kind: 'RealizedEffect' },
+    );
+    expect(realizedDest!.context.drawImage).toHaveBeenCalledWith(unregisteredDest!.canvas, 0, 0);
+    expect(state.context.drawImage).toHaveBeenCalledWith(realizedDest!.canvas, 0, 0);
+  });
 });
 
 describe('releaseCanvasRenderTarget', () => {

package/src/canvasRenderEffectRegistry.test.ts

@@ -1,4 +1,5 @@
-import type { CanvasRenderEffectRunner, CanvasRenderState } from '@flighthq/types/contract';
+import { createCanvasRenderState } from '@flighthq/scene2d-canvas/contract';
+import type { CanvasRenderEffectRunner } from '@flighthq/types/contract';
 
 import {
   getCanvasRenderEffectRunner,
@@ -17,20 +18,20 @@ describe('hasCanvasRenderEffectRunner', () => {
     expect(typeof hasCanvasRenderEffectRunner).toBe('function');
   });
   it('returns false when state has no registered runners', () => {
-    const fakeState = {} as CanvasRenderState;
-    expect(hasCanvasRenderEffectRunner(fakeState, 'NotRegisteredEffect')).toBe(false);
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    expect(hasCanvasRenderEffectRunner(state, 'NotRegisteredEffect')).toBe(false);
   });
   it('returns true after registering a runner for the given kind', () => {
-    const fakeState = {} as CanvasRenderState;
+    const state = createCanvasRenderState(document.createElement('canvas'));
     const fakeRunner = (() => {}) as unknown as CanvasRenderEffectRunner;
-    registerCanvasRenderEffect(fakeState, 'HasTestEffect', fakeRunner);
-    expect(hasCanvasRenderEffectRunner(fakeState, 'HasTestEffect')).toBe(true);
+    registerCanvasRenderEffect(state, 'HasTestEffect', fakeRunner);
+    expect(hasCanvasRenderEffectRunner(state, 'HasTestEffect')).toBe(true);
   });
   it('returns false for a different kind on the same state', () => {
-    const fakeState = {} as CanvasRenderState;
+    const state = createCanvasRenderState(document.createElement('canvas'));
     const fakeRunner = (() => {}) as unknown as CanvasRenderEffectRunner;
-    registerCanvasRenderEffect(fakeState, 'OnlyThisEffect', fakeRunner);
-    expect(hasCanvasRenderEffectRunner(fakeState, 'OtherEffect')).toBe(false);
+    registerCanvasRenderEffect(state, 'OnlyThisEffect', fakeRunner);
+    expect(hasCanvasRenderEffectRunner(state, 'OtherEffect')).toBe(false);
   });
 });
 

package/src/canvasRenderTextureEffect.test.ts

@@ -0,0 +1,73 @@
+import {
+  acquireCanvasRenderTexture,
+  createCanvasOffscreenRenderState,
+  createCanvasRenderState,
+  createCanvasRenderTexturePool,
+  copyCanvasRenderStateRegistrations,
+  getCanvasRenderTextureTarget,
+  isCanvasRenderTextureReady,
+  writeCanvasRenderTextureTarget,
+} from '@flighthq/scene2d-canvas/contract';
+import type { CanvasRenderEffectRunner } from '@flighthq/types/contract';
+
+import { getCanvasRenderEffectRunner, registerCanvasRenderEffect } from './canvasRenderEffectRegistry';
+import { applyCanvasRenderEffectsToRenderTexture } from './canvasRenderTextureEffect';
+
+describe('applyCanvasRenderEffectsToRenderTexture', () => {
+  it('ping-pongs an even registered chain so the last operation publishes destination', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    const pool = createCanvasRenderTexturePool();
+    const source = acquireCanvasRenderTexture(state, pool, { width: 8, height: 8 });
+    const dest = acquireCanvasRenderTexture(state, pool, { width: 8, height: 8 });
+    const scratch = acquireCanvasRenderTexture(state, pool, { width: 8, height: 8 });
+    writeCanvasRenderTextureTarget(state, source, () => {});
+    const first: CanvasRenderEffectRunner = vi.fn();
+    const second: CanvasRenderEffectRunner = vi.fn();
+    registerCanvasRenderEffect(state, 'acme.First', first);
+    registerCanvasRenderEffect(state, 'acme.Second', second);
+
+    expect(
+      applyCanvasRenderEffectsToRenderTexture(state, pool, source, dest, scratch, [
+        { kind: 'acme.First' },
+        { kind: 'acme.Second' },
+      ]),
+    ).toBe(true);
+
+    expect(first).toHaveBeenCalledOnce();
+    expect(second).toHaveBeenCalledOnce();
+    expect(vi.mocked(first).mock.calls[0][0].dest).toBe(getCanvasRenderTextureTarget(state, scratch));
+    expect(vi.mocked(second).mock.calls[0][0].dest).toBe(getCanvasRenderTextureTarget(state, dest));
+    expect(isCanvasRenderTextureReady(state, dest)).toBe(true);
+  });
+
+  it('leaves destination unpublished when no effect kind is registered', () => {
+    const state = createCanvasRenderState(document.createElement('canvas'));
+    const pool = createCanvasRenderTexturePool();
+    const source = acquireCanvasRenderTexture(state, pool, { width: 8, height: 8 });
+    const dest = acquireCanvasRenderTexture(state, pool, { width: 8, height: 8 });
+    const scratch = acquireCanvasRenderTexture(state, pool, { width: 8, height: 8 });
+    writeCanvasRenderTextureTarget(state, source, () => {});
+
+    expect(
+      applyCanvasRenderEffectsToRenderTexture(state, pool, source, dest, scratch, [{ kind: 'acme.Missing' }]),
+    ).toBe(false);
+    expect(isCanvasRenderTextureReady(state, dest)).toBe(false);
+  });
+});
+
+describe('offscreen effect registration snapshots', () => {
+  it('copies runners at derivation and requires explicit re-copy for later runners', () => {
+    const screen = createCanvasRenderState(document.createElement('canvas'));
+    const first: CanvasRenderEffectRunner = vi.fn();
+    const later: CanvasRenderEffectRunner = vi.fn();
+    registerCanvasRenderEffect(screen, 'acme.First', first);
+    const offscreen = createCanvasOffscreenRenderState(screen);
+    registerCanvasRenderEffect(screen, 'acme.Later', later);
+
+    expect(getCanvasRenderEffectRunner(offscreen, 'acme.First')).toBe(first);
+    expect(getCanvasRenderEffectRunner(offscreen, 'acme.Later')).toBeNull();
+
+    copyCanvasRenderStateRegistrations(offscreen, screen);
+    expect(getCanvasRenderEffectRunner(offscreen, 'acme.Later')).toBe(later);
+  });
+});

package/src/canvasScanlinesEffect.test.ts

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

package/src/canvasSourceModeCompositing.test.ts

@@ -1,7 +1,10 @@
+import { createCanvasRenderTarget } from '@flighthq/scene2d-canvas/contract';
+
 import {
   clearCanvasTarget,
   compositeCanvasImage,
   compositeCanvasSourceMode,
+  drawCanvasInvertedTintedAlphaMask,
   drawCanvasTintedAlphaMask,
 } from './canvasSourceModeCompositing';
 
@@ -23,6 +26,43 @@ describe('compositeCanvasSourceMode', () => {
   });
 });
 
+describe('drawCanvasInvertedTintedAlphaMask', () => {
+  it('fills the whole target and then knocks the source out of it', () => {
+    // The inversion IS the knockout: fill everywhere, then remove where the silhouette is. Doing it the
+    // other way round (source-in against the source) produces the ordinary tinted mask, which is the
+    // outer-effect primitive and would turn every inner effect into an outer one.
+    const dest = createCanvasRenderTarget(4, 4);
+    const source = createCanvasRenderTarget(4, 4);
+    source.canvas.id = 'source';
+    const log: string[] = [];
+    vi.spyOn(dest.context, 'fillRect').mockImplementation((() => {
+      log.push(`fill|${dest.context.globalCompositeOperation}`);
+    }) as typeof dest.context.fillRect);
+    vi.spyOn(dest.context, 'drawImage').mockImplementation(((_i: CanvasImageSource, dx?: number, dy?: number) => {
+      log.push(`draw|${dest.context.globalCompositeOperation}|${dx ?? 0},${dy ?? 0}`);
+    }) as typeof dest.context.drawImage);
+
+    drawCanvasInvertedTintedAlphaMask(dest, source, 0x123456, 1, 1);
+
+    expect(log).toEqual(['fill|source-over', 'draw|destination-out|0,0']);
+    vi.restoreAllMocks();
+  });
+
+  it('shifts which side of the boundary the tint survives on when given an offset', () => {
+    const dest = createCanvasRenderTarget(4, 4);
+    const source = createCanvasRenderTarget(4, 4);
+    let offset = '';
+    vi.spyOn(dest.context, 'drawImage').mockImplementation(((_i: CanvasImageSource, dx?: number, dy?: number) => {
+      offset = `${dx ?? 0},${dy ?? 0}`;
+    }) as typeof dest.context.drawImage);
+
+    drawCanvasInvertedTintedAlphaMask(dest, source, 0x123456, 1, 1, 3, -2);
+
+    expect(offset).toBe('3,-2');
+    vi.restoreAllMocks();
+  });
+});
+
 describe('drawCanvasTintedAlphaMask', () => {
   it('is a function', () => {
     expect(typeof drawCanvasTintedAlphaMask).toBe('function');

package/src/canvasVignetteEffect.test.ts

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

package/dist/canvasBokehDepthOfFieldEffect.d.ts

@@ -1,4 +0,0 @@
-import type { BokehDepthOfFieldEffect, CanvasRenderEffectRunner, CanvasRenderTarget } from '@flighthq/types/contract';
-export declare function applyBokehDepthOfFieldEffectToCanvas(source: Readonly<CanvasRenderTarget>, dest: Readonly<CanvasRenderTarget>, _effect: Readonly<BokehDepthOfFieldEffect>): void;
-export declare const defaultCanvasBokehDepthOfFieldEffectRunner: CanvasRenderEffectRunner;
-//# sourceMappingURL=canvasBokehDepthOfFieldEffect.d.ts.map

package/dist/canvasBokehDepthOfFieldEffect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasBokehDepthOfFieldEffect.d.ts","sourceRoot":"","sources":["../src/canvasBokehDepthOfFieldEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAMtH,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAClC,OAAO,EAAE,QAAQ,CAAC,uBAAuB,CAAC,GACzC,IAAI,CAEN;AAED,eAAO,MAAM,0CAA0C,EAAE,wBAExD,CAAC"}

package/dist/canvasBokehDepthOfFieldEffect.js

@@ -1,10 +0,0 @@
-import { passthroughCanvasEffectPass } from './canvasEffectCompositing';
-// Bokeh depth-of-field (PASSTHROUGH): a per-pixel circle-of-confusion blur driven by a depth buffer.
-// Genuinely unsupportable on Canvas 2D: needs a depth G-buffer the 2D context does not expose. Passthrough.
-export function applyBokehDepthOfFieldEffectToCanvas(source, dest, _effect) {
-    passthroughCanvasEffectPass(dest, source);
-}
-export const defaultCanvasBokehDepthOfFieldEffectRunner = (ctx, effect) => {
-    applyBokehDepthOfFieldEffectToCanvas(ctx.source, ctx.dest, effect);
-};
-//# sourceMappingURL=canvasBokehDepthOfFieldEffect.js.map

package/dist/canvasBokehDepthOfFieldEffect.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasBokehDepthOfFieldEffect.js","sourceRoot":"","sources":["../src/canvasBokehDepthOfFieldEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAExE,qGAAqG;AACrG,4GAA4G;AAC5G,MAAM,UAAU,oCAAoC,CAClD,MAAoC,EACpC,IAAkC,EAClC,OAA0C;IAE1C,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,0CAA0C,GAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;IAClG,oCAAoC,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAiC,CAAC,CAAC;AAChG,CAAC,CAAC"}

package/dist/canvasCameraMotionBlurEffect.d.ts

@@ -1,4 +0,0 @@
-import type { CameraMotionBlurEffect, CanvasRenderEffectRunner, CanvasRenderTarget } from '@flighthq/types/contract';
-export declare function applyCameraMotionBlurEffectToCanvas(source: Readonly<CanvasRenderTarget>, dest: Readonly<CanvasRenderTarget>, _effect: Readonly<CameraMotionBlurEffect>): void;
-export declare const defaultCanvasCameraMotionBlurEffectRunner: CanvasRenderEffectRunner;
-//# sourceMappingURL=canvasCameraMotionBlurEffect.d.ts.map

package/dist/canvasCameraMotionBlurEffect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasCameraMotionBlurEffect.d.ts","sourceRoot":"","sources":["../src/canvasCameraMotionBlurEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAOrH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAClC,OAAO,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GACxC,IAAI,CAEN;AAED,eAAO,MAAM,yCAAyC,EAAE,wBAEvD,CAAC"}

package/dist/canvasCameraMotionBlurEffect.js

@@ -1,11 +0,0 @@
-import { passthroughCanvasEffectPass } from './canvasEffectCompositing';
-// Camera3D motion blur (PASSTHROUGH): a zoom smear accumulating taps toward screen center.
-// Genuinely unsupportable on Canvas 2D: needs camera velocity/depth reprojection the 2D context does not
-// expose. Passthrough.
-export function applyCameraMotionBlurEffectToCanvas(source, dest, _effect) {
-    passthroughCanvasEffectPass(dest, source);
-}
-export const defaultCanvasCameraMotionBlurEffectRunner = (ctx, effect) => {
-    applyCameraMotionBlurEffectToCanvas(ctx.source, ctx.dest, effect);
-};
-//# sourceMappingURL=canvasCameraMotionBlurEffect.js.map

package/dist/canvasCameraMotionBlurEffect.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasCameraMotionBlurEffect.js","sourceRoot":"","sources":["../src/canvasCameraMotionBlurEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAExE,2FAA2F;AAC3F,yGAAyG;AACzG,uBAAuB;AACvB,MAAM,UAAU,mCAAmC,CACjD,MAAoC,EACpC,IAAkC,EAClC,OAAyC;IAEzC,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,yCAAyC,GAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;IACjG,mCAAmC,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAgC,CAAC,CAAC;AAC9F,CAAC,CAAC"}

package/dist/canvasChromaticAberrationEffect.d.ts

@@ -1,4 +0,0 @@
-import type { CanvasRenderEffectRunner, CanvasRenderTarget, ChromaticAberrationEffect } from '@flighthq/types/contract';
-export declare function applyChromaticAberrationEffectToCanvas(source: Readonly<CanvasRenderTarget>, dest: Readonly<CanvasRenderTarget>, _effect: Readonly<ChromaticAberrationEffect>): void;
-export declare const defaultCanvasChromaticAberrationEffectRunner: CanvasRenderEffectRunner;
-//# sourceMappingURL=canvasChromaticAberrationEffect.d.ts.map

package/dist/canvasChromaticAberrationEffect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasChromaticAberrationEffect.d.ts","sourceRoot":"","sources":["../src/canvasChromaticAberrationEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAOxH,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAClC,OAAO,EAAE,QAAQ,CAAC,yBAAyB,CAAC,GAC3C,IAAI,CAEN;AAED,eAAO,MAAM,4CAA4C,EAAE,wBAE1D,CAAC"}

package/dist/canvasChromaticAberrationEffect.js

@@ -1,11 +0,0 @@
-import { passthroughCanvasEffectPass } from './canvasEffectCompositing';
-// Chromatic aberration (PASSTHROUGH): splitting R/G/B channels at offset positions, which a 2D drawImage
-// cannot address. No CSS filter equivalent, but expressible per-pixel via getImageData/putImageData; not
-// yet implemented — passthrough for now.
-export function applyChromaticAberrationEffectToCanvas(source, dest, _effect) {
-    passthroughCanvasEffectPass(dest, source);
-}
-export const defaultCanvasChromaticAberrationEffectRunner = (ctx, effect) => {
-    applyChromaticAberrationEffectToCanvas(ctx.source, ctx.dest, effect);
-};
-//# sourceMappingURL=canvasChromaticAberrationEffect.js.map

package/dist/canvasChromaticAberrationEffect.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasChromaticAberrationEffect.js","sourceRoot":"","sources":["../src/canvasChromaticAberrationEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAExE,yGAAyG;AACzG,yGAAyG;AACzG,yCAAyC;AACzC,MAAM,UAAU,sCAAsC,CACpD,MAAoC,EACpC,IAAkC,EAClC,OAA4C;IAE5C,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,4CAA4C,GAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;IACpG,sCAAsC,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAmC,CAAC,CAAC;AACpG,CAAC,CAAC"}

package/dist/canvasConvolutionEffect.d.ts

@@ -1,4 +0,0 @@
-import type { CanvasRenderEffectRunner, CanvasRenderTarget, ConvolutionEffect } from '@flighthq/types/contract';
-export declare function applyConvolutionEffectToCanvas(source: Readonly<CanvasRenderTarget>, dest: Readonly<CanvasRenderTarget>, _effect: Readonly<ConvolutionEffect>): void;
-export declare const defaultCanvasConvolutionEffectRunner: CanvasRenderEffectRunner;
-//# sourceMappingURL=canvasConvolutionEffect.d.ts.map

package/dist/canvasConvolutionEffect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasConvolutionEffect.d.ts","sourceRoot":"","sources":["../src/canvasConvolutionEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAOhH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAClC,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GACnC,IAAI,CAEN;AAED,eAAO,MAAM,oCAAoC,EAAE,wBAElD,CAAC"}

package/dist/canvasConvolutionEffect.js

@@ -1,11 +0,0 @@
-import { passthroughCanvasEffectPass } from './canvasEffectCompositing';
-// Convolution (PASSTHROUGH): a generic matrix-kernel gather is per-pixel neighbor math. No CSS filter
-// equivalent, but expressible per-pixel via getImageData/putImageData; not yet implemented — passthrough
-// for now.
-export function applyConvolutionEffectToCanvas(source, dest, _effect) {
-    passthroughCanvasEffectPass(dest, source);
-}
-export const defaultCanvasConvolutionEffectRunner = (ctx, effect) => {
-    applyConvolutionEffectToCanvas(ctx.source, ctx.dest, effect);
-};
-//# sourceMappingURL=canvasConvolutionEffect.js.map

package/dist/canvasConvolutionEffect.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasConvolutionEffect.js","sourceRoot":"","sources":["../src/canvasConvolutionEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAExE,sGAAsG;AACtG,yGAAyG;AACzG,WAAW;AACX,MAAM,UAAU,8BAA8B,CAC5C,MAAoC,EACpC,IAAkC,EAClC,OAAoC;IAEpC,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,oCAAoC,GAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;IAC5F,8BAA8B,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAA2B,CAAC,CAAC;AACpF,CAAC,CAAC"}

package/dist/canvasCrtEffect.d.ts

@@ -1,4 +0,0 @@
-import type { CanvasRenderEffectRunner, CanvasRenderTarget, CrtEffect } from '@flighthq/types/contract';
-export declare function applyCrtEffectToCanvas(source: Readonly<CanvasRenderTarget>, dest: Readonly<CanvasRenderTarget>, _effect: Readonly<CrtEffect>): void;
-export declare const defaultCanvasCrtEffectRunner: CanvasRenderEffectRunner;
-//# sourceMappingURL=canvasCrtEffect.d.ts.map

package/dist/canvasCrtEffect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canvasCrtEffect.d.ts","sourceRoot":"","sources":["../src/canvasCrtEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAOxG,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAClC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,GAC3B,IAAI,CAEN;AAED,eAAO,MAAM,4BAA4B,EAAE,wBAE1C,CAAC"}