@flighthq/bitmap 0.3.0-next.1021.f5f1ee0

package/src/bitmapFill.test.ts

@@ -0,0 +1,83 @@
+import { createBitmap } from './bitmap';
+import { fillBitmapRectangle, floodFillBitmap } from './bitmapFill';
+import { getBitmapPixel } 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('fillBitmapRectangle', () => {
+  it('fills the specified region', () => {
+    const img = createBitmap(4, 4);
+    fillBitmapRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(getBitmapPixel(img, 1, 1)).toBe(0xaabbccff);
+    expect(getBitmapPixel(img, 2, 2)).toBe(0xaabbccff);
+  });
+
+  it('bumps the bitmap version (self-invalidation)', () => {
+    const img = createBitmap(4, 4);
+    const before = img.version;
+    fillBitmapRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(img.version).toBe(before + 1);
+  });
+
+  it('does not affect pixels outside the region', () => {
+    const img = createBitmap(4, 4);
+    fillBitmapRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0x00000000);
+    expect(getBitmapPixel(img, 3, 3)).toBe(0x00000000);
+  });
+
+  it('skips pixels outside the bitmap bounds', () => {
+    const img = createBitmap(2, 2, 0x000000ff);
+    fillBitmapRectangle(region(img, -1, -1, 4, 4), 0xffffffff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0xffffffff);
+    expect(getBitmapPixel(img, 1, 1)).toBe(0xffffffff);
+  });
+});
+
+describe('floodFillBitmap', () => {
+  it('fills a connected region', () => {
+    const img = createBitmap(3, 3, 0xffffffff);
+    floodFillBitmap(img, 0, 0, 0x000000ff);
+    for (let py = 0; py < 3; py++) {
+      for (let px = 0; px < 3; px++) {
+        expect(getBitmapPixel(img, px, py)).toBe(0x000000ff);
+      }
+    }
+  });
+
+  it('does not cross a barrier', () => {
+    const img = createBitmap(3, 3, 0xffffffff);
+    for (let py = 0; py < 3; py++) {
+      const i = (py * 3 + 1) * 4;
+      img.data[i] = 0;
+      img.data[i + 1] = 0;
+      img.data[i + 2] = 0;
+      img.data[i + 3] = 0xff;
+    }
+    floodFillBitmap(img, 0, 0, 0x0000ffff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0x0000ffff);
+    expect(getBitmapPixel(img, 2, 0)).toBe(0xffffffff);
+  });
+
+  it('is a no-op when fill color matches target', () => {
+    const img = createBitmap(2, 2, 0x112233ff);
+    floodFillBitmap(img, 0, 0, 0x112233ff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0x112233ff);
+  });
+
+  it('reuses the scratch buffer across calls', () => {
+    const img = createBitmap(4, 4, 0xffffffff);
+    floodFillBitmap(img, 0, 0, 0x000000ff);
+    floodFillBitmap(img, 0, 0, 0xffffffff); // second call reuses buffer
+    expect(getBitmapPixel(img, 0, 0)).toBe(0xffffffff);
+  });
+
+  it('reuses the scratch buffer across calls', () => {
+    const img = createBitmap(4, 4, 0xffffffff);
+    floodFillBitmap(img, 0, 0, 0x000000ff);
+    floodFillBitmap(img, 0, 0, 0xffffffff); // second call reuses buffer
+    expect(getBitmapPixel(img, 0, 0)).toBe(0xffffffff);
+  });
+});

package/src/bitmapFingerprint.test.ts

