quadqr-js 0.7.0

package/bin/quadqr.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import {
+  bytesToHex,
+  decryptDecoded,
+  encodeSecureText,
+  encodeText,
+  generateRaw256Key
+} from "../dist/index.js";
+import { savePNG, scanFile } from "../dist/node.js";
+
+function help() {
+  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png] [--ecc M] [--version auto|1..40]\n  quadqr encode <text> --password <password> [-o file.png]\n  quadqr encode <text> --key <64-hex-key> [-o file.png]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>]\n  quadqr keygen\n\nOptions:\n  -o, --output <file>       Output PNG path (default: quadqr.png)\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --module-size <px>        PNG module size (default: 12)\n  --quiet-zone <modules>    PNG quiet zone (default: 4)\n  -h, --help                Show help\n`);
+}
+
+function parse(argv) {
+  const args = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "-h" || token === "--help") flags.help = true;
+    else if (token === "-o" || token === "--output") flags.output = argv[++i];
+    else if (token === "--ecc") flags.ecc = argv[++i];
+    else if (token === "--version") flags.version = argv[++i];
+    else if (token === "--password") flags.password = argv[++i];
+    else if (token === "--key") flags.key = argv[++i];
+    else if (token === "--module-size") flags.moduleSize = Number(argv[++i]);
+    else if (token === "--quiet-zone") flags.quietZone = Number(argv[++i]);
+    else args.push(token);
+  }
+  return { args, flags };
+}
+
+async function main() {
+  const { args, flags } = parse(process.argv.slice(2));
+  if (flags.help || !args.length) {
+    help();
+    return;
+  }
+
+  const command = args.shift();
+  if (command === "keygen") {
+    console.log(bytesToHex(generateRaw256Key()));
+    return;
+  }
+
+  if (command === "encode") {
+    const text = args.join(" ");
+    if (!text) throw new Error("encode requires text.");
+    if (flags.password && flags.key) throw new Error("Choose password mode or raw-key mode, not both.");
+
+    const options = {
+      ecc: flags.ecc || "M",
+      ...(flags.version && flags.version !== "auto" ? { version: Number(flags.version) } : {})
+    };
+    const code = flags.password
+      ? await encodeSecureText(text, { ...options, security: { mode: "password", password: flags.password } })
+      : flags.key
+        ? await encodeSecureText(text, { ...options, security: { mode: "raw-key", key: flags.key } })
+        : encodeText(text, options);
+
+    const output = flags.output || "quadqr.png";
+    const saved = await savePNG(code, output, {
+      moduleSize: flags.moduleSize || 12,
+      quietZone: Number.isFinite(flags.quietZone) ? flags.quietZone : 4
+    });
+    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ECC ${code.eccLevel}).`);
+    return;
+  }
+
+  if (command === "decode") {
+    const filename = args[0];
+    if (!filename) throw new Error("decode requires an image filename.");
+    let result = await scanFile(filename);
+    if (result.secure) {
+      if (!flags.password && !flags.key) {
+        console.log(JSON.stringify({
+          secure: true,
+          mode: result.security?.mode,
+          algorithm: result.security?.algorithm,
+          keyId: result.security?.keyId || result.security?.keyIdHex || null,
+          requiresDecryption: true
+        }, null, 2));
+        process.exitCode = 2;
+        return;
+      }
+      result = await decryptDecoded(result, flags.password ? { password: flags.password } : { key: flags.key });
+    }
+    if (result.text != null) console.log(result.text);
+    else process.stdout.write(Buffer.from(result.payload));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  console.error(`QuadQR: ${error.message}`);
+  process.exitCode = 1;
+});

package/dist/benchmark.cjs

@@ -0,0 +1 @@
+module.exports = require("./benchmark.js");

package/dist/benchmark.js

@@ -0,0 +1 @@
+export * from "./esm/benchmark.js";

package/dist/browser.js

@@ -0,0 +1,2 @@
+export * from "./esm/quadqr.js";
+export { initWasm, getWasmState, disableWasm } from "./esm/wasm.js";

package/dist/esm/benchmark.js

