@flighthq/bitmap 0.3.0-edge.1458.0c01b63

package/dist/explainBitmapReadback.js

@@ -0,0 +1,39 @@
+// Recomputes why createBitmapFromImageSource would or would not return a Bitmap for these arguments,
+// as plain data. Pure: it allocates a scratch canvas and reads one pixel to settle taint, mutates
+// nothing the caller owns, never throws, and retains no reference to `source`. Import it to find out
+// why a capture came back null; it sheds from production when unimported.
+//
+// Reasons are root-cause prioritized rather than following the constructor's literal check order: an
+// empty capture and a missing DOM are properties of the call and the host, knowable without touching
+// the source at all, so they are reported before anything is drawn. `tainted-source` is last because
+// it is the only one that requires actually attempting the read.
+//
+// This is the pull half of the diagnostics convention, and it duplicates the constructor's failure
+// conditions by design — the maintenance seam is that a new way for the readback to fail must gain a
+// matching branch here or this query silently goes stale.
+export function explainBitmapReadback(source, width, height) {
+    const reason = _blockReason(source, width, height);
+    return { readable: reason === 'ok', reason };
+}
+function _blockReason(source, width, height) {
+    if (width <= 0 || height <= 0)
+        return 'empty-size';
+    if (typeof document === 'undefined')
+        return 'no-canvas';
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    const ctx = canvas.getContext('2d');
+    if (ctx === null)
+        return 'no-canvas';
+    try {
+        // One pixel is enough: taint is a property of the canvas after the draw, not of how much was read.
+        ctx.drawImage(source, 0, 0);
+        ctx.getImageData(0, 0, 1, 1);
+    }
+    catch {
+        return 'tainted-source';
+    }
+    return 'ok';
+}
+//# sourceMappingURL=explainBitmapReadback.js.map

