@flighthq/bitmap 0.3.0-edge.1458.0c01b63

package/src/bitmapFormat.test.ts

@@ -0,0 +1,124 @@
+import { convertBitmapPixelOrder, premultiplyBitmapPixels, unpremultiplyBitmapPixels } from './bitmapFormat';
+
+describe('convertBitmapPixelOrder', () => {
+  it('is a no-op when from === to and out !== source', () => {
+    const source = new Uint8ClampedArray([0x11, 0x22, 0x33, 0xff]);
+    const out = new Uint8ClampedArray(4);
+    convertBitmapPixelOrder(out, source, 4, 'RGBA', 'RGBA');
+    expect(out[0]).toBe(0x11);
+    expect(out[1]).toBe(0x22);
+  });
+
+  it('converts RGBA to BGRA', () => {
+    const source = new Uint8ClampedArray([0xaa, 0xbb, 0xcc, 0xff]);
+    const out = new Uint8ClampedArray(4);
+    convertBitmapPixelOrder(out, source, 4, 'RGBA', 'BGRA');
+    expect(out[0]).toBe(0xcc); // B
+    expect(out[1]).toBe(0xbb); // G
+    expect(out[2]).toBe(0xaa); // R
+    expect(out[3]).toBe(0xff); // A
+  });
+
+  it('converts RGBA to ARGB', () => {
+    const source = new Uint8ClampedArray([0xaa, 0xbb, 0xcc, 0xdd]);
+    const out = new Uint8ClampedArray(4);
+    convertBitmapPixelOrder(out, source, 4, 'RGBA', 'ARGB');
+    expect(out[0]).toBe(0xdd); // A
+    expect(out[1]).toBe(0xaa); // R
+    expect(out[2]).toBe(0xbb); // G
+    expect(out[3]).toBe(0xcc); // B
+  });
+
+  it('round-trips RGBA → BGRA → RGBA', () => {
+    const source = new Uint8ClampedArray([0x11, 0x22, 0x33, 0x44]);
+    const tmp = new Uint8ClampedArray(4);
+    const out = new Uint8ClampedArray(4);
+    convertBitmapPixelOrder(tmp, source, 4, 'RGBA', 'BGRA');
+    convertBitmapPixelOrder(out, tmp, 4, 'BGRA', 'RGBA');
+    expect(out[0]).toBe(0x11);
+    expect(out[1]).toBe(0x22);
+    expect(out[2]).toBe(0x33);
+    expect(out[3]).toBe(0x44);
+  });
+
+  it('is safe in-place for the same format (no-op path)', () => {
+    const buf = new Uint8ClampedArray([0xaa, 0xbb, 0xcc, 0xff]);
+    convertBitmapPixelOrder(buf, buf, 4, 'RGBA', 'RGBA');
+    expect(buf[0]).toBe(0xaa);
+  });
+
+  it('is safe in-place for different formats', () => {
+    const buf = new Uint8ClampedArray([0xaa, 0xbb, 0xcc, 0xff]);
+    convertBitmapPixelOrder(buf, buf, 4, 'RGBA', 'BGRA');
+    expect(buf[0]).toBe(0xcc);
+    expect(buf[2]).toBe(0xaa);
+  });
+});
+
+describe('premultiplyBitmapPixels', () => {
+  it('scales RGB by alpha/255', () => {
+    const source = new Uint8ClampedArray([0xff, 0x80, 0x00, 0x80]);
+    const out = new Uint8ClampedArray(4);
+    premultiplyBitmapPixels(out, source, 4);
+    expect(out[0]).toBeCloseTo(0x80, 0); // 255 * 128/255 ≈ 128
+    expect(out[1]).toBeCloseTo(0x40, 0); // 128 * 128/255 ≈ 64
+    expect(out[2]).toBe(0);
+    expect(out[3]).toBe(0x80); // alpha unchanged
+  });
+
+  it('fully transparent pixel becomes all zeros', () => {
+    const source = new Uint8ClampedArray([0xff, 0xff, 0xff, 0x00]);
+    const out = new Uint8ClampedArray(4);
+    premultiplyBitmapPixels(out, source, 4);
+    expect(out[0]).toBe(0);
+    expect(out[1]).toBe(0);
+    expect(out[2]).toBe(0);
+    expect(out[3]).toBe(0);
+  });
+
+  it('fully opaque pixel is unchanged', () => {
+    const source = new Uint8ClampedArray([0x11, 0x22, 0x33, 0xff]);
+    const out = new Uint8ClampedArray(4);
+    premultiplyBitmapPixels(out, source, 4);
+    expect(out[0]).toBe(0x11);
+    expect(out[1]).toBe(0x22);
+    expect(out[2]).toBe(0x33);
+    expect(out[3]).toBe(0xff);
+  });
+
+  it('is safe in-place', () => {
+    const buf = new Uint8ClampedArray([0xff, 0x00, 0x00, 0x80]);
+    premultiplyBitmapPixels(buf, buf, 4);
+    expect(buf[0]).toBeCloseTo(0x80, 0);
+    expect(buf[3]).toBe(0x80);
+  });
+});
+
+describe('unpremultiplyBitmapPixels', () => {
+  it('recovers original RGB after premultiply round-trip within ±1', () => {
+    // Integer premultiply introduces at most ±1 rounding error per channel.
+    const source = new Uint8ClampedArray([0xc0, 0x80, 0x40, 0x80]);
+    const premul = new Uint8ClampedArray(4);
+    const out = new Uint8ClampedArray(4);
+    premultiplyBitmapPixels(premul, source, 4);
+    unpremultiplyBitmapPixels(out, premul, 4);
+    expect(Math.abs(out[0] - 0xc0)).toBeLessThanOrEqual(1);
+    expect(Math.abs(out[1] - 0x80)).toBeLessThanOrEqual(1);
+    expect(out[3]).toBe(0x80);
+  });
+
+  it('fully transparent pixel remains all zeros', () => {
+    const source = new Uint8ClampedArray([0x00, 0x00, 0x00, 0x00]);
+    const out = new Uint8ClampedArray(4);
+    unpremultiplyBitmapPixels(out, source, 4);
+    expect(out[0]).toBe(0);
+    expect(out[3]).toBe(0);
+  });
+
+  it('is safe in-place', () => {
+    const buf = new Uint8ClampedArray([0x80, 0x00, 0x00, 0x80]);
+    unpremultiplyBitmapPixels(buf, buf, 4);
+    expect(buf[0]).toBeCloseTo(0xff, 0);
+    expect(buf[3]).toBe(0x80);
+  });
+});

