cross-image 0.4.0 → 0.4.1

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_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

package/esm/src/utils/image_processing.js

@@ -743,3 +743,91 @@ export function flipVertical(data, width, height) {
     }
     return result;
 }
+/**
+ * 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 function rgbToCmyk(r, g, b) {
+    // Normalize RGB values to 0-1 range
+    const rNorm = r / 255;
+    const gNorm = g / 255;
+    const bNorm = b / 255;
+    // Calculate K (key/black)
+    const k = 1 - Math.max(rNorm, gNorm, bNorm);
+    // If K is 1 (pure black), CMY are undefined but conventionally set to 0
+    if (k === 1) {
+        return [0, 0, 0, 1];
+    }
+    // Calculate CMY components
+    const c = (1 - rNorm - k) / (1 - k);
+    const m = (1 - gNorm - k) / (1 - k);
+    const y = (1 - bNorm - k) / (1 - k);
+    return [c, m, y, k];
+}
+/**
+ * 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 function cmykToRgb(c, m, y, k) {
+    // Convert CMYK to RGB
+    const r = 255 * (1 - c) * (1 - k);
+    const g = 255 * (1 - m) * (1 - k);
+    const b = 255 * (1 - y) * (1 - k);
+    return [
+        Math.round(Math.max(0, Math.min(255, r))),
+        Math.round(Math.max(0, Math.min(255, g))),
+        Math.round(Math.max(0, Math.min(255, b))),
+    ];
+}
+/**
+ * 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 function rgbaToCmyk(data) {
+    const pixelCount = data.length / 4;
+    const result = new Float32Array(pixelCount * 4);
+    for (let i = 0; i < data.length; i += 4) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        const [c, m, y, k] = rgbToCmyk(r, g, b);
+        const outIdx = (i / 4) * 4;
+        result[outIdx] = c;
+        result[outIdx + 1] = m;
+        result[outIdx + 2] = y;
+        result[outIdx + 3] = k;
+    }
+    return result;
+}
+/**
+ * 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 function cmykToRgba(cmykData, alpha = 255) {
+    const pixelCount = cmykData.length / 4;
+    const result = new Uint8Array(pixelCount * 4);
+    for (let i = 0; i < cmykData.length; i += 4) {
+        const c = cmykData[i];
+        const m = cmykData[i + 1];
+        const y = cmykData[i + 2];
+        const k = cmykData[i + 3];
+        const [r, g, b] = cmykToRgb(c, m, y, k);
+        const outIdx = i;
+        result[outIdx] = r;
+        result[outIdx + 1] = g;
+        result[outIdx + 2] = b;
+        result[outIdx + 3] = alpha;
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-image",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A pure JavaScript, dependency-free, cross-runtime image processing library for Deno, Node.js, and Bun.",
   "keywords": [
     "image",

package/script/mod.d.ts

@@ -43,7 +43,7 @@
  * ```
  */
 export { Image } from "./src/image.js";
-export type { ASCIIEncoderOptions, FrameMetadata, ImageData, ImageDecoderOptions, ImageFormat, ImageFrame, ImageMetadata, JPEGEncoderOptions, MultiFrameImageData, ResizeOptions, TIFFEncoderOptions, WebPEncoderOptions, } from "./src/types.js";
+export type { APNGEncoderOptions, ASCIIEncoderOptions, AVIFEncoderOptions, FrameMetadata, GIFEncoderOptions, HEICEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageFrame, ImageMetadata, JPEGEncoderOptions, MultiFrameImageData, PNGEncoderOptions, ResizeOptions, TIFFEncoderOptions, WebPEncoderOptions, } from "./src/types.js";
 export { PNGFormat } from "./src/formats/png.js";
 export { APNGFormat } from "./src/formats/apng.js";
 export { JPEGFormat } from "./src/formats/jpeg.js";
@@ -59,4 +59,6 @@ export { PPMFormat } from "./src/formats/ppm.js";
 export { ASCIIFormat } from "./src/formats/ascii.js";
 export { HEICFormat } from "./src/formats/heic.js";
 export { AVIFFormat } from "./src/formats/avif.js";
+export { decodeBase64, encodeBase64, parseDataUrl, toDataUrl } from "./src/utils/base64.js";
+export { cmykToRgb, cmykToRgba, rgbaToCmyk, rgbToCmyk } from "./src/utils/image_processing.js";
 //# sourceMappingURL=mod.d.ts.map

