qr 0.5.4 → 0.6.0

package/decode.js

@@ -17,22 +17,35 @@ limitations under the License.
 /**
  * Methods for decoding (reading) QR code patterns.
  * @module
- * @example
-```js
-
-```
  */
 import { Bitmap, utils } from "./index.js";
-const { best, bin, drawTemplate, fillArr, info, interleave, validateVersion, zigzag, popcnt } = utils;
 // Constants
 const MAX_BITS_ERROR = 3; // Up to 3 bit errors in version/format
+// Kept at 8: the block-stat fast path reads two u32 words per row and the
+// average uses `sum >>> 6`, so the current binarizer assumes 8x8 = 64 pixels.
 const GRAYSCALE_BLOCK_SIZE = 8;
 const GRAYSCALE_RANGE = 24;
 const PATTERN_VARIANCE = 2;
+// Diagonal finder scans are noisier under blur/perspective than horizontal or
+// vertical runs, so they use a looser ratio tolerance.
 const PATTERN_VARIANCE_DIAGONAL = 1.333;
 const PATTERN_MIN_CONFIRMATIONS = 2;
 const DETECT_MIN_ROW_SKIP = 3;
+// Pair LUTs for the 8x8 block-stat fast path: each 16-bit lane holds two
+// brightness bytes, so we can accumulate sum/min/max four pixels at a time.
+const SUM16 = new Uint16Array(1 << 16);
+const MIN16 = new Uint8Array(1 << 16);
+const MAX16 = new Uint8Array(1 << 16);
+for (let i = 0; i < SUM16.length; i++) {
+    const lo = i & 0xff;
+    const hi = i >>> 8;
+    SUM16[i] = lo + hi;
+    MIN16[i] = lo < hi ? lo : hi;
+    MAX16[i] = lo > hi ? lo : hi;
+}
 // TODO: move to index, nearby with bitmap and other graph related stuff?
