qr-core 1.0.0 → 1.0.1

package/README.md

@@ -110,9 +110,9 @@ Run `npm run bench` to reproduce.
 
 | Scenario | Description | p50 (ms) | p95 (ms) |
 | :--- | :--- | :---: | :---: |
-| **Small** | Auto version/mask, ecc M ("HELLO WORLD") | **0.066** | **0.138** |
-| **Medium** | Auto version/mask, ecc M (~500 bytes URL‑ish payload) | **1.262** | **1.403** |
-| **Large** | Auto version/mask, ecc L (3000 bytes) | **3.849** | **3.984** |
+| **Small** | Auto version/mask, ecc M ("HELLO WORLD") | **0.074** | **0.138** |
+| **Medium** | Auto version/mask, ecc M (~500 bytes URL‑ish payload) | **1.275** | **1.527** |
+| **Large** | Auto version/mask, ecc L (3000 bytes) | **4.082** | **4.536** |
 
 > Benchmarks captured on 2026‑01‑31 with Node v24.7.0 (darwin arm64). Goal from RFC: version‑40 near‑capacity with auto‑mask < 5ms — **met**.
 

package/dist/{src/api → api}/index.js

@@ -153,9 +153,7 @@ function validateOptions(options, ecc, charset, quietZone) {
         throw new QrException("INVALID_OPTIONS", `Invalid charset: ${charset}`);
     }
     if (options.mode !== undefined && options.mode !== "auto") {
-        if (options.mode !== "numeric" &&
-            options.mode !== "alphanumeric" &&
-            options.mode !== "byte") {
+        if (options.mode !== "numeric" && options.mode !== "alphanumeric" && options.mode !== "byte") {
             throw new QrException("INVALID_OPTIONS", `Invalid mode: ${options.mode}`);
         }
     }
@@ -196,6 +194,8 @@ function prepareSegments(segments, charset, strict) {
                 const bytes = encodeByteString(segment.data, charset, strict);
                 return { ...segment, bytes, count: bytes.length };
             }
+            default:
+                throw new QrException("INTERNAL_INVARIANT_BROKEN", `Unknown segment mode: ${segment.mode}`);
         }
     });
 }

package/dist/{src/mapping → mapping}/zigzag.js