package/script/mod.js

@@ -44,7 +44,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AVIFFormat = exports.HEICFormat = exports.ASCIIFormat = exports.PPMFormat = exports.PCXFormat = exports.PAMFormat = exports.DNGFormat = exports.ICOFormat = exports.BMPFormat = exports.TIFFFormat = exports.GIFFormat = exports.WebPFormat = exports.JPEGFormat = exports.APNGFormat = exports.PNGFormat = exports.Image = void 0;
+exports.rgbToCmyk = exports.rgbaToCmyk = exports.cmykToRgba = exports.cmykToRgb = exports.toDataUrl = exports.parseDataUrl = exports.encodeBase64 = exports.decodeBase64 = exports.AVIFFormat = exports.HEICFormat = exports.ASCIIFormat = exports.PPMFormat = exports.PCXFormat = exports.PAMFormat = exports.DNGFormat = exports.ICOFormat = exports.BMPFormat = exports.TIFFFormat = exports.GIFFormat = exports.WebPFormat = exports.JPEGFormat = exports.APNGFormat = exports.PNGFormat = exports.Image = void 0;
 var image_js_1 = require("./src/image.js");
 Object.defineProperty(exports, "Image", { enumerable: true, get: function () { return image_js_1.Image; } });
 var png_js_1 = require("./src/formats/png.js");
@@ -77,3 +77,13 @@ var heic_js_1 = require("./src/formats/heic.js");
 Object.defineProperty(exports, "HEICFormat", { enumerable: true, get: function () { return heic_js_1.HEICFormat; } });
 var avif_js_1 = require("./src/formats/avif.js");
 Object.defineProperty(exports, "AVIFFormat", { enumerable: true, get: function () { return avif_js_1.AVIFFormat; } });
+var base64_js_1 = require("./src/utils/base64.js");
+Object.defineProperty(exports, "decodeBase64", { enumerable: true, get: function () { return base64_js_1.decodeBase64; } });
+Object.defineProperty(exports, "encodeBase64", { enumerable: true, get: function () { return base64_js_1.encodeBase64; } });
+Object.defineProperty(exports, "parseDataUrl", { enumerable: true, get: function () { return base64_js_1.parseDataUrl; } });
+Object.defineProperty(exports, "toDataUrl", { enumerable: true, get: function () { return base64_js_1.toDataUrl; } });
+var image_processing_js_1 = require("./src/utils/image_processing.js");
+Object.defineProperty(exports, "cmykToRgb", { enumerable: true, get: function () { return image_processing_js_1.cmykToRgb; } });
+Object.defineProperty(exports, "cmykToRgba", { enumerable: true, get: function () { return image_processing_js_1.cmykToRgba; } });
+Object.defineProperty(exports, "rgbaToCmyk", { enumerable: true, get: function () { return image_processing_js_1.rgbaToCmyk; } });
+Object.defineProperty(exports, "rgbToCmyk", { enumerable: true, get: function () { return image_processing_js_1.rgbToCmyk; } });

