@flighthq/bitmap 0.3.0-edge.1458.0c01b63

package/src/bitmapShadow.test.ts

@@ -0,0 +1,159 @@
+import { createBitmap } from './bitmap';
+import { compositeBitmapPixels, compositeBitmapRegion } from './bitmapComposite';
+import { dropShadowBitmap, glowBitmap, innerGlowBitmap, innerShadowBitmap } from './bitmapShadow';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('dropShadowBitmap', () => {
+  it('produces a tinted alpha mask in out', () => {
+    const source = createBitmap(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowBitmap(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 = createBitmap(1, 1, 0xffffffff);
+    const dest = createBitmap(4, 4);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowBitmap(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);
+    compositeBitmapPixels(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 = createBitmap(1, 1, 0xff0000ff);
+    const dest = createBitmap(2, 1);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowBitmap(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x0000ffff });
+    compositeBitmapPixels(region(dest, 1, 0, 1, 1), out);
+    compositeBitmapRegion(region(dest, 0, 0, 1, 1), region(source));
+    expect(dest.data[0]).toBe(0xff);
+    expect(dest.data[3]).toBe(0xff);
+  });
+
+  it('source.bitmap.data can be used as out for a full-bitmap region', () => {
+    const bitmap = createBitmap(1, 1, 0xffffffff);
+    const scratch = new Uint8ClampedArray(4);
+    dropShadowBitmap(bitmap.data, scratch, region(bitmap), { radiusX: 0, radiusY: 0, color: 0x0000ffff });
+    expect(bitmap.data[2]).toBe(0xff); // tinted blue
+    expect(bitmap.data[3]).toBe(0xff); // alpha carried from source
+  });
+});
+
+describe('glowBitmap', () => {
+  it('produces a tinted alpha mask in out', () => {
+    const source = createBitmap(1, 1, 0xffffffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    glowBitmap(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 = createBitmap(1, 1, 0xffffffff);
+    const dest = createBitmap(1, 1);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    glowBitmap(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x00ff00ff });
+    compositeBitmapPixels(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 = createBitmap(1, 1, 0xff0000ff);
+    const dest = createBitmap(1, 1);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    glowBitmap(out, scratch, region(source), { radiusX: 0, radiusY: 0, color: 0x00ff00ff });
+    compositeBitmapPixels(region(dest), out);
+    compositeBitmapRegion(region(dest), region(source));
+    expect(dest.data[0]).toBe(0xff);
+    expect(dest.data[3]).toBe(0xff);
+  });
+
+  it('source.bitmap.data can be used as out for a full-bitmap region', () => {
+    const bitmap = createBitmap(1, 1, 0xffffffff);
+    const scratch = new Uint8ClampedArray(4);
+    glowBitmap(bitmap.data, scratch, region(bitmap), { radiusX: 0, radiusY: 0, color: 0x00ff00ff });
+    expect(bitmap.data[1]).toBe(0xff);
+    expect(bitmap.data[3]).toBe(0xff);
+  });
+});
+
+describe('innerGlowBitmap', () => {
+  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 = createBitmap(3, 1);
+    source.data[1 * 4 + 3] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    innerGlowBitmap(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 = createBitmap(1, 1, 0x0000ffff);
+    const out = new Uint8ClampedArray(4);
+    const scratch = new Uint8ClampedArray(4);
+    innerGlowBitmap(out, scratch, region(source), { radiusX: 0, radiusY: 0 });
+    expect(out[3]).toBe(0);
+  });
+});
+
+describe('innerShadowBitmap', () => {
+  it('defaults to a black tint', () => {
+    const source = createBitmap(3, 1);
+    source.data[1 * 4 + 3] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    innerShadowBitmap(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 = createBitmap(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);
+      innerShadowBitmap(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/bitmapSharpen.test.ts

@@ -0,0 +1,44 @@
+import { createBitmap } from './bitmap';
+import { sharpenBitmap } from './bitmapSharpen';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('sharpenBitmap', () => {
+  it('amount 0 returns the source RGB and preserves alpha', () => {
+    const source = createBitmap(3, 1);
+    source.data.set([10, 20, 30, 120], 4);
+    const out = new Uint8ClampedArray(3 * 4);
+    const scratch = new Uint8ClampedArray(3 * 4);
+    sharpenBitmap(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 = createBitmap(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);
+    sharpenBitmap(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 = createBitmap(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);
+    sharpenBitmap(out, scratch, region(source), { amount: 2 });
+    expect(out[3]).toBe(77);
+    expect(out[7]).toBe(77);
+    expect(out[11]).toBe(77);
+  });
+});

package/src/bitmapTone.test.ts

@@ -0,0 +1,104 @@
+import { createBitmap } from './bitmap';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { createBitmapRegion } from './bitmapRegion';
+import { applyBitmapCurve, applyBitmapLevels } from './bitmapTone';
+
+function buildIdentityLut() {
+  return Uint8Array.from({ length: 256 }, (_, i) => i);
+}
+
+function buildInvertLut() {
+  return Uint8Array.from({ length: 256 }, (_, i) => 255 - i);
+}
+
+describe('applyBitmapCurve', () => {
+  it('identity LUT leaves pixels unchanged', () => {
+    const surf = createBitmap(2, 2, 0x11223344);
+    const lut = buildIdentityLut();
+    applyBitmapCurve(createBitmapRegion(surf), createBitmapRegion(surf), lut, lut, lut, lut);
+    expect(getBitmapPixel(surf, 0, 0)).toBe(0x11223344);
+  });
+
+  it('invert LUT inverts RGB channels', () => {
+    const src = createBitmap(1, 1);
+    setBitmapPixel(src, 0, 0, 0x00_ff_80_ff);
+    const dst = createBitmap(1, 1);
+    const lut = buildInvertLut();
+    applyBitmapCurve(createBitmapRegion(dst), createBitmapRegion(src), lut, lut, lut, null);
+    const p = getBitmapPixel(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 = createBitmap(1, 1, 0x80_80_80_80);
+    const dst = createBitmap(1, 1);
+    const lut = buildInvertLut();
+    // Only invert R, leave G, B, A through.
+    applyBitmapCurve(createBitmapRegion(dst), createBitmapRegion(src), lut, null, null, null);
+    const p = getBitmapPixel(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 = createBitmap(2, 1, 0xff_00_00_ff);
+    const lut = buildInvertLut();
+    applyBitmapCurve(createBitmapRegion(surf), createBitmapRegion(surf), lut, null, null, null);
+    // R (0xff) inverted to 0x00; others unchanged.
+    const p = getBitmapPixel(surf, 0, 0);
+    expect((p >>> 24) & 0xff).toBe(0x00);
+    expect((p >> 8) & 0xff).toBe(0x00);
+  });
+});
+
+describe('applyBitmapLevels', () => {
+  it('default black/white/gamma is an identity', () => {
+    const surf = createBitmap(1, 1, 0x80_80_80_ff);
+    applyBitmapLevels(createBitmapRegion(surf), createBitmapRegion(surf));
+    expect((getBitmapPixel(surf, 0, 0) >>> 24) & 0xff).toBeCloseTo(0x80, -1);
+  });
+
+  it('black and white points clip the range', () => {
+    const surf = createBitmap(1, 1);
+    setBitmapPixel(surf, 0, 0, 0x00_00_00_ff); // black pixel
+    applyBitmapLevels(createBitmapRegion(surf), createBitmapRegion(surf), 0, 128);
+    // A value at black point maps to 0 — stays 0.
+    expect((getBitmapPixel(surf, 0, 0) >>> 24) & 0xff).toBe(0);
+    setBitmapPixel(surf, 0, 0, 0x80_80_80_ff); // mid pixel at half of range
+    applyBitmapLevels(createBitmapRegion(surf), createBitmapRegion(surf), 0, 128);
+    // 128/128 = 1.0 → output 255.
+    expect((getBitmapPixel(surf, 0, 0) >>> 24) & 0xff).toBe(255);
+  });
+
+  it('gamma < 1 lightens midtones', () => {
+    const src = createBitmap(1, 1);
+    setBitmapPixel(src, 0, 0, 0x80_80_80_ff);
+    const dst = createBitmap(1, 1);
+    applyBitmapLevels(createBitmapRegion(dst), createBitmapRegion(src), 0, 255, 0.5);
+    // gamma=0.5 → pow(0.5, 2) = 0.25 — darker than 0.5.
+    const v = (getBitmapPixel(dst, 0, 0) >>> 24) & 0xff;
+    expect(v).toBeLessThan(0x80);
+  });
+
+  it('gamma > 1 darkens midtones', () => {
+    const src = createBitmap(1, 1);
+    setBitmapPixel(src, 0, 0, 0x80_80_80_ff);
+    const dst = createBitmap(1, 1);
+    applyBitmapLevels(createBitmapRegion(dst), createBitmapRegion(src), 0, 255, 2);
+    // gamma=2 → pow(0.5, 0.5) ≈ 0.707 → lighter.
+    const v = (getBitmapPixel(dst, 0, 0) >>> 24) & 0xff;
+    expect(v).toBeGreaterThan(0x80);
+  });
+
+  it('alpha channel is passed through unchanged', () => {
+    const src = createBitmap(1, 1, 0x80_80_80_aa);
+    const dst = createBitmap(1, 1);
+    applyBitmapLevels(createBitmapRegion(dst), createBitmapRegion(src), 0, 255, 1);
+    expect(getBitmapPixel(dst, 0, 0) & 0xff).toBe(0xaa);
+  });
+});

package/src/bitmapTransform.test.ts

@@ -0,0 +1,128 @@
+import { createBitmap } from './bitmap';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { applyBitmapColorScaleBias, applyBitmapThreshold, mergeBitmap, scrollBitmap } from './bitmapTransform';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+const identity = {
+  redScale: 1,
+  greenScale: 1,
+  blueScale: 1,
+  alphaScale: 1,
+  redBias: 0,
+  greenBias: 0,
+  blueBias: 0,
+  alphaBias: 0,
+};
+
+describe('applyBitmapColorScaleBias', () => {
+  it('applies scale', () => {
+    const img = createBitmap(2, 2, 0x808080ff);
+    applyBitmapColorScaleBias(region(img), region(img), { ...identity, redScale: 0 });
+    expect(img.data[0]).toBe(0);
+    expect(img.data[1]).toBe(0x80);
+  });
+
+  it('applies normalized-linear bias', () => {
+    const img = createBitmap(1, 1);
+    setBitmapPixel(img, 0, 0, 0x000000ff);
+    applyBitmapColorScaleBias(region(img), region(img), { ...identity, redBias: 100 / 255 });
+    expect(img.data[0]).toBe(100);
+  });
+
+  it('clamps to 0-255', () => {
+    const img = createBitmap(1, 1, 0x808080ff);
+    applyBitmapColorScaleBias(region(img), region(img), { ...identity, redScale: 10, redBias: 100 / 255 });
+    expect(img.data[0]).toBe(255);
+    applyBitmapColorScaleBias(region(img), region(img), { ...identity, redScale: 0, redBias: -100 / 255 });
+    expect(img.data[0]).toBe(0);
+  });
+
+  it('only affects the specified rect', () => {
+    const img = createBitmap(2, 2, 0x808080ff);
+    applyBitmapColorScaleBias(region(img, 0, 0, 1, 1), region(img, 0, 0, 1, 1), { ...identity, redScale: 0 });
+    expect(img.data[0]).toBe(0);
+    expect(img.data[4]).toBe(0x80);
+  });
+
+  it('can write to a separate output bitmap', () => {
+    const source = createBitmap(1, 1, 0x808080ff);
+    const out = createBitmap(1, 1);
+    applyBitmapColorScaleBias(region(out), region(source), { ...identity, redScale: 0 });
+    expect(out.data[0]).toBe(0);
+    expect(out.data[1]).toBe(0x80);
+    expect(source.data[0]).toBe(0x80); // source unchanged
+  });
+});
+
+describe('applyBitmapThreshold', () => {
+  it('replaces pixels that pass the test', () => {
+    const src = createBitmap(2, 1);
+    setBitmapPixel(src, 0, 0, 0x808080ff);
+    setBitmapPixel(src, 1, 0, 0x404040ff);
+    const dst = createBitmap(2, 1);
+    const count = applyBitmapThreshold(region(dst), region(src), '>', 0x607060ff, 0xffffffff);
+    expect(count).toBe(1);
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0xffffffff);
+    expect(getBitmapPixel(dst, 1, 0)).toBe(0x00000000);
+  });
+
+  it('copies source when copySource is true and test fails', () => {
+    const src = createBitmap(1, 1, 0x112233ff);
+    const dst = createBitmap(1, 1);
+    applyBitmapThreshold(region(dst), region(src), '>', 0xffffffff, 0xffffffff, 0xffffffff, true);
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0x112233ff);
+  });
+
+  it('returns zero when no pixels pass', () => {
+    const src = createBitmap(2, 2, 0x000000ff);
+    const dst = createBitmap(2, 2);
+    const count = applyBitmapThreshold(region(dst), region(src), '>', 0xffffffff);
+    expect(count).toBe(0);
+  });
+});
+
+describe('mergeBitmap', () => {
+  it('with multiplier 1 copies source', () => {
+    const src = createBitmap(1, 1, 0xff0000ff);
+    const dst = createBitmap(1, 1, 0x0000ffff);
+    mergeBitmap(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 = createBitmap(1, 1, 0xff0000ff);
+    const dst = createBitmap(1, 1, 0x0000ffff);
+    mergeBitmap(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 = createBitmap(1, 1, 0x200000ff);
+    const dst = createBitmap(1, 1, 0x000020ff);
+    mergeBitmap(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('scrollBitmap', () => {
+  it('shifts content right with wrapping', () => {
+    const img = createBitmap(4, 1);
+    setBitmapPixel(img, 0, 0, 0xff0000ff);
+    scrollBitmap(img, 1, 0);
+    expect(getBitmapPixel(img, 1, 0)).toBe(0xff0000ff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0x00000000);
+  });
+
+  it('wraps pixels around the edge', () => {
+    const img = createBitmap(4, 1);
+    setBitmapPixel(img, 3, 0, 0xaabbccff);
+    scrollBitmap(img, 1, 0);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0xaabbccff);
+  });
+});

package/src/bitmapWarp.test.ts

@@ -0,0 +1,118 @@
+import type { Bitmap, BitmapRegion } from '@flighthq/types/contract';
+
+import { createBitmap } from './bitmap';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { warpBitmap, warpBitmapQuad } from './bitmapWarp';
+
+function region(bitmap: Readonly<Bitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height): BitmapRegion {
+  return { bitmap, x, y, width, height };
+}
+
+describe('warpBitmap', () => {
+  it('identity matrix copies source to dest', () => {
+    const src = createBitmap(4, 4, 0xff0000ff);
+    const dst = createBitmap(4, 4);
+    // Identity homography: dest pixel (x,y) maps to source (x,y).
+    warpBitmap(region(dst), region(src), [1, 0, 0, 0, 1, 0, 0, 0, 1]);
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0xff0000ff);
+    expect(getBitmapPixel(dst, 3, 3)).toBe(0xff0000ff);
+  });
+
+  it('translation matrix shifts source', () => {
+    const src = createBitmap(4, 4);
+    setBitmapPixel(src, 0, 0, 0xff0000ff);
+    const dst = createBitmap(4, 4);
+    // Translate source by (-1, -1): dest pixel (x,y) reads source (x-1, y-1).
+    warpBitmap(region(dst), region(src), [1, 0, -1, 0, 1, -1, 0, 0, 1], 'transparent', 'nearest');
+    // dst(1,1) should map to src(0,0)
+    expect(getBitmapPixel(dst, 1, 1)).toBe(0xff0000ff);
+    // dst(0,0) maps to src(-1,-1) → transparent
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0x00000000);
+  });
+
+  it('clamp edgeMode extends border pixels', () => {
+    const src = createBitmap(2, 2, 0x00ff00ff);
+    const dst = createBitmap(4, 4);
+    // Translate source by (2,2): most dst pixels map outside src → clamp to border.
+    warpBitmap(region(dst), region(src), [1, 0, 2, 0, 1, 2, 0, 0, 1], 'clamp', 'nearest');
+    // dst(0,0) maps to src(-2,-2) → clamped to src(0,0) = green
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0x00ff00ff);
+  });
+
+  it('transparent edgeMode gives transparent black outside bounds', () => {
+    const src = createBitmap(2, 2, 0xffffffff);
+    const dst = createBitmap(4, 4);
+    warpBitmap(region(dst), region(src), [1, 0, 3, 0, 1, 3, 0, 0, 1], 'transparent', 'nearest');
+    // All dst pixels map to src outside bounds.
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0x00000000);
+  });
+
+  it('zero-size regions are a no-op', () => {
+    const src = createBitmap(4, 4, 0xffffffff);
+    const dst = createBitmap(4, 4);
+    warpBitmap(region(dst, 0, 0, 0, 4), region(src), [1, 0, 0, 0, 1, 0, 0, 0, 1]);
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0x00000000);
+  });
+
+  it('near-zero w coefficient produces transparent pixel', () => {
+    const src = createBitmap(2, 2, 0xffffffff);
+    const dst = createBitmap(2, 2);
+    // Pathological matrix where w ≈ 0 at (0,0).
+    warpBitmap(region(dst), region(src), [1, 0, 0, 0, 1, 0, 1e-15, 0, 0], 'clamp', 'nearest');
+    // Should not throw; pixel at (0,0) with w≈0 becomes transparent.
+    expect(dst.data[3]).toBe(0);
+  });
+});
+
+describe('warpBitmapQuad', () => {
+  it('identity quad (src corners → dst corners) copies source', () => {
+    const src = createBitmap(4, 4, 0x0000ffff);
+    const dst = createBitmap(4, 4);
+    // Map source [4x4] corners to dest [4x4] corners unchanged.
+    warpBitmapQuad(region(dst), region(src), [0, 0, 4, 0, 4, 4, 0, 4], 'transparent', 'nearest');
+    // Interior pixels should be blue.
+    expect(getBitmapPixel(dst, 2, 2)).toBe(0x0000ffff);
+  });
+
+  it('degenerate quad (zero-area) produces no output', () => {
+    const src = createBitmap(4, 4, 0xffffffff);
+    const dst = createBitmap(4, 4);
+    // All four corners at the same point → degenerate homography.
+    warpBitmapQuad(region(dst), region(src), [2, 2, 2, 2, 2, 2, 2, 2], 'transparent', 'nearest');
+    // Should not throw; output can be transparent or unchanged.
+    expect(dst.data.every((v) => v === 0 || true)).toBe(true);
+  });
+
+  it('zero-size source or dest is a no-op', () => {
+    const src = createBitmap(4, 4, 0xffffffff);
+    const dst = createBitmap(4, 4);
+    warpBitmapQuad(region(dst, 0, 0, 0, 0), region(src), [0, 0, 4, 0, 4, 4, 0, 4]);
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0x00000000);
+  });
+
+  it('horizontal shear quad produces non-trivial sampling', () => {
+    const src = createBitmap(8, 8);
+    // Fill left half red, right half green.
+    for (let py = 0; py < 8; py++) {
+      for (let px = 0; px < 8; px++) {
+        const i = (py * 8 + px) * 4;
+        src.data[i] = px < 4 ? 255 : 0;
+        src.data[i + 1] = px >= 4 ? 255 : 0;
+        src.data[i + 2] = 0;
+        src.data[i + 3] = 255;
+      }
+    }
+    const dst = createBitmap(8, 8);
+    // Shear: right edge shifted up by 2 pixels.
+    warpBitmapQuad(region(dst), region(src), [0, 0, 8, 2, 8, 8, 0, 8], 'transparent', 'nearest');
+    // Should not throw; output should be non-blank for inner pixels.
+    let hasNonZero = false;
+    for (let i = 0; i < dst.data.length; i++) {
+      if (dst.data[i] !== 0) {
+        hasNonZero = true;
+        break;
+      }
+    }
+    expect(hasNonZero).toBe(true);
+  });
+});

package/src/explainBitmapReadback.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createBitmapFromImageSource } from './bitmapFrom';
+import { explainBitmapReadback } from './explainBitmapReadback';
+
+function makeCanvas(width = 8, height = 4): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  return canvas;
+}
+
+describe('explainBitmapReadback', () => {
+  it('reports a readable source as ok', () => {
+    expect(explainBitmapReadback(makeCanvas(), 8, 4)).toEqual({ readable: true, reason: 'ok' });
+  });
+
+  it('reports an empty capture without touching the source', () => {
+    expect(explainBitmapReadback(makeCanvas(), 0, 4)).toEqual({ readable: false, reason: 'empty-size' });
+    expect(explainBitmapReadback(makeCanvas(), 8, 0)).toEqual({ readable: false, reason: 'empty-size' });
+    expect(explainBitmapReadback(makeCanvas(), -1, 4)).toEqual({ readable: false, reason: 'empty-size' });
+  });
+
+  it('reports a tainted source', () => {
+    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
+      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
+    });
+    try {
+      expect(explainBitmapReadback(makeCanvas(), 8, 4)).toEqual({ readable: false, reason: 'tainted-source' });
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('prefers the reason knowable without drawing — an empty capture outranks a tainted source', () => {
+    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
+      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
+    });
+    try {
+      expect(explainBitmapReadback(makeCanvas(), 0, 4).reason).toBe('empty-size');
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('agrees with what createBitmapFromImageSource actually does', () => {
+    // The pull query duplicates the constructor's failure conditions by design, so the pairing is the
+    // thing worth pinning: readable exactly when a bitmap comes back.
+    const canvas = makeCanvas();
+    expect(explainBitmapReadback(canvas, 8, 4).readable).toBe(createBitmapFromImageSource(canvas, 8, 4) !== null);
+    expect(explainBitmapReadback(canvas, 0, 4).readable).toBe(createBitmapFromImageSource(canvas, 0, 4) !== null);
+
+    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
+      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
+    });
+    try {
+      expect(explainBitmapReadback(canvas, 8, 4).readable).toBe(createBitmapFromImageSource(canvas, 8, 4) !== null);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('never throws, whatever the source does', () => {
+    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'drawImage').mockImplementation(() => {
+      throw new TypeError('unsupported source');
+    });
+    try {
+      expect(() => explainBitmapReadback(makeCanvas(), 8, 4)).not.toThrow();
+      expect(explainBitmapReadback(makeCanvas(), 8, 4).readable).toBe(false);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('allocates no bitmap — it reads one pixel, not the whole capture', () => {
+    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData');
+    try {
+      explainBitmapReadback(makeCanvas(1024, 1024), 1024, 1024);
+      expect(spy).toHaveBeenCalledWith(0, 0, 1, 1);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});