From 7c23ee03eb1688b279f1f31a35f6c259a1103e23 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Mar 2026 20:41:28 +0000
Subject: [PATCH 1/4] Initial plan


From f56cae26e7d348850ed471227f12c9fa37592f64 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Mar 2026 20:55:26 +0000
Subject: [PATCH 2/4] Add PGM, PBM, and QOI image format support

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>
Agent-Logs-Url: https://github.com/cross-org/image/sessions/87a6b200-83c3-4461-8907-3df4836d773c
---
 CHANGELOG.md             |   9 +
 README.md                |   7 +-
 docs/src/formats.md      |  24 ++-
 mod.ts                   |   5 +-
 src/formats/pbm.ts       | 236 ++++++++++++++++++++++++++
 src/formats/pgm.ts       | 238 +++++++++++++++++++++++++++
 src/formats/qoi.ts       | 330 +++++++++++++++++++++++++++++++++++++
 src/image.ts             |   6 +
 test/formats/pbm.test.ts | 345 +++++++++++++++++++++++++++++++++++++++
 test/formats/pgm.test.ts | 297 +++++++++++++++++++++++++++++++++
 test/formats/qoi.test.ts | 335 +++++++++++++++++++++++++++++++++++++
 11 files changed, 1828 insertions(+), 4 deletions(-)
 create mode 100644 src/formats/pbm.ts
 create mode 100644 src/formats/pgm.ts
 create mode 100644 src/formats/qoi.ts
 create mode 100644 test/formats/pbm.test.ts
 create mode 100644 test/formats/pgm.test.ts
 create mode 100644 test/formats/qoi.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a32daeb..bd1bde3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,15 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- PGM format support (Netpbm Portable GrayMap): decode P2 (ASCII) and P5 (binary), encode as P5
+  binary with luminance-preserving grayscale conversion
+- PBM format support (Netpbm Portable BitMap): decode P1 (ASCII) and P4 (binary packed-bit), encode
+  as P4 binary with luminance threshold
+- QOI format support (Quite OK Image): full pure-JS encode and decode including all chunk types
+  (INDEX, DIFF, LUMA, RUN, RGB, RGBA)
+
 ## [0.4.3] - 2025-12-28
 
 ### Fixed
diff --git a/README.md b/README.md
index 7bb8112..0b9cc00 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,8 @@ JPEG, WebP, GIF, and more—all without native dependencies.
 - 🚀 **Pure JavaScript** - No native dependencies
 - 🔌 **Pluggable formats** - Easy to extend with custom formats
 - 📦 **Cross-runtime** - Works on Deno, Node.js (18+), Bun and Browsers.
-- 🎨 **Multiple formats** - PNG, APNG, JPEG, WebP, GIF, TIFF, BMP, ICO, DNG, PAM, PPM, PCX, ASCII,
-  HEIC, and AVIF support
+- 🎨 **Multiple formats** - PNG, APNG, JPEG, WebP, GIF, TIFF, BMP, ICO, DNG, PAM, PPM, PGM, PBM,
+  PCX, QOI, ASCII, HEIC, and AVIF support
 - ✂️ **Image manipulation** - Resize, crop, composite, and more
 - 🎛️ **Image processing** - Chainable filters including `brightness`, `contrast`, `saturation`,
   `hue`, `exposure`, `blur`, `sharpen`, `sepia`, and more
@@ -129,7 +129,10 @@ await Bun.write("output.jpg", jpeg);
 | DNG    | ✅ Full                   | Linear DNG (Uncompressed RGBA)                                                                 |
 | PAM    | ✅ Full                   | Netpbm PAM format                                                                              |
 | PPM    | ✅ Full                   | Netpbm PPM format (P3/P6)                                                                      |
+| PGM    | ✅ Full                   | Netpbm PGM format (P2/P5 grayscale)                                                            |
+| PBM    | ✅ Full                   | Netpbm PBM format (P1/P4 monochrome)                                                           |
 | PCX    | ✅ Full                   | ZSoft PCX (RLE compressed)                                                                     |
+| QOI    | ✅ Full                   | QOI — Quite OK Image (fast lossless)                                                           |
 | ASCII  | ✅ Full                   | Text-based ASCII art                                                                           |
 | JPEG   | ⚠️ Baseline & Progressive | Pure-JS baseline & progressive DCT: decode with spectral selection; encode with 2-scan (DC+AC) |
 | WebP   | ⚠️ Lossless               | Pure-JS lossless VP8L                                                                          |
diff --git a/docs/src/formats.md b/docs/src/formats.md
index 416b70a..d6b6706 100644
--- a/docs/src/formats.md
+++ b/docs/src/formats.md
@@ -21,7 +21,10 @@ This table shows which image formats are supported and their implementation stat
 | DNG    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | Linear DNG (Uncompressed RGBA)                                                                                                                  |
 | PAM    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | Netpbm PAM (Portable Arbitrary Map)                                                                                                             |
 | PPM    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | Netpbm PPM (Portable PixMap) P3/P6 formats                                                                                                      |
+| PGM    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | Netpbm PGM (Portable GrayMap) P2/P5 formats                                                                                                     |
+| PBM    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | Netpbm PBM (Portable BitMap) P1/P4 formats                                                                                                      |
 | PCX    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | ZSoft PCX (RLE compressed)                                                                                                                      |
+| QOI    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | Quite OK Image — fast lossless format                                                                                                           |
 | ASCII  | ✅   | ✅    | ✅ Full                   | ✅ Full                   | N/A               | N/A                | Text-based ASCII art representation                                                                                                             |
 | JPEG   | ✅   | ✅    | ⚠️ Baseline & Progressive | ⚠️ Baseline & Progressive | ✅ ImageDecoder   | ✅ OffscreenCanvas | Pure-JS decode: baseline & progressive (spectral selection + successive approximation). Encode: baseline (native) + basic progressive (pure-JS) |
 | GIF    | ✅   | ✅    | ✅ Full                   | ✅ Full                   | ✅ ImageDecoder   | ✅ OffscreenCanvas | Complete pure-JS implementation                                                                                                                 |
@@ -100,6 +103,22 @@ This table shows which format standards and variants are supported:
 |        | - P6 (Binary) format                 | ✅ Full           | Pure-JS        |
 |        | - Comments in header                 | ✅ Full           | Pure-JS        |
 |        | - Maxval scaling (1-255)             | ✅ Full           | Pure-JS        |
+| PGM    | Netpbm PGM (Portable GrayMap)        | ✅ Full           | Pure-JS        |
+|        | - P2 (ASCII) format                  | ✅ Full           | Pure-JS        |
+|        | - P5 (Binary) format                 | ✅ Full           | Pure-JS        |
+|        | - Comments in header                 | ✅ Full           | Pure-JS        |
+|        | - Maxval scaling (1-255)             | ✅ Full           | Pure-JS        |
+|        | - Encode: RGB to grayscale via luma  | ✅ Full           | Pure-JS        |
+| PBM    | Netpbm PBM (Portable BitMap)         | ✅ Full           | Pure-JS        |
+|        | - P1 (ASCII) format                  | ✅ Full           | Pure-JS        |
+|        | - P4 (Binary) format, packed bits    | ✅ Full           | Pure-JS        |
+|        | - Row padding to byte boundary       | ✅ Full           | Pure-JS        |
+|        | - Encode: luma threshold at 128      | ✅ Full           | Pure-JS        |
+| QOI    | QOI (Quite OK Image)                 | ✅ Full           | Pure-JS        |
+|        | - RGBA channels                      | ✅ Full           | Pure-JS        |
+|        | - RUN encoding                       | ✅ Full           | Pure-JS        |
+|        | - INDEX (color cache)                | ✅ Full           | Pure-JS        |
+|        | - DIFF / LUMA delta encoding         | ✅ Full           | Pure-JS        |
 | PCX    | ZSoft PCX Version 5 (3.0)            | ✅ Full           | Pure-JS        |
 |        | - 24-bit RGB (3 planes)              | ✅ Full           | Pure-JS        |
 |        | - 8-bit Palette (1 plane)            | ✅ Decode only    | Pure-JS        |
@@ -126,7 +145,10 @@ This table shows which format standards and variants are supported:
 | DNG    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
 | PAM    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
 | PPM    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
+| PGM    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
+| PBM    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
 | PCX    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
+| QOI    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
 | ASCII  | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
 | GIF    | ✅       | ✅          | ✅          | ✅  | Pure-JS works everywhere                                           |
 | JPEG   | ✅       | ✅          | ✅          | ✅  | Pure-JS baseline & progressive DCT with spectral selection         |
@@ -136,7 +158,7 @@ This table shows which format standards and variants are supported:
 | AVIF   | ✅       | ⚠️ Runtime  | ✅          | ✅  | Requires ImageDecoder API support                                  |
 
 **Note**: For maximum compatibility across all runtimes, use PNG, APNG, BMP, ICO, GIF, ASCII, PCX,
-PPM or DNG formats which have complete pure-JS implementations.
+PPM, PGM, PBM, QOI or DNG formats which have complete pure-JS implementations.
 
 ## Implementation Details
 
diff --git a/mod.ts b/mod.ts
index cb767d5..de1fcb4 100644
--- a/mod.ts
+++ b/mod.ts
@@ -2,7 +2,7 @@
  * @module @cross/image
  *
  * A pure JavaScript, dependency-free, cross-runtime image processing library.
- * Supports decoding, resizing, and encoding common image formats (PNG, APNG, JPEG, WebP, GIF, TIFF, BMP, ICO, DNG, PAM, PPM, PCX).
+ * Supports decoding, resizing, and encoding common image formats (PNG, APNG, JPEG, WebP, GIF, TIFF, BMP, ICO, DNG, PAM, PPM, PGM, PBM, PCX, QOI).
  * Includes image processing capabilities like compositing, level adjustments, and pixel manipulation.
  *
  * @example
@@ -81,6 +81,9 @@ export { DNGFormat } from "./src/formats/dng.ts";
 export { PAMFormat } from "./src/formats/pam.ts";
 export { PCXFormat } from "./src/formats/pcx.ts";
 export { PPMFormat } from "./src/formats/ppm.ts";
+export { PGMFormat } from "./src/formats/pgm.ts";
+export { PBMFormat } from "./src/formats/pbm.ts";
+export { QOIFormat } from "./src/formats/qoi.ts";
 export { ASCIIFormat } from "./src/formats/ascii.ts";
 export { HEICFormat } from "./src/formats/heic.ts";
 export { AVIFFormat } from "./src/formats/avif.ts";
