@flighthq/surface 0.1.0

package/src/surfaceColorMatrix.test.ts

@@ -0,0 +1,220 @@
+import { createSurface } from './surface';
+import {
+  buildSurfaceBrightnessColorMatrix,
+  buildSurfaceContrastColorMatrix,
+  buildSurfaceGrayscaleColorMatrix,
+  buildSurfaceHueRotationColorMatrix,
+  buildSurfaceInvertColorMatrix,
+  buildSurfaceSaturationColorMatrix,
+  buildSurfaceSepiaColorMatrix,
+  colorMatrixSurface,
+  concatSurfaceColorMatrix,
+  setSurfaceColorMatrixIdentity,
+} from './surfaceColorMatrix';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+// Build a 1x1 surface, apply `matrix`, and return its RGBA bytes.
+function applyTo(rgba: number, matrix: ReadonlyArray<number>): Uint8ClampedArray {
+  const surface = createSurface(1, 1, rgba);
+  const out = new Uint8ClampedArray(4);
+  colorMatrixSurface(out, region(surface), matrix);
+  return out;
+}
+
+describe('buildSurfaceBrightnessColorMatrix', () => {
+  it('multiplies RGB by the amount', () => {
+    const m = new Array<number>(20);
+    buildSurfaceBrightnessColorMatrix(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('buildSurfaceContrastColorMatrix', () => {
+  it('amount 0 flattens every channel to mid grey', () => {
+    const m = new Array<number>(20);
+    buildSurfaceContrastColorMatrix(m, 0);
+    const out = applyTo(0xc80000ff, m); // R=200
+    expect(out[0]).toBe(128); // round(127.5)
+    expect(out[1]).toBe(128);
+  });
+});
+
+describe('buildSurfaceGrayscaleColorMatrix', () => {
+  it('maps pure red to its luma in every channel', () => {
+    const m = new Array<number>(20);
+    buildSurfaceGrayscaleColorMatrix(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('buildSurfaceHueRotationColorMatrix', () => {
+  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
+    buildSurfaceHueRotationColorMatrix(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);
+    buildSurfaceHueRotationColorMatrix(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);
+    buildSurfaceHueRotationColorMatrix(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('buildSurfaceInvertColorMatrix', () => {
+  it('inverts RGB and preserves alpha', () => {
+    const m = new Array<number>(20);
+    buildSurfaceInvertColorMatrix(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('buildSurfaceSaturationColorMatrix', () => {
+  it('amount 1 is identity', () => {
+    const m = new Array<number>(20);
+    buildSurfaceSaturationColorMatrix(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);
+    buildSurfaceSaturationColorMatrix(m, 0);
+    const out = applyTo(0xff0000ff, m);
+    expect(out[0]).toBe(54);
+    expect(out[1]).toBe(54);
+  });
+});
+
+describe('buildSurfaceSepiaColorMatrix', () => {
+  it('maps pure red to the sepia tone', () => {
+    const m = new Array<number>(20);
+    buildSurfaceSepiaColorMatrix(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('colorMatrixSurface', () => {
+  it('applies a 4x5 color matrix to the source region', () => {
+    const source = createSurface(1, 1, 0x204060ff);
+    const out = new Uint8ClampedArray(4);
+    colorMatrixSurface(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.surface.data for a full-surface region', () => {
+    const surface = createSurface(1, 1, 0x010203ff);
+    colorMatrixSurface(surface.data, region(surface), [1, 0, 0, 0, 10, 0, 1, 0, 0, 20, 0, 0, 1, 0, 30, 0, 0, 0, 1, 0]);
+    expect(surface.data[0]).toBe(11);
+    expect(surface.data[1]).toBe(22);
+    expect(surface.data[2]).toBe(33);
+    expect(surface.data[3]).toBe(0xff);
+  });
+
+  it('clamps output to [0, 255]', () => {
+    const source = createSurface(1, 1, 0xff0000ff);
+    const out = new Uint8ClampedArray(4);
+    colorMatrixSurface(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 = createSurface(1, 1);
+    const out = new Uint8ClampedArray(4);
+    expect(() => colorMatrixSurface(out, region(source), [])).toThrow('Color matrix filter requires 20 values');
+  });
+
+  it('silently skips pixels outside source bounds', () => {
+    const source = createSurface(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];
+    colorMatrixSurface(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('concatSurfaceColorMatrix', () => {
+  it('composes two matrices (apply first, then second)', () => {
+    const bright2 = new Array<number>(20);
+    const half = new Array<number>(20);
+    buildSurfaceBrightnessColorMatrix(bright2, 2);
+    buildSurfaceBrightnessColorMatrix(half, 0.5);
+    const out = new Array<number>(20);
+    concatSurfaceColorMatrix(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);
+    setSurfaceColorMatrixIdentity(identity);
+    buildSurfaceInvertColorMatrix(invert);
+    const out = new Array<number>(20);
+    concatSurfaceColorMatrix(out, identity, invert);
+    const pixel = applyTo(0xc80000ff, out); // R=200 -> 55
+    expect(pixel[0]).toBe(55);
+  });
+});
+
+describe('setSurfaceColorMatrixIdentity', () => {
+  it('leaves the pixel unchanged', () => {
+    const m = new Array<number>(20);
+    setSurfaceColorMatrixIdentity(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/surfaceCompare.test.ts

@@ -0,0 +1,92 @@
+import type { Surface } from '@flighthq/types';
+
+import { cloneSurface, createSurface } from './surface';
+import { compareSurface, getSurfaceMismatch } from './surfaceCompare';
+import { setSurfacePixel } from './surfacePixel';
+
+describe('compareSurface', () => {
+  it('throws when widths differ', () => {
+    const a = createSurface(4, 4);
+    const b = createSurface(8, 4);
+    expect(() => compareSurface(a, b)).toThrow();
+  });
+
+  it('throws when heights differ', () => {
+    const a = createSurface(4, 4);
+    const b = createSurface(4, 8);
+    expect(() => compareSurface(a, b)).toThrow();
+  });
+
+  it('returns null for identical images', () => {
+    const a = createSurface(4, 4, 0x0000ffff);
+    const b = cloneSurface(a);
+    expect(compareSurface(a, b)).toBeNull();
+  });
+
+  it('returns diff Surface for different pixels', () => {
+    const a = createSurface(2, 1, 0x000000ff);
+    const b = createSurface(2, 1, 0x000000ff);
+    setSurfacePixel(b, 0, 0, 0x102030ff);
+    const result = compareSurface(a, b) as Surface;
+    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 = createSurface(1, 1, 0x000000ff);
+    const b = createSurface(1, 1, 0x00000080);
+    const result = compareSurface(a, b) as Surface;
+    expect(result.data[3]).toBe(255);
+  });
+
+  it('unchanged pixels in diff have zero alpha', () => {
+    const a = createSurface(2, 1, 0x000000ff);
+    const b = cloneSurface(a);
+    setSurfacePixel(b, 1, 0, 0xff0000ff);
+    const result = compareSurface(a, b) as Surface;
+    expect(result.data[3]).toBe(0);
+    expect(result.data[7]).toBe(255);
+  });
+});
+
+describe('getSurfaceMismatch', () => {
+  it('throws when dimensions differ', () => {
+    expect(() => getSurfaceMismatch(createSurface(4, 4), createSurface(4, 8))).toThrow();
+  });
+
+  it('reports zero mismatch for identical surfaces', () => {
+    const a = createSurface(4, 4, 0x0000ffff);
+    const result = getSurfaceMismatch(a, cloneSurface(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 = createSurface(2, 1, 0x000000ff);
+    const b = createSurface(2, 1, 0x000000ff);
+    setSurfacePixel(b, 0, 0, 0x0a0000ff); // delta 10 on one channel
+    expect(getSurfaceMismatch(a, b, 0).mismatchedPixels).toBe(1);
+    expect(getSurfaceMismatch(a, b, 9).mismatchedPixels).toBe(1);
+    expect(getSurfaceMismatch(a, b, 10).mismatchedPixels).toBe(0); // within tolerance
+  });
+
+  it('reports the largest channel delta and the mismatch fraction', () => {
+    const a = createSurface(2, 1, 0x000000ff);
+    const b = createSurface(2, 1, 0x000000ff);
+    setSurfacePixel(b, 1, 0, 0x804020ff); // max delta 0x80 = 128
+    const result = getSurfaceMismatch(a, b);
+    expect(result.maxChannelDelta).toBe(128);
+    expect(result.mismatchedPixels).toBe(1);
+    expect(result.fraction).toBe(0.5);
+  });
+});

package/src/surfaceComposite.test.ts

@@ -0,0 +1,256 @@
+import { BlendMode } from '@flighthq/types';
+
+import { createSurface } from './surface';
+import {
+  compositeSurfacePixels,
+  compositeSurfaceRegion,
+  extractSurfacePixels,
+  extractSurfacePixels32,
+  writeSurfacePixels,
+  writeSurfacePixels32,
+} from './surfaceComposite';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+describe('compositeSurfacePixels', () => {
+  it('alpha-composites pixels over the destination', () => {
+    const dest = createSurface(1, 1, 0x0000ffff);
+    const pixels = new Uint8ClampedArray([0xff, 0, 0, 0xff]);
+    compositeSurfacePixels(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 = createSurface(1, 1, 0x000000ff);
+    const pixels = new Uint8ClampedArray([0xff, 0xff, 0xff, 0x80]);
+    compositeSurfacePixels(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 = createSurface(1, 1);
+    const pixels = new Uint8ClampedArray([0xff, 0xff, 0xff, 0xff]);
+    compositeSurfacePixels(region(dest, 5, 5, 1, 1), pixels);
+    expect(dest.data[3]).toBe(0);
+  });
+
+  it('multiply blend mode multiplies source and destination channels', () => {
+    const dest = createSurface(1, 1, 0xff0000ff); // RGBA: opaque red
+    const pixels = new Uint8ClampedArray([128, 128, 128, 255]);
+    compositeSurfacePixels(region(dest), pixels, BlendMode.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 = createSurface(1, 1, 0x640000ff); // RGBA: opaque dark red (R=100)
+    const pixels = new Uint8ClampedArray([200, 0, 0, 255]);
+    compositeSurfacePixels(region(dest), pixels, BlendMode.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 = createSurface(1, 1, 0xff0000ff); // RGBA: opaque red
+    const pixels = new Uint8ClampedArray([0, 0, 255, 255]);
+    compositeSurfacePixels(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 = createSurface(1, 1, 0x400000ff); // RGBA: R=64
+    const pixels = new Uint8ClampedArray([200, 0, 0, 255]);
+    compositeSurfacePixels(region(dest), pixels, BlendMode.Overlay);
+    expect(dest.data[0]).toBe(100); // 2 * 64 * 200 / 255
+  });
+
+  it('hardlight blend mode is overlay with operands swapped', () => {
+    const dest = createSurface(1, 1, 0xc80000ff); // RGBA: R=200
+    const pixels = new Uint8ClampedArray([64, 0, 0, 255]);
+    compositeSurfacePixels(region(dest), pixels, BlendMode.Hardlight);
+    expect(dest.data[0]).toBe(100); // 2 * 200 * 64 / 255
+  });
+
+  it('invert blend mode inverts the backdrop, ignoring source color', () => {
+    const dest = createSurface(1, 1, 0xc80000ff); // RGBA: R=200
+    const pixels = new Uint8ClampedArray([0, 0, 0, 255]);
+    compositeSurfacePixels(region(dest), pixels, BlendMode.Invert);
+    expect(dest.data[0]).toBe(55); // 255 - 200
+  });
+
+  it('erase blend mode knocks alpha out of the backdrop, keeping color', () => {
+    const dest = createSurface(1, 1, 0xff0000ff); // RGBA: opaque red
+    const pixels = new Uint8ClampedArray([0, 0, 0, 128]);
+    compositeSurfacePixels(region(dest), pixels, BlendMode.Erase);
+    expect(dest.data[0]).toBe(255); // color untouched
+    expect(dest.data[3]).toBe(127); // 255 * (1 - 128/255)
+  });
+
+  it('throws for blend modes with no surface meaning', () => {
+    const dest = createSurface(1, 1);
+    const pixels = new Uint8ClampedArray([0, 0, 0, 255]);
+    expect(() => compositeSurfacePixels(region(dest), pixels, BlendMode.Shader)).toThrow(/not supported/);
+    expect(() => compositeSurfacePixels(region(dest), pixels, BlendMode.Alpha)).toThrow(/not supported/);
+  });
+});
+
+describe('compositeSurfaceRegion', () => {
+  it('alpha-composites a region of one surface over another', () => {
+    const source = createSurface(1, 1, 0xff0000ff);
+    const dest = createSurface(1, 1, 0x0000ffff);
+    compositeSurfaceRegion(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 = createSurface(1, 1, 0xff0000ff);
+    const dest = createSurface(3, 3);
+    compositeSurfaceRegion(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 = createSurface(1, 1, 0x808080ff); // RGBA: opaque gray
+    const dest = createSurface(1, 1, 0xff0000ff); // RGBA: opaque red
+    compositeSurfaceRegion(region(dest), region(source), BlendMode.Multiply);
+    expect(dest.data[0]).toBe(128); // 255 * 128 / 255
+    expect(dest.data[1]).toBe(0);
+  });
+});
+
+describe('extractSurfacePixels', () => {
+  it('copies a surface region into a tightly-packed buffer', () => {
+    const source = createSurface(2, 2);
+    const i = (1 * 2 + 1) * 4;
+    source.data[i] = 0xff;
+    source.data[i + 3] = 0xff;
+    const out = new Uint8ClampedArray(4);
+    extractSurfacePixels(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 = createSurface(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4 * 4);
+    extractSurfacePixels(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.surface.data can be passed as out for a full-surface extraction', () => {
+    const source = createSurface(2, 2, 0xaabbccff);
+    extractSurfacePixels(source.data, region(source));
+    expect(source.data[0]).toBe(0xaa);
+    expect(source.data[3]).toBe(0xff);
+  });
+});
+
+describe('extractSurfacePixels32', () => {
+  it('packs each pixel into one 0xRRGGBBAA entry', () => {
+    const source = createSurface(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);
+    extractSurfacePixels32(out, region(source, 1, 1, 1, 1));
+    expect(out[0]).toBe(0x11223344);
+  });
+
+  it('round-trips with writeSurfacePixels32', () => {
+    const source = createSurface(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);
+    extractSurfacePixels32(packed, region(source));
+    const dest = createSurface(3, 2);
+    writeSurfacePixels32(region(dest), packed);
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+  });
+
+  it('silently skips pixels outside source bounds', () => {
+    const source = createSurface(1, 1, 0xffffffff);
+    const out = new Uint32Array(4);
+    extractSurfacePixels32(out, region(source, -1, -1, 2, 2));
+    expect(out[1 * 2 + 1]).toBe(0xffffffff);
+    expect(out[0]).toBe(0);
+  });
+});
+
+describe('writeSurfacePixels', () => {
+  it('writes pixels at the given destination region', () => {
+    const dest = createSurface(3, 3);
+    const pixels = new Uint8ClampedArray([0x33, 0x66, 0x99, 0xff]);
+    writeSurfacePixels(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 = createSurface(1, 1, 0x0000ffff);
+    const pixels = new Uint8ClampedArray([0xff, 0, 0, 0xff]);
+    writeSurfacePixels(region(dest), pixels);
+    expect(dest.data[2]).toBe(0);
+    expect(dest.data[0]).toBe(0xff);
+  });
+
+  it('silently clips writes outside destination bounds', () => {
+    const dest = createSurface(1, 1);
+    const pixels = new Uint8ClampedArray([0xff, 0xff, 0xff, 0xff]);
+    writeSurfacePixels(region(dest, 5, 5, 1, 1), pixels);
+    expect(dest.data[3]).toBe(0);
+  });
+});
+
+describe('writeSurfacePixels32', () => {
+  it('unpacks each 0xRRGGBBAA entry into the destination region', () => {
+    const dest = createSurface(3, 3);
+    writeSurfacePixels32(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 = createSurface(1, 1, 0x0000ffff);
+    writeSurfacePixels32(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 = createSurface(1, 1);
+    writeSurfacePixels32(region(dest, 5, 5, 1, 1), new Uint32Array([0xffffffff]));
+    expect(dest.data[3]).toBe(0);
+  });
+});

package/src/surfaceConvolution.test.ts

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