open-ultrahdr 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -28,6 +28,34 @@ interface GainMapMetadata {
     /** Maximum HDR capacity (log2 scale) for full HDR output */
     hdrCapacityMax: number;
 }
+/**
+ * Result of probing an image to check if it's UltraHDR.
+ *
+ * Provides detailed information about what components were found
+ * without fully decoding the image. Useful for batch processing and filtering.
+ */
+interface UltraHdrProbeResult {
+    /** Whether the image is a valid UltraHDR image (has all required components) */
+    isValid: boolean;
+    /** Whether a primary JPEG image was found */
+    hasPrimaryImage: boolean;
+    /** Whether a gain map image was found */
+    hasGainMap: boolean;
+    /** Whether gain map metadata (XMP) was found */
+    hasMetadata: boolean;
+    /** Primary image width in pixels (0 if not found) */
+    width: number;
+    /** Primary image height in pixels (0 if not found) */
+    height: number;
+    /** Gain map width in pixels (0 if not found) */
+    gainMapWidth: number;
+    /** Gain map height in pixels (0 if not found) */
+    gainMapHeight: number;
+    /** HDR capacity (max additional stops of dynamic range), 0 if not found */
+    hdrCapacity: number;
+    /** Metadata version string (empty if not found) */
+    metadataVersion: string;
+}
 /**
  * Result of decoding an UltraHDR image.
  */
@@ -157,6 +185,37 @@ declare function setLocation(newLocation: string): void;
  * ```
  */
 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);
+ *
+ * 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');
+ * }
+ * ```
+ */
+declare function probeUltraHdr(buffer: ArrayBuffer): Promise<UltraHdrProbeResult>;
 /**
  * Decodes an UltraHDR image, extracting all components.
  *
@@ -263,4 +322,4 @@ declare function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number>
  */
 declare function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean>;
 
-export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, 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, smallSizeEncodeOptions, validateMetadata };

package/dist/index.d.ts

@@ -28,6 +28,34 @@ interface GainMapMetadata {
     /** Maximum HDR capacity (log2 scale) for full HDR output */
     hdrCapacityMax: number;
 }
+/**
+ * Result of probing an image to check if it's UltraHDR.
+ *
+ * Provides detailed information about what components were found
+ * without fully decoding the image. Useful for batch processing and filtering.
+ */
+interface UltraHdrProbeResult {
+    /** Whether the image is a valid UltraHDR image (has all required components) */
+    isValid: boolean;
+    /** Whether a primary JPEG image was found */
+    hasPrimaryImage: boolean;
+    /** Whether a gain map image was found */
+    hasGainMap: boolean;
+    /** Whether gain map metadata (XMP) was found */
+    hasMetadata: boolean;
+    /** Primary image width in pixels (0 if not found) */
+    width: number;
+    /** Primary image height in pixels (0 if not found) */
+    height: number;
+    /** Gain map width in pixels (0 if not found) */
+    gainMapWidth: number;
+    /** Gain map height in pixels (0 if not found) */
+    gainMapHeight: number;
+    /** HDR capacity (max additional stops of dynamic range), 0 if not found */
+    hdrCapacity: number;
+    /** Metadata version string (empty if not found) */
+    metadataVersion: string;
+}
 /**
  * Result of decoding an UltraHDR image.
  */
@@ -157,6 +185,37 @@ declare function setLocation(newLocation: string): void;
  * ```
  */
 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);
+ *
+ * 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');
+ * }
+ * ```
+ */
+declare function probeUltraHdr(buffer: ArrayBuffer): Promise<UltraHdrProbeResult>;
 /**
  * Decodes an UltraHDR image, extracting all components.
  *
@@ -263,4 +322,4 @@ declare function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number>
  */
 declare function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean>;
 
-export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, 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, smallSizeEncodeOptions, validateMetadata };

package/dist/index.js

