@flighthq/image 0.3.0 → 0.3.1-next.1041.35b950c

package/dist/contract.d.ts

@@ -1,3 +1,4 @@
+export * from './imageBackend';
 export * from './imageResource';
 export * from './imageResourceFrom';
 export * from './imageResourceReference';

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/contract.js

@@ -1,3 +1,4 @@
+export * from './imageBackend';
 export * from './imageResource';
 export * from './imageResourceFrom';
 export * from './imageResourceReference';

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/imageBackend.d.ts

@@ -0,0 +1,5 @@
+import type { ImageBackend } from '@flighthq/types/contract';
+export declare function createWebImageBackend(): ImageBackend;
+export declare function getImageBackend(): ImageBackend;
+export declare function setImageBackend(backend: ImageBackend | null): void;
+//# sourceMappingURL=imageBackend.d.ts.map

package/dist/imageBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageBackend.d.ts","sourceRoot":"","sources":["../src/imageBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAYpE,wBAAgB,qBAAqB,IAAI,YAAY,CA8BpD;AAGD,wBAAgB,eAAe,IAAI,YAAY,CAG9C;AAKD,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAElE"}

package/dist/imageBackend.js

@@ -0,0 +1,57 @@
+import { createImageResourceFromImageElement } from './imageResourceFrom';
+// Builds the default web backend over `Image` + `decode()`. Created lazily by `getImageBackend` — no
+// DOM is touched at import time, so importing the package has no side effect.
+//
+// ★ THIS BODY IS THE PREVIOUS `loadImageResourceFromUrl` MOVED VERBATIM, INCLUDING ITS KNOWN ABORT
+// RACE: aborting rejects the caller and clears `src`, but the underlying load may already be in
+// flight and is not guaranteed to stop. That defect is preserved deliberately rather than repaired
+// here — this change is the seam, and fixing behaviour while relocating it would make the seam
+// unreviewable against the approval that authorised it.
+export function createWebImageBackend() {
+    return {
+        async loadImageFromUrl(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 and reject with the signal's reason. Always remove the
+            // listener when the race settles so a long-lived signal does not retain the image and closure.
+            if (signal !== undefined) {
+                let rejectAbort = () => { };
+                const abortPromise = new Promise((_, reject) => {
+                    rejectAbort = reject;
+                });
+                const onAbort = () => {
+                    img.src = '';
+                    rejectAbort(signal.reason);
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                try {
+                    await Promise.race([img.decode(), abortPromise]);
+                }
+                finally {
+                    signal.removeEventListener('abort', onAbort);
+                }
+            }
+            else {
+                await img.decode();
+            }
+            return createImageResourceFromImageElement(img);
+        },
+    };
+}
+// The active image backend, lazily defaulting to the web one. There is always a backend.
+export function getImageBackend() {
+    if (_backend === null)
+        _backend = createWebImageBackend();
+    return _backend;
+}
+// Installs a native host image backend; pass null to fall back to the lazy web default. Resettable on
+// purpose: a seam a caller cannot restore is a one-way door, and a test that swapped the backend could
+// not put it back.
+export function setImageBackend(backend) {
+    _backend = backend;
+}
+let _backend = null;
+//# sourceMappingURL=imageBackend.js.map

package/dist/imageBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageBackend.js","sourceRoot":"","sources":["../src/imageBackend.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAC;AAE1E,qGAAqG;AACrG,8EAA8E;AAC9E,EAAE;AACF,mGAAmG;AACnG,gGAAgG;AAChG,mGAAmG;AACnG,+FAA+F;AAC/F,wDAAwD;AACxD,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,KAAK,CAAC,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM;YAC7C,MAAM,EAAE,cAAc,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;YACxB,IAAI,WAAW,KAAK,SAAS;gBAAE,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC;YAC7D,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC;YACd,iGAAiG;YACjG,+FAA+F;YAC/F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,IAAI,WAAW,GAA+B,GAAG,EAAE,GAAE,CAAC,CAAC;gBACvD,MAAM,YAAY,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;oBACpD,WAAW,GAAG,MAAM,CAAC;gBACvB,CAAC,CAAC,CAAC;gBACH,MAAM,OAAO,GAAG,GAAS,EAAE;oBACzB,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC;oBACb,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC7B,CAAC,CAAC;gBACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC1D,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;gBACnD,CAAC;wBAAS,CAAC;oBACT,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC/C,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;YACrB,CAAC;YACD,OAAO,mCAAmC,CAAC,GAAG,CAAC,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,eAAe;IAC7B,IAAI,QAAQ,KAAK,IAAI;QAAE,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IAC1D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,sGAAsG;AACtG,uGAAuG;AACvG,mBAAmB;AACnB,MAAM,UAAU,eAAe,CAAC,OAA4B;IAC1D,QAAQ,GAAG,OAAO,CAAC;AACrB,CAAC;AAED,IAAI,QAAQ,GAAwB,IAAI,CAAC"}

package/dist/imageResourceFrom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imageResourceFrom.d.ts","sourceRoot":"","sources":["../src/imageResourceFrom.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAO9D,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,KAAK,CAQ7E;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,iBAAiB,GAAG,KAAK,CAU9E;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAU7E;AAED,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,gBAAgB,GAAG,KAAK,CAUhF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,KAAK,CAAC,CAEhB;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAOhG;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,KAAK,CAAC,CAOhB;AAED,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,EAC7C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,KAAK,CAAC,CA0BhB"}
+{"version":3,"file":"imageResourceFrom.d.ts","sourceRoot":"","sources":["../src/imageResourceFrom.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAS9D,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,KAAK,CAQ7E;AAsBD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,iBAAiB,GAAG,KAAK,CAU9E;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAU7E;AAED,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,gBAAgB,GAAG,KAAK,CAUhF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,KAAK,CAAC,CAEhB;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAOhG;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,KAAK,CAAC,CAOhB;AAED,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,EAC7C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,KAAK,CAAC,CAEhB"}

package/dist/imageResourceFrom.js

@@ -1,6 +1,7 @@
 import { createEntity } from '@flighthq/entity/contract';
 import { detectImageMimeType } from '@flighthq/image-codec/contract';
 import { ImageTextureSourceKind } from '@flighthq/types/contract';
+import { getImageBackend } from './imageBackend';
 // Transcodes a Bitmap's raw pixels into an element-backed Image, via a detached canvas.
 // The inverse of captureBitmapFromImageResource. Lives here rather than in @flighthq/bitmap because a
 // conversion belongs with the type it PRODUCES: you look for it under what you want to end up with.
@@ -10,10 +11,29 @@ export function createImageResourceFromBitmap(bitmap) {
     canvas.width = bitmap.width;
     canvas.height = bitmap.height;
     const domImageData = new globalThis.ImageData(bitmap.width, bitmap.height);
-    domImageData.data.set(bitmap.data);
+    domImageData.data.set(bitmap.alphaType === 'premultiplied' ? unpremultiplyRgba8(bitmap.data) : bitmap.data);
     canvas.getContext('2d').putImageData(domImageData, 0, 0);
     return createImageResourceFromCanvas(canvas);
 }
+// ImageData is straight-alpha by contract. Preserve a Bitmap's declared representation at its own seam,
+// then normalize only the scratch browser copy used to materialize a CanvasImageSource for Canvas/DOM.
+function unpremultiplyRgba8(source) {
+    const data = new Uint8ClampedArray(source);
+    for (let i = 0; i < data.length; i += 4) {
+        const alpha = data[i + 3];
+        if (alpha === 0) {
+            data[i] = 0;
+            data[i + 1] = 0;
+            data[i + 2] = 0;
+            continue;
+        }
+        const scale = 255 / alpha;
+        data[i] = Math.min(255, Math.round(data[i] * scale));
+        data[i + 1] = Math.min(255, Math.round(data[i + 1] * scale));
+        data[i + 2] = Math.min(255, Math.round(data[i + 2] * scale));
+    }
+    return data;
+}
 export function createImageResourceFromCanvas(canvas) {
     return createEntity({
         alphaType: DECODED_ALPHA_TYPE,
@@ -78,34 +98,7 @@ export async function loadImageResourceFromBytes(bytes, mimeType, signal) {
     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 and reject with the signal's reason. Always remove the
-    // listener when the race settles so a long-lived signal does not retain the image and closure.
-    if (signal !== undefined) {
-        let rejectAbort = () => { };
-        const abortPromise = new Promise((_, reject) => {
-            rejectAbort = reject;
-        });
-        const onAbort = () => {
-            img.src = '';
-            rejectAbort(signal.reason);
-        };
-        signal.addEventListener('abort', onAbort, { once: true });
-        try {
-            await Promise.race([img.decode(), abortPromise]);
-        }
-        finally {
-            signal.removeEventListener('abort', onAbort);
-        }
-    }
-    else {
-        await img.decode();
-    }
-    return createImageResourceFromImageElement(img);
+    return getImageBackend().loadImageFromUrl(url, crossOrigin, signal);
 }
 // The host-decode truth for every browser-backed source; see imageResource.ts.
 const DECODED_ALPHA_TYPE = 'straight';

package/dist/imageResourceFrom.js.map

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

package/dist/imageResourceReference.d.ts

@@ -1,8 +1,10 @@
-import type { EmbeddedImageResourceReference, ExternalImageResourceReference, Image, ImageResourceFailure, ImageResourceFetch, ImageResourceReference, ImageResourceReferenceResolutionExplanation } from '@flighthq/types/contract';
-export declare function createEmbeddedImageResourceReference(bytes: Uint8Array, mimeType?: string | null): EmbeddedImageResourceReference;
+import type { AlphaType, EmbeddedImageResourceReference, ExternalImageResourceReference, ImageResourceFailure, ImageResourceFetch, ImageResourceReference, ImageResourceReferenceResolutionExplanation, TextureSource } from '@flighthq/types/contract';
+export declare function createEmbeddedImageResourceReference(bytes: Uint8Array, mimeType?: string | null, alphaType?: AlphaType): EmbeddedImageResourceReference;
 export declare function createExternalImageResourceReference(uri: string, basePath?: string | null): ExternalImageResourceReference;
 export declare function createImageResourceFailure(cause: unknown): ImageResourceFailure;
+export declare function disableImageBitmapComposition(): void;
+export declare function enableImageBitmapComposition(): void;
 export declare function explainImageResourceReferenceResolution(ref: Readonly<ImageResourceReference>): ImageResourceReferenceResolutionExplanation;
 export declare function resetFailedImageResourceReference(ref: ImageResourceReference): boolean;
-export declare function resolveImageResourceReference(ref: ImageResourceReference, fetch: ImageResourceFetch, signal: AbortSignal): Promise<Image | null>;
+export declare function resolveImageResourceReference(ref: ImageResourceReference, fetch: ImageResourceFetch, signal: AbortSignal): Promise<TextureSource | null>;
 //# sourceMappingURL=imageResourceReference.d.ts.map

package/dist/imageResourceReference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imageResourceReference.d.ts","sourceRoot":"","sources":["../src/imageResourceReference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,8BAA8B,EAC9B,KAAK,EACL,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,2CAA2C,EAC5C,MAAM,0BAA0B,CAAC;AAYlC,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,UAAU,EACjB,QAAQ,GAAE,MAAM,GAAG,IAAW,GAC7B,8BAA8B,CAShC;AAED,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAM,GAAG,IAAW,GAC7B,8BAA8B,CAUhC;AAID,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAK/E;AAID,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GACpC,2CAA2C,CAO7C;AAID,wBAAgB,iCAAiC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAKtF;AAUD,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,sBAAsB,EAC3B,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAwBvB"}
+{"version":3,"file":"imageResourceReference.d.ts","sourceRoot":"","sources":["../src/imageResourceReference.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,SAAS,EAET,8BAA8B,EAE9B,8BAA8B,EAC9B,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,2CAA2C,EAC3C,aAAa,EACd,MAAM,0BAA0B,CAAC;AAWlC,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,UAAU,EACjB,QAAQ,GAAE,MAAM,GAAG,IAAW,EAC9B,SAAS,GAAE,SAAsB,GAChC,8BAA8B,CAUhC;AAgCD,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAM,GAAG,IAAW,GAC7B,8BAA8B,CAUhC;AAID,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAK/E;AAwBD,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAKD,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAID,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GACpC,2CAA2C,CAO7C;AAID,wBAAgB,iCAAiC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAKtF;AAUD,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,sBAAsB,EAC3B,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAkC/B"}

package/dist/imageResourceReference.js

@@ -1,10 +1,12 @@
-import { ImageResourceFailureKind, ImageResourceReferenceKind, ResourceResolutionState, } from '@flighthq/types/contract';
-import { loadImageResourceFromBytes } from './imageResourceFrom';
+import { createEntity } from '@flighthq/entity/contract';
+import { decodeImage, decodeImagePremultiplied, explainImageDecodeFailure, getImageBitmapComposer, } from '@flighthq/image-codec/contract';
+import { BitmapTextureSourceKind, ImageResourceFailureKind, ImageResourceReferenceKind, ResourceResolutionState, } from '@flighthq/types/contract';
 // `bytes` is retained as the view the container handed over, not a copy: a parser carves an image payload
 // out of its source and the reference borrows it, so a document that never resolves an image never pays for
 // its pixels. `textures` starts empty and each waiting Texture subscribes itself.
-export function createEmbeddedImageResourceReference(bytes, mimeType = null) {
+export function createEmbeddedImageResourceReference(bytes, mimeType = null, alphaType = 'straight') {
     return {
+        alphaType,
         bytes,
         failure: null,
         kind: ImageResourceReferenceKind.Embedded,
@@ -13,6 +15,33 @@ export function createEmbeddedImageResourceReference(bytes, mimeType = null) {
         textures: [],
     };
 }
+// The one encoded-byte producer for image resource references. A registered decoder owns format
+// knowledge; this async resource layer turns its RGBA result into the live Bitmap entity renderers
+// dispatch by kind. The reference's alpha request is carried onto the source verbatim, so bytes that
+// are already premultiplied never get multiplied a second time at renderer upload.
+async function decodeEmbeddedImageResourceReference(ref, signal) {
+    if (ref.bitmapComposition !== undefined && _resolveImageBitmapComposition !== null) {
+        return _resolveImageBitmapComposition(ref, signal);
+    }
+    signal.throwIfAborted();
+    const decoded = await (ref.alphaType === 'premultiplied'
+        ? decodeImagePremultiplied(ref.bytes, ref.mimeType ?? undefined)
+        : decodeImage(ref.bytes, ref.mimeType ?? undefined));
+    signal.throwIfAborted();
+    if (decoded === null)
+        return null;
+    const bitmap = {
+        alphaType: ref.alphaType,
+        data: new Uint8ClampedArray(decoded.data),
+        format: 'rgba8unorm',
+        gamut: 'srgb',
+        height: decoded.height,
+        kind: BitmapTextureSourceKind,
+        version: 0,
+        width: decoded.width,
+    };
+    return createEntity(bitmap);
+}
 export function createExternalImageResourceReference(uri, basePath = null) {
     return {
         basePath,
@@ -32,6 +61,28 @@ export function createImageResourceFailure(cause) {
     }
     return { kind: ImageResourceFailureKind.Error, message: String(cause), name: null };
 }
+async function resolveImageBitmapComposition(ref, signal) {
+    signal.throwIfAborted();
+    const composition = ref.bitmapComposition;
+    const composer = getImageBitmapComposer(composition.kind);
+    if (composer === null)
+        return null;
+    // A composer always receives straight decoded pixels. It may also own a raw raster with no MIME
+    // decoder, in which case decoded is null and its plain payload is the complete input.
+    const decoded = await decodeImage(ref.bytes, ref.mimeType ?? undefined);
+    signal.throwIfAborted();
+    return composer(decoded, composition.payload);
+}
+let _resolveImageBitmapComposition = null;
+export function disableImageBitmapComposition() {
+    _resolveImageBitmapComposition = null;
+}
+// Installs the optional decoded-pixel join without making an ordinary embedded-image consumer retain
+// its registry lookup or straight-decode branch. A format package calls this beside its composer
+// registrations; until then the nullable hook leaves the original hot path byte-for-byte tree-shakable.
+export function enableImageBitmapComposition() {
+    _resolveImageBitmapComposition = resolveImageBitmapComposition;
+}
 // Returns a detached plain-data explanation suitable for logs, tools, and serialization. It never throws
 // and exposes no resolver runtime or raw thrown value.
 export function explainImageResourceReferenceResolution(ref) {
@@ -51,7 +102,7 @@ export function resetFailedImageResourceReference(ref) {
     ref.state = ResourceResolutionState.Unresolved;
     return true;
 }
-// Advances one reference through its lifecycle and returns the decoded image, or null for an expected
+// Advances one reference through its lifecycle and returns the decoded texture source, or null for an expected
 // failure. Embedded bytes decode through @flighthq/image-codec; an External uri goes through the caller's
 // fetch seam. An abort is a cancel rather than a failure, so the reference reverts to Unresolved and the
 // rejection propagates — a caller racing several loads against one signal sees one cancellation, not a
@@ -63,16 +114,25 @@ export async function resolveImageResourceReference(ref, fetch, signal) {
     ref.failure = null;
     ref.state = ResourceResolutionState.Loading;
     try {
-        const image = ref.kind === ImageResourceReferenceKind.Embedded
-            ? await loadImageResourceFromBytes(ref.bytes, ref.mimeType ?? undefined, signal)
+        const usesOrdinaryEmbeddedDecode = ref.kind === ImageResourceReferenceKind.Embedded &&
+            (ref.bitmapComposition === undefined || _resolveImageBitmapComposition === null);
+        const source = ref.kind === ImageResourceReferenceKind.Embedded
+            ? await decodeEmbeddedImageResourceReference(ref, signal)
             : await fetch(ref, signal);
-        if (image === null) {
-            ref.failure = { kind: ImageResourceFailureKind.Unavailable, message: 'Image resource unavailable', name: null };
+        if (source === null) {
+            const decodeFailure = usesOrdinaryEmbeddedDecode
+                ? explainImageDecodeFailure(ref.bytes, ref.mimeType ?? undefined)
+                : null;
+            ref.failure = {
+                kind: ImageResourceFailureKind.Unavailable,
+                message: decodeFailure?.reason ?? 'Image resource unavailable',
+                name: null,
+            };
             ref.state = ResourceResolutionState.Failed;
             return null;
         }
         ref.state = ResourceResolutionState.Resolved;
-        return image;
+        return source;
     }
     catch (cause) {
         if (signal.aborted) {

package/dist/imageResourceReference.js.map

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

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { cloneImageResource, createCompressedImage, createEmbeddedImageResourceReference, createExternalImageResourceReference, createImageResource, createImageResourceFailure, createImageResourceFromBitmap, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, explainImageResourceReferenceResolution, isImageResourceEmpty, isImageUrlSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, resetFailedImageResourceReference, resolveImageResourceReference, } from './contract';
+export { cloneImageResource, createCompressedImage, createEmbeddedImageResourceReference, createExternalImageResourceReference, createImageResource, createImageResourceFailure, createImageResourceFromBitmap, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, disableImageBitmapComposition, enableImageBitmapComposition, explainImageResourceReferenceResolution, isImageResourceEmpty, isImageUrlSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, resetFailedImageResourceReference, resolveImageResourceReference, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,oCAAoC,EACpC,oCAAoC,EACpC,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,6BAA6B,EAC7B,kCAAkC,EAClC,mCAAmC,EACnC,uCAAuC,EACvC,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,iCAAiC,EACjC,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,oCAAoC,EACpC,oCAAoC,EACpC,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,6BAA6B,EAC7B,kCAAkC,EAClC,mCAAmC,EACnC,6BAA6B,EAC7B,4BAA4B,EAC5B,uCAAuC,EACvC,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,iCAAiC,EACjC,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { cloneImageResource, createCompressedImage, createEmbeddedImageResourceReference, createExternalImageResourceReference, createImageResource, createImageResourceFailure, createImageResourceFromBitmap, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, explainImageResourceReferenceResolution, isImageResourceEmpty, isImageUrlSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, resetFailedImageResourceReference, resolveImageResourceReference, } from './contract';
+export { cloneImageResource, createCompressedImage, createEmbeddedImageResourceReference, createExternalImageResourceReference, createImageResource, createImageResourceFailure, createImageResourceFromBitmap, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, disableImageBitmapComposition, enableImageBitmapComposition, explainImageResourceReferenceResolution, isImageResourceEmpty, isImageUrlSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, resetFailedImageResourceReference, resolveImageResourceReference, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,oCAAoC,EACpC,oCAAoC,EACpC,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,6BAA6B,EAC7B,kCAAkC,EAClC,mCAAmC,EACnC,uCAAuC,EACvC,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,iCAAiC,EACjC,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,oCAAoC,EACpC,oCAAoC,EACpC,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,6BAA6B,EAC7B,kCAAkC,EAClC,mCAAmC,EACnC,6BAA6B,EAC7B,4BAA4B,EAC5B,uCAAuC,EACvC,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,iCAAiC,EACjC,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/image",
-  "version": "0.3.0",
+  "version": "0.3.1-next.1041.35b950c",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,9 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/entity": "0.3.0",
-    "@flighthq/image-codec": "0.3.0",
-    "@flighthq/types": "0.3.0"
+    "@flighthq/entity": "0.3.1-next.1041.35b950c",
+    "@flighthq/image-codec": "0.3.1-next.1041.35b950c",
+    "@flighthq/types": "0.3.1-next.1041.35b950c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/imageBackend.test.ts

@@ -0,0 +1,74 @@
+import type { Image, ImageBackend } from '@flighthq/types/contract';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createWebImageBackend, getImageBackend, setImageBackend } from './imageBackend';
+import { loadImageResourceFromUrl } from './imageResourceFrom';
+
+// Every test that installs a backend must put it back, or a later test sees a stale one.
+afterEach(() => setImageBackend(null));
+
+function recordingBackend(): { backend: ImageBackend; calls: unknown[][] } {
+  const calls: unknown[][] = [];
+  return {
+    backend: {
+      loadImageFromUrl(url, crossOrigin, signal): Promise<Image> {
+        calls.push([url, crossOrigin, signal]);
+        return Promise.resolve({} as Image);
+      },
+    },
+    calls,
+  };
+}
+
+describe('createWebImageBackend', () => {
+  it('builds a backend without touching the DOM until it is called', () => {
+    // Constructing must not decode anything; the DOM work belongs inside `loadImageFromUrl`.
+    const backend = createWebImageBackend();
+    expect(typeof backend.loadImageFromUrl).toBe('function');
+  });
+
+  it('builds a fresh backend each call rather than a shared singleton', () => {
+    expect(createWebImageBackend()).not.toBe(createWebImageBackend());
+  });
+});
+
+describe('getImageBackend', () => {
+  it('defaults lazily to a web backend rather than being registered at import', () => {
+    expect(typeof getImageBackend().loadImageFromUrl).toBe('function');
+  });
+
+  it('caches the lazy default so repeated calls do not rebuild it', () => {
+    expect(getImageBackend()).toBe(getImageBackend());
+  });
+
+  it('returns the installed backend once one is set', () => {
+    const { backend } = recordingBackend();
+    setImageBackend(backend);
+    expect(getImageBackend()).toBe(backend);
+  });
+});
+
+describe('setImageBackend', () => {
+  it('restores a working web default when passed null, rather than leaving a one-way door', () => {
+    const { backend } = recordingBackend();
+    setImageBackend(backend);
+    setImageBackend(null);
+    const restored = getImageBackend();
+    // Not merely non-null: it must not be the backend that was uninstalled, and it must be usable.
+    expect(restored).not.toBe(backend);
+    expect(typeof restored.loadImageFromUrl).toBe('function');
+  });
+
+  it('routes loadImageResourceFromUrl through the active backend, arguments intact', async () => {
+    // The seam is only real if the loader actually dispatches through it — a backend nobody calls
+    // would satisfy every test above and change nothing.
+    const { backend, calls } = recordingBackend();
+    setImageBackend(backend);
+    const signal = AbortSignal.abort === undefined ? undefined : new AbortController().signal;
+    await loadImageResourceFromUrl('https://example.test/a.png', 'anonymous', signal);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]![0]).toBe('https://example.test/a.png');
+    expect(calls[0]![1]).toBe('anonymous');
+    expect(calls[0]![2]).toBe(signal);
+  });
+});

package/src/imageResourceFrom.test.ts

@@ -44,6 +44,26 @@ describe('createImageResourceFromBitmap', () => {
     expect(resource.height).toBe(4);
     expect(resource.source).not.toBeNull();
   });
+
+  it('normalizes premultiplied Bitmap pixels for the straight-alpha ImageData bridge', () => {
+    const bitmap: Bitmap = createEntity({
+      alphaType: 'premultiplied',
+      gamut: 'srgb',
+      data: new Uint8ClampedArray([0x40, 0x20, 0x10, 0x80]),
+      format: 'rgba8unorm',
+      height: 1,
+      kind: BitmapTextureSourceKind,
+      version: 0,
+      width: 1,
+    });
+    const putImageData = vi.spyOn(CanvasRenderingContext2D.prototype, 'putImageData');
+
+    createImageResourceFromBitmap(bitmap);
+
+    const imageData = putImageData.mock.calls[0][0];
+    expect([...imageData.data]).toEqual([0x80, 0x40, 0x20, 0x80]);
+    expect([...bitmap.data]).toEqual([0x40, 0x20, 0x10, 0x80]);
+  });
 });
 
 describe('createImageResourceFromCanvas', () => {

package/src/imageResourceReference.test.ts

@@ -1,23 +1,44 @@
-import type { Image } from '@flighthq/types/contract';
-import { ImageResourceFailureKind, ResourceResolutionState } from '@flighthq/types/contract';
+import { createEntity } from '@flighthq/entity/contract';
+import {
+  clearImageBitmapComposers,
+  clearImageDecoders,
+  registerImageBitmapComposer,
+  registerImageDecoder,
+} from '@flighthq/image-codec/contract';
+import type { Bitmap, Image, ImageDecoder } from '@flighthq/types/contract';
+import {
+  BitmapTextureSourceKind,
+  EntityRuntimeKey,
+  ImageResourceFailureKind,
+  ResourceResolutionState,
+} from '@flighthq/types/contract';
 
 import {
   createEmbeddedImageResourceReference,
   createExternalImageResourceReference,
   createImageResourceFailure,
+  disableImageBitmapComposition,
+  enableImageBitmapComposition,
   explainImageResourceReferenceResolution,
   resetFailedImageResourceReference,
   resolveImageResourceReference,
 } from './imageResourceReference';
 
-// Stub img.decode() so the embedded decode path resolves in jsdom.
+let decoder: ReturnType<typeof vi.fn<ImageDecoder>>;
+
 beforeEach(() => {
-  HTMLImageElement.prototype.decode = vi.fn().mockResolvedValue(undefined);
+  decoder = vi.fn<ImageDecoder>().mockResolvedValue({
+    data: new Uint8ClampedArray([0x11, 0x22, 0x33, 0x44]),
+    height: 1,
+    width: 1,
+  });
+  registerImageDecoder('image/png', decoder);
 });
 
 afterEach(() => {
-  vi.restoreAllMocks();
-  delete (HTMLImageElement.prototype as Partial<HTMLImageElement>).decode;
+  disableImageBitmapComposition();
+  clearImageBitmapComposers();
+  clearImageDecoders();
 });
 
 const unusedFetch = () => Promise.resolve(null);
@@ -28,6 +49,7 @@ describe('createEmbeddedImageResourceReference', () => {
     const ref = createEmbeddedImageResourceReference(bytes, 'image/png');
     expect(ref.bytes).toBe(bytes);
     expect(ref.mimeType).toBe('image/png');
+    expect(ref.alphaType).toBe('straight');
   });
 
   it('starts unresolved with no failure and no subscribers', () => {
@@ -67,6 +89,37 @@ describe('createImageResourceFailure', () => {
   });
 });
 
+describe('disableImageBitmapComposition', () => {
+  it('restores the ordinary decoder path for a reference that carries composition data', async () => {
+    const composer = vi.fn().mockReturnValue(createTestBitmap('straight'));
+    registerImageBitmapComposer('acme/alpha-plane', composer);
+    enableImageBitmapComposition();
+    disableImageBitmapComposition();
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([1]), 'image/png');
+    ref.bitmapComposition = { kind: 'acme/alpha-plane', payload: new Uint8Array([7]) };
+
+    const source = await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal);
+
+    expect(composer).not.toHaveBeenCalled();
+    expect(decoder).toHaveBeenCalledWith(ref.bytes);
+    expect(source?.kind).toBe(BitmapTextureSourceKind);
+  });
+});
+
+describe('enableImageBitmapComposition', () => {
+  it('installs the registered decoded-pixel composition route', async () => {
+    const bitmap = createTestBitmap('straight');
+    const composer = vi.fn().mockReturnValue(bitmap);
+    registerImageBitmapComposer('acme/alpha-plane', composer);
+    enableImageBitmapComposition();
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([1]), 'image/png');
+    ref.bitmapComposition = { kind: 'acme/alpha-plane', payload: new Uint8Array([7]) };
+
+    expect(await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal)).toBe(bitmap);
+    expect(composer).toHaveBeenCalledOnce();
+  });
+});
+
 describe('explainImageResourceReferenceResolution', () => {
   it('detaches the failure so a caller cannot mutate the reference', () => {
     const ref = createEmbeddedImageResourceReference(new Uint8Array(1));
@@ -106,12 +159,85 @@ describe('resetFailedImageResourceReference', () => {
 describe('resolveImageResourceReference', () => {
   it('decodes embedded bytes and marks the reference resolved', async () => {
     const ref = createEmbeddedImageResourceReference(new Uint8Array([0x89, 0x50, 0x4e, 0x47]), 'image/png');
-    const image = await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal);
-    expect(image).not.toBeNull();
+    const source = await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal);
+    expect(source).toMatchObject({
+      alphaType: 'straight',
+      data: new Uint8ClampedArray([0x11, 0x22, 0x33, 0x44]),
+      height: 1,
+      kind: BitmapTextureSourceKind,
+      width: 1,
+    });
+    expect(EntityRuntimeKey in source!).toBe(true);
+    expect(decoder).toHaveBeenCalledWith(ref.bytes);
     expect(ref.state).toBe(ResourceResolutionState.Resolved);
     expect(ref.failure).toBeNull();
   });
 
+  it('requests and declares premultiplied output when the plain reference says its source retains it', async () => {
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([1]), 'image/png', 'premultiplied');
+
+    const source = await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal);
+
+    expect(decoder).toHaveBeenCalledWith(ref.bytes, { premultiplyAlpha: true });
+    expect(source?.alphaType).toBe('premultiplied');
+  });
+
+  it('hands straight decoded pixels and plain payload bytes to a registered Bitmap composer', async () => {
+    const payload = new Uint8Array([7, 8, 9]);
+    const bitmap = createTestBitmap('straight');
+    const composer = vi.fn().mockReturnValue(bitmap);
+    registerImageBitmapComposer('acme/alpha-plane', composer);
+    enableImageBitmapComposition();
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([1]), 'image/png', 'premultiplied');
+    ref.bitmapComposition = { kind: 'acme/alpha-plane', payload };
+
+    const source = await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal);
+
+    expect(decoder).toHaveBeenCalledWith(ref.bytes);
+    expect(composer).toHaveBeenCalledWith(
+      { data: new Uint8ClampedArray([0x11, 0x22, 0x33, 0x44]), height: 1, width: 1 },
+      payload,
+    );
+    expect(source).toBe(bitmap);
+  });
+
+  it('lets a registered raw-pixel producer return a Bitmap when no MIME decoder recognizes the bytes', async () => {
+    const bitmap = createTestBitmap('opaque');
+    const composer = vi.fn().mockReturnValue(bitmap);
+    registerImageBitmapComposer('acme/raw-raster', composer);
+    enableImageBitmapComposition();
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([1]));
+    ref.bitmapComposition = { kind: 'acme/raw-raster', payload: ref.bytes };
+
+    const source = await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal);
+
+    expect(composer).toHaveBeenCalledWith(null, ref.bytes);
+    expect(source).toBe(bitmap);
+  });
+
+  it('reports an unavailable resource when its declared Bitmap composer is not registered', async () => {
+    enableImageBitmapComposition();
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([1]));
+    ref.bitmapComposition = { kind: 'acme/missing', payload: ref.bytes };
+
+    expect(await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal)).toBeNull();
+    expect(decoder).not.toHaveBeenCalled();
+    expect(ref.state).toBe(ResourceResolutionState.Failed);
+    expect(ref.failure?.kind).toBe(ImageResourceFailureKind.Unavailable);
+  });
+
+  it('retains the missing-decoder cause when embedded bytes cannot be decoded', async () => {
+    clearImageDecoders();
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+
+    expect(await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal)).toBeNull();
+    expect(ref.failure).toEqual({
+      kind: ImageResourceFailureKind.Unavailable,
+      message: 'decoder-not-registered',
+      name: null,
+    });
+  });
+
   it('routes an external reference through the fetch seam', async () => {
     const ref = createExternalImageResourceReference('atlas.png', '/assets');
     const fetched = { width: 2 } as Image;
@@ -158,3 +284,16 @@ describe('resolveImageResourceReference', () => {
     expect(ref.state).toBe(ResourceResolutionState.Resolved);
   });
 });
+
+function createTestBitmap(alphaType: Bitmap['alphaType']): Bitmap {
+  return createEntity({
+    alphaType,
+    data: new Uint8ClampedArray([0x11, 0x22, 0x33, 0x44]),
+    format: 'rgba8unorm',
+    gamut: 'srgb',
+    height: 1,
+    kind: BitmapTextureSourceKind,
+    version: 0,
+    width: 1,
+  });
+}