cross-image 0.2.4 → 0.4.0

package/esm/src/utils/jpeg_decoder.js

@@ -1,10 +1,23 @@
 /**
- * Basic baseline JPEG decoder implementation
- * Supports baseline DCT JPEG images (the most common format)
+ * JPEG decoder implementation supporting both baseline and progressive DCT
  *
- * This is a simplified implementation that handles common JPEG files.
+ * Supports:
+ * - Baseline DCT (SOF0) - Sequential encoding
+ * - Progressive DCT (SOF2) - Multi-scan encoding with spectral selection and successive approximation
+ *
+ * This is a pure JavaScript implementation that handles common JPEG files.
  * For complex or non-standard JPEGs, the ImageDecoder API fallback is preferred.
  */
+/**
+ * Custom error class for end-of-scan marker detection
+ * Thrown when a marker is encountered in scan data, indicating the scan has ended
+ */
+class EndOfScanError extends Error {
+    constructor(message = "End of scan marker detected") {
+        super(message);
+        this.name = "EndOfScanError";
+    }
+}
 // JPEG markers
 const EOI = 0xFFD9; // End of Image
 const SOS = 0xFFDA; // Start of Scan
@@ -13,7 +26,8 @@ const DHT = 0xFFC4; // Define Huffman Table
 const SOF0 = 0xFFC0; // Start of Frame (Baseline DCT)
 const SOF2 = 0xFFC2; // Start of Frame (Progressive DCT)
 const DRI = 0xFFDD; // Define Restart Interval