@@ -41,6 +41,7 @@ __export(index_exports, {
   highQualityEncodeOptions: () => highQualityEncodeOptions,
   isMeaningfulHdr: () => isMeaningfulHdr,
   isUltraHdr: () => isUltraHdr,
+  probeUltraHdr: () => probeUltraHdr,
   setLocation: () => setLocation,
   smallSizeEncodeOptions: () => smallSizeEncodeOptions,
   validateMetadata: () => validateMetadata
@@ -121,15 +122,27 @@ async function getWasm() {
     return initPromise;
   }
   initPromise = (async () => {
-    const UltraHdrWasm = await import("open-ultrahdr-wasm");
-    if (location) {
-      const wasmUrl = location + "open_ultrahdr_bg.wasm";
-      await UltraHdrWasm.default(wasmUrl);
-    } else {
-      await UltraHdrWasm.default();
+    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 fs = await import("fs");
+          const wasmBytes = await fs.promises.readFile(wasmPath);
+          await UltraHdrWasm.default(wasmBytes);
+        } else {
+          await UltraHdrWasm.default(wasmPath);
+        }
+      } else {
+        await UltraHdrWasm.default();
+      }
+      wasmInstance = UltraHdrWasm;
+      return wasmInstance;
+    } catch (err) {
+      initPromise = null;
+      throw err;
     }
-    wasmInstance = UltraHdrWasm;
-    return wasmInstance;
   })();
   return initPromise;
 }
@@ -137,6 +150,10 @@ async function isUltraHdr(buffer) {
   const wasm = await getWasm();
   return wasm.isUltraHdr(new Uint8Array(buffer));
 }
+async function probeUltraHdr(buffer) {
+  const wasm = await getWasm();
+  return wasm.probeUltraHdr(new Uint8Array(buffer));
+}
 async function decodeUltraHdr(id, buffer) {
   const wasm = await getWasm();
   return wasm.decodeUltraHdr(new Uint8Array(buffer));
@@ -156,12 +173,18 @@ async function encodeUltraHdr(id, sdrBuffer, hdrBuffer, options) {
     new Float32Array(hdrBuffer),
     wasmOpts
   );
-  return result.buffer.slice(0);
+  return result.buffer.slice(
+    result.byteOffset,
+    result.byteOffset + result.byteLength
+  );
 }
 async function extractSdrBase(buffer) {
   const wasm = await getWasm();
   const result = wasm.extractSdrBase(new Uint8Array(buffer));
-  return result.buffer.slice(0);
+  return result.buffer.slice(
+    result.byteOffset,
+    result.byteOffset + result.byteLength
+  );
 }
 async function getMetadata(buffer) {
   const wasm = await getWasm();
@@ -195,6 +218,7 @@ async function isMeaningfulHdr(metadata) {
   highQualityEncodeOptions,
   isMeaningfulHdr,
   isUltraHdr,
+  probeUltraHdr,
   setLocation,
   smallSizeEncodeOptions,
   validateMetadata

package/dist/index.mjs

@@ -72,15 +72,27 @@ async function getWasm() {
     return initPromise;
   }
   initPromise = (async () => {
-    const UltraHdrWasm = await import("open-ultrahdr-wasm");
-    if (location) {
-      const wasmUrl = location + "open_ultrahdr_bg.wasm";
-      await UltraHdrWasm.default(wasmUrl);
-    } else {
-      await UltraHdrWasm.default();
+    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 fs = await import("fs");
+          const wasmBytes = await fs.promises.readFile(wasmPath);
+          await UltraHdrWasm.default(wasmBytes);
+        } else {
+          await UltraHdrWasm.default(wasmPath);
+        }
+      } else {
+        await UltraHdrWasm.default();
+      }
+      wasmInstance = UltraHdrWasm;
+      return wasmInstance;
+    } catch (err) {
+      initPromise = null;
+      throw err;
     }
-    wasmInstance = UltraHdrWasm;
-    return wasmInstance;
   })();
   return initPromise;
 }
@@ -88,6 +100,10 @@ async function isUltraHdr(buffer) {
   const wasm = await getWasm();
   return wasm.isUltraHdr(new Uint8Array(buffer));
 }
