@flighthq/image 0.1.0

package/dist/imageResource.d.ts

@@ -0,0 +1,11 @@
+import type { ImageResource } from '@flighthq/types';
+export declare function cloneImageResource(resource: Readonly<ImageResource>): ImageResource;
+export declare function createImageResource(image?: CanvasImageSource): ImageResource;
+export declare function disposeImageResource(resource: ImageResource): void;
+export declare function getImageResourceByteSize(resource: Readonly<ImageResource>): number;
+export declare function hasImageResourceData(resource: Readonly<ImageResource>): boolean;
+export declare function hasImageResourceSource(resource: Readonly<ImageResource>): boolean;
+export declare function invalidateImageResource(resource: ImageResource): void;
+export declare function isImageResourceEmpty(resource: Readonly<ImageResource>): boolean;
+export declare function setImageResourceSource(resource: ImageResource, element: CanvasImageSource | null): void;
+//# sourceMappingURL=imageResource.d.ts.map

package/dist/imageResource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageResource.d.ts","sourceRoot":"","sources":["../src/imageResource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMrD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,aAAa,CAUnF;AAED,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAY5E;AAMD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAIlE;AAMD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAElF;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAE/E;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAEjF;AAKD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAErE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAE/E;AAID,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAIvG"}

package/dist/imageResource.js

@@ -0,0 +1,84 @@
+import { createEntity } from '@flighthq/entity';
+// Allocates a new resource identity over the SAME underlying pixels. The element and the `data` array
+// are shared by reference, not duplicated — clone gives you an independent version counter and entity
+// identity over the same pixels, e.g. to upload one image into two render states with separate
+// invalidation. Use a Surface copy when you need the pixels themselves duplicated.
+export function cloneImageResource(resource) {
+    return createEntity({
+        alphaType: resource.alphaType,
+        data: resource.data,
+        format: resource.format,
+        height: resource.height,
+        source: resource.source,
+        version: resource.version,
+        width: resource.width,
+    });
+}
+export function createImageResource(image) {
+    const resource = createEntity({
+        alphaType: 'straight',
+        data: null,
+        format: 'rgba8unorm',
+        height: 0,
+        source: image ?? null,
+        version: 0,
+        width: 0,
+    });
+    if (resource.source !== null)
+        updateImageResourceSize(resource);
+    return resource;
+}
+// Releases the element and raw-data references so they become eligible for GC, and marks the resource
+// changed. This does NOT free the backend GPU texture (that is owned per render state — call the
+// backend's destroy*Texture) and does NOT close an owned ImageBitmap (ownership is ambiguous; close it
+// explicitly if you own it). Dimensions are left intact; setImageResourceSource repopulates the resource.
+export function disposeImageResource(resource) {
+    resource.data = null;
+    resource.source = null;
+    invalidateImageResource(resource);
+}
+// Returns the byte footprint of the CPU-side pixel data (`data` array). Returns 0 when `data` is
+// null (element-only resource — the GPU texture footprint is tracked by the render state, not here).
+// For `rgba8unorm` (the default) the result equals width × height × 4; other formats are not yet
+// exercised but the formula still applies (byteLength of the actual buffer is authoritative).
+export function getImageResourceByteSize(resource) {
+    return resource.data !== null ? resource.data.byteLength : 0;
+}
+export function hasImageResourceData(resource) {
+    return resource.data !== null;
+}
+export function hasImageResourceSource(resource) {
+    return resource.source !== null;
+}
+// Bumps the resource content revision so consumers (renderer texture caches) know the pixels behind
+// this image changed even though the object identity is the same. Call after mutating the backing
+// pixels in place; the Surface API calls it for you. Resource-tier analog of invalidateNodeLocalContent.
+export function invalidateImageResource(resource) {
+    resource.version = (resource.version + 1) >>> 0;
+}
+export function isImageResourceEmpty(resource) {
+    return resource.width <= 0 || resource.height <= 0;
+}
+// Swaps the element representation, re-reads its dimensions, and marks the resource changed. Pass
+// null to clear the element (dimensions are left intact; use disposeImageResource to release for GC).
+export function setImageResourceSource(resource, element) {
+    resource.source = element;
+    if (element !== null)
+        updateImageResourceSize(resource);
+    invalidateImageResource(resource);
+}
+// Reads pixel dimensions from the current (non-null) element. Video sources carry their size on
+// videoWidth/videoHeight; every other CanvasImageSource exposes width/height directly.
+function updateImageResourceSize(resource) {
+    const element = resource.source;
+    if (element instanceof HTMLVideoElement) {
+        resource.width = element.videoWidth;
+        resource.height = element.videoHeight;
+    }
+    else {
+        const sized = element;
+        resource.width = sized.width;
+        resource.height = sized.height;
+    }
+}
+//# sourceMappingURL=imageResource.js.map