package/src/bitmapFrom.test.ts

@@ -0,0 +1,86 @@
+import { createImageResource } from '@flighthq/image/contract';
+import { vi } from 'vitest';
+
+import { createBitmap } from './bitmap';
+import { createBitmapFromCanvas, captureBitmapFromImageResource, createBitmapFromImageSource } from './bitmapFrom';
+
+describe('captureBitmapFromImageResource', () => {
+  it('reads a host-backed resource into CPU pixels', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 3;
+    canvas.height = 2;
+    const bitmap = captureBitmapFromImageResource(createImageResource(canvas));
+    expect(bitmap.width).toBe(3);
+    expect(bitmap.height).toBe(2);
+    expect(bitmap.data).toHaveLength(3 * 2 * 4);
+  });
+
+  it('returns Bitmap matching the resource dimensions', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    const resource = createImageResource(canvas);
+    const data = captureBitmapFromImageResource(resource);
+    expect(data.width).toBe(4);
+    expect(data.height).toBe(4);
+  });
+});
+
+describe('createBitmapFromCanvas', () => {
+  it('returns Bitmap matching the canvas size', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    const data = createBitmapFromCanvas(canvas);
+    expect(data.width).toBe(4);
+    expect(data.height).toBe(4);
+  });
+
+  it('returns a Bitmap with data length matching canvas pixels', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 8;
+    const data = createBitmapFromCanvas(canvas);
+    expect(data.data.length).toBe(8 * 8 * 4);
+  });
+});
+
+describe('createBitmapFromImageSource', () => {
+  it('captures a canvas image source at the given device size', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 4;
+    const bitmap = createBitmapFromImageSource(canvas, 8, 4);
+    expect(bitmap).not.toBeNull();
+    expect(bitmap!.width).toBe(8);
+    expect(bitmap!.height).toBe(4);
+    expect(bitmap!.data.length).toBe(8 * 4 * 4);
+  });
+
+  it('returns null rather than letting a tainted source throw', () => {
+    // A cross-origin draw taints the scratch canvas and the platform refuses its pixels with a
+    // SecurityError from getImageData. jsdom does not model tainting, so the throw is staged on
+    // getImageData directly — which is the exact call and the exact exception the sentinel exists to
+    // stop escaping to a caller who only asked for a bitmap.
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 4;
+    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
+      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
+    });
+    try {
+      expect(() => createBitmapFromImageSource(canvas, 8, 4)).not.toThrow();
+      expect(createBitmapFromImageSource(canvas, 8, 4)).toBeNull();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('returns null for an empty capture rather than allocating a zero-pixel bitmap', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 4;
+    expect(createBitmapFromImageSource(canvas, 0, 4)).toBeNull();
+    expect(createBitmapFromImageSource(canvas, 8, -1)).toBeNull();
+  });
+});

