@flighthq/image 0.3.0-next.906.07cea63 → 0.3.1-next.209.43ef1bc

package/dist/contract.d.ts

@@ -1,3 +1,4 @@
 export * from './imageResource';
 export * from './imageResourceFrom';
+export * from './imageResourceReference';
 //# sourceMappingURL=contract.d.ts.map

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"}
+{"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"}

package/dist/contract.js

@@ -1,3 +1,4 @@
 export * from './imageResource';
 export * from './imageResourceFrom';
+export * from './imageResourceReference';
 //# sourceMappingURL=contract.js.map

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"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/imageResource.d.ts

@@ -1,13 +1,7 @@
-import type { ImageResource, ImageResourceCompressed } from '@flighthq/types/contract';
-export declare function cloneImageResource(resource: Readonly<ImageResource>): ImageResource;
-export declare function createCompressedImageResource(compressed: Readonly<ImageResourceCompressed>): 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 hasImageResourcePixels(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;
+import type { CompressedImage, CompressedImageData, Image } from '@flighthq/types/contract';
+export declare function cloneImageResource(resource: Readonly<Image>): Image;
+export declare function createCompressedImage(compressed: Readonly<CompressedImageData>): CompressedImage;
+export declare function createImageResource(image: CanvasImageSource): Image;
+export declare function invalidateImageResource(resource: Image): void;
+export declare function isImageResourceEmpty(resource: Readonly<Image>): boolean;
 //# sourceMappingURL=imageResource.d.ts.map

package/dist/imageResource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imageResource.d.ts","sourceRoot":"","sources":["../src/imageResource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAMvF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,aAAa,CAWnF;AAMD,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,QAAQ,CAAC,uBAAuB,CAAC,GAAG,aAAa,CAW1G;AAED,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAa5E;AAMD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAKlE;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;AAQD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAEjF;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"}
+{"version":3,"file":"imageResource.d.ts","sourceRoot":"","sources":["../src/imageResource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAK5F,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,KAAK,CAUnE;AAID,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,eAAe,CAUhG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,CAYnE;AAGD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,KAAK,GAAG,IAAI,CAG7D;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,OAAO,CAEvE"}

package/dist/imageResource.js

@@ -1,104 +1,58 @@
 import { createEntity } from '@flighthq/entity/contract';
-// Allocates a new resource identity over the SAME underlying pixels. The element, the `data` array, and
-// the `compressed` payload 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.
+import { CompressedImageTextureSourceKind, ImageTextureSourceKind } from '@flighthq/types/contract';
+// Allocates a new resource identity over the same borrowed host image. The host handle is shared by
+// reference; the clone owns an independent version counter for renderer cache invalidation.
 export function cloneImageResource(resource) {
     return createEntity({
         alphaType: resource.alphaType,
-        compressed: resource.compressed,
-        data: resource.data,
-        format: resource.format,
+        gamut: resource.gamut,
         height: resource.height,
+        kind: resource.kind,
         source: resource.source,
         version: resource.version,
         width: resource.width,
     });
 }
-// Wraps a parsed block-compressed (KTX2/DDS/Basis) payload as an ImageResource. `width`/`height` mirror
-// the container's base-mip dimensions so the same 2D draw path sizes the quad; `source`/`data` stay null
-// (a GPU backend uploads the `compressed` payload instead, and a Canvas/DOM backend ignores it). The
-// caller owns the payload bytes the container's level ranges index into.
-export function createCompressedImageResource(compressed) {
+// Wraps a parsed block-compressed payload as its own GPU-only source. The caller owns the payload
+// bytes indexed by the container's level ranges.
+export function createCompressedImage(compressed) {
     return createEntity({
-        alphaType: 'straight',
+        alphaType: DECODED_ALPHA_TYPE,
         compressed,
-        data: null,
-        format: 'rgba8unorm',
+        gamut: DECODED_GAMUT,
         height: compressed.container.height,
-        source: null,
+        kind: CompressedImageTextureSourceKind,
         version: 0,
         width: compressed.container.width,
     });
 }
 export function createImageResource(image) {
     const resource = createEntity({
-        alphaType: 'straight',
-        compressed: null,
-        data: null,
-        format: 'rgba8unorm',
+        alphaType: DECODED_ALPHA_TYPE,
+        gamut: DECODED_GAMUT,
         height: 0,
-        source: image ?? null,
+        kind: ImageTextureSourceKind,
+        source: image,
         version: 0,
         width: 0,
     });
-    if (resource.source !== null)
-        updateImageResourceSize(resource);
+    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.compressed = null;
-    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;
-}
-// True when the resource carries pixels in any representation — a decoded `source` element, raw CPU
-// `data`, or a block-`compressed` payload. The upload-readiness predicate for backends that can consume
-// any of them: an element-only load, a data-only generated Surface, a compressed-only parsed container,
-// or a resource holding several are all uploadable. Prefer this over hasImageResourceSource at any gate
-// that feeds a source-or-data uploader (bindGlTexture, bindWgpuTexture), so a memory-generated Surface
-// or a compressed container is not rejected for lacking an element.
-export function hasImageResourcePixels(resource) {
-    return resource.source !== null || resource.data !== null || resource.compressed !== 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.
+// Marks changed pixels behind the same borrowed host handle. The handle itself remains immutable.
 export function invalidateImageResource(resource) {
+    updateImageResourceSize(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
+// Reads pixel dimensions from the current host 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 === null)
+        return;
     if (element instanceof HTMLVideoElement) {
         resource.width = element.videoWidth;
         resource.height = element.videoHeight;
@@ -109,4 +63,11 @@ function updateImageResourceSize(resource) {
         resource.height = sized.height;
     }
 }
+// What a HOST decode yields, and the only honest default for a source whose pixels we never touch.
+// Every browser image/canvas/ImageBitmap decode is straight-alpha sRGB, so declaring it is a statement
+// of fact rather than an assumption — which is the point: a producer that knows otherwise (a native
+// iOS/Android decode commonly premultiplies) now has somewhere to say so, and the uploaders' existing
+// `alphaType !== 'premultiplied'` guard starts protecting Image the way it already protects Bitmap.
+const DECODED_ALPHA_TYPE = 'straight';
+const DECODED_GAMUT = 'srgb';
 //# sourceMappingURL=imageResource.js.map

package/dist/imageResource.js.map

@@ -1 +1 @@
-{"version":3,"file":"imageResource.js","sourceRoot":"","sources":["../src/imageResource.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"imageResource.js","sourceRoot":"","sources":["../src/imageResource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,gCAAgC,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEpG,oGAAoG;AACpG,4FAA4F;AAC5F,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,OAAO,YAAY,CAAC;QAClB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC,CAAC;AACL,CAAC;AAED,kGAAkG;AAClG,iDAAiD;AACjD,MAAM,UAAU,qBAAqB,CAAC,UAAyC;IAC7E,OAAO,YAAY,CAAC;QAClB,SAAS,EAAE,kBAAkB;QAC7B,UAAU;QACV,KAAK,EAAE,aAAa;QACpB,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC,MAAM;QACnC,IAAI,EAAE,gCAAgC;QACtC,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK;KAClC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAwB;IAC1D,MAAM,QAAQ,GAAU,YAAY,CAAC;QACnC,SAAS,EAAE,kBAAkB;QAC7B,KAAK,EAAE,aAAa;QACpB,MAAM,EAAE,CAAC;QACT,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,CAAC;KACT,CAAC,CAAC;IACH,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,uBAAuB,CAAC,QAAe;IACrD,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAClC,QAAQ,CAAC,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,QAAyB;IAC5D,OAAO,QAAQ,CAAC,KAAK,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,0FAA0F;AAC1F,uFAAuF;AACvF,SAAS,uBAAuB,CAAC,QAAe;IAC9C,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC;IAChC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO;IAC7B,IAAI,OAAO,YAAY,gBAAgB,EAAE,CAAC;QACxC,QAAQ,CAAC,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;QACpC,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,OAA6D,CAAC;QAC5E,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC7B,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACjC,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,uGAAuG;AACvG,oGAAoG;AACpG,sGAAsG;AACtG,oGAAoG;AACpG,MAAM,kBAAkB,GAAG,UAAU,CAAC;AACtC,MAAM,aAAa,GAAG,MAAM,CAAC"}

package/dist/imageResourceFrom.d.ts

@@ -1,11 +1,11 @@
-import type { ImageResource } from '@flighthq/types/contract';
-export declare function createCanvasFromImageResource(image: Readonly<ImageResource>): HTMLCanvasElement | null;
-export declare function createImageResourceFromCanvas(canvas: HTMLCanvasElement): ImageResource;
-export declare function createImageResourceFromImageBitmap(bitmap: ImageBitmap): ImageResource;
-export declare function createImageResourceFromImageElement(img: HTMLImageElement): ImageResource;
-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>;
+import type { Bitmap, Image } from '@flighthq/types/contract';
+export declare function createImageResourceFromBitmap(bitmap: Readonly<Bitmap>): Image;
+export declare function createImageResourceFromCanvas(canvas: HTMLCanvasElement): Image;
+export declare function createImageResourceFromImageBitmap(bitmap: ImageBitmap): Image;
+export declare function createImageResourceFromImageElement(img: HTMLImageElement): Image;
+export declare function isImageUrlSameOrigin(url: string): boolean;
+export declare function loadImageResourceFromBase64(base64: string, mimeType: string, signal?: AbortSignal): Promise<Image>;
+export declare function loadImageResourceFromBlob(blob: Blob, signal?: AbortSignal): Promise<Image>;
+export declare function loadImageResourceFromBytes(bytes: Uint8Array, mimeType?: string, signal?: AbortSignal): Promise<Image>;
+export declare function loadImageResourceFromUrl(url: string, crossOrigin?: 'anonymous' | 'use-credentials', signal?: AbortSignal): Promise<Image>;
 //# sourceMappingURL=imageResourceFrom.d.ts.map

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,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAQ9D,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAStG;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAWtF;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAWrF;AAED,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAWxF;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"}
+{"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;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,CA0BhB"}

package/dist/imageResourceFrom.js

@@ -1,29 +1,44 @@
 import { createEntity } from '@flighthq/entity/contract';
 import { detectImageMimeType } from '@flighthq/image-codec/contract';
-// Materializes a data-backed ImageResource's raw pixels into a detached, drawable HTMLCanvasElement
-// via putImageData. The inverse of createImageResourceFromCanvas: it turns the portable `data`
-// representation of a generated Surface into the host element that Canvas/DOM `drawImage` needs.
-// Returns null for an element-only resource (no `data` to transcode). Straight-alpha in, straight-alpha
-// out — the drawn canvas matches the source's `alphaType`. Callers that draw data-only resources cache
-// the result keyed on `version`; this primitive allocates a fresh canvas on every call.
-export function createCanvasFromImageResource(image) {
-    if (image.data === null)
-        return null;
+import { ImageTextureSourceKind } from '@flighthq/types/contract';
+// 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.
+// Allocates a fresh canvas on every call; callers that draw repeatedly should hold the result.
+export function createImageResourceFromBitmap(bitmap) {
     const canvas = document.createElement('canvas');
-    canvas.width = image.width;
-    canvas.height = image.height;
-    const imageData = new globalThis.ImageData(image.width, image.height);
-    imageData.data.set(image.data);
-    canvas.getContext('2d').putImageData(imageData, 0, 0);
-    return canvas;
+    canvas.width = bitmap.width;
+    canvas.height = bitmap.height;
+    const domImageData = new globalThis.ImageData(bitmap.width, bitmap.height);
+    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: 'straight',
-        compressed: null,
-        data: null,
-        format: 'rgba8unorm',
+        alphaType: DECODED_ALPHA_TYPE,
+        gamut: DECODED_GAMUT,
         height: canvas.height,
+        kind: ImageTextureSourceKind,
         source: canvas,
         version: 0,
         width: canvas.width,
@@ -31,11 +46,10 @@ export function createImageResourceFromCanvas(canvas) {
 }
 export function createImageResourceFromImageBitmap(bitmap) {
     return createEntity({
-        alphaType: 'straight',
-        compressed: null,
-        data: null,
-        format: 'rgba8unorm',
+        alphaType: DECODED_ALPHA_TYPE,
+        gamut: DECODED_GAMUT,
         height: bitmap.height,
+        kind: ImageTextureSourceKind,
         source: bitmap,
         version: 0,
         width: bitmap.width,
@@ -43,17 +57,16 @@ export function createImageResourceFromImageBitmap(bitmap) {
 }
 export function createImageResourceFromImageElement(img) {
     return createEntity({
-        alphaType: 'straight',
-        compressed: null,
-        data: null,
-        format: 'rgba8unorm',
+        alphaType: DECODED_ALPHA_TYPE,
+        gamut: DECODED_GAMUT,
         height: img.height,
+        kind: ImageTextureSourceKind,
         source: img,
         version: 0,
         width: img.width,
     });
 }
-export function isImageResourceSameOrigin(url) {
+export function isImageUrlSameOrigin(url) {
     if (url.startsWith('data:') || url.startsWith('blob:'))
         return true;
     try {
@@ -89,16 +102,31 @@ export async function loadImageResourceFromUrl(url, crossOrigin, signal) {
     if (crossOrigin !== undefined)
         img.crossOrigin = crossOrigin;
     img.src = url;
-    // Wire abort to cancel the pending decode by rejecting the promise.
+    // 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) {
-        await Promise.race([
-            img.decode(),
-            new Promise((_, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true })),
-        ]);
+        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 host-decode truth for every browser-backed source; see imageResource.ts.
+const DECODED_ALPHA_TYPE = 'straight';
+const DECODED_GAMUT = 'srgb';
 //# sourceMappingURL=imageResourceFrom.js.map

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

@@ -0,0 +1,8 @@
+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 explainImageResourceReferenceResolution(ref: Readonly<ImageResourceReference>): ImageResourceReferenceResolutionExplanation;
+export declare function resetFailedImageResourceReference(ref: ImageResourceReference): boolean;
+export declare function resolveImageResourceReference(ref: ImageResourceReference, fetch: ImageResourceFetch, signal: AbortSignal): Promise<TextureSource | null>;
+//# sourceMappingURL=imageResourceReference.d.ts.map

package/dist/imageResourceReference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageResourceReference.d.ts","sourceRoot":"","sources":["../src/imageResourceReference.ts"],"names":[],"mappings":"AAEA,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;AA6BD,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,aAAa,GAAG,IAAI,CAAC,CAwB/B"}

package/dist/imageResourceReference.js

@@ -0,0 +1,113 @@
+import { createEntity } from '@flighthq/entity/contract';
+import { decodeImage, decodeImagePremultiplied } 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, alphaType = 'straight') {
+    return {
+        alphaType,
+        bytes,
+        failure: null,
+        kind: ImageResourceReferenceKind.Embedded,
+        mimeType,
+        state: ResourceResolutionState.Unresolved,
+        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) {
+    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,
+        failure: null,
+        kind: ImageResourceReferenceKind.External,
+        mimeType: null,
+        state: ResourceResolutionState.Unresolved,
+        textures: [],
+        uri,
+    };
+}
+// Reduces a thrown value to the serialization-safe categories a reference retains. Raw Error objects and
+// arbitrary thrown values stay inside the resolving operation; diagnostics get category, name, and message.
+export function createImageResourceFailure(cause) {
+    if (cause instanceof Error) {
+        return { kind: ImageResourceFailureKind.Error, message: cause.message, name: cause.name };
+    }
+    return { kind: ImageResourceFailureKind.Error, message: String(cause), name: null };
+}
+// 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) {
+    return {
+        failure: ref.failure === null ? null : { ...ref.failure },
+        kind: ref.kind,
+        retryable: ref.state === ResourceResolutionState.Failed,
+        state: ref.state,
+    };
+}
+// Returns a failed reference to the requestable state. Loading/resolved/unresolved references are unchanged
+// so this atom cannot invalidate live work or a successfully bound resource accidentally.
+export function resetFailedImageResourceReference(ref) {
+    if (ref.state !== ResourceResolutionState.Failed)
+        return false;
+    ref.failure = null;
+    ref.state = ResourceResolutionState.Unresolved;
+    return true;
+}
+// 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
+// document full of spurious Failed references.
+//
+// This is the whole lifecycle for a document that resolves its images once. A caller needing concurrency
+// limits, priority, or retry drives those around this atom rather than inside it.
+export async function resolveImageResourceReference(ref, fetch, signal) {
+    ref.failure = null;
+    ref.state = ResourceResolutionState.Loading;
+    try {
+        const source = ref.kind === ImageResourceReferenceKind.Embedded
+            ? await decodeEmbeddedImageResourceReference(ref, signal)
+            : await fetch(ref, signal);
+        if (source === null) {
+            ref.failure = { kind: ImageResourceFailureKind.Unavailable, message: 'Image resource unavailable', name: null };
+            ref.state = ResourceResolutionState.Failed;
+            return null;
+        }
+        ref.state = ResourceResolutionState.Resolved;
+        return source;
+    }
+    catch (cause) {
+        if (signal.aborted) {
+            ref.state = ResourceResolutionState.Unresolved;
+            throw cause;
+        }
+        ref.failure = createImageResourceFailure(cause);
+        ref.state = ResourceResolutionState.Failed;
+        return null;
+    }
+}
+//# sourceMappingURL=imageResourceReference.js.map

package/dist/imageResourceReference.js.map

@@ -0,0 +1 @@
+{"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, createCanvasFromImageResource, createCompressedImageResource, createImageResource, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, disposeImageResource, getImageResourceByteSize, hasImageResourceData, hasImageResourcePixels, hasImageResourceSource, isImageResourceEmpty, isImageResourceSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, setImageResourceSource, } from './contract';
+export { cloneImageResource, createCompressedImage, createEmbeddedImageResourceReference, createExternalImageResourceReference, createImageResource, createImageResourceFailure, createImageResourceFromBitmap, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, 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,6BAA6B,EAC7B,6BAA6B,EAC7B,mBAAmB,EACnB,6BAA6B,EAC7B,kCAAkC,EAClC,mCAAmC,EACnC,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,GACvB,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,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, createCanvasFromImageResource, createCompressedImageResource, createImageResource, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, disposeImageResource, getImageResourceByteSize, hasImageResourceData, hasImageResourcePixels, hasImageResourceSource, isImageResourceEmpty, isImageResourceSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, setImageResourceSource, } from './contract';
+export { cloneImageResource, createCompressedImage, createEmbeddedImageResourceReference, createExternalImageResourceReference, createImageResource, createImageResourceFailure, createImageResourceFromBitmap, createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, 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,6BAA6B,EAC7B,6BAA6B,EAC7B,mBAAmB,EACnB,6BAA6B,EAC7B,kCAAkC,EAClC,mCAAmC,EACnC,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,GACvB,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,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,8 @@
 {
   "name": "@flighthq/image",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.1-next.209.43ef1bc",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,9 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/entity": "0.3.0-next.906.07cea63",
-    "@flighthq/image-codec": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/entity": "0.3.1-next.209.43ef1bc",
+    "@flighthq/image-codec": "0.3.1-next.209.43ef1bc",
+    "@flighthq/types": "0.3.1-next.209.43ef1bc"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/imageResource.test.ts

@@ -1,234 +1,86 @@
-import type { ImageResourceCompressed } from '@flighthq/types/contract';
+import type { CompressedImageData } from '@flighthq/types/contract';
+import { CompressedImageTextureSourceKind, ImageTextureSourceKind } from '@flighthq/types/contract';
 
 import {
   cloneImageResource,
-  createCompressedImageResource,
+  createCompressedImage,
   createImageResource,
-  disposeImageResource,
-  getImageResourceByteSize,
-  hasImageResourceData,
-  hasImageResourcePixels,
-  hasImageResourceSource,
   invalidateImageResource,
   isImageResourceEmpty,
-  setImageResourceSource,
 } from './imageResource';
 
-// A minimal single-mip bc3 4x4 compressed payload stand-in for the resource wrapper tests.
-function makeCompressed(): ImageResourceCompressed {
+function makeCompressed(): CompressedImageData {
   return {
     container: {
+      depth: 1,
+      faces: 1,
       format: 'bc3',
-      width: 4,
       height: 4,
-      depth: 1,
-      mipLevels: 1,
       layers: 1,
-      faces: 1,
+      levels: [{ byteLength: 16, byteOffset: 0, height: 4, width: 4 }],
+      mipLevels: 1,
       supercompression: 'None',
-      levels: [{ byteOffset: 0, byteLength: 16, width: 4, height: 4 }],
+      width: 4,
     },
     payload: new Uint8Array(16),
   };
 }
 
 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);
+  it('shares the host source under an independent identity and version', () => {
+    const source = document.createElement('canvas');
+    source.width = 4;
+    source.height = 5;
+    const resource = createImageResource(source);
     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);
-
+    expect(copy.source).toBe(source);
+    expect(copy.version).toBe(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');
-  });
-
-  it('shares the compressed payload by reference', () => {
-    const resource = createCompressedImageResource(makeCompressed());
-    const copy = cloneImageResource(resource);
-    expect(copy.compressed).toBe(resource.compressed);
+    expect(resource.version).toBe(3);
   });
 });
 
-describe('createCompressedImageResource', () => {
-  it('wraps the container, mirrors its base dimensions, and leaves source/data null', () => {
+describe('createCompressedImage', () => {
+  it('wraps the compressed payload as a distinct source', () => {
     const compressed = makeCompressed();
-    const resource = createCompressedImageResource(compressed);
-    expect(resource.compressed).toBe(compressed);
-    expect(resource.width).toStrictEqual(4);
-    expect(resource.height).toStrictEqual(4);
-    expect(resource.source).toBeNull();
-    expect(resource.data).toBeNull();
-    expect(resource.version).toStrictEqual(0);
+    const image = createCompressedImage(compressed);
+    expect(image.kind).toBe(CompressedImageTextureSourceKind);
+    expect(image.compressed).toBe(compressed);
+    expect(image.width).toBe(4);
+    expect(image.height).toBe(4);
   });
 });
 
 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, data, and compressed payload and marks the resource changed', () => {
-    const resource = createImageResource({ width: 4, height: 5 } as HTMLImageElement);
-    resource.data = new Uint8ClampedArray(4 * 5 * 4);
-    resource.compressed = makeCompressed();
-    const before = resource.version;
-
-    disposeImageResource(resource);
-
-    expect(resource.source).toBeNull();
-    expect(resource.data).toBeNull();
-    expect(resource.compressed).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('hasImageResourcePixels', () => {
-  it('is false when neither representation is present', () => {
-    expect(hasImageResourcePixels(createImageResource())).toStrictEqual(false);
-  });
-
-  it('is true for a data-only resource (a generated Surface)', () => {
-    const resource = createImageResource();
-    resource.data = new Uint8ClampedArray(4);
-    expect(hasImageResourcePixels(resource)).toStrictEqual(true);
-  });
-
-  it('is true for an element-only resource', () => {
-    expect(hasImageResourcePixels(createImageResource({ width: 1, height: 1 } as HTMLImageElement))).toStrictEqual(
-      true,
-    );
-  });
-
-  it('is true for a compressed-only resource (a parsed container)', () => {
-    expect(hasImageResourcePixels(createCompressedImageResource(makeCompressed()))).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,
-    );
+  it('wraps one host source with its dimensions and declared kind', () => {
+    const source = document.createElement('canvas');
+    source.width = 8;
+    source.height = 6;
+    const resource = createImageResource(source);
+    expect(resource.kind).toBe(ImageTextureSourceKind);
+    expect(resource.source).toBe(source);
+    expect(resource.width).toBe(8);
+    expect(resource.height).toBe(6);
   });
 });
 
 describe('invalidateImageResource', () => {
-  it('increments the version', () => {
-    const resource = createImageResource();
+  it('refreshes host dimensions and advances the version', () => {
+    const source = document.createElement('canvas');
+    const resource = createImageResource(source);
+    source.width = 12;
+    source.height = 9;
     invalidateImageResource(resource);
+    expect(resource.width).toBe(12);
+    expect(resource.height).toBe(9);
     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();
+  it('reports a zero-sized host image', () => {
+    expect(isImageResourceEmpty(createImageResource(globalThis.document.createElement('img')))).toBe(true);
   });
 });

package/src/imageResourceFrom.test.ts

@@ -1,10 +1,14 @@
+import { createEntity } from '@flighthq/entity/contract';
+import type { Bitmap } from '@flighthq/types/contract';
+import { BitmapTextureSourceKind } from '@flighthq/types/contract';
+
 import { createImageResource } from './imageResource';
 import {
-  createCanvasFromImageResource,
+  createImageResourceFromBitmap,
   createImageResourceFromCanvas,
   createImageResourceFromImageBitmap,
   createImageResourceFromImageElement,
-  isImageResourceSameOrigin,
+  isImageUrlSameOrigin,
   loadImageResourceFromBase64,
   loadImageResourceFromBlob,
   loadImageResourceFromBytes,
@@ -21,29 +25,44 @@ afterEach(() => {
   delete (HTMLImageElement.prototype as Partial<HTMLImageElement>).decode;
 });
 
-describe('createCanvasFromImageResource', () => {
-  function makeDataResource(width: number, height: number) {
-    const resource = createImageResource();
-    resource.width = width;
-    resource.height = height;
-    resource.data = new Uint8ClampedArray(width * height * 4).fill(255);
-    return resource;
-  }
-
-  it('materializes a canvas sized to the resource', () => {
-    const canvas = createCanvasFromImageResource(makeDataResource(6, 5));
-    expect(canvas).toBeInstanceOf(HTMLCanvasElement);
-    expect(canvas!.width).toBe(6);
-    expect(canvas!.height).toBe(5);
-  });
-
-  it('returns a new canvas each call', () => {
-    const resource = makeDataResource(4, 4);
-    expect(createCanvasFromImageResource(resource)).not.toBe(createCanvasFromImageResource(resource));
+describe('createImageResourceFromBitmap', () => {
+  it('returns an Image with matching dimensions', () => {
+    // Built with createEntity rather than @flighthq/bitmap's createBitmap: bitmap depends on image,
+    // so importing it here would force a circular tsconfig project reference.
+    const bitmap: Bitmap = createEntity({
+      alphaType: 'straight',
+      gamut: 'srgb',
+      data: new Uint8ClampedArray(4 * 4 * 4),
+      format: 'rgba8unorm',
+      height: 4,
+      kind: BitmapTextureSourceKind,
+      version: 0,
+      width: 4,
+    });
+    const resource = createImageResourceFromBitmap(bitmap);
+    expect(resource.width).toBe(4);
+    expect(resource.height).toBe(4);
+    expect(resource.source).not.toBeNull();
   });
 
-  it('returns null for an element-only resource with no data', () => {
-    expect(createCanvasFromImageResource(createImageResource(document.createElement('img')))).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]);
   });
 });
 
@@ -115,26 +134,26 @@ describe('createImageResourceFromImageElement', () => {
   });
 });
 
-describe('isImageResourceSameOrigin', () => {
+describe('isImageUrlSameOrigin', () => {
   it('returns true for data: URLs', () => {
-    expect(isImageResourceSameOrigin('data:image/png;base64,abc')).toBe(true);
+    expect(isImageUrlSameOrigin('data:image/png;base64,abc')).toBe(true);
   });
 
   it('returns true for blob: URLs', () => {
-    expect(isImageResourceSameOrigin('blob:http://localhost/some-id')).toBe(true);
+    expect(isImageUrlSameOrigin('blob:http://localhost/some-id')).toBe(true);
   });
 
   it('returns true for relative URLs (same origin)', () => {
-    expect(isImageResourceSameOrigin('/images/logo.png')).toBe(true);
+    expect(isImageUrlSameOrigin('/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);
+    expect(isImageUrlSameOrigin('https://cdn.other-domain.com/image.png')).toBe(false);
   });
 });
 
 describe('loadImageResourceFromBase64', () => {
-  it('resolves to an ImageResource', async () => {
+  it('resolves to an Image', async () => {
     const resource = await loadImageResourceFromBase64('abc123', 'image/png');
     expect(resource).not.toBeNull();
     expect(resource.source).toBeInstanceOf(HTMLImageElement);
@@ -147,7 +166,7 @@ describe('loadImageResourceFromBase64', () => {
 });
 
 describe('loadImageResourceFromBlob', () => {
-  it('resolves to an ImageResource', async () => {
+  it('resolves to an Image', async () => {
     const blob = new Blob([], { type: 'image/png' });
     const resource = await loadImageResourceFromBlob(blob);
     expect(resource).not.toBeNull();
@@ -221,12 +240,47 @@ describe('loadImageResourceFromUrl', () => {
     );
   });
 
-  it('resolves to an ImageResource whose source is an HTMLImageElement', async () => {
+  it('clears the image source when aborted during decode', 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;
+    HTMLImageElement.prototype.decode = vi.fn().mockReturnValue(new Promise(() => {}));
+    const controller = new AbortController();
+
+    try {
+      const promise = loadImageResourceFromUrl('/images/slow.png', undefined, controller.signal);
+      controller.abort(new Error('cancelled'));
+      await expect(promise).rejects.toThrow('cancelled');
+      expect(capturedImg?.getAttribute('src')).toBe('');
+    } finally {
+      globalThis.Image = origImage;
+    }
+  });
+
+  it('removes its abort listener after decode succeeds', async () => {
+    const controller = new AbortController();
+    const add = vi.spyOn(controller.signal, 'addEventListener');
+    const remove = vi.spyOn(controller.signal, 'removeEventListener');
+
+    await loadImageResourceFromUrl('/images/logo.png', undefined, controller.signal);
+
+    expect(add).toHaveBeenCalledOnce();
+    expect(remove).toHaveBeenCalledOnce();
+    expect(remove.mock.calls[0][1]).toBe(add.mock.calls[0][1]);
+  });
+
+  it('resolves to an Image 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 () => {
+  it.each(['anonymous', 'use-credentials'] as const)('sets crossOrigin to %s when provided', async (crossOrigin) => {
     let capturedImg: HTMLImageElement | undefined;
     const origImage = globalThis.Image;
     globalThis.Image = new Proxy(origImage, {
@@ -237,8 +291,8 @@ describe('loadImageResourceFromUrl', () => {
       },
     }) as typeof Image;
 
-    await loadImageResourceFromUrl('https://cdn.other-domain.com/image.png', 'anonymous');
-    expect(capturedImg?.crossOrigin).toBe('anonymous');
+    await loadImageResourceFromUrl('https://cdn.other-domain.com/image.png', crossOrigin);
+    expect(capturedImg?.crossOrigin).toBe(crossOrigin);
 
     globalThis.Image = origImage;
   });

package/src/imageResourceReference.test.ts

@@ -0,0 +1,189 @@
+import { clearImageDecoders, registerImageDecoder } from '@flighthq/image-codec/contract';
+import type { Image, ImageDecoder } from '@flighthq/types/contract';
+import {
+  BitmapTextureSourceKind,
+  EntityRuntimeKey,
+  ImageResourceFailureKind,
+  ResourceResolutionState,
+} from '@flighthq/types/contract';
+
+import {
+  createEmbeddedImageResourceReference,
+  createExternalImageResourceReference,
+  createImageResourceFailure,
+  explainImageResourceReferenceResolution,
+  resetFailedImageResourceReference,
+  resolveImageResourceReference,
+} from './imageResourceReference';
+
+let decoder: ReturnType<typeof vi.fn<ImageDecoder>>;
+
+beforeEach(() => {
+  decoder = vi.fn<ImageDecoder>().mockResolvedValue({
+    data: new Uint8ClampedArray([0x11, 0x22, 0x33, 0x44]),
+    height: 1,
+    width: 1,
+  });
+  registerImageDecoder('image/png', decoder);
+});
+
+afterEach(() => {
+  clearImageDecoders();
+});
+
+const unusedFetch = () => Promise.resolve(null);
+
+describe('createEmbeddedImageResourceReference', () => {
+  it('borrows the byte view rather than copying it', () => {
+    const bytes = new Uint8Array([1, 2, 3, 4]);
+    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', () => {
+    const ref = createEmbeddedImageResourceReference(new Uint8Array(1));
+    expect(ref.state).toBe(ResourceResolutionState.Unresolved);
+    expect(ref.failure).toBeNull();
+    expect(ref.mimeType).toBeNull();
+    expect(ref.textures).toEqual([]);
+  });
+});
+
+describe('createExternalImageResourceReference', () => {
+  it('retains the uri and base path', () => {
+    const ref = createExternalImageResourceReference('atlas.png', '/assets');
+    expect(ref.uri).toBe('atlas.png');
+    expect(ref.basePath).toBe('/assets');
+    expect(ref.state).toBe(ResourceResolutionState.Unresolved);
+  });
+
+  it('defaults the base path to null', () => {
+    expect(createExternalImageResourceReference('/atlas.png').basePath).toBeNull();
+  });
+});
+
+describe('createImageResourceFailure', () => {
+  it('keeps an Error name and message', () => {
+    const failure = createImageResourceFailure(new TypeError('bad magic'));
+    expect(failure).toEqual({ kind: ImageResourceFailureKind.Error, message: 'bad magic', name: 'TypeError' });
+  });
+
+  it('stringifies a non-Error cause with no name', () => {
+    expect(createImageResourceFailure('exploded')).toEqual({
+      kind: ImageResourceFailureKind.Error,
+      message: 'exploded',
+      name: null,
+    });
+  });
+});
+
+describe('explainImageResourceReferenceResolution', () => {
+  it('detaches the failure so a caller cannot mutate the reference', () => {
+    const ref = createEmbeddedImageResourceReference(new Uint8Array(1));
+    ref.failure = { kind: ImageResourceFailureKind.Error, message: 'nope', name: null };
+    ref.state = ResourceResolutionState.Failed;
+    const explanation = explainImageResourceReferenceResolution(ref);
+    expect(explanation.failure).not.toBe(ref.failure);
+    expect(explanation.failure).toEqual(ref.failure);
+  });
+
+  it('reports only a failed reference as retryable', () => {
+    const ref = createExternalImageResourceReference('a.png');
+    expect(explainImageResourceReferenceResolution(ref).retryable).toBe(false);
+    ref.state = ResourceResolutionState.Failed;
+    expect(explainImageResourceReferenceResolution(ref).retryable).toBe(true);
+  });
+});
+
+describe('resetFailedImageResourceReference', () => {
+  it('clears a failed reference back to unresolved', () => {
+    const ref = createExternalImageResourceReference('a.png');
+    ref.failure = { kind: ImageResourceFailureKind.Unavailable, message: 'missing', name: null };
+    ref.state = ResourceResolutionState.Failed;
+    expect(resetFailedImageResourceReference(ref)).toBe(true);
+    expect(ref.state).toBe(ResourceResolutionState.Unresolved);
+    expect(ref.failure).toBeNull();
+  });
+
+  it('leaves a resolved reference untouched', () => {
+    const ref = createExternalImageResourceReference('a.png');
+    ref.state = ResourceResolutionState.Resolved;
+    expect(resetFailedImageResourceReference(ref)).toBe(false);
+    expect(ref.state).toBe(ResourceResolutionState.Resolved);
+  });
+});
+
+describe('resolveImageResourceReference', () => {
+  it('decodes embedded bytes and marks the reference resolved', async () => {
+    const ref = createEmbeddedImageResourceReference(new Uint8Array([0x89, 0x50, 0x4e, 0x47]), 'image/png');
+    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('routes an external reference through the fetch seam', async () => {
+    const ref = createExternalImageResourceReference('atlas.png', '/assets');
+    const fetched = { width: 2 } as Image;
+    const fetch = vi.fn().mockResolvedValue(fetched);
+    expect(await resolveImageResourceReference(ref, fetch, new AbortController().signal)).toBe(fetched);
+    expect(fetch).toHaveBeenCalledOnce();
+    expect(ref.state).toBe(ResourceResolutionState.Resolved);
+  });
+
+  it('records an unavailable failure when the fetch seam returns null', async () => {
+    const ref = createExternalImageResourceReference('missing.png');
+    expect(await resolveImageResourceReference(ref, unusedFetch, new AbortController().signal)).toBeNull();
+    expect(ref.state).toBe(ResourceResolutionState.Failed);
+    expect(ref.failure?.kind).toBe(ImageResourceFailureKind.Unavailable);
+  });
+
+  it('records a thrown cause as a failure rather than rethrowing', async () => {
+    const ref = createExternalImageResourceReference('boom.png');
+    const fetch = vi.fn().mockRejectedValue(new Error('network down'));
+    expect(await resolveImageResourceReference(ref, fetch, new AbortController().signal)).toBeNull();
+    expect(ref.state).toBe(ResourceResolutionState.Failed);
+    expect(ref.failure).toEqual({ kind: ImageResourceFailureKind.Error, message: 'network down', name: 'Error' });
+  });
+
+  it('treats an abort as a cancel: reverts to unresolved and rethrows', async () => {
+    const ref = createExternalImageResourceReference('slow.png');
+    const controller = new AbortController();
+    const fetch = vi.fn().mockImplementation(() => {
+      controller.abort();
+      return Promise.reject(new Error('aborted'));
+    });
+    await expect(resolveImageResourceReference(ref, fetch, controller.signal)).rejects.toThrow('aborted');
+    expect(ref.state).toBe(ResourceResolutionState.Unresolved);
+    expect(ref.failure).toBeNull();
+  });
+
+  it('clears a prior failure when the reference is retried', async () => {
+    const ref = createExternalImageResourceReference('flaky.png');
+    ref.failure = { kind: ImageResourceFailureKind.Error, message: 'old', name: null };
+    ref.state = ResourceResolutionState.Failed;
+    const fetch = vi.fn().mockResolvedValue({ width: 1 } as Image);
+    await resolveImageResourceReference(ref, fetch, new AbortController().signal);
+    expect(ref.failure).toBeNull();
+    expect(ref.state).toBe(ResourceResolutionState.Resolved);
+  });
+});