+async function probeUltraHdr(buffer) {
+  const wasm = await getWasm();
+  return wasm.probeUltraHdr(new Uint8Array(buffer));
+}
 async function decodeUltraHdr(id, buffer) {
   const wasm = await getWasm();
   return wasm.decodeUltraHdr(new Uint8Array(buffer));
@@ -107,12 +123,18 @@ async function encodeUltraHdr(id, sdrBuffer, hdrBuffer, options) {
     new Float32Array(hdrBuffer),
     wasmOpts
   );
-  return result.buffer.slice(0);
+  return result.buffer.slice(
+    result.byteOffset,
+    result.byteOffset + result.byteLength
+  );
 }
 async function extractSdrBase(buffer) {
   const wasm = await getWasm();
   const result = wasm.extractSdrBase(new Uint8Array(buffer));
-  return result.buffer.slice(0);
+  return result.buffer.slice(
+    result.byteOffset,
+    result.byteOffset + result.byteLength
+  );
 }
 async function getMetadata(buffer) {
   const wasm = await getWasm();
@@ -145,6 +167,7 @@ export {
   highQualityEncodeOptions,
   isMeaningfulHdr,
   isUltraHdr,
+  probeUltraHdr,
   setLocation,
   smallSizeEncodeOptions,
   validateMetadata

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "open-ultrahdr",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "UltraHDR (ISO 21496-1) gain map support for JavaScript/TypeScript",
 	"author": "Adam Silverstein",
 	"license": "GPL-2.0-or-later",
@@ -15,14 +15,14 @@
 	"homepage": "https://github.com/adamsilverstein/lib-open-ultrahdr",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/adamsilverstein/lib-open-ultrahdr.git",
+		"url": "git+https://github.com/adamsilverstein/lib-open-ultrahdr.git",
 		"directory": "js"
 	},
 	"bugs": {
 		"url": "https://github.com/adamsilverstein/lib-open-ultrahdr/issues"
 	},
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=20.0.0"
 	},
 	"files": [
 		"src",
@@ -52,11 +52,12 @@
 		"lint:fix": "eslint src __tests__ --fix"
 	},
 	"dependencies": {
-		"open-ultrahdr-wasm": "^0.1.1"
+		"open-ultrahdr-wasm": "^0.1.2"
 	},
 	"devDependencies": {
 		"@eslint/js": "^9.0.0",
-		"@vitest/coverage-v8": "^2.0.0",
+		"@types/node": "^25.1.0",
+		"@vitest/coverage-v8": "^4.0.0",
 		"eslint": "^9.0.0",
 		"eslint-config-prettier": "^9.0.0",
 		"tsup": "^8.0.0",
@@ -64,7 +65,7 @@
 		"typescript-eslint": "^8.0.0",
 		"vite-plugin-top-level-await": "^1.6.0",
 		"vite-plugin-wasm": "^3.5.0",
-		"vitest": "^2.0.0"
+		"vitest": "^4.0.0"
 	},
 	"publishConfig": {
 		"access": "public"

package/src/index.ts

@@ -22,7 +22,13 @@
  */
 
 // Re-export types
-export type { ItemId, GainMapMetadata, UltraHdrDecodeResult, UltraHdrEncodeOptions } from './types';
+export type {
+	ItemId,
+	GainMapMetadata,
+	UltraHdrDecodeResult,
+	UltraHdrEncodeOptions,
+	UltraHdrProbeResult,
+} from './types';
 
 export {
 	ColorGamut,
@@ -32,7 +38,13 @@ export {
 	smallSizeEncodeOptions,
 } from './types';
 
-import type { ItemId, GainMapMetadata, UltraHdrDecodeResult, UltraHdrEncodeOptions } from './types';
+import type {
+	ItemId,
+	GainMapMetadata,
+	UltraHdrDecodeResult,
+	UltraHdrEncodeOptions,
+	UltraHdrProbeResult,
+} from './types';
 
 import { defaultEncodeOptions } from './types';
 
@@ -62,6 +74,7 @@ interface WasmGainMapMetadata {
 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,
@@ -159,21 +172,37 @@ async function getWasm(): Promise<UltraHdrWasmModule> {
 	}
 
 	initPromise = (async () => {
-		// Dynamic import of the WASM package
-		const UltraHdrWasm = (await import('open-ultrahdr-wasm')) as unknown as UltraHdrWasmModule;
-
-		// Initialize WASM with the location prefix for the .wasm file
-		// If location is set, construct the full URL to the WASM file
-		if (location) {
-			const wasmUrl = location + 'open_ultrahdr_bg.wasm';
-			await UltraHdrWasm.default(wasmUrl);
-		} else {
-			// Let the WASM module use its default URL resolution (import.meta.url)
-			await UltraHdrWasm.default();
+		try {
+			// Dynamic import of the WASM package
+			const UltraHdrWasm = (await import('open-ultrahdr-wasm')) as unknown as UltraHdrWasmModule;
+
+			// Initialize WASM with the location prefix for the .wasm file
+			// If location is set, construct the full URL to the WASM file
+			if (location) {
+				const base = location.endsWith('/') ? location : `${location}/`;
+				const wasmPath = base + 'open_ultrahdr_bg.wasm';
+
+				// 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);
+				} else {
+					// In browser, use the URL directly
+					await UltraHdrWasm.default(wasmPath);
+				}
+			} else {
+				// Let the WASM module use its default URL resolution (import.meta.url)
+				await UltraHdrWasm.default();
+			}
+
+			wasmInstance = UltraHdrWasm as unknown as UltraHdrWasmModule;
+			return wasmInstance;
+		} catch (err) {
+			initPromise = null;
+			throw err;
 		}
-
-		wasmInstance = UltraHdrWasm as unknown as UltraHdrWasmModule;
-		return wasmInstance;
 	})();
 
 	return initPromise;
@@ -201,6 +230,41 @@ export async function isUltraHdr(buffer: ArrayBuffer): Promise<boolean> {
 	return wasm.isUltraHdr(new Uint8Array(buffer));
 }
 
+/**
+ * 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);
+ *
+ * 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');
+ * }
+ * ```
+ */
+export async function probeUltraHdr(buffer: ArrayBuffer): Promise<UltraHdrProbeResult> {
+	const wasm = await getWasm();
+	return wasm.probeUltraHdr(new Uint8Array(buffer));
+}
+
 /**
  * Decodes an UltraHDR image, extracting all components.
  *
@@ -281,7 +345,10 @@ export async function encodeUltraHdr(
 	);
 
 	// Ensure we return a proper ArrayBuffer (not SharedArrayBuffer)
-	return result.buffer.slice(0) as ArrayBuffer;
+	return result.buffer.slice(
+		result.byteOffset,
+		result.byteOffset + result.byteLength
+	) as ArrayBuffer;
 }
 
 /**
@@ -306,7 +373,10 @@ 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(0) as ArrayBuffer;
+	return result.buffer.slice(
+		result.byteOffset,
+		result.byteOffset + result.byteLength
+	) as ArrayBuffer;
 }
 
 /**

package/src/types.ts

@@ -38,6 +38,44 @@ export interface GainMapMetadata {
 	hdrCapacityMax: number;
 }
 
+/**
+ * Result of probing an image to check if it's UltraHDR.
+ *
+ * Provides detailed information about what components were found
+ * without fully decoding the image. Useful for batch processing and filtering.
+ */
+export interface UltraHdrProbeResult {
+	/** Whether the image is a valid UltraHDR image (has all required components) */
+	isValid: boolean;
+
+	/** Whether a primary JPEG image was found */
+	hasPrimaryImage: boolean;
+
+	/** Whether a gain map image was found */
+	hasGainMap: boolean;
+
+	/** Whether gain map metadata (XMP) was found */
+	hasMetadata: boolean;
+
+	/** Primary image width in pixels (0 if not found) */
+	width: number;
+
+	/** Primary image height in pixels (0 if not found) */
+	height: number;
+
+	/** Gain map width in pixels (0 if not found) */
+	gainMapWidth: number;
+
+	/** Gain map height in pixels (0 if not found) */
+	gainMapHeight: number;
+
+	/** HDR capacity (max additional stops of dynamic range), 0 if not found */
+	hdrCapacity: number;
+
+	/** Metadata version string (empty if not found) */
+	metadataVersion: string;
+}
+
 /**
  * Result of decoding an UltraHDR image.
  */