qr-core 1.0.0

package/dist/src/encoding/bitstream.js

@@ -0,0 +1,68 @@
+import { BitBuffer } from "../core/bit-buffer.js";
+import { CHAR_COUNT_INDICATOR_BITS, getVersionGroupIndex, MODE_INDICATOR, } from "../spec/constants.js";
+import { ECC_TABLE } from "../spec/tables.js";
+import { encodeAlphanumeric, encodeByte, encodeNumeric } from "./encoders.js";
+/**
+ * Combines encoded segments and applies padding to create the final data bitstream.
+ */
+export function buildBitstream(segments, version, ecc) {
+    const buffer = new BitBuffer();
+    const groupIdx = getVersionGroupIndex(version);
+    // 1. Append segments
+    for (const segment of segments) {
+        // Mode Indicator (4 bits)
+        buffer.put(MODE_INDICATOR[segment.mode], 4);
+        // Character Count Indicator (length depends on mode and version group)
+        const charCountBits = CHAR_COUNT_INDICATOR_BITS[segment.mode][groupIdx];
+        const charCount = segment.count;
+        const maxCount = (1 << charCountBits) - 1;
+        if (charCount > maxCount) {
+            throw new Error(`Segment too long for mode ${segment.mode} at version ${version}`);
+        }
+        buffer.put(charCount, charCountBits);
+        // Data bits
+        switch (segment.mode) {
+            case "numeric":
+                encodeNumeric(segment.data, buffer);
+                break;
+            case "alphanumeric":
+                encodeAlphanumeric(segment.data, buffer);
+                break;
+            case "byte":
+                if (!segment.bytes) {
+                    throw new Error("Encoding error: Byte segment missing bytes");
+                }
+                encodeByte(segment.bytes, buffer);
+                break;
+        }
+    }
+    // Calculate target capacity in bits
+    const versionInfo = ECC_TABLE[version]?.[ecc];
+    if (!versionInfo) {
+        throw new Error(`Invalid version/ECC combination: ${version}/${ecc}`);
+    }
+    const dataCapacityBits = (versionInfo.group1.numBlocks * versionInfo.group1.dataCodewords +
+        versionInfo.group2.numBlocks * versionInfo.group2.dataCodewords) *
+        8;
+    if (buffer.length > dataCapacityBits) {
+        throw new Error(`Data too large for version ${version}-${ecc}`);
+    }
+    // 2. Terminator (up to 4 zero bits)
+    const terminatorLen = Math.min(4, dataCapacityBits - buffer.length);
+    if (terminatorLen > 0) {
+        buffer.put(0, terminatorLen);
+    }
+    // 3. Pad to byte boundary
+    buffer.bitByteAlign();
+    // 4. Pad with alternating bytes (0xEC, 0x11) until capacity is reached
+    const padCodewords = [0xec, 0x11];
+    let padIdx = 0;
+    while (buffer.length < dataCapacityBits) {
+        // Safe access because padIdx is modulo 2, so it's always 0 or 1.
+        // padCodewords has 2 elements.
+        const padVal = padCodewords[padIdx];
+        buffer.put(padVal ?? 0xec, 8); // Fallback purely for type safety, never reached
+        padIdx = (padIdx + 1) % 2;
+    }
+    return buffer;
+}

package/dist/src/encoding/encoders.d.ts

@@ -0,0 +1,13 @@
+import type { BitBuffer } from "../core/bit-buffer.js";
+/**
+ * Numeric Mode: 10 bit / 3 characters
+ */
+export declare function encodeNumeric(data: string, buffer: BitBuffer): void;
+/**
+ * Alphanumeric Mode: 11 bit / 2 characters
+ */
+export declare function encodeAlphanumeric(data: string, buffer: BitBuffer): void;
+/**
+ * Byte Mode: UTF-8 (Default)
+ */
+export declare function encodeByte(data: string | Uint8Array, buffer: BitBuffer): void;

package/dist/src/encoding/encoders.js

