@flighthq/bitmap 0.3.0-edge.1458.0c01b63

package/src/bitmapDisplacement.test.ts

@@ -0,0 +1,181 @@
+import { createBitmap } from './bitmap';
+import { displaceBitmap } from './bitmapDisplacement';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+// A 3x1 strip: red | green | blue.
+function rgbStrip() {
+  const s = createBitmap(3, 1);
+  s.data.set([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255]);
+  return s;
+}
+
+describe('displaceBitmap', () => {
+  it('is a no-op copy when scaleX and scaleY are 0', () => {
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(128);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(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 = createBitmap(3, 1);
+    map.data[0] = 255;
+    map.data[4] = 255;
+    map.data[8] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(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 = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(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 = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(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 = createBitmap(3, 1);
+    map.data[0] = 255;
+    map.data[4] = 255;
+    map.data[8] = 255;
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(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 = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(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("edgeMode 'transparent' treats an out-of-range bilinear tap as transparent", () => {
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      scaleX: 1,
+      scaleY: 0,
+      edgeMode: 'transparent',
+    });
+    // px2 samples halfway between blue and the transparent pixel beyond the edge.
+    expect([...out.slice(2 * 4, 3 * 4)]).toEqual([0, 0, 128, 128]);
+  });
+
+  it("edgeMode 'wrap' wraps each out-of-range bilinear tap", () => {
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      scaleX: 1,
+      scaleY: 0,
+      edgeMode: 'wrap',
+    });
+    // px2 samples halfway between blue at x=2 and wrapped red at x=0.
+    expect([...out.slice(2 * 4, 3 * 4)]).toEqual([128, 0, 128, 255]);
+  });
+
+  it("edgeMode 'mirror' reflects out-of-range bilinear taps", () => {
+    const source = rgbStrip();
+    const map = createBitmap(3, 1);
+    map.data.fill(255);
+    const out = new Uint8ClampedArray(3 * 4);
+    displaceBitmap(out, region(source), {
+      map: region(map),
+      scaleX: 3,
+      scaleY: 0,
+      edgeMode: 'mirror',
+    });
+    // px2 samples halfway between reflected blue at x=2 and green at x=1.
+    expect([...out.slice(2 * 4, 3 * 4)]).toEqual([0, 128, 128, 255]);
+  });
+
+  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 = createBitmap(4, 1);
+    source.data.set([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255]);
+    const map = createBitmap(2, 1);
+    map.data.fill(128); // neutral — minimal displacement at scale=0
+    const out = new Uint8ClampedArray(2 * 4);
+    displaceBitmap(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/bitmapDissolve.test.ts

@@ -0,0 +1,99 @@
+import { createBitmap } from './bitmap';
+import { dissolveBitmapPixels } from './bitmapDissolve';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { createBitmapRegion } from './bitmapRegion';
+
+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('dissolveBitmapPixels', () => {
+  it('dissolves at most pixelCount pixels per call', () => {
+    const source = createBitmap(4, 4, 0x112233ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const original = dest.data.slice();
+    dissolveBitmapPixels(createBitmapRegion(dest), createBitmapRegion(source), 0, 5);
+    expect(countChangedPixels(dest.data, original)).toBe(5);
+  });
+
+  it('eventually covers every pixel exactly once so dest matches source', () => {
+    const source = createBitmap(5, 3);
+    for (let i = 0; i < 5 * 3; i++) setBitmapPixel(source, i % 5, (i / 5) | 0, (0x01010100 * (i + 1)) >>> 0);
+    const dest = createBitmap(5, 3, 0x00000000);
+    const sourceRegion = createBitmapRegion(source);
+    const destRegion = createBitmapRegion(dest);
+
+    let seed = 0;
+    for (let call = 0; call < 8; call++) seed = dissolveBitmapPixels(destRegion, sourceRegion, seed, 2);
+
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+  });
+
+  it('is deterministic for the same seed sequence', () => {
+    const source = createBitmap(6, 6, 0xaabbccff);
+    const a = createBitmap(6, 6, 0x00000000);
+    const b = createBitmap(6, 6, 0x00000000);
+    const sourceRegion = createBitmapRegion(source);
+    dissolveBitmapPixels(createBitmapRegion(a), sourceRegion, 3, 7);
+    dissolveBitmapPixels(createBitmapRegion(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 = createBitmap(4, 4, 0x445566ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const sourceRegion = createBitmapRegion(source);
+    const destRegion = createBitmapRegion(dest);
+
+    let seed = 0;
+    for (let call = 0; call < 16; call++) seed = dissolveBitmapPixels(destRegion, sourceRegion, seed, 1);
+    expect(Array.from(dest.data)).toEqual(Array.from(source.data));
+
+    const afterComplete = dissolveBitmapPixels(destRegion, sourceRegion, seed, 4);
+    expect(afterComplete).toBe(seed);
+  });
+
+  it('dissolves toward fillColor when source and dest are the same region', () => {
+    const bitmap = createBitmap(3, 3, 0x112233ff);
+    const region = createBitmapRegion(bitmap);
+    let seed = 0;
+    for (let call = 0; call < 9; call++) seed = dissolveBitmapPixels(region, region, seed, 1, 0x99887766);
+    for (let i = 0; i < 9; i++) expect(getBitmapPixel(bitmap, i % 3, (i / 3) | 0)).toBe(0x99887766);
+  });
+
+  it('ignores fillColor and copies from source when regions differ', () => {
+    const source = createBitmap(2, 2, 0x0a0b0c0d);
+    const dest = createBitmap(2, 2, 0x00000000);
+    let seed = 0;
+    for (let call = 0; call < 4; call++) {
+      seed = dissolveBitmapPixels(createBitmapRegion(dest), createBitmapRegion(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 = createBitmap(4, 4, 0x112233ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const original = dest.data.slice();
+    expect(dissolveBitmapPixels(createBitmapRegion(dest), createBitmapRegion(source), 2, 0)).toBe(2);
+    expect(countChangedPixels(dest.data, original)).toBe(0);
+  });
+
+  it('returns the seed for a zero-area region', () => {
+    const source = createBitmap(4, 4, 0x112233ff);
+    const dest = createBitmap(4, 4, 0x00000000);
+    const region = createBitmapRegion(dest, 0, 0, 0, 0);
+    expect(dissolveBitmapPixels(region, createBitmapRegion(source), 5, 10)).toBe(5);
+  });
+});

package/src/bitmapDraw.test.ts

@@ -0,0 +1,68 @@
+import { createBitmap } from './bitmap';
+import { extractBitmapPixels } from './bitmapComposite';
+import { drawBitmap } from './bitmapDraw';
+import { setBitmapPixel } from './bitmapPixel';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+function readExtractedPixel(buf: Uint8ClampedArray, regionWidth: number, x: number, y: number): number {
+  const i = (y * regionWidth + x) * 4;
+  return ((buf[i] << 24) | (buf[i + 1] << 16) | (buf[i + 2] << 8) | buf[i + 3]) >>> 0;
+}
+
+describe('drawBitmap', () => {
+  it('does not throw when drawing onto a canvas', () => {
+    const src = createBitmap(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    expect(() => drawBitmap(canvas, region(src), 0, 0)).not.toThrow();
+  });
+
+  it('does not throw when drawing at an offset', () => {
+    const src = createBitmap(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 8;
+    canvas.height = 8;
+    expect(() => drawBitmap(canvas, region(src), 2, 2)).not.toThrow();
+  });
+
+  it('extracts correct pixels from a filled source', () => {
+    const src = createBitmap(4, 4, 0xff0000ff);
+    const r = region(src);
+    const buf = new Uint8ClampedArray(r.width * r.height * 4);
+    extractBitmapPixels(buf, r);
+    expect(readExtractedPixel(buf, r.width, 0, 0)).toBe(0xff0000ff);
+    expect(readExtractedPixel(buf, r.width, 3, 3)).toBe(0xff0000ff);
+  });
+
+  it('extracts correct pixels from a sub-region', () => {
+    const src = createBitmap(4, 4);
+    setBitmapPixel(src, 1, 1, 0xaabbccdd);
+    setBitmapPixel(src, 2, 2, 0x11223344);
+    const r = region(src, 1, 1, 2, 2);
+    const buf = new Uint8ClampedArray(r.width * r.height * 4);
+    extractBitmapPixels(buf, r);
+    expect(readExtractedPixel(buf, r.width, 0, 0)).toBe(0xaabbccdd);
+    expect(readExtractedPixel(buf, r.width, 1, 1)).toBe(0x11223344);
+  });
+
+  it('extracts zeroes from an empty bitmap', () => {
+    const src = createBitmap(2, 2);
+    const r = region(src);
+    const buf = new Uint8ClampedArray(r.width * r.height * 4);
+    extractBitmapPixels(buf, r);
+    expect(readExtractedPixel(buf, r.width, 0, 0)).toBe(0x00000000);
+    expect(readExtractedPixel(buf, r.width, 1, 1)).toBe(0x00000000);
+  });
+
+  it('is a no-op for a zero-dimension region', () => {
+    const src = createBitmap(2, 2, 0x112233ff);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    expect(() => drawBitmap(canvas, region(src, 0, 0, 0, 0), 0, 0)).not.toThrow();
+  });
+});

package/src/bitmapEncode.test.ts

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

package/src/bitmapFill.test.ts

@@ -0,0 +1,83 @@
+import { createBitmap } from './bitmap';
+import { fillBitmapRectangle, floodFillBitmap } from './bitmapFill';
+import { getBitmapPixel } from './bitmapPixel';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+describe('fillBitmapRectangle', () => {
+  it('fills the specified region', () => {
+    const img = createBitmap(4, 4);
+    fillBitmapRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(getBitmapPixel(img, 1, 1)).toBe(0xaabbccff);
+    expect(getBitmapPixel(img, 2, 2)).toBe(0xaabbccff);
+  });
+
+  it('bumps the bitmap version (self-invalidation)', () => {
+    const img = createBitmap(4, 4);
+    const before = img.version;
+    fillBitmapRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(img.version).toBe(before + 1);
+  });
+
+  it('does not affect pixels outside the region', () => {
+    const img = createBitmap(4, 4);
+    fillBitmapRectangle(region(img, 1, 1, 2, 2), 0xaabbccff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0x00000000);
+    expect(getBitmapPixel(img, 3, 3)).toBe(0x00000000);
+  });
+
+  it('skips pixels outside the bitmap bounds', () => {
+    const img = createBitmap(2, 2, 0x000000ff);
+    fillBitmapRectangle(region(img, -1, -1, 4, 4), 0xffffffff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0xffffffff);
+    expect(getBitmapPixel(img, 1, 1)).toBe(0xffffffff);
+  });
+});
+
+describe('floodFillBitmap', () => {
+  it('fills a connected region', () => {
+    const img = createBitmap(3, 3, 0xffffffff);
+    floodFillBitmap(img, 0, 0, 0x000000ff);
+    for (let py = 0; py < 3; py++) {
+      for (let px = 0; px < 3; px++) {
+        expect(getBitmapPixel(img, px, py)).toBe(0x000000ff);
+      }
+    }
+  });
+
+  it('does not cross a barrier', () => {
+    const img = createBitmap(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;
+    }
+    floodFillBitmap(img, 0, 0, 0x0000ffff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0x0000ffff);
+    expect(getBitmapPixel(img, 2, 0)).toBe(0xffffffff);
+  });
+
+  it('is a no-op when fill color matches target', () => {
+    const img = createBitmap(2, 2, 0x112233ff);
+    floodFillBitmap(img, 0, 0, 0x112233ff);
+    expect(getBitmapPixel(img, 0, 0)).toBe(0x112233ff);
+  });
+
+  it('reuses the scratch buffer across calls', () => {
+    const img = createBitmap(4, 4, 0xffffffff);
+    floodFillBitmap(img, 0, 0, 0x000000ff);
+    floodFillBitmap(img, 0, 0, 0xffffffff); // second call reuses buffer
+    expect(getBitmapPixel(img, 0, 0)).toBe(0xffffffff);
+  });
+
+  it('reuses the scratch buffer across calls', () => {
+    const img = createBitmap(4, 4, 0xffffffff);
+    floodFillBitmap(img, 0, 0, 0x000000ff);
+    floodFillBitmap(img, 0, 0, 0xffffffff); // second call reuses buffer
+    expect(getBitmapPixel(img, 0, 0)).toBe(0xffffffff);
+  });
+});

package/src/bitmapFingerprint.test.ts

@@ -0,0 +1,103 @@
+import { createBitmap } from './bitmap';
+import {
+  compareBitmapFingerprints,
+  createBitmapFingerprint,
+  formatBitmapFingerprint,
+  parseBitmapFingerprint,
+} from './bitmapFingerprint';
+import { setBitmapPixel } from './bitmapPixel';
+
+describe('compareBitmapFingerprints', () => {
+  it('reports 0 for identical fingerprints', () => {
+    const fp = createBitmapFingerprint(createBitmap(8, 8, 0x336699ff), 4);
+    expect(compareBitmapFingerprints(fp, fp)).toBe(0);
+  });
+
+  it('reports the mean absolute per-channel difference', () => {
+    const a = createBitmapFingerprint(createBitmap(4, 4, 0x000000ff), 1);
+    const b = createBitmapFingerprint(createBitmap(4, 4, 0x0c0c0cff), 1);
+    // one cell, RGB all differ by 12 → mean abs diff 12
+    expect(compareBitmapFingerprints(a, b)).toBe(12);
+  });
+
+  it('throws when gridSizes differ', () => {
+    const a = createBitmapFingerprint(createBitmap(4, 4), 2);
+    const b = createBitmapFingerprint(createBitmap(4, 4), 4);
+    expect(() => compareBitmapFingerprints(a, b)).toThrow();
+  });
+
+  it('stays small for antialiasing-scale noise but large for a colour swap', () => {
+    const base = createBitmap(16, 16, 0x2040a0ff);
+    const noisy = createBitmap(16, 16, 0x2040a0ff);
+    setBitmapPixel(noisy, 0, 0, 0x2442a2ff); // a few pixels nudged
+    setBitmapPixel(noisy, 5, 5, 0x1e3e9eff);
+    const swapped = createBitmap(16, 16, 0xa04020ff); // whole image recoloured
+    const fp = createBitmapFingerprint(base, 16);
+    expect(compareBitmapFingerprints(fp, createBitmapFingerprint(noisy, 16))).toBeLessThan(2);
+    expect(compareBitmapFingerprints(fp, createBitmapFingerprint(swapped, 16))).toBeGreaterThan(50);
+  });
+});
+
+describe('createBitmapFingerprint', () => {
+  it('averages a solid bitmap to that colour in every cell', () => {
+    const fp = createBitmapFingerprint(createBitmap(8, 8, 0x336699ff), 4);
+    expect(fp.gridSize).toBe(4);
+    expect(fp.cells.length).toBe(4 * 4 * 3);
+    expect([fp.cells[0], fp.cells[1], fp.cells[2]]).toEqual([0x33, 0x66, 0x99]);
+    expect([fp.cells[fp.cells.length - 3], fp.cells[fp.cells.length - 2], fp.cells[fp.cells.length - 1]]).toEqual([
+      0x33, 0x66, 0x99,
+    ]);
+  });
+
+  it('places a coloured quadrant in the matching grid cell', () => {
+    const bitmap = createBitmap(2, 2, 0x000000ff);
+    setBitmapPixel(bitmap, 0, 0, 0xff0000ff); // top-left
+    const fp = createBitmapFingerprint(bitmap, 2);
+    expect([fp.cells[0], fp.cells[1], fp.cells[2]]).toEqual([255, 0, 0]); // cell (0,0)
+    expect([fp.cells[3], fp.cells[4], fp.cells[5]]).toEqual([0, 0, 0]); // cell (1,0)
+  });
+
+  it('throws on a non-positive gridSize', () => {
+    expect(() => createBitmapFingerprint(createBitmap(4, 4), 0)).toThrow();
+  });
+
+  it('returns an all-zero grid for an empty bitmap', () => {
+    const fp = createBitmapFingerprint(createBitmap(0, 0), 2);
+    expect(fp.cells.every((v) => v === 0)).toBe(true);
+  });
+});
+
+describe('formatBitmapFingerprint', () => {
+  it('round-trips through parseBitmapFingerprint', () => {
+    const bitmap = createBitmap(8, 8, 0x000000ff);
+    setBitmapPixel(bitmap, 1, 1, 0x12ab34ff);
+    setBitmapPixel(bitmap, 6, 6, 0xfe01dcff);
+    const fp = createBitmapFingerprint(bitmap, 4);
+    const parsed = parseBitmapFingerprint(formatBitmapFingerprint(fp));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.gridSize).toBe(4);
+    expect(Array.from(parsed!.cells)).toEqual(Array.from(fp.cells));
+    expect(compareBitmapFingerprints(fp, parsed!)).toBe(0);
+  });
+
+  it('encodes gridSize and lowercase hex cells', () => {
+    const fp = createBitmapFingerprint(createBitmap(4, 4, 0x0a0b0cff), 1);
+    expect(formatBitmapFingerprint(fp)).toBe('1:0a0b0c');
+  });
+});
+
+describe('parseBitmapFingerprint', () => {
+  it('returns null for malformed text', () => {
+    expect(parseBitmapFingerprint('garbage')).toBeNull();
+    expect(parseBitmapFingerprint('')).toBeNull();
+    expect(parseBitmapFingerprint('2:abcd')).toBeNull(); // wrong cell count for gridSize 2
+    expect(parseBitmapFingerprint('1:0a0b0')).toBeNull(); // odd hex length
+    expect(parseBitmapFingerprint('1:0a0b0z')).toBeNull(); // non-hex digit
+  });
+
+  it('parses a valid single-cell fingerprint', () => {
+    const parsed = parseBitmapFingerprint('1:0a0b0c');
+    expect(parsed).not.toBeNull();
+    expect(Array.from(parsed!.cells)).toEqual([0x0a, 0x0b, 0x0c]);
+  });
+});

package/src/bitmapFlip.test.ts

@@ -0,0 +1,53 @@
+import { createBitmap } from './bitmap';
+import { flipBitmapHorizontal, flipBitmapVertical } from './bitmapFlip';
+import { getBitmapPixel } from './bitmapPixel';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+function ramp(width: number, height: number) {
+  const bitmap = createBitmap(width, height);
+  for (let i = 0; i < width * height; i++) {
+    bitmap.data[i * 4] = i;
+    bitmap.data[i * 4 + 3] = 255;
+  }
+  return bitmap;
+}
+
+describe('flipBitmapHorizontal', () => {
+  it('mirrors columns left-to-right into a separate dest', () => {
+    const source = ramp(3, 1);
+    const out = createBitmap(3, 1);
+    flipBitmapHorizontal(region(out), region(source));
+    expect(out.data[0]).toBe(2);
+    expect(out.data[4]).toBe(1);
+    expect(out.data[8]).toBe(0);
+  });
+
+  it('mirrors in place when dest and source are the same region', () => {
+    const bitmap = ramp(4, 1);
+    flipBitmapHorizontal(region(bitmap), region(bitmap));
+    expect(bitmap.data[0]).toBe(3);
+    expect(bitmap.data[4]).toBe(2);
+    expect(bitmap.data[8]).toBe(1);
+    expect(bitmap.data[12]).toBe(0);
+  });
+});
+
+describe('flipBitmapVertical', () => {
+  it('mirrors rows top-to-bottom into a separate dest', () => {
+    const source = ramp(1, 3);
+    const out = createBitmap(1, 3);
+    flipBitmapVertical(region(out), region(source));
+    expect(getBitmapPixel(out, 0, 0)).toBe(getBitmapPixel(source, 0, 2));
+    expect(getBitmapPixel(out, 0, 2)).toBe(getBitmapPixel(source, 0, 0));
+  });
+
+  it('mirrors in place when dest and source are the same region', () => {
+    const bitmap = ramp(1, 4);
+    flipBitmapVertical(region(bitmap), region(bitmap));
+    expect(bitmap.data[0]).toBe(3);
+    expect(bitmap.data[12]).toBe(0);
+  });
+});