@flighthq/surface 0.1.0

package/src/surfaceFingerprint.test.ts

@@ -0,0 +1,103 @@
+import { createSurface } from './surface';
+import {
+  compareSurfaceFingerprints,
+  createSurfaceFingerprint,
+  formatSurfaceFingerprint,
+  parseSurfaceFingerprint,
+} from './surfaceFingerprint';
+import { setSurfacePixel } from './surfacePixel';
+
+describe('compareSurfaceFingerprints', () => {
+  it('reports 0 for identical fingerprints', () => {
+    const fp = createSurfaceFingerprint(createSurface(8, 8, 0x336699ff), 4);
+    expect(compareSurfaceFingerprints(fp, fp)).toBe(0);
+  });
+
+  it('reports the mean absolute per-channel difference', () => {
+    const a = createSurfaceFingerprint(createSurface(4, 4, 0x000000ff), 1);
+    const b = createSurfaceFingerprint(createSurface(4, 4, 0x0c0c0cff), 1);
+    // one cell, RGB all differ by 12 → mean abs diff 12
+    expect(compareSurfaceFingerprints(a, b)).toBe(12);
+  });
+
+  it('throws when gridSizes differ', () => {
+    const a = createSurfaceFingerprint(createSurface(4, 4), 2);
+    const b = createSurfaceFingerprint(createSurface(4, 4), 4);
+    expect(() => compareSurfaceFingerprints(a, b)).toThrow();
+  });
+
+  it('stays small for antialiasing-scale noise but large for a colour swap', () => {
+    const base = createSurface(16, 16, 0x2040a0ff);
+    const noisy = createSurface(16, 16, 0x2040a0ff);
+    setSurfacePixel(noisy, 0, 0, 0x2442a2ff); // a few pixels nudged
+    setSurfacePixel(noisy, 5, 5, 0x1e3e9eff);
+    const swapped = createSurface(16, 16, 0xa04020ff); // whole image recoloured
+    const fp = createSurfaceFingerprint(base, 16);
+    expect(compareSurfaceFingerprints(fp, createSurfaceFingerprint(noisy, 16))).toBeLessThan(2);
+    expect(compareSurfaceFingerprints(fp, createSurfaceFingerprint(swapped, 16))).toBeGreaterThan(50);
+  });
+});
+
+describe('createSurfaceFingerprint', () => {
+  it('averages a solid surface to that colour in every cell', () => {
+    const fp = createSurfaceFingerprint(createSurface(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 surface = createSurface(2, 2, 0x000000ff);
+    setSurfacePixel(surface, 0, 0, 0xff0000ff); // top-left
+    const fp = createSurfaceFingerprint(surface, 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(() => createSurfaceFingerprint(createSurface(4, 4), 0)).toThrow();
+  });
+
+  it('returns an all-zero grid for an empty surface', () => {
+    const fp = createSurfaceFingerprint(createSurface(0, 0), 2);
+    expect(fp.cells.every((v) => v === 0)).toBe(true);
+  });
+});
+
+describe('formatSurfaceFingerprint', () => {
+  it('round-trips through parseSurfaceFingerprint', () => {
+    const surface = createSurface(8, 8, 0x000000ff);
+    setSurfacePixel(surface, 1, 1, 0x12ab34ff);
+    setSurfacePixel(surface, 6, 6, 0xfe01dcff);
+    const fp = createSurfaceFingerprint(surface, 4);
+    const parsed = parseSurfaceFingerprint(formatSurfaceFingerprint(fp));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.gridSize).toBe(4);
+    expect(Array.from(parsed!.cells)).toEqual(Array.from(fp.cells));
+    expect(compareSurfaceFingerprints(fp, parsed!)).toBe(0);
+  });
+
+  it('encodes gridSize and lowercase hex cells', () => {
+    const fp = createSurfaceFingerprint(createSurface(4, 4, 0x0a0b0cff), 1);
+    expect(formatSurfaceFingerprint(fp)).toBe('1:0a0b0c');
+  });
+});
+
+describe('parseSurfaceFingerprint', () => {
+  it('returns null for malformed text', () => {
+    expect(parseSurfaceFingerprint('garbage')).toBeNull();
+    expect(parseSurfaceFingerprint('')).toBeNull();
+    expect(parseSurfaceFingerprint('2:abcd')).toBeNull(); // wrong cell count for gridSize 2
+    expect(parseSurfaceFingerprint('1:0a0b0')).toBeNull(); // odd hex length
+    expect(parseSurfaceFingerprint('1:0a0b0z')).toBeNull(); // non-hex digit
+  });
+
+  it('parses a valid single-cell fingerprint', () => {
+    const parsed = parseSurfaceFingerprint('1:0a0b0c');
+    expect(parsed).not.toBeNull();
+    expect(Array.from(parsed!.cells)).toEqual([0x0a, 0x0b, 0x0c]);
+  });
+});

package/src/surfaceFlip.test.ts

@@ -0,0 +1,59 @@
+import { createSurface } from './surface';
+import { flipSurfaceHorizontal, flipSurfaceVertical } from './surfaceFlip';
+import { getSurfacePixel } from './surfacePixel';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+function ramp(width: number, height: number) {
+  const surface = createSurface(width, height);
+  for (let i = 0; i < width * height; i++) {
+    surface.data[i * 4] = i;
+    surface.data[i * 4 + 3] = 255;
+  }
+  return surface;
+}
+
+describe('flipSurfaceHorizontal', () => {
+  it('mirrors columns left-to-right into a separate dest', () => {
+    const source = ramp(3, 1);
+    const out = createSurface(3, 1);
+    flipSurfaceHorizontal(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 surface = ramp(4, 1);
+    flipSurfaceHorizontal(region(surface), region(surface));
+    expect(surface.data[0]).toBe(3);
+    expect(surface.data[4]).toBe(2);
+    expect(surface.data[8]).toBe(1);
+    expect(surface.data[12]).toBe(0);
+  });
+});
+
+describe('flipSurfaceVertical', () => {
+  it('mirrors rows top-to-bottom into a separate dest', () => {
+    const source = ramp(1, 3);
+    const out = createSurface(1, 3);
+    flipSurfaceVertical(region(out), region(source));
+    expect(getSurfacePixel(out, 0, 0)).toBe(getSurfacePixel(source, 0, 2));
+    expect(getSurfacePixel(out, 0, 2)).toBe(getSurfacePixel(source, 0, 0));
+  });
+
+  it('mirrors in place when dest and source are the same region', () => {
+    const surface = ramp(1, 4);
+    flipSurfaceVertical(region(surface), region(surface));
+    expect(surface.data[0]).toBe(3);
+    expect(surface.data[12]).toBe(0);
+  });
+});

package/src/surfaceFormat.test.ts

@@ -0,0 +1,124 @@
+import { convertSurfacePixelOrder, premultiplySurfacePixels, unpremultiplySurfacePixels } from './surfaceFormat';
+
+describe('convertSurfacePixelOrder', () => {
+  it('is a no-op when from === to and out !== source', () => {
+    const source = new Uint8ClampedArray([0x11, 0x22, 0x33, 0xff]);
+    const out = new Uint8ClampedArray(4);
+    convertSurfacePixelOrder(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);
+    convertSurfacePixelOrder(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);
+    convertSurfacePixelOrder(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);
+    convertSurfacePixelOrder(tmp, source, 4, 'RGBA', 'BGRA');
+    convertSurfacePixelOrder(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]);
+    convertSurfacePixelOrder(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]);
+    convertSurfacePixelOrder(buf, buf, 4, 'RGBA', 'BGRA');
+    expect(buf[0]).toBe(0xcc);
+    expect(buf[2]).toBe(0xaa);
+  });
+});
+
+describe('premultiplySurfacePixels', () => {
+  it('scales RGB by alpha/255', () => {
+    const source = new Uint8ClampedArray([0xff, 0x80, 0x00, 0x80]);
+    const out = new Uint8ClampedArray(4);
+    premultiplySurfacePixels(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);
+    premultiplySurfacePixels(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);
+    premultiplySurfacePixels(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]);
+    premultiplySurfacePixels(buf, buf, 4);
+    expect(buf[0]).toBeCloseTo(0x80, 0);
+    expect(buf[3]).toBe(0x80);
+  });
+});
+
+describe('unpremultiplySurfacePixels', () => {
+  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);
+    premultiplySurfacePixels(premul, source, 4);
+    unpremultiplySurfacePixels(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);
+    unpremultiplySurfacePixels(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]);
+    unpremultiplySurfacePixels(buf, buf, 4);
+    expect(buf[0]).toBeCloseTo(0xff, 0);
+    expect(buf[3]).toBe(0x80);
+  });
+});