@@ -0,0 +1,54 @@
+import { ALPHANUMERIC_CHARSET } from "../spec/constants.js";
+/**
+ * Numeric Mode: 10 bit / 3 characters
+ */
+export function encodeNumeric(data, buffer) {
+    let i = 0;
+    while (i + 3 <= data.length) {
+        const num = parseInt(data.substring(i, i + 3), 10);
+        buffer.put(num, 10);
+        i += 3;
+    }
+    if (data.length - i === 2) {
+        buffer.put(parseInt(data.substring(i), 10), 7);
+    }
+    else if (data.length - i === 1) {
+        buffer.put(parseInt(data.substring(i), 10), 4);
+    }
+}
+/**
+ * Alphanumeric Mode: 11 bit / 2 characters
+ */
+export function encodeAlphanumeric(data, buffer) {
+    let i = 0;
+    while (i + 2 <= data.length) {
+        const char1Str = data[i];
+        const char2Str = data[i + 1];
+        if (char1Str === undefined || char2Str === undefined)
+            throw new Error("Encoding error: Index out of bounds");
+        const char1 = ALPHANUMERIC_CHARSET.indexOf(char1Str);
+        const char2 = ALPHANUMERIC_CHARSET.indexOf(char2Str);
+        if (char1 === -1 || char2 === -1)
+            throw new Error("Encoding error: Invalid character");
+        buffer.put(char1 * 45 + char2, 11);
+        i += 2;
+    }
+    if (data.length - i === 1) {
+        const char1Str = data[i];
+        if (char1Str === undefined)
+            throw new Error("Encoding error: Index out of bounds");
+        const char1 = ALPHANUMERIC_CHARSET.indexOf(char1Str);
+        if (char1 === -1)
+            throw new Error("Encoding error: Invalid character");
+        buffer.put(char1, 6);
+    }
+}
+/**
+ * Byte Mode: UTF-8 (Default)
+ */
+export function encodeByte(data, buffer) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    for (const byte of bytes) {
+        buffer.put(byte, 8);
+    }
+}

package/dist/src/encoding/interleave.d.ts

@@ -0,0 +1,5 @@
+import type { EccLevel } from "../types/index.js";
+/**
+ * Splits data into blocks and interleaves them with ECC codewords.
+ */
+export declare function interleave(data: Uint8Array, version: number, ecc: EccLevel): Uint8Array;

package/dist/src/encoding/interleave.js

@@ -0,0 +1,49 @@
+import { computeEcc } from "../core/rs.js";
+import { ECC_TABLE } from "../spec/tables.js";
+/**
+ * Splits data into blocks and interleaves them with ECC codewords.
+ */
+export function interleave(data, version, ecc) {
+    const spec = ECC_TABLE[version]?.[ecc];
+    if (!spec)
+        throw new Error(`Invalid version/ECC: ${version}/${ecc}`);
+    const dataBlocks = [];
+    const eccBlocks = [];
+    let offset = 0;
+    const groups = [spec.group1, spec.group2];
+    for (const group of groups) {
+        for (let i = 0; i < group.numBlocks; i++) {
+            const block = data.slice(offset, offset + group.dataCodewords);
+            dataBlocks.push(block);
+            eccBlocks.push(computeEcc(block, spec.eccPerBlock));
+            offset += group.dataCodewords;
+        }
+    }
+    const totalDataLen = dataBlocks.reduce((acc, b) => acc + b.length, 0);
+    const totalEccLen = eccBlocks.length * spec.eccPerBlock;
+    const result = new Uint8Array(totalDataLen + totalEccLen);
+    let resOffset = 0;
+    // Interleave data codewords
+    const maxDataLen = Math.max(...dataBlocks.map((b) => b.length));
+    for (let i = 0; i < maxDataLen; i++) {
+        for (const block of dataBlocks) {
+            if (i < block.length) {
+                const val = block[i];
+                // block[i] is safe because i < block.length
+                if (val !== undefined) {
+                    result[resOffset++] = val;
+                }
+            }
+        }
+    }
+    // Interleave ECC codewords
+    for (let i = 0; i < spec.eccPerBlock; i++) {
+        for (const block of eccBlocks) {
+            const val = block[i];
+            if (val === undefined)
+                throw new Error("Internal error: ECC block shorter than expected");
+            result[resOffset++] = val;
+        }
+    }
+    return result;
+}

package/dist/src/encoding/segmentation.d.ts

@@ -0,0 +1,12 @@
+import type { QrMode } from "../types/index.js";
+export interface Segment {
+    mode: Exclude<QrMode, "auto">;
+    data: string;
+    count: number;
+    bytes?: Uint8Array;
+}
+/**
+ * Analyzes the input string and splits it into the most appropriate QR modes.
+ * v1: Simple but effective greedy approach.
+ */
+export declare function segmentize(input: string): Segment[];

package/dist/src/encoding/segmentation.js

