@flighthq/image 0.3.1-next.975.01aea94 → 0.4.0-edge.1908.751021c

package/dist/imageBackend.d.ts

@@ -1,5 +1,9 @@
-import type { ImageBackend } from '@flighthq/types/contract';
+import type { BackendExplanation, ImageBackend } from '@flighthq/types/contract';
 export declare function createWebImageBackend(): ImageBackend;
+export declare function explainImageBackend(): BackendExplanation;
 export declare function getImageBackend(): ImageBackend;
+export declare function installImageHostBackend(backend: ImageBackend): void;
+export declare function observeImageHostResult(operation: string, succeeded: boolean): void;
+export declare function resetImageBackendForTest(): void;
 export declare function setImageBackend(backend: ImageBackend | null): void;
 //# sourceMappingURL=imageBackend.d.ts.map

package/dist/imageBackend.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"imageBackend.d.ts","sourceRoot":"","sources":["../src/imageBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAS,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAIxF,wBAAgB,qBAAqB,IAAI,YAAY,CA4BpD;AAED,wBAAgB,mBAAmB,IAAI,kBAAkB,CAaxD;AAED,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAMnE;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAKlF;AAED,wBAAgB,wBAAwB,IAAI,IAAI,CAK/C;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAElE"}

package/dist/imageBackend.js

@@ -1,12 +1,4 @@
 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) {
@@ -15,8 +7,6 @@ export function createWebImageBackend() {
             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) => {
@@ -41,17 +31,53 @@ export function createWebImageBackend() {
         },
     };
 }
-// The active image backend, lazily defaulting to the web one. There is always a backend.
+export function explainImageBackend() {
+    if (_custom !== null) {
+        return { conflict: _hostConflict, layer: 'custom', operation: null, viability: 'unobserved' };
+    }
+    if (_host !== null) {
+        return {
+            conflict: _hostConflict,
+            layer: 'host',
+            operation: _hostObservation !== null ? _hostObservation.operation : null,
+            viability: _hostObservation !== null ? _hostObservation.viability : 'unobserved',
+        };
+    }
+    return { conflict: false, layer: 'host-not-enabled', operation: null, viability: 'unobserved' };
+}
 export function getImageBackend() {
-    if (_backend === null)
-        _backend = createWebImageBackend();
-    return _backend;
+    return _custom ?? _host ?? _sentinel;
+}
+export function installImageHostBackend(backend) {
+    if (_host !== null) {
+        if (_host !== backend)
+            _hostConflict = true;
+        return;
+    }
+    _host = backend;
+}
+export function observeImageHostResult(operation, succeeded) {
+    _hostObservation = {
+        operation,
+        viability: succeeded ? 'available' : 'runtime-api-unavailable',
+    };
+}
+export function resetImageBackendForTest() {
+    _custom = null;
+    _host = null;
+    _hostConflict = false;
+    _hostObservation = null;
 }
-// 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;
+    _custom = backend;
 }
-let _backend = null;
+const _sentinel = {
+    loadImageFromUrl(_url, _crossOrigin, _signal) {
+        return Promise.reject(new Error('No image backend installed. Call enableHostWebImage() or setImageBackend() first.'));
+    },
+};
+let _custom = null;
+let _host = null;
+let _hostConflict = false;
+let _hostObservation = null;
 //# sourceMappingURL=imageBackend.js.map

package/dist/imageBackend.js.map