-// Zigzag order for DCT coefficients
+// Zigzag order for DCT coefficients (JPEG standard)
+// Maps coefficient index in zigzag order to position in 8x8 block
 const ZIGZAG = [
     0,
     1,
@@ -81,7 +95,7 @@ const ZIGZAG = [
     63,
 ];
 export class JPEGDecoder {
-    constructor(data) {
+    constructor(data, settings = {}) {
         Object.defineProperty(this, "data", {
             enumerable: true,
             configurable: true,
@@ -148,7 +162,60 @@ export class JPEGDecoder {
             writable: true,
             value: 0
         });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "isProgressive", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        // Progressive JPEG scan parameters
+        Object.defineProperty(this, "spectralStart", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        }); // Start of spectral selection (Ss)
+        Object.defineProperty(this, "spectralEnd", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 63
+        }); // End of spectral selection (Se)
+        Object.defineProperty(this, "successiveHigh", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        }); // Successive approximation bit high (Ah)
+        Object.defineProperty(this, "successiveLow", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        }); // Successive approximation bit low (Al)
+        Object.defineProperty(this, "scanComponentIds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        }); // Component IDs included in current scan
+        Object.defineProperty(this, "eobRun", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        }); // Remaining blocks to skip due to EOBn
         this.data = data;
+        this.options = {
+            tolerantDecoding: settings.tolerantDecoding ?? true,
+            onWarning: settings.onWarning,
+        };
     }
     decode() {
         // Verify JPEG signature
@@ -165,7 +232,11 @@ export class JPEGDecoder {
             else if (marker === SOS) {
                 this.parseSOS();
                 this.decodeScan();
-                break; // Stop after first scan for baseline JPEG
+                // For progressive JPEG, continue to process more scans
+                // For baseline JPEG, stop after first scan
+                if (!this.isProgressive) {
+                    break;
+                }
             }
             else if (marker === DQT) {
                 this.parseDQT();
@@ -173,11 +244,11 @@ export class JPEGDecoder {
             else if (marker === DHT) {
                 this.parseDHT();
             }
-            else if (marker === SOF0) {
+            else if (marker === SOF0 || marker === SOF2) {
+                // Parse SOF for both baseline (SOF0) and progressive (SOF2)
+                // Progressive JPEGs have the same frame header structure
                 this.parseSOF();
-            }
-            else if (marker === SOF2) {
-                throw new Error("Progressive JPEG not supported in pure JS decoder");
+                this.isProgressive = marker === SOF2;
             }
             else if (marker === DRI) {
                 this.parseDRI();
@@ -202,6 +273,20 @@ export class JPEGDecoder {
         if (this.width === 0 || this.height === 0) {
             throw new Error("Failed to decode JPEG: invalid dimensions");
         }
+        // For progressive JPEGs, perform IDCT on all blocks after all scans are complete
+        // This ensures that frequency-domain coefficients from multiple scans are properly
+        // accumulated before transformation to spatial domain
+        if (this.isProgressive) {
+            for (const component of this.components) {
+                if (component.blocks) {
+                    for (const row of component.blocks) {
+                        for (const block of row) {
+                            this.idct(block);
+                        }
+                    }
+                }
+            }
+        }
         // Convert YCbCr to RGB
         return this.convertToRGB();
     }
@@ -238,7 +323,7 @@ export class JPEGDecoder {
             if (precision !== 0) {
                 throw new Error("16-bit quantization tables not supported");
             }
-            const table = new Array(64);
+            const table = new Uint8Array(64);
             for (let i = 0; i < 64; i++) {
                 table[ZIGZAG[i]] = this.data[this.pos++];
             }
@@ -252,13 +337,13 @@ export class JPEGDecoder {
             const info = this.data[this.pos++];
             const tableId = info & 0x0F;
             const tableClass = (info >> 4) & 0x0F;
-            const bits = new Array(16);
+            const bits = new Uint8Array(16);
             let numSymbols = 0;
             for (let i = 0; i < 16; i++) {
                 bits[i] = this.data[this.pos++];
                 numSymbols += bits[i];
             }
-            const huffVal = new Array(numSymbols);
+            const huffVal = new Uint8Array(numSymbols);
             for (let i = 0; i < numSymbols; i++) {
                 huffVal[i] = this.data[this.pos++];
             }
@@ -273,9 +358,9 @@ export class JPEGDecoder {
         }
     }
     buildHuffmanTable(bits, huffVal) {
-        const maxCode = new Array(16).fill(-1);
-        const minCode = new Array(16).fill(-1);
-        const valPtr = new Array(16).fill(-1);
+        const maxCode = new Int32Array(16).fill(-1);
+        const minCode = new Int32Array(16).fill(-1);
+        const valPtr = new Int32Array(16).fill(-1);
         const codes = new Map();
         let code = 0;
         let valIndex = 0;
@@ -329,16 +414,26 @@ export class JPEGDecoder {
     parseSOS() {
         const _length = this.readUint16();
         const numComponents = this.data[this.pos++];
+        // Track which components are included in this scan
+        this.scanComponentIds = [];
         for (let i = 0; i < numComponents; i++) {
             const id = this.data[this.pos++];
             const tables = this.data[this.pos++];
+            this.scanComponentIds.push(id);
             const component = this.components.find((c) => c.id === id);
             if (component) {
                 component.dcTable = (tables >> 4) & 0x0F;
                 component.acTable = tables & 0x0F;
             }
         }
-        this.pos += 3; // Skip spectral selection and successive approximation
+        // Parse spectral selection and successive approximation parameters
+        // These are used in progressive JPEGs to define which coefficients
+        // are encoded and at what bit precision
+        this.spectralStart = this.data[this.pos++]; // Ss: Start of spectral selection (0-63)
+        this.spectralEnd = this.data[this.pos++]; // Se: End of spectral selection (0-63)
+        const successiveApprox = this.data[this.pos++];
+        this.successiveHigh = (successiveApprox >> 4) & 0x0F; // Ah: Successive approximation bit position high
+        this.successiveLow = successiveApprox & 0x0F; // Al: Successive approximation bit position low
     }
     parseDRI() {
         const _length = this.readUint16();
@@ -350,108 +445,360 @@ export class JPEGDecoder {
         const maxV = Math.max(...this.components.map((c) => c.v));
         const mcuWidth = Math.ceil(this.width / (8 * maxH));
         const mcuHeight = Math.ceil(this.height / (8 * maxV));
-        // Initialize bit buffer
+        // Initialize bit buffer for this scan
         this.bitBuffer = 0;
         this.bitCount = 0;
-        // Initialize blocks for each component
+        // Reset DC predictors and EOB run at the start of each scan (JPEG spec requirement)
+        this.eobRun = 0;
         for (const component of this.components) {
-            const blocksAcross = Math.ceil(this.width * component.h / (8 * maxH));
-            const blocksDown = Math.ceil(this.height * component.v / (8 * maxV));
-            component.blocks = Array(blocksDown).fill(null).map(() => Array(blocksAcross).fill(null).map(() => new Array(64).fill(0)));
-        }
-        // Decode MCUs
-        try {
-            for (let mcuY = 0; mcuY < mcuHeight; mcuY++) {
-                for (let mcuX = 0; mcuX < mcuWidth; mcuX++) {
-                    // Decode all components in this MCU
-                    for (const component of this.components) {
-                        for (let v = 0; v < component.v; v++) {
-                            for (let h = 0; h < component.h; h++) {
-                                const blockY = mcuY * component.v + v;
-                                const blockX = mcuX * component.h + h;
-                                if (blockY < component.blocks.length &&
-                                    blockX < component.blocks[0].length) {
-                                    this.decodeBlock(component, blockY, blockX);
-                                }
+            component.pred = 0;
+        }
+        // Initialize or preserve blocks for each component
+        // For progressive JPEGs, blocks must be preserved across multiple scans
+        // to accumulate coefficients from different spectral bands and bit refinements
+        for (const component of this.components) {
+            const blocksAcross = mcuWidth * component.h;
+            const blocksDown = mcuHeight * component.v;
+            // Only initialize blocks if they don't exist yet (first scan)
+            // Check both for undefined/null and empty array
+            if (!component.blocks || component.blocks.length === 0) {
+                component.blocks = Array(blocksDown).fill(null).map(() => Array(blocksAcross).fill(null).map(() => new Int32Array(64)));
+            }
+        }
+        // Decode entropy-coded data.
+        // JPEG defines different MCU sequencing for interleaved vs non-interleaved scans.
+        // For single-component (non-interleaved) scans, the entropy-coded stream is ordered
+        // as a simple raster over that component's block grid; decoding in interleaved MCU
+        // order can permute blocks and produce artifacts that look like half-width duplication.
+        if (this.scanComponentIds.length === 1) {
+            const componentId = this.scanComponentIds[0];
+            const component = this.components.find((c) => c.id === componentId);
+            if (!component)
+                return;
+            const blocksAcross = mcuWidth * component.h;
+            const blocksDown = mcuHeight * component.v;
+            for (let blockY = 0; blockY < blocksDown; blockY++) {
+                for (let blockX = 0; blockX < blocksAcross; blockX++) {
+                    if (blockY >= component.blocks.length ||
+                        blockX >= component.blocks[0].length) {
+                        continue;
+                    }
+                    if (this.options.tolerantDecoding) {
+                        try {
+                            this.decodeBlock(component, blockY, blockX);
+                        }
+                        catch (e) {
+                            if (e instanceof EndOfScanError) {
+                                return;
+                            }
+                        }
+                    }
+                    else {
+                        try {
+                            this.decodeBlock(component, blockY, blockX);
+                        }
+                        catch (e) {
+                            if (e instanceof EndOfScanError) {
+                                return;
                             }
+                            throw e;
                         }
                     }
                 }
             }
+            return;
         }
-        catch (e) {
-            // If we run into issues during decoding, we may still have partial data
-            console.warn("JPEG decode warning:", e);
+        // Interleaved scan: MCU order with per-component sampling factors.
+        outerLoop: for (let mcuY = 0; mcuY < mcuHeight; mcuY++) {
+            for (let mcuX = 0; mcuX < mcuWidth; mcuX++) {
+                for (const component of this.components) {
+                    if (this.scanComponentIds.length > 0 &&
+                        !this.scanComponentIds.includes(component.id)) {
+                        continue;
+                    }
+                    for (let v = 0; v < component.v; v++) {
+                        for (let h = 0; h < component.h; h++) {
+                            const blockY = mcuY * component.v + v;
+                            const blockX = mcuX * component.h + h;
+                            if (blockY < component.blocks.length &&
+                                blockX < component.blocks[0].length) {
+                                if (this.options.tolerantDecoding) {
+                                    try {
+                                        this.decodeBlock(component, blockY, blockX);
+                                    }
+                                    catch (e) {
+                                        if (e instanceof EndOfScanError) {
+                                            break outerLoop;
+                                        }
+                                    }
+                                }
+                                else {
+                                    try {
+                                        this.decodeBlock(component, blockY, blockX);
+                                    }
+                                    catch (e) {
+                                        if (e instanceof EndOfScanError) {
+                                            break outerLoop;
+                                        }
+                                        throw e;
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     }
     decodeBlock(component, blockY, blockX) {
         const block = component.blocks[blockY][blockX];
-        // Decode DC coefficient
-        const dcTable = this.dcTables[component.dcTable];
-        if (!dcTable) {
-            throw new Error(`Missing DC table ${component.dcTable}`);
-        }
-        const dcLen = this.decodeHuffman(dcTable);
-        const dcDiff = dcLen > 0 ? this.receiveBits(dcLen) : 0;
-        component.pred += dcDiff;
-        block[0] = component.pred * this.qTables[component.qTable][0];
-        // Decode AC coefficients
-        const acTable = this.acTables[component.acTable];
-        if (!acTable) {
-            throw new Error(`Missing AC table ${component.acTable}`);
-        }
-        let k = 1;
-        while (k < 64) {
-            const rs = this.decodeHuffman(acTable);
-            const r = (rs >> 4) & 0x0F;
-            const s = rs & 0x0F;
-            if (s === 0) {
-                if (r === 15) {
-                    k += 16;
+        // EOB run handling (progressive JPEG AC scans):
+        // - In first AC scans (Ah=0), an EOB run means the following blocks have no new
+        //   coefficients in the current spectral band and can be skipped entirely.
+        // - In AC refinement scans (Ah>0), blocks in an EOB run STILL contain refinement
+        //   bits for existing non-zero coefficients; skipping would desynchronize the bitstream.
+        const isACScan = this.spectralEnd > 0 && this.spectralStart > 0;
+        const isACRefinementScan = isACScan && this.successiveHigh > 0;
+        if (isACScan && !isACRefinementScan && this.eobRun > 0) {
+            this.eobRun--;
+            // Block remains as-is (zeros or previous values from earlier scans)
+            return;
+        }
+        // Progressive JPEG support:
+        // - Spectral selection (spectralStart, spectralEnd): Defines which DCT coefficients are decoded
+        //   * DC only: Ss=0, Se=0
+        //   * Low-frequency AC: Ss=1, Se=5
+        //   * High-frequency AC: Ss=6, Se=63
+        // - Successive approximation (successiveHigh, successiveLow): Defines bit precision
+        //   * First scan: Ah=0, Al=n (decode high bits, shift left by Al)
+        //   * Refinement scan: Ah=n, Al=n-1 (refine lower bits by adding bit at position Al)
+        //
+        // Implementation: Processes scans sequentially, accumulating coefficients across
+        // multiple scans. Supports full successive approximation bit refinement for both
+        // DC and AC coefficients. IDCT is deferred until all scans complete to preserve
+        // frequency-domain data for proper accumulation.
+        // Decode DC coefficient (if spectralStart == 0)
+        if (this.spectralStart === 0) {
+            const dcTable = this.dcTables[component.dcTable];
+            if (!dcTable) {
+                throw new Error(`Missing DC table ${component.dcTable}`);
+            }
+            if (this.successiveHigh === 0) {
+                // First DC scan: decode the DC coefficient
+                const dcLen = this.decodeHuffman(dcTable);
+                const dcDiff = dcLen > 0 ? this.receiveBits(dcLen) : 0;
+                component.pred += dcDiff;
+                // For successive approximation, shift the coefficient left by Al bits
+                const coeff = component.pred << this.successiveLow;
+                block[0] = coeff * this.qTables[component.qTable][0];
+            }
+            else {
+                // DC refinement scan: add a refinement bit
+                const bit = this.readBit();
+                if (bit) {
+                    // Add the refinement bit at position Al
+                    const refinement = 1 << this.successiveLow;
+                    block[0] += refinement * this.qTables[component.qTable][0];
                 }
-                else {
-                    break; // EOB
+            }
+        }
+        // Decode AC coefficients (if spectralEnd > 0)
+        // Note: For DC-only scans (Ss=0, Se=0), this block is skipped entirely
+        // For AC-only scans (Ss>0), this decodes the specified AC coefficient range
+        if (this.spectralEnd > 0) {
+            const acTable = this.acTables[component.acTable];
+            if (!acTable) {
+                throw new Error(`Missing AC table ${component.acTable}`);
+            }
+            if (this.successiveHigh === 0) {
+                // First AC scan: decode new coefficients
+                // Start from spectralStart, but ensure k >= 1 (AC coefficients start at index 1)
+                let k = this.spectralStart === 0 ? 1 : this.spectralStart;
+                while (k <= this.spectralEnd && k < 64) {
+                    const rs = this.decodeHuffman(acTable);
+                    const r = (rs >> 4) & 0x0F;
+                    const s = rs & 0x0F;
+                    if (s === 0) {
+                        if (r === 15) {
+                            k += 16;
+                        }
+                        else {
+                            // EOB or EOBn (end of block, possibly with run length)
+                            // EOBn is ONLY used in progressive JPEG with spectral selection
+                            // For baseline JPEG, (r,0) where r!=0,15 should not occur
+                            if (this.isProgressive && r > 0) {
+                                // Progressive JPEG: EOBn with additional unsigned bits
+                                // Formula: eobRun = (1 << r) - 1 + additionalBits
+                                // This specifies how many ADDITIONAL blocks (after current) to skip
+                                const additionalBits = this.receiveUnsignedBits(r);
+                                this.eobRun = (1 << r) - 1 + additionalBits;
+                            }
+                            // For both baseline and progressive: end current block
+                            break;
+                        }
+                    }
+                    else {
+                        k += r;
+                        // Check bounds: if k exceeds spectralEnd, stop decoding
+                        // (spectralEnd is guaranteed to be <= 63 per JPEG spec)
+                        if (k > this.spectralEnd)
+                            break;
+                        // For successive approximation, shift the coefficient left by Al bits
+                        const coeff = this.receiveBits(s) << this.successiveLow;
+                        block[ZIGZAG[k]] = coeff *
+                            this.qTables[component.qTable][ZIGZAG[k]];
+                        k++;
+                    }
                 }
             }
             else {
-                k += r;
-                if (k >= 64)
-                    break;
-                block[ZIGZAG[k]] = this.receiveBits(s) *
-                    this.qTables[component.qTable][ZIGZAG[k]];
-                k++;
+                const qTable = this.qTables[component.qTable];
+                const hadEobRunAtStart = this.eobRun > 0;
+                let successiveACState = hadEobRunAtStart ? 4 : 0;
+                let successiveACNextValue = 0;
+                let runLength = 0;
+                let kk = this.spectralStart === 0 ? 1 : this.spectralStart;
+                while (kk <= this.spectralEnd && kk < 64) {
+                    const z = ZIGZAG[kk];
+                    const current = block[z];
+                    const direction = current < 0 ? -1 : 1;
+                    switch (successiveACState) {
+                        case 0: {
+                            const rs = this.decodeHuffman(acTable);
+                            const realR = (rs >> 4) & 0x0f;
+                            const realS = rs & 0x0f;
+                            if (realS === 0) {
+                                if (realR < 15) {
+                                    const additionalBits = this.receiveUnsignedBits(realR);
+                                    this.eobRun = (1 << realR) - 1 + additionalBits;
+                                    successiveACState = 4;
+                                }
+                                else {
+                                    runLength = 16;
+                                    successiveACState = 1;
+                                }
+                            }
+                            else {
+                                if (realS !== 1) {
+                                    throw new Error("Invalid AC refinement size");
+                                }
+                                successiveACNextValue = this.receiveBits(realS);
+                                runLength = realR;
+                                successiveACState = realR ? 2 : 3;
+                            }
+                            continue;
+                        }
+                        case 1:
+                        case 2:
+                            if (current !== 0) {
+                                const bit = this.readBit();
+                                if (bit) {
+                                    const refinement = (1 << this.successiveLow) * qTable[z];
+                                    block[z] += direction * refinement;
+                                }
+                            }
+                            else {
+                                runLength--;
+                                if (runLength === 0) {
+                                    successiveACState = successiveACState === 2 ? 3 : 0;
+                                }
+                            }
+                            break;
+                        case 3:
+                            if (current !== 0) {
+                                const bit = this.readBit();
+                                if (bit) {
+                                    const refinement = (1 << this.successiveLow) * qTable[z];
+                                    block[z] += direction * refinement;
+                                }
+                            }
+                            else {
+                                const newCoeff = successiveACNextValue << this.successiveLow;
+                                block[z] = newCoeff * qTable[z];
+                                successiveACState = 0;
+                            }
+                            break;
+                        case 4:
+                            if (current !== 0) {
+                                const bit = this.readBit();
+                                if (bit) {
+                                    const refinement = (1 << this.successiveLow) * qTable[z];
+                                    block[z] += direction * refinement;
+                                }
+                            }
+                            break;
+                    }
+                    kk++;
+                }
+                // Only consume one EOB-run block here if we started this block already within
+                // an existing EOB run. If we *encountered* an EOBn symbol in this block, the
+                // run applies to subsequent blocks (per our eobRun convention).
+                if (successiveACState === 4 && hadEobRunAtStart && this.eobRun > 0) {
+                    this.eobRun--;
+                }
             }
         }
-        // Perform IDCT
-        this.idct(block);
+        // Perform IDCT only for baseline JPEGs
+        // For progressive JPEGs, IDCT is deferred until all scans are complete
+        // to preserve frequency-domain coefficients for accumulation across scans
+        if (!this.isProgressive) {
+            this.idct(block);
+        }
     }
     decodeHuffman(table) {
+        // Use table-based decoding (more reliable)
         let code = 0;
         for (let len = 0; len < 16; len++) {
             code = (code << 1) | this.readBit();
             if (table.minCode[len] !== -1 && code <= table.maxCode[len]) {
                 const index = table.valPtr[len] + (code - table.minCode[len]);
-                return table.huffVal[index];
+                if (index >= 0 && index < table.huffVal.length) {
+                    return table.huffVal[index];
+                }
+                else {
+                    throw new Error(`Huffman table index out of bounds: ${index} (table size: ${table.huffVal.length})`);
+                }
             }
         }
         throw new Error("Invalid Huffman code");
     }
     readBit() {
         if (this.bitCount === 0) {
-            let byte = this.data[this.pos++];
-            // Handle byte stuffing (0xFF 0x00)
+            // Check bounds
+            if (this.pos >= this.data.length) {
+                throw new Error("Unexpected end of JPEG data");
+            }
+            const byte = this.data[this.pos++];
+            // Handle byte stuffing (0xFF 0x00) and restart markers
             if (byte === 0xFF) {
+                if (this.pos >= this.data.length) {
+                    throw new Error("Unexpected end of JPEG data after 0xFF");
+                }
                 const nextByte = this.data[this.pos];
                 if (nextByte === 0x00) {
+                    // Byte stuffing - skip the 0x00
+                    // The 0xFF byte value is used as-is (already assigned above)
                     this.pos++;
                 }
                 else if (nextByte >= 0xD0 && nextByte <= 0xD7) {
-                    // Restart marker - reset DC predictors
-                    this.pos++;
+                    // Restart marker - reset DC predictors and bit stream
+                    this.pos++; // Skip marker type byte
                     for (const component of this.components) {
                         component.pred = 0;
                     }
-                    byte = this.data[this.pos++];
+                    // Progressive AC refinement uses EOB runs; restart markers reset EOBRUN as well.
+                    this.eobRun = 0;
+                    // Reset bit stream (restart markers are byte-aligned)
+                    this.bitBuffer = 0;
+                    this.bitCount = 0;
+                    // Recursively call readBit to get the next bit after restart
+                    return this.readBit();
+                }
+                else {
+                    // Other marker found in scan data - this indicates end of scan
+                    // Back up to before the marker
+                    this.pos--;
+                    throw new EndOfScanError();
                 }
             }
             this.bitBuffer = byte;
@@ -471,10 +818,24 @@ export class JPEGDecoder {
         }
         return value;
     }
+    receiveUnsignedBits(n) {
+        // Read n bits as an unsigned integer (no magnitude conversion)
+        // Input validation: n should be between 0 and 16
+        if (n < 0 || n > 16) {
+            throw new Error(`Invalid bit count: ${n} (must be 0-16)`);
+        }
+        if (n === 0)
+            return 0;
+        let value = 0;
+        for (let i = 0; i < n; i++) {
+            value = (value << 1) | this.readBit();
+        }
+        return value;
+    }
     idct(block) {
         // Simplified 2D IDCT
         // This is a basic implementation - not optimized
-        const temp = new Array(64);
+        const temp = new Float32Array(64);
         // 1D IDCT on rows
         for (let i = 0; i < 8; i++) {
             const offset = i * 8;
@@ -531,10 +892,14 @@ export class JPEGDecoder {
             for (let row = 0; row < this.height; row++) {
                 for (let col = 0; col < this.width; col++) {
                     // Y component
-                    const yBlockRow = Math.floor(row / 8);
-                    const yBlockCol = Math.floor(col / 8);
-                    const yBlockY = row % 8;
-                    const yBlockX = col % 8;
+                    // Scale pixel position by component sampling factors to get correct block position
+                    // This is necessary when component has h>1 or v>1 (e.g., 4:2:0 chroma subsampling)
+                    const yRow = Math.floor(row * y.v / maxV);
+                    const yCol = Math.floor(col * y.h / maxH);
+                    const yBlockRow = Math.floor(yRow / 8);
+                    const yBlockCol = Math.floor(yCol / 8);
+                    const yBlockY = yRow % 8;
+                    const yBlockX = yCol % 8;
                     let yVal = 0;
                     if (yBlockRow < y.blocks.length && yBlockCol < y.blocks[0].length) {
                         yVal = y.blocks[yBlockRow][yBlockCol][yBlockY * 8 + yBlockX];