package/src/bitmapGradient.test.ts

@@ -0,0 +1,85 @@
+import { createBitmap } from './bitmap';
+import { buildBitmapGradientRamp, gradientBevelBitmap, gradientGlowBitmap } from './bitmapGradient';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('buildBitmapGradientRamp', () => {
+  it('places endpoints exactly and interpolates the middle', () => {
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildBitmapGradientRamp(ramp, [0xff0000, 0x0000ff], [0, 1], [0, 255]);
+    expect(Array.from(ramp.subarray(0, 4))).toEqual([255, 0, 0, 0]);
+    expect(Array.from(ramp.subarray(255 * 4, 256 * 4))).toEqual([0, 0, 255, 255]);
+    expect(Array.from(ramp.subarray(128 * 4, 129 * 4))).toEqual([127, 0, 128, 128]);
+  });
+
+  it('zero-fills when there are no stops', () => {
+    const ramp = new Uint8ClampedArray(256 * 4).fill(99);
+    buildBitmapGradientRamp(ramp, [], [], []);
+    expect(ramp.every((v) => v === 0)).toBe(true);
+  });
+});
+
+describe('gradientBevelBitmap', () => {
+  it('maps the signed edge gradient through the ramp', () => {
+    // 5x1 edge: transparent x2 | opaque x3. Shadow ramp at index 0 (black),
+    // transparent middle at 128, highlight white at 255.
+    const source = createBitmap(5, 1);
+    for (let x = 2; x < 5; x++) source.data[x * 4 + 3] = 255;
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildBitmapGradientRamp(ramp, [0x000000, 0x808080, 0xffffff], [1, 0, 1], [0, 128, 255]);
+    const out = new Uint8ClampedArray(5 * 4);
+    const scratch = new Uint8ClampedArray(5 * 4);
+    gradientBevelBitmap(out, scratch, region(source), ramp, {
+      angle: Math.PI,
+      distance: 1,
+      radiusX: 1,
+      radiusY: 0,
+      type: 'both',
+    });
+    // Light-facing edge (x2) is on the highlight half of the ramp → bright.
+    expect(out[2 * 4 + 0]).toBeGreaterThan(150);
+    expect(out[2 * 4 + 3]).toBeGreaterThan(0);
+    // Far edge (x4) maps to ramp index 0 → opaque black shadow.
+    expect(out[4 * 4 + 0]).toBe(0);
+    expect(out[4 * 4 + 3]).toBe(255);
+  });
+});
+
+describe('gradientGlowBitmap', () => {
+  it('indexes the ramp by the blurred alpha', () => {
+    // ramp: index 0 transparent green, 255 opaque green.
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildBitmapGradientRamp(ramp, [0x00ff00, 0x00ff00], [0, 1], [0, 255]);
+    const source = createBitmap(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    gradientGlowBitmap(out, scratch, region(source), ramp, { radiusX: 0, radiusY: 0 });
+    // Full alpha (255) → ramp[255] = opaque green.
+    expect(out[0]).toBe(0);
+    expect(out[1]).toBe(0xff);
+    expect(out[2]).toBe(0);
+    expect(out[3]).toBe(255);
+  });
+
+  it('scales the ramp alpha by intensity', () => {
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildBitmapGradientRamp(ramp, [0x00ff00, 0x00ff00], [1, 1], [0, 255]);
+    const source = createBitmap(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    gradientGlowBitmap(out, scratch, region(source), ramp, { radiusX: 0, radiusY: 0, intensity: 0.5 });
+    expect(out[3]).toBe(128);
+  });
+
+  it('source.bitmap.data can be used as out for a full-bitmap region', () => {
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildBitmapGradientRamp(ramp, [0x00ff00, 0x00ff00], [0, 1], [0, 255]);
+    const bitmap = createBitmap(1, 1, 0xffffffff);
+    const scratch = new Uint8ClampedArray(4);
+    gradientGlowBitmap(bitmap.data, scratch, region(bitmap), ramp, { radiusX: 0, radiusY: 0 });
+    expect(bitmap.data[1]).toBe(0xff);
+    expect(bitmap.data[3]).toBe(255);
+  });
+});

package/src/bitmapGradientFill.test.ts

@@ -0,0 +1,107 @@
+import { createBitmap } from './bitmap';
+import { buildBitmapGradientRamp } from './bitmapGradient';
+import { fillBitmapLinearGradient, fillBitmapRadialGradient } from './bitmapGradientFill';
+import { getBitmapPixel } from './bitmapPixel';
+import { createBitmapRegion } from './bitmapRegion';
+
+function buildTwoStopRamp(colorA: number, colorB: number): Uint8ClampedArray {
+  const ramp = new Uint8ClampedArray(1024);
+  const aR = (colorA >>> 24) & 0xff;
+  const aG = (colorA >> 16) & 0xff;
+  const aB = (colorA >> 8) & 0xff;
+  const aA = colorA & 0xff;
+  const bR = (colorB >>> 24) & 0xff;
+  const bG = (colorB >> 16) & 0xff;
+  const bB = (colorB >> 8) & 0xff;
+  const bA = colorB & 0xff;
+  buildBitmapGradientRamp(
+    ramp,
+    [(aR << 16) | (aG << 8) | aB, (bR << 16) | (bG << 8) | bB],
+    [aA / 255, bA / 255],
+    [0, 255],
+  );
+  return ramp;
+}
+
+describe('fillBitmapLinearGradient', () => {
+  it('fills leftmost pixel with the first stop color', () => {
+    const surf = createBitmap(4, 1);
+    const region = createBitmapRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillBitmapLinearGradient(region, ramp, 0, 0, 3, 0);
+    const pixel = getBitmapPixel(surf, 0, 0);
+    expect((pixel >>> 24) & 0xff).toBeCloseTo(0xff, -1);
+    expect((pixel >> 8) & 0xff).toBeCloseTo(0x00, -1);
+  });
+
+  it('fills rightmost pixel with the last stop color', () => {
+    const surf = createBitmap(4, 1);
+    const region = createBitmapRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillBitmapLinearGradient(region, ramp, 0, 0, 3, 0);
+    const pixel = getBitmapPixel(surf, 3, 0);
+    expect((pixel >>> 24) & 0xff).toBeCloseTo(0x00, -1);
+    expect((pixel >> 8) & 0xff).toBeCloseTo(0xff, -1);
+  });
+
+  it('middle pixel is a blend of both stops', () => {
+    const surf = createBitmap(3, 1);
+    const region = createBitmapRegion(surf);
+    const ramp = buildTwoStopRamp(0x000000ff, 0xffffffff);
+    fillBitmapLinearGradient(region, ramp, 0, 0, 2, 0);
+    const mid = getBitmapPixel(surf, 1, 0);
+    const r = (mid >>> 24) & 0xff;
+    expect(r).toBeGreaterThan(0);
+    expect(r).toBeLessThan(255);
+  });
+
+  it('pad spread clamps colors outside axis', () => {
+    const surf = createBitmap(5, 1);
+    const region = createBitmapRegion(surf);
+    // Gradient from x=1 to x=3; pixels at x=0 and x=4 should get clamped stops.
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillBitmapLinearGradient(region, ramp, 1, 0, 3, 0, 'pad');
+    const left = getBitmapPixel(surf, 0, 0);
+    const right = getBitmapPixel(surf, 4, 0);
+    expect((left >>> 24) & 0xff).toBe((getBitmapPixel(surf, 1, 0) >>> 24) & 0xff);
+    expect((right >> 8) & 0xff).toBe((getBitmapPixel(surf, 3, 0) >> 8) & 0xff);
+  });
+
+  it('skips pixels outside bitmap bounds', () => {
+    const surf = createBitmap(2, 2);
+    // Region that extends outside bitmap — should not throw.
+    const region = { bitmap: surf, x: -1, y: 0, width: 4, height: 1 };
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    expect(() => fillBitmapLinearGradient(region, ramp, 0, 0, 3, 0)).not.toThrow();
+  });
+});
+
+describe('fillBitmapRadialGradient', () => {
+  it('center pixel gets the first stop color', () => {
+    const surf = createBitmap(5, 5);
+    const region = createBitmapRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillBitmapRadialGradient(region, ramp, 2, 2, 2);
+    // Center is at distance 0, so t=0, gets first stop.
+    const pixel = getBitmapPixel(surf, 2, 2);
+    expect((pixel >>> 24) & 0xff).toBeCloseTo(0xff, -1);
+  });
+
+  it('pad spread clamps beyond radius to last stop', () => {
+    const surf = createBitmap(9, 1);
+    const region = createBitmapRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    // Center at x=4, radius=2; pixels at x=0 and x=8 are far outside.
+    fillBitmapRadialGradient(region, ramp, 4, 0, 2, 4, 0, 'pad');
+    const far = getBitmapPixel(surf, 0, 0);
+    // Should be clamped to last stop (blue).
+    expect((far >> 8) & 0xff).toBeCloseTo(0xff, -1);
+  });
+
+  it('skips pixels outside bitmap bounds', () => {
+    const surf = createBitmap(2, 2);
+    const region = { bitmap: surf, x: -1, y: 0, width: 4, height: 1 };
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    expect(() => fillBitmapRadialGradient(region, ramp, 1, 0, 2)).not.toThrow();
+  });
+});

package/src/bitmapHistogram.test.ts

@@ -0,0 +1,64 @@
+import { createBitmap } from './bitmap';
+import { equalizeBitmapHistogram, getBitmapHistogram } from './bitmapHistogram';
+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 };
+}
+
+describe('equalizeBitmapHistogram', () => {
+  it('spreads a narrow tonal range to fill 0..255', () => {
+    // All red values are either 0 or 128 — a compressed range.
+    const source = createBitmap(2, 1);
+    setBitmapPixel(source, 0, 0, 0x000000ff);
+    setBitmapPixel(source, 1, 0, 0x808000ff);
+    const dest = createBitmap(2, 1);
+    equalizeBitmapHistogram(region(dest), region(source));
+    // After equalization the darker pixel maps to 0 and brighter to 255
+    expect(dest.data[0]).toBe(0);
+    expect(dest.data[4]).toBe(255);
+  });
+
+  it('is safe in-place', () => {
+    const bitmap = createBitmap(2, 1);
+    setBitmapPixel(bitmap, 0, 0, 0x000000ff);
+    setBitmapPixel(bitmap, 1, 0, 0xff0000ff);
+    expect(() => equalizeBitmapHistogram(region(bitmap), region(bitmap))).not.toThrow();
+  });
+
+  it('preserves alpha unchanged', () => {
+    const source = createBitmap(1, 1, 0x40404080);
+    const dest = createBitmap(1, 1);
+    equalizeBitmapHistogram(region(dest), region(source));
+    expect(dest.data[3]).toBe(0x80);
+  });
+});
+
+describe('getBitmapHistogram', () => {
+  it('counts pixel values per channel', () => {
+    const bitmap = createBitmap(2, 1);
+    setBitmapPixel(bitmap, 0, 0, 0x0a000000);
+    setBitmapPixel(bitmap, 1, 0, 0x0a0000ff);
+    const histogram = getBitmapHistogram(region(bitmap));
+    expect(histogram.red[0x0a]).toBe(2);
+    expect(histogram.alpha[0]).toBe(1);
+    expect(histogram.alpha[255]).toBe(1);
+    expect(histogram.green[0]).toBe(2);
+  });
+
+  it('returns all-zero bins for an empty region', () => {
+    const bitmap = createBitmap(2, 2, 0xffffffff);
+    const histogram = getBitmapHistogram(region(bitmap, 0, 0, 0, 0));
+    expect(histogram.red.reduce((a, b) => a + b, 0)).toBe(0);
+    expect(histogram.red.length).toBe(256);
+  });
+
+  it('counts only a sub-region', () => {
+    const bitmap = createBitmap(2, 1);
+    setBitmapPixel(bitmap, 0, 0, 0x10000000);
+    setBitmapPixel(bitmap, 1, 0, 0x20000000);
+    const histogram = getBitmapHistogram(region(bitmap, 1, 0, 1, 1));
+    expect(histogram.red[0x20]).toBe(1);
+    expect(histogram.red[0x10]).toBe(0);
+  });
+});