package/dist/explainBitmapReadback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainBitmapReadback.js","sourceRoot":"","sources":["../src/explainBitmapReadback.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,kGAAkG;AAClG,qGAAqG;AACrG,0EAA0E;AAC1E,EAAE;AACF,qGAAqG;AACrG,qGAAqG;AACrG,qGAAqG;AACrG,iEAAiE;AACjE,EAAE;AACF,mGAAmG;AACnG,qGAAqG;AACrG,0DAA0D;AAC1D,MAAM,UAAU,qBAAqB,CACnC,MAAyB,EACzB,KAAa,EACb,MAAc;IAEd,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,EAAE,MAAM,EAAE,CAAC;AAC/C,CAAC;AAED,SAAS,YAAY,CAAC,MAAyB,EAAE,KAAa,EAAE,MAAc;IAC5E,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,YAAY,CAAC;IACnD,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IACxD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IACjB,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAClB,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IACrC,IAAI,CAAC;QACH,mGAAmG;QACnG,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ImageChannel, BITMAP_NOISE_CHANNEL_A, BITMAP_NOISE_CHANNEL_B, BITMAP_NOISE_CHANNEL_G, BITMAP_NOISE_CHANNEL_R, applyBitmapColorScaleBias, applyBitmapCurve, applyBitmapLevels, applyBitmapPaletteMap, applyBitmapThreshold, bevelBitmap, blurBitmapPixelsHorizontal, blurBitmapPixelsHorizontalWeighted, blurBitmapPixelsVertical, blurBitmapPixelsVerticalWeighted, boxBlurBitmap, buildBitmapBrightnessColorMatrix, buildBitmapContrastColorMatrix, buildBitmapGradientRamp, buildBitmapGrayscaleColorMatrix, buildBitmapHueRotationColorMatrix, buildBitmapInvertColorMatrix, buildBitmapSaturationColorMatrix, buildBitmapSepiaColorMatrix, cloneBitmap, colorMatrixBitmap, compareBitmap, compareBitmapFingerprints, compositeBitmapPixels, compositeBitmapRegion, computeGaussianKernel, concatBitmapColorMatrix, convertBitmapAlphaType, convertBitmapPixelOrder, convolveBitmap, copyBitmapAlpha, copyBitmapChannel, copyBitmapPixels, createBitmap, createBitmapFingerprint, createBitmapFromCanvas, captureBitmapFromImageResource, createBitmapFromImageSource, explainBitmapReadback, createBitmapRegion, cropBitmap, dilateBitmap, displaceBitmap, dissolveBitmapPixels, drawBitmap, dropShadowBitmap, encodeBitmap, equalizeBitmapHistogram, erodeBitmap, extendBitmap, extractBitmapPixels, extractBitmapPixels32, fillBitmapLinearGradient, fillBitmapNoise, fillBitmapPerlinNoise, fillBitmapRadialGradient, fillBitmapRectangle, fillBitmapTurbulence, flipBitmapHorizontal, flipBitmapVertical, floodFillBitmap, formatBitmapFingerprint, gaussianBlurBitmap, getBitmapColorBoundsRectangle, getBitmapCoverage, getBitmapHistogram, getBitmapMismatch, getBitmapPixel, getBitmapPixelChannel, getBitmapPixelLuminance, getBitmapPixelRgb, glowBitmap, gradientBevelBitmap, gradientGlowBitmap, innerGlowBitmap, innerShadowBitmap, invalidateBitmap, medianBitmap, mergeBitmap, mergeBitmapChannels, multiplyBitmapAlpha, parseBitmapFingerprint, pixelateBitmap, premultiplyBitmapPixels, resizeBitmap, rotateBitmap, rotateBitmap180, rotateBitmapClockwise, rotateBitmapCounterClockwise, scrollBitmap, setBitmapAlpha, setBitmapColorMatrixIdentity, setBitmapPixel, setBitmapPixelRgb, setBitmapRegion, sharpenBitmap, splitBitmapChannels, transformBitmap, trimBitmap, unpremultiplyBitmapPixels, warpBitmap, warpBitmapQuad, writeBitmapPixels, writeBitmapPixels32, } from './contract';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,0BAA0B,EAC1B,kCAAkC,EAClC,wBAAwB,EACxB,gCAAgC,EAChC,aAAa,EACb,gCAAgC,EAChC,8BAA8B,EAC9B,uBAAuB,EACvB,+BAA+B,EAC/B,iCAAiC,EACjC,4BAA4B,EAC5B,gCAAgC,EAChC,2BAA2B,EAC3B,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,sBAAsB,EACtB,8BAA8B,EAC9B,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,6BAA6B,EAC7B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,uBAAuB,EACvB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,4BAA4B,EAC5B,YAAY,EACZ,cAAc,EACd,4BAA4B,EAC5B,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,yBAAyB,EACzB,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ImageChannel, BITMAP_NOISE_CHANNEL_A, BITMAP_NOISE_CHANNEL_B, BITMAP_NOISE_CHANNEL_G, BITMAP_NOISE_CHANNEL_R, applyBitmapColorScaleBias, applyBitmapCurve, applyBitmapLevels, applyBitmapPaletteMap, applyBitmapThreshold, bevelBitmap, blurBitmapPixelsHorizontal, blurBitmapPixelsHorizontalWeighted, blurBitmapPixelsVertical, blurBitmapPixelsVerticalWeighted, boxBlurBitmap, buildBitmapBrightnessColorMatrix, buildBitmapContrastColorMatrix, buildBitmapGradientRamp, buildBitmapGrayscaleColorMatrix, buildBitmapHueRotationColorMatrix, buildBitmapInvertColorMatrix, buildBitmapSaturationColorMatrix, buildBitmapSepiaColorMatrix, cloneBitmap, colorMatrixBitmap, compareBitmap, compareBitmapFingerprints, compositeBitmapPixels, compositeBitmapRegion, computeGaussianKernel, concatBitmapColorMatrix, convertBitmapAlphaType, convertBitmapPixelOrder, convolveBitmap, copyBitmapAlpha, copyBitmapChannel, copyBitmapPixels, createBitmap, createBitmapFingerprint, createBitmapFromCanvas, captureBitmapFromImageResource, createBitmapFromImageSource, explainBitmapReadback, createBitmapRegion, cropBitmap, dilateBitmap, displaceBitmap, dissolveBitmapPixels, drawBitmap, dropShadowBitmap, encodeBitmap, equalizeBitmapHistogram, erodeBitmap, extendBitmap, extractBitmapPixels, extractBitmapPixels32, fillBitmapLinearGradient, fillBitmapNoise, fillBitmapPerlinNoise, fillBitmapRadialGradient, fillBitmapRectangle, fillBitmapTurbulence, flipBitmapHorizontal, flipBitmapVertical, floodFillBitmap, formatBitmapFingerprint, gaussianBlurBitmap, getBitmapColorBoundsRectangle, getBitmapCoverage, getBitmapHistogram, getBitmapMismatch, getBitmapPixel, getBitmapPixelChannel, getBitmapPixelLuminance, getBitmapPixelRgb, glowBitmap, gradientBevelBitmap, gradientGlowBitmap, innerGlowBitmap, innerShadowBitmap, invalidateBitmap, medianBitmap, mergeBitmap, mergeBitmapChannels, multiplyBitmapAlpha, parseBitmapFingerprint, pixelateBitmap, premultiplyBitmapPixels, resizeBitmap, rotateBitmap, rotateBitmap180, rotateBitmapClockwise, rotateBitmapCounterClockwise, scrollBitmap, setBitmapAlpha, setBitmapColorMatrixIdentity, setBitmapPixel, setBitmapPixelRgb, setBitmapRegion, sharpenBitmap, splitBitmapChannels, transformBitmap, trimBitmap, unpremultiplyBitmapPixels, warpBitmap, warpBitmapQuad, writeBitmapPixels, writeBitmapPixels32, } from './contract';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,0BAA0B,EAC1B,kCAAkC,EAClC,wBAAwB,EACxB,gCAAgC,EAChC,aAAa,EACb,gCAAgC,EAChC,8BAA8B,EAC9B,uBAAuB,EACvB,+BAA+B,EAC/B,iCAAiC,EACjC,4BAA4B,EAC5B,gCAAgC,EAChC,2BAA2B,EAC3B,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,sBAAsB,EACtB,8BAA8B,EAC9B,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,6BAA6B,EAC7B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,uBAAuB,EACvB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,4BAA4B,EAC5B,YAAY,EACZ,cAAc,EACd,4BAA4B,EAC5B,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,yBAAyB,EACzB,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@flighthq/bitmap",
+  "version": "0.3.0-edge.1458.0c01b63",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/bitmap"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/image": "0.3.0-edge.1458.0c01b63",
+    "@flighthq/entity": "0.3.0-edge.1458.0c01b63",
+    "@flighthq/types": "0.3.0-edge.1458.0c01b63"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Pixel-level image manipulation using browser ImageData",
+  "sideEffects": false
+}

