open-ultrahdr 0.1.2 → 0.2.0

package/src/index.ts

@@ -1,18 +1,18 @@
 /**
  * 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);
@@ -21,7 +21,6 @@
  * ```
  */
 
-// Re-export types
 export type {
 	ItemId,
 	GainMapMetadata,
@@ -48,189 +47,100 @@ import type {
 
 import { defaultEncodeOptions } from './types';
 
-// WASM class types (these are actual classes from the generated WASM bindings)
-interface WasmUltraHdrEncodeOptions {
-	baseQuality: number;
-	gainMapQuality: number;
-	targetHdrCapacity: number;
-	includeIsoMetadata: boolean;
-	includeUltrahdrV1: boolean;
-	gainMapScale: number;
-}
+import type { OpenUltraHdrModule } from 'open-ultrahdr-wasm';
 
-interface WasmGainMapMetadata {
-	version: string;
-	baseRenditionIsHdr: boolean;
-	gainMapMin: number[];
-	gainMapMax: number[];
-	gamma: number[];
-	offsetSdr: number[];
-	offsetHdr: number[];
-	hdrCapacityMin: number;
-	hdrCapacityMax: number;
-}
+const WASM_FILENAME = 'open_ultrahdr.wasm';
 
-// WASM module type (these come from the generated WASM bindings)
-interface UltraHdrWasmModule {
-	default: (moduleOrPath?: string | URL | Response | BufferSource) => Promise<unknown>;
-	isUltraHdr: (buffer: Uint8Array) => boolean;
-	probeUltraHdr: (buffer: Uint8Array) => UltraHdrProbeResult;
-	decodeUltraHdr: (buffer: Uint8Array) => UltraHdrDecodeResult;
-	encodeUltraHdr: (
-		sdrBuffer: Uint8Array,
-		hdrBuffer: Float32Array,
-		options: WasmUltraHdrEncodeOptions
-	) => Uint8Array;
-	extractSdrBase: (buffer: Uint8Array) => Uint8Array;
-	getMetadata: (buffer: Uint8Array) => WasmGainMapMetadata;
-	createDefaultOptions: () => WasmUltraHdrEncodeOptions;
-	createHighQualityOptions: () => WasmUltraHdrEncodeOptions;
-	createSmallSizeOptions: () => WasmUltraHdrEncodeOptions;
-	createDefaultMetadata: () => WasmGainMapMetadata;
-	validateMetadata: (metadata: WasmGainMapMetadata) => boolean;
-	estimateHdrHeadroom: (metadata: WasmGainMapMetadata) => number;
-	isMeaningfulHdr: (metadata: WasmGainMapMetadata) => boolean;
-}
-
-/**
- * Location prefix for WASM files.
- * Set this before calling any other functions.
- */
 let location = '';
-
-/**
- * Direct URL or data URL for the WASM module.
- * When set, this is passed directly to the WASM init function,
- * bypassing the location prefix + filename construction.
- */
-let wasmUrl = '';
-
-/**
- * Cached WASM module instance.
- */
-let wasmInstance: UltraHdrWasmModule | null = null;
-
-/**
- * Promise for ongoing WASM initialization.
- */
-let initPromise: Promise<UltraHdrWasmModule> | null = null;
+let explicitWasmUrl: string | null = null;
+let wasmInstance: OpenUltraHdrModule | null = null;
+let initPromise: Promise<OpenUltraHdrModule> | null = null;
+// Bumped by resetCache() so that any in-flight getWasm() call started under a
+// previous configuration cannot publish a stale instance after setLocation/
+// setWasmUrl is called.
+let initGeneration = 0;
 
 /**
  * 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/');
- * ```
  */
 export function setLocation(newLocation: string): void {
 	location = newLocation;
+	explicitWasmUrl = null;
+	resetCache();
 }
 
 /**
- * Sets a direct URL (including data URLs) for the WASM module.
- *
- * Use this when the WASM binary is inlined as a base64 data URL
- * at build time. Unlike `setLocation`, this passes the URL directly
- * to the WASM init function without appending a filename.
+ * Sets an explicit URL (or `data:` URL) for the WASM file.
  *
- * @param url - Direct URL or data URL for the WASM binary.
+ * Useful when bundling the WASM as a base64 data URL.
  *
- * @example
- * ```typescript
- * // With a build tool that inlines WASM as base64 data URLs:
- * import wasmDataUrl from 'open-ultrahdr-wasm/pkg/open_ultrahdr_bg.wasm';
- * setWasmUrl(wasmDataUrl);
- * ```
+ * @param url - Full URL or data URL pointing to `open_ultrahdr.wasm`.
  */
 export function setWasmUrl(url: string): void {
-	wasmUrl = url;
+	explicitWasmUrl = url;
+	resetCache();
 }
 
-/**
- * Checks if metadata is a WASM class instance (has __wbg_ptr property).
- */
-function isWasmMetadataInstance(metadata: unknown): boolean {
-	return typeof metadata === 'object' && metadata !== null && '__wbg_ptr' in metadata;
+function resetCache(): void {
+	initGeneration += 1;
+	wasmInstance = null;
+	initPromise = null;
 }
 
-/**
- * Converts a plain metadata object to a WASM class instance.
- */
-async function toWasmMetadata(metadata: GainMapMetadata): Promise<WasmGainMapMetadata> {
-	// If it's already a WASM instance, return as-is
-	if (isWasmMetadataInstance(metadata)) {
-		return metadata as unknown as WasmGainMapMetadata;
-	}
-
-	// Create a new WASM instance and copy properties
-	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 joinPath(base: string, name: string): string {
+	if (!base) return name;
+	return base.endsWith('/') ? `${base}${name}` : `${base}/${name}`;
 }
 
-/**
- * Gets the WASM module, initializing it if necessary.
- */
-async function getWasm(): Promise<UltraHdrWasmModule> {
-	if (wasmInstance) {
-		return wasmInstance;
-	}
-
-	if (initPromise) {
-		return initPromise;
-	}
+async function getWasm(): Promise<OpenUltraHdrModule> {
+	if (wasmInstance) return wasmInstance;
+	if (initPromise) return initPromise;
 
+	const generation = initGeneration;
 	initPromise = (async () => {
 		try {
-			// Dynamic import of the WASM package
-			const UltraHdrWasm = (await import('open-ultrahdr-wasm')) as unknown as UltraHdrWasmModule;
+			const wasmModule = await import('open-ultrahdr-wasm');
+			const factory = (wasmModule as unknown as { default: typeof wasmModule.default }).default;
 
-			// Initialize WASM module.
-			// Priority: wasmUrl (direct URL/data URL) > location (path prefix) > default
-			if (wasmUrl) {
-				// Direct URL (e.g. inlined base64 data URL from build tool)
-				await UltraHdrWasm.default(wasmUrl);
-			} else if (location) {
-				const base = location.endsWith('/') ? location : `${location}/`;
-				const wasmPath = base + 'open_ultrahdr_bg.wasm';
+			const isNode =
+				typeof process !== 'undefined' && !!process.versions && !!process.versions.node;
+
+			const moduleOptions: { locateFile?: (path: string) => string; wasmBinary?: Uint8Array } = {};
 
-				// In Node.js, load the WASM file from the filesystem
-				// instead of using fetch which doesn't work with file:// URLs
-				if (typeof process !== 'undefined' && process.versions && process.versions.node) {
-					const fs = await import('fs');
-					const wasmBytes = await fs.promises.readFile(wasmPath);
-					await UltraHdrWasm.default(wasmBytes);
+			if (explicitWasmUrl) {
+				moduleOptions.locateFile = (path: string) =>
+					path.endsWith('.wasm') ? explicitWasmUrl! : path;
+			} else if (location) {
+				if (isNode) {
+					// In Node, sidestep fetch entirely and provide the bytes directly.
+					const fs = await import('node:fs');
+					const wasmBytes = await fs.promises.readFile(joinPath(location, WASM_FILENAME));
+					moduleOptions.wasmBinary = new Uint8Array(wasmBytes);
 				} else {
-					// In browser, use the URL directly
-					await UltraHdrWasm.default(wasmPath);
+					moduleOptions.locateFile = (path: string) =>
+						path.endsWith('.wasm') ? joinPath(location, WASM_FILENAME) : path;
 				}
-			} else {
-				// Let the WASM module use its default URL resolution (import.meta.url)
-				await UltraHdrWasm.default();
 			}
 
-			wasmInstance = UltraHdrWasm as unknown as UltraHdrWasmModule;
-			return wasmInstance;
+			const instance = (await factory(moduleOptions)) as unknown as OpenUltraHdrModule;
+			// If the configuration changed while we were initializing, drop this
+			// instance and fall back to a fresh init under the new config.
+			if (generation !== initGeneration) {
+				return getWasm();
+			}
+			wasmInstance = instance;
+			return instance;
 		} catch (err) {
-			initPromise = null;
+			// Only clear the in-flight promise if it still belongs to this generation;
+			// otherwise resetCache() has already moved on.
+			if (generation === initGeneration) {
+				initPromise = null;
+			}
 			throw err;
 		}
 	})();
@@ -240,20 +150,6 @@ async function getWasm(): Promise<UltraHdrWasmModule> {
 
 /**
  * Checks if a buffer contains an UltraHDR image.
- *
- * This is a fast check that looks for gain map metadata without
- * fully decoding the image.
- *
- * @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!');
- * }
- * ```
  */
 export async function isUltraHdr(buffer: ArrayBuffer): Promise<boolean> {
 	const wasm = await getWasm();
@@ -261,62 +157,35 @@ export async 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.
+ * Probes an image to check if it's UltraHDR and extracts component info.
  *
- * @param buffer - Image file contents.
- * @return Probe result with detailed component information.
- *
- * @example
- * ```typescript
- * const buffer = await file.arrayBuffer();
- * const result = await probeUltraHdr(buffer);
- *
- * 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.
  */
 export async function probeUltraHdr(buffer: ArrayBuffer): Promise<UltraHdrProbeResult> {
-	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: '',
+		};
+	}
 }
 
 /**
  * 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);
- * ```
  */
 export async function decodeUltraHdr(
-	id: ItemId,
+	_id: ItemId,
 	buffer: ArrayBuffer
 ): Promise<UltraHdrDecodeResult> {
 	const wasm = await getWasm();
@@ -325,56 +194,20 @@ export async function decodeUltraHdr(
 
 /**
  * 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' });
- * ```
  */
 export async function encodeUltraHdr(
-	id: ItemId,
+	_id: ItemId,
 	sdrBuffer: ArrayBuffer,
 	hdrBuffer: ArrayBuffer,
 	options?: Partial<UltraHdrEncodeOptions>
 ): Promise<ArrayBuffer> {
 	const wasm = await getWasm();
-
-	// Create a proper WASM options instance
-	const wasmOpts = wasm.createDefaultOptions();
-
-	// Apply user-provided options
-	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: UltraHdrEncodeOptions = { ...defaultEncodeOptions, ...options };
 	const result = wasm.encodeUltraHdr(
 		new Uint8Array(sdrBuffer),
 		new Float32Array(hdrBuffer),
-		wasmOpts
+		merged
 	);
-
-	// Ensure we return a proper ArrayBuffer (not SharedArrayBuffer)
 	return result.buffer.slice(
 		result.byteOffset,
 		result.byteOffset + result.byteLength
@@ -383,26 +216,10 @@ export async function encodeUltraHdr(
 
 /**
  * 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' });
- * ```
  */
 export async function extractSdrBase(buffer: ArrayBuffer): Promise<ArrayBuffer> {
 	const wasm = await getWasm();
 	const result = wasm.extractSdrBase(new Uint8Array(buffer));
-	// Ensure we return a proper ArrayBuffer (not SharedArrayBuffer)
 	return result.buffer.slice(
 		result.byteOffset,
 		result.byteOffset + result.byteLength
@@ -411,20 +228,6 @@ export async 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');
- * ```
  */
 export async function getMetadata(buffer: ArrayBuffer): Promise<GainMapMetadata> {
 	const wasm = await getWasm();
@@ -433,36 +236,24 @@ export async function getMetadata(buffer: ArrayBuffer): Promise<GainMapMetadata>
 
 /**
  * Validates gain map metadata.
- *
- * @param metadata - The metadata to validate.
- * @return True if the metadata is valid.
  */
 export async function validateMetadata(metadata: GainMapMetadata): Promise<boolean> {
 	const wasm = await getWasm();
-	const wasmMetadata = await toWasmMetadata(metadata);
-	return wasm.validateMetadata(wasmMetadata);
+	return wasm.validateMetadata(metadata);
 }
 
 /**
  * Estimates the HDR headroom from metadata.
- *
- * @param metadata - The gain map metadata.
- * @return Maximum additional stops of dynamic range above SDR.
  */
 export async function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number> {
 	const wasm = await getWasm();
-	const wasmMetadata = await toWasmMetadata(metadata);
-	return wasm.estimateHdrHeadroom(wasmMetadata);
+	return wasm.estimateHdrHeadroom(metadata);
 }
 
 /**
  * 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.
  */
 export async function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean> {
 	const wasm = await getWasm();
-	const wasmMetadata = await toWasmMetadata(metadata);
-	return wasm.isMeaningfulHdr(wasmMetadata);
+	return wasm.isMeaningfulHdr(metadata);
 }

package/src/types.ts

@@ -115,10 +115,24 @@ export interface UltraHdrEncodeOptions {
 	/** 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) */