@@ -0,0 +1,103 @@
+import { createBitmap } from './bitmap';
+import {
+  compareBitmapFingerprints,
+  createBitmapFingerprint,
+  formatBitmapFingerprint,
+  parseBitmapFingerprint,
+} from './bitmapFingerprint';
+import { setBitmapPixel } from './bitmapPixel';
+
+describe('compareBitmapFingerprints', () => {
+  it('reports 0 for identical fingerprints', () => {
+    const fp = createBitmapFingerprint(createBitmap(8, 8, 0x336699ff), 4);
+    expect(compareBitmapFingerprints(fp, fp)).toBe(0);
+  });
+
+  it('reports the mean absolute per-channel difference', () => {
+    const a = createBitmapFingerprint(createBitmap(4, 4, 0x000000ff), 1);
+    const b = createBitmapFingerprint(createBitmap(4, 4, 0x0c0c0cff), 1);
+    // one cell, RGB all differ by 12 → mean abs diff 12
+    expect(compareBitmapFingerprints(a, b)).toBe(12);
+  });
+
+  it('throws when gridSizes differ', () => {
+    const a = createBitmapFingerprint(createBitmap(4, 4), 2);
+    const b = createBitmapFingerprint(createBitmap(4, 4), 4);
+    expect(() => compareBitmapFingerprints(a, b)).toThrow();
+  });
+
+  it('stays small for antialiasing-scale noise but large for a colour swap', () => {
+    const base = createBitmap(16, 16, 0x2040a0ff);
+    const noisy = createBitmap(16, 16, 0x2040a0ff);
+    setBitmapPixel(noisy, 0, 0, 0x2442a2ff); // a few pixels nudged
+    setBitmapPixel(noisy, 5, 5, 0x1e3e9eff);
+    const swapped = createBitmap(16, 16, 0xa04020ff); // whole image recoloured
+    const fp = createBitmapFingerprint(base, 16);
+    expect(compareBitmapFingerprints(fp, createBitmapFingerprint(noisy, 16))).toBeLessThan(2);
+    expect(compareBitmapFingerprints(fp, createBitmapFingerprint(swapped, 16))).toBeGreaterThan(50);
+  });
+});
+
+describe('createBitmapFingerprint', () => {
+  it('averages a solid bitmap to that colour in every cell', () => {
+    const fp = createBitmapFingerprint(createBitmap(8, 8, 0x336699ff), 4);
+    expect(fp.gridSize).toBe(4);
+    expect(fp.cells.length).toBe(4 * 4 * 3);
+    expect([fp.cells[0], fp.cells[1], fp.cells[2]]).toEqual([0x33, 0x66, 0x99]);
+    expect([fp.cells[fp.cells.length - 3], fp.cells[fp.cells.length - 2], fp.cells[fp.cells.length - 1]]).toEqual([
+      0x33, 0x66, 0x99,
+    ]);
+  });
+
+  it('places a coloured quadrant in the matching grid cell', () => {
+    const bitmap = createBitmap(2, 2, 0x000000ff);
+    setBitmapPixel(bitmap, 0, 0, 0xff0000ff); // top-left
+    const fp = createBitmapFingerprint(bitmap, 2);
+    expect([fp.cells[0], fp.cells[1], fp.cells[2]]).toEqual([255, 0, 0]); // cell (0,0)
+    expect([fp.cells[3], fp.cells[4], fp.cells[5]]).toEqual([0, 0, 0]); // cell (1,0)
+  });
+
+  it('throws on a non-positive gridSize', () => {
+    expect(() => createBitmapFingerprint(createBitmap(4, 4), 0)).toThrow();
+  });
+
+  it('returns an all-zero grid for an empty bitmap', () => {
+    const fp = createBitmapFingerprint(createBitmap(0, 0), 2);
+    expect(fp.cells.every((v) => v === 0)).toBe(true);
+  });
+});
+
+describe('formatBitmapFingerprint', () => {
+  it('round-trips through parseBitmapFingerprint', () => {
+    const bitmap = createBitmap(8, 8, 0x000000ff);
+    setBitmapPixel(bitmap, 1, 1, 0x12ab34ff);
+    setBitmapPixel(bitmap, 6, 6, 0xfe01dcff);
+    const fp = createBitmapFingerprint(bitmap, 4);
+    const parsed = parseBitmapFingerprint(formatBitmapFingerprint(fp));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.gridSize).toBe(4);
+    expect(Array.from(parsed!.cells)).toEqual(Array.from(fp.cells));
+    expect(compareBitmapFingerprints(fp, parsed!)).toBe(0);
+  });
+
+  it('encodes gridSize and lowercase hex cells', () => {
+    const fp = createBitmapFingerprint(createBitmap(4, 4, 0x0a0b0cff), 1);
+    expect(formatBitmapFingerprint(fp)).toBe('1:0a0b0c');
+  });
+});
+
+describe('parseBitmapFingerprint', () => {
+  it('returns null for malformed text', () => {
+    expect(parseBitmapFingerprint('garbage')).toBeNull();
+    expect(parseBitmapFingerprint('')).toBeNull();
+    expect(parseBitmapFingerprint('2:abcd')).toBeNull(); // wrong cell count for gridSize 2
+    expect(parseBitmapFingerprint('1:0a0b0')).toBeNull(); // odd hex length
+    expect(parseBitmapFingerprint('1:0a0b0z')).toBeNull(); // non-hex digit
+  });
+
+  it('parses a valid single-cell fingerprint', () => {
+    const parsed = parseBitmapFingerprint('1:0a0b0c');
+    expect(parsed).not.toBeNull();
+    expect(Array.from(parsed!.cells)).toEqual([0x0a, 0x0b, 0x0c]);
+  });
+});