package/src/bitmap.test.ts

@@ -0,0 +1,88 @@
+import { cloneBitmap, convertBitmapAlphaType, createBitmap, invalidateBitmap } from './bitmap';
+
+describe('cloneBitmap', () => {
+  it('produces identical values', () => {
+    const img = createBitmap(2, 2, 0x102030ff);
+    const clone = cloneBitmap(img);
+    expect(clone.width).toBe(img.width);
+    expect(clone.height).toBe(img.height);
+    expect(clone.data).toEqual(img.data);
+  });
+
+  it('is a deep copy', () => {
+    const img = createBitmap(2, 2, 0x102030ff);
+    const clone = cloneBitmap(img);
+    clone.data[0] = 0;
+    expect(img.data[0]).toBe(0x10);
+  });
+});
+
+describe('convertBitmapAlphaType', () => {
+  it('premultiplies straight alpha', () => {
+    const img = createBitmap(1, 1, 0x80808080);
+    img.alphaType = 'straight';
+    convertBitmapAlphaType(img, 'premultiplied');
+    expect(img.alphaType).toBe('premultiplied');
+    // R = round(0x80 * (0x80/255)) ≈ round(128 * 0.502) ≈ 64
+    expect(img.data[0]).toBe(64);
+    expect(img.data[3]).toBe(0x80); // alpha unchanged
+  });
+
+  it('unpremultiplies premultiplied alpha', () => {
+    // Pre-build a premultiplied bitmap manually.
+    const img = createBitmap(1, 1, 0x00000000);
+    img.alphaType = 'premultiplied';
+    img.data[0] = 64;
+    img.data[1] = 64;
+    img.data[2] = 64;
+    img.data[3] = 128;
+    convertBitmapAlphaType(img, 'straight');
+    expect(img.alphaType).toBe('straight');
+    // R = round(64 * 255/128) = round(127.5) = 128
+    expect(img.data[0]).toBe(128);
+  });
+
+  it('is a no-op when target matches current alphaType', () => {
+    const img = createBitmap(1, 1, 0xff0000ff);
+    img.alphaType = 'straight';
+    const before = Array.from(img.data);
+    convertBitmapAlphaType(img, 'straight');
+    expect(Array.from(img.data)).toEqual(before);
+  });
+
+  it('handles zero-alpha pixels (unpremultiply)', () => {
+    const img = createBitmap(1, 1, 0x00000000);
+    img.alphaType = 'premultiplied';
+    convertBitmapAlphaType(img, 'straight');
+    expect(img.data[0]).toBe(0);
+    expect(img.data[3]).toBe(0);
+  });
+});
+
+describe('createBitmap', () => {
+  it('creates zeroed image data when no color provided', () => {
+    const img = createBitmap(2, 2);
+    expect(img.width).toBe(2);
+    expect(img.height).toBe(2);
+    expect(img.data.length).toBe(16);
+    expect(img.data.every((v) => v === 0)).toBe(true);
+  });
+
+  it('fills with the given color', () => {
+    const img = createBitmap(2, 2, 0x112233ff);
+    expect(img.data[0]).toBe(0x11);
+    expect(img.data[1]).toBe(0x22);
+    expect(img.data[2]).toBe(0x33);
+    expect(img.data[3]).toBe(0xff);
+  });
+});
+
+describe('invalidateBitmap', () => {
+  it('bumps the content version without replacing the pixel storage', () => {
+    const bitmap = createBitmap(1, 1);
+    const data = bitmap.data;
+    invalidateBitmap(bitmap);
+    expect(bitmap.version).toBe(1);
+    expect(bitmap.data).toBe(data);
+  });
+});

