qr 0.5.5 → 0.6.0

package/index.js

@@ -14,22 +14,6 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-/**
- * Methods for encoding (generating) QR code patterns.
- * Check out decode.ts for decoding (reading).
- * @module
- * @example
-```js
-import encodeQR from 'qr';
-const txt = 'Hello world';
-const ascii = encodeQR(txt, 'ascii'); // Not all fonts are supported
-const terminalFriendly = encodeQR(txt, 'term'); // 2x larger, all fonts are OK
-const gifBytes = encodeQR(txt, 'gif'); // Uncompressed GIF
-const svgElement = encodeQR(txt, 'svg'); // SVG vector image element
-const array = encodeQR(txt, 'raw'); // 2d array for canvas or other libs
-// import decodeQR from 'qr/decode.js';
-```
- */
 // We do not use newline escape code directly in strings because it's not parser-friendly
 const chCodes = { newline: 10, reset: 27 };
 function assertNumber(n) {
@@ -48,6 +32,7 @@ function mod(a, b) {
     return result >= 0 ? result : b + result;
 }
 function fillArr(length, val) {
+    // Current callers only pass primitive fill values; object fills would alias references.
     return new Array(length).fill(val);
 }
 function popcnt(n) {
@@ -69,6 +54,8 @@ function interleaveBytes(blocks) {
     }
     const result = new Uint8Array(totalLen);
     let idx = 0;
+    // When block lengths differ, callers must pass the shorter blocks first so
+    // the interleaving order matches ISO/IEC 18004 §7.6 c).
     for (let i = 0; i < maxLen; i++) {
         for (const block of blocks) {
             if (i < block.length)
@@ -83,6 +70,7 @@ function best() {
     let bestScore = Infinity;
     return {
         add(score, value) {
+            // Ties keep the first candidate so equal-score selections stay deterministic.
             if (score >= bestScore)
                 return;
             best = value;
@@ -94,7 +82,8 @@ function best() {
 }
 // Based on https://github.com/paulmillr/scure-base/blob/main/index.ts
 function alphabet(alphabet) {
-    return {
+    // Character order defines the numeric values used by the target QR mode.
+    return Object.freeze({
         has: (char) => alphabet.includes(char),
         decode: (input) => {
             if (!Array.isArray(input) || (input.length && typeof input[0] !== 'string'))
@@ -118,7 +107,7 @@ function alphabet(alphabet) {
                 return alphabet[i];
             });
         },
-    };
+    });
 }
 // Transpose 32x32 bit matrix in-place
 // a[0..31] are 32 rows of 32 bits each; after transpose they become 32 columns.
@@ -149,10 +138,24 @@ const rangeMask = (shift, len) => {
     // len in [0..32], shift in [0..31]
     if (len === 0)
         return 0;
+    // Callers only request len=32 for word-aligned spans; JS shift counts wrap at 32,
+    // so full-word masks must bypass the generic `(1 << len)` path.
     if (len === 32)
         return 0xffffffff;
     return (((1 << len) - 1) << shift) >>> 0;
 };
+/**
+ * Mutable monochrome bitmap used as the internal QR representation.
+ * @param size - Square edge length or explicit bitmap dimensions.
+ * @param data - Optional row-major pixel matrix using `true`, `false`, or `undefined`.
+ * @example
+ * Create a bitmap, then scale it for display.
+ * ```ts
+ * import { Bitmap } from 'qr';
+ * const bitmap = Bitmap.fromString('X \n X');
+ * bitmap.scale(2);
+ * ```
+ */
 export class Bitmap {
     static size(size, limit) {
         if (typeof size === 'number')
@@ -172,6 +175,8 @@ export class Bitmap {
     }
     static fromString(s) {
         // Remove linebreaks on start and end, so we draw in `` section
+        // Fixture strings use LF-delimited rows of X / space / ? characters; callers
+        // must normalize CRLF input before handing it to this debug parser.
         s = s.replace(/^\n+/g, '').replace(/\n+$/g, '');
         const lines = s.split(String.fromCharCode(chCodes.newline));
         const height = lines.length;
@@ -209,6 +214,14 @@ export class Bitmap {
     width;
     constructor(size, data) {
         const { height, width } = Bitmap.size(size);
+        // Bitmap coordinates wrap through modulo for negative positions, so invalid
+        // dimensions produce NaN, aliasing, or unsafe allocation sizes before later
+        // drawing no-op guards can run. `Infinity` is only valid for rectangle sizes
+        // that are clamped against an existing positive bitmap.
+        if (!Number.isSafeInteger(height) || height <= 0)
+            throw new Error(`Bitmap: invalid height=${height}, expected positive safe integer dimension`);
+        if (!Number.isSafeInteger(width) || width <= 0)
+            throw new Error(`Bitmap: invalid width=${width}, expected positive safe integer dimension`);
         this.height = height;
         this.width = width;
         this.tailMask = rangeMask(0, width & 31 || 32);
@@ -230,8 +243,13 @@ export class Bitmap {
         }
     }
     point(p) {
+        // The storage docs above say "undefined is used as a marker whether cell
+        // was written or not"; `point()` is the detector's dark-module read and
+        // intentionally treats both undefined and false as not-dark. Use
+        // `isDefined()` when the written/undefined distinction matters.
         return this.get(p.x, p.y);
     }
+    // Raw bounds check for scan loops; unlike `xy()`, this does not wrap or normalize coordinates.
     isInside(p) {
         return 0 <= p.x && p.x < this.width && 0 <= p.y && p.y < this.height;
     }
@@ -248,7 +266,8 @@ export class Bitmap {
             throw new Error(`Bitmap: invalid x=${c.x}`);
         if (!Number.isSafeInteger(c.y))
             throw new Error(`Bitmap: invalid y=${c.y}`);
-        // Do modulo, so we can use negative positions
+        // Bitmap's class docs say "For most `draw` calls, structure is mutable";
+        // coordinate objects follow that hot-path policy too and are normalized in place.
         c.x = mod(c.x, this.width);
         c.y = mod(c.y, this.height);
         return c;
@@ -263,6 +282,10 @@ export class Bitmap {
         return { word: this.wordIndex(x, y), bit: x & 31 };
     }
     isDefined(x, y) {
+        // `isInside()` is the raw bounds check; keep these bitset accessors
+        // bounds-check-free for hot paths. Invalid tail coordinates may observe
+        // backing-word bits, so callers that accept untrusted coordinates must
+        // check `isInside()` first.
         const wi = this.wordIndex(x, y);
         const m = bitMask(x);
         return (this.defined[wi] & m) !== 0;
@@ -275,11 +298,15 @@ export class Bitmap {
     maskWord(wi, mask, v) {
         const { defined, value } = this;
         defined[wi] |= mask;
+        // `-v` expands the boolean to either all-zero or all-one bits before masking it into the selected lanes.
         value[wi] = (value[wi] & ~mask) | (-v & mask);
     }
     set(x, y, v) {
+        // `undefined` means "leave the current cell unchanged", not "clear it back to undefined".
         if (v === undefined)
             return;
+        // Like `get()` / `isDefined()`, this is a raw in-bounds bitset accessor;
+        // check `isInside()` before passing untrusted coordinates.
         this.maskWord(this.wordIndex(x, y), bitMask(x), v);
     }
     // word-span fill for constant values (fast path)
@@ -301,6 +328,7 @@ export class Bitmap {
                 continue;
             }
             this.maskWord(rowBase + startWord, rangeMask(startBit, 32 - startBit), v);
+            // Whole interior words can be written directly: every bit in the span becomes defined and equal to v.
             for (let i = startWord + 1; i < endWord; i++) {
                 defined[rowBase + i] = 0xffffffff;
                 value[rowBase + i] = v ? 0xffffffff : 0;
@@ -315,6 +343,7 @@ export class Bitmap {
                 const bitX = x + xPos;
                 const { bit, word } = this.bitIndex(bitX, Py);
                 const bitsPerWord = Math.min(32 - bit, width - xPos);
+                // bitX stays absolute for word-local masks; xPos/yPos stay rectangle-local for rect callbacks.
                 cb(word, bitX, xPos, yPos, bitsPerWord);
                 xPos += bitsPerWord;
             }
@@ -334,7 +363,11 @@ export class Bitmap {
             let valWord = value[wi];
             for (let b = 0; b < n; b++) {
                 const mask = bitMask(bitX + b);
+                // As with `point()`, callback `cur` is a dark/not-dark read; the
+                // storage-level "undefined is used as a marker whether cell was
+                // written or not" distinction is checked separately with `isDefined()`.
                 const res = fn({ x: xPos + b, y: yPos }, (valWord & mask) !== 0);
+                // Returning undefined from the callback keeps the existing cell unchanged.
                 if (res === undefined)
                     continue;
                 defWord |= mask;
@@ -354,6 +387,8 @@ export class Bitmap {
             const valWord = value[wi];
             for (let b = 0; b < n; b++) {
                 const mask = bitMask(bitX + b);
+                // rectRead is non-mutating; callback coordinates are rectangle-local,
+                // and `cur` is the same dark/not-dark read as `point()`.
                 fn({ x: xPos + b, y: yPos }, (valWord & mask) !== 0);
             }
         });
@@ -368,6 +403,10 @@ export class Bitmap {
     }
     // add border
     border(border = 2, value) {
+        // `border` is used both as output-size delta and as embed coordinate; keep
+        // it a positive safe integer before those paths allocate or normalize.
+        if (!Number.isSafeInteger(border) || border <= 0)
+            throw new Error(`Bitmap.border: invalid size=${border}`);
         const height = this.height + 2 * border;
         const width = this.width + 2 * border;
         const out = new Bitmap({ height, width });
@@ -384,6 +423,10 @@ export class Bitmap {
             return this;
         const { value, defined } = this;
         const { words: srcStride, value: srcValue } = src;
+        // The Bitmap storage docs say "undefined is used as a marker whether cell
+        // was written or not"; `embed()` is the packed blit path for materialized
+        // source bitmaps, so it flattens the source rectangle to defined dark/light
+        // bits instead of treating undefined cells as transparent.
         for (let yPos = 0; yPos < height; yPos++) {
             const srcRow = yPos * srcStride;
             for (let xPos = 0; xPos < width;) {
@@ -393,6 +436,7 @@ export class Bitmap {
                 const len = Math.min(32 - dstBit, width - xPos);
                 const w0 = srcValue[srcWord];
                 const w1 = srcBit && srcWord + 1 < srcRow + srcStride ? srcValue[srcWord + 1] : 0;
+                // Source and destination bit offsets may differ, so assemble the source span from up to two words.
                 const sVal = srcBit ? ((w0 >>> srcBit) | (w1 << (32 - srcBit))) >>> 0 : w0;
                 const dstMask = rangeMask(dstBit, len);
                 const valBits = ((sVal & rangeMask(0, len)) << dstBit) >>> 0;
@@ -409,6 +453,7 @@ export class Bitmap {
         const { height, width } = Bitmap.size(size, this.size({ x, y }));
         const rect = new Bitmap({ height, width });
         this.rectRead({ x, y }, { height, width }, (p, cur) => {
+            // rectRead reports undefined cells as false, so copy only when the source defined bit is set.
             if (this.isDefined(x + p.x, y + p.y)) {
                 rect.set(p.x, p.y, cur);
             }
@@ -453,6 +498,9 @@ export class Bitmap {
     negate() {
         const n = this.defined.length;
         for (let i = 0; i < n; i++) {
+            // ISO/IEC 18004:2024 §12 b)5 says to "reverse the colouring of the light
+            // and dark pixels"; this dense scratch-bitmap operation materializes every
+            // backing bit as defined and does not preserve sparse/undefined cells.
             this.value[i] = ~this.value[i];
             this.defined[i] = 0xffffffff;
         }
@@ -463,6 +511,11 @@ export class Bitmap {
         if (!Number.isSafeInteger(factor) || factor > 1024)
             throw new Error(`invalid scale factor: ${factor}`);
         const { height, width } = this;
+        // Bitmap storage docs say "undefined is used as a marker whether cell was
+        // written or not"; `scale()` is an output materialization path and samples
+        // with `get()`, so sparse cells become defined light cells. Positive output
+        // dimensions stay validated by the Bitmap constructor instead of duplicating
+        // dimension checks in every caller that computes a new bitmap size.
         const res = new Bitmap({ height: factor * height, width: factor * width });
         return res.rect({ x: 0, y: 0 }, Infinity, ({ x, y }) => this.get((x / factor) | 0, (y / factor) | 0));
     }
@@ -488,10 +541,14 @@ export class Bitmap {
         }
     }
     countPatternInRow(y, patternLen, ...patterns) {
-        if (patternLen <= 0 || patternLen >= 32)
+        // Penalty scanning only passes Table 11 windows over bounded symbol rows;
+        // validate this public helper before JS shifts / typed-array reads coerce bad inputs.
+        if (!Number.isSafeInteger(patternLen) || patternLen <= 0 || patternLen >= 32)
             throw new Error('wrong patternLen');
         const mask = (1 << patternLen) - 1;
-        const { width, value, words } = this;
+        const { height, width, value, words } = this;
+        if (!Number.isSafeInteger(y) || y < 0 || y >= height)
+            return 0;
         let count = 0;
         const rowBase = this.wordIndex(0, y);
         for (let i = 0, window = 0; i < words; i++) {
@@ -512,9 +569,14 @@ export class Bitmap {
         return count;
     }
     getRuns(y, fn) {
-        const { width, value, words } = this;
+        const { height, width, value, words } = this;
         if (width === 0)
             return;
+        // ISO/IEC 18004:2024 §7.8.3.1 N1 scans adjacent modules in bounded rows
+        // and columns; validate this public helper before missing typed-array rows
+        // are coerced into all-light runs by bitwise operators.
+        if (!Number.isSafeInteger(y) || y < 0 || y >= height)
+            return;
         let runLen = 0;
         let runValue;
         const rowBase = this.wordIndex(0, y);
@@ -551,11 +613,13 @@ export class Bitmap {
         return count;
     }
     countBoxes2x2(y) {
-        const { width, words } = this;
-        if (width < 2 || (y | 0) < 0 || y + 1 >= this.height)
+        const { height, width, words } = this;
+        // ISO/IEC 18004:2024 §7.8.3.1 N2 counts 2 x 2 module blocks in bounded
+        // rows; reject non-integer scan rows before bitwise coercions truncate them.
+        if (width < 2 || !Number.isSafeInteger(y) || y < 0 || y + 1 >= height)
             return 0;
-        const base0 = this.wordIndex(0, y) | 0;
-        const base1 = this.wordIndex(0, y + 1) | 0;
+        const base0 = this.wordIndex(0, y);
+        const base1 = this.wordIndex(0, y + 1);
         // valid "left-edge" positions x in [0 .. W-2]
         const tailBits = width & 31;
         const validLast = tailBits === 0 ? 0x7fffffff : rangeMask(0, (width - 1) & 31);
@@ -594,6 +658,9 @@ export class Bitmap {
         const out = Array.from({ length: this.height }, () => new Array(this.width));
         for (let y = 0; y < this.height; y++) {
             const row = out[y];
+            // Bitmap storage docs say "undefined is used as a marker whether cell was
+            // written or not"; `toRaw()` is the materialized dark/not-dark output path
+            // used after `encodeQR()` asserts the QR symbol is fully drawn.
             for (let x = 0; x < this.width; x++)
                 row[x] = this.get(x, y);
         }
@@ -639,6 +706,8 @@ export class Bitmap {
     }
     toSVG(optimize = true) {
         let out = `<svg viewBox="0 0 ${this.width} ${this.height}" xmlns="http://www.w3.org/2000/svg">`;
+        // ISO/IEC 18004:2024 §5.1 c) / §5.3.8: this SVG draws only dark modules;
+        // callers must render it on a light background for light modules and the quiet zone.
         // Construct optimized SVG path data.
         let pathData = '';
         let prevPoint;
@@ -682,7 +751,9 @@ export class Bitmap {
         const u16le = (i) => [i & 0xff, (i >>> 8) & 0xff];
         const dims = [...u16le(this.width), ...u16le(this.height)];
         const data = [];
+        // Palette index 0 is white/light and index 1 is black/dark; rectRead maps undefined cells to light.
         this.rectRead(0, Infinity, (_, cur) => data.push(+(cur === true)));
+        // Each chunk starts with an LZW clear code; 126 raw pixels keep codes at 8 bits until the next clear.
         const N = 126; // Block size
         // prettier-ignore
         const bytes = [
@@ -717,11 +788,16 @@ export class Bitmap {
 }
 // End of utils
 // Runtime type-checking
-/** Error correction mode. low: 7%, medium: 15%, quartile: 25%, high: 30% */
-export const ECMode = ['low', 'medium', 'quartile', 'high'];
-/** QR Code encoding */
-export const Encoding = ['numeric', 'alphanumeric', 'byte', 'kanji', 'eci'];
+/** Error correction mode. low: 7%, medium: 15%, quartile: 25%, high: 30%. */
+export const ECMode = /* @__PURE__ */ Object.freeze(['low', 'medium', 'quartile', 'high']);
+/**
+ * QR payload compaction mode names recognized by the type/validator.
+ * `kanji` and `eci` are spec modes, but `encodeQR` currently rejects them until implemented.
+ */
+export const Encoding = 
+/* @__PURE__ */ Object.freeze(['numeric', 'alphanumeric', 'byte', 'kanji', 'eci']);
 // Various constants & tables
+// ISO/IEC 18004:2024 Table 1: QR symbol codeword capacity by version (data plus error correction).
 // prettier-ignore
 const BYTES = [
     // 1,  2,  3,   4,   5,   6,   7,   8,   9,  10,  11,  12,  13,  14,  15,  16,  17,  18,  19,   20,
@@ -729,6 +805,7 @@ const BYTES = [
     //  21,   22,   23,   24,   25,   26,   27,   28,   29,   30,   31,   32,   33,   34,   35,   36,   37,   38,   39,   40
     1156, 1258, 1364, 1474, 1588, 1706, 1828, 1921, 2051, 2185, 2323, 2465, 2611, 2761, 2876, 3034, 3196, 3362, 3532, 3706,
 ];
+// ISO/IEC 18004:2024 Table 9: error correction codewords per block by version and level.
 // prettier-ignore
 const WORDS_PER_BLOCK = {
     // Version 1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40
@@ -737,6 +814,7 @@ const WORDS_PER_BLOCK = {
     quartile: [13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
     high: [17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
 };
+// ISO/IEC 18004:2024 Table 9: error correction block count by version and level.
 // prettier-ignore
 const ECC_BLOCKS = {
     // Version   1, 2, 3, 4, 5, 6, 7, 8, 9,10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40
@@ -745,12 +823,15 @@ const ECC_BLOCKS = {
     quartile: [1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29, 34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68],
     high: [1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35, 37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81],
 };
-const info = {
-    size: {
-        encode: (ver) => 21 + 4 * (ver - 1), // ver1 = 21, ver40=177 blocks
+// ISO/IEC 18004:2024 sections 5.3/7.4/7.5/7.9/7.10: QR layout, segment, format/version, and capacity helpers.
+const info = /* @__PURE__ */ Object.freeze({
+    size: /* @__PURE__ */ Object.freeze({
+        encode: (ver) => 21 + 4 * (ver - 1), // ver1 = 21, ver40 = 177 modules per side
         decode: (size) => (size - 17) / 4,
-    },
+    }),
+    // ISO/IEC 18004:2024 Table 3: map version ranges 1-9, 10-26, and 27-40 to count-width indexes.
     sizeType: (ver) => Math.floor((ver + 7) / 17),
+    // ISO/IEC 18004:2024 Annex E Table E.1: row/column coordinate list of alignment-pattern centres.
     // Based on https://codereview.stackexchange.com/questions/74925/algorithm-to-generate-this-alignment-pattern-locations-table-for-qr-codes
     alignmentPatterns(ver) {
         if (ver === 1)
@@ -770,13 +851,16 @@ const info = {
         res.push(last);
         return res;
     },
-    ECCode: {
+    // ISO/IEC 18004:2024 §7.9.1 Table 12: error-correction-level indicators for the top two format-information data bits.
+    ECCode: /* @__PURE__ */ Object.freeze({
         low: 0b01,
         medium: 0b00,
         quartile: 0b11,
         high: 0b10,
-    },
+    }),
+    // ISO/IEC 18004:2024 §7.9.1 final paragraph: XOR the 15-bit format information with mask pattern 101010000010010.
     formatMask: 0b101010000010010,
+    // ISO/IEC 18004:2024 §7.9.1 / Annex C.2: append the 10-bit BCH remainder for the 5 data bits, then apply the fixed QR format mask.
     formatBits(ecc, maskIdx) {
         const data = (info.ECCode[ecc] << 3) | maskIdx;
         let d = data;
@@ -784,16 +868,21 @@ const info = {
             d = (d << 1) ^ ((d >> 9) * 0b10100110111);
         return ((data << 10) | d) ^ info.formatMask;
     },
+    // ISO/IEC 18004:2024 §7.10 / Annex D.2: append the 12-bit Golay remainder to the 6-bit version word; version information is not masked.
     versionBits(ver) {
         let d = ver;
         for (let i = 0; i < 12; i++)
             d = (d << 1) ^ ((d >> 11) * 0b1111100100101);
         return (ver << 12) | d;
     },
-    alphabet: {
+    // ISO/IEC 18004:2024 §7.3.3 / §7.3.4 / §7.4.5 Table 5: character-set membership and value codecs for numeric and alphanumeric QR modes.
+    alphabet: /* @__PURE__ */ Object.freeze({
+        // ISO/IEC 18004:2024 §7.3.3 / §7.4.4: numeric-mode digits map directly to values 0..9 before 3-digit grouping.
         numeric: alphabet('0123456789'),
+        // ISO/IEC 18004:2024 §7.3.4 / §7.4.5 Table 5: 45-character alphanumeric-mode value order used for 11-bit pair packing. Keep the legacy `alphanumerc` key name in sync with existing callers.
         alphanumerc: alphabet('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:'),
-    }, // as Record<EncodingType, ReturnType<typeof alphabet>>,
+    }), // as Record<EncodingType, ReturnType<typeof alphabet>>,
+    // ISO/IEC 18004:2024 Table 3 gives QR character-count widths for data modes; ECI headers instead carry only the mode indicator plus the designator from §7.4.3.
     lengthBits(ver, type) {
         const table = {
             numeric: [10, 12, 14],
@@ -804,13 +893,15 @@ const info = {
         };
         return table[type][info.sizeType(ver)];
     },
-    modeBits: {
+    // ISO/IEC 18004:2024 §7.4.2 Table 2: 4-bit QR mode indicators for the segment types this library models.
+    modeBits: /* @__PURE__ */ Object.freeze({
         numeric: '0001',
         alphanumeric: '0010',
         byte: '0100',
         kanji: '1000',
         eci: '0111',
-    },
+    }),
+    // ISO/IEC 18004:2024 Table 1 / §7.5.1 Table 9: derive total data bits and short/long RS block layout from total codewords, ECC words per block, and block counts.
     capacity(ver, ecc) {
         const bytes = BYTES[ver - 1];
         const words = WORDS_PER_BLOCK[ecc][ver - 1];
@@ -826,8 +917,9 @@ const info = {
             total: (words + blockLen) * numBlocks + numBlocks - shortBlocks,
         };
     },
-};
-const PATTERNS = [
+});
+// ISO/IEC 18004:2024 Table 10: QR data-mask predicates 000..111, written here in (x column, y row) form.
+const PATTERNS = /* @__PURE__ */ Object.freeze([
     (x, y) => (x + y) % 2 == 0,
     (_x, y) => y % 2 == 0,
     (x, _y) => x % 3 == 0,
@@ -836,8 +928,9 @@ const PATTERNS = [
     (x, y) => ((x * y) % 2) + ((x * y) % 3) == 0,
     (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 == 0,
     (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 == 0,
-];
+]);
 // Galois field && reed-solomon encoding
+// ISO/IEC 18004:2024 §7.5.2 / Annex A / Annex B: GF(2^8) field and polynomial helpers shared by QR Reed-Solomon parity generation and decoding.
 const GF = {
     tables: ((p_poly) => {
         const exp = fillArr(256, 0);
@@ -849,26 +942,43 @@ const GF = {
             if (x & 0x100)
                 x ^= p_poly;
         }
+        // Keep α^255 = 1 in exp[255]; GF.log() folds the matching log[1] = 255
+        // back to 0 with `% 255`, so later helpers can wrap exponents without a special case.
         return { exp, log };
     })(0x11d),
+    // Raw α^i lookup from the precomputed field table; callers are expected
+    // to reduce / validate exponents before indexing it.
     exp: (x) => GF.tables.exp[x],
+    // log(0) is undefined in GF(2^8); `% 255` also folds the wrapped table
+    // entry for α^255 = 1 back to exponent 0.
     log(x) {
         if (x === 0)
             throw new Error(`GF.log: invalid arg=${x}`);
         return GF.tables.log[x] % 255;
     },
+    // Zero has no logarithm in GF(2^8), so it must short-circuit here; all
+    // other products are α^(log(x) + log(y) mod 255) in the reviewed field.
     mul(x, y) {
         if (x === 0 || y === 0)
             return 0;
         return GF.tables.exp[(GF.tables.log[x] + GF.tables.log[y]) % 255];
     },
+    // In characteristic 2 fields, addition and subtraction are the same
+    // bitwise XOR operation used by the QR Reed-Solomon arithmetic.
     add: (x, y) => x ^ y,
+    // Raw nonzero field power helper. Current QR use is GF.pow(2, i) for the
+    // Annex A generator factors; x = 0 or negative exponents are not validated.
     pow: (x, e) => GF.tables.exp[(GF.tables.log[x] * e) % 255],
+    // Multiplicative inverse for nonzero field elements. Current callers only
+    // use it on values already known to be nonzero; 0 has no inverse in GF(2^8).
     inv(x) {
         if (x === 0)
             throw new Error(`GF.inverse: invalid arg=${x}`);
         return GF.tables.exp[255 - GF.tables.log[x]];
     },
+    // Canonicalize coefficient arrays by trimming leading zero coefficients
+    // while preserving `[0]` as the zero polynomial; already-normalized inputs
+    // are returned by reference.
     polynomial(poly) {
         if (poly.length == 0)
             throw new Error('GF.polymomial: invalid length');
@@ -880,6 +990,8 @@ const GF = {
             ;
         return poly.slice(i);
     },
+    // Represent c*x^degree in the descending-power coefficient layout used
+    // by the QR Reed-Solomon helpers; coefficient 0 canonicalizes to `[0]`.
     monomial(degree, coefficient) {
         if (degree < 0)
             throw new Error(`GF.monomial: invalid degree=${degree}`);
@@ -889,8 +1001,14 @@ const GF = {
         coefficients[0] = coefficient;
         return GF.polynomial(coefficients);
     },
+    // Canonical polynomials keep the highest-order coefficient first and use
+    // `[0]` for zero, so degree is just `length - 1`.
     degree: (a) => a.length - 1,
+    // Read the coefficient for x^degree from the descending-power array layout.
+    // Canonical arrays make this a direct index; out-of-range degrees return `undefined`.
     coefficient: (a, degree) => a[GF.degree(a) - degree],
+    // Multiply descending-power coefficient arrays by convolution over GF(2^8).
+    // Zero short-circuits here before the log-based field multiply is consulted.
     mulPoly(a, b) {
         if (a[0] === 0 || b[0] === 0)
             return [0];
@@ -902,6 +1020,8 @@ const GF = {
         }
         return GF.polynomial(res);
     },
+    // Scale every coefficient by the same field element in descending-power order.
+    // Scalar 0 canonicalizes to `[0]`, and scalar 1 reuses the original array.
     mulPolyScalar(a, scalar) {
         if (scalar == 0)
             return [0];
@@ -912,6 +1032,8 @@ const GF = {
             res[i] = GF.mul(a[i], scalar);
         return GF.polynomial(res);
     },
+    // Multiply a polynomial by c*x^degree in descending-power coefficient form.
+    // This scales existing coefficients, then appends trailing zero coefficients.
     mulPolyMonomial(a, degree, coefficient) {
         if (degree < 0)
             throw new Error('GF.mulPolyMonomial: invalid degree');
@@ -922,6 +1044,8 @@ const GF = {
             res[i] = GF.mul(a[i], coefficient);
         return GF.polynomial(res);
     },
+    // Add descending-power coefficient arrays with GF(2^8) XOR on the aligned
+    // suffix; `[0]` short-circuits by returning the other array unchanged.
     addPoly(a, b) {
         if (a[0] === 0)
             return b;
@@ -940,6 +1064,8 @@ const GF = {
             sumDiff[i] = GF.add(smaller[i - lengthDiff], larger[i]);
         return GF.polynomial(sumDiff);
     },
+    // Synthetic division for monic divisors in descending-power coefficient form.
+    // Callers are expected to append `divisor.length - 1` zero coefficients first.
     remainderPoly(data, divisor) {
         const out = Array.from(data);
         for (let i = 0; i < data.length - divisor.length + 1; i++) {
@@ -953,12 +1079,16 @@ const GF = {
         }
         return out.slice(data.length - divisor.length + 1, out.length);
     },
+    // Build Annex A's monic generator polynomial g_n(x) = Π(x - 2^i).
+    // degree=0 returns `[1]`; callers are expected to validate degree bounds.
     divisorPoly(degree) {
         let g = [1];
         for (let i = 0; i < degree; i++)
             g = GF.mulPoly(g, [1, GF.pow(2, i)]);
         return g;
     },
+    // Evaluate a descending-power coefficient array at `a` with Horner's rule.
+    // The `a == 0` fast-path returns the x^0 coefficient directly.
     evalPoly(poly, a) {
         if (a == 0)
             return GF.coefficient(poly, 0); // Just return the x^0 coefficient
@@ -968,6 +1098,8 @@ const GF = {
         return res;
     },
     // TODO: cleanup
+    // Extended Euclidean RS step: derive the locator/evaluator pair from x^R
+    // and the syndrome polynomial, then normalize sigma(0) to 1.
     euclidian(a, b, R) {
         // Force degree(a) >= degree(b)
         if (GF.degree(a) < GF.degree(b))
@@ -1005,6 +1137,8 @@ const GF = {
         return [GF.mulPolyScalar(t, inverse), GF.mulPolyScalar(r, inverse)];
     },
 };
+// Per-block Reed-Solomon coder: encode emits only the parity bytes for one
+// data block, while decode expects data+parity bytes and returns the corrected full block.
 function RS(eccWords) {
     return {
         encode(from) {
@@ -1057,11 +1191,15 @@ function RS(eccWords) {
     };
 }
 // Interleaves blocks
+// QR block interleaver / deinterleaver. Shorter data blocks stay first so
+// encode matches ISO/IEC 18004 §7.6 c) and decode can reverse it via §12 z)1.
 function interleave(ver, ecc) {
     const { words, shortBlocks, numBlocks, blockLen, total } = info.capacity(ver, ecc);
     const rs = RS(words);
     return {
         encode(bytes) {
+            // Caller must pass exactly the data codewords for this version/ecc;
+            // this helper only splits blocks and interleaves them with RS parity.
             // Add error correction to bytes
             const blocks = [];
             const eccBlocks = [];
@@ -1114,6 +1252,8 @@ function interleave(ver, ecc) {
 }
 // Draw
 // Generic template per version+ecc+mask. Can be cached, to speedup calculations.
+// Function-pattern template plus reserved format/version areas; data modules
+// are filled later by zigzag placement in `drawQR`.
 function drawTemplate(ver, ecc, maskIdx, test = false) {
     const size = info.size.encode(ver);
     let b = new Bitmap(size + 2);
@@ -1175,9 +1315,11 @@ function drawTemplate(ver, ecc, maskIdx, test = false) {
     }
     return b;
 }
-// zigzag: bottom->top && top->bottom
+// Walk undefined data modules in the QR two-column zigzag order from the
+// lower right, skipping function patterns and the vertical timing column.
 function zigzag(tpl, maskIdx, fn) {
-    const size = tpl.height;
+    const bm = tpl;
+    const size = bm.height;
     const pattern = PATTERNS[maskIdx];
     // zig-zag pattern
     let dir = -1;
@@ -1189,7 +1331,7 @@ function zigzag(tpl, maskIdx, fn) {
         for (;; y += dir) {
             for (let j = 0; j < 2; j += 1) {
                 const x = xOffset - j;
-                if (tpl.isDefined(x, y))
+                if (bm.isDefined(x, y))
                     continue; // skip already written elements
                 fn(x, y, pattern(x, y));
             }
@@ -1201,6 +1343,8 @@ function zigzag(tpl, maskIdx, fn) {
 }
 // NOTE: byte encoding is just representation, QR works with strings only. Most decoders will fail on raw byte array,
 // since they expect unicode or other text encoding inside bytes
+// Auto-pick among the currently supported single-segment modes only.
+// Empty strings stay numeric, and any non-alphanumeric character falls back to byte.
 function detectType(str) {
     let type = 'numeric';
     for (let x of str) {
@@ -1213,13 +1357,27 @@ function detectType(str) {
     return type;
 }
 /**
- * @example utf8ToBytes('abc') // new Uint8Array([97, 98, 99])
+ * Encode a string as UTF-8 bytes.
+ * @param str - Text to encode into UTF-8.
+ * @returns UTF-8 bytes for the provided string.
+ * @throws If the input is not a string. {@link Error}
+ * @example
+ * Encode a string as UTF-8 bytes.
+ * ```ts
+ * const bytes = utf8ToBytes('abc'); // new Uint8Array([97, 98, 99])
+ * ```
  */
+// ISO/IEC 18004:2024 §7.3.2 says QR's default interpretation is
+// "ECI 000003 representing the ISO/IEC 8859-1 character set"; §7.4.2 says
+// non-default initial ECI data starts with an ECI header. Keep UTF-8 bytes
+// without that header for compatibility with existing emoji/qrcode fixtures.
 export function utf8ToBytes(str) {
     if (typeof str !== 'string')
         throw new Error(`utf8ToBytes expected string, got ${typeof str}`);
     return new Uint8Array(new TextEncoder().encode(str)); // https://bugzil.la/1681809
 }
+// Build one QR mode/count/data segment, then append the terminator, zero padding,
+// and alternating pad codewords before RS interleaving.
 function encode(ver, ecc, data, type, encoder = utf8ToBytes) {
     let encoded = '';
     let dataLen = data.length;
@@ -1244,6 +1402,7 @@ function encode(ver, ecc, data, type, encoder = utf8ToBytes) {
             encoded += bin(t[n - 1], 6); // pad if odd number of chars
     }
     else if (type === 'byte') {
+        // The default encoder is intentionally UTF-8-without-ECI; see utf8ToBytes().
         const utf8 = encoder(data);
         dataLen = utf8.length;
         encoded = Array.from(utf8)
@@ -1272,6 +1431,8 @@ function encode(ver, ecc, data, type, encoder = utf8ToBytes) {
     return interleave(ver, ecc).encode(bytes);
 }
 // DRAW
+// Stream interleaved codeword bits MSB-first through zigzag; any leftover
+// cells after the final codeword become zero-valued remainder bits before masking.
 function drawQR(ver, ecc, data, maskIdx, test = false) {
     const b = drawTemplate(ver, ecc, maskIdx, test);
     let i = 0;
@@ -1288,6 +1449,8 @@ function drawQR(ver, ecc, data, maskIdx, test = false) {
         throw new Error('QR: bytes left after draw');
     return b;
 }
+// Pack a left-to-right row pattern for `Bitmap.countPatternInRow()`; keep the
+// explicit width because leading light modules vanish from the numeric value.
 const mkPattern = (pattern) => {
     const s = pattern.map((i) => (i ? '1' : '0')).join('');
     return { len: s.length, n: Number(`0b${s}`) };
@@ -1295,15 +1458,16 @@ const mkPattern = (pattern) => {
 // 1:1:3:1:1 ratio (dark:light:dark:light:dark) pattern in row/column, preceded or followed by light area 4 modules wide
 const finderPattern = [true, false, true, true, true, false, true]; // dark:light:dark:light:dark
 const lightPattern = [false, false, false, false]; // light area 4 modules wide
-const P1 = mkPattern([...finderPattern, ...lightPattern]);
-const P2 = mkPattern([...lightPattern, ...finderPattern]);
+const P1 = /* @__PURE__ */ (() => mkPattern([...finderPattern, ...lightPattern]))();
+const P2 = /* @__PURE__ */ (() => mkPattern([...lightPattern, ...finderPattern]))();
 function penalty(bm) {
-    const { width, height } = bm;
-    const transposed = bm.transpose();
+    const b = bm;
+    const { width, height } = b;
+    const transposed = b.transpose();
     // Adjacent modules in row/column in same | No. of modules = (5 + i) color
     let adjacent = 0;
     for (let y = 0; y < height; y++) {
-        bm.getRuns(y, (len) => {
+        b.getRuns(y, (len) => {
             if (len >= 5)
                 adjacent += 3 + (len - 5);
         });
@@ -1317,29 +1481,28 @@ function penalty(bm) {
     // Block of modules in same color (Block size = 2x2)
     let box = 0;
     for (let y = 0; y < height - 1; y++)
-        box += 3 * bm.countBoxes2x2(y);
+        box += 3 * b.countBoxes2x2(y);
     let finder = 0;
     for (let y = 0; y < height; y++)
-        finder += 40 * bm.countPatternInRow(y, P1.len, P1.n, P2.n);
+        finder += 40 * b.countPatternInRow(y, P1.len, P1.n, P2.n);
     for (let y = 0; y < width; y++)
         finder += 40 * transposed.countPatternInRow(y, P1.len, P1.n, P2.n);
-    // Proportion of dark modules in entire symbol
-    // Add 10 points to a deviation of 5% increment or decrement in the proportion
-    // ratio of dark module from the referential 50%
-    let darkPixels = 0;
-    darkPixels = bm.popcnt();
-    //bm.rectRead(0, Infinity, (_c, val) => (darkPixels += val ? 1 : 0));
-    // for (let y = 0; y < height; y++) {
-    //   for (let x = 0; x < width; x++) if (bm.get(x, y)) darkPixels++;
-    // }
-    const darkPercent = (darkPixels / (height * width)) * 100;
-    const dark = 10 * Math.floor(Math.abs(darkPercent - 50) / 5);
+    const total = height * width;
+    const darkPixels = b.popcnt();
+    // ISO/IEC 18004:2024 §7.8.3.1 NOTE 4 assigns "0 points" when the dark ratio
+    // is "between 45 % and 55 %"; subtract that first 5% deviation band before
+    // rating further 5% steps, so exact 45/55 and 40/60 boundaries stay in-band.
+    const darkSteps = Math.ceil(Math.max(0, Math.abs(darkPixels * 100 - total * 50) - total * 5) / (total * 5));
+    const dark = 10 * darkSteps;
     return adjacent + box + finder + dark;
 }
 // Selects best mask according to penalty, if no mask is provided
 function drawQRBest(ver, ecc, data, maskIdx) {
     if (maskIdx === undefined) {
         const bestMask = best();
+        // ISO/IEC 18004:2024 §7.8.3.1 says mask penalty area is "the complete symbol",
+        // but python-qrcode scores this placeholder form. Keep that output for compatibility
+        // with common QR generators and to avoid fingerprinting this implementation.
         for (let mask = 0; mask < PATTERNS.length; mask++)
             bestMask.add(penalty(drawQR(ver, ecc, data, mask, true)), mask);
         maskIdx = bestMask.get();
@@ -1363,24 +1526,25 @@ function validateMask(mask) {
         throw new Error(`Invalid mask=${mask}. Expected number [0..7]`);
 }
 export function encodeQR(text, output = 'raw', opts = {}) {
-    const ecc = opts.ecc !== undefined ? opts.ecc : 'medium';
+    const _opts = opts;
+    const ecc = _opts.ecc !== undefined ? _opts.ecc : 'medium';
     validateECC(ecc);
-    const encoding = opts.encoding !== undefined ? opts.encoding : detectType(text);
+    const encoding = _opts.encoding !== undefined ? _opts.encoding : detectType(text);
     validateEncoding(encoding);
-    if (opts.mask !== undefined)
-        validateMask(opts.mask);
-    let ver = opts.version;
+    if (_opts.mask !== undefined)
+        validateMask(_opts.mask);
+    let ver = _opts.version;
     let data, err = new Error('Unknown error');
     if (ver !== undefined) {
         validateVersion(ver);
-        data = encode(ver, ecc, text, encoding, opts.textEncoder);
+        data = encode(ver, ecc, text, encoding, _opts.textEncoder);
     }
     else {
         // If no version is provided, try to find smallest one which fits
         // Currently just scans all version, can be significantly speedup if needed
         for (let i = 1; i <= 40; i++) {
             try {
-                data = encode(i, ecc, text, encoding, opts.textEncoder);
+                data = encode(i, ecc, text, encoding, _opts.textEncoder);
                 ver = i;
                 break;
             }
@@ -1391,20 +1555,24 @@ export function encodeQR(text, output = 'raw', opts = {}) {
     }
     if (!ver || !data)
         throw err;
-    let res = drawQRBest(ver, ecc, data, opts.mask);
+    let res = drawQRBest(ver, ecc, data, _opts.mask);
     res.assertDrawn();
-    const border = opts.border === undefined ? 2 : opts.border;
-    if (!Number.isSafeInteger(border))
-        throw new Error(`invalid border type=${typeof border}`);
+    // ISO/IEC 18004:2024 §5.3.8 says a QR quiet zone's "width shall be 4X",
+    // and §9.1 requires 4X "on all four sides". Keep the compact historical
+    // 2-module default to avoid changing encoder output; callers that need a
+    // standards-conformant quiet zone must pass `border: 4` explicitly.
+    const border = _opts.border === undefined ? 2 : _opts.border;
+    if (!Number.isSafeInteger(border) || border <= 0)
+        throw new Error(`invalid border=${border}`);
     res = res.border(border, false); // Add border
-    if (opts.scale !== undefined)
-        res = res.scale(opts.scale); // Scale image
+    if (_opts.scale !== undefined)
+        res = res.scale(_opts.scale); // Scale image
     if (output === 'raw')
         return res.toRaw();
     else if (output === 'ascii')
         return res.toASCII();
     else if (output === 'svg')
-        return res.toSVG(opts.optimize);
+        return res.toSVG(_opts.optimize);
     else if (output === 'gif')
         return res.toGIF();
     else if (output === 'term')
@@ -1412,8 +1580,32 @@ export function encodeQR(text, output = 'raw', opts = {}) {
     else
         throw new Error(`Unknown output: ${output}`);
 }
+/**
+ * Default export alias for {@link encodeQR}.
+ * @param text - Text payload that should be encoded into the QR symbol.
+ * @param output - Output format to generate: raw matrix, ASCII, terminal ANSI, GIF, or SVG.
+ * @param opts - Encoding and rendering options. See {@link QrOpts} and {@link SvgQrOpts}.
+ * @returns Encoded QR data in the format selected by `output`.
+ * @throws If the payload, options, QR capacity, or output format are invalid. {@link Error}
+ * @example
+ * Encode text into the default export from the package root.
+ * ```ts
+ * import encodeQR from 'qr';
+ * encodeQR('Hello world', 'ascii');
+ * ```
+ */
 export default encodeQR;
-export const utils = {
+/**
+ * Low-level helpers used by the encoder and test suite.
+ * Exports the shared helper tables/functions through a frozen container.
+ * @example
+ * Read low-level QR metadata tables.
+ * ```ts
+ * import { utils } from 'qr';
+ * const size = utils.info.size.encode(1); // 21
+ * ```
+ */
+export const utils = /* @__PURE__ */ Object.freeze({
     best,
     bin,
     popcnt,
@@ -1423,9 +1615,10 @@ export const utils = {
     interleave,
     validateVersion,
     zigzag,
-};
+});
 // Unsafe API utils, exported only for tests
-export const _tests = {
+// Exposes the shared internal helpers/tables through a frozen container.
+export const _tests = /* @__PURE__ */ Object.freeze({
     Bitmap,
     info,
     detectType,
@@ -1433,7 +1626,7 @@ export const _tests = {
     drawQR,
     penalty,
     PATTERNS,
-};
+});
 // Type tests
 // const o1 = qr('test', 'ascii');
 // const o2 = qr('test', 'raw');