@@ -0,0 +1,193 @@
+/**
+ * Benchmark helpers for QuadQR.
+ *
+ * Standard QR capacities below are ISO QR byte-mode payload capacities for
+ * versions 1..40. They are used only for same-matrix-size capacity comparison.
+ * The QuadQR ECC profile letters are convenience names and are NOT
+ * calibrated to the same recovery percentages as ISO QR L/M/Q/H.
+ */
+
+import {
+  encodeBytes,
+  decodeMatrix,
+  getVersionInfo,
+  MAX_VERSION
+} from "./quadqr.js";
+
+export const STANDARD_QR_BYTE_CAPACITY = Object.freeze({
+  L: Object.freeze([17, 32, 53, 78, 106, 134, 154, 192, 230, 271, 321, 367, 425, 458, 520, 586, 644, 718, 792, 858, 929, 1003, 1091, 1171, 1273, 1367, 1465, 1528, 1628, 1732, 1840, 1952, 2068, 2188, 2303, 2431, 2563, 2699, 2809, 2953]),
+  M: Object.freeze([14, 26, 42, 62, 84, 106, 122, 152, 180, 213, 251, 287, 331, 362, 412, 450, 504, 560, 624, 666, 711, 779, 857, 911, 997, 1059, 1125, 1190, 1264, 1370, 1452, 1538, 1628, 1722, 1809, 1911, 1989, 2099, 2213, 2331]),
+  Q: Object.freeze([11, 20, 32, 46, 60, 74, 86, 108, 130, 151, 177, 203, 241, 258, 292, 322, 364, 394, 442, 482, 509, 565, 611, 661, 715, 751, 805, 868, 908, 982, 1030, 1112, 1168, 1228, 1283, 1351, 1423, 1499, 1579, 1663]),
+  H: Object.freeze([7, 14, 24, 34, 44, 58, 64, 84, 98, 119, 137, 155, 177, 194, 220, 250, 280, 310, 338, 382, 403, 439, 461, 511, 535, 593, 625, 658, 698, 742, 790, 842, 898, 958, 983, 1051, 1093, 1139, 1219, 1273])
+});
+
+function normalizeEcc(ecc = "M") {
+  const value = String(ecc).toUpperCase();
+  if (!STANDARD_QR_BYTE_CAPACITY[value]) {
+    throw new Error("ECC must be one of L, M, Q, H.");
+  }
+  return value;
+}
+
+function nowMs() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+
+function makePayload(length, seed = 0x51) {
+  const out = new Uint8Array(length);
+  let state = (seed ^ length) >>> 0;
+  for (let i = 0; i < length; i++) {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    out[i] = state & 0xff;
+  }
+  return out;
+}
+
+function percentile(values, p) {
+  if (!values.length) return 0;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+  return sorted[index];
+}
+
+function summarize(samples) {
+  if (!samples.length) return { meanMs: 0, medianMs: 0, p95Ms: 0, minMs: 0, maxMs: 0 };
+  const total = samples.reduce((sum, value) => sum + value, 0);
+  const sorted = samples.slice().sort((a, b) => a - b);
+  return {
+    meanMs: total / samples.length,
+    medianMs: percentile(sorted, 0.5),
+    p95Ms: percentile(sorted, 0.95),
+    minMs: sorted[0],
+    maxMs: sorted[sorted.length - 1]
+  };
+}
+
+export function getStandardQrByteCapacity(version, ecc = "M") {
+  if (!Number.isInteger(version) || version < 1 || version > MAX_VERSION) {
+    throw new Error(`Version must be 1..${MAX_VERSION}.`);
+  }
+  return STANDARD_QR_BYTE_CAPACITY[normalizeEcc(ecc)][version - 1];
+}
+
+export function compareCapacity(version, ecc = "M") {
+  const level = normalizeEcc(ecc);
+  const quadqr = getVersionInfo(version, { ecc: level });
+  const standardQrBytes = getStandardQrByteCapacity(version, level);
+  const quadqrBytes = quadqr.capacityBytes;
+  const differenceBytes = quadqrBytes - standardQrBytes;
+  const ratio = standardQrBytes > 0 ? quadqrBytes / standardQrBytes : null;
+  const gainPercent = standardQrBytes > 0 ? (differenceBytes / standardQrBytes) * 100 : null;
+
+  return {
+    version,
+    size: quadqr.size,
+    ecc: level,
+    quadqrBytes,
+    standardQrBytes,
+    differenceBytes,
+    ratio,
+    gainPercent,
+    quadqrBitsPerDataCell: quadqr.bitsPerDataCell,
+    quadqrPayloadEfficiencyPercent: quadqr.theoreticalBits > 0
+      ? (quadqrBytes * 8 / quadqr.theoreticalBits) * 100
+      : 0,
+    quadqrPayloadBitsPerMatrixCell: quadqrBytes * 8 / (quadqr.size * quadqr.size),
+    standardQrPayloadBitsPerMatrixCell: standardQrBytes * 8 / (quadqr.size * quadqr.size),
+    note: "ECC profile letters are nominal only; recovery strength is not equivalent to ISO QR."
+  };
+}
+
+export function buildCapacityComparison(options = {}) {
+  const ecc = normalizeEcc(options.ecc ?? "M");
+  const versions = options.versions ?? Array.from({ length: MAX_VERSION }, (_, i) => i + 1);
+  return versions.map((version) => compareCapacity(version, ecc));
+}
+
+export function benchmarkCodec(options = {}) {
+  const ecc = normalizeEcc(options.ecc ?? "M");
+  const iterations = Math.max(1, Math.floor(options.iterations ?? 30));
+  const warmup = Math.max(0, Math.floor(options.warmup ?? Math.min(5, iterations)));
+  const requestedSizes = options.payloadSizes ?? [24, 32, 128, 512, 1024, 2048];
+  const results = [];
+
+  for (const requestedSize of requestedSizes) {
+    const payloadBytes = Math.max(0, Math.floor(requestedSize));
+    const payload = makePayload(payloadBytes);
+
+    let probe;
+    try {
+      probe = encodeBytes(payload, { ecc });
+    } catch (error) {
+      results.push({ payloadBytes, skipped: true, reason: error.message });
+      continue;
+    }
+
+    for (let i = 0; i < warmup; i++) {
+      const encoded = encodeBytes(payload, { ecc, version: probe.version });
+      decodeMatrix(encoded.matrix);
+    }
+
+    const encodeSamples = [];
+    const decodeSamples = [];
+    let encoded = probe;
+
+    for (let i = 0; i < iterations; i++) {
+      let start = nowMs();
+      encoded = encodeBytes(payload, { ecc, version: probe.version });
+      encodeSamples.push(nowMs() - start);
+
+      start = nowMs();
+      const decoded = decodeMatrix(encoded.matrix);
+      decodeSamples.push(nowMs() - start);
+
+      if (decoded.payload.length !== payload.length) {
+        throw new Error(`Benchmark decode length mismatch at ${payloadBytes} bytes.`);
+      }
+    }
+
+    const versionInfo = getVersionInfo(encoded.version, { ecc });
+    results.push({
+      payloadBytes,
+      skipped: false,
+      version: encoded.version,
+      size: encoded.size,
+      capacityBytes: versionInfo.capacityBytes,
+      utilizationPercent: versionInfo.capacityBytes > 0
+        ? (payloadBytes / versionInfo.capacityBytes) * 100
+        : 0,
+      encode: summarize(encodeSamples),
+      decode: summarize(decodeSamples),
+      iterations
+    });
+  }
+
+  return {
+    format: "QuadQR",
+    ecc,
+    iterations,
+    warmup,
+    generatedAt: new Date().toISOString(),
+    results
+  };
+}
+
+export function benchmarkReport(options = {}) {
+  const ecc = normalizeEcc(options.ecc ?? "M");
+  const versions = options.versions ?? [1, 2, 5, 10, 20, 30, 40];
+  return {
+    capacity: buildCapacityComparison({ ecc, versions }),
+    performance: benchmarkCodec({
+      ecc,
+      iterations: options.iterations ?? 30,
+      warmup: options.warmup,
+      payloadSizes: options.payloadSizes
+    }),
+    caveat: "QuadQR and standard QR ECC labels are not equivalent recovery targets. Capacity rows compare equal matrix dimensions and same letter only."
+  };
+}

