cross-image 0.1.2 → 0.1.4

package/esm/src/formats/bmp.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 // Constants for unit conversions
 const INCHES_PER_METER = 39.3701;
 /**
@@ -6,12 +7,14 @@ const INCHES_PER_METER = 39.3701;
  */
 export class BMPFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "bmp"
         });
+        /** MIME type for BMP images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -19,11 +22,21 @@ export class BMPFormat {
             value: "image/bmp"
         });
     }
+    /**
+     * Check if the given data is a BMP image
+     * @param data Raw image data to check
+     * @returns true if data has BMP signature
+     */
     canDecode(data) {
         // BMP signature: 'BM' (0x42 0x4D)
         return data.length >= 2 &&
             data[0] === 0x42 && data[1] === 0x4d;
     }
+    /**
+     * Decode BMP image data to RGBA
+     * @param data Raw BMP image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid BMP signature");
@@ -61,6 +74,8 @@ export class BMPFormat {
         // Handle negative height (top-down bitmap)
         const isTopDown = height < 0;
         const absHeight = Math.abs(height);
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, absHeight);
         // Only support uncompressed BMPs for now
         if (compression !== 0) {
             throw new Error(`Compressed BMP not supported (compression type: ${compression})`);
@@ -94,6 +109,11 @@ export class BMPFormat {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         });
     }
+    /**
+     * Encode RGBA image data to BMP format
+     * @param imageData Image data to encode
+     * @returns Encoded BMP image bytes
+     */
     encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Calculate sizes

package/esm/src/formats/gif.d.ts

@@ -12,12 +12,33 @@ import type { ImageData, ImageFormat, MultiFrameImageData } from "../types.js";
  * - Falls back to runtime APIs when pure-JS fails
  */
 export declare class GIFFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "gif";
+    /** MIME type for GIF images */
     readonly mimeType = "image/gif";
+    /**
+     * Check if this format supports multiple frames (animations)
+     * @returns true for GIF format
+     */
     supportsMultipleFrames(): boolean;
+    /**
+     * Check if the given data is a GIF image
+     * @param data Raw image data to check
+     * @returns true if data has GIF signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode GIF image data to RGBA (first frame only)
+     * @param data Raw GIF image data
+     * @returns Decoded image data with RGBA pixels of first frame
+     */
     decode(data: Uint8Array): Promise<ImageData>;
     private extractMetadata;
+    /**
+     * Encode RGBA image data to GIF format (single frame)
+     * @param imageData Image data to encode
+     * @returns Encoded GIF image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     /**
      * Decode all frames from an animated GIF

package/esm/src/formats/gif.js

@@ -1,5 +1,6 @@
 import { GIFDecoder } from "../utils/gif_decoder.js";
 import { GIFEncoder } from "../utils/gif_encoder.js";
+import { validateImageDimensions } from "../utils/security.js";
 /**
  * GIF format handler
  * Now includes pure-JS implementation with custom LZW compression/decompression
@@ -14,12 +15,14 @@ import { GIFEncoder } from "../utils/gif_encoder.js";
  */
 export class GIFFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "gif"
         });
+        /** MIME type for GIF images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -27,9 +30,18 @@ export class GIFFormat {
             value: "image/gif"
         });
     }
+    /**
+     * Check if this format supports multiple frames (animations)
+     * @returns true for GIF format
+     */
     supportsMultipleFrames() {
         return true;
     }
