open-ultrahdr 0.1.1 → 0.2.0

package/README.md

@@ -28,4 +28,6 @@ if (await isUltraHdr(buffer)) {
 
 ## License
 
-GPL-2.0-or-later
+Dual-licensed under `Apache-2.0 OR MIT`, matching upstream
+[libultrahdr](https://github.com/google/libultrahdr).
+See the project root [LICENSE](../LICENSE) for details.

package/dist/index.d.mts

@@ -85,9 +85,23 @@ interface UltraHdrEncodeOptions {
     gainMapQuality: number;
     /** Target HDR capacity (typically 2.0-4.0) */
     targetHdrCapacity: number;
-    /** Whether to include ISO 21496-1 metadata */
+    /**
+     * Whether to include ISO 21496-1 metadata.
+     *
+     * Currently a no-op: libultrahdr's encoder unconditionally emits ISO
+     * 21496-1 metadata and exposes no public toggle. Kept for API stability
+     * with prior versions; setting this to `false` will not suppress the
+     * metadata block.
+     */
     includeIsoMetadata: boolean;
-    /** Whether to include UltraHDR v1 metadata for Android compatibility */
+    /**
+     * Whether to include UltraHDR v1 metadata for Android compatibility.
+     *
+     * Currently a no-op: libultrahdr's encoder unconditionally emits the v1
+     * metadata block and exposes no public toggle. Kept for API stability
+     * with prior versions; setting this to `false` will not suppress the
+     * metadata block.
+     */
     includeUltrahdrV1: boolean;
     /** Downscale factor for the gain map (1 = same size, 2 = half, 4 = quarter) */
     gainMapScale: number;
@@ -132,18 +146,18 @@ declare const smallSizeEncodeOptions: UltraHdrEncodeOptions;
 /**
  * Open UltraHDR Library
  *
- * TypeScript bindings for the UltraHDR WASM library.
- * Provides detection, encoding, and decoding of UltraHDR JPEG images
- * implementing ISO 21496-1 (gain map) specification.
+ * TypeScript bindings for the libultrahdr WASM library. Provides detection,
+ * encoding, and decoding of UltraHDR JPEG images implementing the
+ * ISO 21496-1 (gain map) specification.
+ *
+ * Backed by upstream `libultrahdr` compiled to WebAssembly via Emscripten/embind.
  *
  * @example
  * ```typescript
  * import { isUltraHdr, decodeUltraHdr, setLocation } from 'open-ultrahdr';
  *
- * // Set the location for WASM files
  * setLocation('/path/to/wasm/');
  *
- * // Check if an image is UltraHDR
  * const buffer = await file.arrayBuffer();
  * if (await isUltraHdr(buffer)) {
  *     const result = await decodeUltraHdr('item-1', buffer);
@@ -155,171 +169,57 @@ declare const smallSizeEncodeOptions: UltraHdrEncodeOptions;
 /**
  * Sets the location/public path for loading WASM files.
  *
- * This must be called before using any other functions when the WASM
- * files are not in the same directory as the JavaScript bundle.
+ * Must be called before using any other functions when the WASM file is not
+ * served from the same directory as the JavaScript bundle.
  *
  * @param newLocation - Base URL or path where WASM files are located.
- *
- * @example
- * ```typescript
- * // Set location before any other calls
- * setLocation('/assets/wasm/');
- * ```
  */
 declare function setLocation(newLocation: string): void;
 /**
- * Checks if a buffer contains an UltraHDR image.
+ * Sets an explicit URL (or `data:` URL) for the WASM file.
  *
- * This is a fast check that looks for gain map metadata without
- * fully decoding the image.
+ * Useful when bundling the WASM as a base64 data URL.
  *
- * @param buffer - JPEG file contents.
- * @return True if the image contains UltraHDR/gain map data.
- *
- * @example
- * ```typescript
- * const buffer = await file.arrayBuffer();
- * if (await isUltraHdr(buffer)) {
- *     console.log('This is an UltraHDR image!');
- * }
- * ```
+ * @param url - Full URL or data URL pointing to `open_ultrahdr.wasm`.
+ */
+declare function setWasmUrl(url: string): void;
+/**
+ * Checks if a buffer contains an UltraHDR image.
  */
 declare function isUltraHdr(buffer: ArrayBuffer): Promise<boolean>;
 /**
- * Probes an image to check if it's UltraHDR and extracts component information.
- *
- * This function efficiently validates if an image is UltraHDR by checking for
- * required components (primary image, gain map, metadata) without full decoding.
- * Returns structured results useful for batch processing and filtering.
- *
- * Unlike `isUltraHdr`, this function provides detailed information about what
- * was found, making it useful for diagnostics and filtering workflows.
- *
- * @param buffer - Image file contents.
- * @return Probe result with detailed component information.
- *
- * @example
- * ```typescript
- * const buffer = await file.arrayBuffer();
- * const result = await probeUltraHdr(buffer);
+ * Probes an image to check if it's UltraHDR and extracts component info.
  *
- * if (result.isValid) {
- *     console.log('UltraHDR image:', result.width, 'x', result.height);
- *     console.log('HDR capacity:', result.hdrCapacity, 'stops');
- *     console.log('Gain map:', result.gainMapWidth, 'x', result.gainMapHeight);
- * } else {
- *     // Diagnose why it's not a valid UltraHDR
- *     if (!result.hasPrimaryImage) console.log('Not a valid JPEG');
- *     if (!result.hasGainMap) console.log('Missing gain map');
- *     if (!result.hasMetadata) console.log('Missing HDR metadata');
- * }
- * ```
+ * Never throws — invalid inputs return a result with all flags set to false.
  */
 declare function probeUltraHdr(buffer: ArrayBuffer): Promise<UltraHdrProbeResult>;
 /**
  * Decodes an UltraHDR image, extracting all components.
- *
- * @param id     - Unique identifier for this operation (for cancellation).
- * @param buffer - UltraHDR JPEG file contents.
- * @return Decoded result with SDR image, gain map, and metadata.
- *
- * @throws Error if the buffer is not a valid UltraHDR JPEG.
- *
- * @example
- * ```typescript
- * const buffer = await file.arrayBuffer();
- * const result = await decodeUltraHdr('upload-1', buffer);
- *
- * // Access components
- * const sdrBlob = new Blob([result.sdrImage], { type: 'image/jpeg' });
- * console.log('Image size:', result.width, 'x', result.height);
- * console.log('HDR capacity:', result.metadata.hdrCapacityMax);
- * ```
  */
-declare function decodeUltraHdr(id: ItemId, buffer: ArrayBuffer): Promise<UltraHdrDecodeResult>;
+declare function decodeUltraHdr(_id: ItemId, buffer: ArrayBuffer): Promise<UltraHdrDecodeResult>;
 /**
  * Encodes an UltraHDR JPEG from SDR and HDR inputs.
- *
- * @param id        - Unique identifier for this operation.
- * @param sdrBuffer - SDR JPEG image bytes.
- * @param hdrBuffer - HDR linear RGB data (Float32Array, 3 values per pixel).
- * @param options   - Encoding options.
- * @return Encoded UltraHDR JPEG as ArrayBuffer.
- *
- * @throws Error if inputs are invalid or dimensions don't match.
- *
- * @example
- * ```typescript
- * const sdrBuffer = await sdrFile.arrayBuffer();
- * const hdrData = await getHdrLinearData(); // Float32Array
- *
- * const ultraHdr = await encodeUltraHdr('encode-1', sdrBuffer, hdrData, {
- *     ...defaultEncodeOptions,
- *     targetHdrCapacity: 4.0,
- * });
- *
- * // Create downloadable file
- * const blob = new Blob([ultraHdr], { type: 'image/jpeg' });
- * ```
  */
-declare function encodeUltraHdr(id: ItemId, sdrBuffer: ArrayBuffer, hdrBuffer: ArrayBuffer, options?: Partial<UltraHdrEncodeOptions>): Promise<ArrayBuffer>;
+declare function encodeUltraHdr(_id: ItemId, sdrBuffer: ArrayBuffer, hdrBuffer: ArrayBuffer, options?: Partial<UltraHdrEncodeOptions>): Promise<ArrayBuffer>;
 /**
  * Extracts the SDR base image from an UltraHDR JPEG.
- *
- * This produces a standard JPEG that can be displayed on any device,
- * without the gain map metadata. Useful for backwards compatibility.
- *
- * @param buffer - UltraHDR JPEG file contents.
- * @return Standard JPEG without gain map.
- *
- * @example
- * ```typescript
- * const ultraHdrBuffer = await file.arrayBuffer();
- * const sdrBuffer = await extractSdrBase(ultraHdrBuffer);
- *
- * // Use the SDR image for non-HDR displays
- * const blob = new Blob([sdrBuffer], { type: 'image/jpeg' });
- * ```
  */
 declare function extractSdrBase(buffer: ArrayBuffer): Promise<ArrayBuffer>;
 /**
  * Gets gain map metadata from an UltraHDR JPEG.
- *
- * This is faster than `decodeUltraHdr` when you only need the metadata.
- *
- * @param buffer - UltraHDR JPEG file contents.
- * @return Gain map metadata.
- *
- * @throws Error if the buffer doesn't contain gain map metadata.
- *
- * @example
- * ```typescript
- * const metadata = await getMetadata(buffer);
- * console.log('Version:', metadata.version);
- * console.log('HDR headroom:', metadata.hdrCapacityMax, 'stops');
- * ```
  */
 declare function getMetadata(buffer: ArrayBuffer): Promise<GainMapMetadata>;
 /**
  * Validates gain map metadata.
- *
- * @param metadata - The metadata to validate.
- * @return True if the metadata is valid.
  */
 declare function validateMetadata(metadata: GainMapMetadata): Promise<boolean>;
 /**
  * Estimates the HDR headroom from metadata.
- *
- * @param metadata - The gain map metadata.
- * @return Maximum additional stops of dynamic range above SDR.
  */
 declare function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number>;
 /**
  * Checks if metadata indicates a meaningful HDR image.
- *
- * @param metadata - The gain map metadata.
- * @return True if the gain map provides significant dynamic range extension.
  */
 declare function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean>;
 
-export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, type UltraHdrProbeResult, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, probeUltraHdr, setLocation, smallSizeEncodeOptions, validateMetadata };
+export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, type UltraHdrProbeResult, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, probeUltraHdr, setLocation, setWasmUrl, smallSizeEncodeOptions, validateMetadata };

package/dist/index.d.ts

@@ -85,9 +85,23 @@ interface UltraHdrEncodeOptions {
     gainMapQuality: number;
     /** Target HDR capacity (typically 2.0-4.0) */
     targetHdrCapacity: number;
-    /** Whether to include ISO 21496-1 metadata */
+    /**
+     * Whether to include ISO 21496-1 metadata.
+     *
+     * Currently a no-op: libultrahdr's encoder unconditionally emits ISO
+     * 21496-1 metadata and exposes no public toggle. Kept for API stability
+     * with prior versions; setting this to `false` will not suppress the
+     * metadata block.
+     */
     includeIsoMetadata: boolean;
-    /** Whether to include UltraHDR v1 metadata for Android compatibility */
+    /**
+     * Whether to include UltraHDR v1 metadata for Android compatibility.
+     *
+     * Currently a no-op: libultrahdr's encoder unconditionally emits the v1
+     * metadata block and exposes no public toggle. Kept for API stability
+     * with prior versions; setting this to `false` will not suppress the
+     * metadata block.
+     */
     includeUltrahdrV1: boolean;
     /** Downscale factor for the gain map (1 = same size, 2 = half, 4 = quarter) */
     gainMapScale: number;
@@ -132,18 +146,18 @@ declare const smallSizeEncodeOptions: UltraHdrEncodeOptions;
 /**
  * Open UltraHDR Library
  *
- * TypeScript bindings for the UltraHDR WASM library.
- * Provides detection, encoding, and decoding of UltraHDR JPEG images
- * implementing ISO 21496-1 (gain map) specification.
+ * TypeScript bindings for the libultrahdr WASM library. Provides detection,
+ * encoding, and decoding of UltraHDR JPEG images implementing the
+ * ISO 21496-1 (gain map) specification.
+ *
+ * Backed by upstream `libultrahdr` compiled to WebAssembly via Emscripten/embind.
  *
  * @example
  * ```typescript
  * import { isUltraHdr, decodeUltraHdr, setLocation } from 'open-ultrahdr';
  *
- * // Set the location for WASM files
  * setLocation('/path/to/wasm/');
  *
- * // Check if an image is UltraHDR
  * const buffer = await file.arrayBuffer();
  * if (await isUltraHdr(buffer)) {
  *     const result = await decodeUltraHdr('item-1', buffer);
@@ -155,171 +169,57 @@ declare const smallSizeEncodeOptions: UltraHdrEncodeOptions;
 /**
  * Sets the location/public path for loading WASM files.
  *
- * This must be called before using any other functions when the WASM
- * files are not in the same directory as the JavaScript bundle.
+ * Must be called before using any other functions when the WASM file is not
+ * served from the same directory as the JavaScript bundle.
  *
  * @param newLocation - Base URL or path where WASM files are located.
- *
- * @example
- * ```typescript
- * // Set location before any other calls
- * setLocation('/assets/wasm/');
- * ```
  */
 declare function setLocation(newLocation: string): void;
 /**
- * Checks if a buffer contains an UltraHDR image.
+ * Sets an explicit URL (or `data:` URL) for the WASM file.
  *
- * This is a fast check that looks for gain map metadata without
- * fully decoding the image.
+ * Useful when bundling the WASM as a base64 data URL.
  *
- * @param buffer - JPEG file contents.
- * @return True if the image contains UltraHDR/gain map data.
- *
- * @example
- * ```typescript
- * const buffer = await file.arrayBuffer();
- * if (await isUltraHdr(buffer)) {
- *     console.log('This is an UltraHDR image!');
- * }
- * ```
+ * @param url - Full URL or data URL pointing to `open_ultrahdr.wasm`.
+ */
+declare function setWasmUrl(url: string): void;
+/**
+ * Checks if a buffer contains an UltraHDR image.
  */
 declare function isUltraHdr(buffer: ArrayBuffer): Promise<boolean>;
 /**
- * Probes an image to check if it's UltraHDR and extracts component information.
- *
- * This function efficiently validates if an image is UltraHDR by checking for
- * required components (primary image, gain map, metadata) without full decoding.
- * Returns structured results useful for batch processing and filtering.
- *
- * Unlike `isUltraHdr`, this function provides detailed information about what
- * was found, making it useful for diagnostics and filtering workflows.
- *
- * @param buffer - Image file contents.
- * @return Probe result with detailed component information.
- *
- * @example
- * ```typescript
- * const buffer = await file.arrayBuffer();
- * const result = await probeUltraHdr(buffer);
+ * Probes an image to check if it's UltraHDR and extracts component info.
  *
- * if (result.isValid) {
- *     console.log('UltraHDR image:', result.width, 'x', result.height);
- *     console.log('HDR capacity:', result.hdrCapacity, 'stops');
- *     console.log('Gain map:', result.gainMapWidth, 'x', result.gainMapHeight);
- * } else {
- *     // Diagnose why it's not a valid UltraHDR
- *     if (!result.hasPrimaryImage) console.log('Not a valid JPEG');
- *     if (!result.hasGainMap) console.log('Missing gain map');
- *     if (!result.hasMetadata) console.log('Missing HDR metadata');
- * }
- * ```
+ * Never throws — invalid inputs return a result with all flags set to false.
  */
 declare function probeUltraHdr(buffer: ArrayBuffer): Promise<UltraHdrProbeResult>;
 /**
  * Decodes an UltraHDR image, extracting all components.
- *
- * @param id     - Unique identifier for this operation (for cancellation).
- * @param buffer - UltraHDR JPEG file contents.
- * @return Decoded result with SDR image, gain map, and metadata.
- *
- * @throws Error if the buffer is not a valid UltraHDR JPEG.
- *
- * @example
- * ```typescript
- * const buffer = await file.arrayBuffer();
- * const result = await decodeUltraHdr('upload-1', buffer);
- *
- * // Access components
- * const sdrBlob = new Blob([result.sdrImage], { type: 'image/jpeg' });
- * console.log('Image size:', result.width, 'x', result.height);
- * console.log('HDR capacity:', result.metadata.hdrCapacityMax);
- * ```
  */
-declare function decodeUltraHdr(id: ItemId, buffer: ArrayBuffer): Promise<UltraHdrDecodeResult>;
+declare function decodeUltraHdr(_id: ItemId, buffer: ArrayBuffer): Promise<UltraHdrDecodeResult>;
 /**
  * Encodes an UltraHDR JPEG from SDR and HDR inputs.
- *
- * @param id        - Unique identifier for this operation.
- * @param sdrBuffer - SDR JPEG image bytes.
- * @param hdrBuffer - HDR linear RGB data (Float32Array, 3 values per pixel).
- * @param options   - Encoding options.
- * @return Encoded UltraHDR JPEG as ArrayBuffer.
- *
- * @throws Error if inputs are invalid or dimensions don't match.
- *
- * @example
- * ```typescript
- * const sdrBuffer = await sdrFile.arrayBuffer();
- * const hdrData = await getHdrLinearData(); // Float32Array
- *
- * const ultraHdr = await encodeUltraHdr('encode-1', sdrBuffer, hdrData, {
- *     ...defaultEncodeOptions,
- *     targetHdrCapacity: 4.0,
- * });
- *
- * // Create downloadable file
- * const blob = new Blob([ultraHdr], { type: 'image/jpeg' });
- * ```
  */
-declare function encodeUltraHdr(id: ItemId, sdrBuffer: ArrayBuffer, hdrBuffer: ArrayBuffer, options?: Partial<UltraHdrEncodeOptions>): Promise<ArrayBuffer>;
+declare function encodeUltraHdr(_id: ItemId, sdrBuffer: ArrayBuffer, hdrBuffer: ArrayBuffer, options?: Partial<UltraHdrEncodeOptions>): Promise<ArrayBuffer>;
 /**
  * Extracts the SDR base image from an UltraHDR JPEG.
- *
- * This produces a standard JPEG that can be displayed on any device,
- * without the gain map metadata. Useful for backwards compatibility.
- *
- * @param buffer - UltraHDR JPEG file contents.
- * @return Standard JPEG without gain map.
- *
- * @example
- * ```typescript
- * const ultraHdrBuffer = await file.arrayBuffer();
- * const sdrBuffer = await extractSdrBase(ultraHdrBuffer);
- *
- * // Use the SDR image for non-HDR displays
- * const blob = new Blob([sdrBuffer], { type: 'image/jpeg' });
- * ```
  */
 declare function extractSdrBase(buffer: ArrayBuffer): Promise<ArrayBuffer>;
 /**
  * Gets gain map metadata from an UltraHDR JPEG.
- *
- * This is faster than `decodeUltraHdr` when you only need the metadata.
- *
- * @param buffer - UltraHDR JPEG file contents.
- * @return Gain map metadata.
- *
- * @throws Error if the buffer doesn't contain gain map metadata.
- *
- * @example
- * ```typescript
- * const metadata = await getMetadata(buffer);
- * console.log('Version:', metadata.version);
- * console.log('HDR headroom:', metadata.hdrCapacityMax, 'stops');
- * ```
  */
 declare function getMetadata(buffer: ArrayBuffer): Promise<GainMapMetadata>;
 /**
  * Validates gain map metadata.
- *
- * @param metadata - The metadata to validate.
- * @return True if the metadata is valid.
  */
 declare function validateMetadata(metadata: GainMapMetadata): Promise<boolean>;
 /**
  * Estimates the HDR headroom from metadata.
- *
- * @param metadata - The gain map metadata.
- * @return Maximum additional stops of dynamic range above SDR.
  */
 declare function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number>;
 /**
  * Checks if metadata indicates a meaningful HDR image.
- *
- * @param metadata - The gain map metadata.
- * @return True if the gain map provides significant dynamic range extension.
  */
 declare function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean>;
 
-export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, type UltraHdrProbeResult, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, probeUltraHdr, setLocation, smallSizeEncodeOptions, validateMetadata };
+export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, type UltraHdrProbeResult, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, probeUltraHdr, setLocation, setWasmUrl, smallSizeEncodeOptions, validateMetadata };