package/dist/esm/geometry.js

@@ -0,0 +1,149 @@
+/**
+ * Shared QuadQR matrix geometry helpers.
+ *
+ * Versions 2..40 use the same alignment-pattern center schedule as standard
+ * QR Code matrices. QuadQR remains its own symbology, but reuses that proven
+ * spatial distribution for alignment references. QuadQR uses one 5x5 primary
+ * alignment reference at the bottom-right and compact 3x3 secondary markers.
+ * Version 1 keeps the legacy QuadQR bottom-right bootstrap marker because standard QR v1 has no
+ * alignment pattern and the QuadQR camera scanner needs a fourth projective
+ * reference point.
+ */
+
+export const MIN_GEOMETRY_VERSION = 1;
+export const MAX_GEOMETRY_VERSION = 40;
+
+// Index by version. Entry 0 is unused. Values are module indices of alignment
+// pattern centers, matching the standard QR Code version layout for v2..v40.
+export const ALIGNMENT_PATTERN_AXES = Object.freeze([
+  null,
+  Object.freeze([]),
+  Object.freeze([6, 18]),
+  Object.freeze([6, 22]),
+  Object.freeze([6, 26]),
+  Object.freeze([6, 30]),
+  Object.freeze([6, 34]),
+  Object.freeze([6, 22, 38]),
+  Object.freeze([6, 24, 42]),
+  Object.freeze([6, 26, 46]),
+  Object.freeze([6, 28, 50]),
+  Object.freeze([6, 30, 54]),
+  Object.freeze([6, 32, 58]),
+  Object.freeze([6, 34, 62]),
+  Object.freeze([6, 26, 46, 66]),
+  Object.freeze([6, 26, 48, 70]),
+  Object.freeze([6, 26, 50, 74]),
+  Object.freeze([6, 30, 54, 78]),
+  Object.freeze([6, 30, 56, 82]),
+  Object.freeze([6, 30, 58, 86]),
+  Object.freeze([6, 34, 62, 90]),
+  Object.freeze([6, 28, 50, 72, 94]),
+  Object.freeze([6, 26, 50, 74, 98]),
+  Object.freeze([6, 30, 54, 78, 102]),
+  Object.freeze([6, 28, 54, 80, 106]),
+  Object.freeze([6, 32, 58, 84, 110]),
+  Object.freeze([6, 30, 58, 86, 114]),
+  Object.freeze([6, 34, 62, 90, 118]),
+  Object.freeze([6, 26, 50, 74, 98, 122]),
+  Object.freeze([6, 30, 54, 78, 102, 126]),
+  Object.freeze([6, 26, 52, 78, 104, 130]),
+  Object.freeze([6, 30, 56, 82, 108, 134]),
+  Object.freeze([6, 34, 60, 86, 112, 138]),
+  Object.freeze([6, 30, 58, 86, 114, 142]),
+  Object.freeze([6, 34, 62, 90, 118, 146]),
+  Object.freeze([6, 30, 54, 78, 102, 126, 150]),
+  Object.freeze([6, 24, 50, 76, 102, 128, 154]),
+  Object.freeze([6, 28, 54, 80, 106, 132, 158]),
+  Object.freeze([6, 32, 58, 84, 110, 136, 162]),
+  Object.freeze([6, 26, 54, 82, 110, 138, 166]),
+  Object.freeze([6, 30, 58, 86, 114, 142, 170])
+]);
+
+function assertVersion(version) {
+  if (!Number.isInteger(version) || version < MIN_GEOMETRY_VERSION || version > MAX_GEOMETRY_VERSION) {
+    throw new Error(`Version must be ${MIN_GEOMETRY_VERSION}..${MAX_GEOMETRY_VERSION}.`);
+  }
+}
+
+export function sizeForVersion(version) {
+  assertVersion(version);
+  return 21 + 4 * (version - 1);
+}
+
+export function versionFromSize(size) {
+  const delta = size - 21;
+  if (delta < 0 || delta % 4 !== 0) return null;
+  const version = delta / 4 + 1;
+  return Number.isInteger(version) && version >= MIN_GEOMETRY_VERSION && version <= MAX_GEOMETRY_VERSION
+    ? version
+    : null;
+}
+
+export function alignmentPatternCentersForVersion(version) {
+  assertVersion(version);
+  const size = sizeForVersion(version);
+
+  if (version === 1) {
+    const center = size - 4;
+    return [{
+      row: center,
+      col: center,
+      size: 5,
+      primary: true,
+      bootstrap: true,
+      separator: true
+    }];
+  }
+
+  const axes = ALIGNMENT_PATTERN_AXES[version];
+  const last = axes[axes.length - 1];
+  const centers = [];
+
+  for (const row of axes) {
+    for (const col of axes) {
+      // These three locations are occupied by the primary finder patterns.
+      if (
+        (row === 6 && col === 6) ||
+        (row === 6 && col === last) ||
+        (row === last && col === 6)
+      ) {
+        continue;
+      }
+      const primary = row === last && col === last;
+      centers.push({
+        row,
+        col,
+        size: primary ? 5 : 3,
+        primary,
+        bootstrap: false,
+        separator: false
+      });
+    }
+  }
+
+  return centers;
+}
+
+export function primaryAlignmentPatternForVersion(version) {
+  const centers = alignmentPatternCentersForVersion(version);
+  return centers.find((pattern) => pattern.primary) ?? centers[centers.length - 1];
+}
+
+export function alignmentPatternRadius(pattern) {
+  return pattern.size === 3 ? 1 : 2;
+}
+
+export function alignmentPatternIsBlack(pattern, rowOffset, colOffset) {
+  const radius = alignmentPatternRadius(pattern);
+  if (Math.abs(rowOffset) > radius || Math.abs(colOffset) > radius) return null;
+
+  if (pattern.size === 3) {
+    // Compact secondary marker: black 3x3 ring with a white center.
+    return rowOffset !== 0 || colOffset !== 0;
+  }
+
+  // Primary 5x5 marker: black outer ring, white inner ring, black center.
+  const outer = Math.abs(rowOffset) === 2 || Math.abs(colOffset) === 2;
+  const center = rowOffset === 0 && colOffset === 0;
+  return outer || center;
+}