@flighthq/surface 0.1.0

package/src/surfaceRotate.test.ts

@@ -0,0 +1,119 @@
+import { createSurface } from './surface';
+import { getSurfacePixel } from './surfacePixel';
+import {
+  rotateSurface,
+  rotateSurface180,
+  rotateSurfaceClockwise,
+  rotateSurfaceCounterClockwise,
+} from './surfaceRotate';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+// 2x1 surface: pixel (0,0) = A, pixel (1,0) = B.
+function ab() {
+  const surface = createSurface(2, 1);
+  surface.data.set([0xa0, 0, 0, 255], 0);
+  surface.data.set([0xb0, 0, 0, 255], 4);
+  return surface;
+}
+
+describe('rotateSurface', () => {
+  it('with angle 0 copies source into dest', () => {
+    const source = createSurface(3, 3, 0xff0000ff);
+    const out = createSurface(3, 3);
+    rotateSurface(region(out), region(source), 0);
+    expect(out.data[0]).toBe(0xff);
+    expect(out.data[3]).toBe(0xff);
+  });
+
+  it('with angle π reverses source similar to rotateSurface180', () => {
+    const source = ab();
+    const out = createSurface(2, 1);
+    rotateSurface(region(out), region(source), Math.PI);
+    // Bilinear introduces slight blending, so just check direction
+    expect(out.data[0]).toBeGreaterThan(out.data[4]); // B-side (brighter) on left
+  });
+
+  it('clamp edge mode (default) repeats edge pixels for out-of-bounds', () => {
+    const source = createSurface(1, 1, 0xff0000ff);
+    const out = createSurface(5, 5);
+    rotateSurface(region(out), region(source), 0);
+    // With clamp, all pixels map to the single source pixel
+    expect(out.data[(0 * 5 + 0) * 4 + 3]).toBe(0xff);
+    expect(out.data[(2 * 5 + 2) * 4 + 3]).toBe(0xff);
+  });
+
+  it('transparent edge mode writes transparent black for out-of-bounds', () => {
+    const source = createSurface(1, 1, 0xff0000ff);
+    const out = createSurface(5, 5);
+    rotateSurface(region(out), region(source), 0, undefined, undefined, 'transparent');
+    // Only center pixel maps back to source; corners are out of bounds
+    expect(out.data[(0 * 5 + 0) * 4 + 3]).toBe(0);
+    expect(out.data[(2 * 5 + 2) * 4 + 3]).toBe(0xff);
+  });
+
+  it('wrap edge mode tiles the source', () => {
+    const source = createSurface(2, 2, 0xff0000ff);
+    const out = createSurface(4, 4);
+    rotateSurface(region(out), region(source), 0, undefined, undefined, 'wrap');
+    // All pixels should be opaque red (wraps the 2x2 source)
+    expect(out.data[3]).toBe(0xff);
+    expect(out.data[(3 * 4 + 3) * 4 + 3]).toBe(0xff);
+  });
+
+  it('nearest sample mode uses nearest-neighbor interpolation', () => {
+    const source = createSurface(2, 1);
+    source.data.set([0, 0, 0, 255], 0);
+    source.data.set([200, 200, 200, 255], 4);
+    const out = createSurface(2, 1);
+    rotateSurface(region(out), region(source), 0, undefined, undefined, 'clamp', 'nearest');
+    // Nearest should produce exact pixel values, no blending
+    expect(out.data[0]).toBe(0);
+    expect(out.data[4]).toBe(200);
+  });
+});
+
+describe('rotateSurface180', () => {
+  it('reverses pixel order with matching dimensions', () => {
+    const source = ab();
+    const out = createSurface(2, 1);
+    rotateSurface180(region(out), region(source));
+    expect(out.data[0]).toBe(0xb0);
+    expect(out.data[4]).toBe(0xa0);
+  });
+
+  it('rotates in place when dest and source are the same region', () => {
+    const surface = ab();
+    rotateSurface180(region(surface), region(surface));
+    expect(surface.data[0]).toBe(0xb0);
+    expect(surface.data[4]).toBe(0xa0);
+  });
+});
+
+describe('rotateSurfaceClockwise', () => {
+  it('rotates a row into a column, left element on top', () => {
+    const source = ab();
+    const out = createSurface(1, 2);
+    rotateSurfaceClockwise(region(out), region(source));
+    expect(getSurfacePixel(out, 0, 0)).toBe(getSurfacePixel(source, 0, 0));
+    expect(getSurfacePixel(out, 0, 1)).toBe(getSurfacePixel(source, 1, 0));
+  });
+});
+
+describe('rotateSurfaceCounterClockwise', () => {
+  it('rotates a row into a column, right element on top', () => {
+    const source = ab();
+    const out = createSurface(1, 2);
+    rotateSurfaceCounterClockwise(region(out), region(source));
+    expect(getSurfacePixel(out, 0, 0)).toBe(getSurfacePixel(source, 1, 0));
+    expect(getSurfacePixel(out, 0, 1)).toBe(getSurfacePixel(source, 0, 0));
+  });
+});