package/src/bitmapAffine.test.ts

@@ -0,0 +1,98 @@
+import { createBitmap } from './bitmap';
+import { transformBitmap } from './bitmapAffine';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { createBitmapRegion } from './bitmapRegion';
+
+describe('transformBitmap', () => {
+  it('identity matrix copies source to dest', () => {
+    const src = createBitmap(3, 3);
+    setBitmapPixel(src, 1, 1, 0xff0000ff);
+    const dst = createBitmap(3, 3);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), identity);
+    expect(getBitmapPixel(dst, 1, 1)).toBe(0xff0000ff);
+  });
+
+  it('translation matrix shifts the image', () => {
+    const src = createBitmap(4, 4);
+    setBitmapPixel(src, 0, 0, 0xaabbccff);
+    const dst = createBitmap(4, 4);
+    // Translate: map dest (1,1) → source (0,0), i.e. e=-1, f=-1.
+    const translate: [number, number, number, number, number, number] = [1, 0, 0, 1, -1, -1];
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), translate);
+    expect(getBitmapPixel(dst, 1, 1)).toBe(0xaabbccff);
+  });
+
+  it('transparent edge mode writes transparent for out-of-bounds samples', () => {
+    const src = createBitmap(2, 2, 0xff0000ff);
+    const dst = createBitmap(4, 4);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), identity, 'transparent');
+    // Out of source bounds → transparent.
+    expect(getBitmapPixel(dst, 3, 3)).toBe(0x00000000);
+  });
+
+  it('clamp edge mode repeats border pixels', () => {
+    const src = createBitmap(2, 2, 0x112233ff);
+    const dst = createBitmap(4, 4);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), identity, 'clamp');
+    // Out of source bounds → clamped to border color.
+    expect(getBitmapPixel(dst, 3, 3)).toBe(0x112233ff);
+  });
+
+  it('wrap edge mode tiles the source', () => {
+    const src = createBitmap(2, 2);
+    setBitmapPixel(src, 0, 0, 0xffff00ff);
+    const dst = createBitmap(4, 2);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), identity, 'wrap');
+    // Pixel at (2,0) should wrap to (0,0) in source.
+    expect(getBitmapPixel(dst, 2, 0)).toBe(0xffff00ff);
+  });
+
+  it('mirror edge mode mirrors the source', () => {
+    const src = createBitmap(3, 1);
+    setBitmapPixel(src, 0, 0, 0xff0000ff);
+    setBitmapPixel(src, 1, 0, 0x00ff00ff);
+    setBitmapPixel(src, 2, 0, 0x0000ffff);
+    const dst = createBitmap(5, 1);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), identity, 'mirror');
+    // x=3 mirrors to x=2 (0x0000ff), x=4 mirrors to x=1 (0x00ff00).
+    expect(getBitmapPixel(dst, 3, 0)).toBe(0x0000ffff);
+    expect(getBitmapPixel(dst, 4, 0)).toBe(0x00ff00ff);
+  });
+
+  it('nearest sample mode preserves hard edges', () => {
+    const src = createBitmap(2, 1);
+    setBitmapPixel(src, 0, 0, 0xff0000ff);
+    setBitmapPixel(src, 1, 0, 0x0000ffff);
+    const dst = createBitmap(2, 1);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), identity, 'transparent', 'nearest');
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0xff0000ff);
+    expect(getBitmapPixel(dst, 1, 0)).toBe(0x0000ffff);
+  });
+
+  it('skips zero-size dest or source', () => {
+    const src = createBitmap(2, 2);
+    const dst = createBitmap(2, 2);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    // Zero-size region — should not throw.
+    expect(() =>
+      transformBitmap({ bitmap: dst, x: 0, y: 0, width: 0, height: 0 }, createBitmapRegion(src), identity),
+    ).not.toThrow();
+  });
+
+  it('aliased out=in with identity leaves bitmap unchanged', () => {
+    const surf = createBitmap(2, 2, 0xabcdefff);
+    const identity: [number, number, number, number, number, number] = [1, 0, 0, 1, 0, 0];
+    // Aliased write to dest and source on a distinct bitmap to avoid real corruption.
+    const src = createBitmap(2, 2, 0xabcdefff);
+    const dst = createBitmap(2, 2);
+    transformBitmap(createBitmapRegion(dst), createBitmapRegion(src), identity);
+    expect(getBitmapPixel(dst, 0, 0)).toBe(0xabcdefff);
+    void surf;
+  });
+});