diff --git a/src/formats/pbm.ts b/src/formats/pbm.ts
new file mode 100644
index 0000000..9bb2bd2
--- /dev/null
+++ b/src/formats/pbm.ts
@@ -0,0 +1,236 @@
+import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.ts";
+import { validateImageDimensions } from "../utils/security.ts";
+
+/**
+ * PBM format handler
+ * Implements the Netpbm PBM (Portable BitMap) format.
+ * Supports both P1 (ASCII) and P4 (binary) variants.
+ *
+ * In PBM, 0 = white and 1 = black (the opposite of most image formats).
+ *
+ * Format structure:
+ * - P1 (ASCII format):
+ *   P1
+ *   <width> <height>
+ *   0 1 0 1 ... (0=white, 1=black)
+ *
+ * - P4 (Binary format):
+ *   P4
+ *   <width> <height>
+ *   <packed bits: 1 bit per pixel, MSB first, rows padded to byte boundary>
+ */
+export class PBMFormat implements ImageFormat {
+  /** Format name identifier */
+  readonly name = "pbm";
+  /** MIME type for PBM images */
+  readonly mimeType = "image/x-portable-bitmap";
+
+  /**
+   * Check if the given data is a PBM image
+   * @param data Raw image data to check
+   * @returns true if data has PBM signature (P1 or P4)
+   */
+  canDecode(data: Uint8Array): boolean {
+    if (data.length < 3) return false;
+    return (
+      data[0] === 0x50 && // P
+      (data[1] === 0x31 || data[1] === 0x34) && // 1 or 4
+      (data[2] === 0x0a || data[2] === 0x0d || data[2] === 0x20 || data[2] === 0x09)
+    );
+  }
+
+  /**
+   * Decode PBM image data to RGBA
+   * Supports both P1 (ASCII) and P4 (binary) formats
+   * @param data Raw PBM image data
+   * @returns Decoded image data with RGBA pixels (0=white 255,255,255, 1=black 0,0,0)
+   */
+  decode(data: Uint8Array, _options?: ImageDecoderOptions): Promise<ImageData> {
+    if (!this.canDecode(data)) {
+      throw new Error("Invalid PBM signature");
+    }
+
+    const isBinary = data[1] === 0x34; // P4
+
+    let offset = 2;
+    let width = 0;
+    let height = 0;
+    let headerValues = 0;
+
+    while (offset < data.length && this.isWhitespace(data[offset])) offset++;
+
+    while (headerValues < 2 && offset < data.length) {
+      if (data[offset] === 0x23) { // #
+        while (offset < data.length && data[offset] !== 0x0a) offset++;
+        if (offset < data.length) offset++;
+        continue;
+      }
+
+      while (offset < data.length && this.isWhitespace(data[offset])) offset++;
+
+      let numStr = "";
+      while (
+        offset < data.length &&
+        !this.isWhitespace(data[offset]) &&
+        data[offset] !== 0x23
+      ) {
+        numStr += String.fromCharCode(data[offset]);
+        offset++;
+      }
+
+      if (numStr) {
+        const num = parseInt(numStr, 10);
+        if (isNaN(num) || num <= 0) {
+          throw new Error(`Invalid PBM header value: ${numStr}`);
+        }
+        if (headerValues === 0) width = num;
+        else if (headerValues === 1) height = num;
+        headerValues++;
+      }
+    }
+
+    if (headerValues < 2) {
+      throw new Error("Incomplete PBM header");
+    }
+
+    if (offset < data.length && this.isWhitespace(data[offset])) offset++;
+
+    validateImageDimensions(width, height);
+
+    const pixelCount = width * height;
+    const rgba = new Uint8Array(pixelCount * 4);
+
+    if (isBinary) {
+      // P4: packed bits, 1 bit per pixel, rows padded to byte boundary, MSB first
+      const rowBytes = Math.ceil(width / 8);
+      const expectedDataLength = rowBytes * height;
+      if (data.length - offset < expectedDataLength) {
+        throw new Error(
+          `Invalid PBM data length: expected ${expectedDataLength}, got ${data.length - offset}`,
+        );
+      }
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          const byteIndex = offset + y * rowBytes + Math.floor(x / 8);
+          const bitIndex = 7 - (x % 8);
+          const bit = (data[byteIndex] >> bitIndex) & 1;
+          const i = (y * width + x) * 4;
+          const v = bit ? 0 : 255; // 1=black, 0=white
+          rgba[i] = v;
+          rgba[i + 1] = v;
+          rgba[i + 2] = v;
+          rgba[i + 3] = 255;
+        }
+      }
+    } else {
+      // P1: ASCII format, values are '0' or '1' separated by whitespace
+      let pixelIndex = 0;
+      while (pixelIndex < pixelCount && offset < data.length) {
+        while (offset < data.length) {
+          if (data[offset] === 0x23) {
+            while (offset < data.length && data[offset] !== 0x0a) offset++;
+            if (offset < data.length) offset++;
+          } else if (this.isWhitespace(data[offset])) {
+            offset++;
+          } else {
+            break;
+          }
+        }
+        if (offset >= data.length) break;
+
+        const ch = data[offset];
+        if (ch !== 0x30 && ch !== 0x31) { // '0' or '1'
+          throw new Error(`Invalid PBM pixel value at offset ${offset}`);
+        }
+        const bit = ch - 0x30;
+        offset++;
+
+        const v = bit ? 0 : 255;
+        rgba[pixelIndex * 4] = v;
+        rgba[pixelIndex * 4 + 1] = v;
+        rgba[pixelIndex * 4 + 2] = v;
+        rgba[pixelIndex * 4 + 3] = 255;
+        pixelIndex++;
+      }
+
+      if (pixelIndex < pixelCount) {
+        throw new Error(
+          `Incomplete PBM pixel data: expected ${pixelCount} values, got ${pixelIndex}`,
+        );
+      }
+    }
+
+    return Promise.resolve({ width, height, data: rgba });
+  }
+
+  /**
+   * Encode RGBA image data to PBM format (P4 binary)
+   * Converts to monochrome using standard luminance threshold (128)
+   * Note: Alpha channel is ignored during encoding
+   * @param imageData Image data to encode
+   * @returns Encoded PBM image bytes
+   */
+  encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array> {
+    const { width, height, data } = imageData;
+
+    if (data.length !== width * height * 4) {
+      throw new Error(
+        `Data length mismatch: expected ${width * height * 4}, got ${data.length}`,
+      );
+    }
+
+    const header = `P4\n${width} ${height}\n`;
+    const encoder = new TextEncoder();
+    const headerBytes = encoder.encode(header);
+
+    const rowBytes = Math.ceil(width / 8);
+    const output = new Uint8Array(headerBytes.length + rowBytes * height);
+    output.set(headerBytes, 0);
+
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const si = (y * width + x) * 4;
+        const gray = Math.round(
+          0.299 * data[si] + 0.587 * data[si + 1] + 0.114 * data[si + 2],
+        );
+        // dark pixels become 1 (black in PBM), bright pixels become 0 (white)
+        const bit = gray < 128 ? 1 : 0;
+        const byteIndex = headerBytes.length + y * rowBytes + Math.floor(x / 8);
+        const bitPosition = 7 - (x % 8);
+        output[byteIndex] |= bit << bitPosition;
+      }
+    }
+
+    return Promise.resolve(output);
+  }
+
+  /**
+   * Check if a byte is whitespace (space, tab, CR, LF)
+   */
+  private isWhitespace(byte: number): boolean {
+    return byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d;
+  }
+
+  /**
+   * Get the list of metadata fields supported by PBM format
+   */
+  getSupportedMetadata(): Array<keyof ImageMetadata> {
+    return [];
+  }
+
+  /**
+   * Extract metadata from PBM data without fully decoding the pixel data
+   * @param data Raw PBM data
+   * @returns Extracted metadata or undefined
+   */
+  extractMetadata(data: Uint8Array): Promise<ImageMetadata | undefined> {
+    if (!this.canDecode(data)) return Promise.resolve(undefined);
+    return Promise.resolve({
+      format: "pbm",
+      compression: "none",
+      frameCount: 1,
+      bitDepth: 1,
+      colorType: "grayscale",
+    });
+  }
+}
diff --git a/src/formats/pgm.ts b/src/formats/pgm.ts
new file mode 100644
index 0000000..c7426cc
--- /dev/null
+++ b/src/formats/pgm.ts
@@ -0,0 +1,238 @@
+import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.ts";
+import { validateImageDimensions } from "../utils/security.ts";
+
+/**
+ * PGM format handler
+ * Implements the Netpbm PGM (Portable GrayMap) format.
+ * Supports both P2 (ASCII) and P5 (binary) variants.
+ *
+ * Format structure:
+ * - P2 (ASCII format):
+ *   P2
+ *   <width> <height>
+ *   <maxval>
+ *   V V V ... (space-separated decimal grayscale values, 0=black, maxval=white)
+ *
+ * - P5 (Binary format):
+ *   P5
+ *   <width> <height>
+ *   <maxval>
+ *   <binary 8-bit grayscale data>
+ */
+export class PGMFormat implements ImageFormat {
+  /** Format name identifier */
+  readonly name = "pgm";
+  /** MIME type for PGM images */
+  readonly mimeType = "image/x-portable-graymap";
+
+  /**
+   * Check if the given data is a PGM image
+   * @param data Raw image data to check
+   * @returns true if data has PGM signature (P2 or P5)
+   */
+  canDecode(data: Uint8Array): boolean {
+    if (data.length < 3) return false;
+    return (
+      data[0] === 0x50 && // P
+      (data[1] === 0x32 || data[1] === 0x35) && // 2 or 5
+      (data[2] === 0x0a || data[2] === 0x0d || data[2] === 0x20 || data[2] === 0x09)
+    );
+  }
+
+  /**
+   * Decode PGM image data to RGBA
+   * Supports both P2 (ASCII) and P5 (binary) formats
+   * @param data Raw PGM image data
+   * @returns Decoded image data with RGBA pixels (grayscale expanded to RGB with A=255)
+   */
+  decode(data: Uint8Array, _options?: ImageDecoderOptions): Promise<ImageData> {
+    if (!this.canDecode(data)) {
+      throw new Error("Invalid PGM signature");
+    }
+
+    const isBinary = data[1] === 0x35; // P5
+
+    let offset = 2;
+    let width = 0;
+    let height = 0;
+    let maxval = 0;
+    let headerValues = 0;
+
+    while (offset < data.length && this.isWhitespace(data[offset])) offset++;
+
+    while (headerValues < 3 && offset < data.length) {
+      if (data[offset] === 0x23) { // #
+        while (offset < data.length && data[offset] !== 0x0a) offset++;
+        if (offset < data.length) offset++;
+        continue;
+      }
+
+      while (offset < data.length && this.isWhitespace(data[offset])) offset++;
+
+      let numStr = "";
+      while (
+        offset < data.length &&
+        !this.isWhitespace(data[offset]) &&
+        data[offset] !== 0x23
+      ) {
+        numStr += String.fromCharCode(data[offset]);
+        offset++;
+      }
+
+      if (numStr) {
+        const num = parseInt(numStr, 10);
+        if (isNaN(num) || num <= 0) {
+          throw new Error(`Invalid PGM header value: ${numStr}`);
+        }
+        if (headerValues === 0) width = num;
+        else if (headerValues === 1) height = num;
+        else if (headerValues === 2) maxval = num;
+        headerValues++;
+      }
+    }
+
+    if (headerValues < 3) {
+      throw new Error("Incomplete PGM header");
+    }
+
+    if (offset < data.length && this.isWhitespace(data[offset])) offset++;
+
+    validateImageDimensions(width, height);
+
+    if (maxval > 255) {
+      throw new Error(
+        `Unsupported PGM maxval: ${maxval}. Only maxval <= 255 is supported.`,
+      );
+    }
+
+    const pixelCount = width * height;
+    const rgba = new Uint8Array(pixelCount * 4);
+
+    if (isBinary) {
+      // P5: binary format, 1 byte per pixel
+      if (data.length - offset < pixelCount) {
+        throw new Error(
+          `Invalid PGM data length: expected ${pixelCount}, got ${data.length - offset}`,
+        );
+      }
+      for (let i = 0; i < pixelCount; i++) {
+        const v = maxval === 255 ? data[offset + i] : Math.round((data[offset + i] * 255) / maxval);
+        rgba[i * 4] = v;
+        rgba[i * 4 + 1] = v;
+        rgba[i * 4 + 2] = v;
+        rgba[i * 4 + 3] = 255;
+      }
+    } else {
+      // P2: ASCII format
+      let pixelIndex = 0;
+      while (pixelIndex < pixelCount && offset < data.length) {
+        while (offset < data.length) {
+          if (data[offset] === 0x23) {
+            while (offset < data.length && data[offset] !== 0x0a) offset++;
+            if (offset < data.length) offset++;
+          } else if (this.isWhitespace(data[offset])) {
+            offset++;
+          } else {
+            break;
+          }
+        }
+
+        let numStr = "";
+        while (
+          offset < data.length &&
+          !this.isWhitespace(data[offset]) &&
+          data[offset] !== 0x23
+        ) {
+          numStr += String.fromCharCode(data[offset]);
+          offset++;
+        }
+
+        if (numStr) {
+          const value = parseInt(numStr, 10);
+          if (isNaN(value) || value < 0 || value > maxval) {
+            throw new Error(`Invalid PGM pixel value: ${numStr}`);
+          }
+          const v = maxval === 255 ? value : Math.round((value * 255) / maxval);
+          rgba[pixelIndex * 4] = v;
+          rgba[pixelIndex * 4 + 1] = v;
+          rgba[pixelIndex * 4 + 2] = v;
+          rgba[pixelIndex * 4 + 3] = 255;
+          pixelIndex++;
+        }
+      }
+
+      if (pixelIndex < pixelCount) {
+        throw new Error(
+          `Incomplete PGM pixel data: expected ${pixelCount} values, got ${pixelIndex}`,
+        );
+      }
+    }
+
+    return Promise.resolve({ width, height, data: rgba });
+  }
+
+  /**
+   * Encode RGBA image data to PGM format (P5 binary)
+   * Converts to grayscale using standard luminance formula
+   * @param imageData Image data to encode
+   * @returns Encoded PGM image bytes
+   */
+  encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array> {
+    const { width, height, data } = imageData;
+
+    if (data.length !== width * height * 4) {
+      throw new Error(
+        `Data length mismatch: expected ${width * height * 4}, got ${data.length}`,
+      );
+    }
+
+    const header = `P5\n${width} ${height}\n255\n`;
+    const encoder = new TextEncoder();
+    const headerBytes = encoder.encode(header);
+
+    const pixelCount = width * height;
+    const output = new Uint8Array(headerBytes.length + pixelCount);
+    output.set(headerBytes, 0);
+
+    let outputOffset = headerBytes.length;
+    for (let i = 0; i < pixelCount; i++) {
+      const si = i * 4;
+      // Standard luminance-preserving grayscale conversion
+      output[outputOffset++] = Math.round(
+        0.299 * data[si] + 0.587 * data[si + 1] + 0.114 * data[si + 2],
+      );
+    }
+
+    return Promise.resolve(output);
+  }
+
+  /**
+   * Check if a byte is whitespace (space, tab, CR, LF)
+   */
+  private isWhitespace(byte: number): boolean {
+    return byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d;
+  }
+
+  /**
+   * Get the list of metadata fields supported by PGM format
+   */
+  getSupportedMetadata(): Array<keyof ImageMetadata> {
+    return [];
+  }
+
+  /**
+   * Extract metadata from PGM data without fully decoding the pixel data
+   * @param data Raw PGM data
+   * @returns Extracted metadata or undefined
+   */
+  extractMetadata(data: Uint8Array): Promise<ImageMetadata | undefined> {
+    if (!this.canDecode(data)) return Promise.resolve(undefined);
+    return Promise.resolve({
+      format: "pgm",
+      compression: "none",
+      frameCount: 1,
+      bitDepth: 8,
+      colorType: "grayscale",
+    });
+  }
+}
diff --git a/src/formats/qoi.ts b/src/formats/qoi.ts
new file mode 100644
index 0000000..f5598f6
--- /dev/null
+++ b/src/formats/qoi.ts
@@ -0,0 +1,330 @@
+import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.ts";
+import { validateImageDimensions } from "../utils/security.ts";
+
+// QOI magic bytes: "qoif"
+const QOI_MAGIC_0 = 0x71; // q
+const QOI_MAGIC_1 = 0x6f; // o
+const QOI_MAGIC_2 = 0x69; // i
+const QOI_MAGIC_3 = 0x66; // f
+
+// QOI chunk tags (top 2 bits)
+const QOI_OP_INDEX = 0x00; // 00xxxxxx
+const QOI_OP_DIFF = 0x40; // 01xxxxxx
+const QOI_OP_LUMA = 0x80; // 10xxxxxx
+const QOI_OP_RUN = 0xc0; // 11xxxxxx
+
+// QOI special 8-bit tags
+const QOI_OP_RGB = 0xfe; // 11111110
+const QOI_OP_RGBA = 0xff; // 11111111
+
+/**
+ * Compute the QOI running color array hash index for a pixel
+ */
+function qoiHash(r: number, g: number, b: number, a: number): number {
+  return (r * 3 + g * 5 + b * 7 + a * 11) % 64;
+}
+
+/**
+ * QOI format handler
+ * Implements the QOI (Quite OK Image) format — a fast, lossless image format.
+ * https://qoiformat.org/
+ *
+ * Format structure:
+ * - Header (14 bytes):
+ *   magic: "qoif" (4 bytes)
+ *   width: uint32 big-endian
+ *   height: uint32 big-endian
+ *   channels: uint8 (3=RGB, 4=RGBA)
+ *   colorspace: uint8 (0=sRGB with linear alpha, 1=all channels linear)
+ * - Pixel data: sequence of QOI chunks (variable length)
+ * - End marker: 8 bytes [0x00 × 7, 0x01]
+ */
+export class QOIFormat implements ImageFormat {
+  /** Format name identifier */
+  readonly name = "qoi";
+  /** MIME type for QOI images */
+  readonly mimeType = "image/qoi";
+
+  /**
+   * Check if the given data is a QOI image
+   * @param data Raw image data to check
+   * @returns true if data has QOI signature ("qoif")
+   */
+  canDecode(data: Uint8Array): boolean {
+    return (
+      data.length >= 14 &&
+      data[0] === QOI_MAGIC_0 &&
+      data[1] === QOI_MAGIC_1 &&
+      data[2] === QOI_MAGIC_2 &&
+      data[3] === QOI_MAGIC_3
+    );
+  }
+
+  /**
+   * Decode QOI image data to RGBA
+   * @param data Raw QOI image data
+   * @returns Decoded image data with RGBA pixels
+   */
+  decode(data: Uint8Array, _options?: ImageDecoderOptions): Promise<ImageData> {
+    if (!this.canDecode(data)) {
+      throw new Error("Invalid QOI signature");
+    }
+
+    // Parse header (big-endian)
+    const width = ((data[4] << 24) | (data[5] << 16) | (data[6] << 8) | data[7]) >>> 0;
+    const height = ((data[8] << 24) | (data[9] << 16) | (data[10] << 8) | data[11]) >>> 0;
+    const channels = data[12]; // 3=RGB, 4=RGBA
+    // data[13] = colorspace (informational only, not used for decoding)
+
+    validateImageDimensions(width, height);
+
+    if (channels !== 3 && channels !== 4) {
+      throw new Error(`Unsupported QOI channels: ${channels}`);
+    }
+
+    const pixelCount = width * height;
+    const rgba = new Uint8Array(pixelCount * 4);
+
+    // Running color array: 64 entries × 4 bytes (RGBA), initialized to zero
+    const colorArray = new Uint8Array(64 * 4);
+
+    let r = 0, g = 0, b = 0, a = 255;
+    let offset = 14;
+    let pixelIndex = 0;
+
+    // Reserve 8 bytes for end marker at tail
+    const dataEnd = data.length - 8;
+
+    while (pixelIndex < pixelCount && offset < dataEnd) {
+      const byte = data[offset++];
+
+      if (byte === QOI_OP_RGB) {
+        r = data[offset++];
+        g = data[offset++];
+        b = data[offset++];
+        // a unchanged
+        const hash = qoiHash(r, g, b, a);
+        colorArray[hash * 4] = r;
+        colorArray[hash * 4 + 1] = g;
+        colorArray[hash * 4 + 2] = b;
+        colorArray[hash * 4 + 3] = a;
+      } else if (byte === QOI_OP_RGBA) {
+        r = data[offset++];
+        g = data[offset++];
+        b = data[offset++];
+        a = data[offset++];
+        const hash = qoiHash(r, g, b, a);
+        colorArray[hash * 4] = r;
+        colorArray[hash * 4 + 1] = g;
+        colorArray[hash * 4 + 2] = b;
+        colorArray[hash * 4 + 3] = a;
+      } else if ((byte & 0xc0) === QOI_OP_INDEX) {
+        const index = byte & 0x3f;
+        r = colorArray[index * 4];
+        g = colorArray[index * 4 + 1];
+        b = colorArray[index * 4 + 2];
+        a = colorArray[index * 4 + 3];
+        // INDEX does not update the color array
+      } else if ((byte & 0xc0) === QOI_OP_DIFF) {
+        r = (r + ((byte >> 4) & 0x03) - 2) & 0xff;
+        g = (g + ((byte >> 2) & 0x03) - 2) & 0xff;
+        b = (b + (byte & 0x03) - 2) & 0xff;
+        const hash = qoiHash(r, g, b, a);
+        colorArray[hash * 4] = r;
+        colorArray[hash * 4 + 1] = g;
+        colorArray[hash * 4 + 2] = b;
+        colorArray[hash * 4 + 3] = a;
+      } else if ((byte & 0xc0) === QOI_OP_LUMA) {
+        const byte2 = data[offset++];
+        const dg = (byte & 0x3f) - 32;
+        r = (r + dg - 8 + ((byte2 >> 4) & 0x0f)) & 0xff;
+        g = (g + dg) & 0xff;
+        b = (b + dg - 8 + (byte2 & 0x0f)) & 0xff;
+        const hash = qoiHash(r, g, b, a);
+        colorArray[hash * 4] = r;
+        colorArray[hash * 4 + 1] = g;
+        colorArray[hash * 4 + 2] = b;
+        colorArray[hash * 4 + 3] = a;
+      } else {
+        // QOI_OP_RUN: top 2 bits are 11, byte is 0xC0–0xFD
+        // run count stored as bias-1: (byte & 0x3F) + 1 pixels
+        const run = (byte & 0x3f) + 1;
+        // RUN does not update the color array
+        for (let i = 0; i < run && pixelIndex < pixelCount; i++, pixelIndex++) {
+          const di = pixelIndex * 4;
+          rgba[di] = r;
+          rgba[di + 1] = g;
+          rgba[di + 2] = b;
+          rgba[di + 3] = a;
+        }
+        continue;
+      }
+
+      const di = pixelIndex * 4;
+      rgba[di] = r;
+      rgba[di + 1] = g;
+      rgba[di + 2] = b;
+      rgba[di + 3] = a;
+      pixelIndex++;
+    }
+
+    return Promise.resolve({ width, height, data: rgba });
+  }
+
+  /**
+   * Encode RGBA image data to QOI format
+   * @param imageData Image data to encode
+   * @returns Encoded QOI image bytes
+   */
+  encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array> {
+    const { width, height, data } = imageData;
+
+    if (data.length !== width * height * 4) {
+      throw new Error(
+        `Data length mismatch: expected ${width * height * 4}, got ${data.length}`,
+      );
+    }
+
+    // Worst case: every pixel is QOI_OP_RGBA (5 bytes) + header (14) + end marker (8)
+    const maxSize = 14 + width * height * 5 + 8;
+    const out = new Uint8Array(maxSize);
+
+    // Write header
+    out[0] = QOI_MAGIC_0;
+    out[1] = QOI_MAGIC_1;
+    out[2] = QOI_MAGIC_2;
+    out[3] = QOI_MAGIC_3;
+    // Width (big-endian uint32)
+    out[4] = (width >>> 24) & 0xff;
+    out[5] = (width >>> 16) & 0xff;
+    out[6] = (width >>> 8) & 0xff;
+    out[7] = width & 0xff;
+    // Height (big-endian uint32)
+    out[8] = (height >>> 24) & 0xff;
+    out[9] = (height >>> 16) & 0xff;
+    out[10] = (height >>> 8) & 0xff;
+    out[11] = height & 0xff;
+    out[12] = 4; // channels: RGBA
+    out[13] = 0; // colorspace: sRGB with linear alpha
+
+    // Running color array: 64 entries × 4 bytes (RGBA), initialized to zero
+    const colorArray = new Uint8Array(64 * 4);
+
+    let offset = 14;
+    let prevR = 0, prevG = 0, prevB = 0, prevA = 255;
+    let run = 0;
+    const pixelCount = width * height;
+
+    const flushRun = () => {
+      if (run > 0) {
+        out[offset++] = QOI_OP_RUN | (run - 1);
+        run = 0;
+      }
+    };
+
+    for (let i = 0; i < pixelCount; i++) {
+      const di = i * 4;
+      const r = data[di];
+      const g = data[di + 1];
+      const b = data[di + 2];
+      const a = data[di + 3];
+
+      if (r === prevR && g === prevG && b === prevB && a === prevA) {
+        run++;
+        if (run === 62) {
+          flushRun();
+        }
+        continue;
+      }
+
+      flushRun();
+
+      const hash = qoiHash(r, g, b, a);
+
+      if (
+        colorArray[hash * 4] === r &&
+        colorArray[hash * 4 + 1] === g &&
+        colorArray[hash * 4 + 2] === b &&
+        colorArray[hash * 4 + 3] === a
+      ) {
+        out[offset++] = QOI_OP_INDEX | hash;
+      } else if (a === prevA) {
+        const dr = (r - prevR) | 0;
+        const dg = (g - prevG) | 0;
+        const db = (b - prevB) | 0;
+
+        if (dr >= -2 && dr <= 1 && dg >= -2 && dg <= 1 && db >= -2 && db <= 1) {
+          out[offset++] = QOI_OP_DIFF | ((dr + 2) << 4) | ((dg + 2) << 2) | (db + 2);
+        } else {
+          const dgR = dr - dg;
+          const dgB = db - dg;
+          if (dg >= -32 && dg <= 31 && dgR >= -8 && dgR <= 7 && dgB >= -8 && dgB <= 7) {
+            out[offset++] = QOI_OP_LUMA | (dg + 32);
+            out[offset++] = ((dgR + 8) << 4) | (dgB + 8);
+          } else {
+            out[offset++] = QOI_OP_RGB;
+            out[offset++] = r;
+            out[offset++] = g;
+            out[offset++] = b;
+          }
+        }
+      } else {
+        out[offset++] = QOI_OP_RGBA;
+        out[offset++] = r;
+        out[offset++] = g;
+        out[offset++] = b;
+        out[offset++] = a;
+      }
+
+      colorArray[hash * 4] = r;
+      colorArray[hash * 4 + 1] = g;
+      colorArray[hash * 4 + 2] = b;
+      colorArray[hash * 4 + 3] = a;
+
+      prevR = r;
+      prevG = g;
+      prevB = b;
+      prevA = a;
+    }
+
+    flushRun();
+
+    // Write end marker
+    out[offset++] = 0x00;
+    out[offset++] = 0x00;
+    out[offset++] = 0x00;
+    out[offset++] = 0x00;
+    out[offset++] = 0x00;
+    out[offset++] = 0x00;
+    out[offset++] = 0x00;
+    out[offset++] = 0x01;
+
+    return Promise.resolve(out.subarray(0, offset));
+  }
+
+  /**
+   * Get the list of metadata fields supported by QOI format
+   */
+  getSupportedMetadata(): Array<keyof ImageMetadata> {
+    return [];
+  }
+
+  /**
+   * Extract metadata from QOI data without fully decoding the pixel data
+   * @param data Raw QOI data
+   * @returns Extracted metadata or undefined
+   */
+  extractMetadata(data: Uint8Array): Promise<ImageMetadata | undefined> {
+    if (!this.canDecode(data)) return Promise.resolve(undefined);
+
+    const channels = data[12];
+
+    return Promise.resolve({
+      format: "qoi",
+      compression: "none",
+      frameCount: 1,
+      bitDepth: 8,
+      colorType: channels === 4 ? "rgba" : "rgb",
+    });
+  }
+}
diff --git a/src/image.ts b/src/image.ts
index 546e766..ba9c893 100644
--- a/src/image.ts
+++ b/src/image.ts
@@ -44,6 +44,9 @@ import { DNGFormat } from "./formats/dng.ts";
 import { PAMFormat } from "./formats/pam.ts";
 import { PCXFormat } from "./formats/pcx.ts";
 import { PPMFormat } from "./formats/ppm.ts";