package/src/bitmapImageChannel.test.ts

@@ -0,0 +1,19 @@
+import { ImageChannel } from './bitmapImageChannel';
+
+describe('ImageChannel', () => {
+  it('has Red = 0', () => {
+    expect(ImageChannel.Red).toBe(0);
+  });
+
+  it('has Green = 1', () => {
+    expect(ImageChannel.Green).toBe(1);
+  });
+
+  it('has Blue = 2', () => {
+    expect(ImageChannel.Blue).toBe(2);
+  });
+
+  it('has Alpha = 3', () => {
+    expect(ImageChannel.Alpha).toBe(3);
+  });
+});

package/src/bitmapMedian.test.ts

@@ -0,0 +1,39 @@
+import { createBitmap } from './bitmap';
+import { medianBitmap } from './bitmapMedian';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('medianBitmap', () => {
+  it('removes an isolated salt pixel without blurring', () => {
+    // 3x3 of black with a single white (R=255) center; the median is black.
+    const source = createBitmap(3, 3);
+    for (let i = 0; i < 9; i++) source.data[i * 4 + 3] = 255;
+    source.data[4 * 4] = 255;
+    const out = new Uint8ClampedArray(3 * 3 * 4);
+    medianBitmap(out, region(source), 1);
+    expect(out[4 * 4]).toBe(0);
+  });
+
+  it('preserves a hard edge (median is not an average)', () => {
+    // Left half 0, right half 255 across a 4x1 row; the boundary stays crisp.
+    const source = createBitmap(4, 1);
+    source.data[0] = 0;
+    source.data[4] = 0;
+    source.data[8] = 255;
+    source.data[12] = 255;
+    const out = new Uint8ClampedArray(4 * 4);
+    medianBitmap(out, region(source), 1);
+    expect(out[4]).toBe(0);
+    expect(out[8]).toBe(255);
+  });
+
+  it('radius 0 copies the source', () => {
+    const source = createBitmap(1, 1, 0x123456ff);
+    const out = new Uint8ClampedArray(4);
+    medianBitmap(out, region(source), 0);
+    expect(out[0]).toBe(0x12);
+    expect(out[3]).toBe(0xff);
+  });
+});