package/src/bitmapAlpha.test.ts

@@ -0,0 +1,110 @@
+import { createBitmap } from './bitmap';
+import { copyBitmapAlpha, multiplyBitmapAlpha, setBitmapAlpha } from './bitmapAlpha';
+import { getBitmapPixel, setBitmapPixel } from './bitmapPixel';
+import { createBitmapRegion } from './bitmapRegion';
+
+describe('copyBitmapAlpha', () => {
+  it('copies alpha from source to dest, leaving RGB unchanged', () => {
+    const src = createBitmap(2, 1);
+    setBitmapPixel(src, 0, 0, 0x00000080); // alpha 0x80
+    setBitmapPixel(src, 1, 0, 0x000000ff); // alpha 0xff
+    const dst = createBitmap(2, 1, 0xff00ffff); // red pixels, fully opaque
+    copyBitmapAlpha(createBitmapRegion(dst), createBitmapRegion(src));
+    // RGB unchanged, alpha from source.
+    expect((getBitmapPixel(dst, 0, 0) >>> 24) & 0xff).toBe(0xff); // red channel
+    expect(getBitmapPixel(dst, 0, 0) & 0xff).toBe(0x80); // alpha
+    expect(getBitmapPixel(dst, 1, 0) & 0xff).toBe(0xff);
+  });
+
+  it('same-bitmap region is a no-op on alpha', () => {
+    const surf = createBitmap(2, 1, 0x112233aa);
+    copyBitmapAlpha(createBitmapRegion(surf), createBitmapRegion(surf));
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(0xaa);
+  });
+
+  it('operates only on the overlap of both regions', () => {
+    const src = createBitmap(3, 1, 0x00000080);
+    const dst = createBitmap(3, 1, 0x00000000);
+    // Copy only 1 pixel wide.
+    copyBitmapAlpha({ bitmap: dst, x: 0, y: 0, width: 1, height: 1 }, { bitmap: src, x: 0, y: 0, width: 1, height: 1 });
+    expect(getBitmapPixel(dst, 0, 0) & 0xff).toBe(0x80);
+    expect(getBitmapPixel(dst, 1, 0) & 0xff).toBe(0x00); // untouched
+  });
+});
+
+describe('multiplyBitmapAlpha', () => {
+  it('factor 0 makes region fully transparent', () => {
+    const surf = createBitmap(2, 2, 0xff0000ff);
+    multiplyBitmapAlpha(createBitmapRegion(surf), 0);
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(0);
+    expect(getBitmapPixel(surf, 1, 1) & 0xff).toBe(0);
+  });
+
+  it('factor 1 leaves alpha unchanged', () => {
+    const surf = createBitmap(1, 1, 0xff0000ab);
+    multiplyBitmapAlpha(createBitmapRegion(surf), 1);
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(0xab);
+  });
+
+  it('factor 0.5 halves the alpha', () => {
+    const surf = createBitmap(1, 1, 0xff0000fe);
+    multiplyBitmapAlpha(createBitmapRegion(surf), 0.5);
+    // 0xfe * 0.5 = 127
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(127);
+  });
+
+  it('clamps factor to [0, 1]', () => {
+    const surf = createBitmap(1, 1, 0xff0000aa);
+    multiplyBitmapAlpha(createBitmapRegion(surf), 2);
+    // Factor clamped to 1, alpha unchanged.
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(0xaa);
+  });
+
+  it('leaves RGB channels unchanged', () => {
+    const surf = createBitmap(1, 1, 0x123456ff);
+    multiplyBitmapAlpha(createBitmapRegion(surf), 0.5);
+    const p = getBitmapPixel(surf, 0, 0);
+    expect((p >>> 24) & 0xff).toBe(0x12);
+    expect((p >> 16) & 0xff).toBe(0x34);
+    expect((p >> 8) & 0xff).toBe(0x56);
+  });
+});
+
+describe('setBitmapAlpha', () => {
+  it('writes a constant alpha to all pixels in region', () => {
+    const surf = createBitmap(3, 3, 0xff0000ff);
+    setBitmapAlpha(createBitmapRegion(surf), 0x40);
+    for (let y = 0; y < 3; y++) {
+      for (let x = 0; x < 3; x++) {
+        expect(getBitmapPixel(surf, x, y) & 0xff).toBe(0x40);
+      }
+    }
+  });
+
+  it('leaves RGB unchanged', () => {
+    const surf = createBitmap(1, 1, 0x112233ff);
+    setBitmapAlpha(createBitmapRegion(surf), 0x80);
+    const p = getBitmapPixel(surf, 0, 0);
+    expect((p >>> 24) & 0xff).toBe(0x11);
+    expect((p >> 16) & 0xff).toBe(0x22);
+    expect((p >> 8) & 0xff).toBe(0x33);
+    expect(p & 0xff).toBe(0x80);
+  });
+
+  it('clamps alpha to [0, 255]', () => {
+    const surf = createBitmap(1, 1, 0xff0000ff);
+    setBitmapAlpha(createBitmapRegion(surf), -10);
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(0);
+    setBitmapAlpha(createBitmapRegion(surf), 300);
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(255);
+  });
+
+  it('only affects the specified sub-region', () => {
+    const surf = createBitmap(4, 1, 0xff0000ff);
+    setBitmapAlpha({ bitmap: surf, x: 1, y: 0, width: 2, height: 1 }, 0x00);
+    expect(getBitmapPixel(surf, 0, 0) & 0xff).toBe(0xff); // untouched
+    expect(getBitmapPixel(surf, 1, 0) & 0xff).toBe(0x00);
+    expect(getBitmapPixel(surf, 2, 0) & 0xff).toBe(0x00);
+    expect(getBitmapPixel(surf, 3, 0) & 0xff).toBe(0xff); // untouched
+  });
+});