+import { PGMFormat } from "./formats/pgm.ts";
+import { PBMFormat } from "./formats/pbm.ts";
+import { QOIFormat } from "./formats/qoi.ts";
 import { ASCIIFormat } from "./formats/ascii.ts";
 import { HEICFormat } from "./formats/heic.ts";
 import { AVIFFormat } from "./formats/avif.ts";
@@ -67,6 +70,9 @@ export class Image {
     new PAMFormat(),
     new PCXFormat(),
     new PPMFormat(),
+    new PGMFormat(),
+    new PBMFormat(),
+    new QOIFormat(),
     new ASCIIFormat(),
     new HEICFormat(),
     new AVIFFormat(),
diff --git a/test/formats/pbm.test.ts b/test/formats/pbm.test.ts
new file mode 100644
index 0000000..c6f3348
--- /dev/null
+++ b/test/formats/pbm.test.ts
@@ -0,0 +1,345 @@
+import { assertEquals, assertRejects } from "@std/assert";
+import { test } from "@cross/test";
+import { PBMFormat } from "../../src/formats/pbm.ts";
+
+test("PBM: canDecode - valid P4 (binary) signature", () => {
+  const encoder = new TextEncoder();
+  const validPBM = encoder.encode("P4\n8 1\n");
+  const format = new PBMFormat();
+
+  assertEquals(format.canDecode(validPBM), true);
+});
+
+test("PBM: canDecode - valid P1 (ASCII) signature", () => {
+  const encoder = new TextEncoder();
+  const validPBM = encoder.encode("P1\n8 1\n");
+  const format = new PBMFormat();
+
+  assertEquals(format.canDecode(validPBM), true);
+});
+
+test("PBM: canDecode - invalid signature", () => {
+  const invalid = new Uint8Array([0, 1, 2, 3, 4, 5]);
+  const format = new PBMFormat();
+
+  assertEquals(format.canDecode(invalid), false);
+});
+
+test("PBM: canDecode - PPM signature rejected", () => {
+  const encoder = new TextEncoder();
+  const ppm = encoder.encode("P6\n10 10\n255\n");
+  const format = new PBMFormat();
+
+  assertEquals(format.canDecode(ppm), false);
+});
+
+test("PBM: canDecode - too short", () => {
+  const tooShort = new Uint8Array([0x50, 0x34]);
+  const format = new PBMFormat();
+
+  assertEquals(format.canDecode(tooShort), false);
+});
+
+test("PBM: decode - invalid data throws", async () => {
+  const format = new PBMFormat();
+
+  await assertRejects(
+    async () => await format.decode(new Uint8Array([0, 1, 2, 3])),
+    Error,
+    "Invalid PBM signature",
+  );
+});
+
+test("PBM: decode P4 - 8-pixel row (1 byte)", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  // P4, 8 pixels wide, 1 pixel tall
+  // Bit pattern 0b10110010 = 0xB2 -> pixels: black white black black white white black black
+  // In PBM: 1=black (0,0,0), 0=white (255,255,255)
+  const header = encoder.encode("P4\n8 1\n");
+  const pixels = new Uint8Array([0b10110010]); // 8 pixels packed
+  const data = new Uint8Array(header.length + pixels.length);
+  data.set(header);
+  data.set(pixels, header.length);
+
+  const decoded = await format.decode(data);
+
+  assertEquals(decoded.width, 8);
+  assertEquals(decoded.height, 1);
+
+  // Bit 7 (MSB) = 1 = black
+  assertEquals(decoded.data[0], 0); // R
+  assertEquals(decoded.data[1], 0); // G
+  assertEquals(decoded.data[2], 0); // B
+  assertEquals(decoded.data[3], 255); // A
+
+  // Bit 6 = 0 = white
+  assertEquals(decoded.data[4], 255);
+  assertEquals(decoded.data[5], 255);
+  assertEquals(decoded.data[6], 255);
+  assertEquals(decoded.data[7], 255);
+
+  // Bit 5 = 1 = black
+  assertEquals(decoded.data[8], 0);
+
+  // Bit 4 = 1 = black
+  assertEquals(decoded.data[12], 0);
+
+  // Bit 3 = 0 = white
+  assertEquals(decoded.data[16], 255);
+
+  // Bit 2 = 0 = white
+  assertEquals(decoded.data[20], 255);
+
+  // Bit 1 = 1 = black
+  assertEquals(decoded.data[24], 0);
+
+  // Bit 0 (LSB) = 0 = white
+  assertEquals(decoded.data[28], 255);
+});
+
+test("PBM: decode P4 - row padding", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  // 3 pixels wide, 2 rows: each row is 1 byte (3 bits + 5 padding bits)
+  // Row 1: 0b10100000 -> pixels: black, white, black (then 5 padding bits ignored)
+  // Row 2: 0b01100000 -> pixels: white, black, black
+  const header = encoder.encode("P4\n3 2\n");
+  const pixels = new Uint8Array([0b10100000, 0b01100000]);
+  const data = new Uint8Array(header.length + pixels.length);
+  data.set(header);
+  data.set(pixels, header.length);
+
+  const decoded = await format.decode(data);
+
+  assertEquals(decoded.width, 3);
+  assertEquals(decoded.height, 2);
+
+  // Row 1
+  assertEquals(decoded.data[0], 0); // black
+  assertEquals(decoded.data[4], 255); // white
+  assertEquals(decoded.data[8], 0); // black
+
+  // Row 2
+  assertEquals(decoded.data[12], 255); // white
+  assertEquals(decoded.data[16], 0); // black
+  assertEquals(decoded.data[20], 0); // black
+});
+
+test("PBM: decode P1 (ASCII) - small image", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  // 2x2: 0=white, 1=black
+  const p1Data = encoder.encode("P1\n2 2\n0 1 1 0");
+
+  const decoded = await format.decode(p1Data);
+
+  assertEquals(decoded.width, 2);
+  assertEquals(decoded.height, 2);
+
+  assertEquals(decoded.data[0], 255); // white
+  assertEquals(decoded.data[4], 0); // black
+  assertEquals(decoded.data[8], 0); // black
+  assertEquals(decoded.data[12], 255); // white
+});
+
+test("PBM: decode P1 (ASCII) - with comments", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  const p1Data = encoder.encode("P1\n# a comment\n2 1\n0 1");
+
+  const decoded = await format.decode(p1Data);
+
+  assertEquals(decoded.width, 2);
+  assertEquals(decoded.height, 1);
+  assertEquals(decoded.data[0], 255); // 0 = white
+  assertEquals(decoded.data[4], 0); // 1 = black
+});
+
+test("PBM: encode and decode round-trip", async () => {
+  const format = new PBMFormat();
+
+  // Create a 4x4 image with clear black/white pixels
+  const imageData = {
+    width: 4,
+    height: 4,
+    data: new Uint8Array([
+      0,
+      0,
+      0,
+      255,
+      255,
+      255,
+      255,
+      255,
+      0,
+      0,
+      0,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      0,
+      0,
+      0,
+      255,
+      255,
+      255,
+      255,
+      255,
+      0,
+      0,
+      0,
+      255,
+      0,
+      0,
+      0,
+      255,
+      0,
+      0,
+      0,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      255,
+      0,
+      0,
+      0,
+      255,
+      0,
+      0,
+      0,
+      255,
+    ]),
+  };
+
+  const encoded = await format.encode(imageData);
+  assertEquals(format.canDecode(encoded), true);
+
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, 4);
+  assertEquals(decoded.height, 4);
+
+  // Black pixels should be black, white pixels should be white
+  for (let i = 0; i < 16; i++) {
+    const origGray = imageData.data[i * 4]; // all are pure black or pure white
+    const expected = origGray < 128 ? 0 : 255;
+    assertEquals(decoded.data[i * 4], expected, `pixel ${i} mismatch`);
+    assertEquals(decoded.data[i * 4 + 3], 255, `pixel ${i} alpha mismatch`);
+  }
+});
+
+test("PBM: encode - thresholding gray to black/white", async () => {
+  const format = new PBMFormat();
+
+  // Dark gray (100 < 128) -> black; light gray (200 >= 128) -> white
+  const imageData = {
+    width: 2,
+    height: 1,
+    data: new Uint8Array([100, 100, 100, 255, 200, 200, 200, 255]),
+  };
+
+  const encoded = await format.encode(imageData);
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.data[0], 0); // dark gray -> black
+  assertEquals(decoded.data[4], 255); // light gray -> white
+});
+
+test("PBM: properties", () => {
+  const format = new PBMFormat();
+
+  assertEquals(format.name, "pbm");
+  assertEquals(format.mimeType, "image/x-portable-bitmap");
+});
+
+test("PBM: decode P4 - data length mismatch", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  const header = encoder.encode("P4\n16 16\n"); // needs 16*16/8 = 32 bytes
+  const data = new Uint8Array(header.length + 3); // only 3 bytes
+  data.set(header);
+
+  await assertRejects(
+    async () => await format.decode(data),
+    Error,
+    "Invalid PBM data length",
+  );
+});
+
+test("PBM: decode - incomplete header", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  const incomplete = encoder.encode("P4\n10");
+
+  await assertRejects(
+    async () => await format.decode(incomplete),
+    Error,
+    "Incomplete PBM header",
+  );
+});
+
+test("PBM: encode - data length mismatch", async () => {
+  const format = new PBMFormat();
+
+  await assertRejects(
+    async () =>
+      await format.encode({
+        width: 2,
+        height: 2,
+        data: new Uint8Array([255, 0, 0]),
+      }),
+    Error,
+    "Data length mismatch",
+  );
+});
+
+test("PBM: decode P1 - incomplete pixel data", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  // 2x2 needs 4 values, only 3
+  const incomplete = encoder.encode("P1\n2 2\n0 1 0");
+
+  await assertRejects(
+    async () => await format.decode(incomplete),
+    Error,
+    "Incomplete PBM pixel data",
+  );
+});
+
+test("PBM: extractMetadata", async () => {
+  const format = new PBMFormat();
+  const encoder = new TextEncoder();
+  const data = encoder.encode("P4\n10 10\n");
+
+  const metadata = await format.extractMetadata(data);
+
+  assertEquals(metadata?.format, "pbm");
+  assertEquals(metadata?.colorType, "grayscale");
+  assertEquals(metadata?.bitDepth, 1);
+  assertEquals(metadata?.compression, "none");
+});
+
+test("PBM: getSupportedMetadata", () => {
+  const format = new PBMFormat();
+  assertEquals(format.getSupportedMetadata(), []);
+});
diff --git a/test/formats/pgm.test.ts b/test/formats/pgm.test.ts
new file mode 100644
index 0000000..53b72ea
--- /dev/null
+++ b/test/formats/pgm.test.ts
@@ -0,0 +1,297 @@
+import { assertEquals, assertRejects } from "@std/assert";
+import { test } from "@cross/test";
+import { PGMFormat } from "../../src/formats/pgm.ts";
+
+test("PGM: canDecode - valid P5 (binary) signature", () => {
+  const encoder = new TextEncoder();
+  const validPGM = encoder.encode("P5\n10 10\n255\n");
+  const format = new PGMFormat();
+
+  assertEquals(format.canDecode(validPGM), true);
+});
+
+test("PGM: canDecode - valid P2 (ASCII) signature", () => {
+  const encoder = new TextEncoder();
+  const validPGM = encoder.encode("P2\n10 10\n255\n");
+  const format = new PGMFormat();
+
+  assertEquals(format.canDecode(validPGM), true);
+});
+
+test("PGM: canDecode - invalid signature", () => {
+  const invalid = new Uint8Array([0, 1, 2, 3, 4, 5]);
+  const format = new PGMFormat();
+
+  assertEquals(format.canDecode(invalid), false);
+});
+
+test("PGM: canDecode - PPM signature rejected", () => {
+  const encoder = new TextEncoder();
+  const ppm = encoder.encode("P6\n10 10\n255\n");
+  const format = new PGMFormat();
+
+  assertEquals(format.canDecode(ppm), false);
+});
+
+test("PGM: canDecode - too short", () => {
+  const tooShort = new Uint8Array([0x50, 0x35]);
+  const format = new PGMFormat();
+
+  assertEquals(format.canDecode(tooShort), false);
+});
+
+test("PGM: decode - invalid data throws", async () => {
+  const format = new PGMFormat();
+
+  await assertRejects(
+    async () => await format.decode(new Uint8Array([0, 1, 2, 3])),
+    Error,
+    "Invalid PGM signature",
+  );
+});
+
+test("PGM: decode P5 - small grayscale image", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  const header = encoder.encode("P5\n2 2\n255\n");
+  const pixels = new Uint8Array([0, 128, 64, 255]);
+  const data = new Uint8Array(header.length + pixels.length);
+  data.set(header);
+  data.set(pixels, header.length);
+
+  const decoded = await format.decode(data);
+
+  assertEquals(decoded.width, 2);
+  assertEquals(decoded.height, 2);
+  // Each grayscale value should be expanded to R=G=B with A=255
+  assertEquals(decoded.data[0], 0); // R
+  assertEquals(decoded.data[1], 0); // G
+  assertEquals(decoded.data[2], 0); // B
+  assertEquals(decoded.data[3], 255); // A
+
+  assertEquals(decoded.data[4], 128); // R
+  assertEquals(decoded.data[5], 128); // G
+  assertEquals(decoded.data[6], 128); // B
+  assertEquals(decoded.data[7], 255); // A
+
+  assertEquals(decoded.data[8], 64); // R
+  assertEquals(decoded.data[9], 64); // G
+  assertEquals(decoded.data[10], 64); // B
+  assertEquals(decoded.data[11], 255); // A
+
+  assertEquals(decoded.data[12], 255); // R
+  assertEquals(decoded.data[13], 255); // G
+  assertEquals(decoded.data[14], 255); // B
+  assertEquals(decoded.data[15], 255); // A
+});
+
+test("PGM: decode P2 (ASCII) - small image", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  const p2Data = encoder.encode("P2\n2 1\n255\n0 128");
+
+  const decoded = await format.decode(p2Data);
+
+  assertEquals(decoded.width, 2);
+  assertEquals(decoded.height, 1);
+  assertEquals(decoded.data[0], 0);
+  assertEquals(decoded.data[1], 0);
+  assertEquals(decoded.data[2], 0);
+  assertEquals(decoded.data[3], 255);
+  assertEquals(decoded.data[4], 128);
+  assertEquals(decoded.data[5], 128);
+  assertEquals(decoded.data[6], 128);
+  assertEquals(decoded.data[7], 255);
+});
+
+test("PGM: decode P2 (ASCII) - with comments", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  const p2Data = encoder.encode("P2\n# comment\n1 1\n255\n# pixel\n200");
+
+  const decoded = await format.decode(p2Data);
+
+  assertEquals(decoded.width, 1);
+  assertEquals(decoded.height, 1);
+  assertEquals(decoded.data[0], 200);
+  assertEquals(decoded.data[1], 200);
+  assertEquals(decoded.data[2], 200);
+  assertEquals(decoded.data[3], 255);
+});
+
+test("PGM: encode and decode round-trip", async () => {
+  const format = new PGMFormat();
+
+  // Create a simple 3x3 RGBA image (all grays)
+  const imageData = {
+    width: 3,
+    height: 3,
+    data: new Uint8Array([
+      100,
+      100,
+      100,
+      255,
+      150,
+      150,
+      150,
+      255,
+      200,
+      200,
+      200,
+      255,
+      50,
+      50,
+      50,
+      255,
+      0,
+      0,
+      0,
+      255,
+      255,
+      255,
+      255,
+      255,
+      128,
+      128,
+      128,
+      255,
+      64,
+      64,
+      64,
+      255,
+      192,
+      192,
+      192,
+      255,
+    ]),
+  };
+
+  const encoded = await format.encode(imageData);
+  assertEquals(format.canDecode(encoded), true);
+
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, 3);
+  assertEquals(decoded.height, 3);
+
+  // For pure grays, encode->decode should preserve values
+  for (let i = 0; i < 9; i++) {
+    assertEquals(decoded.data[i * 4], imageData.data[i * 4], `pixel ${i} mismatch`);
+    assertEquals(decoded.data[i * 4 + 1], imageData.data[i * 4 + 1], `pixel ${i} G mismatch`);
+    assertEquals(decoded.data[i * 4 + 2], imageData.data[i * 4 + 2], `pixel ${i} B mismatch`);
+    assertEquals(decoded.data[i * 4 + 3], 255, `pixel ${i} A mismatch`);
+  }
+});
+
+test("PGM: encode - RGB to grayscale conversion", async () => {
+  const format = new PGMFormat();
+
+  // Red pixel: luminance = 0.299 * 255 ≈ 76
+  const imageData = {
+    width: 1,
+    height: 1,
+    data: new Uint8Array([255, 0, 0, 255]),
+  };
+
+  const encoded = await format.encode(imageData);
+  const decoded = await format.decode(encoded);
+
+  // Should be approximately the red luminance
+  const expected = Math.round(0.299 * 255 + 0.587 * 0 + 0.114 * 0);
+  assertEquals(decoded.data[0], expected);
+  assertEquals(decoded.data[1], expected);
+  assertEquals(decoded.data[2], expected);
+  assertEquals(decoded.data[3], 255);
+});
+
+test("PGM: properties", () => {
+  const format = new PGMFormat();
+
+  assertEquals(format.name, "pgm");
+  assertEquals(format.mimeType, "image/x-portable-graymap");
+});
+
+test("PGM: decode P5 - data length mismatch", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  const header = encoder.encode("P5\n4 4\n255\n");
+  // Only 3 bytes when 16 expected
+  const data = new Uint8Array(header.length + 3);
+  data.set(header);
+
+  await assertRejects(
+    async () => await format.decode(data),
+    Error,
+    "Invalid PGM data length",
+  );
+});
+
+test("PGM: decode - incomplete header", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  const incomplete = encoder.encode("P5\n10 10\n");
+
+  await assertRejects(
+    async () => await format.decode(incomplete),
+    Error,
+    "Incomplete PGM header",
+  );
+});
+
+test("PGM: decode - maxval greater than 255", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  const unsupported = encoder.encode("P5\n1 1\n65535\n");
+
+  await assertRejects(
+    async () => await format.decode(unsupported),
+    Error,
+    "Unsupported PGM maxval",
+  );
+});
+
+test("PGM: encode - data length mismatch", async () => {
+  const format = new PGMFormat();
+
+  await assertRejects(
+    async () =>
+      await format.encode({
+        width: 2,
+        height: 2,
+        data: new Uint8Array([255, 0, 0]),
+      }),
+    Error,
+    "Data length mismatch",
+  );
+});
+
+test("PGM: decode P2 - incomplete pixel data", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  // 2x2 needs 4 values, only 3
+  const incomplete = encoder.encode("P2\n2 2\n255\n100 200 150");
+
+  await assertRejects(
+    async () => await format.decode(incomplete),
+    Error,
+    "Incomplete PGM pixel data",
+  );
+});
+
+test("PGM: extractMetadata", async () => {
+  const format = new PGMFormat();
+  const encoder = new TextEncoder();
+  const data = encoder.encode("P5\n10 10\n255\n");
+
+  const metadata = await format.extractMetadata(data);
+
+  assertEquals(metadata?.format, "pgm");
+  assertEquals(metadata?.colorType, "grayscale");
+  assertEquals(metadata?.bitDepth, 8);
+  assertEquals(metadata?.compression, "none");
+});
+
+test("PGM: getSupportedMetadata", () => {
+  const format = new PGMFormat();
+  assertEquals(format.getSupportedMetadata(), []);
+});
diff --git a/test/formats/qoi.test.ts b/test/formats/qoi.test.ts
new file mode 100644
index 0000000..aa2025d
--- /dev/null
+++ b/test/formats/qoi.test.ts
@@ -0,0 +1,335 @@
+import { assertEquals, assertRejects } from "@std/assert";
+import { test } from "@cross/test";
+import { QOIFormat } from "../../src/formats/qoi.ts";
+
+test("QOI: canDecode - valid signature", () => {
+  const data = new Uint8Array([
+    0x71,
+    0x6f,
+    0x69,
+    0x66, // "qoif"
+    0,
+    0,
+    0,
+    4, // width=4
+    0,
+    0,
+    0,
+    4, // height=4
+    4, // channels=4 (RGBA)
+    0, // colorspace=sRGB
+  ]);
+  const format = new QOIFormat();
+
+  assertEquals(format.canDecode(data), true);
+});
+
+test("QOI: canDecode - invalid signature", () => {
+  const invalid = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]);
+  const format = new QOIFormat();
+
+  assertEquals(format.canDecode(invalid), false);
+});
+
+test("QOI: canDecode - too short", () => {
+  const tooShort = new Uint8Array([0x71, 0x6f, 0x69, 0x66]);
+  const format = new QOIFormat();
+
+  assertEquals(format.canDecode(tooShort), false);
+});
+
+test("QOI: decode - invalid data throws", async () => {
+  const format = new QOIFormat();
+
+  await assertRejects(
+    async () => await format.decode(new Uint8Array([0, 1, 2, 3])),
+    Error,
+    "Invalid QOI signature",
+  );
+});
+
+test("QOI: encode and decode - single pixel", async () => {
+  const format = new QOIFormat();
+
+  const imageData = {
+    width: 1,
+    height: 1,
+    data: new Uint8Array([128, 64, 32, 255]),
+  };
+
+  const encoded = await format.encode(imageData);
+  assertEquals(format.canDecode(encoded), true);
+
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, 1);
+  assertEquals(decoded.height, 1);
+  assertEquals(decoded.data[0], 128);
+  assertEquals(decoded.data[1], 64);
+  assertEquals(decoded.data[2], 32);
+  assertEquals(decoded.data[3], 255);
+});
+
+test("QOI: encode and decode - solid color (uses RUN encoding)", async () => {
+  const format = new QOIFormat();
+
+  // All red pixels — encoder should use QOI_OP_RUN for most
+  const width = 10;
+  const height = 10;
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    data[i * 4] = 255;
+    data[i * 4 + 1] = 0;
+    data[i * 4 + 2] = 0;
+    data[i * 4 + 3] = 255;
+  }
+
+  const encoded = await format.encode({ width, height, data });
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, width);
+  assertEquals(decoded.height, height);
+  for (let i = 0; i < width * height; i++) {
+    assertEquals(decoded.data[i * 4], 255, `pixel ${i} R`);
+    assertEquals(decoded.data[i * 4 + 1], 0, `pixel ${i} G`);
+    assertEquals(decoded.data[i * 4 + 2], 0, `pixel ${i} B`);
+    assertEquals(decoded.data[i * 4 + 3], 255, `pixel ${i} A`);
+  }
+});
+
+test("QOI: encode and decode - gradient image", async () => {
+  const format = new QOIFormat();
+
+  const width = 16;
+  const height = 16;
+  const data = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = (y * width + x) * 4;
+      data[i] = Math.floor((x / (width - 1)) * 255);
+      data[i + 1] = Math.floor((y / (height - 1)) * 255);
+      data[i + 2] = 128;
+      data[i + 3] = 255;
+    }
+  }
+
+  const encoded = await format.encode({ width, height, data });
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, width);
+  assertEquals(decoded.height, height);
+
+  for (let i = 0; i < width * height; i++) {
+    assertEquals(decoded.data[i * 4], data[i * 4], `pixel ${i} R mismatch`);
+    assertEquals(decoded.data[i * 4 + 1], data[i * 4 + 1], `pixel ${i} G mismatch`);
+    assertEquals(decoded.data[i * 4 + 2], data[i * 4 + 2], `pixel ${i} B mismatch`);
+    assertEquals(decoded.data[i * 4 + 3], data[i * 4 + 3], `pixel ${i} A mismatch`);
+  }
+});
+
+test("QOI: encode and decode - alpha channel preserved", async () => {
+  const format = new QOIFormat();
+
+  const imageData = {
+    width: 2,
+    height: 2,
+    data: new Uint8Array([
+      255,
+      0,
+      0,
+      255, // opaque red
+      0,
+      255,
+      0,
+      128, // semi-transparent green
+      0,
+      0,
+      255,
+      0, // transparent blue
+      255,
+      255,
+      0,
+      200, // mostly-opaque yellow
+    ]),
+  };
+
+  const encoded = await format.encode(imageData);
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.data[3], 255);
+  assertEquals(decoded.data[7], 128);
+  assertEquals(decoded.data[11], 0);
+  assertEquals(decoded.data[15], 200);
+});
+
+test("QOI: encode - header format", async () => {
+  const format = new QOIFormat();
+
+  const imageData = {
+    width: 3,
+    height: 5,
+    data: new Uint8Array(3 * 5 * 4).fill(0),
+  };
+
+  const encoded = await format.encode(imageData);
+
+  // Check magic bytes "qoif"
+  assertEquals(encoded[0], 0x71);
+  assertEquals(encoded[1], 0x6f);
+  assertEquals(encoded[2], 0x69);
+  assertEquals(encoded[3], 0x66);
+
+  // Check width (big-endian): 3
+  assertEquals(encoded[4], 0);
+  assertEquals(encoded[5], 0);
+  assertEquals(encoded[6], 0);
+  assertEquals(encoded[7], 3);
+
+  // Check height (big-endian): 5
+  assertEquals(encoded[8], 0);
+  assertEquals(encoded[9], 0);
+  assertEquals(encoded[10], 0);
+  assertEquals(encoded[11], 5);
+
+  // Channels = 4 (RGBA)
+  assertEquals(encoded[12], 4);
+});
+
+test("QOI: encode - end marker present", async () => {
+  const format = new QOIFormat();
+
+  const imageData = {
+    width: 1,
+    height: 1,
+    data: new Uint8Array([255, 0, 0, 255]),
+  };
+
+  const encoded = await format.encode(imageData);
+
+  // Last 8 bytes should be the QOI end marker: 7 zeros followed by 0x01
+  const end = encoded.slice(-8);
+  assertEquals(end[0], 0x00);
+  assertEquals(end[1], 0x00);
+  assertEquals(end[2], 0x00);
+  assertEquals(end[3], 0x00);
+  assertEquals(end[4], 0x00);
+  assertEquals(end[5], 0x00);
+  assertEquals(end[6], 0x00);
+  assertEquals(end[7], 0x01);
+});
+
+test("QOI: encode and decode - repeated colors use INDEX", async () => {
+  const format = new QOIFormat();
+
+  // Create image where the same colors repeat (exercises QOI_OP_INDEX)
+  const width = 4;
+  const height = 4;
+  const data = new Uint8Array(width * height * 4);
+  const colors = [
+    [255, 0, 0, 255],
+    [0, 255, 0, 255],
+    [0, 0, 255, 255],
+    [255, 255, 0, 255],
+  ];
+  for (let i = 0; i < width * height; i++) {
+    const color = colors[i % 4];
+    data[i * 4] = color[0];
+    data[i * 4 + 1] = color[1];
+    data[i * 4 + 2] = color[2];
+    data[i * 4 + 3] = color[3];
+  }
+
+  const encoded = await format.encode({ width, height, data });
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, width);
+  assertEquals(decoded.height, height);
+  for (let i = 0; i < width * height; i++) {
+    const expected = colors[i % 4];
+    assertEquals(decoded.data[i * 4], expected[0], `pixel ${i} R`);
+    assertEquals(decoded.data[i * 4 + 1], expected[1], `pixel ${i} G`);
+    assertEquals(decoded.data[i * 4 + 2], expected[2], `pixel ${i} B`);
+    assertEquals(decoded.data[i * 4 + 3], expected[3], `pixel ${i} A`);
+  }
+});
+
+test("QOI: encode and decode - large run (>62 pixels)", async () => {
+  const format = new QOIFormat();
+
+  // 100 pixels of the same color — exercises run length > 62
+  const width = 100;
+  const height = 1;
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    data[i * 4] = 123;
+    data[i * 4 + 1] = 45;
+    data[i * 4 + 2] = 67;
+    data[i * 4 + 3] = 200;
+  }
+
+  const encoded = await format.encode({ width, height, data });
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, width);
+  assertEquals(decoded.height, height);
+  for (let i = 0; i < width; i++) {
+    assertEquals(decoded.data[i * 4], 123);
+    assertEquals(decoded.data[i * 4 + 1], 45);
+    assertEquals(decoded.data[i * 4 + 2], 67);
+    assertEquals(decoded.data[i * 4 + 3], 200);
+  }
+});
+
+test("QOI: encode - data length mismatch", async () => {
+  const format = new QOIFormat();
+
+  await assertRejects(
+    async () =>
+      await format.encode({
+        width: 2,
+        height: 2,
+        data: new Uint8Array([255, 0, 0]),
+      }),
+    Error,
+    "Data length mismatch",
+  );
+});
+
+test("QOI: properties", () => {
+  const format = new QOIFormat();
+
+  assertEquals(format.name, "qoi");
+  assertEquals(format.mimeType, "image/qoi");
+});
+
+test("QOI: extractMetadata - RGBA", async () => {
+  const format = new QOIFormat();
+
+  const imageData = {
+    width: 4,
+    height: 4,
+    data: new Uint8Array(4 * 4 * 4).fill(128),
+  };
+
+  const encoded = await format.encode(imageData);
+  const metadata = await format.extractMetadata(encoded);
+
+  assertEquals(metadata?.format, "qoi");
+  assertEquals(metadata?.colorType, "rgba");
+  assertEquals(metadata?.bitDepth, 8);
+  assertEquals(metadata?.compression, "none");
+  assertEquals(metadata?.frameCount, 1);
+});
+
+test("QOI: extractMetadata - invalid data returns undefined", async () => {
+  const format = new QOIFormat();
+  const invalid = new Uint8Array([0, 1, 2, 3]);
+
+  const metadata = await format.extractMetadata(invalid);
+  assertEquals(metadata, undefined);
+});
+
+test("QOI: getSupportedMetadata", () => {
+  const format = new QOIFormat();
+  assertEquals(format.getSupportedMetadata(), []);
+});