package/dist/imageResource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageResource.js","sourceRoot":"","sources":["../src/imageResource.ts"],"names":[],"mappings":"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"}

package/dist/imageResourceFrom.d.ts

@@ -0,0 +1,11 @@
+import type { ImageResource } from '@flighthq/types';
+export declare function createImageResourceFromCanvas(canvas: HTMLCanvasElement): ImageResource;
+export declare function createImageResourceFromImageBitmap(bitmap: ImageBitmap): ImageResource;
+export declare function createImageResourceFromImageElement(img: HTMLImageElement): ImageResource;
+export declare function detectImageMimeType(data: ArrayBuffer | Uint8Array): string | null;
+export declare function isImageResourceSameOrigin(url: string): boolean;
+export declare function loadImageResourceFromBase64(base64: string, mimeType: string, signal?: AbortSignal): Promise<ImageResource>;
+export declare function loadImageResourceFromBlob(blob: Blob, signal?: AbortSignal): Promise<ImageResource>;
+export declare function loadImageResourceFromBytes(bytes: Uint8Array, mimeType?: string, signal?: AbortSignal): Promise<ImageResource>;
+export declare function loadImageResourceFromUrl(url: string, crossOrigin?: string, signal?: AbortSignal): Promise<ImageResource>;
+//# sourceMappingURL=imageResourceFrom.d.ts.map

package/dist/imageResourceFrom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageResourceFrom.d.ts","sourceRoot":"","sources":["../src/imageResourceFrom.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAUtF;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAUrF;AAED,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAUxF;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CA+BjF;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAOxG;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAexB"}

package/dist/imageResourceFrom.js

@@ -0,0 +1,112 @@
+import { createEntity } from '@flighthq/entity';
+export function createImageResourceFromCanvas(canvas) {
+    return createEntity({
+        alphaType: 'straight',
+        data: null,
+        format: 'rgba8unorm',
+        height: canvas.height,
+        source: canvas,
+        version: 0,
+        width: canvas.width,
+    });
+}
+export function createImageResourceFromImageBitmap(bitmap) {
+    return createEntity({
+        alphaType: 'straight',
+        data: null,
+        format: 'rgba8unorm',
+        height: bitmap.height,
+        source: bitmap,
+        version: 0,
+        width: bitmap.width,
+    });
+}
+export function createImageResourceFromImageElement(img) {
+    return createEntity({
+        alphaType: 'straight',
+        data: null,
+        format: 'rgba8unorm',
+        height: img.height,
+        source: img,
+        version: 0,
+        width: img.width,
+    });
+}
+export function detectImageMimeType(data) {
+    const b = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (b.byteLength < 4)
+        return null;
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47)
+        return 'image/png';
+    // JPEG: FF D8 FF
+    if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return 'image/jpeg';
+    // GIF87a / GIF89a: 47 49 46 38
+    if (b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38)
+        return 'image/gif';
+    // WebP: RIFF....WEBP (bytes 0-3 and 8-11)
+    if (b.byteLength >= 12 &&
+        b[0] === 0x52 &&
+        b[1] === 0x49 &&
+        b[2] === 0x46 &&
+        b[3] === 0x46 &&
+        b[8] === 0x57 &&
+        b[9] === 0x45 &&
+        b[10] === 0x42 &&
+        b[11] === 0x50)
+        return 'image/webp';
+    // BMP: 42 4D
+    if (b[0] === 0x42 && b[1] === 0x4d)
+        return 'image/bmp';
+    return null;
+}
+export function isImageResourceSameOrigin(url) {
+    if (url.startsWith('data:') || url.startsWith('blob:'))
+        return true;
+    try {
+        return new URL(url, location.href).origin === location.origin;
+    }
+    catch {
+        return true;
+    }
+}
+export async function loadImageResourceFromBase64(base64, mimeType, signal) {
+    return loadImageResourceFromUrl(`data:${mimeType};base64,${base64}`, undefined, signal);
+}
+export async function loadImageResourceFromBlob(blob, signal) {
+    const url = URL.createObjectURL(blob);
+    try {
+        return await loadImageResourceFromUrl(url, undefined, signal);
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}
+export async function loadImageResourceFromBytes(bytes, mimeType, signal) {
+    const type = mimeType ?? detectImageMimeType(bytes);
+    if (type === null) {
+        throw new Error('Unable to determine image type from bytes');
+    }
+    const buf = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    return loadImageResourceFromBlob(new Blob([buf], { type }), signal);
+}
+export async function loadImageResourceFromUrl(url, crossOrigin, signal) {
+    signal?.throwIfAborted();
+    const img = new Image();
+    if (crossOrigin !== undefined)
+        img.crossOrigin = crossOrigin;
+    img.src = url;
+    // Wire abort to cancel the pending decode by rejecting the promise.
+    if (signal !== undefined) {
+        await Promise.race([
+            img.decode(),
+            new Promise((_, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true })),
+        ]);
+    }
+    else {
+        await img.decode();
+    }
+    return createImageResourceFromImageElement(img);
+}
+//# sourceMappingURL=imageResourceFrom.js.map