package/src/surfaceShadow.test.ts

@@ -0,0 +1,165 @@
+import { createSurface } from './surface';
+import { compositeSurfacePixels, compositeSurfaceRegion } from './surfaceComposite';
+import { dropShadowSurface, glowSurface, innerGlowSurface, innerShadowSurface } from './surfaceShadow';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+describe('dropShadowSurface', () => {
+  it('produces a tinted alpha mask in out', () => {
+    const source = createSurface(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowSurface(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x0000ffff });
+    expect(out[0]).toBe(0);
+    expect(out[2]).toBe(0xff);
+    expect(out[3]).toBe(0xff);
+  });
+
+  it('compositing out at an offset places the shadow correctly', () => {
+    const source = createSurface(1, 1, 0xffffffff);
+    const dest = createSurface(4, 4);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowSurface(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x0000ffff });
+    const angle = (0 * Math.PI) / 180;
+    const offsetX = Math.round(Math.cos(angle) * 1);
+    const offsetY = Math.round(Math.sin(angle) * 1);
+    compositeSurfacePixels(region(dest, 1 + offsetX, 1 + offsetY, 1, 1), out);
+    const i = (1 * dest.width + 2) * 4;
+    expect(dest.data[i + 2]).toBe(0xff);
+    expect(dest.data[i + 3]).toBe(0xff);
+  });
+
+  it('compositing shadow then source produces source-over-shadow', () => {
+    const source = createSurface(1, 1, 0xff0000ff);
+    const dest = createSurface(2, 1);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowSurface(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x0000ffff });
+    compositeSurfacePixels(region(dest, 1, 0, 1, 1), out);
+    compositeSurfaceRegion(region(dest, 0, 0, 1, 1), region(source));
+    expect(dest.data[0]).toBe(0xff);
+    expect(dest.data[3]).toBe(0xff);
+  });
+
+  it('source.surface.data can be used as out for a full-surface region', () => {
+    const surface = createSurface(1, 1, 0xffffffff);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowSurface(surface.data, scratch, region(surface), { radiusX: 0, radiusY: 0, color: 0x0000ffff });
+    expect(surface.data[2]).toBe(0xff); // tinted blue
+    expect(surface.data[3]).toBe(0xff); // alpha carried from source
+  });
+});
+
+describe('glowSurface', () => {
+  it('produces a tinted alpha mask in out', () => {
+    const source = createSurface(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    glowSurface(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x00ff00ff });
+    expect(out[1]).toBe(0xff);
+    expect(out[3]).toBe(0xff);
+  });
+
+  it('compositing out places the glow at the same position', () => {
+    const source = createSurface(1, 1, 0xffffffff);
+    const dest = createSurface(1, 1);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    glowSurface(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x00ff00ff });
+    compositeSurfacePixels(region(dest), out);
+    expect(dest.data[1]).toBe(0xff);
+    expect(dest.data[3]).toBe(0xff);
+  });
+
+  it('compositing source over glow produces source-over-glow', () => {
+    const source = createSurface(1, 1, 0xff0000ff);
+    const dest = createSurface(1, 1);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    glowSurface(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x00ff00ff });
+    compositeSurfacePixels(region(dest), out);
+    compositeSurfaceRegion(region(dest), region(source));
+    expect(dest.data[0]).toBe(0xff);
+    expect(dest.data[3]).toBe(0xff);
+  });
+
+  it('source.surface.data can be used as out for a full-surface region', () => {
+    const surface = createSurface(1, 1, 0xffffffff);
+    const scratch = new Uint8ClampedArray(4);
+    glowSurface(surface.data, scratch, region(surface), { radiusX: 0, radiusY: 0, color: 0x00ff00ff });
+    expect(surface.data[1]).toBe(0xff);
+    expect(surface.data[3]).toBe(0xff);
+  });
+});
+
+describe('innerGlowSurface', () => {
+  it('clips the glow to inside the shape and tints it', () => {
+    // 3x1: transparent | opaque | transparent. The inner glow appears only on
+    // the opaque pixel; transparent pixels (outside the shape) stay at 0 alpha.
+    const source = createSurface(3, 1);
+    source.data[1 * 4 + 3] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    innerGlowSurface(out, scratch, region(source), { radiusX: 2, radiusY: 0, color: 0x00ff00ff });
+    expect(out[0 * 4 + 3]).toBe(0);
+    expect(out[2 * 4 + 3]).toBe(0);
+    expect(out[1 * 4 + 3]).toBe(170);
+    expect(out[1 * 4 + 0]).toBe(0);
+    expect(out[1 * 4 + 1]).toBe(0xff);
+    expect(out[1 * 4 + 2]).toBe(0);
+  });
+
+  it('produces no inner glow when blur is zero', () => {
+    const source = createSurface(1, 1, 0x0000ffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    innerGlowSurface(out, scratch, region(source), { radiusX: 0, radiusY: 0 });
+    expect(out[3]).toBe(0);
+  });
+});
+
+describe('innerShadowSurface', () => {
+  it('defaults to a black tint', () => {
+    const source = createSurface(3, 1);
+    source.data[1 * 4 + 3] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    innerShadowSurface(out, scratch, region(source), { radiusX: 2, radiusY: 0 });
+    expect(out[1 * 4 + 0]).toBe(0);
+    expect(out[1 * 4 + 1]).toBe(0);
+    expect(out[1 * 4 + 2]).toBe(0);
+    expect(out[1 * 4 + 3]).toBe(170);
+  });
+
+  it('gathers the shadow toward one edge when given a directional offset', () => {
+    // A 3-px-wide filled bar (px 1..3) inside a 5-px row; px 0 and 4 are exterior.
+    const source = createSurface(5, 1);
+    for (let px = 1; px <= 3; px++) source.data[px * 4 + 3] = 255;
+    const alphaAt = (offsetX: number): number[] => {
+      const out = new Uint8ClampedArray(5 * 4);
+      const scratch = new Uint8ClampedArray(5 * 4);
+      innerShadowSurface(out, scratch, region(source), { offsetX, radiusX: 1, radiusY: 0 });
+      return [out[1 * 4 + 3], out[2 * 4 + 3], out[3 * 4 + 3]];
+    };
+    // Zero offset rings the boundary evenly: the two interior edges match.
+    const centered = alphaAt(0);
+    expect(centered[0]).toBe(centered[2]);
+    // A positive offset pulls the exterior in from the left, so the shadow gathers on the left edge.
+    const shifted = alphaAt(2);
+    expect(shifted[0]).toBeGreaterThan(shifted[2]);
+    // The opposite offset mirrors it.
+    const mirrored = alphaAt(-2);
+    expect(mirrored[2]).toBeGreaterThan(mirrored[0]);
+    expect(mirrored[0]).toBe(shifted[2]);
+    expect(mirrored[2]).toBe(shifted[0]);
+  });
+});

package/src/surfaceSharpen.test.ts

@@ -0,0 +1,50 @@
+import { createSurface } from './surface';
+import { sharpenSurface } from './surfaceSharpen';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+describe('sharpenSurface', () => {
+  it('amount 0 returns the source RGB and preserves alpha', () => {
+    const source = createSurface(3, 1);
+    source.data.set([10, 20, 30, 120], 4);
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    sharpenSurface(out, scratch, region(source), { amount: 0 });
+    expect(out[4]).toBe(10);
+    expect(out[5]).toBe(20);
+    expect(out[6]).toBe(30);
+    expect(out[7]).toBe(120);
+  });
+
+  it('accentuates a bright center pixel above its original value', () => {
+    const source = createSurface(5, 1);
+    source.data[2 * 4] = 100;
+    for (let i = 0; i < 5; i++) source.data[i * 4 + 3] = 255;
+    const out = new Uint8ClampedArray(5 * 4);
+    const scratch = new Uint8ClampedArray(5 * 4);
+    sharpenSurface(out, scratch, region(source), { amount: 1, radiusX: 4, radiusY: 0 });
+    expect(out[2 * 4]).toBeGreaterThan(100);
+  });
+
+  it('preserves source alpha while sharpening RGB', () => {
+    const source = createSurface(3, 1);
+    for (let i = 0; i < 3; i++) {
+      source.data[i * 4] = i * 40;
+      source.data[i * 4 + 3] = 77;
+    }
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    sharpenSurface(out, scratch, region(source), { amount: 2 });
+    expect(out[3]).toBe(77);
+    expect(out[7]).toBe(77);
+    expect(out[11]).toBe(77);
+  });
+});

package/src/surfaceTone.test.ts

@@ -0,0 +1,104 @@
+import { createSurface } from './surface';
+import { getSurfacePixel, setSurfacePixel } from './surfacePixel';
+import { createSurfaceRegion } from './surfaceRegion';
+import { applySurfaceCurve, applySurfaceLevels } from './surfaceTone';
+
+function buildIdentityLut() {
+  return Uint8Array.from({ length: 256 }, (_, i) => i);
+}
+
+function buildInvertLut() {
+  return Uint8Array.from({ length: 256 }, (_, i) => 255 - i);
+}
+
+describe('applySurfaceCurve', () => {
+  it('identity LUT leaves pixels unchanged', () => {
+    const surf = createSurface(2, 2, 0x11223344);
+    const lut = buildIdentityLut();
+    applySurfaceCurve(createSurfaceRegion(surf), createSurfaceRegion(surf), lut, lut, lut, lut);
+    expect(getSurfacePixel(surf, 0, 0)).toBe(0x11223344);
+  });
+
+  it('invert LUT inverts RGB channels', () => {
+    const src = createSurface(1, 1);
+    setSurfacePixel(src, 0, 0, 0x00_ff_80_ff);
+    const dst = createSurface(1, 1);
+    const lut = buildInvertLut();
+    applySurfaceCurve(createSurfaceRegion(dst), createSurfaceRegion(src), lut, lut, lut, null);
+    const p = getSurfacePixel(dst, 0, 0);
+    expect((p >>> 24) & 0xff).toBe(0xff); // 0x00 inverted
+    expect((p >> 16) & 0xff).toBe(0x00); // 0xff inverted
+    expect((p >> 8) & 0xff).toBe(0x7f); // 0x80 inverted
+    expect(p & 0xff).toBe(0xff); // alpha passed through
+  });
+
+  it('null LUT passes channel through unchanged', () => {
+    const src = createSurface(1, 1, 0x80_80_80_80);
+    const dst = createSurface(1, 1);
+    const lut = buildInvertLut();
+    // Only invert R, leave G, B, A through.
+    applySurfaceCurve(createSurfaceRegion(dst), createSurfaceRegion(src), lut, null, null, null);
+    const p = getSurfacePixel(dst, 0, 0);
+    expect((p >>> 24) & 0xff).toBe(0x7f); // R inverted
+    expect((p >> 16) & 0xff).toBe(0x80); // G unchanged
+    expect((p >> 8) & 0xff).toBe(0x80); // B unchanged
+    expect(p & 0xff).toBe(0x80); // A unchanged
+  });
+
+  it('is alias-safe when out aliases source', () => {
+    const surf = createSurface(2, 1, 0xff_00_00_ff);
+    const lut = buildInvertLut();
+    applySurfaceCurve(createSurfaceRegion(surf), createSurfaceRegion(surf), lut, null, null, null);
+    // R (0xff) inverted to 0x00; others unchanged.
+    const p = getSurfacePixel(surf, 0, 0);
+    expect((p >>> 24) & 0xff).toBe(0x00);
+    expect((p >> 8) & 0xff).toBe(0x00);
+  });
+});
+
+describe('applySurfaceLevels', () => {
+  it('default black/white/gamma is an identity', () => {
+    const surf = createSurface(1, 1, 0x80_80_80_ff);
+    applySurfaceLevels(createSurfaceRegion(surf), createSurfaceRegion(surf));
+    expect((getSurfacePixel(surf, 0, 0) >>> 24) & 0xff).toBeCloseTo(0x80, -1);
+  });
+
+  it('black and white points clip the range', () => {
+    const surf = createSurface(1, 1);
+    setSurfacePixel(surf, 0, 0, 0x00_00_00_ff); // black pixel
+    applySurfaceLevels(createSurfaceRegion(surf), createSurfaceRegion(surf), 0, 128);
+    // A value at black point maps to 0 — stays 0.
+    expect((getSurfacePixel(surf, 0, 0) >>> 24) & 0xff).toBe(0);
+    setSurfacePixel(surf, 0, 0, 0x80_80_80_ff); // mid pixel at half of range
+    applySurfaceLevels(createSurfaceRegion(surf), createSurfaceRegion(surf), 0, 128);
+    // 128/128 = 1.0 → output 255.
+    expect((getSurfacePixel(surf, 0, 0) >>> 24) & 0xff).toBe(255);
+  });
+
+  it('gamma < 1 lightens midtones', () => {
+    const src = createSurface(1, 1);
+    setSurfacePixel(src, 0, 0, 0x80_80_80_ff);
+    const dst = createSurface(1, 1);
+    applySurfaceLevels(createSurfaceRegion(dst), createSurfaceRegion(src), 0, 255, 0.5);
+    // gamma=0.5 → pow(0.5, 2) = 0.25 — darker than 0.5.
+    const v = (getSurfacePixel(dst, 0, 0) >>> 24) & 0xff;
+    expect(v).toBeLessThan(0x80);
+  });
+
+  it('gamma > 1 darkens midtones', () => {
+    const src = createSurface(1, 1);
+    setSurfacePixel(src, 0, 0, 0x80_80_80_ff);
+    const dst = createSurface(1, 1);
+    applySurfaceLevels(createSurfaceRegion(dst), createSurfaceRegion(src), 0, 255, 2);
+    // gamma=2 → pow(0.5, 0.5) ≈ 0.707 → lighter.
+    const v = (getSurfacePixel(dst, 0, 0) >>> 24) & 0xff;
+    expect(v).toBeGreaterThan(0x80);
+  });
+
+  it('alpha channel is passed through unchanged', () => {
+    const src = createSurface(1, 1, 0x80_80_80_aa);
+    const dst = createSurface(1, 1);
+    applySurfaceLevels(createSurfaceRegion(dst), createSurfaceRegion(src), 0, 255, 1);
+    expect(getSurfacePixel(dst, 0, 0) & 0xff).toBe(0xaa);
+  });
+});

package/src/surfaceTransform.test.ts

@@ -0,0 +1,134 @@
+import { createSurface } from './surface';
+import { getSurfacePixel, setSurfacePixel } from './surfacePixel';
+import { applySurfaceColorTransform, applySurfaceThreshold, mergeSurface, scrollSurface } from './surfaceTransform';
+
+function region(
+  surface: ReturnType<typeof createSurface>,
+  x = 0,
+  y = 0,
+  width = surface.width,
+  height = surface.height,
+) {
+  return { surface, x, y, width, height };
+}
+
+const identity = {
+  redMultiplier: 1,
+  greenMultiplier: 1,
+  blueMultiplier: 1,
+  alphaMultiplier: 1,
+  redOffset: 0,
+  greenOffset: 0,
+  blueOffset: 0,
+  alphaOffset: 0,
+};
+
+describe('applySurfaceColorTransform', () => {
+  it('applies multiplier', () => {
+    const img = createSurface(2, 2, 0x808080ff);
+    applySurfaceColorTransform(region(img), region(img), { ...identity, redMultiplier: 0 });
+    expect(img.data[0]).toBe(0);
+    expect(img.data[1]).toBe(0x80);
+  });
+
+  it('applies offset', () => {
+    const img = createSurface(1, 1);
+    setSurfacePixel(img, 0, 0, 0x000000ff);
+    applySurfaceColorTransform(region(img), region(img), { ...identity, redOffset: 100 });
+    expect(img.data[0]).toBe(100);
+  });
+
+  it('clamps to 0-255', () => {
+    const img = createSurface(1, 1, 0x808080ff);
+    applySurfaceColorTransform(region(img), region(img), { ...identity, redMultiplier: 10, redOffset: 100 });
+    expect(img.data[0]).toBe(255);
+    applySurfaceColorTransform(region(img), region(img), { ...identity, redMultiplier: 0, redOffset: -100 });
+    expect(img.data[0]).toBe(0);
+  });
+
+  it('only affects the specified rect', () => {
+    const img = createSurface(2, 2, 0x808080ff);
+    applySurfaceColorTransform(region(img, 0, 0, 1, 1), region(img, 0, 0, 1, 1), { ...identity, redMultiplier: 0 });
+    expect(img.data[0]).toBe(0);
+    expect(img.data[4]).toBe(0x80);
+  });
+
+  it('can write to a separate output surface', () => {
+    const source = createSurface(1, 1, 0x808080ff);
+    const out = createSurface(1, 1);
+    applySurfaceColorTransform(region(out), region(source), { ...identity, redMultiplier: 0 });
+    expect(out.data[0]).toBe(0);
+    expect(out.data[1]).toBe(0x80);
+    expect(source.data[0]).toBe(0x80); // source unchanged
+  });
+});
+
+describe('applySurfaceThreshold', () => {
+  it('replaces pixels that pass the test', () => {
+    const src = createSurface(2, 1);
+    setSurfacePixel(src, 0, 0, 0x808080ff);
+    setSurfacePixel(src, 1, 0, 0x404040ff);
+    const dst = createSurface(2, 1);
+    const count = applySurfaceThreshold(region(dst), region(src), '>', 0x607060ff, 0xffffffff);
+    expect(count).toBe(1);
+    expect(getSurfacePixel(dst, 0, 0)).toBe(0xffffffff);
+    expect(getSurfacePixel(dst, 1, 0)).toBe(0x00000000);
+  });
+
+  it('copies source when copySource is true and test fails', () => {
+    const src = createSurface(1, 1, 0x112233ff);
+    const dst = createSurface(1, 1);
+    applySurfaceThreshold(region(dst), region(src), '>', 0xffffffff, 0xffffffff, 0xffffffff, true);
+    expect(getSurfacePixel(dst, 0, 0)).toBe(0x112233ff);
+  });
+
+  it('returns zero when no pixels pass', () => {
+    const src = createSurface(2, 2, 0x000000ff);
+    const dst = createSurface(2, 2);
+    const count = applySurfaceThreshold(region(dst), region(src), '>', 0xffffffff);
+    expect(count).toBe(0);
+  });
+});
+
+describe('mergeSurface', () => {
+  it('with multiplier 1 copies source', () => {
+    const src = createSurface(1, 1, 0xff0000ff);
+    const dst = createSurface(1, 1, 0x0000ffff);
+    mergeSurface(region(dst), region(src), 1, 1, 1, 1);
+    expect(dst.data[0]).toBe(0xff);
+    expect(dst.data[2]).toBe(0x00);
+  });
+
+  it('with multiplier 0 keeps destination', () => {
+    const src = createSurface(1, 1, 0xff0000ff);
+    const dst = createSurface(1, 1, 0x0000ffff);
+    mergeSurface(region(dst), region(src), 0, 0, 0, 0);
+    expect(dst.data[0]).toBe(0x00);
+    expect(dst.data[2]).toBe(0xff);
+  });
+
+  it('with multiplier 0.5 blends evenly', () => {
+    const src = createSurface(1, 1, 0x200000ff);
+    const dst = createSurface(1, 1, 0x000020ff);
+    mergeSurface(region(dst), region(src), 0.5, 0, 0.5, 0);
+    expect(dst.data[0]).toBeCloseTo(16, 0);
+    expect(dst.data[2]).toBeCloseTo(16, 0);
+  });
+});
+
+describe('scrollSurface', () => {
+  it('shifts content right with wrapping', () => {
+    const img = createSurface(4, 1);
+    setSurfacePixel(img, 0, 0, 0xff0000ff);
+    scrollSurface(img, 1, 0);
+    expect(getSurfacePixel(img, 1, 0)).toBe(0xff0000ff);
+    expect(getSurfacePixel(img, 0, 0)).toBe(0x00000000);
+  });
+
+  it('wraps pixels around the edge', () => {
+    const img = createSurface(4, 1);
+    setSurfacePixel(img, 3, 0, 0xaabbccff);
+    scrollSurface(img, 1, 0);
+    expect(getSurfacePixel(img, 0, 0)).toBe(0xaabbccff);
+  });
+});