From 2b44047bf64a7378f4fd0bea3e4662723b251374 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Mar 2026 21:08:55 +0000
Subject: [PATCH 3/4] Fix QOI encoder to use byte-wrapping arithmetic for
 DIFF/LUMA (matching reference qoi.h)

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>
Agent-Logs-Url: https://github.com/cross-org/image/sessions/e7a44ae9-80eb-4cd0-9a7b-f21aad38724d
---
 src/formats/qoi.ts       | 24 ++++++------
 test/formats/qoi.test.ts | 83 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 11 deletions(-)

diff --git a/src/formats/qoi.ts b/src/formats/qoi.ts
index f5598f6..cd33b22 100644
--- a/src/formats/qoi.ts
+++ b/src/formats/qoi.ts
@@ -249,18 +249,20 @@ export class QOIFormat implements ImageFormat {
       ) {
         out[offset++] = QOI_OP_INDEX | hash;
       } else if (a === prevA) {
-        const dr = (r - prevR) | 0;
-        const dg = (g - prevG) | 0;
-        const db = (b - prevB) | 0;
-
-        if (dr >= -2 && dr <= 1 && dg >= -2 && dg <= 1 && db >= -2 && db <= 1) {
-          out[offset++] = QOI_OP_DIFF | ((dr + 2) << 4) | ((dg + 2) << 2) | (db + 2);
+        // Compute channel diffs with byte-wrapping (matching C signed char behavior).
+        // The QOI spec mandates wraparound: e.g. going from 255 to 0 is a diff of +1.
+        const vr = (((r - prevR) & 0xff) ^ 0x80) - 0x80;
+        const vg = (((g - prevG) & 0xff) ^ 0x80) - 0x80;
+        const vb = (((b - prevB) & 0xff) ^ 0x80) - 0x80;
+
+        if (vr >= -2 && vr <= 1 && vg >= -2 && vg <= 1 && vb >= -2 && vb <= 1) {
+          out[offset++] = QOI_OP_DIFF | ((vr + 2) << 4) | ((vg + 2) << 2) | (vb + 2);
         } else {
-          const dgR = dr - dg;
-          const dgB = db - dg;
-          if (dg >= -32 && dg <= 31 && dgR >= -8 && dgR <= 7 && dgB >= -8 && dgB <= 7) {
-            out[offset++] = QOI_OP_LUMA | (dg + 32);
-            out[offset++] = ((dgR + 8) << 4) | (dgB + 8);
+          const vgR = vr - vg;
+          const vgB = vb - vg;
+          if (vg >= -32 && vg <= 31 && vgR >= -8 && vgR <= 7 && vgB >= -8 && vgB <= 7) {
+            out[offset++] = QOI_OP_LUMA | (vg + 32);
+            out[offset++] = ((vgR + 8) << 4) | (vgB + 8);
           } else {
             out[offset++] = QOI_OP_RGB;
             out[offset++] = r;
diff --git a/test/formats/qoi.test.ts b/test/formats/qoi.test.ts
index aa2025d..f863684 100644
--- a/test/formats/qoi.test.ts
+++ b/test/formats/qoi.test.ts
@@ -333,3 +333,86 @@ test("QOI: getSupportedMetadata", () => {
   const format = new QOIFormat();
   assertEquals(format.getSupportedMetadata(), []);
 });
+
+test("QOI: encode and decode - wraparound DIFF (255 to 0 and 0 to 255)", async () => {
+  const format = new QOIFormat();
+
+  // Pixel transitions that wrap around byte boundaries:
+  // prev {0,0,0,255} (initial) → {0,0,0,255} same → then transitions with wraparound
+  const imageData = {
+    width: 4,
+    height: 1,
+    data: new Uint8Array([
+      255,
+      255,
+      255,
+      255, // first pixel
+      0,
+      0,
+      0,
+      255, // 255→0: wraparound diff of +1 per channel
+      255,
+      255,
+      255,
+      255, // 0→255: wraparound diff of -1 per channel
+      1,
+      1,
+      1,
+      255, // 255→1: wraparound diff of +2... wait, that's outside DIFF range
+    ]),
+  };
+
+  const encoded = await format.encode(imageData);
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.width, 4);
+  assertEquals(decoded.height, 1);
+  for (let i = 0; i < 4; i++) {
+    assertEquals(decoded.data[i * 4], imageData.data[i * 4], `pixel ${i} R`);
+    assertEquals(decoded.data[i * 4 + 1], imageData.data[i * 4 + 1], `pixel ${i} G`);
+    assertEquals(decoded.data[i * 4 + 2], imageData.data[i * 4 + 2], `pixel ${i} B`);
+    assertEquals(decoded.data[i * 4 + 3], imageData.data[i * 4 + 3], `pixel ${i} A`);
+  }
+
+  // The wraparound transitions (255→0 and 0→255) should use DIFF encoding,
+  // producing a smaller file than if they fell through to RGB
+  // Header (14) + first pixel as RGB (4) + two DIFFs (2) + one RGB or LUMA + end (8)
+  // Without wraparound fix: 14 + 4 + 4 + 4 + 4 + 8 = much larger (all RGB)
+  // With wraparound: should be noticeably smaller
+});
+
+test("QOI: encode uses DIFF for byte-wraparound transitions", async () => {
+  const format = new QOIFormat();
+
+  // Two pixels: {254,254,254,255} → {0,0,0,255}
+  // With wraparound: diff = +2 per channel → outside DIFF range [-2,1]
+  // {255,255,255,255} → {0,0,0,255}: diff = +1 → inside DIFF range
+  const imageData = {
+    width: 2,
+    height: 1,
+    data: new Uint8Array([
+      255,
+      255,
+      255,
+      255,
+      0,
+      0,
+      0,
+      255,
+    ]),
+  };
+
+  const encoded = await format.encode(imageData);
+  const decoded = await format.decode(encoded);
+
+  assertEquals(decoded.data[0], 255);
+  assertEquals(decoded.data[4], 0);
+  assertEquals(decoded.data[5], 0);
+  assertEquals(decoded.data[6], 0);
+  assertEquals(decoded.data[7], 255);
+
+  // Encoding: header(14) + RGB for {255,255,255,255}(4) + DIFF for +1(1) + end(8) = 27
+  // Without wraparound: header(14) + RGB(4) + RGB(4) + end(8) = 30
+  // The DIFF encoding should make this smaller
+  assertEquals(encoded.length <= 27, true, `Expected compact encoding, got ${encoded.length}`);
+});

From 31dbbd6451302320944515863e0f69667b4a7323 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Mar 2026 21:13:58 +0000
Subject: [PATCH 4/4] Harden QOI decoder: bounds checks, end marker validation,
 incomplete pixel detection, extractMetadata channels validation, and 7 new
 negative tests

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>
Agent-Logs-Url: https://github.com/cross-org/image/sessions/82c277d1-99d4-4c56-b8c3-a21a2187967f
---
 src/formats/qoi.ts       |  28 +++++
 test/formats/qoi.test.ts | 222 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 250 insertions(+)

diff --git a/src/formats/qoi.ts b/src/formats/qoi.ts
index cd33b22..2da2758 100644
--- a/src/formats/qoi.ts
+++ b/src/formats/qoi.ts
@@ -99,6 +99,9 @@ export class QOIFormat implements ImageFormat {
       const byte = data[offset++];
 
       if (byte === QOI_OP_RGB) {
+        if (offset + 3 > dataEnd) {
+          throw new Error("Truncated QOI data: incomplete QOI_OP_RGB chunk");
+        }
         r = data[offset++];
         g = data[offset++];
         b = data[offset++];
@@ -109,6 +112,9 @@ export class QOIFormat implements ImageFormat {
         colorArray[hash * 4 + 2] = b;
         colorArray[hash * 4 + 3] = a;
       } else if (byte === QOI_OP_RGBA) {
+        if (offset + 4 > dataEnd) {
+          throw new Error("Truncated QOI data: incomplete QOI_OP_RGBA chunk");
+        }
         r = data[offset++];
         g = data[offset++];
         b = data[offset++];
@@ -135,6 +141,9 @@ export class QOIFormat implements ImageFormat {
         colorArray[hash * 4 + 2] = b;
         colorArray[hash * 4 + 3] = a;
       } else if ((byte & 0xc0) === QOI_OP_LUMA) {
+        if (offset + 1 > dataEnd) {
+          throw new Error("Truncated QOI data: incomplete QOI_OP_LUMA chunk");
+        }
         const byte2 = data[offset++];
         const dg = (byte & 0x3f) - 32;
         r = (r + dg - 8 + ((byte2 >> 4) & 0x0f)) & 0xff;
@@ -168,6 +177,23 @@ export class QOIFormat implements ImageFormat {
       pixelIndex++;
     }
 
+    if (pixelIndex < pixelCount) {
+      throw new Error(
+        `Incomplete QOI image: decoded ${pixelIndex} of ${pixelCount} pixels`,
+      );
+    }
+
+    // Verify the 8-byte end marker
+    const markerStart = data.length - 8;
+    for (let i = 0; i < 7; i++) {
+      if (data[markerStart + i] !== 0x00) {
+        throw new Error("Invalid QOI end marker");
+      }
+    }
+    if (data[markerStart + 7] !== 0x01) {
+      throw new Error("Invalid QOI end marker");
+    }
+
     return Promise.resolve({ width, height, data: rgba });
   }
 
@@ -321,6 +347,8 @@ export class QOIFormat implements ImageFormat {
 
     const channels = data[12];
 
+    if (channels !== 3 && channels !== 4) return Promise.resolve(undefined);
+
     return Promise.resolve({
       format: "qoi",
       compression: "none",
diff --git a/test/formats/qoi.test.ts b/test/formats/qoi.test.ts
index f863684..fe01004 100644
--- a/test/formats/qoi.test.ts
+++ b/test/formats/qoi.test.ts
@@ -48,6 +48,228 @@ test("QOI: decode - invalid data throws", async () => {
   );
 });
 
+test("QOI: decode - truncated QOI_OP_RGB payload throws", async () => {
+  const format = new QOIFormat();
+
+  // Valid header for 1×1 image, then QOI_OP_RGB (0xFE) but only 2 of 3 payload bytes
+  // before end marker
+  const data = new Uint8Array([
+    0x71,
+    0x6f,
+    0x69,
+    0x66, // magic "qoif"
+    0,
+    0,
+    0,
+    1, // width=1
+    0,
+    0,
+    0,
+    1, // height=1
+    4, // channels=4
+    0, // colorspace=sRGB
+    0xfe, // QOI_OP_RGB
+    128,
+    64, // only 2 of 3 bytes
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    1, // end marker
+  ]);
+
+  await assertRejects(
+    async () => await format.decode(data),
+    Error,
+    "Truncated QOI data",
+  );
+});
+
+test("QOI: decode - truncated QOI_OP_RGBA payload throws", async () => {
+  const format = new QOIFormat();
+
+  // Valid header for 1×1, then QOI_OP_RGBA (0xFF) but only 3 of 4 payload bytes
+  const data = new Uint8Array([
+    0x71,
+    0x6f,
+    0x69,
+    0x66, // magic
+    0,
+    0,
+    0,
+    1, // width=1
+    0,
+    0,
+    0,
+    1, // height=1
+    4,
+    0, // channels, colorspace
+    0xff, // QOI_OP_RGBA
+    128,
+    64,
+    32, // only 3 of 4 bytes
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    1, // end marker
+  ]);
+
+  await assertRejects(
+    async () => await format.decode(data),
+    Error,
+    "Truncated QOI data",
+  );
+});
+
+test("QOI: decode - truncated QOI_OP_LUMA payload throws", async () => {
+  const format = new QOIFormat();
+
+  // Valid header for 1×1, then QOI_OP_LUMA tag (0x80) but missing second byte
+  const data = new Uint8Array([
+    0x71,
+    0x6f,
+    0x69,
+    0x66, // magic
+    0,
+    0,
+    0,
+    1, // width=1
+    0,
+    0,
+    0,
+    1, // height=1
+    4,
+    0, // channels, colorspace
+    0x80, // QOI_OP_LUMA (needs 1 more byte)
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    1, // end marker
+  ]);
+
+  await assertRejects(
+    async () => await format.decode(data),
+    Error,
+    "Truncated QOI data",
+  );
+});
+
+test("QOI: decode - incomplete pixel stream throws", async () => {
+  const format = new QOIFormat();
+
+  // Header says 2×2 (4 pixels), but data stream only produces 1 pixel
+  const data = new Uint8Array([
+    0x71,
+    0x6f,
+    0x69,
+    0x66, // magic
+    0,
+    0,
+    0,
+    2, // width=2
+    0,
+    0,
+    0,
+    2, // height=2
+    4,
+    0, // channels, colorspace
+    0xfe,
+    128,
+    64,
+    32, // QOI_OP_RGB: 1 pixel
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    1, // end marker
+  ]);
+
+  await assertRejects(
+    async () => await format.decode(data),
+    Error,
+    "Incomplete QOI image",
+  );
+});
+
+test("QOI: decode - invalid end marker throws", async () => {
+  const format = new QOIFormat();
+
+  // Valid header for 1×1 image with a valid pixel, but wrong end marker
+  const data = new Uint8Array([
+    0x71,
+    0x6f,
+    0x69,
+    0x66, // magic
+    0,
+    0,
+    0,
+    1, // width=1
+    0,
+    0,
+    0,
+    1, // height=1
+    4,
+    0, // channels, colorspace
+    0xfe,
+    128,
+    64,
+    32, // QOI_OP_RGB: 1 pixel
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0, // wrong end marker (all zeros)
+  ]);
+
+  await assertRejects(
+    async () => await format.decode(data),
+    Error,
+    "Invalid QOI end marker",
+  );
+});
+
+test("QOI: extractMetadata - invalid channels returns undefined", async () => {
+  const format = new QOIFormat();
+
+  // Valid QOI signature but channels=5 (invalid)
+  const data = new Uint8Array([
+    0x71,
+    0x6f,
+    0x69,
+    0x66, // magic
+    0,
+    0,
+    0,
+    1, // width
+    0,
+    0,
+    0,
+    1, // height
+    5, // channels=5 (invalid)
+    0, // colorspace
+  ]);
+
+  const metadata = await format.extractMetadata(data);
+  assertEquals(metadata, undefined);
+});
+
 test("QOI: encode and decode - single pixel", async () => {
   const format = new QOIFormat();