package/src/surfaceFrom.test.ts

@@ -0,0 +1,62 @@
+import { createImageResource } from '@flighthq/image';
+
+import { createSurface } from './surface';
+import {
+  createImageResourceFromSurface,
+  createSurfaceFromCanvas,
+  createSurfaceFromImageResource,
+  createSurfaceFromImageSource,
+} from './surfaceFrom';
+
+describe('createImageResourceFromSurface', () => {
+  it('returns an ImageResource with matching dimensions', () => {
+    const img = createSurface(4, 4, 0x112233ff);
+    const resource = createImageResourceFromSurface(img);
+    expect(resource.width).toBe(4);
+    expect(resource.height).toBe(4);
+    expect(resource.source).not.toBeNull();
+  });
+});
+
+describe('createSurfaceFromCanvas', () => {
+  it('returns Surface matching the canvas size', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    const data = createSurfaceFromCanvas(canvas);
+    expect(data.width).toBe(4);
+    expect(data.height).toBe(4);
+  });
+
+  it('returns a Surface with data length matching canvas pixels', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 8;
+    const data = createSurfaceFromCanvas(canvas);
+    expect(data.data.length).toBe(8 * 8 * 4);
+  });
+});
+
+describe('createSurfaceFromImageResource', () => {
+  it('returns Surface matching the resource dimensions', () => {
+    const resource = createImageResource();
+    resource.width = 4;
+    resource.height = 4;
+    resource.source = null;
+    const data = createSurfaceFromImageResource(resource);
+    expect(data.width).toBe(4);
+    expect(data.height).toBe(4);
+  });
+});
+
+describe('createSurfaceFromImageSource', () => {
+  it('captures a canvas image source at the given device size', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 4;
+    const surface = createSurfaceFromImageSource(canvas, 8, 4);
+    expect(surface.width).toBe(8);
+    expect(surface.height).toBe(4);
+    expect(surface.data.length).toBe(8 * 4 * 4);
+  });
+});

