@flighthq/bitmap 0.3.0-next.1021.f5f1ee0

package/src/bitmapConvolution.test.ts

@@ -0,0 +1,130 @@
+import { createBitmap } from './bitmap';
+import { convolveBitmap } from './bitmapConvolution';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('convolveBitmap', () => {
+  it('applies a convolution matrix to the source region', () => {
+    const source = createBitmap(3, 1);
+    source.data[0] = 10;
+    source.data[4] = 20;
+    source.data[8] = 30;
+    const out = new Uint8ClampedArray(4);
+    convolveBitmap(out, region(source, 1, 0, 1, 1), {
+      matrix: [1, 1, 1],
+      matrixX: 3,
+      matrixY: 1,
+      preserveAlpha: false,
+    });
+    expect(out[0]).toBe(20);
+  });
+
+  it("'clamp' edge mode (default) repeats the nearest edge pixel", () => {
+    // 1px source, 3-wide kernel: all three samples hit the single source pixel
+    const source = createBitmap(1, 1, 0x606060ff);
+    const out = new Uint8ClampedArray(4);
+    convolveBitmap(out, region(source), {
+      matrix: [1, 1, 1],
+      matrixX: 3,
+      matrixY: 1,
+      divisor: 3,
+      preserveAlpha: false,
+    });
+    expect(out[0]).toBe(0x60);
+  });
+
+  it("'mirror' edge mode reflects at boundaries", () => {
+    // 3px source [10, 20, 30]. 5-wide kernel [1, 0, 0, 0, 0] picks 2 positions left.
+    // For px=0, offsetX=2: rawSampleX = 0 + 0 + 0 - 2 = -2.
+    // mirror(-2, 3) reflects to x=1 (value 20), while clamp(-2) gives x=0 (value 10).
+    const source = createBitmap(3, 1);
+    source.data[0] = 10;
+    source.data[4] = 20;
+    source.data[8] = 30;
+    const out = new Uint8ClampedArray(3 * 4);
+    convolveBitmap(out, region(source), {
+      edge: 'mirror',
+      matrix: [1, 0, 0, 0, 0],
+      matrixX: 5,
+      matrixY: 1,
+      divisor: 1,
+      preserveAlpha: false,
+    });
+    expect(out[0]).toBe(20);
+  });
+
+  it("'transparent' edge mode treats out-of-bounds as transparent black", () => {
+    // 1px source (opaque black), 3-wide kernel [1, 0, 0] — leftmost sample
+    // is out of bounds and contributes transparent black (all zeros).
+    const source = createBitmap(1, 1, 0x000000ff);
+    const out = new Uint8ClampedArray(4);
+    convolveBitmap(out, region(source), {
+      edge: 'transparent',
+      divisor: 1,
+      matrix: [1, 0, 0],
+      matrixX: 3,
+      matrixY: 1,
+      preserveAlpha: false,
+    });
+    expect(out[0]).toBe(0);
+    expect(out[3]).toBe(0);
+  });
+
+  it("'wrap' edge mode tiles the source toroidally", () => {
+    // 3px source [10, 20, 30]. The leftmost kernel position for px=0 wraps to px=2.
+    const source = createBitmap(3, 1);
+    source.data[0] = 10;
+    source.data[4] = 20;
+    source.data[8] = 30;
+    const out = new Uint8ClampedArray(3 * 4);
+    convolveBitmap(out, region(source), {
+      edge: 'wrap',
+      matrix: [1, 0, 0], // picks left neighbor only
+      matrixX: 3,
+      matrixY: 1,
+      divisor: 1,
+      preserveAlpha: false,
+    });
+    // px=0 left neighbor wraps to px=2 → value 30
+    expect(out[0]).toBe(30);
+  });
+
+  it('preserves source alpha by default', () => {
+    const source = createBitmap(1, 1, 0x00000044);
+    const out = new Uint8ClampedArray(4);
+    convolveBitmap(out, region(source), {
+      bias: 255,
+      matrix: [1],
+      matrixX: 1,
+      matrixY: 1,
+    });
+    expect(out[3]).toBe(0x44);
+  });
+
+  it('throws when matrix dimensions are not positive', () => {
+    const source = createBitmap(1, 1);
+    const out = new Uint8ClampedArray(4);
+    expect(() => convolveBitmap(out, region(source), { matrix: [], matrixX: 0, matrixY: 1 })).toThrow();
+  });
+
+  it('throws when matrix is too short for its declared dimensions', () => {
+    const source = createBitmap(1, 1);
+    const out = new Uint8ClampedArray(4);
+    expect(() => convolveBitmap(out, region(source), { matrix: [1], matrixX: 3, matrixY: 3 })).toThrow();
+  });
+
+  it('treats an explicit divisor of 0 as passthrough (no division by zero)', () => {
+    const source = createBitmap(1, 1, 0x804020ff);
+    const out = new Uint8ClampedArray(4);
+    convolveBitmap(out, region(source), {
+      divisor: 0,
+      matrix: [1],
+      matrixX: 1,
+      matrixY: 1,
+      preserveAlpha: false,
+    });
+    expect(out[0]).toBe(0x80);
+  });
+});