+    /**
+     * Check if the given data is a GIF image
+     * @param data Raw image data to check
+     * @returns true if data has GIF signature
+     */
     canDecode(data) {
         // GIF signature: "GIF87a" or "GIF89a"
         return data.length >= 6 &&
@@ -38,6 +50,11 @@ export class GIFFormat {
             (data[4] === 0x37 || data[4] === 0x39) && // "7" or "9"
             data[5] === 0x61; // "a"
     }
+    /**
+     * Decode GIF image data to RGBA (first frame only)
+     * @param data Raw GIF image data
+     * @returns Decoded image data with RGBA pixels of first frame
+     */
     async decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid GIF signature");
@@ -46,6 +63,8 @@ export class GIFFormat {
         try {
             const decoder = new GIFDecoder(data);
             const result = decoder.decode();
+            // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+            validateImageDimensions(result.width, result.height);
             // Extract metadata from comment extensions
             const metadata = this.extractMetadata(data);
             return {
@@ -62,6 +81,8 @@ export class GIFFormat {
             const width = this.readUint16LE(data, pos);
             pos += 2;
             const height = this.readUint16LE(data, pos);
+            // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+            validateImageDimensions(width, height);
             const rgba = await this.decodeUsingRuntime(data, width, height);
             const metadata = this.extractMetadata(data);
             return {
@@ -124,6 +145,11 @@ export class GIFFormat {
         }
         return metadata;
     }
+    /**
+     * Encode RGBA image data to GIF format (single frame)
+     * @param imageData Image data to encode
+     * @returns Encoded GIF image bytes
+     */
     async encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Try pure-JS encoder first

package/esm/src/formats/jpeg.d.ts

@@ -4,10 +4,27 @@ import type { ImageData, ImageFormat } from "../types.js";
  * Implements a basic JPEG decoder and encoder
  */
 export declare class JPEGFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "jpeg";
+    /** MIME type for JPEG images */
     readonly mimeType = "image/jpeg";
+    /**
+     * Check if the given data is a JPEG image
+     * @param data Raw image data to check
+     * @returns true if data has JPEG signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode JPEG image data to RGBA
+     * @param data Raw JPEG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to JPEG format
+     * @param imageData Image data to encode
+     * @returns Encoded JPEG image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     private injectMetadata;
     private decodeUsingRuntime;

package/esm/src/formats/jpeg.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 // Constants for unit conversions
 const CM_PER_INCH = 2.54;
 /**
@@ -6,12 +7,14 @@ const CM_PER_INCH = 2.54;
  */
 export class JPEGFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "jpeg"
         });
+        /** MIME type for JPEG images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -19,11 +22,21 @@ export class JPEGFormat {
             value: "image/jpeg"
         });
     }
+    /**
+     * Check if the given data is a JPEG image
+     * @param data Raw image data to check
+     * @returns true if data has JPEG signature
+     */
     canDecode(data) {
         // JPEG signature: FF D8 FF
         return data.length >= 3 &&
             data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;
     }
+    /**
+     * Decode JPEG image data to RGBA
+     * @param data Raw JPEG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     async decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid JPEG signature");
@@ -78,6 +91,8 @@ export class JPEGFormat {
         if (width === 0 || height === 0) {
             throw new Error("Could not determine JPEG dimensions");
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         // For a pure JS implementation, we'd need to implement full JPEG decoding
         // which is very complex. Instead, we'll use the browser/runtime's decoder.
         const rgba = await this.decodeUsingRuntime(data, width, height);
@@ -88,6 +103,11 @@ export class JPEGFormat {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         };
     }
+    /**
+     * Encode RGBA image data to JPEG format
+     * @param imageData Image data to encode
+     * @returns Encoded JPEG image bytes
+     */
     async encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Try to use runtime encoding if available (better quality)

package/esm/src/formats/png.d.ts

@@ -4,10 +4,27 @@ import type { ImageData, ImageFormat } from "../types.js";
  * Implements a pure JavaScript PNG decoder and encoder
  */
 export declare class PNGFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "png";
+    /** MIME type for PNG images */
     readonly mimeType = "image/png";
+    /**
+     * Check if the given data is a PNG image
+     * @param data Raw image data to check
+     * @returns true if data has PNG signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode PNG image data to RGBA
+     * @param data Raw PNG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to PNG format
+     * @param imageData Image data to encode
+     * @returns Encoded PNG image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     private readUint32;
     private writeUint32;

package/esm/src/formats/png.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 // Constants for unit conversions
 const INCHES_PER_METER = 39.3701;
 /**
@@ -6,12 +7,14 @@ const INCHES_PER_METER = 39.3701;
  */
 export class PNGFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "png"
         });
+        /** MIME type for PNG images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -19,6 +22,11 @@ export class PNGFormat {
             value: "image/png"
         });
     }
+    /**
+     * Check if the given data is a PNG image
+     * @param data Raw image data to check
+     * @returns true if data has PNG signature
+     */
     canDecode(data) {
         // PNG signature: 137 80 78 71 13 10 26 10
         return data.length >= 8 &&
@@ -27,6 +35,11 @@ export class PNGFormat {
             data[4] === 13 && data[5] === 10 &&
             data[6] === 26 && data[7] === 10;
     }
+    /**
+     * Decode PNG image data to RGBA
+     * @param data Raw PNG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     async decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid PNG signature");
@@ -79,6 +92,8 @@ export class PNGFormat {
         if (width === 0 || height === 0) {
             throw new Error("Invalid PNG: missing IHDR chunk");
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         // Concatenate IDAT chunks
         const idatData = this.concatenateChunks(chunks);
         // Decompress data
@@ -92,6 +107,11 @@ export class PNGFormat {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         };
     }
+    /**
+     * Encode RGBA image data to PNG format
+     * @param imageData Image data to encode
+     * @returns Encoded PNG image bytes
+     */
     async encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Prepare IHDR chunk

package/esm/src/formats/raw.d.ts

@@ -10,12 +10,29 @@ import type { ImageData, ImageFormat } from "../types.js";
  * - RGBA pixel data (width * height * 4 bytes)
  */
 export declare class RAWFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "raw";
+    /** MIME type for RAW images */
     readonly mimeType = "image/raw";
     private readonly MAGIC_BYTES;
     private readonly HEADER_SIZE;
+    /**
+     * Check if the given data is a RAW image
+     * @param data Raw image data to check
+     * @returns true if data has RAW signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode RAW image data to RGBA
+     * @param data Raw RAW image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to RAW format
+     * @param imageData Image data to encode
+     * @returns Encoded RAW image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     private readUint32;
     private writeUint32;

package/esm/src/formats/raw.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 /**
  * RAW format handler
  * Implements a simple uncompressed RGBA format with a minimal header
@@ -10,12 +11,14 @@
  */
 export class RAWFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "raw"
         });
