@flighthq/bitmap 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.638.d4dbd4e

package/src/bitmapDraw.test.ts

@@ -12,21 +12,58 @@ function readExtractedPixel(buf: Uint8ClampedArray, regionWidth: number, x: numb
   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();
+function guardGlobalImageDataAccess() {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'ImageData');
+  let accesses = 0;
+  Object.defineProperty(globalThis, 'ImageData', {
+    configurable: true,
+    get() {
+      accesses++;
+      throw new Error('global ImageData must not be accessed');
+    },
   });
+  return {
+    get accesses() {
+      return accesses;
+    },
+    restore() {
+      if (descriptor === undefined) Reflect.deleteProperty(globalThis, 'ImageData');
+      else Object.defineProperty(globalThis, 'ImageData', descriptor);
+    },
+  };
+}
 
-  it('does not throw when drawing at an offset', () => {
-    const src = createBitmap(2, 2, 0x112233ff);
+describe('drawBitmap', () => {
+  it('allocates through one destination context and puts the exact extracted pixels at the caller coordinates', () => {
+    const src = createBitmap(2, 1);
+    setBitmapPixel(src, 0, 0, 0x112233ff);
+    setBitmapPixel(src, 1, 0, 0xaabbccdd);
+    const imageData = {
+      colorSpace: 'srgb',
+      data: new Uint8ClampedArray(8),
+      height: 1,
+      width: 2,
+    } as ImageData;
+    const createImageData = vi.fn(() => imageData);
+    const putImageData = vi.fn();
+    const getContext = vi.fn(() => ({ createImageData, putImageData }));
     const canvas = document.createElement('canvas');
-    canvas.width = 8;
-    canvas.height = 8;
-    expect(() => drawBitmap(canvas, region(src), 2, 2)).not.toThrow();
+    Object.defineProperty(canvas, 'getContext', { configurable: true, value: getContext });
+    const globalImageData = guardGlobalImageDataAccess();
+
+    try {
+      drawBitmap(canvas, region(src), 7, -3);
+      expect(getContext).toHaveBeenCalledOnce();
+      expect(getContext).toHaveBeenCalledWith('2d');
+      expect(createImageData).toHaveBeenCalledOnce();
+      expect(createImageData).toHaveBeenCalledWith(2, 1);
+      expect(Array.from(imageData.data)).toEqual([17, 34, 51, 255, 170, 187, 204, 221]);
+      expect(putImageData).toHaveBeenCalledOnce();
+      expect(putImageData).toHaveBeenCalledWith(imageData, 7, -3);
+      expect(globalImageData.accesses).toBe(0);
+    } finally {
+      globalImageData.restore();
+    }
   });
 
   it('extracts correct pixels from a filled source', () => {
@@ -58,11 +95,69 @@ describe('drawBitmap', () => {
     expect(readExtractedPixel(buf, r.width, 1, 1)).toBe(0x00000000);
   });
 
-  it('is a no-op for a zero-dimension region', () => {
+  it.each([
+    ['width', 0, 1],
+    ['height', 1, 0],
+  ] as const)('is a no-op for a zero %s before context, allocation, extraction, or put', (_axis, width, height) => {
     const src = createBitmap(2, 2, 0x112233ff);
+    const sourceData = src.data;
+    let sourceDataAccesses = 0;
+    Object.defineProperty(src, 'data', {
+      configurable: true,
+      get() {
+        sourceDataAccesses++;
+        return sourceData;
+      },
+    });
+    const createImageData = vi.fn();
+    const putImageData = vi.fn();
+    const getContext = vi.fn(() => ({ createImageData, putImageData }));
+    const canvas = document.createElement('canvas');
+    Object.defineProperty(canvas, 'getContext', { configurable: true, value: getContext });
+    const globalImageData = guardGlobalImageDataAccess();
+
+    try {
+      expect(() => drawBitmap(canvas, region(src, 0, 0, width, height), 0, 0)).not.toThrow();
+      expect(getContext).not.toHaveBeenCalled();
+      expect(createImageData).not.toHaveBeenCalled();
+      expect(putImageData).not.toHaveBeenCalled();
+      expect(sourceDataAccesses).toBe(0);
+      expect(globalImageData.accesses).toBe(0);
+    } finally {
+      globalImageData.restore();
+    }
+  });
+
+  it('throws from a null positive-size context before allocation, extraction, or put', () => {
+    const src = createBitmap(1, 1, 0x112233ff);
+    const sourceData = src.data;
+    let sourceDataAccesses = 0;
+    Object.defineProperty(src, 'data', {
+      configurable: true,
+      get() {
+        sourceDataAccesses++;
+        return sourceData;
+      },
+    });
+    const getContext = vi.fn(() => null);
     const canvas = document.createElement('canvas');
-    canvas.width = 4;
-    canvas.height = 4;
-    expect(() => drawBitmap(canvas, region(src, 0, 0, 0, 0), 0, 0)).not.toThrow();
+    Object.defineProperty(canvas, 'getContext', { configurable: true, value: getContext });
+    const globalImageData = guardGlobalImageDataAccess();
+    const createImageData = vi.spyOn(CanvasRenderingContext2D.prototype, 'createImageData');
+    const putImageData = vi.spyOn(CanvasRenderingContext2D.prototype, 'putImageData');
+
+    try {
+      expect(() => drawBitmap(canvas, region(src), 0, 0)).toThrow();
+      expect(getContext).toHaveBeenCalledOnce();
+      expect(getContext).toHaveBeenCalledWith('2d');
+      expect(createImageData).not.toHaveBeenCalled();
+      expect(putImageData).not.toHaveBeenCalled();
+      expect(sourceDataAccesses).toBe(0);
+      expect(globalImageData.accesses).toBe(0);
+    } finally {
+      createImageData.mockRestore();
+      putImageData.mockRestore();
+      globalImageData.restore();
+    }
   });
 });

package/src/bitmapEncode.test.ts

@@ -1,18 +1,104 @@
+import type { BitmapEncodeBackend, ImageFormat } from '@flighthq/types/contract';
+
 import { createBitmap } from './bitmap';
-import { encodeBitmap } from './bitmapEncode';
+import { encodeBitmap, explainBitmapEncodeFailure } from './bitmapEncode';
+import {
+  installBitmapEncodeHostBackend,
+  resetBitmapEncodeBackendForTest,
+  setBitmapEncodeBackend,
+} from './bitmapEncodeBackend';
+
+function createBackend(
+  supportedFormats: BitmapEncodeBackend['supportedFormats'] = ['jpeg', 'png'],
+  bytes: Uint8Array = new Uint8Array([9, 8, 7]),
+) {
+  return {
+    encodeBitmap: vi.fn(() => bytes),
+    supportedFormats,
+  } satisfies BitmapEncodeBackend;
+}
+
+afterEach(() => {
+  resetBitmapEncodeBackendForTest();
+});
 
 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);
+  it('dispatches the default png format and quality to the selected backend', () => {
+    const backend = createBackend();
+    const source = createBitmap(2, 2, 0x112233ff);
+    setBitmapEncodeBackend(backend);
+    expect(encodeBitmap(source)).toEqual(new Uint8Array([9, 8, 7]));
+    expect(backend.encodeBitmap).toHaveBeenCalledWith(source, 'png', 0.9);
+  });
+
+  it('forwards jpeg and caller quality unchanged', () => {
+    const backend = createBackend();
+    const source = createBitmap(1, 1);
+    setBitmapEncodeBackend(backend);
+    encodeBitmap(source, 'jpeg', 1.25);
+    expect(backend.encodeBitmap).toHaveBeenCalledWith(source, 'jpeg', 1.25);
+  });
+
+  it('preserves the legacy runtime fallback from every non-jpeg value to png', () => {
+    const backend = createBackend();
+    const source = createBitmap(1, 1);
+    setBitmapEncodeBackend(backend);
+    encodeBitmap(source, 'webp' as ImageFormat);
+    expect(backend.encodeBitmap).toHaveBeenCalledWith(source, 'png', 0.9);
+  });
+
+  it('returns null when no backend is installed', () => {
+    expect(encodeBitmap(createBitmap(1, 1))).toBeNull();
+  });
+
+  it('returns null without invoking an installed backend that does not support the format', () => {
+    const backend = createBackend(['png']);
+    setBitmapEncodeBackend(backend);
+    expect(encodeBitmap(createBitmap(1, 1), 'jpeg')).toBeNull();
+    expect(backend.encodeBitmap).not.toHaveBeenCalled();
+  });
+
+  it('keeps a custom backend terminal above an installed host', () => {
+    const host = createBackend();
+    const custom = createBackend(['png'], new Uint8Array([3]));
+    installBitmapEncodeHostBackend(host);
+    setBitmapEncodeBackend(custom);
+    expect(encodeBitmap(createBitmap(1, 1), 'jpeg')).toBeNull();
+    expect(custom.encodeBitmap).not.toHaveBeenCalled();
+    expect(host.encodeBitmap).not.toHaveBeenCalled();
+  });
+
+  it('propagates genuine supported-format encoding faults', () => {
+    const failure = new Error('encode failed');
+    const backend: BitmapEncodeBackend = {
+      encodeBitmap(): Uint8Array {
+        throw failure;
+      },
+      supportedFormats: ['png'],
+    };
+    setBitmapEncodeBackend(backend);
+    expect(() => encodeBitmap(createBitmap(1, 1))).toThrow(failure);
+  });
+});
+
+describe('explainBitmapEncodeFailure', () => {
+  it('reports a missing backend for the normalized requested format', () => {
+    expect(explainBitmapEncodeFailure('jpeg')).toEqual({ format: 'jpeg', reason: 'backend-not-installed' });
+    expect(explainBitmapEncodeFailure('webp' as ImageFormat)).toEqual({
+      format: 'png',
+      reason: 'backend-not-installed',
+    });
+  });
+
+  it('reports an unsupported format from the selected backend', () => {
+    setBitmapEncodeBackend(createBackend(['png']));
+    expect(explainBitmapEncodeFailure('jpeg')).toEqual({ format: 'jpeg', reason: 'format-unsupported' });
+  });
+
+  it('returns null for a supported format without invoking the encoder', () => {
+    const backend = createBackend(['png']);
+    setBitmapEncodeBackend(backend);
+    expect(explainBitmapEncodeFailure('png')).toBeNull();
+    expect(backend.encodeBitmap).not.toHaveBeenCalled();
   });
 });

package/src/bitmapEncodeBackend.test.ts

@@ -0,0 +1,146 @@
+import type { BitmapEncodeBackend } from '@flighthq/types/contract';
+
+import {
+  explainBitmapEncodeBackend,
+  explainBitmapEncodeOperation,
+  getBitmapEncodeBackend,
+  hasBitmapEncodeHostBackend,
+  hasBitmapEncodeOperation,
+  installBitmapEncodeHostBackend,
+  observeBitmapEncodeHostResult,
+  resetBitmapEncodeBackendForTest,
+  setBitmapEncodeBackend,
+} from './bitmapEncodeBackend';
+
+function createBackend(supportedFormats: BitmapEncodeBackend['supportedFormats'] = ['jpeg', 'png']) {
+  return {
+    encodeBitmap: vi.fn(() => new Uint8Array([1])),
+    supportedFormats,
+  } satisfies BitmapEncodeBackend;
+}
+
+afterEach(() => {
+  resetBitmapEncodeBackendForTest();
+});
+
+describe('explainBitmapEncodeBackend', () => {
+  it('reports absence, host installation, and custom precedence', () => {
+    expect(explainBitmapEncodeBackend()).toEqual({
+      conflict: false,
+      layer: 'host-not-enabled',
+      operation: null,
+      viability: 'unobserved',
+    });
+    installBitmapEncodeHostBackend(createBackend());
+    expect(explainBitmapEncodeBackend()).toMatchObject({ layer: 'host' });
+    setBitmapEncodeBackend(createBackend());
+    expect(explainBitmapEncodeBackend()).toMatchObject({ layer: 'custom' });
+  });
+});
+
+describe('explainBitmapEncodeOperation', () => {
+  it('distinguishes sentinel, host, and custom layers', () => {
+    expect(explainBitmapEncodeOperation('encodeBitmap')).toEqual({
+      implemented: false,
+      layer: 'sentinel',
+      operation: 'encodeBitmap',
+    });
+    installBitmapEncodeHostBackend(createBackend());
+    expect(explainBitmapEncodeOperation('encodeBitmap')).toEqual({
+      implemented: true,
+      layer: 'host',
+      operation: 'encodeBitmap',
+    });
+    setBitmapEncodeBackend(createBackend());
+    expect(explainBitmapEncodeOperation('encodeBitmap')).toEqual({
+      implemented: true,
+      layer: 'custom',
+      operation: 'encodeBitmap',
+    });
+  });
+});
+
+describe('getBitmapEncodeBackend', () => {
+  it('returns custom over host and null when neither is installed', () => {
+    const host = createBackend();
+    const custom = createBackend();
+    expect(getBitmapEncodeBackend()).toBeNull();
+    installBitmapEncodeHostBackend(host);
+    expect(getBitmapEncodeBackend()).toBe(host);
+    setBitmapEncodeBackend(custom);
+    expect(getBitmapEncodeBackend()).toBe(custom);
+    setBitmapEncodeBackend(null);
+    expect(getBitmapEncodeBackend()).toBe(host);
+  });
+});
+
+describe('hasBitmapEncodeHostBackend', () => {
+  it('reports host occupancy independently of a custom backend', () => {
+    setBitmapEncodeBackend(createBackend());
+    expect(hasBitmapEncodeHostBackend()).toBe(false);
+    installBitmapEncodeHostBackend(createBackend());
+    expect(hasBitmapEncodeHostBackend()).toBe(true);
+  });
+});
+
+describe('hasBitmapEncodeOperation', () => {
+  it('does not count the sentinel as support', () => {
+    expect(hasBitmapEncodeOperation('encodeBitmap')).toBe(false);
+    installBitmapEncodeHostBackend(createBackend());
+    expect(hasBitmapEncodeOperation('encodeBitmap')).toBe(true);
+  });
+});
+
+describe('installBitmapEncodeHostBackend', () => {
+  it('keeps the first host and records a conflicting later identity', () => {
+    const first = createBackend();
+    installBitmapEncodeHostBackend(first);
+    installBitmapEncodeHostBackend(first);
+    expect(explainBitmapEncodeBackend().conflict).toBe(false);
+    installBitmapEncodeHostBackend(createBackend());
+    expect(getBitmapEncodeBackend()).toBe(first);
+    expect(explainBitmapEncodeBackend().conflict).toBe(true);
+  });
+});
+
+describe('observeBitmapEncodeHostResult', () => {
+  it.each([
+    [true, 'available'],
+    [false, 'runtime-api-unavailable'],
+  ] as const)('records host viability for result %s', (succeeded, viability) => {
+    installBitmapEncodeHostBackend(createBackend());
+    observeBitmapEncodeHostResult('encodeBitmap', succeeded);
+    expect(explainBitmapEncodeBackend()).toMatchObject({ operation: 'encodeBitmap', viability });
+  });
+});
+
+describe('resetBitmapEncodeBackendForTest', () => {
+  it('clears custom, host, conflict, and observation state', () => {
+    installBitmapEncodeHostBackend(createBackend());
+    installBitmapEncodeHostBackend(createBackend());
+    setBitmapEncodeBackend(createBackend());
+    observeBitmapEncodeHostResult('encodeBitmap', false);
+    resetBitmapEncodeBackendForTest();
+    expect(getBitmapEncodeBackend()).toBeNull();
+    expect(explainBitmapEncodeBackend()).toEqual({
+      conflict: false,
+      layer: 'host-not-enabled',
+      operation: null,
+      viability: 'unobserved',
+    });
+  });
+});
+
+describe('setBitmapEncodeBackend', () => {
+  it('replaces and clears only the custom layer', () => {
+    const host = createBackend();
+    const first = createBackend();
+    const second = createBackend();
+    installBitmapEncodeHostBackend(host);
+    setBitmapEncodeBackend(first);
+    setBitmapEncodeBackend(second);
+    expect(getBitmapEncodeBackend()).toBe(second);
+    setBitmapEncodeBackend(null);
+    expect(getBitmapEncodeBackend()).toBe(host);
+  });
+});

package/src/bitmapFrom.test.ts

@@ -1,28 +1,39 @@
 import { createImageResource } from '@flighthq/image/contract';
+import type { BitmapReadbackBackend } from '@flighthq/types/contract';
 import { vi } from 'vitest';
 
 import { createBitmap } from './bitmap';
-import { createBitmapFromCanvas, captureBitmapFromImageResource, createBitmapFromImageSource } from './bitmapFrom';
+import { captureBitmapFromImageResource, createBitmapFromCanvas, createBitmapFromImageSource } from './bitmapFrom';
+import { resetBitmapReadbackBackendForTest, setBitmapReadbackBackend } from './bitmapReadbackBackend';
+
+afterEach(() => {
+  resetBitmapReadbackBackendForTest();
+});
 
 describe('captureBitmapFromImageResource', () => {
-  it('reads a host-backed resource into CPU pixels', () => {
+  it('passes the resource source and dimensions through the selected readback backend', () => {
     const canvas = document.createElement('canvas');
     canvas.width = 3;
     canvas.height = 2;
-    const bitmap = captureBitmapFromImageResource(createImageResource(canvas));
-    expect(bitmap.width).toBe(3);
-    expect(bitmap.height).toBe(2);
-    expect(bitmap.data).toHaveLength(3 * 2 * 4);
+    const bitmap = createBitmap(3, 2);
+    const readBitmap = vi.fn(() => ({ bitmap, reason: 'ok' as const }));
+    setBitmapReadbackBackend({ readBitmap });
+
+    expect(captureBitmapFromImageResource(createImageResource(canvas))).toBe(bitmap);
+    expect(readBitmap).toHaveBeenCalledOnce();
+    expect(readBitmap).toHaveBeenCalledWith(canvas, 3, 2, 'bitmap');
   });
 
-  it('returns Bitmap matching the resource dimensions', () => {
+  it('returns null for an expected backend refusal', () => {
+    const backend: BitmapReadbackBackend = {
+      readBitmap: vi.fn(() => ({ bitmap: null, reason: 'tainted-source' as const })),
+    };
+    setBitmapReadbackBackend(backend);
     const canvas = document.createElement('canvas');
     canvas.width = 4;
     canvas.height = 4;
-    const resource = createImageResource(canvas);
-    const data = captureBitmapFromImageResource(resource);
-    expect(data.width).toBe(4);
-    expect(data.height).toBe(4);
+
+    expect(captureBitmapFromImageResource(createImageResource(canvas))).toBeNull();
   });
 });
 
@@ -67,41 +78,17 @@ describe('createBitmapFromCanvas', () => {
 });
 
 describe('createBitmapFromImageSource', () => {
-  it('captures a canvas image source at the given device size', () => {
-    const canvas = document.createElement('canvas');
-    canvas.width = 8;
-    canvas.height = 4;
-    const bitmap = createBitmapFromImageSource(canvas, 8, 4);
-    expect(bitmap).not.toBeNull();
-    expect(bitmap!.width).toBe(8);
-    expect(bitmap!.height).toBe(4);
-    expect(bitmap!.data.length).toBe(8 * 4 * 4);
-  });
+  it('returns the exact Bitmap from the selected backend outcome', () => {
+    const expected = createBitmap(8, 4);
+    const backend: BitmapReadbackBackend = {
+      readBitmap: vi.fn(() => ({ bitmap: expected, reason: 'ok' as const })),
+    };
+    setBitmapReadbackBackend(backend);
 
-  it('returns null rather than letting a tainted source throw', () => {
-    // A cross-origin draw taints the scratch canvas and the platform refuses its pixels with a
-    // SecurityError from getImageData. jsdom does not model tainting, so the throw is staged on
-    // getImageData directly — which is the exact call and the exact exception the sentinel exists to
-    // stop escaping to a caller who only asked for a bitmap.
-    const canvas = document.createElement('canvas');
-    canvas.width = 8;
-    canvas.height = 4;
-    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
-      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
-    });
-    try {
-      expect(() => createBitmapFromImageSource(canvas, 8, 4)).not.toThrow();
-      expect(createBitmapFromImageSource(canvas, 8, 4)).toBeNull();
-    } finally {
-      spy.mockRestore();
-    }
+    expect(createBitmapFromImageSource(document.createElement('canvas'), 8, 4)).toBe(expected);
   });
 
-  it('returns null for an empty capture rather than allocating a zero-pixel bitmap', () => {
-    const canvas = document.createElement('canvas');
-    canvas.width = 8;
-    canvas.height = 4;
-    expect(createBitmapFromImageSource(canvas, 0, 4)).toBeNull();
-    expect(createBitmapFromImageSource(canvas, 8, -1)).toBeNull();
+  it('returns null when no backend is installed', () => {
+    expect(createBitmapFromImageSource(document.createElement('canvas'), 8, 4)).toBeNull();
   });
 });

package/src/bitmapReadbackBackend.test.ts

@@ -0,0 +1,69 @@
+import type { BitmapReadbackBackend } from '@flighthq/types/contract';
+
+import {
+  getBitmapReadbackBackend,
+  hasBitmapReadbackHostBackend,
+  installBitmapReadbackHostBackend,
+  resetBitmapReadbackBackendForTest,
+  setBitmapReadbackBackend,
+} from './bitmapReadbackBackend';
+
+afterEach(() => {
+  resetBitmapReadbackBackendForTest();
+});
+
+describe('getBitmapReadbackBackend', () => {
+  it('prefers a custom backend over the installed host backend', () => {
+    const host = createBackend();
+    const custom = createBackend();
+    installBitmapReadbackHostBackend(host);
+    setBitmapReadbackBackend(custom);
+
+    expect(getBitmapReadbackBackend()).toBe(custom);
+  });
+});
+
+describe('hasBitmapReadbackHostBackend', () => {
+  it('reports only host installation', () => {
+    setBitmapReadbackBackend(createBackend());
+    expect(hasBitmapReadbackHostBackend()).toBe(false);
+    installBitmapReadbackHostBackend(createBackend());
+    expect(hasBitmapReadbackHostBackend()).toBe(true);
+  });
+});
+
+describe('installBitmapReadbackHostBackend', () => {
+  it('keeps the first installed host backend', () => {
+    const first = createBackend();
+    installBitmapReadbackHostBackend(first);
+    installBitmapReadbackHostBackend(createBackend());
+
+    expect(getBitmapReadbackBackend()).toBe(first);
+  });
+});
+
+describe('resetBitmapReadbackBackendForTest', () => {
+  it('clears custom and host backends', () => {
+    installBitmapReadbackHostBackend(createBackend());
+    setBitmapReadbackBackend(createBackend());
+
+    resetBitmapReadbackBackendForTest();
+
+    expect(getBitmapReadbackBackend()).toBeNull();
+    expect(hasBitmapReadbackHostBackend()).toBe(false);
+  });
+});
+
+describe('setBitmapReadbackBackend', () => {
+  it('sets and clears the custom backend', () => {
+    const backend = createBackend();
+    setBitmapReadbackBackend(backend);
+    expect(getBitmapReadbackBackend()).toBe(backend);
+    setBitmapReadbackBackend(null);
+    expect(getBitmapReadbackBackend()).toBeNull();
+  });
+});
+
+function createBackend(): BitmapReadbackBackend {
+  return { readBitmap: () => ({ bitmap: null, reason: 'ok' }) };
+}

package/src/bitmapReadbackResolver.test.ts

@@ -0,0 +1,32 @@
+import type { HostImageSource } from '@flighthq/types/contract';
+import { vi } from 'vitest';
+
+import { resetBitmapReadbackBackendForTest, setBitmapReadbackBackend } from './bitmapReadbackBackend';
+import { resolveBitmapReadback } from './bitmapReadbackResolver';
+
+afterEach(() => {
+  resetBitmapReadbackBackendForTest();
+});
+
+describe('resolveBitmapReadback', () => {
+  it('rejects empty dimensions before backend selection', () => {
+    expect(resolveBitmapReadback(source, 0, 1, 'bitmap')).toEqual({ bitmap: null, reason: 'empty-size' });
+  });
+
+  it('reports an absent backend', () => {
+    expect(resolveBitmapReadback(source, 1, 1, 'probe')).toEqual({
+      bitmap: null,
+      reason: 'backend-not-installed',
+    });
+  });
+
+  it('forwards source, dimensions, and mode to the selected backend', () => {
+    const readBitmap = vi.fn(() => ({ bitmap: null, reason: 'ok' as const }));
+    setBitmapReadbackBackend({ readBitmap });
+
+    expect(resolveBitmapReadback(source, 3, 5, 'probe')).toEqual({ bitmap: null, reason: 'ok' });
+    expect(readBitmap).toHaveBeenCalledWith(source, 3, 5, 'probe');
+  });
+});
+
+const source = {} as HostImageSource;