package/src/bitmapCopy.test.ts

@@ -0,0 +1,48 @@
+import { createBitmap } from './bitmap';
+import { copyBitmapChannel, copyBitmapPixels } from './bitmapCopy';
+import { ImageChannel } from './bitmapImageChannel';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('copyBitmapChannel', () => {
+  it('copies the red channel to the blue channel', () => {
+    const src = createBitmap(2, 2);
+    src.data[0] = 0xab;
+    const dst = createBitmap(2, 2);
+    copyBitmapChannel(region(dst), ImageChannel.Blue, region(src), ImageChannel.Red);
+    expect(dst.data[2]).toBe(src.data[0]);
+  });
+
+  it('copies the alpha channel independently', () => {
+    const src = createBitmap(1, 1);
+    setBitmapPixel(src, 0, 0, 0x000000de);
+    const dst = createBitmap(1, 1);
+    copyBitmapChannel(region(dst), ImageChannel.Alpha, region(src), ImageChannel.Alpha);
+    expect(dst.data[3]).toBe(0xde);
+  });
+});
+
+describe('copyBitmapPixels', () => {
+  it('copies a region without alpha blend', () => {
+    const src = createBitmap(2, 2, 0xaabbccff);
+    const dst = createBitmap(4, 4);
+    copyBitmapPixels(region(dst, 1, 1, 2, 2), region(src, 0, 0, 2, 2));
+    expect(getBitmapPixel(dst, 1, 1)).toBe(0xaabbccff);
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0x00000000);
+  });
+
+  it('alpha-composites when composite is true', () => {
+    const src = createBitmap(1, 1);
+    setBitmapPixel(src, 0, 0, 0xff000080);
+    const dst = createBitmap(1, 1);
+    setBitmapPixel(dst, 0, 0, 0x0000ffff);
+    copyBitmapPixels(region(dst), region(src), true);
+    const result = getBitmapPixel(dst, 0, 0);
+    expect(result & 0xff).toBe(0xff); // alpha opaque after composite
+    expect((result >>> 24) & 0xff).toBeGreaterThan(0); // red blended in
+    expect((result >> 8) & 0xff).toBeGreaterThan(0); // blue retained
+  });
+});

package/src/bitmapCoverage.test.ts