package/dist/imageResourceFrom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageResourceFrom.js","sourceRoot":"","sources":["../src/imageResourceFrom.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './imageResource';
+export * from './imageResourceFrom';
+//# 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,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './imageResource';
+export * from './imageResourceFrom';
+//# 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,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/image",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.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/entity": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Image resources: pixel sources, MIME detection, and constructors from canvas/bitmap/element",
+  "sideEffects": false
+}

package/src/imageResource.test.ts

@@ -0,0 +1,169 @@
+import {
+  cloneImageResource,
+  createImageResource,
+  disposeImageResource,
+  getImageResourceByteSize,
+  hasImageResourceData,
+  hasImageResourceSource,
+  invalidateImageResource,
+  isImageResourceEmpty,
+  setImageResourceSource,
+} from './imageResource';
+
+describe('cloneImageResource', () => {
+  it('copies fields, shares the element, and gives an independent identity', () => {
+    const element = { width: 4, height: 5 } as HTMLImageElement;
+    const resource = createImageResource(element);
+    resource.version = 3;
+
+    const copy = cloneImageResource(resource);
+
+    expect(copy).not.toBe(resource);
+    expect(copy.source).toBe(element);
+    expect(copy.width).toStrictEqual(4);
+    expect(copy.height).toStrictEqual(5);
+    expect(copy.version).toStrictEqual(3);
+
+    copy.version++;
+    expect(resource.version).toStrictEqual(3);
+  });
+
+  it('shares the data buffer by reference and copies the format and alphaType', () => {
+    const resource = createImageResource();
+    resource.data = new Uint8ClampedArray([1, 2, 3, 4]);
+    resource.format = 'bgra8unorm';
+    resource.alphaType = 'premultiplied';
+
+    const copy = cloneImageResource(resource);
+
+    expect(copy.data).toBe(resource.data);
+    expect(copy.format).toStrictEqual('bgra8unorm');
+    expect(copy.alphaType).toStrictEqual('premultiplied');
+  });
+});
+
+describe('createImageResource', () => {
+  it('returns an object', () => {
+    const resource = createImageResource();
+    expect(resource).not.toBeNull();
+  });
+
+  it('sets source, width and height if you pass in a source element', () => {
+    const element = { width: 100, height: 100 } as HTMLImageElement;
+    const resource = createImageResource(element);
+    expect(resource.source).toStrictEqual(element);
+    expect(resource.width).toStrictEqual(element.width);
+    expect(resource.height).toStrictEqual(element.height);
+  });
+
+  it('starts at version 0', () => {
+    expect(createImageResource().version).toBe(0);
+  });
+
+  it('defaults to null data, rgba8unorm format, and straight alphaType', () => {
+    const resource = createImageResource();
+    expect(resource.data).toBeNull();
+    expect(resource.format).toStrictEqual('rgba8unorm');
+    expect(resource.alphaType).toStrictEqual('straight');
+  });
+});
+
+describe('disposeImageResource', () => {
+  it('releases the element and data and marks the resource changed', () => {
+    const resource = createImageResource({ width: 4, height: 5 } as HTMLImageElement);
+    resource.data = new Uint8ClampedArray(4 * 5 * 4);
+    const before = resource.version;
+
+    disposeImageResource(resource);
+
+    expect(resource.source).toBeNull();
+    expect(resource.data).toBeNull();
+    expect(resource.version).toStrictEqual(before + 1);
+  });
+});
+
+describe('getImageResourceByteSize', () => {
+  it('returns 0 when data is null (element-only resource)', () => {
+    const resource = createImageResource();
+    expect(getImageResourceByteSize(resource)).toBe(0);
+  });
+
+  it('returns the byteLength of the data array when present', () => {
+    const resource = createImageResource();
+    resource.data = new Uint8ClampedArray(100);
+    expect(getImageResourceByteSize(resource)).toBe(100);
+  });
+
+  it('reflects width × height × 4 for a typical rgba8unorm resource', () => {
+    const resource = createImageResource();
+    resource.width = 4;
+    resource.height = 4;
+    resource.data = new Uint8ClampedArray(4 * 4 * 4);
+    expect(getImageResourceByteSize(resource)).toBe(64);
+  });
+});
+
+describe('hasImageResourceData', () => {
+  it('is false without data and true with it', () => {
+    const resource = createImageResource();
+    expect(hasImageResourceData(resource)).toStrictEqual(false);
+    resource.data = new Uint8ClampedArray(4);
+    expect(hasImageResourceData(resource)).toStrictEqual(true);
+  });
+});
+
+describe('hasImageResourceSource', () => {
+  it('is false without an element and true with one', () => {
+    expect(hasImageResourceSource(createImageResource())).toStrictEqual(false);
+    expect(hasImageResourceSource(createImageResource({ width: 1, height: 1 } as HTMLImageElement))).toStrictEqual(
+      true,
+    );
+  });
+});
+
+describe('invalidateImageResource', () => {
+  it('increments the version', () => {
+    const resource = createImageResource();
+    invalidateImageResource(resource);
+    expect(resource.version).toBe(1);
+    invalidateImageResource(resource);
+    expect(resource.version).toBe(2);
+  });
+
+  it('wraps around with >>> 0', () => {
+    const resource = createImageResource();
+    resource.version = 0xffffffff;
+    invalidateImageResource(resource);
+    expect(resource.version).toBe(0);
+  });
+});
+
+describe('isImageResourceEmpty', () => {
+  it('is true with no dimensions and false once sized', () => {
+    expect(isImageResourceEmpty(createImageResource())).toStrictEqual(true);
+    expect(isImageResourceEmpty(createImageResource({ width: 2, height: 2 } as HTMLImageElement))).toStrictEqual(false);
+  });
+});
+
+describe('setImageResourceSource', () => {
+  it('swaps the element, re-reads dimensions, and marks the resource changed', () => {
+    const resource = createImageResource();
+    const before = resource.version;
+    const element = { width: 8, height: 6 } as HTMLImageElement;
+
+    setImageResourceSource(resource, element);
+
+    expect(resource.source).toBe(element);
+    expect(resource.width).toStrictEqual(8);
+    expect(resource.height).toStrictEqual(6);
+    expect(resource.version).toStrictEqual(before + 1);
+  });
+
+  it('clears the element when passed null', () => {
+    const resource = createImageResource({ width: 8, height: 6 } as HTMLImageElement);
+
+    setImageResourceSource(resource, null);
+
+    expect(resource.source).toBeNull();
+  });
+});