package/dist/index.js

@@ -43,6 +43,7 @@ __export(index_exports, {
   isUltraHdr: () => isUltraHdr,
   probeUltraHdr: () => probeUltraHdr,
   setLocation: () => setLocation,
+  setWasmUrl: () => setWasmUrl,
   smallSizeEncodeOptions: () => smallSizeEncodeOptions,
   validateMetadata: () => validateMetadata
 });
@@ -88,59 +89,61 @@ var smallSizeEncodeOptions = {
 };
 
 // src/index.ts
+var WASM_FILENAME = "open_ultrahdr.wasm";
 var location = "";
+var explicitWasmUrl = null;
 var wasmInstance = null;
 var initPromise = null;
+var initGeneration = 0;
 function setLocation(newLocation) {
   location = newLocation;
+  explicitWasmUrl = null;
+  resetCache();
 }
-function isWasmMetadataInstance(metadata) {
-  return typeof metadata === "object" && metadata !== null && "__wbg_ptr" in metadata;
+function setWasmUrl(url) {
+  explicitWasmUrl = url;
+  resetCache();
 }
-async function toWasmMetadata(metadata) {
-  if (isWasmMetadataInstance(metadata)) {
-    return metadata;
-  }
-  const wasm = await getWasm();
-  const wasmMetadata = wasm.createDefaultMetadata();
-  wasmMetadata.version = metadata.version;
-  wasmMetadata.baseRenditionIsHdr = metadata.baseRenditionIsHdr;
-  wasmMetadata.gainMapMin = metadata.gainMapMin;
-  wasmMetadata.gainMapMax = metadata.gainMapMax;
-  wasmMetadata.gamma = metadata.gamma;
-  wasmMetadata.offsetSdr = metadata.offsetSdr;
-  wasmMetadata.offsetHdr = metadata.offsetHdr;
-  wasmMetadata.hdrCapacityMin = metadata.hdrCapacityMin;
-  wasmMetadata.hdrCapacityMax = metadata.hdrCapacityMax;
-  return wasmMetadata;
+function resetCache() {
+  initGeneration += 1;
+  wasmInstance = null;
+  initPromise = null;
+}
+function joinPath(base, name) {
+  if (!base) return name;
+  return base.endsWith("/") ? `${base}${name}` : `${base}/${name}`;
 }
 async function getWasm() {
-  if (wasmInstance) {
-    return wasmInstance;
-  }
-  if (initPromise) {
-    return initPromise;
-  }
+  if (wasmInstance) return wasmInstance;
+  if (initPromise) return initPromise;
+  const generation = initGeneration;
   initPromise = (async () => {
     try {
-      const UltraHdrWasm = await import("open-ultrahdr-wasm");
-      if (location) {
-        const base = location.endsWith("/") ? location : `${location}/`;
-        const wasmPath = base + "open_ultrahdr_bg.wasm";
-        if (typeof process !== "undefined" && process.versions && process.versions.node) {
+      const wasmModule = await import("open-ultrahdr-wasm");
+      const factory = wasmModule.default;
+      const isNode = typeof process !== "undefined" && !!process.versions && !!process.versions.node;
+      const moduleOptions = {};
+      if (explicitWasmUrl) {
+        moduleOptions.locateFile = (path) => path.endsWith(".wasm") ? explicitWasmUrl : path;
+      } else if (location) {
+        if (isNode) {
           const fs = await import("fs");
-          const wasmBytes = await fs.promises.readFile(wasmPath);
-          await UltraHdrWasm.default(wasmBytes);
+          const wasmBytes = await fs.promises.readFile(joinPath(location, WASM_FILENAME));
+          moduleOptions.wasmBinary = new Uint8Array(wasmBytes);
         } else {
-          await UltraHdrWasm.default(wasmPath);
+          moduleOptions.locateFile = (path) => path.endsWith(".wasm") ? joinPath(location, WASM_FILENAME) : path;
         }
-      } else {
-        await UltraHdrWasm.default();
       }
-      wasmInstance = UltraHdrWasm;
-      return wasmInstance;
+      const instance = await factory(moduleOptions);
+      if (generation !== initGeneration) {
+        return getWasm();
+      }
+      wasmInstance = instance;
+      return instance;
     } catch (err) {
-      initPromise = null;
+      if (generation === initGeneration) {
+        initPromise = null;
+      }
       throw err;
     }
   })();
@@ -151,27 +154,35 @@ async function isUltraHdr(buffer) {
   return wasm.isUltraHdr(new Uint8Array(buffer));
 }
 async function probeUltraHdr(buffer) {
-  const wasm = await getWasm();
-  return wasm.probeUltraHdr(new Uint8Array(buffer));
+  try {
+    const wasm = await getWasm();
+    return wasm.probeUltraHdr(new Uint8Array(buffer));
+  } catch {
+    return {
+      isValid: false,
+      hasPrimaryImage: false,
+      hasGainMap: false,
+      hasMetadata: false,
+      width: 0,
+      height: 0,
+      gainMapWidth: 0,
+      gainMapHeight: 0,
+      hdrCapacity: 0,
+      metadataVersion: ""
+    };
+  }
 }
-async function decodeUltraHdr(id, buffer) {
+async function decodeUltraHdr(_id, buffer) {
   const wasm = await getWasm();
   return wasm.decodeUltraHdr(new Uint8Array(buffer));
 }
-async function encodeUltraHdr(id, sdrBuffer, hdrBuffer, options) {
+async function encodeUltraHdr(_id, sdrBuffer, hdrBuffer, options) {
   const wasm = await getWasm();
-  const wasmOpts = wasm.createDefaultOptions();
-  const mergedOpts = { ...defaultEncodeOptions, ...options };
-  wasmOpts.baseQuality = mergedOpts.baseQuality;
-  wasmOpts.gainMapQuality = mergedOpts.gainMapQuality;
-  wasmOpts.targetHdrCapacity = mergedOpts.targetHdrCapacity;
-  wasmOpts.includeIsoMetadata = mergedOpts.includeIsoMetadata;
-  wasmOpts.includeUltrahdrV1 = mergedOpts.includeUltrahdrV1;
-  wasmOpts.gainMapScale = mergedOpts.gainMapScale;
+  const merged = { ...defaultEncodeOptions, ...options };
   const result = wasm.encodeUltraHdr(
     new Uint8Array(sdrBuffer),
     new Float32Array(hdrBuffer),
-    wasmOpts
+    merged
   );
   return result.buffer.slice(
     result.byteOffset,
@@ -192,18 +203,15 @@ async function getMetadata(buffer) {
 }
 async function validateMetadata(metadata) {
   const wasm = await getWasm();
-  const wasmMetadata = await toWasmMetadata(metadata);
-  return wasm.validateMetadata(wasmMetadata);
+  return wasm.validateMetadata(metadata);
 }
 async function estimateHdrHeadroom(metadata) {
   const wasm = await getWasm();
-  const wasmMetadata = await toWasmMetadata(metadata);
-  return wasm.estimateHdrHeadroom(wasmMetadata);
+  return wasm.estimateHdrHeadroom(metadata);
 }
 async function isMeaningfulHdr(metadata) {
   const wasm = await getWasm();
-  const wasmMetadata = await toWasmMetadata(metadata);
-  return wasm.isMeaningfulHdr(wasmMetadata);
+  return wasm.isMeaningfulHdr(metadata);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -220,6 +228,7 @@ async function isMeaningfulHdr(metadata) {
   isUltraHdr,
   probeUltraHdr,
   setLocation,
+  setWasmUrl,
   smallSizeEncodeOptions,
   validateMetadata
 });