@@ -0,0 +1,39 @@
+import { createBitmap } from './bitmap';
+import { getBitmapCoverage } from './bitmapCoverage';
+import { setBitmapPixel } from './bitmapPixel';
+
+describe('getBitmapCoverage', () => {
+  it('returns 0 for a bitmap still entirely the background colour', () => {
+    expect(getBitmapCoverage(createBitmap(4, 4, 0x123456ff), 0x123456ff)).toBe(0);
+  });
+
+  it('returns 0 for a fully transparent bitmap against a transparent background', () => {
+    expect(getBitmapCoverage(createBitmap(4, 4, 0x00000000), 0x00000000)).toBe(0);
+  });
+
+  it('counts pixels that differ from the background on any channel', () => {
+    const bitmap = createBitmap(2, 2, 0x000000ff);
+    setBitmapPixel(bitmap, 0, 0, 0xff0000ff);
+    expect(getBitmapCoverage(bitmap, 0x000000ff)).toBe(0.25);
+  });
+
+  it('measures a fully painted bitmap as full coverage', () => {
+    const bitmap = createBitmap(2, 2, 0x000000ff);
+    setBitmapPixel(bitmap, 0, 0, 0xffffffff);
+    setBitmapPixel(bitmap, 1, 0, 0xffffffff);
+    setBitmapPixel(bitmap, 0, 1, 0xffffffff);
+    setBitmapPixel(bitmap, 1, 1, 0xffffffff);
+    expect(getBitmapCoverage(bitmap, 0x000000ff)).toBe(1);
+  });
+
+  it('ignores differences within the channel tolerance', () => {
+    const bitmap = createBitmap(2, 1, 0x000000ff);
+    setBitmapPixel(bitmap, 0, 0, 0x050505ff); // 5 per channel
+    expect(getBitmapCoverage(bitmap, 0x000000ff, 5)).toBe(0);
+    expect(getBitmapCoverage(bitmap, 0x000000ff, 4)).toBe(0.5);
+  });
+
+  it('returns 0 for an empty bitmap', () => {
+    expect(getBitmapCoverage(createBitmap(0, 0), 0x000000ff)).toBe(0);
+  });
+});

package/src/bitmapCrop.test.ts