package/src/bitmapMorphological.test.ts

@@ -0,0 +1,69 @@
+import { createBitmap } from './bitmap';
+import { dilateBitmap, erodeBitmap } from './bitmapMorphological';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('dilateBitmap', () => {
+  it('expands a single bright pixel into its neighborhood', () => {
+    const source = createBitmap(3, 1);
+    source.data[1 * 4 + 3] = 255; // center pixel fully opaque
+    const out = new Uint8ClampedArray(3 * 4);
+    dilateBitmap(out, region(source), 1);
+    expect(out[0 * 4 + 3]).toBe(255);
+    expect(out[1 * 4 + 3]).toBe(255);
+    expect(out[2 * 4 + 3]).toBe(255);
+  });
+
+  it('with radius 0 is an identity copy', () => {
+    const source = createBitmap(3, 1);
+    source.data.set([10, 20, 30, 100], 0);
+    source.data.set([50, 60, 70, 200], 4);
+    const out = new Uint8ClampedArray(3 * 4);
+    dilateBitmap(out, region(source), 0);
+    expect(out[0]).toBe(10);
+    expect(out[4]).toBe(50);
+  });
+
+  it('is dual to erodeBitmap (dilate after erode has no-smaller effect)', () => {
+    const source = createBitmap(5, 1);
+    for (let i = 1; i < 4; i++) source.data[i * 4 + 3] = 255; // pixels 1-3 opaque
+    const eroded = new Uint8ClampedArray(5 * 4);
+    const dilated = new Uint8ClampedArray(5 * 4);
+    erodeBitmap(eroded, region(source), 1);
+    dilateBitmap(dilated, region(source), 1);
+    // Dilation always >= source, erosion always <= source for alpha
+    expect(dilated[1 * 4 + 3]).toBeGreaterThanOrEqual(source.data[1 * 4 + 3]);
+    expect(eroded[1 * 4 + 3]).toBeLessThanOrEqual(source.data[1 * 4 + 3]);
+  });
+});
+
+describe('erodeBitmap', () => {
+  it('shrinks an isolated bright pixel to dark when radius covers neighbors', () => {
+    const source = createBitmap(3, 1);
+    source.data[1 * 4 + 3] = 255; // only center opaque
+    const out = new Uint8ClampedArray(3 * 4);
+    erodeBitmap(out, region(source), 1);
+    // Center eroded to 0 because transparent neighbors dominate the min
+    expect(out[1 * 4 + 3]).toBe(0);
+  });
+
+  it('with radius 0 is an identity copy', () => {
+    const source = createBitmap(3, 1);
+    source.data.set([10, 20, 30, 100], 4);
+    const out = new Uint8ClampedArray(3 * 4);
+    erodeBitmap(out, region(source), 0);
+    expect(out[4]).toBe(10);
+    expect(out[7]).toBe(100);
+  });
+
+  it('preserves a fully opaque field', () => {
+    const source = createBitmap(5, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(5 * 4);
+    erodeBitmap(out, region(source), 2);
+    for (let i = 0; i < 5; i++) {
+      expect(out[i * 4 + 3]).toBe(255);
+    }
+  });
+});