cross-image 0.2.4 → 0.4.1

package/esm/src/types.d.ts

@@ -135,10 +135,46 @@ export interface ResizeOptions {
      */
     fit?: "stretch" | "fit" | "fill" | "cover" | "contain";
 }
+/**
+ * Options for PNG encoding.
+ */
+export interface PNGEncoderOptions {
+    /**
+     * Compression level (0-9)
+     * - 0-2: No filtering (fastest)
+     * - 3-6: Sub filter (balanced, default is 6)
+     * - 7-9: Adaptive filtering per scanline (best compression)
+     *
+     * Default: 6 (balanced)
+     *
+     * Note: Affects PNG filter selection. The native deflate compression
+     * is used regardless of level.
+     */
+    compressionLevel?: number;
+}
+/**
+ * Options for APNG (Animated PNG) encoding.
+ *
+ * APNG uses PNG encoding for each frame.
+ */
+export interface APNGEncoderOptions extends PNGEncoderOptions {
+}
+/**
+ * Options for GIF encoding.
+ */
+export interface GIFEncoderOptions {
+    /**
+     * Loop count for animated GIFs.
+     * - 0 (default): Loop infinitely
+     * - 1+: Loop a specific number of times
+     * - undefined or not set: Loop infinitely (same as 0)
+     */
+    loop?: number;
+}
 /**
  * Options for ASCII art encoding
  */