@@ -5,10 +5,11 @@ 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) {
+    const last = size - 1;
+    for (let right = last, pairIndex = 0; right > 0; right -= 2, pairIndex++) {
         if (right === 6)
             right--;
-        const upward = ((right + 1) / 2) % 2 !== 0;
+        const upward = pairIndex % 2 === 0;
         for (let i = 0; i < size; i++) {
             const y = upward ? size - 1 - i : i;
             for (let j = 0; j < 2; j++) {

package/dist/{src/mask → mask}/selection.js

@@ -141,7 +141,7 @@ export function writeFormatInformation(matrix, ecc, maskId) {
     const formatBits = getFormatInfo(ecc, maskId);
     const size = matrix.size;
     for (let i = 0; i < 15; i++) {
-        const bit = (formatBits >>> i) & 1;
+        const bit = (formatBits >>> (14 - i)) & 1;
         // Top-left
         let x;
         let y;
@@ -168,6 +168,8 @@ export function writeFormatInformation(matrix, ecc, maskId) {
         if (i < 8) {
             x2 = 8;
             y2 = size - 1 - i;
+            if (y2 === size - 8)
+                continue; // skip dark module
         }
         else {
             x2 = size - 15 + i;

package/dist/{src/matrix → matrix}/bit-matrix.js

@@ -88,9 +88,7 @@ export class Matrix {
     toRows() {
         const rows = [];
         for (let y = 0; y < this.size; y++) {
-            rows.push(this.data
-                .slice(y * this.size, (y + 1) * this.size)
-                .map((v) => (v & 1)));
+            rows.push(this.data.slice(y * this.size, (y + 1) * this.size).map((v) => (v & 1)));
         }
         return rows;
     }

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "qr-core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Deterministic, zero-dependency QR Code Model 2 encoder (matrix-only)",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "test": "vitest",
     "lint": "biome check src tests bench",
@@ -39,6 +40,8 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@types/node": "^25.1.0",
+    "jsqr": "^1.4.0",
+    "pngjs": "^7.0.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }

package/dist/bench/bench.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/bench/bench.js

@@ -1,38 +0,0 @@
-import { encode } from "../src/index.js";
-function bench(name, fn, iterations = 100) {
-    // Warmup
-    for (let i = 0; i < 10; i++)
-        fn();
-    const times = [];
-    for (let i = 0; i < iterations; i++) {
-        const start = performance.now();
-        fn();
-        const end = performance.now();
-        times.push(end - start);
-    }
-    times.sort((a, b) => a - b);
-    const p50 = times[Math.floor(times.length * 0.5)] || 0;
-    const p95 = times[Math.floor(times.length * 0.95)] || 0;
-    const avg = times.reduce((a, b) => a + b, 0) / times.length;
-    console.log(`${name}:`);
-    console.log(`  p50: ${p50.toFixed(3)}ms`);
-    console.log(`  p95: ${p95.toFixed(3)}ms`);
-    console.log(`  avg: ${avg.toFixed(3)}ms`);
-}
-async function runBenchmarks() {
-    console.log("Running benchmarks...\n");
-    const smallPayload = "HELLO WORLD";
-    bench("Small Payload (auto version/mask, ecc M)", () => {
-        encode(smallPayload, { ecc: "M" });
-    });
-    const mediumPayload = "https://example.com/search?q=" + "A".repeat(480);
-    bench("Medium Payload (~500 bytes, auto version/mask, ecc M)", () => {
-        encode(mediumPayload, { ecc: "M" });
-    });
-    const largePayload = "A".repeat(3000);
-    // Version 40-L holds 3181 data codewords; 3000 bytes fits.
-    bench("Large Payload (3000 bytes, auto version/mask, ecc L)", () => {
-        encode(largePayload, { ecc: "L" });
-    });
-}
-runBenchmarks();

package/dist/tests/golden/golden.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/golden/golden.test.js

@@ -1,26 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { encode } from "../../src/api/index";
-const vectorsDir = path.join(__dirname, "../vectors");
-const vectorFiles = fs
-    .readdirSync(vectorsDir)
-    .filter((f) => f.endsWith(".json"));
-let vectors = [];
-for (const file of vectorFiles) {
-    const content = JSON.parse(fs.readFileSync(path.join(vectorsDir, file), "utf-8"));
-    vectors = vectors.concat(content);
-}
-describe("Golden Vectors", () => {
-    for (const vec of vectors) {
-        it(`should match vector: ${vec.name}`, () => {
-            // Normalize inputs
-            // biome-ignore lint/suspicious/noExplicitAny: generic casting for options
-            const opts = { ...vec.options };
-            const result = encode(vec.input.value, opts);
-            expect(result.version).toBe(vec.expected.version);
-            expect(result.size).toBe(vec.expected.size);
-            // In a real golden test, we would compare the entire matrix hash/bits
-        });
-    }
-});

package/dist/tests/unit/api.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/unit/api.test.js

@@ -1,35 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { encode, encodeSafe } from "../../src/api/index";
-describe("Public API", () => {
-    it("should encode simple string", () => {
-        const result = encode("Hello World");
-        expect(result.version).toBeGreaterThan(0);
-        expect(result.size).toBeGreaterThan(0);
-        expect(result.matrix).toBeDefined();
-    });
-    it("should allow forcing version", () => {
-        const result = encode("A", { version: 5 });
-        expect(result.version).toBe(5);
-        expect(result.size).toBe(21 + 4 * (5 - 1));
-    });
-    it("should throw if data too large for fixed version", () => {
-        // Version 1 can only hold ~17 bytes (Ecc L)
-        // "A" * 100 needs version ~4
-        const largeData = "A".repeat(100);
-        // Expect message to contain "Data requires version"
-        expect(() => encode(largeData, { version: 1 })).toThrow(/Data requires version/);
-    });
-    it("should safe encode without throwing", () => {
-        const largeData = "A".repeat(100);
-        const result = encodeSafe(largeData, { version: 1 });
-        expect(result.ok).toBe(false);
-        if (!result.ok) {
-            expect(result.error.code).toBe("DATA_TOO_LARGE");
-        }
-    });
-    it("should support Uint8Array input", () => {
-        const input = new Uint8Array([65, 66, 67]);
-        const result = encode(input, { mode: "byte" });
-        expect(result.version).toBe(1);
-    });
-});

package/dist/tests/unit/bit-matrix.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/unit/bit-matrix.test.js

@@ -1,46 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { Matrix } from "../../src/matrix/bit-matrix";
-describe("BitMatrix", () => {
-    it("should initialize with correct size and default values", () => {
-        const size = 21;
-        const matrix = new Matrix(size);
-        expect(matrix.size).toBe(size);
-        expect(matrix.get(0, 0)).toBe(0);
-        expect(matrix.get(size - 1, size - 1)).toBe(0);
-    });
-    it("should set and get values", () => {
-        const matrix = new Matrix(21);
-        matrix.set(5, 5, true);
-        expect(matrix.get(5, 5)).toBe(1);
-        matrix.set(5, 5, false);
-        expect(matrix.get(5, 5)).toBe(0);
-    });
-    it("should handle reserved modules", () => {
-        const matrix = new Matrix(21);
-        matrix.setReserved(10, 10, true);
-        expect(matrix.isReserved(10, 10)).toBe(true);
-        expect(matrix.get(10, 10)).toBe(1);
-        // Normal set should not overwrite reserved
-        matrix.set(10, 10, false);
-        expect(matrix.get(10, 10)).toBe(1);
-    });
-    it("should throw on out of bounds access", () => {
-        const matrix = new Matrix(21);
-        expect(() => matrix.get(-1, 0)).toThrow();
-        expect(() => matrix.get(0, 21)).toThrow();
-        expect(() => matrix.set(21, 0, true)).toThrow();
-        expect(() => matrix.setReserved(0, -1, true)).toThrow();
-    });
-    it("should serialize to packed bytes correct MSB-first order", () => {
-        // Size 9 -> 2 bytes per row
-        // Row 0: 10000000 1.......
-        const matrix = new Matrix(9);
-        matrix.set(0, 0, true); // First bit
-        matrix.set(8, 0, true); // 9th bit (first bit of second byte)
-        const packed = matrix.toPacked();
-        expect(packed.length).toBe(9 * 2);
-        // Row 0
-        expect(packed[0]).toBe(0x80); // 10000000
-        expect(packed[1]).toBe(0x80); // 10000000 (padded)
-    });
-});

package/dist/tests/unit/core.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/unit/core.test.js

@@ -1,88 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { BitBuffer } from "../../src/core/bit-buffer";
-import { EXP, inv, LOG, mul } from "../../src/core/gf";
-import { computeEcc } from "../../src/core/rs";
-describe("GF(256)", () => {
-    it("should have correct table sizes", () => {
-        expect(EXP.length).toBe(512);
-        expect(LOG.length).toBe(256);
-    });
-    it("EXP[0] should be 1", () => {
-        expect(EXP[0]).toBe(1);
-        expect(EXP[255]).toBe(1);
-    });
-    it("LOG[1] should be 0", () => {
-        expect(LOG[1]).toBe(0);
-    });
-    it("multiplication should be correct", () => {
-        expect(mul(0, 5)).toBe(0);
-        expect(mul(5, 0)).toBe(0);
-        expect(mul(1, 10)).toBe(10);
-        // 2 * 2 = 4
-        expect(mul(2, 2)).toBe(4);
-        // Inverse check
-        const a = 123;
-        const invA = inv(a);
-        expect(mul(a, invA)).toBe(1);
-    });
-});
-describe("BitBuffer", () => {
-    it("should append bits correctly", () => {
-        const bb = new BitBuffer();
-        bb.put(0b1, 1);
-        bb.put(0b0, 1);
-        bb.put(0b1, 1);
-        // current: 101 (5)
-        // length: 3
-        expect(bb.length).toBe(3);
-        const bytes = bb.toBytes();
-        // 10100000 = 0xA0
-        expect(bytes[0]).toBe(0xa0);
-    });
-    it("should handle multi-bit put", () => {
-        const bb = new BitBuffer();
-        // append 0xABC (101010111100) 12 bits
-        bb.put(0xabc, 12);
-        expect(bb.length).toBe(12);
-        const bytes = bb.toBytes();
-        // 10101011 1100xxxx
-        // 0xAB     0xC0
-        expect(bytes[0]).toBe(0xab);
-        expect((bytes[1] ?? 0) & 0xf0).toBe(0xc0);
-    });
-});
-describe("Reed-Solomon", () => {
-    it("should return all zeros for zero data", () => {
-        const data = new Uint8Array([0, 0, 0]);
-        const ecc = computeEcc(data, 5);
-        expect(ecc).toEqual(new Uint8Array(5));
-    });
-    // Simple known vector check could be added here if we had one.
-    // Using a known property check:
-    // If we encode M(x), then M(x)x^n + R(x) is a codeword.
-    // This means it evaluates to 0 at the roots of G(x)?
-    // Roots of G(x) are 2^0, 2^1 ... 2^{n-1}.
-    // Let's check with eccLen=2. Roots 2^0=1, 2^1=2.
-    // Codeword C(x) should satisfy C(1)=0 and C(2)=0.
-    it("should produce valid codewords (eval to 0 at roots)", () => {
-        const message = new Uint8Array([10, 20, 30]);
-        const eccLen = 2; // Roots: 1, 2
-        const ecc = computeEcc(message, eccLen);
-        // Construct full codeword: message * x^n + ecc
-        // Coefficients: [10, 20, 30, ecc[0], ecc[1]]
-        const codeword = new Uint8Array([...message, ...ecc]);
-        // Evaluate at root 1 (2^0) = 1
-        // Eval(x) = c0*x^4 + c1*x^3 + ...
-        function evalPoly(poly, x) {
-            let res = 0;
-            for (const coeff of poly) {
-                res = mul(res, x) ^ coeff;
-            }
-            return res;
-        }
-        const root0 = EXP[0] ?? 0; // 1
-        const root1 = EXP[1] ?? 0; // 2
-        expect(evalPoly(codeword, root0)).toBe(0);
-        expect(evalPoly(codeword, root1)).toBe(0);
-    });
-});

package/dist/tests/unit/encoding.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/unit/encoding.test.js

@@ -1,63 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { BitBuffer } from "../../src/core/bit-buffer";
-import { encodeAlphanumeric, encodeByte, encodeNumeric, } from "../../src/encoding/encoders";
-import { interleave } from "../../src/encoding/interleave";
-import { segmentize } from "../../src/encoding/segmentation";
-describe("Encoders", () => {
-    it("should encode numeric data", () => {
-        const buffer = new BitBuffer();
-        // "01234567" -> "012" (10 bits) + "345" (10 bits) + "67" (7 bits)
-        encodeNumeric("01234567", buffer);
-        // 012 = 0000001100
-        // 345 = 0101011001
-        // 67  = 1000011
-        expect(buffer.length).toBe(27);
-    });
-    it("should encode alphanumeric data", () => {
-        const buffer = new BitBuffer();
-        // "AC-42" -> "AC" (11) + "-4" (11) + "2" (6)
-        encodeAlphanumeric("AC-42", buffer);
-        expect(buffer.length).toBe(11 + 11 + 6);
-    });
-    it("should encode byte data", () => {
-        const buffer = new BitBuffer();
-        encodeByte("Hello", buffer);
-        expect(buffer.length).toBe(5 * 8);
-    });
-});
-describe("Segmentation", () => {
-    it("should segment simple numeric", () => {
-        const segments = segmentize("0123456789");
-        expect(segments).toHaveLength(1);
-        expect(segments[0]?.mode).toBe("numeric");
-    });
-    it("should segment simple alphanumeric", () => {
-        const segments = segmentize("HELLO WORLD");
-        expect(segments).toHaveLength(1);
-        expect(segments[0]?.mode).toBe("alphanumeric");
-    });
-    it("should segment mixed content", () => {
-        // "123ABC123" -> numeric, alphanumeric, numeric
-        // Our greedy segmenter might merge if it's suboptimal, but let's see current behavior.
-        // "123" (num) "ABC" (alnum) "123" (num)
-        const segments = segmentize("123ABC123");
-        // Actually, greedy might switch eagerly.
-        // "123" -> numeric
-        // "A" -> switch to Alnum
-        // "123" -> switch to Numeric
-        expect(segments.map((s) => s.mode)).toEqual([
-            "numeric",
-            "alphanumeric",
-            "numeric",
-        ]);
-    });
-});
-describe("Interleave", () => {
-    it("should interleave data and ecc correctly", () => {
-        // Mock data that fits version 1-L (19 data bytes)
-        const data = new Uint8Array(19).fill(0x11);
-        // Version 1-L: 19 data bytes, 7 ECC bytes. Total 26.
-        const result = interleave(data, 1, "L");
-        expect(result.length).toBe(26);
-    });
-});

package/dist/tests/unit/layout.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/unit/layout.test.js

@@ -1,62 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { setupFunctionPatterns } from "../../src/layout/patterns";
-import { Matrix } from "../../src/matrix/bit-matrix";
-describe("Layout Patterns", () => {
-    it("should set up finder patterns", () => {
-        const matrix = new Matrix(21);
-        setupFunctionPatterns(matrix, 1);
-        // Top Left Finder
-        expect(matrix.isReserved(3, 3)).toBe(true); // Center of 3x3
-        // Finder is 7x7. (0,0) to (6,6). Center (3,3).
-        // (3,3) is dark.
-        expect(matrix.get(3, 3)).toBe(1);
-        // (0,0) is dark (outer ring)
-        expect(matrix.get(0, 0)).toBe(1);
-        // (1,1) is light (gap between outer and inner) - wait no
-        // 7x7 finder:
-        // xxxxxxx
-        // x.....x
-        // x.xxx.x
-        // x.xxx.x
-        // x.xxx.x
-        // x.....x
-        // xxxxxxx
-        // (0,0) dark
-        // (1,1) light?
-        // Logic: max(abs(x-3), abs(y-3))
-        // (1,1): abs(-2)=2. max(2,2)=2.
-        // isDark = (max === 3) || (max <= 1).
-        // 2 is not 3, nor <= 1. So light. Correct.
-        expect(matrix.get(1, 1)).toBe(0);
-    });
-    it("should set up timing patterns", () => {
-        const matrix = new Matrix(21);
-        setupFunctionPatterns(matrix, 1);
-        // Row 6, Cols 8..Size-8 (8..13 for V1)
-        // (8, 6) -> i=8. even -> dark (true)
-        // (9, 6) -> light
-        expect(matrix.isReserved(8, 6)).toBe(true);
-        expect(matrix.get(8, 6)).toBe(1);
-        expect(matrix.get(9, 6)).toBe(0);
-    });
-    it("should set up alignment patterns for V2", () => {
-        const matrix = new Matrix(25); // V2 size
-        setupFunctionPatterns(matrix, 2);
-        // V2 alignment at 6, 18
-        // (6,6) is finder.
-        // (18,18) should be alignment center.
-        // Alignment is 5x5 center (18,18).
-        expect(matrix.isReserved(18, 18)).toBe(true);
-        // Center is dark
-        expect(matrix.get(18, 18)).toBe(1);
-    });
-    it("should set up version info for V7", () => {
-        const matrix = new Matrix(45); // V7 size
-        setupFunctionPatterns(matrix, 7);
-        // Version info is 3x6 block above bottom-left finder and left of top-right finder.
-        // Bottom-left finder is at (0, Size-7).
-        // Version info above it: Row Size-11..Size-9. Col 0..5
-        // Let's check reservation.
-        expect(matrix.isReserved(0, 45 - 11)).toBe(true);
-    });
-});

package/dist/tests/unit/masking.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/unit/masking.test.js

@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { applyMask, selectAndApplyBestMask } from "../../src/mask/selection";
-import { Matrix } from "../../src/matrix/bit-matrix";
-describe("Masking", () => {
-    it("should allow applying a specific mask", () => {
-        const matrix = new Matrix(21);
-        // Mask 0: (x+y)%2 == 0
-        applyMask(matrix, 0);
-        // (0,0) -> even -> flip inv (0->1)
-        expect(matrix.get(0, 0)).toBe(1);
-        // (0,1) -> odd -> 0
-        expect(matrix.get(0, 1)).toBe(0);
-    });
-    it("should select the best mask", () => {
-        const matrix = new Matrix(21);
-        // Empty matrix -> penalty calculation will favor a mask that breaks up large white areas
-        // or one that doesn't create false patterns.
-        const result = selectAndApplyBestMask(matrix, "M");
-        expect(result.mask).toBeGreaterThanOrEqual(0);
-        expect(result.mask).toBeLessThanOrEqual(7);
-        expect(result.penalties).toHaveLength(8);
-        // Ensure format info was written
-        // (8,0) to (8,8) area
-        let formatInfoWritten = false;
-        for (let i = 0; i < 9; i++) {
-            if (matrix.isReserved(i, 8))
-                formatInfoWritten = true;
-        }
-        expect(formatInfoWritten).toBe(true);
-    });
-});