@@ -0,0 +1,116 @@
+import { createBitmap } from './bitmap';
+import { cropBitmap, extendBitmap, trimBitmap } from './bitmapCrop';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+
+describe('cropBitmap', () => {
+  it('returns a bitmap with the requested dimensions', () => {
+    const src = createBitmap(10, 10, 0xff0000ff);
+    const out = cropBitmap(src, { x: 2, y: 3, width: 4, height: 5 });
+    expect(out.width).toBe(4);
+    expect(out.height).toBe(5);
+  });
+
+  it('copies pixels from the source region', () => {
+    const src = createBitmap(4, 4);
+    setBitmapPixel(src, 2, 1, 0x00ff00ff);
+    const out = cropBitmap(src, { x: 2, y: 1, width: 2, height: 2 });
+    expect(getBitmapPixel(out, 0, 0)).toBe(0x00ff00ff);
+  });
+
+  it('fills pixels outside the source with transparent black', () => {
+    const src = createBitmap(2, 2, 0xffffffff);
+    // Crop region extends beyond source.
+    const out = cropBitmap(src, { x: 1, y: 1, width: 3, height: 3 });
+    // (0,0) is inside source — opaque white.
+    expect(getBitmapPixel(out, 0, 0)).toBe(0xffffffff);
+    // (2,2) is outside source — transparent black.
+    expect(getBitmapPixel(out, 2, 2)).toBe(0x00000000);
+  });
+
+  it('preserves source colorSpace and alphaType', () => {
+    const src = createBitmap(2, 2, 0xff0000ff);
+    const out = cropBitmap(src, { x: 0, y: 0, width: 2, height: 2 });
+    expect(out.colorSpace).toBe(src.colorSpace);
+    expect(out.alphaType).toBe(src.alphaType);
+  });
+
+  it('returns a distinct bitmap object', () => {
+    const src = createBitmap(2, 2, 0xff0000ff);
+    const out = cropBitmap(src, { x: 0, y: 0, width: 2, height: 2 });
+    expect(out).not.toBe(src);
+    expect(out.data).not.toBe(src.data);
+  });
+});
+
+describe('extendBitmap', () => {
+  it('returns a bitmap padded by the correct number of pixels', () => {
+    const src = createBitmap(2, 2, 0x0000ffff);
+    const out = extendBitmap(src, 1, 2, 3, 4);
+    expect(out.width).toBe(2 + 1 + 3);
+    expect(out.height).toBe(2 + 2 + 4);
+  });
+
+  it('copies source pixels into the center region', () => {
+    const src = createBitmap(2, 2, 0xabcdefff);
+    const out = extendBitmap(src, 1, 1, 1, 1);
+    expect(getBitmapPixel(out, 1, 1)).toBe(0xabcdefff);
+  });
+
+  it('transparent edge mode fills padding with transparent black by default', () => {
+    const src = createBitmap(2, 2, 0xff0000ff);
+    const out = extendBitmap(src, 1, 1, 1, 1);
+    expect(getBitmapPixel(out, 0, 0)).toBe(0x00000000);
+  });
+
+  it('transparent edge mode uses fillColor when provided', () => {
+    const src = createBitmap(2, 2, 0xff0000ff);
+    const out = extendBitmap(src, 1, 1, 1, 1, 'transparent', 0xffffffff);
+    expect(getBitmapPixel(out, 0, 0)).toBe(0xffffffff);
+  });
+
+  it('clamp edge mode repeats border pixels in padding', () => {
+    const src = createBitmap(2, 2, 0x0000ffff);
+    // Set a distinct border pixel.
+    setBitmapPixel(src, 0, 0, 0x123456ff);
+    const out = extendBitmap(src, 1, 1, 0, 0, 'clamp');
+    // Top-left padding comes from source (0,0).
+    expect(getBitmapPixel(out, 0, 0)).toBe(0x123456ff);
+  });
+
+  it('wrap edge mode tiles the source in padding', () => {
+    const src = createBitmap(2, 2);
+    setBitmapPixel(src, 0, 0, 0xff0000ff);
+    setBitmapPixel(src, 1, 0, 0x00ff00ff);
+    // Extend by 2 on the right → first padding column maps to source col 0.
+    const out = extendBitmap(src, 0, 0, 2, 0, 'wrap');
+    expect(getBitmapPixel(out, 2, 0)).toBe(0xff0000ff);
+    expect(getBitmapPixel(out, 3, 0)).toBe(0x00ff00ff);
+  });
+});
+
+describe('trimBitmap', () => {
+  it('removes transparent border rows and columns', () => {
+    const src = createBitmap(5, 5);
+    // Only pixel (2,2) is non-transparent.
+    setBitmapPixel(src, 2, 2, 0xff0000ff);
+    const out = trimBitmap(src);
+    expect(out.width).toBe(1);
+    expect(out.height).toBe(1);
+    expect(getBitmapPixel(out, 0, 0)).toBe(0xff0000ff);
+  });
+
+  it('returns a 1×1 transparent bitmap for a fully transparent input', () => {
+    const src = createBitmap(3, 3);
+    const out = trimBitmap(src);
+    expect(out.width).toBe(1);
+    expect(out.height).toBe(1);
+    expect(getBitmapPixel(out, 0, 0) & 0xff).toBe(0);
+  });
+
+  it('returns a bitmap equal to the source when there is no transparent border', () => {
+    const src = createBitmap(2, 2, 0xff0000ff);
+    const out = trimBitmap(src);
+    expect(out.width).toBe(2);
+    expect(out.height).toBe(2);
+  });
+});

package/src/bitmapDisplacement.test.ts