-export interface ASCIIOptions {
+export interface ASCIIEncoderOptions {
     /** Target width in characters (default: 80) */
     width?: number;
     /** Character set to use (default: "simple") */
@@ -148,10 +184,23 @@ export interface ASCIIOptions {
     /** Whether to invert brightness (default: false) */
     invert?: boolean;
 }
+/**
+ * Options for TIFF encoding.
+ */
+export interface TIFFEncoderOptions {
+    /** Compression method: "none" (default), "lzw", "packbits", or "deflate" */
+    compression?: "none" | "lzw" | "packbits" | "deflate";
+    /** Encode as grayscale instead of RGB/RGBA (default: false) */
+    grayscale?: boolean;
+    /** Encode as RGB without alpha channel (default: false, ignored if grayscale is true) */
+    rgb?: boolean;
+    /** Encode as CMYK color space (default: false, ignored if grayscale is true) */
+    cmyk?: boolean;
+}
 /**
  * Options for WebP encoding
  */
-export interface WebPEncodeOptions {
+export interface WebPEncoderOptions {
     /**
      * Encoding quality (1-100, default: 90)
      * - 100 = lossless (VP8L)
@@ -164,6 +213,75 @@ export interface WebPEncodeOptions {
      */
     lossless?: boolean;
 }
+/**
+ * Options for JPEG encoding.
+ */
+export interface JPEGEncoderOptions {
+    /**
+     * Encoding quality (1-100, default depends on encoder backend).
+     */
+    quality?: number;
+    /**
+     * Enable progressive JPEG output when using the pure-JS encoder.
+     * Runtime encoders do not currently expose a progressive toggle.
+     */
+    progressive?: boolean;
+}
+/**
+ * Options for AVIF encoding.
+ *
+ * Note: AVIF encoding is currently delegated to runtime APIs (OffscreenCanvas).
+ * Many runtimes ignore `quality` for AVIF, or may not support AVIF encoding at all.
+ */
+export interface AVIFEncoderOptions {
+    /**
+     * Best-effort encoding quality.
+     *
+     * Accepts either 0-1 (canvas-style) or 1-100 (library-style).
+     */
+    quality?: number;
+}
+/**
+ * Options for HEIC encoding.
+ *
+ * Note: HEIC encoding is currently delegated to runtime APIs (OffscreenCanvas).
+ * Many runtimes do not support HEIC encoding.
+ */
+export interface HEICEncoderOptions {
+    /**
+     * Best-effort encoding quality.
+     *
+     * Accepts either 0-1 (canvas-style) or 1-100 (library-style).
+     */
+    quality?: number;
+}
+/**
+ * Common options for decode APIs.
+ *
+ * These options are runtime-agnostic and can be passed to `Image.decode()` and
+ * `Image.decodeFrames()`.
+ */
+export interface ImageDecoderOptions {
+    /**
+     * Controls tolerant decoding in the pure-JS decoders.
+     *
+     * - true (default): try to recover from corruption and continue
+     * - false: strict mode (fail fast)
+     */
+    tolerantDecoding?: boolean;
+    /**
+     * Optional warning callback used by pure-JS decoders when non-fatal issues are
+     * encountered.
+     */
+    onWarning?: (message: string, details?: unknown) => void;
+    /**
+     * Runtime decoder strategy.
+     *
+     * - "prefer" (default): try runtime decoders first (ImageDecoder/Canvas), then fall back to pure JS
+     * - "never": skip runtime decoders and use pure JS when available
+     */
+    runtimeDecoding?: "prefer" | "never";
+}
 /**
  * Image format handler interface
  */
@@ -177,7 +295,7 @@ export interface ImageFormat {
      * @param data Raw image data
      * @returns Decoded image data
      */
-    decode(data: Uint8Array): Promise<ImageData>;
+    decode(data: Uint8Array, options?: ImageDecoderOptions): Promise<ImageData>;
     /**
      * Encode image data to bytes
      * @param imageData Image data to encode
@@ -196,7 +314,7 @@ export interface ImageFormat {
      * @param data Raw image data
      * @returns Decoded multi-frame image data
      */
-    decodeFrames?(data: Uint8Array): Promise<MultiFrameImageData>;
+    decodeFrames?(data: Uint8Array, options?: ImageDecoderOptions): Promise<MultiFrameImageData>;
     /**
      * Encode multi-frame image data to bytes (optional)
      * @param imageData Multi-frame image data to encode

package/esm/src/utils/base64.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Base64 utilities.
+ *
+ * Designed to work across Deno, Node.js, and Bun without external dependencies.
+ */
+/**
+ * Encode bytes into a standard Base64 string.
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Decode a Base64 (or Base64URL) string into bytes.
+ *
+ * - Whitespace is ignored.
+ * - Missing padding is tolerated.
+ * - `-`/`_` are accepted as URL-safe variants.
+ */
+export declare function decodeBase64(base64: string): Uint8Array;
+export interface ParsedDataUrl {
+    mime: string;
+    bytes: Uint8Array;
+}
+/**
+ * Create a base64 data URL.
+ */
+export declare function toDataUrl(mime: string, bytes: Uint8Array): string;
+/**
+ * Parse a base64 data URL.
+ *
+ * Supports `data:<mime>;base64,<payload>`.
+ */
+export declare function parseDataUrl(url: string): ParsedDataUrl;
+//# sourceMappingURL=base64.d.ts.map

package/esm/src/utils/base64.js

@@ -0,0 +1,173 @@
+/**
+ * Base64 utilities.
+ *
+ * Designed to work across Deno, Node.js, and Bun without external dependencies.
+ */
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const DECODE_TABLE = (() => {
+    const table = new Uint8Array(256);
+    table.fill(0xff);
+    for (let i = 0; i < BASE64_ALPHABET.length; i++) {
+        table[BASE64_ALPHABET.charCodeAt(i)] = i;
+    }
+    return table;
+})();
+function stripWhitespace(input) {
+    // Avoid regex to keep this fast and allocation-light.
+    let out = "";
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        // Space, tab, CR, LF
+        if (code === 0x20 || code === 0x09 || code === 0x0d || code === 0x0a)
+            continue;
+        out += input[i];
+    }
+    return out;
+}
+function normalizeBase64(input) {
+    // Accept URL-safe alphabet in decode paths.
+    let s = stripWhitespace(input.trim());
+    if (s.length === 0)
+        return s;
+    // Map base64url to base64.
+    if (s.includes("-") || s.includes("_")) {
+        s = s.replaceAll("-", "+").replaceAll("_", "/");
+    }
+    const remainder = s.length % 4;
+    if (remainder === 1) {
+        throw new Error("Invalid base64: length must not be 1 (mod 4)");
+    }
+    if (remainder === 2)
+        s += "==";
+    if (remainder === 3)
+        s += "=";
+    return s;
+}
+/**
+ * Encode bytes into a standard Base64 string.
+ */
+export function encodeBase64(bytes) {
+    if (bytes.length === 0)
+        return "";
+    const outLen = Math.ceil(bytes.length / 3) * 4;
+    const out = new Array(outLen);
+    let i = 0;
+    let o = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        out[o++] = BASE64_ALPHABET[(n >> 18) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 12) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 6) & 63];
+        out[o++] = BASE64_ALPHABET[n & 63];
+    }
+    const remaining = bytes.length - i;
+    if (remaining === 1) {
+        const n = bytes[i] << 16;
+        out[o++] = BASE64_ALPHABET[(n >> 18) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 12) & 63];
+        out[o++] = "=";
+        out[o++] = "=";
+    }
+    else if (remaining === 2) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+        out[o++] = BASE64_ALPHABET[(n >> 18) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 12) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 6) & 63];
+        out[o++] = "=";
+    }
+    return out.join("");
+}
+/**
+ * Decode a Base64 (or Base64URL) string into bytes.
+ *
+ * - Whitespace is ignored.
+ * - Missing padding is tolerated.
+ * - `-`/`_` are accepted as URL-safe variants.
+ */
+export function decodeBase64(base64) {
+    const s = normalizeBase64(base64);
+    if (s.length === 0)
+        return new Uint8Array(0);
+    let padding = 0;
+    if (s.endsWith("=="))
+        padding = 2;
+    else if (s.endsWith("="))
+        padding = 1;
+    const quadCount = s.length / 4;
+    const outLen = quadCount * 3 - padding;
+    const out = new Uint8Array(outLen);
+    let o = 0;
+    for (let i = 0; i < s.length; i += 4) {
+        const c0 = s.charCodeAt(i);
+        const c1 = s.charCodeAt(i + 1);
+        const c2 = s.charCodeAt(i + 2);
+        const c3 = s.charCodeAt(i + 3);
+        const v0 = DECODE_TABLE[c0];
+        const v1 = DECODE_TABLE[c1];
+        if (v0 === 0xff || v1 === 0xff) {
+            throw new Error("Invalid base64: invalid character");
+        }
+        const isPad2 = c2 === 0x3d; // '='
+        const isPad3 = c3 === 0x3d;
+        const v2 = isPad2 ? 0 : DECODE_TABLE[c2];
+        const v3 = isPad3 ? 0 : DECODE_TABLE[c3];
+        if ((!isPad2 && v2 === 0xff) || (!isPad3 && v3 === 0xff)) {
+            throw new Error("Invalid base64: invalid character");
+        }
+        const n = (v0 << 18) | (v1 << 12) | (v2 << 6) | v3;
+        out[o++] = (n >> 16) & 0xff;
+        if (!isPad2) {
+            if (o >= out.length)
+                break;
+            out[o++] = (n >> 8) & 0xff;
+        }
+        if (!isPad3) {
+            if (o >= out.length)
+                break;
+            out[o++] = n & 0xff;
+        }
+        if (isPad2 || isPad3) {
+            // Padding is only valid in the final quartet.
+            if (i + 4 !== s.length) {
+                throw new Error("Invalid base64: padding can only appear at the end");
+            }
+            // If third char is padding, fourth must also be padding.
+            if (isPad2 && !isPad3) {
+                throw new Error("Invalid base64: invalid padding");
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Create a base64 data URL.
+ */
+export function toDataUrl(mime, bytes) {
+    if (!mime)
+        throw new Error("mime is required");
+    return `data:${mime};base64,${encodeBase64(bytes)}`;
+}
+/**
+ * Parse a base64 data URL.
+ *
+ * Supports `data:<mime>;base64,<payload>`.
+ */
+export function parseDataUrl(url) {
+    if (!url.startsWith("data:")) {
+        throw new Error("Invalid data URL: must start with 'data:'");
+    }
+    const commaIndex = url.indexOf(",");
+    if (commaIndex === -1) {
+        throw new Error("Invalid data URL: missing ',' separator");
+    }
+    const meta = url.slice(5, commaIndex);
+    const payload = url.slice(commaIndex + 1);
+    // We only support base64 payloads.
+    const metaParts = meta.split(";");
+    const mime = metaParts[0] || "application/octet-stream";
+    const isBase64 = metaParts.some((p) => p.toLowerCase() === "base64");
+    if (!isBase64) {
+        throw new Error("Invalid data URL: only base64 payloads are supported");
+    }
+    return { mime, bytes: decodeBase64(payload) };
+}

package/esm/src/utils/gif_decoder.d.ts

@@ -2,6 +2,7 @@
  * Pure JavaScript GIF decoder implementation
  * Supports GIF87a and GIF89a formats with LZW decompression
  */
+import type { ImageDecoderOptions } from "../types.js";
 interface GIFImage {
     width: number;
     height: number;
@@ -19,7 +20,8 @@ interface GIFFrame {
 export declare class GIFDecoder {
     private data;
     private pos;
-    constructor(data: Uint8Array);
+    private options;
+    constructor(data: Uint8Array, settings?: ImageDecoderOptions);
     private readByte;
     private readUint16LE;
     private readBytes;
@@ -36,6 +38,7 @@ export declare class GIFDecoder {
         frames: GIFFrame[];
     };
     private indexedToRGBA;
+    private decodeFrame;
     private deinterlace;
 }
 export {};

package/esm/src/utils/gif_decoder.js

@@ -4,7 +4,7 @@
  */
 import { LZWDecoder } from "./lzw.js";
 export class GIFDecoder {
-    constructor(data) {
+    constructor(data, settings = {}) {
         Object.defineProperty(this, "data", {
             enumerable: true,
             configurable: true,
@@ -17,8 +17,18 @@ export class GIFDecoder {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.data = data;
         this.pos = 0;
+        this.options = {
+            tolerantDecoding: settings.tolerantDecoding ?? true,
+            onWarning: settings.onWarning,
+        };
     }
     readByte() {
         if (this.pos >= this.data.length) {
@@ -207,72 +217,20 @@ export class GIFDecoder {
             }
             else if (separator === 0x2c) {
                 // Image Descriptor
-                const imageLeft = this.readUint16LE();
-                const imageTop = this.readUint16LE();
-                const imageWidth = this.readUint16LE();
-                const imageHeight = this.readUint16LE();
-                const packed = this.readByte();
-                const hasLocalColorTable = (packed & 0x80) !== 0;
-                const interlaced = (packed & 0x40) !== 0;
-                // Color table size: 2^(n+1) where n is the 3 least significant bits
-                const localColorTableSize = 2 << (packed & 0x07);
-                let localColorTable = null;
-                if (hasLocalColorTable) {
-                    localColorTable = this.readColorTable(localColorTableSize);
-                }
-                // Read image data
-                const minCodeSize = this.readByte();
-                const compressedData = this.readDataSubBlocks();
-                // Decompress using LZW
-                const decoder = new LZWDecoder(minCodeSize, compressedData);
-                const indexedData = decoder.decompress();
-                // Convert indexed to RGBA
-                const colorTable = localColorTable || globalColorTable;
-                if (!colorTable) {
-                    throw new Error("No color table available");
-                }
-                // Deinterlace if necessary
-                const deinterlaced = interlaced
-                    ? this.deinterlace(indexedData, imageWidth, imageHeight)
-                    : indexedData;
-                // Create frame with just the image data (not full canvas)
-                const frameData = new Uint8Array(imageWidth * imageHeight * 4);
-                for (let y = 0; y < imageHeight; y++) {
-                    for (let x = 0; x < imageWidth; x++) {
-                        const srcIdx = y * imageWidth + x;
-                        if (srcIdx >= deinterlaced.length)
-                            continue;
-                        const colorIndex = deinterlaced[srcIdx];
-                        const dstIdx = (y * imageWidth + x) * 4;
-                        if (transparentColorIndex !== null &&
-                            colorIndex === transparentColorIndex) {
-                            // Transparent pixel
-                            frameData[dstIdx] = 0;
-                            frameData[dstIdx + 1] = 0;
-                            frameData[dstIdx + 2] = 0;
-                            frameData[dstIdx + 3] = 0;
-                        }
-                        else {
-                            // Copy color from color table
-                            const colorOffset = colorIndex * 3;
-                            if (colorOffset + 2 < colorTable.length) {
-                                frameData[dstIdx] = colorTable[colorOffset];
-                                frameData[dstIdx + 1] = colorTable[colorOffset + 1];
-                                frameData[dstIdx + 2] = colorTable[colorOffset + 2];
-                                frameData[dstIdx + 3] = 255;
-                            }
-                        }
+                if (this.options.tolerantDecoding) {
+                    try {
+                        this.decodeFrame(frames, globalColorTable, transparentColorIndex, delayTime, disposalMethod);
+                    }
+                    catch (e) {
+                        // Tolerant decoding: skip corrupted frames and continue
+                        // This allows partial decoding of multi-frame GIFs with some bad frames
+                        this.options.onWarning?.("GIF: Skipping corrupted frame", e);
                     }
                 }
-                frames.push({
-                    width: imageWidth,
-                    height: imageHeight,
-                    left: imageLeft,
-                    top: imageTop,
-                    data: frameData,
-                    delay: delayTime,
-                    disposal: disposalMethod,
-                });
+                else {
+                    // Non-tolerant mode: throw on first error
+                    this.decodeFrame(frames, globalColorTable, transparentColorIndex, delayTime, disposalMethod);
+                }
                 // Reset graphic control extension state
                 transparentColorIndex = null;
                 delayTime = 0;
@@ -350,6 +308,74 @@ export class GIFDecoder {
             data: rgba,
         };
     }
+    decodeFrame(frames, globalColorTable, transparentColorIndex, delayTime, disposalMethod) {
+        const imageLeft = this.readUint16LE();
+        const imageTop = this.readUint16LE();
+        const imageWidth = this.readUint16LE();
+        const imageHeight = this.readUint16LE();
+        const packed = this.readByte();
+        const hasLocalColorTable = (packed & 0x80) !== 0;
+        const interlaced = (packed & 0x40) !== 0;
+        // Color table size: 2^(n+1) where n is the 3 least significant bits
+        const localColorTableSize = 2 << (packed & 0x07);
+        let localColorTable = null;
+        if (hasLocalColorTable) {
+            localColorTable = this.readColorTable(localColorTableSize);
+        }
+        // Read image data
+        const minCodeSize = this.readByte();
+        const compressedData = this.readDataSubBlocks();
+        // Decompress using LZW
+        const decoder = new LZWDecoder(minCodeSize, compressedData);
+        const indexedData = decoder.decompress();
+        // Convert indexed to RGBA
+        const colorTable = localColorTable || globalColorTable;
+        if (!colorTable) {
+            throw new Error("No color table available");
+        }
+        // Deinterlace if necessary
+        const deinterlaced = interlaced
+            ? this.deinterlace(indexedData, imageWidth, imageHeight)
+            : indexedData;
+        // Create frame with just the image data (not full canvas)
+        const frameData = new Uint8Array(imageWidth * imageHeight * 4);
+        for (let y = 0; y < imageHeight; y++) {
+            for (let x = 0; x < imageWidth; x++) {
+                const srcIdx = y * imageWidth + x;
+                if (srcIdx >= deinterlaced.length)
+                    continue;
+                const colorIndex = deinterlaced[srcIdx];
+                const dstIdx = (y * imageWidth + x) * 4;
+                if (transparentColorIndex !== null &&
+                    colorIndex === transparentColorIndex) {
+                    // Transparent pixel
+                    frameData[dstIdx] = 0;
+                    frameData[dstIdx + 1] = 0;
+                    frameData[dstIdx + 2] = 0;
+                    frameData[dstIdx + 3] = 0;
+                }
+                else {
+                    // Copy color from color table
+                    const colorOffset = colorIndex * 3;
+                    if (colorOffset + 2 < colorTable.length) {
+                        frameData[dstIdx] = colorTable[colorOffset];
+                        frameData[dstIdx + 1] = colorTable[colorOffset + 1];
+                        frameData[dstIdx + 2] = colorTable[colorOffset + 2];
+                        frameData[dstIdx + 3] = 255;
+                    }
+                }
+            }
+        }
+        frames.push({
+            width: imageWidth,
+            height: imageHeight,
+            left: imageLeft,
+            top: imageTop,
+            data: frameData,
+            delay: delayTime,
+            disposal: disposalMethod,
+        });
+    }
     deinterlace(data, width, height) {
         const deinterlaced = new Uint8Array(data.length);
         const passes = [

package/esm/src/utils/gif_encoder.d.ts

@@ -25,6 +25,8 @@ export declare class GIFEncoder {
     private quantize;
     private nextPowerOf2;
     private getBitsPerColor;
-    encode(): Uint8Array;
+    encode(options?: {
+        loop?: number;
+    }): Uint8Array;
 }
 //# sourceMappingURL=gif_encoder.d.ts.map

package/esm/src/utils/gif_encoder.js

@@ -165,11 +165,13 @@ export class GIFEncoder {
         }
         return Math.max(2, bits);
     }
-    encode() {
+    encode(options) {
         if (this.frames.length === 0) {
             throw new Error("No frames to encode");
         }
         const output = [];
+        // Get loop count from options (default to 0 = infinite)
+        const loopCount = options?.loop ?? 0;
         // Quantize first frame for Global Color Table
         const firstFrame = this.frames[0];
         const { palette: globalPalette, indexed: firstIndexed } = this.quantize(firstFrame.data);
@@ -206,7 +208,7 @@ export class GIFEncoder {
             this.writeString(output, "NETSCAPE2.0");
             output.push(3); // Sub-block Size
             output.push(1); // Loop Indicator (1 = loop)
-            this.writeUint16LE(output, 0); // Loop Count (0 = infinite)
+            this.writeUint16LE(output, loopCount); // Loop Count (0 = infinite, 1+ = specific count)
             output.push(0); // Block Terminator
         }
         // Encode frames

package/esm/src/utils/image_processing.d.ts

@@ -186,4 +186,35 @@ export declare function flipHorizontal(data: Uint8Array, width: number, height:
  * @returns Flipped image data
  */
 export declare function flipVertical(data: Uint8Array, width: number, height: number): Uint8Array;
+/**
+ * Convert RGB color to CMYK color space
+ * @param r Red component (0-255)
+ * @param g Green component (0-255)
+ * @param b Blue component (0-255)
+ * @returns CMYK values: [c (0-1), m (0-1), y (0-1), k (0-1)]
+ */
+export declare function rgbToCmyk(r: number, g: number, b: number): [number, number, number, number];
+/**
+ * Convert CMYK color to RGB color space
+ * @param c Cyan component (0-1)
+ * @param m Magenta component (0-1)
+ * @param y Yellow component (0-1)
+ * @param k Key/Black component (0-1)
+ * @returns RGB values: [r (0-255), g (0-255), b (0-255)]
+ */
+export declare function cmykToRgb(c: number, m: number, y: number, k: number): [number, number, number];
+/**
+ * Convert RGBA image data to CMYK representation
+ * Returns a Float32Array with 4 values per pixel (C, M, Y, K) in 0-1 range
+ * @param data Image data (RGBA)
+ * @returns CMYK image data as Float32Array (4 values per pixel)
+ */
+export declare function rgbaToCmyk(data: Uint8Array): Float32Array;
+/**
+ * Convert CMYK image data to RGBA representation
+ * @param cmykData CMYK image data (4 values per pixel in 0-1 range)
+ * @param alpha Optional alpha value for all pixels (0-255, default: 255)
+ * @returns RGBA image data
+ */
+export declare function cmykToRgba(cmykData: Float32Array, alpha?: number): Uint8Array;
 //# sourceMappingURL=image_processing.d.ts.map