+        /** MIME type for RAW images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -35,6 +38,11 @@ export class RAWFormat {
             value: 12
         }); // 4 bytes magic + 4 bytes width + 4 bytes height
     }
+    /**
+     * Check if the given data is a RAW image
+     * @param data Raw image data to check
+     * @returns true if data has RAW signature
+     */
     canDecode(data) {
         // Check if data has at least header size and matches magic bytes
         if (data.length < this.HEADER_SIZE) {
@@ -45,6 +53,11 @@ export class RAWFormat {
             data[2] === this.MAGIC_BYTES[2] &&
             data[3] === this.MAGIC_BYTES[3];
     }
+    /**
+     * Decode RAW image data to RGBA
+     * @param data Raw RAW image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid RAW signature");
@@ -56,6 +69,8 @@ export class RAWFormat {
         if (width <= 0 || height <= 0) {
             throw new Error(`Invalid RAW dimensions: ${width}x${height}`);
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         const expectedDataLength = width * height * 4;
         const actualDataLength = data.length - this.HEADER_SIZE;
         if (actualDataLength !== expectedDataLength) {
@@ -66,6 +81,11 @@ export class RAWFormat {
         pixelData.set(data.subarray(this.HEADER_SIZE));
         return Promise.resolve({ width, height, data: pixelData });
     }
+    /**
+     * Encode RGBA image data to RAW format
+     * @param imageData Image data to encode
+     * @returns Encoded RAW image bytes
+     */
     encode(imageData) {
         const { width, height, data } = imageData;
         // Validate input

package/esm/src/formats/tiff.d.ts

@@ -14,10 +14,26 @@ export interface TIFFEncodeOptions {
  * Supports multi-page TIFF files.
  */
 export declare class TIFFFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "tiff";
+    /** MIME type for TIFF images */
     readonly mimeType = "image/tiff";
+    /**
+     * Check if this format supports multiple frames (pages)
+     * @returns true for TIFF format
+     */
     supportsMultipleFrames(): boolean;
+    /**
+     * Check if the given data is a TIFF image
+     * @param data Raw image data to check
+     * @returns true if data has TIFF signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode TIFF image data to RGBA (first page only)
+     * @param data Raw TIFF image data
+     * @returns Decoded image data with RGBA pixels of first page
+     */
     decode(data: Uint8Array): Promise<ImageData>;
     encode(imageData: ImageData, options?: unknown): Promise<Uint8Array>;
     /**

package/esm/src/formats/tiff.js

@@ -1,4 +1,5 @@
 import { TIFFLZWDecoder, TIFFLZWEncoder } from "../utils/tiff_lzw.js";
+import { validateImageDimensions } from "../utils/security.js";
 // Constants for unit conversions
 const DEFAULT_DPI = 72;
 /**
@@ -10,12 +11,14 @@ const DEFAULT_DPI = 72;
  */
 export class TIFFFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "tiff"
         });
+        /** MIME type for TIFF images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -23,9 +26,18 @@ export class TIFFFormat {
             value: "image/tiff"
         });
     }
+    /**
+     * Check if this format supports multiple frames (pages)
+     * @returns true for TIFF format
+     */
     supportsMultipleFrames() {
         return true;
     }
+    /**
+     * Check if the given data is a TIFF image
+     * @param data Raw image data to check
+     * @returns true if data has TIFF signature
+     */
     canDecode(data) {
         // TIFF signature: "II" (little-endian) or "MM" (big-endian) followed by 42
         return data.length >= 4 &&
@@ -35,6 +47,11 @@ export class TIFFFormat {
                     data[3] === 0x2a) // "MM\0*"
             );
     }
+    /**
+     * Decode TIFF image data to RGBA (first page only)
+     * @param data Raw TIFF image data
+     * @returns Decoded image data with RGBA pixels of first page
+     */
     async decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid TIFF signature");
@@ -144,7 +161,7 @@ export class TIFFFormat {
         // IFD (Image File Directory)
         const ifdStart = result.length;
         // Count number of entries (including metadata)
-        let numEntries = 11; // Base entries
+        let numEntries = 12; // Base entries (including ExtraSamples)
         if (metadata?.description)
             numEntries++;
         if (metadata?.author)
@@ -184,6 +201,8 @@ export class TIFFFormat {
         const yResOffset = dataOffset;
         this.writeIFDEntry(result, 0x011b, 5, 1, yResOffset);
         dataOffset += 8;
+        // ExtraSamples (0x0152) - 2 = unassociated alpha
+        this.writeIFDEntry(result, 0x0152, 3, 1, 2);
         // Optional metadata entries
         if (metadata?.description) {
             const descBytes = new TextEncoder().encode(metadata.description + "\0");
@@ -210,6 +229,11 @@ export class TIFFFormat {
         // Next IFD offset (0 = no more IFDs)
         this.writeUint32LE(result, 0);
         // Write variable-length data
+        // BitsPerSample values (must be written first to match offset calculation)
+        this.writeUint16LE(result, 8);
+        this.writeUint16LE(result, 8);
+        this.writeUint16LE(result, 8);
+        this.writeUint16LE(result, 8);
         // XResolution value (rational)
         const dpiX = metadata?.dpiX ?? DEFAULT_DPI;
         this.writeUint32LE(result, dpiX);
@@ -218,11 +242,6 @@ export class TIFFFormat {
         const dpiY = metadata?.dpiY ?? DEFAULT_DPI;
         this.writeUint32LE(result, dpiY);
         this.writeUint32LE(result, 1);
-        // BitsPerSample values
-        this.writeUint16LE(result, 8);
-        this.writeUint16LE(result, 8);
-        this.writeUint16LE(result, 8);
-        this.writeUint16LE(result, 8);
         // Write metadata strings
         if (metadata?.description) {
             const descBytes = new TextEncoder().encode(metadata.description + "\0");
@@ -358,7 +377,7 @@ export class TIFFFormat {
             ifdOffsets.push(currentOffset);
             const ifdStart = result.length;
             // Count number of entries (including metadata only for first page)
-            let numEntries = 11;
+            let numEntries = 12; // Base entries (including ExtraSamples)
             if (i === 0 && imageData.metadata) {
                 if (imageData.metadata.description)
                     numEntries++;
@@ -402,6 +421,8 @@ export class TIFFFormat {
             const yResOffset = dataOffset;
             this.writeIFDEntry(result, 0x011b, 5, 1, yResOffset);
             dataOffset += 8;
+            // ExtraSamples (0x0152) - 2 = unassociated alpha
+            this.writeIFDEntry(result, 0x0152, 3, 1, 2);
             // Metadata (only for first page)
             if (i === 0 && imageData.metadata) {
                 if (imageData.metadata.description) {
@@ -432,6 +453,11 @@ export class TIFFFormat {
             this.writeUint32LE(result, nextIFDOffset);
             currentOffset = dataOffset;
             // Write variable-length data
+            // BitsPerSample values (must be written first to match offset calculation)
+            this.writeUint16LE(result, 8);
+            this.writeUint16LE(result, 8);
+            this.writeUint16LE(result, 8);
+            this.writeUint16LE(result, 8);
             // XResolution value (rational)
             const dpiX = (i === 0 && imageData.metadata?.dpiX) ||
                 DEFAULT_DPI;
@@ -442,11 +468,6 @@ export class TIFFFormat {
                 DEFAULT_DPI;
             this.writeUint32LE(result, dpiY);
             this.writeUint32LE(result, 1);
-            // BitsPerSample values
-            this.writeUint16LE(result, 8);
-            this.writeUint16LE(result, 8);
-            this.writeUint16LE(result, 8);
-            this.writeUint16LE(result, 8);
             // Write metadata strings (only for first page)
             if (i === 0 && imageData.metadata) {
                 if (imageData.metadata.description) {
@@ -707,6 +728,8 @@ export class TIFFFormat {
             // Uncompressed
             pixelData = data.slice(stripOffset, stripOffset + stripByteCount);
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         // Convert to RGBA
         const rgba = new Uint8Array(width * height * 4);
         let srcPos = 0;
@@ -770,6 +793,8 @@ export class TIFFFormat {
             // Uncompressed
             pixelData = data.slice(stripOffset, stripOffset + stripByteCount);
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         // Convert to RGBA
         const rgba = new Uint8Array(width * height * 4);
         let srcPos = 0;

package/esm/src/formats/webp.d.ts

@@ -4,10 +4,28 @@ import type { ImageData, ImageFormat, WebPEncodeOptions } from "../types.js";
  * Implements a basic WebP decoder and encoder
  */
 export declare class WebPFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "webp";
+    /** MIME type for WebP images */
     readonly mimeType = "image/webp";
+    /**
+     * Check if the given data is a WebP image
+     * @param data Raw image data to check
+     * @returns true if data has WebP signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode WebP image data to RGBA
+     * @param data Raw WebP image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to WebP format
+     * @param imageData Image data to encode
+     * @param options Optional WebP encoding options
+     * @returns Encoded WebP image bytes
+     */
     encode(imageData: ImageData, options?: WebPEncodeOptions): Promise<Uint8Array>;
     private readUint32LE;
     private readUint24LE;