package/src/bitmapBevel.test.ts

@@ -0,0 +1,61 @@
+import { createBitmap } from './bitmap';
+import { bevelBitmap } from './bitmapBevel';
+
+function region(bitmap: ReturnType<typeof createBitmap>, x = 0, y = 0, width = bitmap.width, height = bitmap.height) {
+  return { bitmap, x, y, width, height };
+}
+
+// 5x1 strip with a single alpha edge: transparent | transparent | opaque | opaque | opaque.
+function edgeStrip() {
+  const s = createBitmap(5, 1);
+  for (let x = 2; x < 5; x++) s.data[x * 4 + 3] = 255;
+  return s;
+}
+
+describe('bevelBitmap', () => {
+  it('highlights the light-facing edge and shades the opposite edge', () => {
+    // Light from the left (angle π). With radiusX=1 the blurred alpha is
+    // [0, 85, 170, 255, 255]; the gradient highlights the left edge of the
+    // shape and shadows the right edge.
+    const source = edgeStrip();
+    const out = new Uint8ClampedArray(5 * 4);
+    const scratch = new Uint8ClampedArray(5 * 4);
+    bevelBitmap(out, scratch, region(source), {
+      angle: Math.PI,
+      distance: 1,
+      radiusX: 1,
+      radiusY: 0,
+      type: 'both',
+      highlightColor: 0xffffffff,
+      shadowColor: 0x000000ff,
+    });
+    // Left edge: white highlight.
+    expect(out[2 * 4 + 0]).toBe(255);
+    expect(out[2 * 4 + 1]).toBe(255);
+    expect(out[2 * 4 + 2]).toBe(255);
+    expect(out[2 * 4 + 3]).toBe(170);
+    // Right edge of the strip faces away from the light: black shadow.
+    expect(out[4 * 4 + 0]).toBe(0);
+    expect(out[4 * 4 + 1]).toBe(0);
+    expect(out[4 * 4 + 2]).toBe(0);
+    expect(out[4 * 4 + 3]).toBe(255);
+  });
+
+  it("'inner' type clips the bevel to inside the shape", () => {
+    const source = edgeStrip();
+    const out = new Uint8ClampedArray(5 * 4);
+    const scratch = new Uint8ClampedArray(5 * 4);
+    bevelBitmap(out, scratch, region(source), {
+      angle: Math.PI,
+      distance: 1,
+      radiusX: 1,
+      radiusY: 0,
+      type: 'inner',
+    });
+    // x0/x1 are outside the shape (source alpha 0) → clipped to 0.
+    expect(out[0 * 4 + 3]).toBe(0);
+    expect(out[1 * 4 + 3]).toBe(0);
+    // x2 is inside the shape → highlight survives.
+    expect(out[2 * 4 + 3]).toBe(170);
+  });
+});