package/src/imageResourceFrom.test.ts

@@ -0,0 +1,273 @@
+import {
+  createImageResourceFromCanvas,
+  createImageResourceFromImageBitmap,
+  createImageResourceFromImageElement,
+  detectImageMimeType,
+  isImageResourceSameOrigin,
+  loadImageResourceFromBase64,
+  loadImageResourceFromBlob,
+  loadImageResourceFromBytes,
+  loadImageResourceFromUrl,
+} from './imageResourceFrom';
+
+// Stub img.decode() so async load functions resolve immediately in jsdom.
+beforeEach(() => {
+  HTMLImageElement.prototype.decode = vi.fn().mockResolvedValue(undefined);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete (HTMLImageElement.prototype as Partial<HTMLImageElement>).decode;
+});
+
+describe('createImageResourceFromCanvas', () => {
+  it('wraps a canvas with correct dimensions', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 320;
+    canvas.height = 240;
+    const resource = createImageResourceFromCanvas(canvas);
+
+    expect(resource.source).toBe(canvas);
+    expect(resource.width).toBe(320);
+    expect(resource.height).toBe(240);
+  });
+
+  it('reflects the canvas dimensions at wrap time', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 0;
+    canvas.height = 0;
+    const resource = createImageResourceFromCanvas(canvas);
+
+    expect(resource.width).toBe(0);
+    expect(resource.height).toBe(0);
+  });
+
+  it('returns a new object each call', () => {
+    const canvas = document.createElement('canvas');
+    expect(createImageResourceFromCanvas(canvas)).not.toBe(createImageResourceFromCanvas(canvas));
+  });
+});
+
+describe('createImageResourceFromImageBitmap', () => {
+  it('wraps an ImageBitmap with correct dimensions', () => {
+    const bitmap = { width: 64, height: 128, close: () => {} } as ImageBitmap;
+    const resource = createImageResourceFromImageBitmap(bitmap);
+
+    expect(resource.source).toBe(bitmap);
+    expect(resource.width).toBe(64);
+    expect(resource.height).toBe(128);
+  });
+
+  it('returns a new object each call', () => {
+    const bitmap = { width: 1, height: 1, close: () => {} } as ImageBitmap;
+    expect(createImageResourceFromImageBitmap(bitmap)).not.toBe(createImageResourceFromImageBitmap(bitmap));
+  });
+});
+
+describe('createImageResourceFromImageElement', () => {
+  it('wraps an HTMLImageElement with correct dimensions', () => {
+    const img = { width: 200, height: 100 } as HTMLImageElement;
+    const resource = createImageResourceFromImageElement(img);
+
+    expect(resource.source).toBe(img);
+    expect(resource.width).toBe(200);
+    expect(resource.height).toBe(100);
+  });
+
+  it('reflects zero dimensions for an unloaded image element', () => {
+    const img = document.createElement('img');
+    const resource = createImageResourceFromImageElement(img);
+
+    expect(resource.width).toBe(0);
+    expect(resource.height).toBe(0);
+  });
+
+  it('returns a new object each call', () => {
+    const img = document.createElement('img');
+    expect(createImageResourceFromImageElement(img)).not.toBe(createImageResourceFromImageElement(img));
+  });
+});
+
+describe('detectImageMimeType', () => {
+  it('returns null for a buffer that is too small', () => {
+    expect(detectImageMimeType(new ArrayBuffer(2))).toBeNull();
+  });
+
+  it('returns null for an unrecognised header', () => {
+    const buf = new ArrayBuffer(16);
+    new Uint8Array(buf).set([0x00, 0x01, 0x02, 0x03]);
+    expect(detectImageMimeType(buf)).toBeNull();
+  });
+
+  it('detects PNG', () => {
+    const buf = new ArrayBuffer(16);
+    new Uint8Array(buf).set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    expect(detectImageMimeType(buf)).toBe('image/png');
+  });
+
+  it('detects JPEG', () => {
+    const buf = new ArrayBuffer(16);
+    new Uint8Array(buf).set([0xff, 0xd8, 0xff, 0xe0]);
+    expect(detectImageMimeType(buf)).toBe('image/jpeg');
+  });
+
+  it('detects GIF', () => {
+    const buf = new ArrayBuffer(16);
+    new Uint8Array(buf).set([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]);
+    expect(detectImageMimeType(buf)).toBe('image/gif');
+  });
+
+  it('detects WebP', () => {
+    const buf = new ArrayBuffer(16);
+    new Uint8Array(buf).set([
+      0x52,
+      0x49,
+      0x46,
+      0x46, // RIFF
+      0x00,
+      0x00,
+      0x00,
+      0x00, // size (ignored)
+      0x57,
+      0x45,
+      0x42,
+      0x50, // WEBP
+    ]);
+    expect(detectImageMimeType(buf)).toBe('image/webp');
+  });
+
+  it('detects BMP', () => {
+    const buf = new ArrayBuffer(16);
+    new Uint8Array(buf).set([0x42, 0x4d]);
+    expect(detectImageMimeType(buf)).toBe('image/bmp');
+  });
+});
+
+describe('isImageResourceSameOrigin', () => {
+  it('returns true for data: URLs', () => {
+    expect(isImageResourceSameOrigin('data:image/png;base64,abc')).toBe(true);
+  });
+
+  it('returns true for blob: URLs', () => {
+    expect(isImageResourceSameOrigin('blob:http://localhost/some-id')).toBe(true);
+  });
+
+  it('returns true for relative URLs (same origin)', () => {
+    expect(isImageResourceSameOrigin('/images/logo.png')).toBe(true);
+  });
+
+  it('returns false for a different-origin absolute URL', () => {
+    expect(isImageResourceSameOrigin('https://cdn.other-domain.com/image.png')).toBe(false);
+  });
+});
+
+describe('loadImageResourceFromBase64', () => {
+  it('resolves to an ImageResource', async () => {
+    const resource = await loadImageResourceFromBase64('abc123', 'image/png');
+    expect(resource).not.toBeNull();
+    expect(resource.source).toBeInstanceOf(HTMLImageElement);
+  });
+
+  it('builds a data: URL from the base64 string and mime type', async () => {
+    const resource = await loadImageResourceFromBase64('aGVsbG8=', 'image/png');
+    expect(resource.source).toBeInstanceOf(HTMLImageElement);
+  });
+});
+
+describe('loadImageResourceFromBlob', () => {
+  it('resolves to an ImageResource', async () => {
+    const blob = new Blob([], { type: 'image/png' });
+    const resource = await loadImageResourceFromBlob(blob);
+    expect(resource).not.toBeNull();
+    expect(resource.source).toBeInstanceOf(HTMLImageElement);
+  });
+
+  it('revokes the object URL after loading', async () => {
+    const revokeSpy = vi.spyOn(URL, 'revokeObjectURL');
+    const blob = new Blob([], { type: 'image/png' });
+    await loadImageResourceFromBlob(blob);
+    expect(revokeSpy).toHaveBeenCalledOnce();
+  });
+
+  it('revokes the object URL even if loading fails', async () => {
+    HTMLImageElement.prototype.decode = vi.fn().mockRejectedValue(new Error('load failed'));
+    const revokeSpy = vi.spyOn(URL, 'revokeObjectURL');
+    const blob = new Blob([], { type: 'image/png' });
+    await expect(loadImageResourceFromBlob(blob)).rejects.toThrow('load failed');
+    expect(revokeSpy).toHaveBeenCalledOnce();
+  });
+});
+
+describe('loadImageResourceFromBytes', () => {
+  it('throws when mime type cannot be detected and none is provided', async () => {
+    const bytes = new Uint8Array([0x00, 0x01, 0x02, 0x03]);
+    await expect(loadImageResourceFromBytes(bytes)).rejects.toThrow('Unable to determine image type');
+  });
+
+  it('uses the provided mimeType and bypasses detection', async () => {
+    const bytes = new Uint8Array(16);
+    const resource = await loadImageResourceFromBytes(bytes, 'image/png');
+    expect(resource.source).toBeInstanceOf(HTMLImageElement);
+  });
+
+  it('detects PNG and resolves', async () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0, 0, 0, 0, 0]);
+    const resource = await loadImageResourceFromBytes(bytes);
+    expect(resource.source).toBeInstanceOf(HTMLImageElement);
+  });
+
+  it('detects JPEG and resolves', async () => {
+    const bytes = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
+    const resource = await loadImageResourceFromBytes(bytes);
+    expect(resource.source).toBeInstanceOf(HTMLImageElement);
+  });
+});
+
+describe('loadImageResourceFromUrl', () => {
+  it('does not set crossOrigin when no crossOrigin parameter is given', async () => {
+    let capturedImg: HTMLImageElement | undefined;
+    const origImage = globalThis.Image;
+    globalThis.Image = new Proxy(origImage, {
+      construct(Target, args) {
+        const img = new Target(...(args as []));
+        capturedImg = img;
+        return img;
+      },
+    }) as typeof Image;
+
+    await loadImageResourceFromUrl('/images/logo.png');
+    expect(capturedImg?.crossOrigin).toBeNull();
+
+    globalThis.Image = origImage;
+  });
+
+  it('rejects with an abort reason when the signal is already aborted before the call', async () => {
+    const controller = new AbortController();
+    controller.abort(new Error('cancelled'));
+    await expect(loadImageResourceFromUrl('data:image/png;base64,abc', undefined, controller.signal)).rejects.toThrow(
+      'cancelled',
+    );
+  });
+
+  it('resolves to an ImageResource whose source is an HTMLImageElement', async () => {
+    const resource = await loadImageResourceFromUrl('data:image/png;base64,abc');
+    expect(resource.source).toBeInstanceOf(HTMLImageElement);
+  });
+
+  it('sets crossOrigin when the crossOrigin parameter is provided', async () => {
+    let capturedImg: HTMLImageElement | undefined;
+    const origImage = globalThis.Image;
+    globalThis.Image = new Proxy(origImage, {
+      construct(Target, args) {
+        const img = new Target(...(args as []));
+        capturedImg = img;
+        return img;
+      },
+    }) as typeof Image;
+
+    await loadImageResourceFromUrl('https://cdn.other-domain.com/image.png', 'anonymous');
+    expect(capturedImg?.crossOrigin).toBe('anonymous');
+
+    globalThis.Image = origImage;
+  });
+});