@@ -0,0 +1,136 @@
+import { createBitmap } from './bitmap';
+import { displaceBitmap } from './bitmapDisplacement';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+// A 3x1 strip: red | green | blue.
+function rgbStrip() {
+  const s = createBitmap(3, 1);
+  s.data.set([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255]);
+  return s;
+}
+
+describe('displaceBitmap', () => {
+  it('is a no-op copy when scaleX and scaleY are 0', () => {
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(128);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), { map: region(map), scaleX: 0, scaleY: 0, mode: 'clamp' });
+    // With zero scale, every output pixel samples from its exact position.
+    expect(out[0]).toBe(255); // px0 = red
+    expect(out[4 + 1]).toBe(255); // px1 = green
+    expect(out[8 + 2]).toBe(255); // px2 = blue
+  });
+
+  it('shifts the sample position by the scaled map displacement', () => {
+    // map value 255 → dx = (255/255 - 0.5) * 2 = +1.0 exactly; scaleX=2.
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data[0] = 255;
+    map.data[4] = 255;
+    map.data[8] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      componentX: 0,
+      scaleX: 2,
+      scaleY: 0,
+      mode: 'clamp',
+    });
+    // px0←src1 (green), px1←src2 (blue), px2←src3 oob clamped to src2 (blue)
+    expect(out[1]).toBe(255); // green channel of px0
+    expect(out[4 + 2]).toBe(255); // blue channel of px1
+    expect(out[8 + 2]).toBe(255); // blue channel of px2 (clamped)
+  });
+
+  it("'color' mode fills out-of-range samples with fillColor", () => {
+    // Map value 255 with scaleX=4 → dx=+2; px2 samples at x=4 (oob)
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      scaleX: 4,
+      scaleY: 0,
+      mode: 'color',
+      fillColor: 0xff00ffff,
+    });
+    // px2 displaces to x=4 (out of range) → magenta fill
+    expect(out[2 * 4 + 0]).toBe(0xff);
+    expect(out[2 * 4 + 1]).toBe(0);
+    expect(out[2 * 4 + 2]).toBe(0xff);
+    expect(out[2 * 4 + 3]).toBe(255);
+  });
+
+  it("'ignore' mode keeps the undisplaced source pixel for out-of-range samples", () => {
+    // Map value 255 with scaleX=4 → px2 samples at x=4 (oob) → keep blue
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      scaleX: 4,
+      scaleY: 0,
+      mode: 'ignore',
+    });
+    // px2 displaces out of range → keeps src2 (blue) unchanged
+    expect(out[2 * 4 + 2]).toBe(255);
+    expect(out[2 * 4 + 3]).toBe(255);
+  });
+
+  it("edgeMode 'clamp' clamps out-of-range samples to the edge", () => {
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data[0] = 255;
+    map.data[4] = 255;
+    map.data[8] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      componentX: 0,
+      scaleX: 2,
+      scaleY: 0,
+      edgeMode: 'clamp',
+    });
+    // px2 displaces to x=3 (oob) → clamped to x=2 (blue)
+    expect(out[8 + 2]).toBe(255);
+  });
+
+  it("edgeMode 'transparent' fills out-of-range samples with transparent black", () => {
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      scaleX: 4,
+      scaleY: 0,
+      edgeMode: 'transparent',
+    });
+    // px2 displaces to x=4 (oob) → transparent black
+    expect(out[2 * 4 + 0]).toBe(0);
+    expect(out[2 * 4 + 3]).toBe(0);
+  });
+
+  it('samples through the source region offset', () => {
+    // 4px [red, green, blue, white]; zero displacement over region (1,0,2,1) copies
+    // source pixels 1 and 2 (green, blue), proving the offset is applied.
+    const source = createBitmap(4, 1);
+    source.data.set([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255]);
+    const map = createBitmap(2, 1);
+    map.data.fill(128); // neutral — minimal displacement at scale=0
+    const out = new Uint8ClampedArray(2 * 4);
+    displaceBitmap(out, region(source, 1, 0, 2, 1), {
+      map: region(map),
+      scaleX: 0,
+      scaleY: 0,
+    });
+    expect(out[1]).toBe(255); // green from source[1]
+    expect(out[4 + 2]).toBe(255); // blue from source[2]
+  });
+});

package/src/bitmapDissolve.test.ts

