specqr 1.0.0-rc.1

package/src/core/tables.js

@@ -0,0 +1,112 @@
+export const ERROR_CORRECTION_LEVELS = {
+  L: { key: "L", ordinal: 0, formatBits: 0b01 },
+  M: { key: "M", ordinal: 1, formatBits: 0b00 },
+  Q: { key: "Q", ordinal: 2, formatBits: 0b11 },
+  H: { key: "H", ordinal: 3, formatBits: 0b10 }
+};
+
+export const ERROR_CORRECTION_LEVEL_ORDER = ["L", "M", "Q", "H"];
+
+export const ECC_CODEWORDS_PER_BLOCK = [
+  [-1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
+  [-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28],
+  [-1, 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],
+  [-1, 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]
+];
+
+export const NUM_ERROR_CORRECTION_BLOCKS = [
+  [-1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25],
+  [-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49],
+  [-1, 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],
+  [-1, 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]
+];
+
+export function getSize(version) {
+  assertVersion(version);
+  return version * 4 + 17;
+}
+
+export function getRawCodewordCount(version) {
+  assertVersion(version);
+
+  let result = (16 * version + 128) * version + 64;
+  if (version >= 2) {
+    const numAlign = Math.floor(version / 7) + 2;
+    result -= (25 * numAlign - 10) * numAlign - 55;
+    if (version >= 7) {
+      result -= 36;
+    }
+  }
+
+  return Math.floor(result / 8);
+}
+
+export function getDataCodewordCount(version, level) {
+  assertVersion(version);
+  const ecl = ERROR_CORRECTION_LEVELS[level];
+  if (!ecl) {
+    throw new RangeError(`Unsupported error correction level: ${level}`);
+  }
+
+  const raw = getRawCodewordCount(version);
+  const blocks = NUM_ERROR_CORRECTION_BLOCKS[ecl.ordinal][version];
+  const eccPerBlock = ECC_CODEWORDS_PER_BLOCK[ecl.ordinal][version];
+  return raw - blocks * eccPerBlock;
+}
+
+export function getErrorCorrectionBlockInfo(version, level) {
+  assertVersion(version);
+  const ecl = ERROR_CORRECTION_LEVELS[level];
+  if (!ecl) {
+    throw new RangeError(`Unsupported error correction level: ${level}`);
+  }
+
+  return {
+    blocks: NUM_ERROR_CORRECTION_BLOCKS[ecl.ordinal][version],
+    eccPerBlock: ECC_CODEWORDS_PER_BLOCK[ecl.ordinal][version],
+    rawCodewords: getRawCodewordCount(version),
+    dataCodewords: getDataCodewordCount(version, level)
+  };
+}
+
+export function getAlignmentPatternPositions(version) {
+  assertVersion(version);
+  if (version === 1) {
+    return [];
+  }
+
+  const size = getSize(version);
+  const numAlign = Math.floor(version / 7) + 2;
+  const step = version === 32
+    ? 26
+    : Math.ceil((version * 4 + 4) / (numAlign * 2 - 2)) * 2;
+
+  const positions = [6];
+  for (let pos = size - 7; positions.length < numAlign; pos -= step) {
+    positions.splice(1, 0, pos);
+  }
+  return positions;
+}
+
+export function getCharacterCountBitLength(version, mode) {
+  assertVersion(version);
+
+  switch (mode) {
+    case "numeric":
+      return version <= 9 ? 10 : version <= 26 ? 12 : 14;
+    case "alphanumeric":
+      return version <= 9 ? 9 : version <= 26 ? 11 : 13;
+    case "byte":
+      return version <= 9 ? 8 : 16;
+    case "kanji":
+      return version <= 9 ? 8 : version <= 26 ? 10 : 12;
+    default:
+      throw new RangeError(`Unsupported mode: ${mode}`);
+  }
+}
+
+function assertVersion(version) {
+  if (!Number.isInteger(version) || version < 1 || version > 40) {
+    throw new RangeError(`QR version must be an integer from 1 to 40; got ${version}`);
+  }
+}

package/src/diagnostics.js

@@ -0,0 +1,208 @@
+import { parseRgbaColor, getContrastRatio } from "./render/color.js";
+
+const MIN_RECOMMENDED_CONTRAST = 4.5;
+const STRONG_RECOMMENDED_CONTRAST = 7;
+const MIN_PRINT_MODULE_MM = 0.25;
+
+export function createDiagnostics({
+  plan,
+  built,
+  options,
+  inputBytes,
+  capacityBits,
+  interleaved,
+  getSize,
+  getDiagnosticMode,
+  getFirstEciAssignmentNumber,
+  getFirstFnc1Mode,
+  getSegmentDiagnostics
+}) {
+  const remainingBits = capacityBits - plan.dataBitLength;
+  const contrast = getColorContrast(options);
+  const print = getPrintDiagnostics(plan, options);
+  const warnings = createWarnings({
+    options,
+    remainingBits,
+    capacityBits,
+    contrast,
+    print
+  });
+
+  return {
+    version: plan.version,
+    size: getSize(plan.version),
+    errorCorrectionLevel: plan.errorCorrectionLevel,
+    requestedErrorCorrectionLevel: plan.requestedErrorCorrectionLevel,
+    boostedErrorCorrection: plan.boostedErrorCorrection,
+    versionSelection: plan.versionSelection,
+    versionSelectionReason: getVersionSelectionReason(plan, options),
+    maskPattern: built.maskPattern,
+    maskPenalty: built.penalty,
+    maskPenalties: built.maskPenalties,
+    maskSelectionReason: getMaskSelectionReason(built, options),
+    mode: getDiagnosticMode(plan.segments),
+    eciAssignmentNumber: getFirstEciAssignmentNumber(plan.segments),
+    fnc1: getFirstFnc1Mode(plan.segments),
+    gs1: getFirstFnc1Mode(plan.segments) === "first-position",
+    segments: plan.segments.map(getSegmentDiagnostics),
+    dataBitLength: plan.dataBitLength,
+    capacityBits,
+    remainingBits,
+    capacityUtilization: plan.dataBitLength / capacityBits,
+    inputBytes,
+    dataCodewords: interleaved.dataCodewords,
+    errorCorrectionCodewords: interleaved.errorCorrectionCodewords,
+    totalCodewords: interleaved.totalCodewords,
+    quietZone: {
+      modules: options.margin,
+      recommendedModules: 4,
+      isSufficient: options.margin >= 4
+    },
+    colors: contrast,
+    print,
+    warnings
+  };
+}
+
+function getVersionSelectionReason(plan, options) {
+  if (plan.versionSelection === "fixed") {
+    return `Version ${plan.version} was requested explicitly.`;
+  }
+  return `Version ${plan.version} is the smallest version in ${options.minVersion}..${options.maxVersion} that fits the encoded data at error correction ${options.errorCorrectionLevel}.`;
+}
+
+function getMaskSelectionReason(built, options) {
+  if (options.maskPattern !== "auto") {
+    return `Mask pattern ${built.maskPattern} was requested explicitly.`;
+  }
+  return `Mask pattern ${built.maskPattern} had the lowest penalty score (${built.penalty}) among the evaluated masks.`;
+}
+
+function getColorContrast(options) {
+  const foreground = parseRgbaColor(options.foreground);
+  const background = parseRgbaColor(options.background);
+  if (!foreground || !background) {
+    return {
+      ratio: null,
+      foregroundAlpha: null,
+      backgroundAlpha: null,
+      isInspectable: false,
+      isStrong: false,
+      isSufficient: false
+    };
+  }
+
+  const ratio = getContrastRatio(foreground, background);
+  return {
+    ratio,
+    foregroundAlpha: foreground[3],
+    backgroundAlpha: background[3],
+    isInspectable: true,
+    isStrong: ratio >= STRONG_RECOMMENDED_CONTRAST,
+    isSufficient: ratio >= MIN_RECOMMENDED_CONTRAST && foreground[3] === 255 && background[3] === 255
+  };
+}
+
+function getPrintDiagnostics(plan, options) {
+  const moduleSizeMm = options.printDpi === null ? null : (options.scale / options.printDpi) * 25.4;
+  return {
+    dpi: options.printDpi,
+    modulePixels: options.scale,
+    moduleSizeMm,
+    symbolSizeMm: moduleSizeMm === null ? null : (plan.version * 4 + 17 + options.margin * 2) * moduleSizeMm,
+    recommendedMinimumModuleSizeMm: MIN_PRINT_MODULE_MM,
+    isModuleSizeSufficient: moduleSizeMm === null ? null : moduleSizeMm >= MIN_PRINT_MODULE_MM
+  };
+}
+
+function createWarnings({ options, remainingBits, capacityBits, contrast, print }) {
+  const warnings = [];
+
+  if (options.margin < 4) {
+    warnings.push({
+      code: "QUIET_ZONE_TOO_SMALL",
+      severity: "warning",
+      message: "QR Code Model 2 readers expect a quiet zone of at least 4 modules.",
+      details: { margin: options.margin, recommendedModules: 4 }
+    });
+  }
+
+  if (!contrast.isInspectable) {
+    warnings.push({
+      code: "COLOR_CONTRAST_UNKNOWN",
+      severity: "info",
+      message: "Color contrast could not be inspected because one or both colors are not simple hex/named colors.",
+      details: { foreground: options.foreground, background: options.background }
+    });
+  } else if (contrast.ratio < MIN_RECOMMENDED_CONTRAST) {
+    warnings.push({
+      code: "COLOR_CONTRAST_LOW",
+      severity: "warning",
+      message: "Foreground and background contrast is low for reliable scanning.",
+      details: { ratio: contrast.ratio, recommendedMinimumRatio: MIN_RECOMMENDED_CONTRAST }
+    });
+  } else if (contrast.ratio < STRONG_RECOMMENDED_CONTRAST) {
+    warnings.push({
+      code: "COLOR_CONTRAST_MODERATE",
+      severity: "info",
+      message: "Contrast is acceptable, but stronger contrast is recommended for damaged, small, or printed QR codes.",
+      details: { ratio: contrast.ratio, strongRecommendedRatio: STRONG_RECOMMENDED_CONTRAST }
+    });
+  }
+
+  if (contrast.isInspectable && (contrast.foregroundAlpha < 255 || contrast.backgroundAlpha < 255)) {
+    warnings.push({
+      code: "COLOR_ALPHA_USED",
+      severity: "warning",
+      message: "Transparent foreground or background colors can reduce scanner reliability.",
+      details: {
+        foregroundAlpha: contrast.foregroundAlpha,
+        backgroundAlpha: contrast.backgroundAlpha
+      }
+    });
+  }
+
+  if (remainingBits / capacityBits < 0.05) {
+    warnings.push({
+      code: "CAPACITY_NEAR_LIMIT",
+      severity: "info",
+      message: "The selected version is close to full capacity.",
+      details: { remainingBits, capacityBits }
+    });
+  }
+
+  if (print.dpi !== null && print.isModuleSizeSufficient === false) {
+    warnings.push({
+      code: "PRINT_MODULE_TOO_SMALL",
+      severity: "warning",
+      message: "The configured scale and DPI produce modules smaller than the print recommendation.",
+      details: {
+        dpi: print.dpi,
+        moduleSizeMm: print.moduleSizeMm,
+        recommendedMinimumModuleSizeMm: print.recommendedMinimumModuleSizeMm
+      }
+    });
+  }
+
+  if (["png", "png-data-url"].includes(options.output) && options.scale < 3) {
+    warnings.push({
+      code: "RASTER_SCALE_SMALL",
+      severity: "info",
+      message: "Raster output with fewer than 3 pixels per module may scan poorly after resizing.",
+      details: { scale: options.scale, recommendedMinimumScale: 3 }
+    });
+  }
+
+  if (warnings.some((warning) => warning.severity === "warning")) {
+    warnings.push({
+      code: "SCAN_RISK",
+      severity: "warning",
+      message: "One or more settings may reduce scan reliability.",
+      details: {
+        blockingWarnings: warnings.filter((warning) => warning.severity === "warning").map((warning) => warning.code)
+      }
+    });
+  }
+
+  return warnings;
+}

package/src/encoding/bit-buffer.js

@@ -0,0 +1,54 @@
+export class BitBuffer {
+  #bits = [];
+
+  get length() {
+    return this.#bits.length;
+  }
+
+  append(value, bitLength) {
+    if (!Number.isInteger(bitLength) || bitLength < 0 || bitLength > 31) {
+      throw new RangeError(`Bit length must be from 0 to 31; got ${bitLength}`);
+    }
+    if (!Number.isInteger(value) || value < 0 || value >>> bitLength !== 0) {
+      throw new RangeError(`Value ${value} does not fit in ${bitLength} bits`);
+    }
+
+    for (let i = bitLength - 1; i >= 0; i -= 1) {
+      this.#bits.push(((value >>> i) & 1) !== 0);
+    }
+  }
+
+  appendBits(bits) {
+    for (const bit of bits) {
+      this.#bits.push(Boolean(bit));
+    }
+  }
+
+  getBit(index) {
+    if (!Number.isInteger(index) || index < 0 || index >= this.#bits.length) {
+      throw new RangeError(`Bit index out of range: ${index}`);
+    }
+    return this.#bits[index];
+  }
+
+  toBytes(targetLength) {
+    if (this.#bits.length % 8 !== 0) {
+      throw new Error("Bit length must be a multiple of 8 before converting to bytes");
+    }
+
+    const bytes = [];
+    for (let i = 0; i < this.#bits.length; i += 8) {
+      let value = 0;
+      for (let j = 0; j < 8; j += 1) {
+        value = (value << 1) | (this.#bits[i + j] ? 1 : 0);
+      }
+      bytes.push(value);
+    }
+
+    if (targetLength !== undefined && bytes.length !== targetLength) {
+      throw new Error(`Expected ${targetLength} bytes; got ${bytes.length}`);
+    }
+
+    return bytes;
+  }
+}