package/src/bitmapFlip.test.ts

@@ -0,0 +1,53 @@
+import { createBitmap } from './bitmap';
+import { flipBitmapHorizontal, flipBitmapVertical } from './bitmapFlip';
+import { getBitmapPixel } 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 ramp(width: number, height: number) {
+  const bitmap = createBitmap(width, height);
+  for (let i = 0; i < width * height; i++) {
+    bitmap.data[i * 4] = i;
+    bitmap.data[i * 4 + 3] = 255;
+  }
+  return bitmap;
+}
+
+describe('flipBitmapHorizontal', () => {
+  it('mirrors columns left-to-right into a separate dest', () => {
+    const source = ramp(3, 1);
+    const out = createBitmap(3, 1);
+    flipBitmapHorizontal(region(out), region(source));
+    expect(out.data[0]).toBe(2);
+    expect(out.data[4]).toBe(1);
+    expect(out.data[8]).toBe(0);
+  });
+
+  it('mirrors in place when dest and source are the same region', () => {
+    const bitmap = ramp(4, 1);
+    flipBitmapHorizontal(region(bitmap), region(bitmap));
+    expect(bitmap.data[0]).toBe(3);
+    expect(bitmap.data[4]).toBe(2);
+    expect(bitmap.data[8]).toBe(1);
+    expect(bitmap.data[12]).toBe(0);
+  });
+});
+
+describe('flipBitmapVertical', () => {
+  it('mirrors rows top-to-bottom into a separate dest', () => {
+    const source = ramp(1, 3);
+    const out = createBitmap(1, 3);
+    flipBitmapVertical(region(out), region(source));
+    expect(getBitmapPixel(out, 0, 0)).toBe(getBitmapPixel(source, 0, 2));
+    expect(getBitmapPixel(out, 0, 2)).toBe(getBitmapPixel(source, 0, 0));
+  });
+
+  it('mirrors in place when dest and source are the same region', () => {
+    const bitmap = ramp(1, 4);
+    flipBitmapVertical(region(bitmap), region(bitmap));
+    expect(bitmap.data[0]).toBe(3);
+    expect(bitmap.data[12]).toBe(0);
+  });
+});

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,57 @@
+import { createImageResource } from '@flighthq/image/contract';
+
+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.width).toBe(8);
+    expect(bitmap.height).toBe(4);
+    expect(bitmap.data.length).toBe(8 * 4 * 4);
+  });
+});

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