@flighthq/bitmap 0.3.0-next.1021.f5f1ee0

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);
+  });
+});

package/src/bitmapComposite.test.ts

@@ -0,0 +1,259 @@
+import { BitmapCompositeMode } from '@flighthq/types/contract';
+
+import { createBitmap } from './bitmap';
+import {
+  compositeBitmapPixels,
+  compositeBitmapRegion,
+  extractBitmapPixels,
+  extractBitmapPixels32,
+  writeBitmapPixels,
+  writeBitmapPixels32,
+} from './bitmapComposite';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('compositeBitmapPixels', () => {
+  it('alpha-composites pixels over the destination', () => {
+    const dest = createBitmap(1, 1, 0x0000ffff);
+    const pixels = new Uint8ClampedArray([0xff, 0, 0, 0xff]);
+    compositeBitmapPixels(region(dest), pixels);
+    expect(dest.data[0]).toBe(0xff);
+    expect(dest.data[2]).toBe(0);
+    expect(dest.data[3]).toBe(0xff);
+  });
+
+  it('blends semi-transparent source over destination', () => {
+    const dest = createBitmap(1, 1, 0x000000ff);
+    const pixels = new Uint8ClampedArray([0xff, 0xff, 0xff, 0x80]);
+    compositeBitmapPixels(region(dest), pixels);
+    expect(dest.data[0]).toBeGreaterThan(0);
+    expect(dest.data[0]).toBeLessThan(0xff);
+    expect(dest.data[3]).toBe(0xff);
+  });
+
+  it('silently skips pixels outside destination bounds', () => {
+    const dest = createBitmap(1, 1);
+    const pixels = new Uint8ClampedArray([0xff, 0xff, 0xff, 0xff]);
+    compositeBitmapPixels(region(dest, 5, 5, 1, 1), pixels);
+    expect(dest.data[3]).toBe(0);
+  });
+
+  it('multiply blend mode multiplies source and destination channels', () => {
+    const dest = createBitmap(1, 1, 0xff0000ff); // RGBA: opaque red
+    const pixels = new Uint8ClampedArray([128, 128, 128, 255]);
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.Multiply);
+    expect(dest.data[0]).toBe(128); // 255 * 128 / 255
+    expect(dest.data[1]).toBe(0); // 0 * 128 / 255
+    expect(dest.data[2]).toBe(0);
+    expect(dest.data[3]).toBe(255);
+  });
+
+  it('add blend mode clamps the sum of channels', () => {
+    const dest = createBitmap(1, 1, 0x640000ff); // RGBA: opaque dark red (R=100)
+    const pixels = new Uint8ClampedArray([200, 0, 0, 255]);
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.Add);
+    expect(dest.data[0]).toBe(255); // min(255, 100 + 200)
+  });
+
+  it('defaults to source-over (Normal) when no blend mode is given', () => {
+    const dest = createBitmap(1, 1, 0xff0000ff); // RGBA: opaque red
+    const pixels = new Uint8ClampedArray([0, 0, 255, 255]);
+    compositeBitmapPixels(region(dest), pixels);
+    expect(dest.data[0]).toBe(0);
+    expect(dest.data[2]).toBe(255);
+  });
+
+  it('overlay blend mode darkens on dark backdrops', () => {
+    const dest = createBitmap(1, 1, 0x400000ff); // RGBA: R=64
+    const pixels = new Uint8ClampedArray([200, 0, 0, 255]);
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.Overlay);
+    expect(dest.data[0]).toBe(100); // 2 * 64 * 200 / 255
+  });
+
+  it('hardlight blend mode is overlay with operands swapped', () => {
+    const dest = createBitmap(1, 1, 0xc80000ff); // RGBA: R=200
+    const pixels = new Uint8ClampedArray([64, 0, 0, 255]);
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.HardLight);
+    expect(dest.data[0]).toBe(100); // 2 * 200 * 64 / 255
+  });
+
+  it('invert blend mode inverts the backdrop, ignoring source color', () => {
+    const dest = createBitmap(1, 1, 0xc80000ff); // RGBA: R=200
+    const pixels = new Uint8ClampedArray([0, 0, 0, 255]);
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.Invert);
+    expect(dest.data[0]).toBe(55); // 255 - 200
+  });
+
+  it('DestinationOut (erase) knocks alpha out of the backdrop, keeping color', () => {
+    const dest = createBitmap(1, 1, 0xff0000ff); // RGBA: opaque red
+    const pixels = new Uint8ClampedArray([0, 0, 0, 128]);
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.DestinationOut);
+    expect(dest.data[0]).toBe(255); // color untouched
+    expect(dest.data[3]).toBe(127); // 255 * (1 - 128/255)
+  });
+
+  it('DestinationIn (alpha) masks the backdrop to the source coverage', () => {
+    const dest = createBitmap(1, 1, 0xff0000ff); // RGBA: opaque red
+    const pixels = new Uint8ClampedArray([0, 0, 0, 128]);
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.DestinationIn);
+    expect(dest.data[0]).toBe(255); // backdrop color kept
+    expect(dest.data[3]).toBe(128); // 255 * (128/255)
+  });
+
+  it('Copy overwrites the backdrop with the source', () => {
+    const dest = createBitmap(1, 1, 0xff0000ff); // opaque red
+    const pixels = new Uint8ClampedArray([0, 0, 255, 128]); // semi-transparent blue
+    compositeBitmapPixels(region(dest), pixels, BitmapCompositeMode.Copy);
+    expect(dest.data[2]).toBe(255);
+    expect(dest.data[3]).toBe(128); // source alpha replaces, no source-over
+  });
+});
+
+describe('compositeBitmapRegion', () => {
+  it('alpha-composites a region of one bitmap over another', () => {
+    const source = createBitmap(1, 1, 0xff0000ff);
+    const dest = createBitmap(1, 1, 0x0000ffff);
+    compositeBitmapRegion(region(dest), region(source));
+    expect(dest.data[0]).toBe(0xff);
+    expect(dest.data[2]).toBe(0);
+  });
+
+  it('clips to the smaller of source and dest dimensions', () => {
+    const source = createBitmap(1, 1, 0xff0000ff);
+    const dest = createBitmap(3, 3);
+    compositeBitmapRegion(region(dest, 1, 1, 2, 2), region(source));
+    expect(dest.data[(1 * 3 + 1) * 4]).toBe(0xff);
+    expect(dest.data[(1 * 3 + 2) * 4]).toBe(0);
+  });
+
+  it('applies the blend mode to the source region', () => {
+    const source = createBitmap(1, 1, 0x808080ff); // RGBA: opaque gray
+    const dest = createBitmap(1, 1, 0xff0000ff); // RGBA: opaque red
+    compositeBitmapRegion(region(dest), region(source), BitmapCompositeMode.Multiply);
+    expect(dest.data[0]).toBe(128); // 255 * 128 / 255
+    expect(dest.data[1]).toBe(0);
+  });
+});
+
+describe('extractBitmapPixels', () => {
+  it('copies a bitmap region into a tightly-packed buffer', () => {
+    const source = createBitmap(2, 2);
+    const i = (1 * 2 + 1) * 4;
+    source.data[i] = 0xff;
+    source.data[i + 3] = 0xff;
+    const out = new Uint8ClampedArray(4);
+    extractBitmapPixels(out, region(source, 1, 1, 1, 1));
+    expect(out[0]).toBe(0xff);
+    expect(out[3]).toBe(0xff);
+  });
+
+  it('silently skips pixels outside source bounds', () => {
+    const source = createBitmap(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4 * 4);
+    extractBitmapPixels(out, region(source, -1, -1, 2, 2));
+    const i = (1 * 2 + 1) * 4;
+    expect(out[i]).toBe(0xff);
+    expect(out[i + 3]).toBe(0xff);
+    expect(out[0]).toBe(0);
+  });
+
+  it('source.bitmap.data can be passed as out for a full-bitmap extraction', () => {
+    const source = createBitmap(2, 2, 0xaabbccff);
+    extractBitmapPixels(source.data, region(source));
+    expect(source.data[0]).toBe(0xaa);
+    expect(source.data[3]).toBe(0xff);
+  });
+});
+
+describe('extractBitmapPixels32', () => {
+  it('packs each pixel into one 0xRRGGBBAA entry', () => {
+    const source = createBitmap(2, 2);
+    const i = (1 * 2 + 1) * 4;
+    source.data[i] = 0x11;
+    source.data[i + 1] = 0x22;
+    source.data[i + 2] = 0x33;
+    source.data[i + 3] = 0x44;
+    const out = new Uint32Array(1);
+    extractBitmapPixels32(out, region(source, 1, 1, 1, 1));
+    expect(out[0]).toBe(0x11223344);
+  });
+
+  it('round-trips with writeBitmapPixels32', () => {
+    const source = createBitmap(3, 2);
+    for (let p = 0; p < 6; p++) {
+      const i = p * 4;
+      source.data[i] = p * 10 + 1;
+      source.data[i + 1] = p * 10 + 2;
+      source.data[i + 2] = p * 10 + 3;
+      source.data[i + 3] = p * 10 + 4;
+    }
+    const packed = new Uint32Array(6);
+    extractBitmapPixels32(packed, region(source));
+    const dest = createBitmap(3, 2);
+    writeBitmapPixels32(region(dest), packed);
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+  });
+
+  it('silently skips pixels outside source bounds', () => {
+    const source = createBitmap(1, 1, 0xffffffff);
+    const out = new Uint32Array(4);
+    extractBitmapPixels32(out, region(source, -1, -1, 2, 2));
+    expect(out[1 * 2 + 1]).toBe(0xffffffff);
+    expect(out[0]).toBe(0);
+  });
+});
+
+describe('writeBitmapPixels', () => {
+  it('writes pixels at the given destination region', () => {
+    const dest = createBitmap(3, 3);
+    const pixels = new Uint8ClampedArray([0x33, 0x66, 0x99, 0xff]);
+    writeBitmapPixels(region(dest, 1, 1, 1, 1), pixels);
+    const i = (1 * 3 + 1) * 4;
+    expect(dest.data[i]).toBe(0x33);
+    expect(dest.data[i + 1]).toBe(0x66);
+    expect(dest.data[i + 2]).toBe(0x99);
+    expect(dest.data[i + 3]).toBe(0xff);
+  });
+
+  it('overwrites existing content', () => {
+    const dest = createBitmap(1, 1, 0x0000ffff);
+    const pixels = new Uint8ClampedArray([0xff, 0, 0, 0xff]);
+    writeBitmapPixels(region(dest), pixels);
+    expect(dest.data[2]).toBe(0);
+    expect(dest.data[0]).toBe(0xff);
+  });
+
+  it('silently clips writes outside destination bounds', () => {
+    const dest = createBitmap(1, 1);
+    const pixels = new Uint8ClampedArray([0xff, 0xff, 0xff, 0xff]);
+    writeBitmapPixels(region(dest, 5, 5, 1, 1), pixels);
+    expect(dest.data[3]).toBe(0);
+  });
+});
+
+describe('writeBitmapPixels32', () => {
+  it('unpacks each 0xRRGGBBAA entry into the destination region', () => {
+    const dest = createBitmap(3, 3);
+    writeBitmapPixels32(region(dest, 1, 1, 1, 1), new Uint32Array([0x33669900 | 0xff]));
+    const i = (1 * 3 + 1) * 4;
+    expect(dest.data[i]).toBe(0x33);
+    expect(dest.data[i + 1]).toBe(0x66);
+    expect(dest.data[i + 2]).toBe(0x99);
+    expect(dest.data[i + 3]).toBe(0xff);
+  });
+
+  it('overwrites existing content', () => {
+    const dest = createBitmap(1, 1, 0x0000ffff);
+    writeBitmapPixels32(region(dest), new Uint32Array([0xff0000ff]));
+    expect(dest.data[0]).toBe(0xff);
+    expect(dest.data[2]).toBe(0);
+  });
+
+  it('silently clips writes outside destination bounds', () => {
+    const dest = createBitmap(1, 1);
+    writeBitmapPixels32(region(dest, 5, 5, 1, 1), new Uint32Array([0xffffffff]));
+    expect(dest.data[3]).toBe(0);
+  });
+});