package/script/src/formats/apng.d.ts

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
+import type { APNGEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
 import { PNGBase } from "./png_base.js";
 /**
  * APNG (Animated PNG) format handler
@@ -36,15 +36,17 @@ export declare class APNGFormat extends PNGBase implements ImageFormat {
     /**
      * Encode RGBA image data to APNG format (single frame)
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: APNGEncoderOptions): Promise<Uint8Array>;
     /**
      * Encode multi-frame image data to APNG format
      * @param imageData Multi-frame image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    encodeFrames(imageData: MultiFrameImageData, _options?: unknown): Promise<Uint8Array>;
+    encodeFrames(imageData: MultiFrameImageData, options?: APNGEncoderOptions): Promise<Uint8Array>;
     private decodeFrameData;
     /**
      * Get the list of metadata fields supported by APNG format

package/script/src/formats/apng.js

@@ -253,9 +253,10 @@ class APNGFormat extends png_base_js_1.PNGBase {
     /**
      * Encode RGBA image data to APNG format (single frame)
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    encode(imageData, _options) {
+    encode(imageData, options) {
         // For single frame, create a multi-frame with one frame
         const multiFrame = {
             width: imageData.width,
@@ -268,15 +269,21 @@ class APNGFormat extends png_base_js_1.PNGBase {
                 }],
             metadata: imageData.metadata,
         };
-        return this.encodeFrames(multiFrame, _options);
+        return this.encodeFrames(multiFrame, options);
     }
     /**
      * Encode multi-frame image data to APNG format
      * @param imageData Multi-frame image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    async encodeFrames(imageData, _options) {
+    async encodeFrames(imageData, options) {
         const { width, height, frames, metadata } = imageData;
+        const compressionLevel = options?.compressionLevel ?? 6;
+        // Validate compression level
+        if (compressionLevel < 0 || compressionLevel > 9) {
+            throw new Error("Compression level must be between 0 and 9");
+        }
         if (frames.length === 0) {
             throw new Error("No frames to encode");
         }
@@ -334,7 +341,7 @@ class APNGFormat extends png_base_js_1.PNGBase {
             fctl[25] = 0; // blend_op: APNG_BLEND_OP_SOURCE
             chunks.push(this.createChunk("fcTL", fctl));
             // Filter and compress frame data
-            const filtered = this.filterData(frame.data, frame.width, frame.height);
+            const filtered = this.filterData(frame.data, frame.width, frame.height, compressionLevel);
             const compressed = await this.deflate(filtered);
             if (i === 0) {
                 // First frame uses IDAT

package/script/src/formats/avif.d.ts

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
+import type { AVIFEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
 /**
  * AVIF format handler
  * Supports AVIF images using runtime APIs (ImageDecoder/OffscreenCanvas)
@@ -32,7 +32,7 @@ export declare class AVIFFormat implements ImageFormat {
      * @param imageData Image data to encode
      * @returns Encoded AVIF image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: AVIFEncoderOptions): Promise<Uint8Array>;
     /**
      * Decode using runtime APIs
      * @param data Raw AVIF data

package/script/src/formats/avif.js

@@ -82,8 +82,9 @@ class AVIFFormat {
      * @param imageData Image data to encode
      * @returns Encoded AVIF image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata: _metadata } = imageData;
+        const requestedQuality = options?.quality;
         // Try to use runtime encoding if available
         if (typeof OffscreenCanvas !== "undefined") {
             try {
@@ -94,10 +95,19 @@ class AVIFFormat {
                     const imgDataData = new Uint8ClampedArray(data);
                     imgData.data.set(imgDataData);
                     ctx.putImageData(imgData, 0, 0);
+                    const quality = requestedQuality === undefined
+                        ? undefined
+                        : (requestedQuality <= 1
+                            ? Math.max(0, Math.min(1, requestedQuality))
+                            : Math.max(1, Math.min(100, requestedQuality)) / 100);
                     // Try to encode as AVIF
                     const blob = await canvas.convertToBlob({
                         type: "image/avif",
+                        ...(quality === undefined ? {} : { quality }),
                     });
+                    if (blob.type !== "image/avif") {
+                        throw new Error(`Runtime did not encode AVIF (got '${blob.type || "(empty)"}')`);
+                    }
                     const arrayBuffer = await blob.arrayBuffer();
                     const encoded = new Uint8Array(arrayBuffer);
                     // Note: Metadata injection for AVIF is complex and would require

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

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
+import type { GIFEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
 /**
  * GIF format handler
  * Now includes pure-JS implementation with custom LZW compression/decompression
@@ -39,7 +39,7 @@ export declare class GIFFormat implements ImageFormat {
      * @param imageData Image data to encode
      * @returns Encoded GIF image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: GIFEncoderOptions): Promise<Uint8Array>;
     /**
      * Decode all frames from an animated GIF
      */
@@ -47,7 +47,7 @@ export declare class GIFFormat implements ImageFormat {
     /**
      * Encode multi-frame image data to animated GIF
      */
-    encodeFrames(imageData: MultiFrameImageData, _options?: unknown): Promise<Uint8Array>;
+    encodeFrames(imageData: MultiFrameImageData, options?: GIFEncoderOptions): Promise<Uint8Array>;
     private mapDisposalMethod;
     private decodeUsingRuntime;
     private readDataSubBlocks;

package/script/src/formats/gif.js

@@ -156,12 +156,12 @@ class GIFFormat {
      * @param imageData Image data to encode
      * @returns Encoded GIF image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata } = imageData;
         // Try pure-JS encoder first
         try {
             const encoder = new gif_encoder_js_1.GIFEncoder(width, height, data);
-            const encoded = encoder.encode();
+            const encoded = encoder.encode(options);
             // Inject metadata if present
             if (metadata && Object.keys(metadata).length > 0) {
                 const injected = this.injectMetadata(encoded, metadata);
@@ -240,7 +240,7 @@ class GIFFormat {
     /**
      * Encode multi-frame image data to animated GIF
      */
-    encodeFrames(imageData, _options) {
+    encodeFrames(imageData, options) {
         if (imageData.frames.length === 0) {
             throw new Error("No frames to encode");
         }
@@ -250,7 +250,7 @@ class GIFFormat {
             const delay = frame.frameMetadata?.delay ?? 100;
             encoder.addFrame(frame.data, delay);
         }
-        return Promise.resolve(encoder.encode());
+        return Promise.resolve(encoder.encode(options));
     }
     mapDisposalMethod(disposal) {
         switch (disposal) {

package/script/src/formats/heic.d.ts

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
+import type { HEICEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
 /**
  * HEIC format handler
  * Supports HEIC/HEIF images using runtime APIs (ImageDecoder/OffscreenCanvas)
@@ -32,7 +32,7 @@ export declare class HEICFormat implements ImageFormat {
      * @param imageData Image data to encode
      * @returns Encoded HEIC image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: HEICEncoderOptions): Promise<Uint8Array>;
     /**
      * Decode using runtime APIs
      * @param data Raw HEIC data

package/script/src/formats/heic.js

@@ -83,8 +83,9 @@ class HEICFormat {
      * @param imageData Image data to encode
      * @returns Encoded HEIC image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata: _metadata } = imageData;
+        const requestedQuality = options?.quality;
         // Try to use runtime encoding if available
         if (typeof OffscreenCanvas !== "undefined") {
             try {
@@ -95,10 +96,19 @@ class HEICFormat {
                     const imgDataData = new Uint8ClampedArray(data);
                     imgData.data.set(imgDataData);
                     ctx.putImageData(imgData, 0, 0);
+                    const quality = requestedQuality === undefined
+                        ? undefined
+                        : (requestedQuality <= 1
+                            ? Math.max(0, Math.min(1, requestedQuality))
+                            : Math.max(1, Math.min(100, requestedQuality)) / 100);
                     // Try to encode as HEIC
                     const blob = await canvas.convertToBlob({
                         type: "image/heic",
+                        ...(quality === undefined ? {} : { quality }),
                     });
+                    if (blob.type !== "image/heic") {
+                        throw new Error(`Runtime did not encode HEIC (got '${blob.type || "(empty)"}')`);
+                    }
                     const arrayBuffer = await blob.arrayBuffer();
                     const encoded = new Uint8Array(arrayBuffer);
                     // Note: Metadata injection for HEIC is complex and would require

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

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
+import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, PNGEncoderOptions } from "../types.js";
 import { PNGBase } from "./png_base.js";
 /**
  * PNG format handler
@@ -24,9 +24,10 @@ export declare class PNGFormat extends PNGBase implements ImageFormat {
     /**
      * Encode RGBA image data to PNG format
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded PNG image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: PNGEncoderOptions): Promise<Uint8Array>;
     /**
      * Get the list of metadata fields supported by PNG format
      * Delegates to PNGBase implementation

package/script/src/formats/png.js

@@ -113,10 +113,16 @@ class PNGFormat extends png_base_js_1.PNGBase {
     /**
      * Encode RGBA image data to PNG format
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded PNG image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata } = imageData;
+        const compressionLevel = options?.compressionLevel ?? 6;
+        // Validate compression level
+        if (compressionLevel < 0 || compressionLevel > 9) {
+            throw new Error("Compression level must be between 0 and 9");
+        }
         // Prepare IHDR chunk
         const ihdr = new Uint8Array(13);
         this.writeUint32(ihdr, 0, width);
@@ -127,7 +133,7 @@ class PNGFormat extends png_base_js_1.PNGBase {
         ihdr[11] = 0; // filter method
         ihdr[12] = 0; // interlace method
         // Filter and compress image data
-        const filtered = this.filterData(data, width, height);
+        const filtered = this.filterData(data, width, height, compressionLevel);
         const compressed = await this.deflate(filtered);
         // Build PNG
         const chunks = [];