package/src/surfaceGradient.test.ts

@@ -0,0 +1,91 @@
+import { createSurface } from './surface';
+import { buildSurfaceGradientRamp, gradientBevelSurface, gradientGlowSurface } from './surfaceGradient';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+describe('buildSurfaceGradientRamp', () => {
+  it('places endpoints exactly and interpolates the middle', () => {
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildSurfaceGradientRamp(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);
+    buildSurfaceGradientRamp(ramp, [], [], []);
+    expect(ramp.every((v) => v === 0)).toBe(true);
+  });
+});
+
+describe('gradientBevelSurface', () => {
+  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 = createSurface(5, 1);
+    for (let x = 2; x < 5; x++) source.data[x * 4 + 3] = 255;
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildSurfaceGradientRamp(ramp, [0x000000, 0x808080, 0xffffff], [1, 0, 1], [0, 128, 255]);
+    const out = new Uint8ClampedArray(5 * 4);
+    const scratch = new Uint8ClampedArray(5 * 4);
+    gradientBevelSurface(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('gradientGlowSurface', () => {
+  it('indexes the ramp by the blurred alpha', () => {
+    // ramp: index 0 transparent green, 255 opaque green.
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildSurfaceGradientRamp(ramp, [0x00ff00, 0x00ff00], [0, 1], [0, 255]);
+    const source = createSurface(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    gradientGlowSurface(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);
+    buildSurfaceGradientRamp(ramp, [0x00ff00, 0x00ff00], [1, 1], [0, 255]);
+    const source = createSurface(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    gradientGlowSurface(out, scratch, region(source), ramp, { radiusX: 0, radiusY: 0, intensity: 0.5 });
+    expect(out[3]).toBe(128);
+  });
+
+  it('source.surface.data can be used as out for a full-surface region', () => {
+    const ramp = new Uint8ClampedArray(256 * 4);
+    buildSurfaceGradientRamp(ramp, [0x00ff00, 0x00ff00], [0, 1], [0, 255]);
+    const surface = createSurface(1, 1, 0xffffffff);
+    const scratch = new Uint8ClampedArray(4);
+    gradientGlowSurface(surface.data, scratch, region(surface), ramp, { radiusX: 0, radiusY: 0 });
+    expect(surface.data[1]).toBe(0xff);
+    expect(surface.data[3]).toBe(255);
+  });
+});

package/src/surfaceGradientFill.test.ts

@@ -0,0 +1,107 @@
+import { createSurface } from './surface';
+import { buildSurfaceGradientRamp } from './surfaceGradient';
+import { fillSurfaceLinearGradient, fillSurfaceRadialGradient } from './surfaceGradientFill';
+import { getSurfacePixel } from './surfacePixel';
+import { createSurfaceRegion } from './surfaceRegion';
+
+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;
+  buildSurfaceGradientRamp(
+    ramp,
+    [(aR << 16) | (aG << 8) | aB, (bR << 16) | (bG << 8) | bB],
+    [aA / 255, bA / 255],
+    [0, 255],
+  );
+  return ramp;
+}
+
+describe('fillSurfaceLinearGradient', () => {
+  it('fills leftmost pixel with the first stop color', () => {
+    const surf = createSurface(4, 1);
+    const region = createSurfaceRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillSurfaceLinearGradient(region, ramp, 0, 0, 3, 0);
+    const pixel = getSurfacePixel(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 = createSurface(4, 1);
+    const region = createSurfaceRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillSurfaceLinearGradient(region, ramp, 0, 0, 3, 0);
+    const pixel = getSurfacePixel(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 = createSurface(3, 1);
+    const region = createSurfaceRegion(surf);
+    const ramp = buildTwoStopRamp(0x000000ff, 0xffffffff);
+    fillSurfaceLinearGradient(region, ramp, 0, 0, 2, 0);
+    const mid = getSurfacePixel(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 = createSurface(5, 1);
+    const region = createSurfaceRegion(surf);
+    // Gradient from x=1 to x=3; pixels at x=0 and x=4 should get clamped stops.
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillSurfaceLinearGradient(region, ramp, 1, 0, 3, 0, 'pad');
+    const left = getSurfacePixel(surf, 0, 0);
+    const right = getSurfacePixel(surf, 4, 0);
+    expect((left >>> 24) & 0xff).toBe((getSurfacePixel(surf, 1, 0) >>> 24) & 0xff);
+    expect((right >> 8) & 0xff).toBe((getSurfacePixel(surf, 3, 0) >> 8) & 0xff);
+  });
+
+  it('skips pixels outside surface bounds', () => {
+    const surf = createSurface(2, 2);
+    // Region that extends outside surface — should not throw.
+    const region = { surface: surf, x: -1, y: 0, width: 4, height: 1 };
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    expect(() => fillSurfaceLinearGradient(region, ramp, 0, 0, 3, 0)).not.toThrow();
+  });
+});
+
+describe('fillSurfaceRadialGradient', () => {
+  it('center pixel gets the first stop color', () => {
+    const surf = createSurface(5, 5);
+    const region = createSurfaceRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    fillSurfaceRadialGradient(region, ramp, 2, 2, 2);
+    // Center is at distance 0, so t=0, gets first stop.
+    const pixel = getSurfacePixel(surf, 2, 2);
+    expect((pixel >>> 24) & 0xff).toBeCloseTo(0xff, -1);
+  });
+
+  it('pad spread clamps beyond radius to last stop', () => {
+    const surf = createSurface(9, 1);
+    const region = createSurfaceRegion(surf);
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    // Center at x=4, radius=2; pixels at x=0 and x=8 are far outside.
+    fillSurfaceRadialGradient(region, ramp, 4, 0, 2, 4, 0, 'pad');
+    const far = getSurfacePixel(surf, 0, 0);
+    // Should be clamped to last stop (blue).
+    expect((far >> 8) & 0xff).toBeCloseTo(0xff, -1);
+  });
+
+  it('skips pixels outside surface bounds', () => {
+    const surf = createSurface(2, 2);
+    const region = { surface: surf, x: -1, y: 0, width: 4, height: 1 };
+    const ramp = buildTwoStopRamp(0xff0000ff, 0x0000ffff);
+    expect(() => fillSurfaceRadialGradient(region, ramp, 1, 0, 2)).not.toThrow();
+  });
+});

package/src/surfaceHistogram.test.ts

@@ -0,0 +1,70 @@
+import { createSurface } from './surface';
+import { equalizeSurfaceHistogram, getSurfaceHistogram } from './surfaceHistogram';
+import { setSurfacePixel } from './surfacePixel';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+describe('equalizeSurfaceHistogram', () => {
+  it('spreads a narrow tonal range to fill 0..255', () => {
+    // All red values are either 0 or 128 — a compressed range.
+    const source = createSurface(2, 1);
+    setSurfacePixel(source, 0, 0, 0x000000ff);
+    setSurfacePixel(source, 1, 0, 0x808000ff);
+    const dest = createSurface(2, 1);
+    equalizeSurfaceHistogram(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 surface = createSurface(2, 1);
+    setSurfacePixel(surface, 0, 0, 0x000000ff);
+    setSurfacePixel(surface, 1, 0, 0xff0000ff);
+    expect(() => equalizeSurfaceHistogram(region(surface), region(surface))).not.toThrow();
+  });
+
+  it('preserves alpha unchanged', () => {
+    const source = createSurface(1, 1, 0x40404080);
+    const dest = createSurface(1, 1);
+    equalizeSurfaceHistogram(region(dest), region(source));
+    expect(dest.data[3]).toBe(0x80);
+  });
+});
+
+describe('getSurfaceHistogram', () => {
+  it('counts pixel values per channel', () => {
+    const surface = createSurface(2, 1);
+    setSurfacePixel(surface, 0, 0, 0x0a000000);
+    setSurfacePixel(surface, 1, 0, 0x0a0000ff);
+    const histogram = getSurfaceHistogram(region(surface));
+    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 surface = createSurface(2, 2, 0xffffffff);
+    const histogram = getSurfaceHistogram(region(surface, 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 surface = createSurface(2, 1);
+    setSurfacePixel(surface, 0, 0, 0x10000000);
+    setSurfacePixel(surface, 1, 0, 0x20000000);
+    const histogram = getSurfaceHistogram(region(surface, 1, 0, 1, 1));
+    expect(histogram.red[0x20]).toBe(1);
+    expect(histogram.red[0x10]).toBe(0);
+  });
+});

package/src/surfaceImageChannel.test.ts

@@ -0,0 +1,19 @@
+import { ImageChannel } from './surfaceImageChannel';
+
+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/surfaceMedian.test.ts

@@ -0,0 +1,45 @@
+import { createSurface } from './surface';
+import { medianSurface } from './surfaceMedian';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+describe('medianSurface', () => {
+  it('removes an isolated salt pixel without blurring', () => {
+    // 3x3 of black with a single white (R=255) center; the median is black.
+    const source = createSurface(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);
+    medianSurface(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 = createSurface(4, 1);
+    source.data[0] = 0;
+    source.data[4] = 0;
+    source.data[8] = 255;
+    source.data[12] = 255;
+    const out = new Uint8ClampedArray(4 * 4);
+    medianSurface(out, region(source), 1);
+    expect(out[4]).toBe(0);
+    expect(out[8]).toBe(255);
+  });
+
+  it('radius 0 copies the source', () => {
+    const source = createSurface(1, 1, 0x123456ff);
+    const out = new Uint8ClampedArray(4);
+    medianSurface(out, region(source), 0);
+    expect(out[0]).toBe(0x12);
+    expect(out[3]).toBe(0xff);
+  });
+});