@@ -1 +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"}
+{"version":3,"file":"imageBackend.js","sourceRoot":"","sources":["../src/imageBackend.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, disableImageBitmapComposition, enableImageBitmapComposition, explainImageResourceReferenceResolution, isImageResourceEmpty, isImageUrlSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, resetFailedImageResourceReference, resolveImageResourceReference, } from './contract';
+export { explainImageBackend, 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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,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, disableImageBitmapComposition, enableImageBitmapComposition, explainImageResourceReferenceResolution, isImageResourceEmpty, isImageUrlSameOrigin, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, resetFailedImageResourceReference, resolveImageResourceReference, } from './contract';
+export { explainImageBackend, 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,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,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.1-next.975.01aea94",
+  "version": "0.4.0-edge.1908.751021c",
   "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.1-next.975.01aea94",
-    "@flighthq/image-codec": "0.3.1-next.975.01aea94",
-    "@flighthq/types": "0.3.1-next.975.01aea94"
+    "@flighthq/entity": "0.4.0-edge.1908.751021c",
+    "@flighthq/image-codec": "0.4.0-edge.1908.751021c",
+    "@flighthq/types": "0.4.0-edge.1908.751021c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/imageBackend.test.ts

@@ -1,7 +1,15 @@
 import type { Image, ImageBackend } from '@flighthq/types/contract';
 import { afterEach, describe, expect, it } from 'vitest';
 
-import { createWebImageBackend, getImageBackend, setImageBackend } from './imageBackend';
+import {
+  createWebImageBackend,
+  getImageBackend,
+  setImageBackend,
+  explainImageBackend,
+  installImageHostBackend,
+  observeImageHostResult,
+  resetImageBackendForTest,
+} from './imageBackend';
 import { loadImageResourceFromUrl } from './imageResourceFrom';
 
 // Every test that installs a backend must put it back, or a later test sees a stale one.
@@ -32,6 +40,34 @@ describe('createWebImageBackend', () => {
   });
 });
 
+describe('explainImageBackend', () => {
+  afterEach(() => resetImageBackendForTest());
+
+  it('reports host-not-enabled when no backend is installed', () => {
+    resetImageBackendForTest();
+    const explanation = explainImageBackend();
+    expect(explanation.layer).toBe('host-not-enabled');
+    expect(explanation.conflict).toBe(false);
+    expect(explanation.viability).toBe('unobserved');
+  });
+
+  it('reports custom layer when a custom backend is set', () => {
+    setImageBackend(getImageBackend());
+    expect(explainImageBackend().layer).toBe('custom');
+  });
+
+  it('reports host layer when a host backend is installed', () => {
+    installImageHostBackend(getImageBackend());
+    expect(explainImageBackend().layer).toBe('host');
+  });
+
+  it('reports conflict when two different host backends are installed', () => {
+    installImageHostBackend({ ...getImageBackend() });
+    installImageHostBackend({ ...getImageBackend() });
+    expect(explainImageBackend().conflict).toBe(true);
+  });
+});
+
 describe('getImageBackend', () => {
   it('defaults lazily to a web backend rather than being registered at import', () => {
     expect(typeof getImageBackend().loadImageFromUrl).toBe('function');
@@ -48,6 +84,55 @@ describe('getImageBackend', () => {
   });
 });
 
+describe('installImageHostBackend', () => {
+  afterEach(() => resetImageBackendForTest());
+
+  it('installs a host backend that getImageBackend returns', () => {
+    const backend = getImageBackend();
+    installImageHostBackend(backend);
+    expect(getImageBackend()).toBe(backend);
+  });
+
+  it('is first-host-wins: a second different backend sets conflict', () => {
+    const first = { ...getImageBackend() };
+    const second = { ...getImageBackend() };
+    installImageHostBackend(first);
+    installImageHostBackend(second);
+    expect(getImageBackend()).toBe(first);
+    expect(explainImageBackend().conflict).toBe(true);
+  });
+});
+
+describe('observeImageHostResult', () => {
+  afterEach(() => resetImageBackendForTest());
+
+  it('records a successful observation', () => {
+    installImageHostBackend(getImageBackend());
+    observeImageHostResult('loadImageFromUrl', true);
+    const explanation = explainImageBackend();
+    expect(explanation.operation).toBe('loadImageFromUrl');
+    expect(explanation.viability).toBe('available');
+  });
+
+  it('records a failed observation', () => {
+    installImageHostBackend(getImageBackend());
+    observeImageHostResult('loadImageFromUrl', false);
+    expect(explainImageBackend().viability).toBe('runtime-api-unavailable');
+  });
+});
+
+describe('resetImageBackendForTest', () => {
+  it('clears all backend slots', () => {
+    setImageBackend(getImageBackend());
+    installImageHostBackend(getImageBackend());
+    observeImageHostResult('loadImageFromUrl', true);
+    resetImageBackendForTest();
+    expect(explainImageBackend().layer).toBe('host-not-enabled');
+    expect(explainImageBackend().conflict).toBe(false);
+    expect(explainImageBackend().viability).toBe('unobserved');
+  });
+});
+
 describe('setImageBackend', () => {
   it('restores a working web default when passed null, rather than leaving a one-way door', () => {
     const { backend } = recordingBackend();

package/src/imageResourceFrom.test.ts

@@ -2,6 +2,7 @@ import { createEntity } from '@flighthq/entity/contract';
 import type { Bitmap } from '@flighthq/types/contract';
 import { BitmapTextureSourceKind } from '@flighthq/types/contract';
 
+import { createWebImageBackend, resetImageBackendForTest, setImageBackend } from './imageBackend';
 import { createImageResource } from './imageResource';
 import {
   createImageResourceFromBitmap,
@@ -17,11 +18,13 @@ import {
 
 // Stub img.decode() so async load functions resolve immediately in jsdom.
 beforeEach(() => {
+  setImageBackend(createWebImageBackend());
   HTMLImageElement.prototype.decode = vi.fn().mockResolvedValue(undefined);
 });
 
 afterEach(() => {
   vi.restoreAllMocks();
+  resetImageBackendForTest();
   delete (HTMLImageElement.prototype as Partial<HTMLImageElement>).decode;
 });