+// Fast truncation for values expected to be non-negative; negatives would wrap
+// through uint32 because this uses `>>> 0`, not `Math.floor()`.
 const int = (n) => n >>> 0;
 // distance ^ 2
 const distance2 = (p1, p2) => {
@@ -51,37 +64,145 @@ const pointMirror = (p) => ({ x: p.y, y: p.x });
 const pointClone = (p) => ({ x: p.x, y: p.y });
 const pointInt = (p) => ({ x: int(p.x), y: int(p.y) });
 const pointAdd = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+// Count trailing zeroes in a packed bitmap word so scanLine can skip whole
+// runs instead of testing one bit at a time.
+const ctz32 = (v) => {
+    v = v >>> 0;
+    if (v === 0)
+        return 32;
+    return 31 - Math.clz32((v & -v) >>> 0);
+};
 function cap(value, min, max) {
-    return Math.max(Math.min(value, max || value), min || value);
+    // ISO/IEC 18004:2024 §12 h) builds the sampling grid from "module centres";
+    // detector callers pass `0` as a real image edge when clipping those samples
+    // and search windows. `|| value` treats that bound as absent.
+    let res = value;
+    if (max !== undefined)
+        res = Math.min(res, max);
+    if (min !== undefined)
+        res = Math.max(res, min);
+    return res;
 }
-const getBytesPerPixel = (img) => {
-    const perPixel = img.data.length / (img.width * img.height);
+function getBytesPerPixel(img) {
+    const image = img;
+    const perPixel = image.data.length / (image.width * image.height);
     if (perPixel === 3 || perPixel === 4)
         return perPixel; // RGB or RGBA
     throw new Error(`Unknown image format, bytes per pixel=${perPixel}`);
-};
+}
+function isBytes(data) {
+    return data instanceof Uint8Array || data instanceof Uint8ClampedArray;
+}
 /**
  * Convert to grayscale. The function is the most expensive part of decoding:
- * it takes up to 90% of time. TODO: check gamma correction / sqr.
+ * it takes up to 90% of time.
+ *
+ * Binarization pipeline:
+ * 1. Convert RGB/RGBA image to one luma byte per pixel.
+ * 2. Split the image into 8x8 blocks and collect per-block mean/min/max.
+ * 3. Build a 5x5 neighborhood mean over those block means.
+ * 4. Turn each 8x8 block into bitmap bits using a local cut derived from:
+ *    - the neighborhood mean,
+ *    - the current block statistics,
+ *    - a cheap whole-image color-spread estimate,
+ *    - and, on risky scenes, a local variance field over block means.
+ *
+ * Instead of producing "best looking" thresholding: we produce a
+ * bitmap where finder patterns survive perspective / blur / highlights while
+ * keeping false dark regions low enough for downstream finder selection.
  */
 function toBitmap(img) {
+    const image = img;
+    const width = image.width;
+    const height = image.height;
+    const data = image.data;
     const bytesPerPixel = getBytesPerPixel(img);
-    const brightness = new Uint8Array(img.height * img.width);
-    for (let i = 0, j = 0, d = img.data; i < d.length; i += bytesPerPixel) {
-        const r = d[i];
-        const g = d[i + 1];
-        const b = d[i + 2];
-        brightness[j++] = int((r + 2 * g + b) / 4) & 0xff;
+    const pixLen = height * width;
+    const brightness = new Uint8Array(pixLen);
+    if (bytesPerPixel === 4 && isBytes(data) && (data.byteOffset & 3) === 0) {
+        // Little-endian RGBA: compute four grayscale bytes and commit as one u32 store.
+        // Unaligned RGBA subarray views are still valid inputs; they fall back to
+        // the scalar path because Uint32Array would throw on a misaligned offset.
+        const pixels = new Uint32Array(data.buffer, data.byteOffset, pixLen);
+        const bright32 = new Uint32Array(brightness.buffer, brightness.byteOffset, brightness.length >>> 2);
+        const n4 = pixels.length & ~3;
+        for (let i = 0, j = 0; i < n4; i += 4, j++) {
+            const v0 = pixels[i] >>> 0;
+            const v1 = pixels[i + 1] >>> 0;
+            const v2 = pixels[i + 2] >>> 0;
+            const v3 = pixels[i + 3] >>> 0;
+            // RGBA words are little-endian here, so this is `(r + 2*g + b) / 4`
+            // computed from the packed byte lanes for four pixels at once.
+            const b0 = ((v0 & 0xff) + (((v0 >>> 8) & 0xff) << 1) + ((v0 >>> 16) & 0xff)) >>> 2;
+            const b1 = ((v1 & 0xff) + (((v1 >>> 8) & 0xff) << 1) + ((v1 >>> 16) & 0xff)) >>> 2;
+            const b2 = ((v2 & 0xff) + (((v2 >>> 8) & 0xff) << 1) + ((v2 >>> 16) & 0xff)) >>> 2;
+            const b3 = ((v3 & 0xff) + (((v3 >>> 8) & 0xff) << 1) + ((v3 >>> 16) & 0xff)) >>> 2;
+            bright32[j] = b0 | (b1 << 8) | (b2 << 16) | (b3 << 24);
+        }
+        for (let i = n4; i < pixels.length; i++) {
+            const v = pixels[i] >>> 0;
+            brightness[i] = ((v & 0xff) + (((v >>> 8) & 0xff) << 1) + ((v >>> 16) & 0xff)) >>> 2;
+        }
     }
+    else {
+        for (let i = 0, j = 0, d = data; i < d.length; i += bytesPerPixel) {
+            const r = d[i];
+            const g = d[i + 1];
+            const b = d[i + 2];
+            brightness[j++] = int((r + 2 * g + b) / 4) & 0xff;
+        }
+    }
+    // Sampled color spread is a cheap "scene type" signal:
+    // grayscale / flat lighting scenes want conservative cuts, while colorful or
+    // high-spread scenes benefit from a slightly darker threshold.
+    let spreadSum = 0;
+    let spreadCnt = 0;
+    const spreadStep = bytesPerPixel * 16;
+    for (let i = 0; i < data.length; i += spreadStep) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        // hi=max(r,g,b), lo=min(r,g,b): this sampled channel spread is a cheap
+        // scene-level proxy for "how colorful / highlighty is this frame?".
+        const hi = r > g ? (r > b ? r : b) : g > b ? g : b;
+        const lo = r < g ? (r < b ? r : b) : g < b ? g : b;
+        spreadSum += hi - lo;
+        spreadCnt++;
+    }
+    const spreadMean = spreadSum / spreadCnt;
     // Convert to bitmap
     const block = GRAYSCALE_BLOCK_SIZE;
-    if (img.width < block * 5 || img.height < block * 5)
+    if (width < block * 5 || height < block * 5)
         throw new Error('image too small');
-    const bWidth = Math.ceil(img.width / block);
-    const bHeight = Math.ceil(img.height / block);
-    const maxY = img.height - block;
-    const maxX = img.width - block;
-    const blocks = new Uint8Array(bWidth * bHeight);
+    const bWidth = Math.ceil(width / block);
+    const bHeight = Math.ceil(height / block);
+    const maxY = height - block;
+    const maxX = width - block;
+    const blockLen = bWidth * bHeight;
+    const blockState = new Uint32Array(blockLen);
+    // Each 8x8 block stores packed:
+    // - bits 0..7: block baseline brightness used by the threshold field
+    // - bits 8..15: block min
+    // - bits 16..23: block max
+    let hiRangeCnt = 0;
+    let veryLowCnt = 0;
+    const padW = (width + 3) & ~3;
+    let statStride = width;
+    let stat32;
+    if ((width & 3) !== 0) {
+        const padLen = padW * height;
+        const brightPad = new Uint8Array(padLen);
+        for (let y = 0; y < height; y++) {
+            const src = y * width;
+            const dst = y * padW;
+            brightPad.set(brightness.subarray(src, src + width), dst);
+        }
+        // Misaligned widths are padded only for the block-stat fast path.
+        statStride = padW;
+        stat32 = new Uint32Array(brightPad.buffer, brightPad.byteOffset, (padW * height) >>> 2);
+    }
+    else
+        stat32 = new Uint32Array(brightness.buffer, brightness.byteOffset, brightness.length >>> 2);
     for (let y = 0; y < bHeight; y++) {
         const yPos = cap(y * block, 0, maxY);
         for (let x = 0; x < bWidth; x++) {
@@ -89,48 +210,248 @@ function toBitmap(img) {
             let sum = 0;
             let min = 0xff;
             let max = 0;
-            for (let yy = 0, pos = yPos * img.width + xPos; yy < block; yy = yy + 1, pos = pos + img.width) {
-                for (let xx = 0; xx < block; xx++) {
-                    const pixel = brightness[pos + xx];
-                    sum += pixel;
-                    min = Math.min(min, pixel);
-                    max = Math.max(max, pixel);
+            // The stat-LUT fast path needs the 8-pixel row start to be 32-bit aligned
+            // so each row can be read as two full u32 words without any shifts.
+            if ((xPos & 3) === 0) {
+                for (let yy = 0, pos = yPos * statStride + xPos; yy < block; yy++, pos += statStride) {
+                    const p = pos >>> 2;
+                    const w0 = stat32[p] >>> 0;
+                    const w1 = stat32[p + 1] >>> 0;
+                    const a0 = w0 & 0xffff;
+                    const a1 = w0 >>> 16;
+                    const b0 = w1 & 0xffff;
+                    const b1 = w1 >>> 16;
+                    sum += SUM16[a0] + SUM16[a1] + SUM16[b0] + SUM16[b1];
+                    const min0 = MIN16[a0];
+                    const min1 = MIN16[a1];
+                    const min2 = MIN16[b0];
+                    const min3 = MIN16[b1];
+                    if (min0 < min)
+                        min = min0;
+                    if (min1 < min)
+                        min = min1;
+                    if (min2 < min)
+                        min = min2;
+                    if (min3 < min)
+                        min = min3;
+                    const max0 = MAX16[a0];
+                    const max1 = MAX16[a1];
+                    const max2 = MAX16[b0];
+                    const max3 = MAX16[b1];
+                    if (max0 > max)
+                        max = max0;
+                    if (max1 > max)
+                        max = max1;
+                    if (max2 > max)
+                        max = max2;
+                    if (max3 > max)
+                        max = max3;
                 }
             }
+            else {
+                for (let yy = 0, pos = yPos * width + xPos; yy < block; yy++, pos += width) {
+                    for (let xx = 0; xx < block; xx++) {
+                        const pixel = brightness[pos + xx];
+                        sum += pixel;
+                        if (pixel < min)
+                            min = pixel;
+                        if (pixel > max)
+                            max = pixel;
+                    }
+                }
+            }
+            const bIdx = bWidth * y + x;
+            const range = max - min;
             // Average brightness of block
-            let average = Math.floor(sum / block ** 2);
-            if (max - min <= GRAYSCALE_RANGE) {
+            let average = sum >>> 6;
+            if (range <= GRAYSCALE_RANGE) {
+                // Low-contrast blocks are unstable if we threshold from their raw mean.
+                // Bias toward the local dark floor, then smooth with already-seen
+                // neighbors so finder rings don't disappear in washed-out regions.
                 average = min / 2;
                 if (y > 0 && x > 0) {
                     const idx = (x, y) => y * bWidth + x;
-                    const prev = (blocks[idx(x, y - 1)] + 2 * blocks[idx(x - 1, y)] + blocks[idx(x - 1, y - 1)]) / 4;
-                    if (min < prev)
-                        average = prev;
+                    const neighborNumerator = (blockState[idx(x, y - 1)] & 0xff) +
+                        2 * (blockState[idx(x - 1, y)] & 0xff) +
+                        (blockState[idx(x - 1, y - 1)] & 0xff);
+                    if (min * 4 < neighborNumerator)
+                        average = neighborNumerator / 4;
                 }
             }
-            blocks[bWidth * y + x] = int(average);
+            blockState[bIdx] = int(average) | (min << 8) | (max << 16);
+            if (range > 40 && average < 224)
+                hiRangeCnt++;
+            if (range <= 10)
+                veryLowCnt++;
         }
     }
-    const matrix = new Bitmap({ width: img.width, height: img.height });
+    const hiRangeFrac = hiRangeCnt / blockLen;
+    const veryLowFrac = veryLowCnt / blockLen;
+    // These two scene gates are the main "policy" layer on top of the local cut:
+    // - `spotBias` darkens globally flat, slightly colorful scenes that otherwise
+    //   miss bright-spot / washed-out QR modules.
+    // - `useVarField` avoids paying the variance-field cost on scenes where the
+    //   plain 5x5 mean is already stable enough.
+    const spotBias = veryLowFrac > 0.55 &&
+        veryLowFrac < 0.66 &&
+        hiRangeFrac < 0.02 &&
+        spreadMean > 10 &&
+        spreadMean < 20
+        ? -1
+        : 0;
+    const useVarField = veryLowFrac < 0.62 || spreadMean > 30;
+    const iWidth = bWidth + 1;
+    const iHeight = bHeight + 1;
+    const integLen = iHeight * iWidth;
+    // `integ` is the standard summed-area table of block means.
+    const integ = new Uint32Array(integLen);
+    // `integSqr` is the square-integral / summed-area table of `v * v` over the
+    // same block means, not a u8 pixel buffer. Those prefix sums can overflow
+    // 32-bit integer storage on large images, and Float32 was the measured
+    // faster compromise vs Float64 for this heuristic field.
+    const integSqr = useVarField ? new Float32Array(integLen) : undefined;
+    for (let y = 0; y < bHeight; y++) {
+        let rowSum = 0;
+        let rowSq = 0;
+        const bRow = y * bWidth;
+        const iRow = (y + 1) * iWidth;
+        const iPrev = y * iWidth;
+        for (let x = 0; x < bWidth; x++) {
+            const v = blockState[bRow + x] & 0xff;
+            rowSum += v;
+            if (integSqr)
+                rowSq += v * v;
+            integ[iRow + x + 1] = integ[iPrev + x + 1] + rowSum;
+            if (integSqr)
+                integSqr[iRow + x + 1] = integSqr[iPrev + x + 1] + rowSq;
+        }
+    }
+    const matrix = new Bitmap({ width, height });
+    const rows = Math.ceil(width / 32);
+    // Decode intentionally writes the packed bitmap words directly here. The
+    // per-pixel Bitmap API is too expensive on this hot path, so this must stay
+    // in sync with Bitmap's internal `value` layout.
+    const bm = matrix.value;
+    const rad = 2;
+    const win = rad * 2 + 1;
+    const area = win * win;
     for (let y = 0; y < bHeight; y++) {
         const yPos = cap(y * block, 0, maxY);
-        const top = cap(y, 2, bHeight - 3);
+        const top = cap(y, rad, bHeight - rad - 1);
+        const y0 = top - rad;
+        const y1 = top + rad;
+        const r0 = y0 * iWidth;
+        const r1 = (y1 + 1) * iWidth;
         for (let x = 0; x < bWidth; x++) {
             const xPos = cap(x * block, 0, maxX);
-            const left = cap(x, 2, bWidth - 3);
+            const shift = xPos & 31;
+            const col = xPos >>> 5;
+            const left = cap(x, rad, bWidth - rad - 1);
+            const x0 = left - rad;
+            const x1 = left + rad;
             // 5x5 blocks average
-            let sum = 0;
-            for (let yy = -2; yy <= 2; yy++) {
-                const y2 = bWidth * (top + yy) + left;
-                for (let xx = -2; xx <= 2; xx++)
-                    sum += blocks[y2 + xx];
-            }
-            const average = sum / 25;
-            for (let y = 0, pos = yPos * img.width + xPos; y < block; y += 1, pos += img.width) {
-                for (let x = 0; x < block; x++) {
-                    if (brightness[pos + x] <= average)
-                        matrix.set(xPos + x, yPos + y, true);
+            const sum = integ[r1 + (x1 + 1)] - integ[r0 + (x1 + 1)] - integ[r1 + x0] + integ[r0 + x0];
+            // `average` is the coarse threshold surface: a 5x5 neighborhood mean of
+            // the 8x8 block means. The adjustments below decide when to move away
+            // from that surface for the current block.
+            const average = (sum / area) | 0;
+            let cut = average;
+            const bIdx = bWidth * y + x;
+            const blk = blockState[bIdx];
+            const blockAvg = blk & 0xff;
+            const min = (blk >>> 8) & 0xff;
+            const max = blk >>> 16;
+            const range = max - min;
+            if (average < min)
+                continue;
+            if (average >= max) {
+                const m = 0xff;
+                for (let yy = 0, row = yPos * rows + col; yy < block; yy++, row += rows) {
+                    const lo = (m << shift) >>> 0;
+                    bm[row] |= lo;
+                    if (shift > 24)
+                        bm[row + 1] |= m >>> (32 - shift);
                 }
+                continue;
+            }
+            // `localAdj`: nudge toward the current block when it is darker than
+            // its neighborhood. This helps preserve dark rings / modules that are
+            // locally meaningful but diluted by the 5x5 field.
+            let localAdj = (blockAvg - average) >> 4;
+            if (localAdj < 0)
+                localAdj = 0;
+            if (localAdj > 1)
+                localAdj = 1;
+            // `chromaAdj`: in colorful, mid-tone blocks, slight extra darkening
+            // helps where luma alone underestimates QR structure.
+            let chromaAdj = 0;
+            if (range > 6 && average > 48 && average < 232) {
+                const spreadBoost = spreadMean > 8 ? spreadMean - 8 : 0;
+                const mid = 128 - Math.abs(average - 128);
+                chromaAdj = int((spreadBoost * (range - 6) * mid) / 2200000);
+                if (chromaAdj > 1)
+                    chromaAdj = 1;
+            }
+            // `varAdj`: if the surrounding block field has real variance, darken
+            // more aggressively when the local mean still sits far above the
+            // block minimum. This is what rescues many weak finder cases.
+            let varAdj = 0;
+            if (integSqr && range >= 6 && range <= 128) {
+                const sq = integSqr[r1 + (x1 + 1)] - integSqr[r0 + (x1 + 1)] - integSqr[r1 + x0] + integSqr[r0 + x0];
+                const meanSq = sq / area;
+                let variance = meanSq - average * average;
+                if (variance < 0)
+                    variance = 0;
+                const gap = average - min;
+                const num = gap * (variance - 196);
+                const den = (variance + 832) * 9;
+                // `variance` is clamped non-negative, so `den` stays strictly positive.
+                varAdj = int(num / den);
+                if (varAdj < -1)
+                    varAdj = -1;
+                if (varAdj > 4)
+                    varAdj = 4;
+            }
+            cut = average + localAdj + chromaAdj + varAdj;
+            // Small scene-level nudges are intentionally separate from the three
+            // local terms above: they are cheap and only target known whole-scene
+            // failure modes such as washed-out bright-spot images.
+            if (spreadMean > 10 && range >= 8 && range <= 96 && average > min + 8 && average < 192)
+                cut++;
+            if (veryLowFrac > 0.68 && veryLowFrac < 0.86 && range >= 6 && range <= 20 && average < 196)
+                cut++;
+            cut += spotBias;
+            if (cut < min)
+                cut = min;
+            if (cut > max)
+                cut = max;
+            // Emit one 8-pixel row of the current 8x8 block: compare against the
+            // block cut, pack the 8 black/white decisions into one byte, then OR
+            // that byte into the bitmap word(s) at the current x-bit offset.
+            for (let yy = 0, pos = yPos * width + xPos, row = yPos * rows + col; yy < block; yy++, pos += width, row += rows) {
+                let m = 0;
+                if (brightness[pos] <= cut)
+                    m |= 1;
+                if (brightness[pos + 1] <= cut)
+                    m |= 2;
+                if (brightness[pos + 2] <= cut)
+                    m |= 4;
+                if (brightness[pos + 3] <= cut)
+                    m |= 8;
+                if (brightness[pos + 4] <= cut)
+                    m |= 16;
+                if (brightness[pos + 5] <= cut)
+                    m |= 32;
+                if (brightness[pos + 6] <= cut)
+                    m |= 64;
+                if (brightness[pos + 7] <= cut)
+                    m |= 128;
+                if (m === 0)
+                    continue;
+                const lo = (m << shift) >>> 0;
+                bm[row] |= lo;
+                if (shift > 24)
+                    bm[row + 1] |= m >>> (32 - shift);
             }
         }
     }
@@ -161,7 +482,7 @@ const patternsConfirmed = (lst) => lst.filter((i) => i.count >= PATTERN_MIN_CONF
  * @returns
  */
 function pattern(p, size) {
-    const _size = size || fillArr(p.length, 1);
+    const _size = size || utils.fillArr(p.length, 1);
     if (p.length !== _size.length)
         throw new Error('invalid pattern');
     if (!(p.length & 1))
@@ -171,7 +492,7 @@ function pattern(p, size) {
         length: p.length,
         pattern: p,
         size: _size,
-        runs: () => fillArr(p.length, 0),
+        runs: () => utils.fillArr(p.length, 0),
         totalSize: sum(_size),
         total: (runs) => runs.reduce((acc, i) => acc + i),
         shift: (runs, n) => {
@@ -189,7 +510,11 @@ function pattern(p, size) {
             return true;
         },
         add(out, x, y, total) {
-            const moduleSize = total / FINDER.totalSize;
+            // ISO/IEC 18004:2024 §5.3.3.1 gives finder runs as "1:1:3:1:1";
+            // §5.3.6 defines alignment as "5 x 5 dark modules", "3 x 3 light
+            // modules", and a central dark module. Use this pattern's own run width
+            // so alignment candidates are not divided by finder width 7.
+            const moduleSize = total / res.totalSize;
             const cur = { x, y, moduleSize, count: 1 };
             for (let idx = 0; idx < out.length; idx++) {
                 const f = out[idx];
@@ -207,11 +532,12 @@ function pattern(p, size) {
             return end;
         },
         check(b, runs, center, incr, maxCount) {
+            const bm = b;
             let j = 0;
             let i = pointClone(center);
             const neg = pointNeg(incr);
             const check = (p, step) => {
-                for (; b.isInside(i) && !!b.point(i) === res.pattern[p]; pointIncr(i, step)) {
+                for (; bm.isInside(i) && !!bm.point(i) === res.pattern[p]; pointIncr(i, step)) {
                     runs[p]++;
                     j++;
                 }
@@ -234,20 +560,57 @@ function pattern(p, size) {
             return j;
         },
         scanLine(b, y, xStart, xEnd, fn) {
+            const bm = b;
             const runs = res.runs();
+            // Finder scanning also couples to Bitmap internals so it can scan packed
+            // 32-bit words directly instead of re-reading one pixel bit at a time.
+            const words = bm.words;
+            const vals = bm.value;
+            const row = y * words;
+            const pattern = res.pattern;
+            // Scan one packed bitmap row by jumping whole equal-bit runs inside 32-bit
+            // words; this keeps finder scanning from degenerating into per-pixel work.
+            const bitAt = (x) => ((vals[row + (x >>> 5)] >>> (x & 31)) & 1) === 1;
+            const runLen = (x, want) => {
+                let wi = row + (x >>> 5);
+                let bit = x & 31;
+                let w = (vals[wi] >>> bit) >>> 0;
+                let left = xEnd - x;
+                let len = 0;
+                while (left > 0) {
+                    const room = 32 - bit;
+                    let n = want ? ctz32(~w >>> 0) : ctz32(w);
+                    if (n > room)
+                        n = room;
+                    if (n > left)
+                        n = left;
+                    len += n;
+                    if (n < room && n < left)
+                        break;
+                    left -= n;
+                    if (left <= 0)
+                        break;
+                    wi++;
+                    bit = 0;
+                    w = vals[wi] >>> 0;
+                }
+                return len;
+            };
             let pos = 0;
             let x = xStart;
             // If we start in middle of an image, skip first pattern run,
             // since we don't know run length of pixels from left side
             if (xStart)
-                while (x < xEnd && !!b.get(x, y) === res.pattern[0])
-                    x++;
+                x += runLen(x, pattern[0]);
             for (; x < xEnd; x++) {
+                const cur = bitAt(x);
                 // Same run, continue counting
-                if (!!b.get(x, y) === res.pattern[pos]) {
-                    runs[pos]++;
+                if (cur === pattern[pos]) {
+                    const n = runLen(x, cur);
+                    runs[pos] += n;
+                    x += n - 1;
                     // If not last element - continue counting
-                    if (x !== b.width - 1)
+                    if (x !== bm.width - 1)
                         continue;
                     // Last element finishes run, set x outside of run
                     x++;
@@ -278,11 +641,12 @@ function pattern(p, size) {
     };
     return res;
 }
-// light/dark/light/dark/light in 1:1:3:1:1 ratio
-const FINDER = pattern([true, false, true, false, true], [1, 1, 3, 1, 1]);
-// dark/light/dark in 1:1:1 ratio
-const ALIGNMENT = pattern([false, true, false]);
+// dark/light/dark/light/dark in 1:1:3:1:1 ratio
+const FINDER = /* @__PURE__ */ pattern([true, false, true, false, true], [1, 1, 3, 1, 1]);
+// central light/dark/light runs of an alignment pattern in 1:1:1 ratio
+const ALIGNMENT = /* @__PURE__ */ pattern([false, true, false]);
 function findFinder(b) {
+    const bm = b;
     let found = [];
     function checkRuns(runs, v = 2) {
         const total = sum(runs);
@@ -294,7 +658,7 @@ function findFinder(b) {
     // Non-diagonal line (horizontal or vertical)
     function checkLine(center, maxCount, total, incr) {
         const runs = FINDER.runs();
-        let i = FINDER.check(b, runs, center, incr, maxCount);
+        let i = FINDER.check(bm, runs, center, incr, maxCount);
         if (i === false)
             return false;
         const runsTotal = sum(runs);
@@ -321,7 +685,7 @@ function findFinder(b) {
         x = xx + int(x);
         // Diagonal
         const dRuns = FINDER.runs();
-        if (!FINDER.check(b, dRuns, { x: int(x), y: int(y) }, { x: 1, y: 1 }))
+        if (!FINDER.check(bm, dRuns, { x: int(x), y: int(y) }, { x: 1, y: 1 }))
             return false;
         if (!checkRuns(dRuns, PATTERN_VARIANCE_DIAGONAL))
             return false;
@@ -330,10 +694,10 @@ function findFinder(b) {
     }
     let skipped = false;
     // Start with high skip lines count until we find first pattern
-    let ySkip = cap(int((3 * b.height) / (4 * 97)), DETECT_MIN_ROW_SKIP);
+    let ySkip = cap(int((3 * bm.height) / (4 * 97)), DETECT_MIN_ROW_SKIP);
     let done = false;
-    for (let y = ySkip - 1; y < b.height && !done; y += ySkip) {
-        FINDER.scanLine(b, y, 0, b.width, (runs, x) => {
+    for (let y = ySkip - 1; y < bm.height && !done; y += ySkip) {
+        FINDER.scanLine(bm, y, 0, bm.width, (runs, x) => {
             if (!check(runs, y, x))
                 return;
             // Found pattern
@@ -379,7 +743,7 @@ function findFinder(b) {
     if (flen < 3)
         throw new Error(`Finder: len(found) = ${flen}`);
     found.sort((i, j) => i.moduleSize - j.moduleSize);
-    const pBest = best();
+    const pBest = utils.best();
     // Qubic complexity, but we stop search when we found 3 patterns, so not a problem
     for (let i = 0; i < flen - 2; i++) {
         const fi = found[i];
@@ -429,20 +793,25 @@ function findFinder(b) {
     return { bl, tl, tr };
 }
 function findAlignment(b, est, allowanceFactor) {
+    const bm = b;
     const { moduleSize } = est;
     const allowance = int(allowanceFactor * moduleSize);
     const leftX = cap(est.x - allowance, 0);
-    const rightX = cap(est.x + allowance, undefined, b.width - 1);
+    const rightX = cap(est.x + allowance, undefined, bm.width - 1);
     const x = rightX - leftX;
     const topY = cap(est.y - allowance, 0);
-    const bottomY = cap(est.y + allowance, undefined, b.height - 1);
+    const bottomY = cap(est.y + allowance, undefined, bm.height - 1);
     const y = bottomY - topY;
     if (x < moduleSize * 3 || y < moduleSize * 3)
         throw new Error(`x = ${x}, y=${y} moduleSize = ${moduleSize}`);
     const xStart = leftX;
     const yStart = topY;
-    const width = rightX - leftX;
-    const height = bottomY - topY;
+    // ISO/IEC 18004:2024 §12 h)3 scans the alignment pattern's white-square
+    // outline from the provisional centre. `rightX` / `bottomY` are inclusive
+    // clipped image coordinates; convert them to exclusive scan bounds below so
+    // an exact 5x5 search window still includes its final row and column.
+    const width = rightX - leftX + 1;
+    const height = bottomY - topY + 1;
     const found = [];
     const xEnd = xStart + width;
     const middleY = int(yStart + height / 2);
@@ -450,14 +819,14 @@ function findAlignment(b, est, allowanceFactor) {
         const diff = int((yGen + 1) / 2);
         const y = middleY + (yGen & 1 ? -diff : diff);
         let res;
-        ALIGNMENT.scanLine(b, y, xStart, xEnd, (runs, x) => {
+        ALIGNMENT.scanLine(bm, y, xStart, xEnd, (runs, x) => {
             if (!ALIGNMENT.checkSize(runs, moduleSize))
                 return;
             const total = sum(runs);
             const xx = ALIGNMENT.toCenter(runs, x);
             // Vertical
             const rVert = ALIGNMENT.runs();
-            let v = ALIGNMENT.check(b, rVert, { x: int(xx), y }, { y: 1, x: 0 }, 2 * runs[1]);
+            let v = ALIGNMENT.check(bm, rVert, { x: int(xx), y }, { y: 1, x: 0 }, 2 * runs[1]);
             if (v === false)
                 return;
             v += y;
@@ -480,6 +849,7 @@ function findAlignment(b, est, allowanceFactor) {
     throw new Error('Alignment pattern not found');
 }
 function _single(b, from, to) {
+    const bm = b;
     // http://en.wikipedia.org/wiki/Bresenham's_line_algorithm
     let steep = false;
     let d = { x: Math.abs(to.x - from.x), y: Math.abs(to.y - from.y) };
@@ -498,8 +868,10 @@ function _single(b, from, to) {
         let real = { x, y };
         if (steep)
             real = pointMirror(real);
-        // Same as alignment pattern ([true, false, true])
-        if ((runPos === 1) === !!b.point(real)) {
+        // Starting from a dark finder center, walk until the ray crosses
+        // light -> dark -> light; `BWBRunLength()` mirrors this to recover the
+        // full finder width around the center point.
+        if ((runPos === 1) === !!bm.point(real)) {
             if (runPos === 2)
                 return distance({ x, y }, from);
             runPos++;
@@ -517,11 +889,12 @@ function _single(b, from, to) {
     return NaN;
 }
 function BWBRunLength(b, from, to) {
-    let result = _single(b, from, to);
+    const bm = b;
+    let result = _single(bm, from, to);
     let scaleY = 1.0;
     const { x: fx, y: fy } = from;
     let otherToX = fx - (to.x - fx);
-    const bw = b.width;
+    const bw = bm.width;
     if (otherToX < 0) {
         scaleY = fx / (fx - otherToX);
         otherToX = 0;
@@ -530,9 +903,15 @@ function BWBRunLength(b, from, to) {
         scaleY = (bw - 1 - fx) / (otherToX - fx);
         otherToX = bw - 1;
     }
+    // ISO/IEC 18004:2024 §12 b) uses finder runs in the 1:1:3:1:1 ratio,
+    // and §12 h)1 derives module size from finder pattern width. Clipping the
+    // reflected ray before `int()` would avoid `>>> 0` wrapping negative near-edge
+    // coordinates to a huge uint32 and clamping to the wrong edge. Policy: keep
+    // the existing heuristic because the direct fix degraded decode performance
+    // on current vectors (BoofCV sweep 134/485 -> 132/485).
     let otherToY = int(fy - (to.y - fy) * scaleY);
     let scaleX = 1.0;
-    const bh = b.height;
+    const bh = bm.height;
     if (otherToY < 0) {
         scaleX = fy / (fy - otherToY);
         otherToY = 0;
@@ -542,12 +921,16 @@ function BWBRunLength(b, from, to) {
         otherToY = bh - 1;
     }
     otherToX = int(fx + (otherToX - fx) * scaleX);
-    result += _single(b, from, { x: otherToX, y: otherToY });
+    result += _single(bm, from, { x: otherToX, y: otherToY });
+    // Both mirrored rays include the center module once, so drop one module
+    // after summing them into the full finder-width estimate.
     return result - 1.0;
 }
 function moduleSizeAvg(b, p1, p2) {
     const est1 = BWBRunLength(b, pointInt(p1), pointInt(p2));
     const est2 = BWBRunLength(b, pointInt(p2), pointInt(p1));
+    // One ray can fail near image edges, so keep the surviving estimate
+    // instead of discarding the finder-width measurement outright.
     if (Number.isNaN(est1))
         return est2 / FINDER.totalSize;
     if (Number.isNaN(est2))
@@ -555,27 +938,34 @@ function moduleSizeAvg(b, p1, p2) {
     return (est1 + est2) / (2 * FINDER.totalSize);
 }
 function detect(b) {
+    const bm = b;
     let bl, tl, tr;
     try {
-        ({ bl, tl, tr } = findFinder(b));
+        ({ bl, tl, tr } = findFinder(bm));
     }
     catch (e) {
         try {
-            b.negate();
-            ({ bl, tl, tr } = findFinder(b));
+            // ISO/IEC 18004:2024 §12 b)5 says to "reverse the colouring of the
+            // light and dark pixels" for reflectance reversal. `detect()` works on
+            // the `decodeQR()`-owned scratch bitmap, so keep the retry in-place for
+            // performance instead of cloning before this private/test-only helper.
+            bm.negate();
+            ({ bl, tl, tr } = findFinder(bm));
         }
         catch (e) {
-            b.negate(); // undo negate
+            bm.negate(); // undo negate
             throw e;
         }
     }
-    const moduleSize = (moduleSizeAvg(b, tl, tr) + moduleSizeAvg(b, tl, bl)) / 2;
+    const moduleSize = (moduleSizeAvg(bm, tl, tr) + moduleSizeAvg(bm, tl, bl)) / 2;
     if (moduleSize < 1.0)
         throw new Error(`invalid moduleSize = ${moduleSize}`);
     // Estimate size
     const tltr = int(distance(tl, tr) / moduleSize + 0.5);
     const tlbl = int(distance(tl, bl) / moduleSize + 0.5);
     let size = int((tltr + tlbl) / 2 + 7);
+    // QR side lengths are 21 + 4 * (version - 1), so normalize the estimate
+    // to the nearest size that is 1 modulo 4 before decoding the version.
     const rem = size % 4;
     if (rem === 0)
         size++; // -> 1
@@ -583,13 +973,13 @@ function detect(b) {
         size--; // -> 1
     else if (rem === 3)
         size -= 2;
-    const version = info.size.decode(size);
-    validateVersion(version);
+    const version = utils.info.size.decode(size);
+    utils.validateVersion(version);
     let alignmentPattern;
-    if (info.alignmentPatterns(version).length > 0) {
+    if (utils.info.alignmentPatterns(version).length > 0) {
         // Bottom right estimate
         const br = { x: tr.x - tl.x + bl.x, y: tr.y - tl.y + bl.y };
-        const c = 1.0 - 3.0 / (info.size.encode(version) - 7);
+        const c = 1.0 - 3.0 / (utils.info.size.encode(version) - 7);
         // Estimated alignment pattern position
         const est = {
             x: int(tl.x + c * (br.x - tl.x)),
@@ -599,7 +989,7 @@ function detect(b) {
         };
         for (let i = 4; i <= 16; i <<= 1) {
             try {
-                alignmentPattern = findAlignment(b, est, i);
+                alignmentPattern = findAlignment(bm, est, i);
                 break;
             }
             catch (e) { }
@@ -619,13 +1009,15 @@ function detect(b) {
         toBR = { x: size - 3.5, y: size - 3.5 };
     }
     const from = [tl, tr, br, bl];
-    const bits = transform(b, size, from, [toTL, toTR, toBR, toBL]);
+    const bits = transform(bm, size, from, [toTL, toTR, toBR, toBL]);
     return { bits: bits, points: from };
 }
 // Perspective transform by 4 points
 function squareToQuadrilateral(p) {
     const d3 = { x: p[0].x - p[1].x + p[2].x - p[3].x, y: p[0].y - p[1].y + p[2].y - p[3].y };
     if (d3.x === 0.0 && d3.y === 0.0) {
+        // Parallelogram fast path: perspective terms vanish, so the homography
+        // reduces to an affine transform.
         return [
             [p[1].x - p[0].x, p[2].x - p[1].x, p[0].x],
             [p[1].y - p[0].y, p[2].y - p[1].y, p[0].y],
@@ -647,9 +1039,12 @@ function squareToQuadrilateral(p) {
 }
 // Transform quadrilateral to square by 4 points
 function transform(b, size, from, to) {
+    const bm = b;
     // TODO: check
     // https://math.stackexchange.com/questions/13404/mapping-irregular-quadrilateral-to-a-rectangle
     const p = squareToQuadrilateral(to);
+    // Homographies are scale-invariant, so the adjugate is enough here;
+    // there is no need to divide by the determinant when inverting `p`.
     const qToS = [
         [
             p[1][1] * p[2][2] - p[2][1] * p[1][2],
@@ -670,7 +1065,7 @@ function transform(b, size, from, to) {
     const sToQ = squareToQuadrilateral(from);
     const transform = sToQ.map((i) => i.map((_, qx) => i.reduce((acc, v, j) => acc + v * qToS[j][qx], 0)));
     const res = new Bitmap(size);
-    const points = fillArr(2 * size, 0);
+    const points = utils.fillArr(2 * size, 0);
     const pointsLength = points.length;
     for (let y = 0; y < size; y++) {
         const p = transform;
@@ -678,13 +1073,15 @@ function transform(b, size, from, to) {
             const x = i / 2 + 0.5;
             const y2 = y + 0.5;
             const den = p[2][0] * x + p[2][1] * y2 + p[2][2];
-            points[i] = int((p[0][0] * x + p[0][1] * y2 + p[0][2]) / den);
-            points[i + 1] = int((p[1][0] * x + p[1][1] * y2 + p[1][2]) / den);
+            // ISO/IEC 18004:2024 §12 h) maps sampling grid intersections back to
+            // image coordinates before deciding dark/light state. Clip projected
+            // coordinates before `int()` because `>>> 0` wraps negative samples to a
+            // huge uint32 and would clamp them to the far image edge.
+            points[i] = int(cap((p[0][0] * x + p[0][1] * y2 + p[0][2]) / den, 0, bm.width - 1));
+            points[i + 1] = int(cap((p[1][0] * x + p[1][1] * y2 + p[1][2]) / den, 0, bm.height - 1));
         }
         for (let i = 0; i < pointsLength; i += 2) {
-            const px = cap(points[i], 0, b.width - 1);
-            const py = cap(points[i + 1], 0, b.height - 1);
-            if (b.get(px, py))
+            if (bm.get(points[i], points[i + 1]))
                 res.set((i / 2) | 0, y, true);
         }
     }
@@ -693,8 +1090,11 @@ function transform(b, size, from, to) {
 // Same as in drawTemplate, but reading
 // TODO: merge in CoderType?
 function readInfoBits(b) {
-    const readBit = (x, y, out) => (out << 1) | (b.get(x, y) ? 1 : 0);
-    const size = b.height;
+    const bm = b;
+    // Walk each reserved copy from the highest-numbered module back to module 0
+    // so the shift accumulator rebuilds the canonical bit string from MSB to LSB.
+    const readBit = (x, y, out) => (out << 1) | (bm.get(x, y) ? 1 : 0);
+    const size = bm.height;
     // Version information
     let version1 = 0;
     for (let y = 5; y >= 0; y--)
@@ -721,56 +1121,62 @@ function readInfoBits(b) {
     return { version1, version2, format1, format2 };
 }
 function parseInfo(b) {
+    const bm = b;
     // Population count over xor -> hamming distance
-    const size = b.height;
-    const { version1, version2, format1, format2 } = readInfoBits(b);
+    const size = bm.height;
+    const { version1, version2, format1, format2 } = readInfoBits(bm);
     // Guess format
     let format;
-    const bestFormat = best();
+    const bestFormat = utils.best();
     for (const ecc of ['medium', 'low', 'high', 'quartile']) {
         for (let mask = 0; mask < 8; mask++) {
-            const bits = info.formatBits(ecc, mask);
+            const bits = utils.info.formatBits(ecc, mask);
             const cur = { ecc, mask: mask };
             if (bits === format1 || bits === format2) {
                 format = cur;
                 break;
             }
-            bestFormat.add(popcnt(format1 ^ bits), cur);
+            bestFormat.add(utils.popcnt(format1 ^ bits), cur);
             if (format1 !== format2)
-                bestFormat.add(popcnt(format2 ^ bits), cur);
+                bestFormat.add(utils.popcnt(format2 ^ bits), cur);
         }
     }
     if (format === undefined && bestFormat.score() <= MAX_BITS_ERROR)
         format = bestFormat.get();
     if (format === undefined)
         throw new Error('invalid format pattern');
-    let version = info.size.decode(size); // Guess version based on bitmap size
+    let version = utils.info.size.decode(size); // Guess version based on bitmap size
+    // Versions 1-6 do not carry version-information words, so side length is
+    // the only authoritative version source until version 7 adds those fields.
     if (version < 7)
-        validateVersion(version);
+        utils.validateVersion(version);
     else {
         version = undefined;
         // Guess version
-        const bestVer = best();
+        const bestVer = utils.best();
         for (let ver = 7; ver <= 40; ver++) {
-            const bits = info.versionBits(ver);
+            const bits = utils.info.versionBits(ver);
             if (bits === version1 || bits === version2) {
                 version = ver;
                 break;
             }
-            bestVer.add(popcnt(version1 ^ bits), ver);
+            bestVer.add(utils.popcnt(version1 ^ bits), ver);
             if (version1 !== version2)
-                bestVer.add(popcnt(version2 ^ bits), ver);
+                bestVer.add(utils.popcnt(version2 ^ bits), ver);
         }
         if (version === undefined && bestVer.score() <= MAX_BITS_ERROR)
             version = bestVer.get();
         if (version === undefined)
             throw new Error('invalid version pattern');
-        if (info.size.encode(version) !== size)
+        if (utils.info.size.encode(version) !== size)
             throw new Error('invalid version size');
     }
     return { version, ...format };
 }
-// Common encodings, please open issue if something popular missing
+// ISO/IEC 18004:2024 §7.4.3.2 says each ECI is a "6-digit assignment
+// number"; §7.4.3.4 says invoked ECIs apply until "a change of ECI".
+// Decode through platform TextDecoder only: unsupported labels may throw on
+// some runtimes, and callers needing them can provide a custom textDecoder.
 const eciToEncoding = {
     1: 'iso-8859-1',
     2: 'ibm437',
@@ -800,26 +1206,30 @@ const eciToEncoding = {
     30: 'euc-kr',
 };
 function decodeWithEci(bytes, eci = 26) {
+    // ISO/IEC 18004:2024 §7.3.2 says QR's "default interpretation" is
+    // "ECI 000003 representing the ISO/IEC 8859-1 character set". Keep UTF-8
+    // here so this library's UTF-8 byte-mode encoder round-trips without ECI.
     const encoding = eciToEncoding[eci];
     if (!encoding)
         throw new Error(`Unsupported ECI: ${eci}`);
     return new TextDecoder(encoding).decode(bytes);
 }
 function decodeBitmap(b, decoder = decodeWithEci) {
-    const size = b.height;
-    if (size < 21 || (size & 0b11) !== 1 || size !== b.width)
+    const bm = b;
+    const size = bm.height;
+    if (size < 21 || (size & 0b11) !== 1 || size !== bm.width)
         throw new Error(`decode: invalid size=${size}`);
-    const { version, mask, ecc } = parseInfo(b);
-    const tpl = drawTemplate(version, ecc, mask);
-    const { total } = info.capacity(version, ecc);
+    const { version, mask, ecc } = parseInfo(bm);
+    const tpl = utils.drawTemplate(version, ecc, mask);
+    const { total } = utils.info.capacity(version, ecc);
     const bytes = new Uint8Array(total);
     let pos = 0;
     let buf = 0;
     let bitPos = 0;
-    zigzag(tpl, mask, (x, y, m) => {
+    utils.zigzag(tpl, mask, (x, y, m) => {
         bitPos++;
         buf <<= 1;
-        buf |= +(!!b.get(x, y) !== m);
+        buf |= +(!!bm.get(x, y) !== m);
         if (bitPos !== 8)
             return;
         bytes[pos++] = buf;
@@ -828,8 +1238,8 @@ function decodeBitmap(b, decoder = decodeWithEci) {
     });
     if (pos !== total)
         throw new Error(`decode: pos=${pos}, total=${total}`);
-    let bits = Array.from(interleave(version, ecc).decode(bytes))
-        .map((i) => bin(i, 8))
+    let bits = Array.from(utils.interleave(version, ecc).decode(bytes))
+        .map((i) => utils.bin(i, 8))
         .join('');
     // Reverse operation of index.ts/encode working on bits
     const readBits = (n) => {
@@ -850,6 +1260,9 @@ function decodeBitmap(b, decoder = decodeWithEci) {
         '1000': 'kanji',
     };
     let res = '';
+    // ISO/IEC 18004:2024 §7.3.2 defines no-ECI byte data as ECI 000003
+    // / ISO-8859-1. Keep ECI 26 for compatibility with legacy no-ECI UTF-8
+    // payloads and with encodeQR's UTF-8 byte-mode default.
     let eci = 26; // Default to utf-8 for compat with old behavior
     while (true) {
         if (bits.length < 4)
@@ -860,7 +1273,7 @@ function decodeBitmap(b, decoder = decodeWithEci) {
             throw new Error(`Unknown modeBits=${modeBits} res="${res}"`);
         if (mode === 'terminator')
             break;
-        const countBits = info.lengthBits(version, mode);
+        const countBits = utils.info.lengthBits(version, mode);
         let count = toNum(readBits(countBits));
         if (mode === 'numeric') {
             while (count >= 3) {
@@ -886,11 +1299,11 @@ function decodeBitmap(b, decoder = decodeWithEci) {
         else if (mode === 'alphanumeric') {
             while (count >= 2) {
                 const v = toNum(readBits(11));
-                res += info.alphabet.alphanumerc.encode([Math.floor(v / 45), v % 45]).join('');
+                res += utils.info.alphabet.alphanumerc.encode([Math.floor(v / 45), v % 45]).join('');
                 count -= 2;
             }
             if (count === 1)
-                res += info.alphabet.alphanumerc.encode([toNum(readBits(6))]).join('');
+                res += utils.info.alphabet.alphanumerc.encode([toNum(readBits(6))]).join('');
         }
         else if (mode === 'eci') {
             const first = toNum(readBits(8));
@@ -908,15 +1321,24 @@ function decodeBitmap(b, decoder = decodeWithEci) {
                 data[i] = toNum(readBits(8));
             res += decoder(data, eci);
         }
+        else if (mode === 'kanji') {
+            // ISO/IEC 18004:2024 §7.3.6 says Kanji mode uses Shift JIS and
+            // "Each two-byte character value is compacted to a 13-bit binary
+            // codeword." Keep it unsupported until a real interop fixture can verify
+            // the 13-bit-to-Shift-JIS mapping rather than adding untested decoding.
+            throw new Error('Kanji mode is not supported');
+        }
         else
             throw new Error(`Unknown mode=${mode}`);
     }
     return res;
 }
-// Creates square from rectangle
+// Center-crop to a square and return the original-image offset so
+// `decodeQR()` can map detected points back into caller coordinates.
 function cropToSquare(img) {
-    const data = Array.isArray(img.data) ? new Uint8Array(img.data) : img.data;
-    const { height, width } = img;
+    const image = img;
+    const data = Array.isArray(image.data) ? new Uint8Array(image.data) : image.data;
+    const { height, width } = image;
     const squareSize = Math.min(height, width);
     const offset = {
         x: Math.floor((width - squareSize) / 2),
@@ -932,45 +1354,93 @@ function cropToSquare(img) {
     }
     return { offset, img: { height: squareSize, width: squareSize, data: croppedData } };
 }
+/**
+ * Decode text from a QR image.
+ * @param img - RGB or RGBA image data that contains a QR code.
+ * @param opts - Decoder hooks and image preprocessing options. See {@link DecodeOpts}.
+ * @returns Decoded QR payload as a string.
+ * @throws If the image, decoder options, or QR contents are invalid. {@link Error}
+ * @example
+ * Decode text from a QR image.
+ * ```ts
+ * import encodeQR, { Bitmap } from 'qr';
+ * import decodeQR from 'qr/decode.js';
+ * const bits = encodeQR('Hello world', 'raw', { scale: 4 });
+ * const bm = new Bitmap({ width: bits[0].length, height: bits.length }, bits);
+ * const text = decodeQR(bm.toImage());
+ * ```
+ */
 export function decodeQR(img, opts = {}) {
+    let image = img;
+    const options = opts;
     for (const field of ['height', 'width']) {
-        if (!Number.isSafeInteger(img[field]) || img[field] <= 0)
-            throw new Error(`invalid img.${field}=${img[field]} (${typeof img[field]})`);
-    }
-    if (!Array.isArray(img.data) &&
-        !(img.data instanceof Uint8Array) &&
-        !(img.data instanceof Uint8ClampedArray))
-        throw new Error(`invalid image.data=${img.data} (${typeof img.data})`);
-    if (opts.cropToSquare !== undefined && typeof opts.cropToSquare !== 'boolean')
-        throw new Error(`invalid opts.cropToSquare=${opts.cropToSquare}`);
-    for (const fn of ['pointsOnDetect', 'imageOnBitmap', 'imageOnDetect', 'imageOnResult']) {
-        if (opts[fn] !== undefined && typeof opts[fn] !== 'function')
-            throw new Error(`invalid opts.${fn}=${opts[fn]} (${typeof opts[fn]})`);
+        if (!Number.isSafeInteger(image[field]) || image[field] <= 0)
+            throw new Error(`invalid img.${field}=${image[field]} (${typeof image[field]})`);
+    }
+    const { data } = image;
+    if (!Array.isArray(data) && !isBytes(data))
+        throw new Error(`invalid image.data=${data} (${typeof data})`);
+    if (options.cropToSquare !== undefined && typeof options.cropToSquare !== 'boolean')
+        throw new Error(`invalid opts.cropToSquare=${options.cropToSquare}`);
+    // Validate callbacks before decoding so payload mode does not decide whether
+    // an invalid public option is accepted.
+    for (const fn of [
+        'textDecoder',
+        'pointsOnDetect',
+        'imageOnBitmap',
+        'imageOnDetect',
+        'imageOnResult',
+    ]) {
+        if (options[fn] !== undefined && typeof options[fn] !== 'function')
+            throw new Error(`invalid opts.${fn}=${options[fn]} (${typeof options[fn]})`);
     }
     let offset = { x: 0, y: 0 };
-    if (opts.cropToSquare)
-        ({ img, offset } = cropToSquare(img));
-    const bmp = toBitmap(img);
-    if (opts.imageOnBitmap)
-        opts.imageOnBitmap(bmp.toImage());
+    if (options.cropToSquare)
+        ({ img: image, offset } = cropToSquare(image));
+    const bmp = toBitmap(image);
+    if (options.imageOnBitmap)
+        options.imageOnBitmap(bmp.toImage());
     const { bits, points } = detect(bmp);
-    if (opts.pointsOnDetect) {
+    if (options.pointsOnDetect) {
+        // Report finder points in the caller's original coordinate space after any center-crop.
         const p = points.map((i) => ({ ...i, ...pointAdd(i, offset) }));
-        opts.pointsOnDetect(p);
+        options.pointsOnDetect(p);
     }
-    if (opts.imageOnDetect)
-        opts.imageOnDetect(bits.toImage());
-    const res = decodeBitmap(bits, opts.textDecoder);
-    if (opts.imageOnResult)
-        opts.imageOnResult(bits.toImage());
+    if (options.imageOnDetect)
+        options.imageOnDetect(bits.toImage());
+    const res = decodeBitmap(bits, options.textDecoder);
+    if (options.imageOnResult)
+        options.imageOnResult(bits.toImage());
     return res;
 }
+/**
+ * Default export alias for {@link decodeQR}.
+ * @param img - RGB or RGBA image data that contains a QR code.
+ * @param opts - Decoder hooks and image preprocessing options. See {@link DecodeOpts}.
+ * @returns Decoded QR payload as a string.
+ * @throws If the image, decoder options, or QR contents are invalid. {@link Error}
+ * @example
+ * Decode a rendered QR image via the default decoder export.
+ * ```ts
+ * import encodeQR, { Bitmap } from 'qr';
+ * import decodeQR from 'qr/decode.js';
+ * const bits = encodeQR('Hello world', 'raw', { scale: 4 });
+ * const bm = new Bitmap({ width: bits[0].length, height: bits.length }, bits);
+ * decodeQR(bm.toImage());
+ * ```
+ */
 export default decodeQR;
+// Additional private helpers for focused regression tests; separate from the
+// existing `_tests` object so its current keys remain stable.
+export const _TESTS = /* @__PURE__ */ Object.freeze({
+    findAlignment: findAlignment,
+    transform: transform,
+});
 // Unsafe API utils, exported only for tests
-export const _tests = {
+export const _tests = /* @__PURE__ */ Object.freeze({
     toBitmap,
     decodeBitmap,
     findFinder,
     detect,
-};
+});
 //# sourceMappingURL=decode.js.map