@@ -0,0 +1,99 @@
+import { createBitmap } from './bitmap';
+import { dissolveBitmapPixels } from './bitmapDissolve';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { createBitmapRegion } from './bitmapRegion';
+
+function countChangedPixels(data: Readonly<Uint8ClampedArray>, original: Readonly<Uint8ClampedArray>): number {
+  let changed = 0;
+  for (let i = 0; i < data.length; i += 4) {
+    if (
+      data[i] !== original[i] ||
+      data[i + 1] !== original[i + 1] ||
+      data[i + 2] !== original[i + 2] ||
+      data[i + 3] !== original[i + 3]
+    ) {
+      changed++;
+    }
+  }
+  return changed;
+}
+
+describe('dissolveBitmapPixels', () => {
+  it('dissolves at most pixelCount pixels per call', () => {
+    const source = createBitmap(4, 4, 0x112233ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const original = dest.data.slice();
+    dissolveBitmapPixels(createBitmapRegion(dest), createBitmapRegion(source), 0, 5);
+    expect(countChangedPixels(dest.data, original)).toBe(5);
+  });
+
+  it('eventually covers every pixel exactly once so dest matches source', () => {
+    const source = createBitmap(5, 3);
+    for (let i = 0; i < 5 * 3; i++) setBitmapPixel(source, i % 5, (i / 5) | 0, (0x01010100 * (i + 1)) >>> 0);
+    const dest = createBitmap(5, 3, 0x00000000);
+    const sourceRegion = createBitmapRegion(source);
+    const destRegion = createBitmapRegion(dest);
+
+    let seed = 0;
+    for (let call = 0; call < 8; call++) seed = dissolveBitmapPixels(destRegion, sourceRegion, seed, 2);
+
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+  });
+
+  it('is deterministic for the same seed sequence', () => {
+    const source = createBitmap(6, 6, 0xaabbccff);
+    const a = createBitmap(6, 6, 0x00000000);
+    const b = createBitmap(6, 6, 0x00000000);
+    const sourceRegion = createBitmapRegion(source);
+    dissolveBitmapPixels(createBitmapRegion(a), sourceRegion, 3, 7);
+    dissolveBitmapPixels(createBitmapRegion(b), sourceRegion, 3, 7);
+    expect(Array.from(a.data)).toEqual(Array.from(b.data));
+  });
+
+  it('returns a terminal seed once fully dissolved that no-ops on reuse', () => {
+    const source = createBitmap(4, 4, 0x445566ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const sourceRegion = createBitmapRegion(source);
+    const destRegion = createBitmapRegion(dest);
+
+    let seed = 0;
+    for (let call = 0; call < 16; call++) seed = dissolveBitmapPixels(destRegion, sourceRegion, seed, 1);
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+
+    const afterComplete = dissolveBitmapPixels(destRegion, sourceRegion, seed, 4);
+    expect(afterComplete).toBe(seed);
+  });
+
+  it('dissolves toward fillColor when source and dest are the same region', () => {
+    const bitmap = createBitmap(3, 3, 0x112233ff);
+    const region = createBitmapRegion(bitmap);
+    let seed = 0;
+    for (let call = 0; call < 9; call++) seed = dissolveBitmapPixels(region, region, seed, 1, 0x99887766);
+    for (let i = 0; i < 9; i++) expect(getBitmapPixel(bitmap, i % 3, (i / 3) | 0)).toBe(0x99887766);
+  });
+
+  it('ignores fillColor and copies from source when regions differ', () => {
+    const source = createBitmap(2, 2, 0x0a0b0c0d);
+    const dest = createBitmap(2, 2, 0x00000000);
+    let seed = 0;
+    for (let call = 0; call < 4; call++) {
+      seed = dissolveBitmapPixels(createBitmapRegion(dest), createBitmapRegion(source), seed, 1, 0xffffffff);
+    }
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+  });
+
+  it('returns the seed unchanged for a non-positive pixelCount without writing', () => {
+    const source = createBitmap(4, 4, 0x112233ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const original = dest.data.slice();
+    expect(dissolveBitmapPixels(createBitmapRegion(dest), createBitmapRegion(source), 2, 0)).toBe(2);
+    expect(countChangedPixels(dest.data, original)).toBe(0);
+  });
+
+  it('returns the seed for a zero-area region', () => {
+    const source = createBitmap(4, 4, 0x112233ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const region = createBitmapRegion(dest, 0, 0, 0, 0);
+    expect(dissolveBitmapPixels(region, createBitmapRegion(source), 5, 10)).toBe(5);
+  });
+});

package/src/bitmapDraw.test.ts

@@ -0,0 +1,68 @@
+import { createBitmap } from './bitmap';
+import { extractBitmapPixels } from './bitmapComposite';
+import { drawBitmap } from './bitmapDraw';
+import { setBitmapPixel } from './bitmapPixel';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+function readExtractedPixel(buf: Uint8ClampedArray, regionWidth: number, x: number, y: number): number {
+  const i = (y * regionWidth + x) * 4;
+  return ((buf[i] << 24) | (buf[i + 1] << 16) | (buf[i + 2] << 8) | buf[i + 3]) >>> 0;
+}
+
+describe('drawBitmap', () => {
+  it('does not throw when drawing onto a canvas', () => {
+    const src = createBitmap(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    expect(() => drawBitmap(canvas, region(src), 0, 0)).not.toThrow();
+  });
+
+  it('does not throw when drawing at an offset', () => {
+    const src = createBitmap(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 8;
+    expect(() => drawBitmap(canvas, region(src), 2, 2)).not.toThrow();
+  });
+
+  it('extracts correct pixels from a filled source', () => {
+    const src = createBitmap(4, 4, 0xff0000ff);
+    const r = region(src);
+    const buf = new Uint8ClampedArray(r.width * r.height * 4);
+    extractBitmapPixels(buf, r);
+    expect(readExtractedPixel(buf, r.width, 0, 0)).toBe(0xff0000ff);
+    expect(readExtractedPixel(buf, r.width, 3, 3)).toBe(0xff0000ff);
+  });
+
+  it('extracts correct pixels from a sub-region', () => {
+    const src = createBitmap(4, 4);
+    setBitmapPixel(src, 1, 1, 0xaabbccdd);
+    setBitmapPixel(src, 2, 2, 0x11223344);
+    const r = region(src, 1, 1, 2, 2);
+    const buf = new Uint8ClampedArray(r.width * r.height * 4);
+    extractBitmapPixels(buf, r);
+    expect(readExtractedPixel(buf, r.width, 0, 0)).toBe(0xaabbccdd);
+    expect(readExtractedPixel(buf, r.width, 1, 1)).toBe(0x11223344);
+  });
+
+  it('extracts zeroes from an empty bitmap', () => {
+    const src = createBitmap(2, 2);
+    const r = region(src);
+    const buf = new Uint8ClampedArray(r.width * r.height * 4);
+    extractBitmapPixels(buf, r);
+    expect(readExtractedPixel(buf, r.width, 0, 0)).toBe(0x00000000);
+    expect(readExtractedPixel(buf, r.width, 1, 1)).toBe(0x00000000);
+  });
+
+  it('is a no-op for a zero-dimension region', () => {
+    const src = createBitmap(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    expect(() => drawBitmap(canvas, region(src, 0, 0, 0, 0), 0, 0)).not.toThrow();
+  });
+});

package/src/bitmapEncode.test.ts

@@ -0,0 +1,18 @@
+import { createBitmap } from './bitmap';
+import { encodeBitmap } from './bitmapEncode';
+
+describe('encodeBitmap', () => {
+  it('returns a non-empty Uint8Array for a simple image', () => {
+    const img = createBitmap(2, 2, 0x112233ff);
+    const bytes = encodeBitmap(img);
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBeGreaterThan(0);
+  });
+
+  it('accepts jpeg format', () => {
+    const img = createBitmap(2, 2, 0x112233ff);
+    const bytes = encodeBitmap(img, 'jpeg');
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBeGreaterThan(0);
+  });
+});