@flighthq/effects-wgpu 0.4.0-next.1488.43bcb37 → 0.4.0-next.1585.bf131c8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/effects-wgpu",
-  "version": "0.4.0-next.1488.43bcb37",
+  "version": "0.4.0-next.1585.bf131c8",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,14 +38,14 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/adjustments": "0.4.0-next.1488.43bcb37",
-    "@flighthq/color": "0.4.0-next.1488.43bcb37",
-    "@flighthq/effects": "0.4.0-next.1488.43bcb37",
-    "@flighthq/geometry": "0.4.0-next.1488.43bcb37",
-    "@flighthq/log": "0.4.0-next.1488.43bcb37",
-    "@flighthq/render-wgpu": "0.4.0-next.1488.43bcb37",
-    "@flighthq/registry": "0.4.0-next.1488.43bcb37",
-    "@flighthq/types": "0.4.0-next.1488.43bcb37"
+    "@flighthq/adjustments": "0.4.0-next.1585.bf131c8",
+    "@flighthq/color": "0.4.0-next.1585.bf131c8",
+    "@flighthq/effects": "0.4.0-next.1585.bf131c8",
+    "@flighthq/geometry": "0.4.0-next.1585.bf131c8",
+    "@flighthq/log": "0.4.0-next.1585.bf131c8",
+    "@flighthq/render-wgpu": "0.4.0-next.1585.bf131c8",
+    "@flighthq/registry": "0.4.0-next.1585.bf131c8",
+    "@flighthq/types": "0.4.0-next.1585.bf131c8"
   },
   "peerDependencies": {
     "@webgpu/types": "^0.1.70"

package/src/wgpuBevelEffect.test.ts

@@ -1,19 +1,227 @@
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu/contract';
+import type { BevelEffect, WgpuRenderState, WgpuRenderTarget, WgpuRenderTargetPool } from '@flighthq/types/contract';
+
+const passMock = vi.hoisted(() => ({
+  clearWgpuEffectTarget: vi.fn(),
+  createWgpuDualSourceEffectPipeline: vi.fn(() => ({ pipeline: {} })),
+  drawWgpuDualSourceEffectPass: vi.fn(
+    (
+      _state: unknown,
+      _field: unknown,
+      _source: unknown,
+      _dest: unknown,
+      _pipeline: unknown,
+      setUniforms: (f32: Float32Array) => void,
+    ) => {
+      const f32 = new Float32Array(12);
+      setUniforms(f32);
+      recorded.composites.push([...f32]);
+    },
+  ),
+}));
+const blitMock = vi.hoisted(() => ({
+  applyWgpuEffectBlitPass: vi.fn(() => recorded.calls.push('blit')),
+  applyWgpuEffectErasePass: vi.fn(() => recorded.calls.push('erase')),
+}));
+const blurMock = vi.hoisted(() => ({
+  applyWgpuEffectBoxBlur: vi.fn((_state: unknown, _s: unknown, _d: unknown, _t: unknown, options: unknown) => {
+    recorded.blurs.push(options);
+  }),
+}));
+const tintMock = vi.hoisted(() => ({
+  applyWgpuEffectTintPass: vi.fn(
+    (_state: unknown, _source: unknown, _dest: unknown, color: number, alpha: number, strength: number) => {
+      recorded.tints.push([color, alpha, strength]);
+    },
+  ),
+}));
+const targetMock = vi.hoisted(() => ({
+  acquireWgpuRenderTarget: vi.fn((_state: unknown, _pool: unknown, descriptor: unknown) => {
+    const target = { ...(descriptor as object), id: `scratch-${recorded.acquired.length}`, view: {} };
+    recorded.acquired.push(target);
+    return target;
+  }),
+  releaseWgpuRenderTarget: vi.fn((_pool: unknown, target: unknown) => recorded.released.push(target)),
+}));
+const recorded = vi.hoisted(() => ({
+  acquired: [] as unknown[],
+  blurs: [] as unknown[],
+  calls: [] as string[],
+  composites: [] as number[][],
+  released: [] as unknown[],
+  tints: [] as (number | undefined)[][],
+}));
+
+vi.mock('./wgpuEffectBlitShader', () => blitMock);
+vi.mock('./wgpuEffectBoxBlur', () => blurMock);
+vi.mock('./wgpuEffectPass', () => passMock);
+vi.mock('./wgpuEffectTintShader', () => tintMock);
+
+vi.mock('@flighthq/render-wgpu/contract', async () => {
+  const actual = (await vi.importActual('@flighthq/render-wgpu/contract')) as Record<string, unknown>;
+  return { ...actual, ...targetMock };
+});
+
 import { applyBevelEffectToWgpu, defaultWgpuBevelEffectRunner, registerWgpuBevelEffect } from './wgpuBevelEffect';
+import { getWgpuRenderEffectRunner } from './wgpuRenderEffectRegistry';
+
+beforeAll(() => installWgpuMock());
+
+const SOURCE_WIDTH = 100;
+const SOURCE_HEIGHT = 50;
+
+function apply(effect: Readonly<Partial<BevelEffect>> = {}): readonly number[] {
+  for (const list of [
+    recorded.acquired,
+    recorded.blurs,
+    recorded.calls,
+    recorded.composites,
+    recorded.released,
+    recorded.tints,
+  ]) {
+    list.length = 0;
+  }
+  const target = {
+    format: 'rgba8unorm',
+    height: SOURCE_HEIGHT,
+    view: {},
+    width: SOURCE_WIDTH,
+  } as unknown as WgpuRenderTarget;
+  applyBevelEffectToWgpu(
+    {} as unknown as WgpuRenderState,
+    target,
+    target,
+    {} as unknown as WgpuRenderTargetPool,
+    {
+      kind: 'BevelEffect',
+      ...effect,
+    } as BevelEffect,
+  );
+  return recorded.composites[0]!;
+}
 
 describe('applyBevelEffectToWgpu', () => {
-  it('is a function', () => {
-    expect(typeof applyBevelEffectToWgpu).toBe('function');
+  // ★ THE DEFECT THIS REPLACES A `typeof` CHECK FOR — branch 1, restorable from git. The highlight and
+  // shadow colours used to be read as 24-bit RGB with the `*Alpha` fields standing alone
+  // (`effect.shadowColor ?? 0x000000`). They are packed RGBA everywhere else in the SDK, so under the old
+  // reading 0x102030c0 shaded the bevel 0x2030c0 at full opacity — a different colour, fully plausible,
+  // with the c0 silently becoming part of the blue channel. Unified in 51e364d1d.
+  //
+  // MEASURED by restoring 51e364d1d^'s exact four lines — 2 of 11 failed:
+  //   AssertionError: expected 0.3333333432674408 to be close to 0.615686274509804
+  //   AssertionError: expected 0.125490203499794 to be close to 0.06274509803921569
+  it('splits a packed RGBA colour into composite RGB and an alpha multiplied by its Alpha field', () => {
+    const uniforms = apply({
+      highlightAlpha: 0.5,
+      highlightColor: 0x9d55ff80,
+      shadowAlpha: 1,
+      shadowColor: 0x102030c0,
+    });
+
+    expect(uniforms[0]).toBeCloseTo(0x9d / 255, 6);
+    expect(uniforms[1]).toBeCloseTo(0x55 / 255, 6);
+    expect(uniforms[2]).toBeCloseTo(0xff / 255, 6);
+    expect(uniforms[3]).toBeCloseTo((0x80 / 255) * 0.5, 6);
+
+    expect(uniforms[4]).toBeCloseTo(0x10 / 255, 6);
+    expect(uniforms[5]).toBeCloseTo(0x20 / 255, 6);
+    expect(uniforms[6]).toBeCloseTo(0x30 / 255, 6);
+    expect(uniforms[7]).toBeCloseTo(0xc0 / 255, 6);
+  });
+
+  it('defaults to opaque white over opaque black', () => {
+    const uniforms = apply();
+
+    expect(uniforms.slice(0, 4)).toEqual([1, 1, 1, 1]);
+    expect(uniforms.slice(4, 8)).toEqual([0, 0, 0, 1]);
+  });
+
+  // ★ THE VERTICAL SEAM, the same class that was wrong in six effects tonight: the light direction
+  // arrives in screen space (Y down) and only the Y component is negated on the way into the shader.
+  // Written symmetrically, every bevel is lit from the wrong side — and still looks like a bevel.
+  it('negates only the vertical component of the light offset', () => {
+    // 0 degrees points along +X, 90 degrees along +Y in screen space.
+    const alongX = apply({ angle: 0, distance: 10 });
+    expect(alongX[8]).toBeCloseTo(10 / SOURCE_WIDTH, 6);
+    expect(alongX[9]).toBeCloseTo(0, 6);
+
+    const alongY = apply({ angle: 90, distance: 10 });
+    expect(alongY[8]).toBeCloseTo(0, 6);
+    expect(alongY[9]).toBeCloseTo(-10 / SOURCE_HEIGHT, 6);
+  });
+
+  // Normalised per axis, and the two source dimensions differ here on purpose: with them equal, dividing
+  // by the wrong one is invisible.
+  it('normalises each offset component by its own source dimension', () => {
+    const uniforms = apply({ angle: 45, distance: 10 });
+
+    // cos(45)*10 and sin(45)*10 both round to 7.
+    expect(uniforms[8]).toBeCloseTo(7 / SOURCE_WIDTH, 6);
+    expect(uniforms[9]).toBeCloseTo(-7 / SOURCE_HEIGHT, 6);
+  });
+
+  it('snaps the light offset to whole pixels, matching the surface reference', () => {
+    // cos(30)*10 = 8.66 -> 9, sin(30)*10 = 5 -> 5.
+    const uniforms = apply({ angle: 30, distance: 10 });
+
+    expect(uniforms[8] * SOURCE_WIDTH).toBeCloseTo(9, 6);
+    expect(uniforms[9] * SOURCE_HEIGHT).toBeCloseTo(-5, 6);
+  });
+
+  it('maps each bevel type to its clip mode', () => {
+    expect(apply({ bevelType: 'inner' })[11]).toBe(1);
+    expect(apply({ bevelType: 'outer' })[11]).toBe(2);
+    expect(apply({ bevelType: 'full' })[11]).toBe(0);
+    // The default is inner, which is the one a caller gets without asking.
+    expect(apply()[11]).toBe(1);
+  });
+
+  it('draws the source under the bevel for draw mode and erases it for knockout', () => {
+    apply({ sourceMode: 'draw' });
+    expect(recorded.calls).toEqual(['blit']);
+
+    apply({ sourceMode: 'knockout' });
+    expect(recorded.calls).toEqual(['erase']);
+  });
+
+  // The field is built with a NEUTRAL tint at strength 1 — `strength` is the per-pixel gradient intensity
+  // in the composite, not something baked into the blurred silhouette. Baking it there instead would
+  // change the bevel's width as well as its contrast.
+  it('builds the alpha field with a neutral tint and passes strength to the composite instead', () => {
+    const uniforms = apply({ strength: 3 });
+
+    expect(recorded.tints[0]).toEqual([0xffffffff, 1, 1]);
+    expect(uniforms[10]).toBe(3);
+  });
+
+  it('releases every scratch target it acquired', () => {
+    apply();
+
+    expect(recorded.acquired).toHaveLength(3);
+    expect(recorded.released).toEqual(recorded.acquired);
   });
 });
 
 describe('defaultWgpuBevelEffectRunner', () => {
-  it('is a function', () => {
-    expect(typeof defaultWgpuBevelEffectRunner).toBe('function');
+  it('routes the runner context through to the pass', () => {
+    recorded.composites.length = 0;
+    const target = { format: 'rgba8unorm', height: 8, view: {}, width: 8 } as unknown as WgpuRenderTarget;
+
+    defaultWgpuBevelEffectRunner(
+      { dest: target, pool: {}, source: target, state: {} } as never,
+      { kind: 'BevelEffect', shadowColor: 0x102030ff } as BevelEffect,
+    );
+
+    expect(recorded.composites[0]![4]).toBeCloseTo(0x10 / 255, 6);
   });
 });
 
 describe('registerWgpuBevelEffect', () => {
-  it('is a separately importable registration primitive', () => {
-    expect(registerWgpuBevelEffect).toBeTypeOf('function');
+  it('makes the runner resolvable for the BevelEffect kind', async () => {
+    const state = await createWgpuRenderStateForTest();
+
+    expect(getWgpuRenderEffectRunner(state, 'BevelEffect')).toBeNull();
+    registerWgpuBevelEffect(state);
+    expect(getWgpuRenderEffectRunner(state, 'BevelEffect')).toBe(defaultWgpuBevelEffectRunner);
   });
 });

package/src/wgpuColorLutPass.test.ts

@@ -1,7 +1,252 @@
+import { installWgpuMock } from '@flighthq/render-wgpu/contract';
+import type { ColorLut, WgpuColorLutTextureCache, WgpuRenderState, WgpuRenderTarget } from '@flighthq/types/contract';
+
+const passStateMock = vi.hoisted(() => ({
+  EFFECT_VERTEX_WGSL: 'VERTEX_WGSL\n',
+  getWgpuEffectPassState: vi.fn(() => passState),
+}));
+const passState = vi.hoisted(() => ({
+  acquireSlot: vi.fn(() => 256),
+  beginPass: vi.fn((_dest: unknown, loadOp: string) => {
+    recorded.loadOps.push(loadOp);
+    return {
+      draw: vi.fn((count: number) => recorded.draws.push(count)),
+      end: vi.fn(),
+      setBindGroup: vi.fn((index: number, group: unknown) => recorded.bindGroups.push({ group, index })),
+      setPipeline: vi.fn((pipeline: unknown) => recorded.pipelines.push(pipeline)),
+    };
+  }),
+  sampler: { id: 'sampler' },
+  textureBGLayout: { id: 'textureBGLayout' },
+  uniformBG: { id: 'uniformBG' },
+  uniformBGLayout: { id: 'uniformBGLayout' },
+  writeSlot: vi.fn((_offset: number, write: (f32: Float32Array) => void) => {
+    const f32 = new Float32Array(4);
+    write(f32);
+    recorded.uniforms.push([...f32]);
+  }),
+}));
+const recorded = vi.hoisted(() => ({
+  bindGroups: [] as { group: unknown; index: number }[],
+  draws: [] as number[],
+  loadOps: [] as string[],
+  pipelines: [] as unknown[],
+  shaderCode: [] as string[],
+  uniforms: [] as number[][],
+}));
+
+vi.mock('./wgpuEffectPass', () => passStateMock);
+
 import { applyColorLutPassToWgpu } from './wgpuColorLutPass';
 
+// The WebGPU flag enums are type-level only in @webgpu/types, so jsdom has no runtime values for the
+// usage and visibility bits this module ORs together.
+beforeAll(() => installWgpuMock());
+
+function createHarness(): {
+  createTexture: ReturnType<typeof vi.fn>;
+  destroyed: string[];
+  state: WgpuRenderState;
+  uploads: Uint8Array[];
+} {
+  const destroyed: string[] = [];
+  const uploads: Uint8Array[] = [];
+  let nextTexture = 0;
+  const createTexture = vi.fn(() => {
+    const id = `lut-${nextTexture++}`;
+    return { createView: vi.fn(() => ({ id: `${id}-view` })), destroy: () => destroyed.push(id), id };
+  });
+  const state = {
+    device: {
+      createBindGroup: vi.fn((descriptor: unknown) => ({ descriptor })),
+      createBindGroupLayout: vi.fn(() => ({ id: 'lutBGLayout' })),
+      createPipelineLayout: vi.fn(() => ({ id: 'pipelineLayout' })),
+      createRenderPipeline: vi.fn((descriptor: { fragment: { targets: { format: string }[] } }) => ({
+        format: descriptor.fragment.targets[0]!.format,
+      })),
+      createShaderModule: vi.fn((descriptor: { code: string }) => {
+        recorded.shaderCode.push(descriptor.code);
+        return { id: 'module' };
+      }),
+      createTexture,
+      queue: { writeTexture: vi.fn((_destination: unknown, data: Uint8Array) => uploads.push(new Uint8Array(data))) },
+    },
+  } as unknown as WgpuRenderState;
+  return { createTexture, destroyed, state, uploads };
+}
+
+function createLut(size: number, samples: ReadonlyArray<number>): ColorLut {
+  return { samples: Float32Array.from(samples), size } as unknown as ColorLut;
+}
+
+function createGreyLut(size = 2): ColorLut {
+  const count = size * size * size;
+  const samples: number[] = [];
+  for (let index = 0; index < count; index++)
+    samples.push(index / (count - 1), index / (count - 1), index / (count - 1));
+  return createLut(size, samples);
+}
+
+function emptyCache(): WgpuColorLutTextureCache {
+  return { lut: null, size: 0, texture: null } as unknown as WgpuColorLutTextureCache;
+}
+
+function apply(
+  harness: ReturnType<typeof createHarness>,
+  lut: Readonly<ColorLut>,
+  cache: WgpuColorLutTextureCache,
+  format = 'rgba8unorm',
+): void {
+  const target = { format, view: { id: 'sourceView' } } as unknown as WgpuRenderTarget;
+  applyColorLutPassToWgpu(harness.state, target, target, lut, cache);
+}
+
+function reset(): void {
+  recorded.bindGroups.length = 0;
+  recorded.draws.length = 0;
+  recorded.loadOps.length = 0;
+  recorded.pipelines.length = 0;
+  recorded.shaderCode.length = 0;
+  recorded.uniforms.length = 0;
+}
+
 describe('applyColorLutPassToWgpu', () => {
-  it('is a function', () => {
-    expect(typeof applyColorLutPassToWgpu).toBe('function');
+  // ★ WHY THIS FILE IS WORTH MORE THAN ONE EFFECT'S. It is the SINGLE realization for the whole LUT-tier
+  // Adjustment family on this backend — curves, levels, gamma, colour grading all bake to one 3D LUT and
+  // arrive here — so an error is wrong colour everywhere at once, and a LUT lookup always returns a
+  // colour rather than an error.
+  //
+  // ★ NO HISTORICAL DEFECT EXISTS FOR THIS FILE, so the cases below are CONSTRUCTED, not restored: its
+  // history holds the feature commit, a caching perf change, a type move and the lane refactor.
+  //
+  // ★ SCOPE, STATED SO A PASS IS NOT OVERREAD. The fragment arithmetic — the half-texel cell-centre
+  // mapping — is evaluated numerically on the paired Gl file, where a scalar GLSL evaluator exists;
+  // effects-wgpu must not depend on effects-gl to borrow it. What this file covers is everything on the
+  // CPU side of the seam, which is where this backend carries complexity its sibling does not: an
+  // explicit bind-group layout, a pipeline per destination format, and a texture that is recreated rather
+  // than merely rewritten when the LUT size changes.
+  beforeEach(() => reset());
+
+  it('uploads the LUT with samples scaled to bytes and alpha forced opaque', () => {
+    const harness = createHarness();
+
+    apply(
+      harness,
+      createLut(
+        2,
+        new Array(24).fill(0).map((_, index) => (index % 3) / 2),
+      ),
+      emptyCache(),
+    );
+
+    expect([...harness.uploads[0]!.slice(0, 8)]).toEqual([0, 128, 255, 255, 0, 128, 255, 255]);
+  });
+
+  it('clamps a sample outside zero to one rather than wrapping it', () => {
+    const harness = createHarness();
+    const samples = new Array(24).fill(0);
+    samples[0] = -0.5;
+    samples[1] = 1.5;
+
+    apply(harness, createLut(2, samples), emptyCache());
+
+    expect([...harness.uploads[0]!.slice(0, 2)]).toEqual([0, 255]);
+  });
+
+  // ★ CONSTRUCTED CASE: the write is skipped when handed the SAME LUT reference. A static grade is the
+  // common case and a 32³ table is 128 KB — re-uploading it every frame is a defect no output comparison
+  // could ever see.
+  it('writes once for an unchanged LUT and again when it changes', () => {
+    const harness = createHarness();
+    const cache = emptyCache();
+    const lut = createGreyLut();
+
+    apply(harness, lut, cache);
+    apply(harness, lut, cache);
+    expect(harness.uploads).toHaveLength(1);
+
+    apply(harness, createGreyLut(), cache);
+    expect(harness.uploads).toHaveLength(2);
+  });
+
+  // ★ CONSTRUCTED CASE: a 3D texture's dimensions are fixed at creation, so a LUT of a different SIZE
+  // needs a new texture — rewriting the old one would either fail validation or grade through a table of
+  // the wrong extent. The previous texture is destroyed rather than leaked, since this is a real GPU
+  // resource and `destroy` is the verb for one.
+  // MEASURED by dropping the `cache.size !== n` arm so the texture is only created once — 1 of 9 failed,
+  // the predicted one and only it:
+  //   AssertionError: expected "vi.fn()" to be called 2 times, but got 1 times
+  it('recreates and destroys the texture when the LUT size changes, and reuses it when it does not', () => {
+    const harness = createHarness();
+    const cache = emptyCache();
+
+    apply(harness, createGreyLut(2), cache);
+    apply(harness, createGreyLut(2), cache);
+    expect(harness.createTexture).toHaveBeenCalledTimes(1);
+    expect(harness.destroyed).toEqual([]);
+
+    apply(harness, createGreyLut(4), cache);
+    expect(harness.createTexture).toHaveBeenCalledTimes(2);
+    expect(harness.destroyed).toEqual(['lut-0']);
+  });
+
+  // ★ CONSTRUCTED CASE: a render pipeline's colour target format must match the attachment it draws into,
+  // so an HDR (rgba16float) effect target needs its own pipeline. Cached per state alone, the second
+  // format would silently reuse the first's pipeline — a validation error at best and a wrong-format
+  // draw at worst, and only on the HDR path.
+  // MEASURED by looking the pipeline up without the format key — 1 of 9 failed, the predicted one and
+  // only it:
+  //   AssertionError: expected "vi.fn()" to be called 2 times, but got 1 times
+  it('builds one pipeline per destination format and reuses it within a format', () => {
+    const harness = createHarness();
+    const cache = emptyCache();
+
+    apply(harness, createGreyLut(), cache, 'rgba8unorm');
+    apply(harness, createGreyLut(), cache, 'rgba8unorm');
+    expect(harness.state.device.createRenderPipeline).toHaveBeenCalledTimes(1);
+
+    apply(harness, createGreyLut(), cache, 'rgba16float');
+    expect(harness.state.device.createRenderPipeline).toHaveBeenCalledTimes(2);
+    expect(recorded.pipelines.at(-1)).toEqual({ format: 'rgba16float' });
+  });
+
+  // The group indices are a contract with the WGSL: 0 uniforms, 1 source texture, 2 LUT. Swapped, the
+  // pass would sample the scene as its own grade — every draw wrong, in a way that still produces pixels.
+  it('binds uniforms, source and LUT to groups zero, one and two', () => {
+    const harness = createHarness();
+
+    apply(harness, createGreyLut(), emptyCache());
+
+    expect(recorded.bindGroups.map((entry) => entry.index)).toEqual([0, 1, 2]);
+    expect(recorded.draws).toEqual([6]);
+  });
+
+  // `load` rather than `clear`: this is a full-frame grade over what is already in the target.
+  it('loads the destination rather than clearing it', () => {
+    const harness = createHarness();
+
+    apply(harness, createGreyLut(), emptyCache());
+
+    expect(recorded.loadOps).toEqual(['load']);
+  });
+
+  it('passes the LUT size to the shader as its one uniform', () => {
+    const harness = createHarness();
+
+    apply(harness, createGreyLut(4), emptyCache());
+
+    expect(recorded.uniforms[0]![0]).toBe(4);
+  });
+
+  // A TEXT check, and named as one: it pins the half-texel form against the numeric assertions made on
+  // the Gl sibling. It cannot tell whether the arithmetic is right — only that these two shaders still
+  // agree about what to compute, which is the cross-backend claim worth locking here.
+  it('computes cell centres from the size uniform, matching the Gl recipe', () => {
+    const harness = createHarness();
+
+    apply(harness, createGreyLut(), emptyCache());
+
+    expect(recorded.shaderCode[0]).toContain('(uni.u_size - 1.0) / uni.u_size');
+    expect(recorded.shaderCode[0]).toContain('0.5 / uni.u_size');
   });
 });

package/src/wgpuColorMatrixPass.test.ts

@@ -1,7 +1,105 @@
+import type { WgpuRenderState, WgpuRenderTarget } from '@flighthq/types/contract';
+
+const passMock = vi.hoisted(() => ({
+  drawWgpuEffectPass: vi.fn(
+    (
+      _state: unknown,
+      _source: unknown,
+      _dest: unknown,
+      _pipeline: unknown,
+      setUniforms: (f32: Float32Array) => void,
+    ) => {
+      const f32 = new Float32Array(20);
+      setUniforms(f32);
+      uniformState.uploads.push([...f32]);
+    },
+  ),
+}));
+const pipelineMock = vi.hoisted(() => ({
+  getWgpuEffectPipeline: vi.fn((_state: unknown, _key: string, _wgsl: string, _blend: string) => ({ pipeline: {} })),
+}));
+const uniformState = vi.hoisted(() => ({ uploads: [] as number[][] }));
+
+vi.mock('./wgpuEffectPass', () => passMock);
+vi.mock('./wgpuEffectProgramCache', () => pipelineMock);
+
 import { applyColorMatrixPassToWgpu } from './wgpuColorMatrixPass';
 
+function packed(matrix: ReadonlyArray<number>): readonly number[] {
+  uniformState.uploads.length = 0;
+  pipelineMock.getWgpuEffectPipeline.mockClear();
+  const target = {} as unknown as WgpuRenderTarget;
+  applyColorMatrixPassToWgpu({} as unknown as WgpuRenderState, target, target, matrix);
+  return uniformState.uploads[0]!;
+}
+
 describe('applyColorMatrixPassToWgpu', () => {
-  it('is a function', () => {
-    expect(typeof applyColorMatrixPassToWgpu).toBe('function');
+  // ★ WHY THIS FILE IS WORTH MORE THAN ONE EFFECT'S. It is the SINGLE realization for the whole
+  // matrix-tier Adjustment family on this backend — invert, grayscale, sepia, saturation, hue rotate,
+  // scale/bias all fuse into one 4×5 matrix and arrive here. A packing error is wrong colour in every one
+  // of them, and it produces a plausible colour rather than an error.
+  //
+  // ★ THIS BACKEND REPACKS AND THE OTHER DOES NOT, WHICH IS THE WHOLE HAZARD. Gl uploads the caller's
+  // twenty floats verbatim; WGSL wants four vec4f coefficient ROWS with the bias column moved to a fifth
+  // vec4f, so this runner permutes 20 indices by hand. Twenty hand-written assignments is precisely the
+  // shape where one transposed pair survives review, and nothing downstream would report it.
+  //
+  // ★ NO HISTORICAL DEFECT EXISTS FOR THIS FILE, so the cases are CONSTRUCTED, not restored: its history
+  // holds the feature commit, an API rename, a type move and the lane refactor. Branch-2 shape.
+  //
+  // MEASURED by swapping the red row's alpha coefficient with its bias (f32[3] <-> f32[16]) — 2 of 6:
+  //   AssertionError: expected [ 1, 2, 3, 5, 6, 7, 8, 9, 11, …(11) ] to deeply equal [ 1, 2, 3, 4, 6, 7, 8, 9, 11, …(11) ]
+  //   AssertionError: expected 5 to be 4 // Object.is equality
+  it('packs the four coefficient rows first and the bias column last', () => {
+    // Twenty distinct values, so every slot names exactly one source index and a swap cannot hide.
+    const distinct = Array.from({ length: 20 }, (_, index) => index + 1);
+
+    expect(packed(distinct)).toEqual([
+      // rows R, G, B, A — the RGBA coefficients of each, with each row's bias skipped
+      1, 2, 3, 4, 6, 7, 8, 9, 11, 12, 13, 14, 16, 17, 18, 19,
+      // the bias column, gathered from indices 4, 9, 14, 19
+      5, 10, 15, 20,
+    ]);
+  });
+
+  // Stated separately from the packing above because it is the claim a reader actually needs: the
+  // caller's 4×5 row-major matrix means the same thing on both backends, and only the transport differs.
+  it('keeps each row bias with its own row, not with the row after it', () => {
+    const distinct = Array.from({ length: 20 }, (_, index) => index + 1);
+    const uploaded = packed(distinct);
+
+    // Red's bias is the caller's index 4, and red's alpha coefficient is index 3 — the pair a one-off
+    // permutation swaps.
+    expect(uploaded[3]).toBe(distinct[3]);
+    expect(uploaded[16]).toBe(distinct[4]);
+    expect(uploaded[19]).toBe(distinct[19]);
+  });
+
+  it('leaves an identity matrix as an identity packing', () => {
+    expect(packed(IDENTITY)).toEqual([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0]);
+  });
+
+  // A caller handing over a 4×4 (sixteen entries) is the realistic mistake, and every missing slot must
+  // read as zero rather than as `undefined` written into a Float32Array — which would be NaN, and NaN
+  // through a colour matrix is a transparent black frame.
+  it('zero-fills a matrix shorter than twenty', () => {
+    const uploaded = packed([1, 0, 0, 0]);
+
+    expect(uploaded.every(Number.isFinite)).toBe(true);
+    expect(uploaded.slice(4)).toEqual(new Array(16).fill(0));
+  });
+
+  it('ignores coefficients past the twentieth', () => {
+    expect(packed([...IDENTITY, 99, 98])).toEqual(packed(IDENTITY));
+  });
+
+  it('compiles one pipeline for every matrix, in replace blend', () => {
+    packed(IDENTITY);
+
+    const call = pipelineMock.getWgpuEffectPipeline.mock.calls[0]!;
+    expect(call[1]).toBe('adjustment.colorMatrix');
+    expect(call[3]).toBe('replace');
   });
 });
+
+const IDENTITY = [1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0];