@@ -0,0 +1,43 @@
+import { ALPHANUMERIC_CHARSET } from "../spec/constants.js";
+/**
+ * Analyzes the input string and splits it into the most appropriate QR modes.
+ * v1: Simple but effective greedy approach.
+ */
+export function segmentize(input) {
+    if (input.length === 0)
+        return [];
+    const segments = [];
+    const firstChar = input[0];
+    if (firstChar === undefined)
+        return []; // Should be caught by input.length === 0 check
+    let currentMode = getBestMode(firstChar);
+    let startIndex = 0;
+    for (let i = 1; i < input.length; i++) {
+        const char = input[i];
+        if (char === undefined)
+            throw new Error("Segmentation error: index out of bounds");
+        const charMode = getBestMode(char);
+        if (charMode !== currentMode) {
+            segments.push({
+                mode: currentMode,
+                data: input.substring(startIndex, i),
+                count: i - startIndex,
+            });
+            currentMode = charMode;
+            startIndex = i;
+        }
+    }
+    segments.push({
+        mode: currentMode,
+        data: input.substring(startIndex),
+        count: input.length - startIndex,
+    });
+    return segments;
+}
+function getBestMode(char) {
+    if (/[0-9]/.test(char))
+        return "numeric";
+    if (ALPHANUMERIC_CHARSET.includes(char))
+        return "alphanumeric";
+    return "byte";
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { encode, encodeSafe } from "./api/index.js";
+export { QrException } from "./core/error.js";
+export * from "./types/index.js";

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export { encode, encodeSafe } from "./api/index.js";
+export { QrException } from "./core/error.js";
+export * from "./types/index.js";

package/dist/src/layout/patterns.d.ts

@@ -0,0 +1,12 @@
+/**
+ * QR Fonksiyonel Desenlerin Yerleştirilmesi (Finder, Timing, Alignment)
+ */
+import type { Matrix } from "../matrix/bit-matrix.js";
+/**
+ * Writes the 18-bit version information for versions >= 7.
+ */
+export declare function writeVersionInfo(matrix: Matrix, version: number): void;
+/**
+ * Tüm fonksiyonel desenleri matrise çizer
+ */
+export declare function setupFunctionPatterns(matrix: Matrix, version: number): void;

package/dist/src/layout/patterns.js

@@ -0,0 +1,120 @@
+/**
+ * QR Fonksiyonel Desenlerin Yerleştirilmesi (Finder, Timing, Alignment)
+ */
+import { getVersionInfo } from "../spec/bch.js";
+import { ALIGNMENT_PATTERN_POSITIONS } from "../spec/tables.js";
+/**
+ * Writes the 18-bit version information for versions >= 7.
+ */
+export function writeVersionInfo(matrix, version) {
+    const info = getVersionInfo(version);
+    const size = matrix.size;
+    for (let i = 0; i < 18; i++) {
+        const bit = ((info >>> i) & 1) === 1;
+        const row = Math.floor(i / 3);
+        const col = i % 3;
+        // Bottom-left area (above the bottom-left finder pattern)
+        matrix.setReserved(row, size - 11 + col, bit);
+        // Top-right area (left of the top-right finder pattern)
+        matrix.setReserved(size - 11 + col, row, bit);
+    }
+}
+/**
+ * Tüm fonksiyonel desenleri matrise çizer
+ */
+export function setupFunctionPatterns(matrix, version) {
+    const size = matrix.size;
+    // 1. Finder Patterns (Sol Üst, Sağ Üst, Sol Alt)
+    drawFinder(matrix, 0, 0);
+    drawFinder(matrix, size - 7, 0);
+    drawFinder(matrix, 0, size - 7);
+    // 2. Separators (Finder pattern'lerin etrafındaki beyaz boşluklar)
+    drawSeparators(matrix);
+    // 3. Timing Patterns (6. satır ve 6. sütun boyunca bir dolu bir boş çizgiler)
+    for (let i = 8; i < size - 8; i++) {
+        const bit = i % 2 === 0;
+        matrix.setReserved(6, i, bit); // Dikey
+        matrix.setReserved(i, 6, bit); // Yatay
+    }
+    // 4. Alignment Patterns (Versiyon >= 2, 5x5 desenler)
+    const coords = ALIGNMENT_PATTERN_POSITIONS[version] || [];
+    for (let i = 0; i < coords.length; i++) {
+        for (let j = 0; j < coords.length; j++) {
+            const x = coords[i];
+            const y = coords[j];
+            if (x === undefined || y === undefined)
+                throw new Error("Internal error: Alignment pattern coords undefined");
+            // Finder pattern alanlarıyla çakışmıyorsa çiz
+            if (!matrix.isReserved(x, y)) {
+                drawAlignment(matrix, x - 2, y - 2);
+            }
+        }
+    }
+    // 5. Dark Module (Sabit koyu modül)
+    matrix.setReserved(8, size - 8, true);
+    // 6. Format & Version Alanlarını Rezerve Et (Daha sonra BCH ile doldurulacak)
+    reserveFormatAreas(matrix);
+    if (version >= 7) {
+        reserveVersionAreas(matrix);
+    }
+}
+function drawFinder(matrix, ox, oy) {
+    for (let y = 0; y < 7; y++) {
+        for (let x = 0; x < 7; x++) {
+            const isDark = Math.max(Math.abs(x - 3), Math.abs(y - 3)) === 3 || // Dış 7x7 çerçeve
+                Math.max(Math.abs(x - 3), Math.abs(y - 3)) <= 1; // İç 3x3 kare
+            matrix.setReserved(ox + x, oy + y, isDark);
+        }
+    }
+}
+function drawAlignment(matrix, ox, oy) {
+    for (let y = 0; y < 5; y++) {
+        for (let x = 0; x < 5; x++) {
+            const isDark = Math.max(Math.abs(x - 2), Math.abs(y - 2)) === 2 || // 5x5 çerçeve
+                (x === 2 && y === 2); // Merkez nokta
+            matrix.setReserved(ox + x, oy + y, isDark);
+        }
+    }
+}
+function drawSeparators(matrix) {
+    const size = matrix.size;
+    // Sol Üst
+    for (let i = 0; i < 8; i++) {
+        matrix.setReserved(7, i, false);
+        matrix.setReserved(i, 7, false);
+    }
+    // Sağ Üst
+    for (let i = 0; i < 8; i++) {
+        matrix.setReserved(size - 8, i, false);
+        matrix.setReserved(size - 8 + i, 7, false);
+    }
+    // Sol Alt
+    for (let i = 0; i < 8; i++) {
+        matrix.setReserved(7, size - 8 + i, false);
+        matrix.setReserved(i, size - 8, false);
+    }
+}
+function reserveFormatAreas(matrix) {
+    const size = matrix.size;
+    // Format bitleri alanlarını rezerve et (Timing çizgisi hariç)
+    for (let i = 0; i <= 8; i++) {
+        if (i !== 6)
+            matrix.setReserved(i, 8, false);
+        if (i !== 6)
+            matrix.setReserved(8, i, false);
+    }
+    for (let i = 0; i < 8; i++)
+        matrix.setReserved(size - 1 - i, 8, false);
+    for (let i = 0; i < 7; i++)
+        matrix.setReserved(8, size - 1 - i, false);
+}
+function reserveVersionAreas(matrix) {
+    const size = matrix.size;
+    // Versiyon >= 7 için 3x6 alanlar
+    for (let i = 0; i < 6; i++) {
+        for (let j = 0; j < 3; j++) {
+            matrix.setReserved(size - 11 + j, i, false);
+            matrix.setReserved(i, size - 11 + j, false);
+        }
+    }
+}

package/dist/src/mapping/zigzag.d.ts

@@ -0,0 +1,5 @@
+import type { Matrix } from "../matrix/bit-matrix.js";
+/**
+ * Places bits into the matrix in a zigzag pattern, skipping reserved modules.
+ */
+export declare function zigzag(matrix: Matrix, data: Uint8Array): void;

package/dist/src/mapping/zigzag.js

@@ -0,0 +1,28 @@
+/**
+ * Places bits into the matrix in a zigzag pattern, skipping reserved modules.
+ */
+export function zigzag(matrix, data) {
+    const size = matrix.size;
+    let bitIndex = 0;
+    const totalBits = data.length * 8;
+    for (let right = size - 1; right > 0; right -= 2) {
+        if (right === 6)
+            right--;
+        const upward = ((right + 1) / 2) % 2 !== 0;
+        for (let i = 0; i < size; i++) {
+            const y = upward ? size - 1 - i : i;
+            for (let j = 0; j < 2; j++) {
+                const x = right - j;
+                if (!matrix.isReserved(x, y) && bitIndex < totalBits) {
+                    const byteIndex = Math.floor(bitIndex / 8);
+                    const byte = data[byteIndex];
+                    if (byte === undefined)
+                        throw new Error(`Internal error: Data missing at index ${byteIndex}`);
+                    const bit = (byte >>> (7 - (bitIndex % 8))) & 1;
+                    matrix.set(x, y, bit === 1);
+                    bitIndex++;
+                }
+            }
+        }
+    }
+}

package/dist/src/mask/patterns.d.ts

@@ -0,0 +1,6 @@
+import type { MaskId } from "../types/index.js";
+export type MaskFn = (x: number, y: number) => boolean;
+/**
+ * Standard QR mask patterns (0-7)
+ */
+export declare const MASK_PATTERNS: Record<MaskId, MaskFn>;

package/dist/src/mask/patterns.js

@@ -0,0 +1,13 @@
+/**
+ * Standard QR mask patterns (0-7)
+ */
+export const MASK_PATTERNS = {
+    0: (x, y) => (x + y) % 2 === 0,
+    1: (_x, y) => y % 2 === 0,
+    2: (x, _y) => x % 3 === 0,
+    3: (x, y) => (x + y) % 3 === 0,
+    4: (x, y) => (Math.floor(y / 2) + Math.floor(x / 3)) % 2 === 0,
+    5: (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+    6: (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,
+    7: (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+};

package/dist/src/mask/penalty.d.ts

@@ -0,0 +1,5 @@
+import type { Matrix } from "../matrix/bit-matrix.js";
+/**
+ * Calculates the penalty score for a matrix based on N1-N4 rules.
+ */
+export declare function calculatePenalty(matrix: Matrix): number;

package/dist/src/mask/penalty.js

@@ -0,0 +1,173 @@
+/**
+ * Calculates the penalty score for a matrix based on N1-N4 rules.
+ */
+export function calculatePenalty(matrix) {
+    const size = matrix.size;
+    const data = matrix._data; // Direct access optimization
+    let penalty = 0;
+    let darkCount = 0;
+    // Process Rows: N1, N3, N2, N4 (partial)
+    for (let y = 0; y < size; y++) {
+        let rowRun = 0;
+        let lastBit = -1;
+        // History scalars
+        let h0 = 0, h1 = 0, h2 = 0, h3 = 0, h4 = 0;
+        for (let x = 0; x < size; x++) {
+            const idx = y * size + x;
+            const val = data[idx] ?? 0;
+            const bit = val & 1;
+            if (bit === 1)
+                darkCount++;
+            // N2 (2x2)
+            if (x < size - 1 && y < size - 1) {
+                const right = (data[idx + 1] ?? 0) & 1;
+                const down = (data[idx + size] ?? 0) & 1;
+                const diag = (data[idx + size + 1] ?? 0) & 1;
+                if (bit === right && bit === down && bit === diag) {
+                    penalty += 3;
+                }
+            }
+            // N1 & N3
+            if (bit === lastBit) {
+                rowRun++;
+            }
+            else {
+                if (rowRun >= 5)
+                    penalty += 3 + (rowRun - 5);
+                // Shift history
+                if (lastBit !== -1) {
+                    // Skip initial run
+                    h0 = h1;
+                    h1 = h2;
+                    h2 = h3;
+                    h3 = h4;
+                    h4 = rowRun;
+                    // Check N3
+                    if (lastBit === 1 && checkRatioScalar(h0, h1, h2, h3, h4)) {
+                        if (checkWhiteSpace(data, size, x, y, 1, 0, h0, h1, h2, h3, h4)) {
+                            penalty += 40;
+                        }
+                    }
+                }
+                rowRun = 1;
+                lastBit = bit;
+            }
+        }
+        // End of row
+        if (rowRun >= 5)
+            penalty += 3 + (rowRun - 5);
+        if (lastBit !== -1) {
+            h0 = h1;
+            h1 = h2;
+            h2 = h3;
+            h3 = h4;
+            h4 = rowRun;
+            if (lastBit === 1 && checkRatioScalar(h0, h1, h2, h3, h4)) {
+                if (checkWhiteSpace(data, size, size, y, 1, 0, h0, h1, h2, h3, h4)) {
+                    penalty += 40;
+                }
+            }
+        }
+    }
+    // Process Columns: N1
+    for (let x = 0; x < size; x++) {
+        let colRun = 0;
+        let lastBit = -1;
+        let h0 = 0, h1 = 0, h2 = 0, h3 = 0, h4 = 0;
+        for (let y = 0; y < size; y++) {
+            const idx = y * size + x;
+            const bit = (data[idx] ?? 0) & 1;
+            if (bit === lastBit) {
+                colRun++;
+            }
+            else {
+                if (colRun >= 5)
+                    penalty += 3 + (colRun - 5);
+                if (lastBit !== -1) {
+                    h0 = h1;
+                    h1 = h2;
+                    h2 = h3;
+                    h3 = h4;
+                    h4 = colRun;
+                    if (lastBit === 1 && checkRatioScalar(h0, h1, h2, h3, h4)) {
+                        if (checkWhiteSpace(data, size, x, y, 0, 1, h0, h1, h2, h3, h4)) {
+                            penalty += 40;
+                        }
+                    }
+                }
+                colRun = 1;
+                lastBit = bit;
+            }
+        }
+        if (colRun >= 5)
+            penalty += 3 + (colRun - 5);
+        if (lastBit !== -1) {
+            h0 = h1;
+            h1 = h2;
+            h2 = h3;
+            h3 = h4;
+            h4 = colRun;
+            if (lastBit === 1 && checkRatioScalar(h0, h1, h2, h3, h4)) {
+                if (checkWhiteSpace(data, size, x, size, 0, 1, h0, h1, h2, h3, h4)) {
+                    penalty += 40;
+                }
+            }
+        }
+    }
+    const total = size * size;
+    const ratio = (darkCount * 20) / total;
+    const _diff = Math.abs(ratio - 10);
+    const percentage = (darkCount / total) * 100;
+    const deviation = Math.abs(percentage - 50);
+    penalty += Math.floor(deviation / 5) * 10;
+    return penalty;
+}
+function checkRatioScalar(h0, h1, h2, h3, h4) {
+    if (h0 === 0 || h1 === 0 || h2 === 0 || h3 === 0 || h4 === 0)
+        return false;
+    const total = h0 + h1 + h2 + h3 + h4;
+    if (total < 7)
+        return false;
+    const moduleSize = total / 7;
+    const maxVariance = moduleSize / 2;
+    return (Math.abs(moduleSize - h0) < maxVariance &&
+        Math.abs(moduleSize - h1) < maxVariance &&
+        Math.abs(3 * moduleSize - h2) < 3 * maxVariance &&
+        Math.abs(moduleSize - h3) < maxVariance &&
+        Math.abs(moduleSize - h4) < maxVariance);
+}
+function checkWhiteSpace(data, size, x, y, dx, dy, h0, h1, h2, h3, h4) {
+    const totalLen = h0 + h1 + h2 + h3 + h4;
+    let hasRightWhite = true;
+    for (let i = 0; i < 4; i++) {
+        const px = x + dx * i;
+        const py = y + dy * i;
+        if (px >= size || py >= size)
+            break;
+        const idx = py * size + px;
+        if (((data[idx] ?? 0) & 1) === 1) {
+            hasRightWhite = false;
+            break;
+        }
+    }
+    if (hasRightWhite)
+        return true; // Optimization: If one side is white, we are good?
+    // Wait. "Preceded OR followed by". Yes. If right is white, we satisfy condition.
+    // We don't need to check left.
+    // RETURN TRUE EARLY!
+    let hasLeftWhite = true;
+    const startX = x - dx * totalLen;
+    const startY = y - dy * totalLen;
+    for (let i = 1; i <= 4; i++) {
+        const px = startX - dx * i;
+        const py = startY - dy * i;
+        if (px < 0 || py < 0)
+            break;
+        const idx = py * size + px;
+        if (((data[idx] ?? 0) & 1) === 1) {
+            hasLeftWhite = false;
+            break;
+        }
+    }
+    return hasLeftWhite;
+}

package/dist/src/mask/selection.d.ts

@@ -0,0 +1,12 @@
+import { Matrix } from "../matrix/bit-matrix.js";
+import type { EccLevel, MaskId } from "../types/index.js";
+/**
+ * Evaluates all 8 masks and applies the one with the lowest penalty.
+ * Implements the deterministic tie-break (lowest ID).
+ */
+export declare function selectAndApplyBestMask(matrix: Matrix, ecc: EccLevel): {
+    mask: MaskId;
+    penalties: number[];
+};
+export declare function applyMask(matrix: Matrix, maskId: MaskId): void;
+export declare function writeFormatInformation(matrix: Matrix, ecc: EccLevel, maskId: MaskId): void;