@flighthq/surface 0.1.0

package/src/surfaceCopy.test.ts

@@ -0,0 +1,54 @@
+import { createSurface } from './surface';
+import { copySurfaceChannel, copySurfacePixels } from './surfaceCopy';
+import { ImageChannel } from './surfaceImageChannel';
+import { getSurfacePixel, 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('copySurfaceChannel', () => {
+  it('copies the red channel to the blue channel', () => {
+    const src = createSurface(2, 2);
+    src.data[0] = 0xab;
+    const dst = createSurface(2, 2);
+    copySurfaceChannel(region(dst), ImageChannel.Blue, region(src), ImageChannel.Red);
+    expect(dst.data[2]).toBe(src.data[0]);
+  });
+
+  it('copies the alpha channel independently', () => {
+    const src = createSurface(1, 1);
+    setSurfacePixel(src, 0, 0, 0x000000de);
+    const dst = createSurface(1, 1);
+    copySurfaceChannel(region(dst), ImageChannel.Alpha, region(src), ImageChannel.Alpha);
+    expect(dst.data[3]).toBe(0xde);
+  });
+});
+
+describe('copySurfacePixels', () => {
+  it('copies a region without alpha blend', () => {
+    const src = createSurface(2, 2, 0xaabbccff);
+    const dst = createSurface(4, 4);
+    copySurfacePixels(region(dst, 1, 1, 2, 2), region(src, 0, 0, 2, 2));
+    expect(getSurfacePixel(dst, 1, 1)).toBe(0xaabbccff);
+    expect(getSurfacePixel(dst, 0, 0)).toBe(0x00000000);
+  });
+
+  it('alpha-composites when composite is true', () => {
+    const src = createSurface(1, 1);
+    setSurfacePixel(src, 0, 0, 0xff000080);
+    const dst = createSurface(1, 1);
+    setSurfacePixel(dst, 0, 0, 0x0000ffff);
+    copySurfacePixels(region(dst), region(src), true);
+    const result = getSurfacePixel(dst, 0, 0);
+    expect(result & 0xff).toBe(0xff); // alpha opaque after composite
+    expect((result >>> 24) & 0xff).toBeGreaterThan(0); // red blended in
+    expect((result >> 8) & 0xff).toBeGreaterThan(0); // blue retained
+  });
+});

package/src/surfaceCoverage.test.ts

@@ -0,0 +1,39 @@
+import { createSurface } from './surface';
+import { getSurfaceCoverage } from './surfaceCoverage';
+import { setSurfacePixel } from './surfacePixel';
+
+describe('getSurfaceCoverage', () => {
+  it('returns 0 for a surface still entirely the background colour', () => {
+    expect(getSurfaceCoverage(createSurface(4, 4, 0x123456ff), 0x123456ff)).toBe(0);
+  });
+
+  it('returns 0 for a fully transparent surface against a transparent background', () => {
+    expect(getSurfaceCoverage(createSurface(4, 4, 0x00000000), 0x00000000)).toBe(0);
+  });
+
+  it('counts pixels that differ from the background on any channel', () => {
+    const surface = createSurface(2, 2, 0x000000ff);
+    setSurfacePixel(surface, 0, 0, 0xff0000ff);
+    expect(getSurfaceCoverage(surface, 0x000000ff)).toBe(0.25);
+  });
+
+  it('measures a fully painted surface as full coverage', () => {
+    const surface = createSurface(2, 2, 0x000000ff);
+    setSurfacePixel(surface, 0, 0, 0xffffffff);
+    setSurfacePixel(surface, 1, 0, 0xffffffff);
+    setSurfacePixel(surface, 0, 1, 0xffffffff);
+    setSurfacePixel(surface, 1, 1, 0xffffffff);
+    expect(getSurfaceCoverage(surface, 0x000000ff)).toBe(1);
+  });
+
+  it('ignores differences within the channel tolerance', () => {
+    const surface = createSurface(2, 1, 0x000000ff);
+    setSurfacePixel(surface, 0, 0, 0x050505ff); // 5 per channel
+    expect(getSurfaceCoverage(surface, 0x000000ff, 5)).toBe(0);
+    expect(getSurfaceCoverage(surface, 0x000000ff, 4)).toBe(0.5);
+  });
+
+  it('returns 0 for an empty surface', () => {
+    expect(getSurfaceCoverage(createSurface(0, 0), 0x000000ff)).toBe(0);
+  });
+});

package/src/surfaceCrop.test.ts

@@ -0,0 +1,116 @@
+import { createSurface } from './surface';
+import { cropSurface, extendSurface, trimSurface } from './surfaceCrop';
+import { getSurfacePixel, setSurfacePixel } from './surfacePixel';
+
+describe('cropSurface', () => {
+  it('returns a surface with the requested dimensions', () => {
+    const src = createSurface(10, 10, 0xff0000ff);
+    const out = cropSurface(src, { x: 2, y: 3, width: 4, height: 5 });
+    expect(out.width).toBe(4);
+    expect(out.height).toBe(5);
+  });
+
+  it('copies pixels from the source region', () => {
+    const src = createSurface(4, 4);
+    setSurfacePixel(src, 2, 1, 0x00ff00ff);
+    const out = cropSurface(src, { x: 2, y: 1, width: 2, height: 2 });
+    expect(getSurfacePixel(out, 0, 0)).toBe(0x00ff00ff);
+  });
+
+  it('fills pixels outside the source with transparent black', () => {
+    const src = createSurface(2, 2, 0xffffffff);
+    // Crop region extends beyond source.
+    const out = cropSurface(src, { x: 1, y: 1, width: 3, height: 3 });
+    // (0,0) is inside source — opaque white.
+    expect(getSurfacePixel(out, 0, 0)).toBe(0xffffffff);
+    // (2,2) is outside source — transparent black.
+    expect(getSurfacePixel(out, 2, 2)).toBe(0x00000000);
+  });
+
+  it('preserves source colorSpace and alphaType', () => {
+    const src = createSurface(2, 2, 0xff0000ff);
+    const out = cropSurface(src, { x: 0, y: 0, width: 2, height: 2 });
+    expect(out.colorSpace).toBe(src.colorSpace);
+    expect(out.alphaType).toBe(src.alphaType);
+  });
+
+  it('returns a distinct surface object', () => {
+    const src = createSurface(2, 2, 0xff0000ff);
+    const out = cropSurface(src, { x: 0, y: 0, width: 2, height: 2 });
+    expect(out).not.toBe(src);
+    expect(out.data).not.toBe(src.data);
+  });
+});
+
+describe('extendSurface', () => {
+  it('returns a surface padded by the correct number of pixels', () => {
+    const src = createSurface(2, 2, 0x0000ffff);
+    const out = extendSurface(src, 1, 2, 3, 4);
+    expect(out.width).toBe(2 + 1 + 3);
+    expect(out.height).toBe(2 + 2 + 4);
+  });
+
+  it('copies source pixels into the center region', () => {
+    const src = createSurface(2, 2, 0xabcdefff);
+    const out = extendSurface(src, 1, 1, 1, 1);
+    expect(getSurfacePixel(out, 1, 1)).toBe(0xabcdefff);
+  });
+
+  it('transparent edge mode fills padding with transparent black by default', () => {
+    const src = createSurface(2, 2, 0xff0000ff);
+    const out = extendSurface(src, 1, 1, 1, 1);
+    expect(getSurfacePixel(out, 0, 0)).toBe(0x00000000);
+  });
+
+  it('transparent edge mode uses fillColor when provided', () => {
+    const src = createSurface(2, 2, 0xff0000ff);
+    const out = extendSurface(src, 1, 1, 1, 1, 'transparent', 0xffffffff);
+    expect(getSurfacePixel(out, 0, 0)).toBe(0xffffffff);
+  });
+
+  it('clamp edge mode repeats border pixels in padding', () => {
+    const src = createSurface(2, 2, 0x0000ffff);
+    // Set a distinct border pixel.
+    setSurfacePixel(src, 0, 0, 0x123456ff);
+    const out = extendSurface(src, 1, 1, 0, 0, 'clamp');
+    // Top-left padding comes from source (0,0).
+    expect(getSurfacePixel(out, 0, 0)).toBe(0x123456ff);
+  });
+
+  it('wrap edge mode tiles the source in padding', () => {
+    const src = createSurface(2, 2);
+    setSurfacePixel(src, 0, 0, 0xff0000ff);
+    setSurfacePixel(src, 1, 0, 0x00ff00ff);
+    // Extend by 2 on the right → first padding column maps to source col 0.
+    const out = extendSurface(src, 0, 0, 2, 0, 'wrap');
+    expect(getSurfacePixel(out, 2, 0)).toBe(0xff0000ff);
+    expect(getSurfacePixel(out, 3, 0)).toBe(0x00ff00ff);
+  });
+});
+
+describe('trimSurface', () => {
+  it('removes transparent border rows and columns', () => {
+    const src = createSurface(5, 5);
+    // Only pixel (2,2) is non-transparent.
+    setSurfacePixel(src, 2, 2, 0xff0000ff);
+    const out = trimSurface(src);
+    expect(out.width).toBe(1);
+    expect(out.height).toBe(1);
+    expect(getSurfacePixel(out, 0, 0)).toBe(0xff0000ff);
+  });
+
+  it('returns a 1×1 transparent surface for a fully transparent input', () => {
+    const src = createSurface(3, 3);
+    const out = trimSurface(src);
+    expect(out.width).toBe(1);
+    expect(out.height).toBe(1);
+    expect(getSurfacePixel(out, 0, 0) & 0xff).toBe(0);
+  });
+
+  it('returns a surface equal to the source when there is no transparent border', () => {
+    const src = createSurface(2, 2, 0xff0000ff);
+    const out = trimSurface(src);
+    expect(out.width).toBe(2);
+    expect(out.height).toBe(2);
+  });
+});

package/src/surfaceDisplacement.test.ts

@@ -0,0 +1,142 @@
+import { createSurface } from './surface';
+import { displaceSurface } from './surfaceDisplacement';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+// A 3x1 strip: red | green | blue.
+function rgbStrip() {
+  const s = createSurface(3, 1);
+  s.data.set([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255]);
+  return s;
+}
+
+describe('displaceSurface', () => {
+  it('is a no-op copy when scaleX and scaleY are 0', () => {
+    const source = rgbStrip();
+    const map = createSurface(3, 1);
+    map.data.fill(128);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceSurface(out, region(source), { map: region(map), scaleX: 0, scaleY: 0, mode: 'clamp' });
+    // With zero scale, every output pixel samples from its exact position.
+    expect(out[0]).toBe(255); // px0 = red
+    expect(out[4 + 1]).toBe(255); // px1 = green
+    expect(out[8 + 2]).toBe(255); // px2 = blue
+  });
+
+  it('shifts the sample position by the scaled map displacement', () => {
+    // map value 255 → dx = (255/255 - 0.5) * 2 = +1.0 exactly; scaleX=2.
+    const source = rgbStrip();
+    const map = createSurface(3, 1);
+    map.data[0] = 255;
+    map.data[4] = 255;
+    map.data[8] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceSurface(out, region(source), {
+      map: region(map),
+      componentX: 0,
+      scaleX: 2,
+      scaleY: 0,
+      mode: 'clamp',
+    });
+    // px0←src1 (green), px1←src2 (blue), px2←src3 oob clamped to src2 (blue)
+    expect(out[1]).toBe(255); // green channel of px0
+    expect(out[4 + 2]).toBe(255); // blue channel of px1
+    expect(out[8 + 2]).toBe(255); // blue channel of px2 (clamped)
+  });
+
+  it("'color' mode fills out-of-range samples with fillColor", () => {
+    // Map value 255 with scaleX=4 → dx=+2; px2 samples at x=4 (oob)
+    const source = rgbStrip();
+    const map = createSurface(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceSurface(out, region(source), {
+      map: region(map),
+      scaleX: 4,
+      scaleY: 0,
+      mode: 'color',
+      fillColor: 0xff00ffff,
+    });
+    // px2 displaces to x=4 (out of range) → magenta fill
+    expect(out[2 * 4 + 0]).toBe(0xff);
+    expect(out[2 * 4 + 1]).toBe(0);
+    expect(out[2 * 4 + 2]).toBe(0xff);
+    expect(out[2 * 4 + 3]).toBe(255);
+  });
+
+  it("'ignore' mode keeps the undisplaced source pixel for out-of-range samples", () => {
+    // Map value 255 with scaleX=4 → px2 samples at x=4 (oob) → keep blue
+    const source = rgbStrip();
+    const map = createSurface(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceSurface(out, region(source), {
+      map: region(map),
+      scaleX: 4,
+      scaleY: 0,
+      mode: 'ignore',
+    });
+    // px2 displaces out of range → keeps src2 (blue) unchanged
+    expect(out[2 * 4 + 2]).toBe(255);
+    expect(out[2 * 4 + 3]).toBe(255);
+  });
+
+  it("edgeMode 'clamp' clamps out-of-range samples to the edge", () => {
+    const source = rgbStrip();
+    const map = createSurface(3, 1);
+    map.data[0] = 255;
+    map.data[4] = 255;
+    map.data[8] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceSurface(out, region(source), {
+      map: region(map),
+      componentX: 0,
+      scaleX: 2,
+      scaleY: 0,
+      edgeMode: 'clamp',
+    });
+    // px2 displaces to x=3 (oob) → clamped to x=2 (blue)
+    expect(out[8 + 2]).toBe(255);
+  });
+
+  it("edgeMode 'transparent' fills out-of-range samples with transparent black", () => {
+    const source = rgbStrip();
+    const map = createSurface(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceSurface(out, region(source), {
+      map: region(map),
+      scaleX: 4,
+      scaleY: 0,
+      edgeMode: 'transparent',
+    });
+    // px2 displaces to x=4 (oob) → transparent black
+    expect(out[2 * 4 + 0]).toBe(0);
+    expect(out[2 * 4 + 3]).toBe(0);
+  });
+
+  it('samples through the source region offset', () => {
+    // 4px [red, green, blue, white]; zero displacement over region (1,0,2,1) copies
+    // source pixels 1 and 2 (green, blue), proving the offset is applied.
+    const source = createSurface(4, 1);
+    source.data.set([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255]);
+    const map = createSurface(2, 1);
+    map.data.fill(128); // neutral — minimal displacement at scale=0
+    const out = new Uint8ClampedArray(2 * 4);
+    displaceSurface(out, region(source, 1, 0, 2, 1), {
+      map: region(map),
+      scaleX: 0,
+      scaleY: 0,
+    });
+    expect(out[1]).toBe(255); // green from source[1]
+    expect(out[4 + 2]).toBe(255); // blue from source[2]
+  });
+});

package/src/surfaceDissolve.test.ts

@@ -0,0 +1,99 @@
+import { createSurface } from './surface';
+import { dissolveSurfacePixels } from './surfaceDissolve';
+import { getSurfacePixel, setSurfacePixel } from './surfacePixel';
+import { createSurfaceRegion } from './surfaceRegion';
+
+function countChangedPixels(data: Readonly<Uint8ClampedArray>, original: Readonly<Uint8ClampedArray>): number {
+  let changed = 0;
+  for (let i = 0; i < data.length; i += 4) {
+    if (
+      data[i] !== original[i] ||
+      data[i + 1] !== original[i + 1] ||
+      data[i + 2] !== original[i + 2] ||
+      data[i + 3] !== original[i + 3]
+    ) {
+      changed++;
+    }
+  }
+  return changed;
+}
+
+describe('dissolveSurfacePixels', () => {
+  it('dissolves at most pixelCount pixels per call', () => {
+    const source = createSurface(4, 4, 0x112233ff);
+    const dest = createSurface(4, 4, 0x00000000);
+    const original = dest.data.slice();
+    dissolveSurfacePixels(createSurfaceRegion(dest), createSurfaceRegion(source), 0, 5);
+    expect(countChangedPixels(dest.data, original)).toBe(5);
+  });
+
+  it('eventually covers every pixel exactly once so dest matches source', () => {
+    const source = createSurface(5, 3);
+    for (let i = 0; i < 5 * 3; i++) setSurfacePixel(source, i % 5, (i / 5) | 0, (0x01010100 * (i + 1)) >>> 0);
+    const dest = createSurface(5, 3, 0x00000000);
+    const sourceRegion = createSurfaceRegion(source);
+    const destRegion = createSurfaceRegion(dest);
+
+    let seed = 0;
+    for (let call = 0; call < 8; call++) seed = dissolveSurfacePixels(destRegion, sourceRegion, seed, 2);
+
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+  });
+
+  it('is deterministic for the same seed sequence', () => {
+    const source = createSurface(6, 6, 0xaabbccff);
+    const a = createSurface(6, 6, 0x00000000);
+    const b = createSurface(6, 6, 0x00000000);
+    const sourceRegion = createSurfaceRegion(source);
+    dissolveSurfacePixels(createSurfaceRegion(a), sourceRegion, 3, 7);
+    dissolveSurfacePixels(createSurfaceRegion(b), sourceRegion, 3, 7);
+    expect(Array.from(a.data)).toEqual(Array.from(b.data));
+  });
+
+  it('returns a terminal seed once fully dissolved that no-ops on reuse', () => {
+    const source = createSurface(4, 4, 0x445566ff);
+    const dest = createSurface(4, 4, 0x00000000);
+    const sourceRegion = createSurfaceRegion(source);
+    const destRegion = createSurfaceRegion(dest);
+
+    let seed = 0;
+    for (let call = 0; call < 16; call++) seed = dissolveSurfacePixels(destRegion, sourceRegion, seed, 1);
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+
+    const afterComplete = dissolveSurfacePixels(destRegion, sourceRegion, seed, 4);
+    expect(afterComplete).toBe(seed);
+  });
+
+  it('dissolves toward fillColor when source and dest are the same region', () => {
+    const surface = createSurface(3, 3, 0x112233ff);
+    const region = createSurfaceRegion(surface);
+    let seed = 0;
+    for (let call = 0; call < 9; call++) seed = dissolveSurfacePixels(region, region, seed, 1, 0x99887766);
+    for (let i = 0; i < 9; i++) expect(getSurfacePixel(surface, i % 3, (i / 3) | 0)).toBe(0x99887766);
+  });
+
+  it('ignores fillColor and copies from source when regions differ', () => {
+    const source = createSurface(2, 2, 0x0a0b0c0d);
+    const dest = createSurface(2, 2, 0x00000000);
+    let seed = 0;
+    for (let call = 0; call < 4; call++) {
+      seed = dissolveSurfacePixels(createSurfaceRegion(dest), createSurfaceRegion(source), seed, 1, 0xffffffff);
+    }
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+  });
+
+  it('returns the seed unchanged for a non-positive pixelCount without writing', () => {
+    const source = createSurface(4, 4, 0x112233ff);
+    const dest = createSurface(4, 4, 0x00000000);
+    const original = dest.data.slice();
+    expect(dissolveSurfacePixels(createSurfaceRegion(dest), createSurfaceRegion(source), 2, 0)).toBe(2);
+    expect(countChangedPixels(dest.data, original)).toBe(0);
+  });
+
+  it('returns the seed for a zero-area region', () => {
+    const source = createSurface(4, 4, 0x112233ff);
+    const dest = createSurface(4, 4, 0x00000000);
+    const region = createSurfaceRegion(dest, 0, 0, 0, 0);
+    expect(dissolveSurfacePixels(region, createSurfaceRegion(source), 5, 10)).toBe(5);
+  });
+});

package/src/surfaceDraw.test.ts

@@ -0,0 +1,38 @@
+import { createSurface } from './surface';
+import { drawSurface } from './surfaceDraw';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+describe('drawSurface', () => {
+  it('does not throw when drawing onto a canvas', () => {
+    const src = createSurface(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    expect(() => drawSurface(canvas, region(src), 0, 0)).not.toThrow();
+  });
+
+  it('does not throw when drawing at an offset', () => {
+    const src = createSurface(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 8;
+    expect(() => drawSurface(canvas, region(src), 2, 2)).not.toThrow();
+  });
+
+  it('is a no-op for a zero-dimension region', () => {
+    const src = createSurface(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    expect(() => drawSurface(canvas, region(src, 0, 0, 0, 0), 0, 0)).not.toThrow();
+  });
+});

package/src/surfaceEncode.test.ts

@@ -0,0 +1,18 @@
+import { createSurface } from './surface';
+import { encodeSurface } from './surfaceEncode';
+
+describe('encodeSurface', () => {
+  it('returns a non-empty Uint8Array for a simple image', () => {
+    const img = createSurface(2, 2, 0x112233ff);
+    const bytes = encodeSurface(img);
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBeGreaterThan(0);
+  });
+
+  it('accepts jpeg format', () => {
+    const img = createSurface(2, 2, 0x112233ff);
+    const bytes = encodeSurface(img, 'jpeg');
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBeGreaterThan(0);
+  });
+});

package/src/surfaceFill.test.ts

@@ -0,0 +1,89 @@
+import { createSurface } from './surface';
+import { fillSurfaceRectangle, floodFillSurface } from './surfaceFill';
+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 };
+}
+
+describe('fillSurfaceRectangle', () => {
+  it('fills the specified region', () => {
+    const img = createSurface(4, 4);
+    fillSurfaceRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(getSurfacePixel(img, 1, 1)).toBe(0xaabbccff);
+    expect(getSurfacePixel(img, 2, 2)).toBe(0xaabbccff);
+  });
+
+  it('bumps the surface version (self-invalidation)', () => {
+    const img = createSurface(4, 4);
+    const before = img.version;
+    fillSurfaceRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(img.version).toBe(before + 1);
+  });
+
+  it('does not affect pixels outside the region', () => {
+    const img = createSurface(4, 4);
+    fillSurfaceRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(getSurfacePixel(img, 0, 0)).toBe(0x00000000);
+    expect(getSurfacePixel(img, 3, 3)).toBe(0x00000000);
+  });
+
+  it('skips pixels outside the surface bounds', () => {
+    const img = createSurface(2, 2, 0x000000ff);
+    fillSurfaceRectangle(region(img, -1, -1, 4, 4), 0xffffffff);
+    expect(getSurfacePixel(img, 0, 0)).toBe(0xffffffff);
+    expect(getSurfacePixel(img, 1, 1)).toBe(0xffffffff);
+  });
+});
+
+describe('floodFillSurface', () => {
+  it('fills a connected region', () => {
+    const img = createSurface(3, 3, 0xffffffff);
+    floodFillSurface(img, 0, 0, 0x000000ff);
+    for (let py = 0; py < 3; py++) {
+      for (let px = 0; px < 3; px++) {
+        expect(getSurfacePixel(img, px, py)).toBe(0x000000ff);
+      }
+    }
+  });
+
+  it('does not cross a barrier', () => {
+    const img = createSurface(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;
+    }
+    floodFillSurface(img, 0, 0, 0x0000ffff);
+    expect(getSurfacePixel(img, 0, 0)).toBe(0x0000ffff);
+    expect(getSurfacePixel(img, 2, 0)).toBe(0xffffffff);
+  });
+
+  it('is a no-op when fill color matches target', () => {
+    const img = createSurface(2, 2, 0x112233ff);
+    floodFillSurface(img, 0, 0, 0x112233ff);
+    expect(getSurfacePixel(img, 0, 0)).toBe(0x112233ff);
+  });
+
+  it('reuses the scratch buffer across calls', () => {
+    const img = createSurface(4, 4, 0xffffffff);
+    floodFillSurface(img, 0, 0, 0x000000ff);
+    floodFillSurface(img, 0, 0, 0xffffffff); // second call reuses buffer
+    expect(getSurfacePixel(img, 0, 0)).toBe(0xffffffff);
+  });
+
+  it('reuses the scratch buffer across calls', () => {
+    const img = createSurface(4, 4, 0xffffffff);
+    floodFillSurface(img, 0, 0, 0x000000ff);
+    floodFillSurface(img, 0, 0, 0xffffffff); // second call reuses buffer
+    expect(getSurfacePixel(img, 0, 0)).toBe(0xffffffff);
+  });
+});