@flighthq/bitmap 0.3.0-edge.1458.0c01b63

package/src/bitmapBlur.test.ts

@@ -0,0 +1,234 @@
+import { createBitmap } from './bitmap';
+import {
+  blurBitmapPixelsHorizontal,
+  blurBitmapPixelsHorizontalWeighted,
+  blurBitmapPixelsVertical,
+  blurBitmapPixelsVerticalWeighted,
+  boxBlurBitmap,
+  computeGaussianKernel,
+  gaussianBlurBitmap,
+} from './bitmapBlur';
+import { premultiplyBitmapPixels, unpremultiplyBitmapPixels } from './bitmapFormat';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('blurBitmapPixelsHorizontal', () => {
+  it('spreads alpha into horizontal neighbors', () => {
+    const source = new Uint8ClampedArray([0, 0, 0, 0, 0, 0, 0, 255, 0, 0, 0, 0]);
+    const out = new Uint8ClampedArray(12);
+    blurBitmapPixelsHorizontal(out, source, 3, 1, 1);
+    expect(out[3]).toBeGreaterThan(0);
+    expect(out[11]).toBeGreaterThan(0);
+  });
+
+  it('copies source to out without spreading when radius is 0', () => {
+    const source = new Uint8ClampedArray([0, 0, 0, 255, 0, 0, 0, 0]);
+    const out = new Uint8ClampedArray(8);
+    blurBitmapPixelsHorizontal(out, source, 2, 1, 0);
+    expect(out[3]).toBe(255);
+    expect(out[7]).toBe(0);
+  });
+
+  it('premultiplying before blur avoids the dark-halo artifact at transparent edges', () => {
+    // [opaque red, transparent]. Straight-alpha blur bleeds the transparent
+    // pixel's hidden black into the red; a premultiplied blur keeps it pure red.
+    const buf = new Uint8ClampedArray([255, 0, 0, 255, 0, 0, 0, 0]);
+
+    const straight = new Uint8ClampedArray(8);
+    blurBitmapPixelsHorizontal(straight, buf, 2, 1, 1);
+    expect(straight[4]).toBe(128); // transparent pixel's red darkened toward black
+
+    const premul = new Uint8ClampedArray(8);
+    premultiplyBitmapPixels(premul, buf, 8);
+    const blurred = new Uint8ClampedArray(8);
+    blurBitmapPixelsHorizontal(blurred, premul, 2, 1, 1);
+    const result = new Uint8ClampedArray(8);
+    unpremultiplyBitmapPixels(result, blurred, 8);
+    expect(result[4]).toBe(255); // red stays pure
+    expect(result[7]).toBe(128); // alpha still half
+  });
+
+  it('produces correct edge average for a single row', () => {
+    // pixels: [0, 255, 0] alpha only; radius=1
+    // x=0: avg([0,255])/2 = 128 (approx); x=1: avg([0,255,0])/3 = 85; x=2: avg([255,0])/2 = 128
+    const source = new Uint8ClampedArray([0, 0, 0, 0, 0, 0, 0, 255, 0, 0, 0, 0]);
+    const out = new Uint8ClampedArray(12);
+    blurBitmapPixelsHorizontal(out, source, 3, 1, 1);
+    expect(out[3]).toBe(128); // (0+255)/2
+    expect(out[7]).toBe(85); // (0+255+0)/3
+    expect(out[11]).toBe(128); // (255+0)/2
+  });
+});
+
+describe('blurBitmapPixelsHorizontalWeighted', () => {
+  it('applies Gaussian weights to horizontal neighbors', () => {
+    const kernel = new Float32Array(3);
+    computeGaussianKernel(kernel, 1, 0.8);
+    const source = new Uint8ClampedArray([0, 0, 0, 0, 0, 0, 0, 255, 0, 0, 0, 0]);
+    const out = new Uint8ClampedArray(12);
+    blurBitmapPixelsHorizontalWeighted(out, source, 3, 1, kernel);
+    // center weight >> edge; center alpha should be highest
+    expect(out[7]).toBeGreaterThan(out[3]);
+    expect(out[7]).toBeGreaterThan(out[11]);
+  });
+
+  it('with an identity kernel [1] leaves source unchanged', () => {
+    const kernel = new Float32Array([1]);
+    const source = new Uint8ClampedArray([0x11, 0x22, 0x33, 0xff]);
+    const out = new Uint8ClampedArray(4);
+    blurBitmapPixelsHorizontalWeighted(out, source, 1, 1, kernel);
+    expect(out[0]).toBe(0x11);
+    expect(out[3]).toBe(0xff);
+  });
+});
+
+describe('blurBitmapPixelsVertical', () => {
+  it('spreads alpha into vertical neighbors', () => {
+    const source = new Uint8ClampedArray([0, 0, 0, 0, 0, 0, 0, 255, 0, 0, 0, 0]);
+    const out = new Uint8ClampedArray(12);
+    blurBitmapPixelsVertical(out, source, 1, 3, 1);
+    expect(out[3]).toBeGreaterThan(0);
+    expect(out[11]).toBeGreaterThan(0);
+  });
+});
+
+describe('blurBitmapPixelsVerticalWeighted', () => {
+  it('applies Gaussian weights to vertical neighbors', () => {
+    const kernel = new Float32Array(3);
+    computeGaussianKernel(kernel, 1, 0.8);
+    const source = new Uint8ClampedArray([0, 0, 0, 0, 0, 0, 0, 255, 0, 0, 0, 0]);
+    const out = new Uint8ClampedArray(12);
+    blurBitmapPixelsVerticalWeighted(out, source, 1, 3, kernel);
+    expect(out[7]).toBeGreaterThan(out[3]);
+  });
+});
+
+describe('boxBlurBitmap', () => {
+  it('spreads alpha into neighboring pixels', () => {
+    const source = createBitmap(3, 1);
+    source.data[7] = 255; // center pixel opaque
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    boxBlurBitmap(out, scratch, region(source), { radiusX: 2, radiusY: 0 });
+    expect(out[3]).toBeGreaterThan(0);
+    expect(out[11]).toBeGreaterThan(0);
+  });
+
+  it('writes source into out when blur is zero', () => {
+    const source = createBitmap(1, 1, 0x336699ff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    boxBlurBitmap(out, scratch, region(source), { radiusX: 0, radiusY: 0 });
+    expect(out[0]).toBe(0x33);
+    expect(out[3]).toBe(0xff);
+  });
+
+  it('result always lands in out regardless of pass parity', () => {
+    const source = createBitmap(3, 3, 0xffffff88);
+    const out = new Uint8ClampedArray(3 * 3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 3 * 4);
+    boxBlurBitmap(out, scratch, region(source), { radiusX: 2, radiusY: 0 });
+    expect(out[3]).toBeGreaterThan(0);
+  });
+
+  it('source.bitmap.data can be used as out for a full-bitmap region', () => {
+    const bitmap = createBitmap(3, 1);
+    bitmap.data[7] = 255;
+    const scratch = new Uint8ClampedArray(3 * 4);
+    boxBlurBitmap(bitmap.data, scratch, region(bitmap), { radiusX: 2, radiusY: 0 });
+    expect(bitmap.data[3]).toBeGreaterThan(0);
+    expect(bitmap.data[11]).toBeGreaterThan(0);
+  });
+
+  it('blurs only the offset sub-region, reading from the right source pixels', () => {
+    // 4 px alpha: [_, 255, 100, _]. Blurring region (1,0,2,1) extracts [255,100]
+    // and averages them — proving the source x-offset is honored, not ignored.
+    const bitmap = createBitmap(4, 1);
+    bitmap.data[1 * 4 + 3] = 255;
+    bitmap.data[2 * 4 + 3] = 100;
+    const out = new Uint8ClampedArray(2 * 4);
+    const scratch = new Uint8ClampedArray(2 * 4);
+    boxBlurBitmap(out, scratch, region(bitmap, 1, 0, 2, 1), { radiusX: 2, radiusY: 0 });
+    expect(out[3]).toBe(178); // round((255 + 100) / 2)
+    expect(out[7]).toBe(178);
+  });
+});
+
+describe('computeGaussianKernel', () => {
+  it('produces a kernel that sums to 1', () => {
+    const kernel = new Float32Array(7);
+    computeGaussianKernel(kernel, 3, 1.0);
+    const sum = kernel.reduce((acc, v) => acc + v, 0);
+    expect(sum).toBeCloseTo(1, 5);
+  });
+
+  it('is symmetric', () => {
+    const kernel = new Float32Array(9);
+    computeGaussianKernel(kernel, 4, 1.5);
+    for (let i = 0; i < 4; i++) {
+      expect(kernel[i]).toBeCloseTo(kernel[8 - i], 10);
+    }
+  });
+
+  it('center weight is the largest', () => {
+    const kernel = new Float32Array(5);
+    computeGaussianKernel(kernel, 2, 1.0);
+    expect(kernel[2]).toBeGreaterThan(kernel[1]);
+    expect(kernel[1]).toBeGreaterThan(kernel[0]);
+  });
+
+  it('radius-0 kernel produces a single weight of 1', () => {
+    const kernel = new Float32Array(1);
+    computeGaussianKernel(kernel, 0, 1.0);
+    expect(kernel[0]).toBeCloseTo(1, 10);
+  });
+
+  it('sigma <= 0 produces a unit impulse rather than a NaN kernel', () => {
+    const kernel = new Float32Array(5).fill(9);
+    computeGaussianKernel(kernel, 2, 0);
+    expect(kernel[2]).toBe(1);
+    expect(kernel[0]).toBe(0);
+    expect(kernel[4]).toBe(0);
+    expect(kernel.every((v) => !Number.isNaN(v))).toBe(true);
+  });
+});
+
+describe('gaussianBlurBitmap', () => {
+  it('spreads alpha into neighboring pixels', () => {
+    const source = createBitmap(5, 1);
+    source.data[2 * 4 + 3] = 255; // center pixel opaque
+    const out = new Uint8ClampedArray(5 * 4);
+    const scratch = new Uint8ClampedArray(5 * 4);
+    gaussianBlurBitmap(out, scratch, region(source), 1.0);
+    expect(out[3]).toBeGreaterThan(0);
+    expect(out[4 * 4 + 3]).toBeGreaterThan(0);
+  });
+
+  it('center pixel retains more weight than edges', () => {
+    const source = createBitmap(5, 1);
+    source.data[2 * 4 + 3] = 255;
+    const out = new Uint8ClampedArray(5 * 4);
+    const scratch = new Uint8ClampedArray(5 * 4);
+    gaussianBlurBitmap(out, scratch, region(source), 0.8);
+    expect(out[2 * 4 + 3]).toBeGreaterThan(out[3]);
+  });
+
+  it('with sigma=0 writes source unchanged', () => {
+    const source = createBitmap(1, 1, 0x336699ff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    gaussianBlurBitmap(out, scratch, region(source), 0);
+    expect(out[0]).toBe(0x33);
+    expect(out[3]).toBe(0xff);
+  });
+
+  it('result always lands in out regardless of pass parity', () => {
+    const source = createBitmap(3, 3, 0xffffff88);
+    const out = new Uint8ClampedArray(3 * 3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 3 * 4);
+    gaussianBlurBitmap(out, scratch, region(source), 1.0);
+    expect(out[3]).toBeGreaterThan(0);
+  });
+});

package/src/bitmapChannel.test.ts

@@ -0,0 +1,97 @@
+import { createBitmap } from './bitmap';
+import { mergeBitmapChannels, splitBitmapChannels } from './bitmapChannel';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { createBitmapRegion } from './bitmapRegion';
+
+describe('mergeBitmapChannels', () => {
+  it('combines one channel from each input into the output', () => {
+    const rSurf = createBitmap(1, 1, 0xff000000); // R=0xff, G=0, B=0, A=0
+    const gSurf = createBitmap(1, 1, 0x00ff0000); // R=0, G=0xff, B=0, A=0
+    const bSurf = createBitmap(1, 1, 0x0000ff00); // R=0, G=0, B=0xff, A=0
+    const aSurf = createBitmap(1, 1, 0x000000ff); // R=0, G=0, B=0, A=0xff
+    const out = createBitmap(1, 1);
+    mergeBitmapChannels(
+      createBitmapRegion(out),
+      createBitmapRegion(rSurf),
+      createBitmapRegion(gSurf),
+      createBitmapRegion(bSurf),
+      createBitmapRegion(aSurf),
+    );
+    expect(getBitmapPixel(out, 0, 0)).toBe(0xff_ff_ff_ff);
+  });
+
+  it('uses the minimum dimension overlap', () => {
+    const r = createBitmap(3, 1, 0xff000000);
+    const g = createBitmap(3, 1, 0x00ff0000);
+    const b = createBitmap(3, 1, 0x0000ff00);
+    const a = createBitmap(3, 1, 0x000000ff);
+    const out = createBitmap(3, 1);
+    // Restrict r region to width=1 — only pixel 0 should be written.
+    mergeBitmapChannels(
+      createBitmapRegion(out),
+      { bitmap: r, x: 0, y: 0, width: 1, height: 1 },
+      createBitmapRegion(g),
+      createBitmapRegion(b),
+      createBitmapRegion(a),
+    );
+    // Pixel 0 is covered; pixel 1 should be untouched (0x00000000).
+    expect((getBitmapPixel(out, 0, 0) >>> 24) & 0xff).toBe(0xff);
+    expect(getBitmapPixel(out, 1, 0)).toBe(0x00000000);
+  });
+});
+
+describe('splitBitmapChannels', () => {
+  it('returns four bitmaps of the same dimensions', () => {
+    const src = createBitmap(3, 2, 0x112233ff);
+    const [r, g, b, a] = splitBitmapChannels(src);
+    expect(r.width).toBe(3);
+    expect(r.height).toBe(2);
+    expect(g.width).toBe(3);
+    expect(b.height).toBe(2);
+    expect(a.width).toBe(3);
+  });
+
+  it('each channel bitmap is a grayscale copy of that channel', () => {
+    const src = createBitmap(1, 1);
+    setBitmapPixel(src, 0, 0, 0x11_22_33_44);
+    const [r, g, b, a] = splitBitmapChannels(src);
+    // R bitmap: R=G=B=0x11, A=0xff.
+    expect((getBitmapPixel(r, 0, 0) >>> 24) & 0xff).toBe(0x11);
+    expect((getBitmapPixel(r, 0, 0) >> 16) & 0xff).toBe(0x11);
+    expect((getBitmapPixel(r, 0, 0) >> 8) & 0xff).toBe(0x11);
+    expect(getBitmapPixel(r, 0, 0) & 0xff).toBe(0xff);
+    // G bitmap: R=G=B=0x22, A=0xff.
+    expect((getBitmapPixel(g, 0, 0) >>> 24) & 0xff).toBe(0x22);
+    // B bitmap: R=G=B=0x33, A=0xff.
+    expect((getBitmapPixel(b, 0, 0) >>> 24) & 0xff).toBe(0x33);
+    // A bitmap: R=G=B=A=0x44 (alpha stored in all channels for round-trip fidelity).
+    expect((getBitmapPixel(a, 0, 0) >>> 24) & 0xff).toBe(0x44);
+    expect(getBitmapPixel(a, 0, 0) & 0xff).toBe(0x44);
+  });
+
+  it('returns distinct bitmap objects', () => {
+    const src = createBitmap(2, 2, 0xffffffff);
+    const [r, g, b, a] = splitBitmapChannels(src);
+    expect(r).not.toBe(src);
+    expect(r).not.toBe(g);
+    expect(g).not.toBe(b);
+    expect(b).not.toBe(a);
+  });
+
+  it('round-trip: split then merge reconstructs the original', () => {
+    const src = createBitmap(2, 2);
+    setBitmapPixel(src, 0, 0, 0xaabbccdd);
+    setBitmapPixel(src, 1, 0, 0x11223344);
+    const [r, g, b, a] = splitBitmapChannels(src);
+    const out = createBitmap(2, 2);
+    mergeBitmapChannels(
+      createBitmapRegion(out),
+      createBitmapRegion(r),
+      createBitmapRegion(g),
+      createBitmapRegion(b),
+      createBitmapRegion(a),
+    );
+    expect(getBitmapPixel(out, 0, 0)).toBe(0xaabbccdd);
+    expect(getBitmapPixel(out, 1, 0)).toBe(0x11223344);
+  });
+});

package/src/bitmapColorMatrix.test.ts

@@ -0,0 +1,214 @@
+import { createBitmap } from './bitmap';
+import {
+  buildBitmapBrightnessColorMatrix,
+  buildBitmapContrastColorMatrix,
+  buildBitmapGrayscaleColorMatrix,
+  buildBitmapHueRotationColorMatrix,
+  buildBitmapInvertColorMatrix,
+  buildBitmapSaturationColorMatrix,
+  buildBitmapSepiaColorMatrix,
+  colorMatrixBitmap,
+  concatBitmapColorMatrix,
+  setBitmapColorMatrixIdentity,
+} from './bitmapColorMatrix';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+// Build a 1x1 bitmap, apply `matrix`, and return its RGBA bytes.
+function applyTo(rgba: number, matrix: ReadonlyArray<number>): Uint8ClampedArray {
+  const bitmap = createBitmap(1, 1, rgba);
+  const out = new Uint8ClampedArray(4);
+  colorMatrixBitmap(out, region(bitmap), matrix);
+  return out;
+}
+
+describe('buildBitmapBrightnessColorMatrix', () => {
+  it('multiplies RGB by the amount', () => {
+    const m = new Array<number>(20);
+    buildBitmapBrightnessColorMatrix(m, 0.5);
+    const out = applyTo(0xc86432ff, m); // R=200 G=100 B=50
+    expect(out[0]).toBe(100);
+    expect(out[1]).toBe(50);
+    expect(out[2]).toBe(25);
+    expect(out[3]).toBe(0xff);
+  });
+});
+
+describe('buildBitmapContrastColorMatrix', () => {
+  it('amount 0 flattens every channel to mid grey', () => {
+    const m = new Array<number>(20);
+    buildBitmapContrastColorMatrix(m, 0);
+    const out = applyTo(0xc80000ff, m); // R=200
+    expect(out[0]).toBe(128); // round(127.5)
+    expect(out[1]).toBe(128);
+  });
+});
+
+describe('buildBitmapGrayscaleColorMatrix', () => {
+  it('maps pure red to its luma in every channel', () => {
+    const m = new Array<number>(20);
+    buildBitmapGrayscaleColorMatrix(m);
+    const out = applyTo(0xff0000ff, m);
+    expect(out[0]).toBe(54); // round(0.213 * 255)
+    expect(out[1]).toBe(54);
+    expect(out[2]).toBe(54);
+  });
+});
+
+describe('buildBitmapHueRotationColorMatrix', () => {
+  it('leaves grey unchanged at any angle (rotation around the luma axis)', () => {
+    const m = new Array<number>(20);
+    // 70.7° ≈ 1.234 radians — same geometric rotation, now expressed in degrees
+    buildBitmapHueRotationColorMatrix(m, 70.7);
+    const out = applyTo(0x808080ff, m);
+    expect(out[0]).toBe(128);
+    expect(out[1]).toBe(128);
+    expect(out[2]).toBe(128);
+  });
+
+  it('is identity at 0 degrees', () => {
+    const m = new Array<number>(20);
+    buildBitmapHueRotationColorMatrix(m, 0);
+    const out = applyTo(0xc86432ff, m);
+    expect(out[0]).toBe(200);
+    expect(out[1]).toBe(100);
+    expect(out[2]).toBe(50);
+  });
+
+  it('is identity at 360 degrees', () => {
+    const m = new Array<number>(20);
+    buildBitmapHueRotationColorMatrix(m, 360);
+    const out = applyTo(0xc86432ff, m);
+    expect(out[0]).toBeCloseTo(200, 0);
+    expect(out[1]).toBeCloseTo(100, 0);
+    expect(out[2]).toBeCloseTo(50, 0);
+  });
+});
+
+describe('buildBitmapInvertColorMatrix', () => {
+  it('inverts RGB and preserves alpha', () => {
+    const m = new Array<number>(20);
+    buildBitmapInvertColorMatrix(m);
+    const out = applyTo(0xc83200ff, m); // R=200 G=50 B=0
+    expect(out[0]).toBe(55);
+    expect(out[1]).toBe(205);
+    expect(out[2]).toBe(255);
+    expect(out[3]).toBe(0xff);
+  });
+});
+
+describe('buildBitmapSaturationColorMatrix', () => {
+  it('amount 1 is identity', () => {
+    const m = new Array<number>(20);
+    buildBitmapSaturationColorMatrix(m, 1);
+    const out = applyTo(0xc86432ff, m);
+    expect(out[0]).toBe(200);
+    expect(out[1]).toBe(100);
+    expect(out[2]).toBe(50);
+  });
+
+  it('amount 0 equals grayscale', () => {
+    const m = new Array<number>(20);
+    buildBitmapSaturationColorMatrix(m, 0);
+    const out = applyTo(0xff0000ff, m);
+    expect(out[0]).toBe(54);
+    expect(out[1]).toBe(54);
+  });
+});
+
+describe('buildBitmapSepiaColorMatrix', () => {
+  it('maps pure red to the sepia tone', () => {
+    const m = new Array<number>(20);
+    buildBitmapSepiaColorMatrix(m);
+    const out = applyTo(0xff0000ff, m);
+    expect(out[0]).toBe(100); // round(0.393 * 255)
+    expect(out[1]).toBe(89); // round(0.349 * 255)
+    expect(out[2]).toBe(69); // round(0.272 * 255)
+  });
+});
+
+describe('colorMatrixBitmap', () => {
+  it('applies a 4x5 color matrix to the source region', () => {
+    const source = createBitmap(1, 1, 0x204060ff);
+    const out = new Uint8ClampedArray(4);
+    colorMatrixBitmap(out, region(source), [0, 0, 0, 0, 10, 0, 0, 0, 0, 20, 0, 0, 0, 0, 30, 0, 0, 0, 1, 0]);
+    expect(out[0]).toBe(10);
+    expect(out[1]).toBe(20);
+    expect(out[2]).toBe(30);
+    expect(out[3]).toBe(0xff);
+  });
+
+  it('is safe when out aliases source.bitmap.data for a full-bitmap region', () => {
+    const bitmap = createBitmap(1, 1, 0x010203ff);
+    colorMatrixBitmap(bitmap.data, region(bitmap), [1, 0, 0, 0, 10, 0, 1, 0, 0, 20, 0, 0, 1, 0, 30, 0, 0, 0, 1, 0]);
+    expect(bitmap.data[0]).toBe(11);
+    expect(bitmap.data[1]).toBe(22);
+    expect(bitmap.data[2]).toBe(33);
+    expect(bitmap.data[3]).toBe(0xff);
+  });
+
+  it('clamps output to [0, 255]', () => {
+    const source = createBitmap(1, 1, 0xff0000ff);
+    const out = new Uint8ClampedArray(4);
+    colorMatrixBitmap(out, region(source), [10, 0, 0, 0, 100, 0, 0, 0, 0, -50, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0]);
+    expect(out[0]).toBe(255);
+    expect(out[1]).toBe(0);
+  });
+
+  it('throws when the matrix is too short', () => {
+    const source = createBitmap(1, 1);
+    const out = new Uint8ClampedArray(4);
+    expect(() => colorMatrixBitmap(out, region(source), [])).toThrow('Color matrix filter requires 20 values');
+  });
+
+  it('silently skips pixels outside source bounds', () => {
+    const source = createBitmap(1, 1, 0xff0000ff);
+    const out = new Uint8ClampedArray(4 * 4);
+    const identity = [1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0];
+    colorMatrixBitmap(out, region(source, -1, -1, 2, 2), identity);
+    // only bottom-right pixel of the 2x2 region is in-bounds
+    const i = (1 * 2 + 1) * 4;
+    expect(out[i]).toBe(0xff);
+    expect(out[0]).toBe(0);
+  });
+});
+
+describe('concatBitmapColorMatrix', () => {
+  it('composes two matrices (apply first, then second)', () => {
+    const bright2 = new Array<number>(20);
+    const half = new Array<number>(20);
+    buildBitmapBrightnessColorMatrix(bright2, 2);
+    buildBitmapBrightnessColorMatrix(half, 0.5);
+    const out = new Array<number>(20);
+    concatBitmapColorMatrix(out, bright2, half); // *2 then *0.5 = identity
+    const pixel = applyTo(0xc86432ff, out);
+    expect(pixel[0]).toBe(200);
+    expect(pixel[1]).toBe(100);
+    expect(pixel[2]).toBe(50);
+  });
+
+  it('carries the offset through composition', () => {
+    const identity = new Array<number>(20);
+    const invert = new Array<number>(20);
+    setBitmapColorMatrixIdentity(identity);
+    buildBitmapInvertColorMatrix(invert);
+    const out = new Array<number>(20);
+    concatBitmapColorMatrix(out, identity, invert);
+    const pixel = applyTo(0xc80000ff, out); // R=200 -> 55
+    expect(pixel[0]).toBe(55);
+  });
+});
+
+describe('setBitmapColorMatrixIdentity', () => {
+  it('leaves the pixel unchanged', () => {
+    const m = new Array<number>(20);
+    setBitmapColorMatrixIdentity(m);
+    const out = applyTo(0xc86432ff, m);
+    expect(out[0]).toBe(200);
+    expect(out[1]).toBe(100);
+    expect(out[2]).toBe(50);
+    expect(out[3]).toBe(0xff);
+  });
+});

package/src/bitmapCompare.test.ts

@@ -0,0 +1,92 @@
+import type { Bitmap } from '@flighthq/types/contract';
+
+import { cloneBitmap, createBitmap } from './bitmap';
+import { compareBitmap, getBitmapMismatch } from './bitmapCompare';
+import { setBitmapPixel } from './bitmapPixel';
+
+describe('compareBitmap', () => {
+  it('throws when widths differ', () => {
+    const a = createBitmap(4, 4);
+    const b = createBitmap(8, 4);
+    expect(() => compareBitmap(a, b)).toThrow();
+  });
+
+  it('throws when heights differ', () => {
+    const a = createBitmap(4, 4);
+    const b = createBitmap(4, 8);
+    expect(() => compareBitmap(a, b)).toThrow();
+  });
+
+  it('returns null for identical images', () => {
+    const a = createBitmap(4, 4, 0x0000ffff);
+    const b = cloneBitmap(a);
+    expect(compareBitmap(a, b)).toBeNull();
+  });
+
+  it('returns diff Bitmap for different pixels', () => {
+    const a = createBitmap(2, 1, 0x000000ff);
+    const b = createBitmap(2, 1, 0x000000ff);
+    setBitmapPixel(b, 0, 0, 0x102030ff);
+    const result = compareBitmap(a, b) as Bitmap;
+    expect(result.width).toBe(2);
+    expect(result.height).toBe(1);
+    expect(result.data[0]).toBe(0x10);
+    expect(result.data[1]).toBe(0x20);
+    expect(result.data[2]).toBe(0x30);
+    expect(result.data[3]).toBe(255);
+    expect(result.data[4]).toBe(0);
+    expect(result.data[5]).toBe(0);
+    expect(result.data[6]).toBe(0);
+    expect(result.data[7]).toBe(0);
+  });
+
+  it('diff pixel alpha is 255 when any channel differs', () => {
+    const a = createBitmap(1, 1, 0x000000ff);
+    const b = createBitmap(1, 1, 0x00000080);
+    const result = compareBitmap(a, b) as Bitmap;
+    expect(result.data[3]).toBe(255);
+  });
+
+  it('unchanged pixels in diff have zero alpha', () => {
+    const a = createBitmap(2, 1, 0x000000ff);
+    const b = cloneBitmap(a);
+    setBitmapPixel(b, 1, 0, 0xff0000ff);
+    const result = compareBitmap(a, b) as Bitmap;
+    expect(result.data[3]).toBe(0);
+    expect(result.data[7]).toBe(255);
+  });
+});
+
+describe('getBitmapMismatch', () => {
+  it('throws when dimensions differ', () => {
+    expect(() => getBitmapMismatch(createBitmap(4, 4), createBitmap(4, 8))).toThrow();
+  });
+
+  it('reports zero mismatch for identical bitmaps', () => {
+    const a = createBitmap(4, 4, 0x0000ffff);
+    const result = getBitmapMismatch(a, cloneBitmap(a));
+    expect(result.mismatchedPixels).toBe(0);
+    expect(result.totalPixels).toBe(16);
+    expect(result.fraction).toBe(0);
+    expect(result.maxChannelDelta).toBe(0);
+  });
+
+  it('counts pixels whose max channel delta exceeds the tolerance', () => {
+    const a = createBitmap(2, 1, 0x000000ff);
+    const b = createBitmap(2, 1, 0x000000ff);
+    setBitmapPixel(b, 0, 0, 0x0a0000ff); // delta 10 on one channel
+    expect(getBitmapMismatch(a, b, 0).mismatchedPixels).toBe(1);
+    expect(getBitmapMismatch(a, b, 9).mismatchedPixels).toBe(1);
+    expect(getBitmapMismatch(a, b, 10).mismatchedPixels).toBe(0); // within tolerance
+  });
+
+  it('reports the largest channel delta and the mismatch fraction', () => {
+    const a = createBitmap(2, 1, 0x000000ff);
+    const b = createBitmap(2, 1, 0x000000ff);
+    setBitmapPixel(b, 1, 0, 0x804020ff); // max delta 0x80 = 128
+    const result = getBitmapMismatch(a, b);
+    expect(result.maxChannelDelta).toBe(128);
+    expect(result.mismatchedPixels).toBe(1);
+    expect(result.fraction).toBe(0.5);
+  });
+});