@sythos/js_barcode_universal 1.0.0 → 1.2.5

package/src/aztec/encoder.js

@@ -0,0 +1,257 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Aztec encoder: high-level bits, bit stuffing, Reed-Solomon and matrix layout.
+ *
+ * `tables.js` is intentionally the source of geometry and field selection.
+ * Its `aztecLayer(layers, compact)` entries must expose `totalBits`,
+ * `totalCodewords`, `baseMatrixSize` and `symbolSize`; `fieldForLayers()` must
+ * return the matching binary field.  All Aztec Reed-Solomon generators start
+ * at alpha^1, hence the explicit base `1` in both data and mode messages.
+ *
+ * @module aztec/encoder
+ */
+
+import { BitWriter } from '../core/bit-buffer.js';
+import { BitMatrix } from '../core/bit-matrix.js';
+import { EncodeError } from '../core/errors.js';
+import { rsEncode } from '../core/reed-solomon.js';
+import { encodeHighLevel } from './high-level.js';
+import { AZTEC_COMPACT_LAYERS, AZTEC_FULL_LAYERS, aztecLayer, eccCodewordsFor, fieldForLayers, fieldForWordSize, wordSizeForLayers } from './tables.js';
+
+/** @param {BitWriter} bits @param {number} at @returns {boolean} */
+function bitAt(bits, at) {
+  return at >= 0 && at < bits.length && ((bits.bytes[at >>> 3] >>> (7 - (at & 7))) & 1) !== 0;
+}
+
+/** @param {BitWriter} bits @param {number} from @param {number} count @returns {number} */
+function readBits(bits, from, count) {
+  let value = 0;
+  for (let i = 0; i < count; i++) value = (value << 1) | (bitAt(bits, from + i) ? 1 : 0);
+  return value;
+}
+
+/**
+ * Prevent all-zero and all-one codewords except their final bit.  The final
+ * bit is intentionally re-consumed after a stuffed word; it is the mechanism
+ * that makes the transform injective and reversible.
+ *
+ * @param {BitWriter} bits @param {number} wordSize @returns {BitWriter}
+ */
+export function stuffBits(bits, wordSize) {
+  const out = new BitWriter();
+  const reserved = (1 << wordSize) - 2;
+  for (let at = 0; at < bits.length; at += wordSize) {
+    const word = readBits(bits, at, wordSize);
+    if ((word & reserved) === reserved) {
+      out.put(word & reserved, wordSize);
+      at--;
+    } else if ((word & reserved) === 0) {
+      out.put(word | 1, wordSize);
+      at--;
+    } else {
+      out.put(word, wordSize);
+    }
+  }
+  return out;
+}
+
+/**
+ * Add systematic Aztec Reed-Solomon parity and the leading alignment bits.
+ * @param {BitWriter} data @param {number} totalBits @param {number} wordSize
+ * @param {import('../core/galois-field.js').GaloisField} field
+ * @returns {{bits: BitWriter, dataWords: number, eccWords: number}}
+ */
+export function addCheckWords(data, totalBits, wordSize, field) {
+  const totalWords = Math.floor(totalBits / wordSize);
+  const dataWords = Math.ceil(data.length / wordSize);
+  if (dataWords > totalWords) throw new EncodeError('Aztec: data codewords exceed layer capacity');
+  const eccWords = totalWords - dataWords;
+  const words = new Array(dataWords);
+  for (let i = 0; i < dataWords; i++) words[i] = readBits(data, i * wordSize, wordSize);
+  const ecc = rsEncode(words, eccWords, field, 1);
+  const out = new BitWriter();
+  out.put(0, totalBits % wordSize);
+  for (const word of words) out.put(word, wordSize);
+  for (const word of ecc) out.put(word, wordSize);
+  return { bits: out, dataWords, eccWords };
+}
+
+/** @param {number} layers @param {number} dataWords @param {boolean} compact @returns {BitWriter} */
+export function modeMessage(layers, dataWords, compact) {
+  const raw = new BitWriter();
+  if (compact) {
+    raw.put(layers - 1, 2);
+    raw.put(dataWords - 1, 6);
+    return addCheckWords(raw, 28, 4, fieldForWordSize(4)).bits;
+  }
+  raw.put(layers - 1, 5);
+  raw.put(dataWords - 1, 11);
+  return addCheckWords(raw, 40, 4, fieldForWordSize(4)).bits;
+}
+
+/** @param {BitMatrix} matrix @param {number} center @param {number} size */
+function drawBullsEye(matrix, center, size) {
+  for (let ring = 0; ring < size; ring += 2) {
+    for (let p = center - ring; p <= center + ring; p++) {
+      matrix.set(p, center - ring); matrix.set(p, center + ring);
+      matrix.set(center - ring, p); matrix.set(center + ring, p);
+    }
+  }
+  matrix.set(center - size, center - size);
+  matrix.set(center - size + 1, center - size);
+  matrix.set(center - size, center - size + 1);
+  matrix.set(center + size, center - size);
+  matrix.set(center + size, center - size + 1);
+  matrix.set(center + size, center + size - 1);
+}
+
+/** @param {BitMatrix} matrix @param {BitWriter} message @param {boolean} compact @param {number} center */
+function drawModeMessage(matrix, message, compact, center) {
+  if (compact) {
+    for (let i = 0; i < 7; i++) {
+      const offset = center - 3 + i;
+      if (bitAt(message, i)) matrix.set(offset, center - 5);
+      if (bitAt(message, i + 7)) matrix.set(center + 5, offset);
+      if (bitAt(message, 20 - i)) matrix.set(offset, center + 5);
+      if (bitAt(message, 27 - i)) matrix.set(center - 5, offset);
+    }
+  } else {
+    for (let i = 0; i < 10; i++) {
+      const offset = center - 5 + i + Math.floor(i / 5);
+      if (bitAt(message, i)) matrix.set(offset, center - 7);
+      if (bitAt(message, i + 10)) matrix.set(center + 7, offset);
+      if (bitAt(message, 29 - i)) matrix.set(offset, center + 7);
+      if (bitAt(message, 39 - i)) matrix.set(center - 7, offset);
+    }
+  }
+}
+
+/**
+ * Lay low-level bits in the four-sided, inward Aztec spiral.
+ * @param {BitWriter} bits @param {{layers:number,compact:boolean,baseMatrixSize:number,symbolSize:number}} symbol
+ * @returns {BitMatrix}
+ */
+export function buildAztecMatrix(bits, symbol) {
+  const { layers, compact, baseMatrixSize, symbolSize } = symbol;
+  const matrix = new BitMatrix(symbolSize);
+  const alignment = new Int32Array(baseMatrixSize);
+  const center = Math.floor(symbolSize / 2);
+
+  if (compact) {
+    for (let i = 0; i < baseMatrixSize; i++) alignment[i] = i;
+  } else {
+    const originalCenter = Math.floor(baseMatrixSize / 2);
+    for (let i = 0; i < originalCenter; i++) {
+      const offset = i + Math.floor(i / 15);
+      alignment[originalCenter - i - 1] = center - offset - 1;
+      alignment[originalCenter + i] = center + offset + 1;
+    }
+  }
+
+  let bit = 0;
+  for (let layer = 0; layer < layers; layer++) {
+    const rowSize = (layers - layer) * 4 + (compact ? 9 : 12);
+    const low = layer * 2;
+    const high = baseMatrixSize - 1 - low;
+    for (let j = 0; j < rowSize; j++) {
+      const offset = j * 2;
+      for (let k = 0; k < 2; k++) {
+        if (bitAt(bits, bit + offset + k)) matrix.set(alignment[low + k], alignment[low + j]);
+        if (bitAt(bits, bit + rowSize * 2 + offset + k)) matrix.set(alignment[low + j], alignment[high - k]);
+        if (bitAt(bits, bit + rowSize * 4 + offset + k)) matrix.set(alignment[high - k], alignment[high - j]);
+        if (bitAt(bits, bit + rowSize * 6 + offset + k)) matrix.set(alignment[high - j], alignment[low + k]);
+      }
+    }
+    bit += rowSize * 8;
+  }
+  if (bit !== bits.length) throw new EncodeError(`Aztec: layout consumed ${bit} of ${bits.length} bits`);
+
+  const mode = modeMessage(layers, symbol.dataWords, compact);
+  drawModeMessage(matrix, mode, compact, center);
+  drawBullsEye(matrix, center, compact ? 5 : 7);
+
+  if (!compact) {
+    for (let i = 0, offset = 0; i < Math.floor(baseMatrixSize / 2) - 1; i += 15, offset += 16) {
+      for (let p = center & 1; p < symbolSize; p += 2) {
+        matrix.set(center - offset, p); matrix.set(center + offset, p);
+        matrix.set(p, center - offset); matrix.set(p, center + offset);
+      }
+    }
+  }
+  return matrix;
+}
+
+/** @param {number | undefined} layers @param {boolean | undefined} compact */
+function candidates(layers, compact) {
+  if (layers !== undefined) {
+    if (!Number.isInteger(layers) || layers < 1 || layers > 32) throw new EncodeError('Aztec: layers must be an integer 1..32');
+    if (compact === true && layers > 4) throw new EncodeError('Aztec: compact symbols support layers 1..4');
+    return [aztecLayer(layers, compact === true)];
+  }
+  if (compact === true) return AZTEC_COMPACT_LAYERS;
+  if (compact === false) return AZTEC_FULL_LAYERS;
+  return [...AZTEC_COMPACT_LAYERS, ...AZTEC_FULL_LAYERS];
+}
+
+/**
+ * Encode a UTF-8 string or bytes into an Aztec Code matrix.
+ *
+ * @param {string|ArrayBuffer|ArrayBufferView} value
+ * @param {{layers?:number,compact?:boolean,eccPercent?:number,charset?:'utf-8'}} [options]
+ * @returns {BitMatrix & {format?:string,layers?:number,compact?:boolean,eccPercent?:number,dataCodewords?:number}}
+ */
+export function encodeAztec(value, options = {}) {
+  const eccPercent = options.eccPercent ?? 23;
+  if (!Number.isFinite(eccPercent) || eccPercent < 5 || eccPercent > 95) {
+    throw new EncodeError('Aztec: eccPercent must be between 5 and 95');
+  }
+  const high = encodeHighLevel(value, { charset: options.charset ?? 'utf-8' });
+  for (const candidate of candidates(options.layers, options.compact)) {
+    if (!candidate) continue;
+    const wordSize = wordSizeForLayers(candidate.layers);
+    const stuffed = stuffBits(high, wordSize);
+    const dataWords = Math.ceil(stuffed.length / wordSize);
+    const eccWords = eccCodewordsFor(dataWords, eccPercent);
+    if (dataWords > candidate.maxDataCodewords || dataWords + eccWords > candidate.totalCodewords) continue;
+    const checked = addCheckWords(stuffed, candidate.totalBits, wordSize, fieldForLayers(candidate.layers));
+    // `addCheckWords` uses every remaining word as parity.  This is stronger
+    // than the requested percentage, never weaker, and canonical for a chosen
+    // layer/data-word combination.
+    const symbol = { ...candidate, dataWords: checked.dataWords };
+    const matrix = buildAztecMatrix(checked.bits, symbol);
+    matrix.format = 'aztec'; matrix.layers = candidate.layers; matrix.compact = candidate.compact;
+    matrix.eccPercent = Math.round(checked.eccWords * wordSize * 100 / Math.max(1, stuffed.length));
+    matrix.dataCodewords = checked.dataWords;
+    return matrix;
+  }
+  throw new EncodeError('Aztec: payload does not fit the requested layers and error correction');
+}

package/src/aztec/high-level.js

@@ -0,0 +1,211 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Aztec high-level stream writer.
+ *
+ * The output is deliberately a `BitWriter`, rather than a byte array: Aztec's
+ * text controls and binary-shift lengths are not byte aligned.  This module is
+ * also the boundary where JavaScript strings become UTF-8.  Passing a byte
+ * view bypasses that conversion and preserves every octet unchanged.
+ *
+ * The initial state mandated by the symbology is UPPER.  The greedy text pass
+ * uses UPPER, LOWER, DIGIT and PUNCT tables, selecting the shortest available
+ * latch at each byte.  Bytes without a text-table representation are emitted
+ * through the standard B/S (binary shift) escape.  B/S is available from
+ * UPPER and makes this a complete, lossless representation of UTF-8 payloads.
+ *
+ * @module aztec/high-level
+ */
+
+import { BitWriter } from '../core/bit-buffer.js';
+import { EncodeError } from '../core/errors.js';
+
+/** Aztec high-level table identifiers, exposed for decoder/API symmetry. */
+export const HIGH_LEVEL_MODE = Object.freeze({
+  UPPER: 0,
+  LOWER: 1,
+  DIGIT: 2,
+  MIXED: 3,
+  PUNCT: 4,
+});
+
+/** Maximum number of bytes represented by one B/S escape. */
+export const MAX_BINARY_SHIFT = 2078;
+
+/**
+ * Convert accepted public input to its encoded octets.
+ *
+ * @param {string|ArrayBuffer|ArrayBufferView} value
+ * @param {'utf-8'} [charset]
+ * @returns {Uint8Array}
+ */
+export function aztecBytes(value, charset = 'utf-8') {
+  if (charset !== 'utf-8') throw new EncodeError(`Aztec: unsupported charset "${charset}"`);
+  if (typeof value === 'string') return new TextEncoder().encode(value);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  throw new EncodeError('Aztec: value must be a string, ArrayBuffer, or byte view');
+}
+
+/** @param {number} byte @returns {number} UPPER-table value, or -1. */
+function upperValue(byte) {
+  if (byte === 0x20) return 1;
+  if (byte >= 0x41 && byte <= 0x5a) return byte - 0x41 + 2;
+  return -1;
+}
+
+/** Aztec's latch table, packed as `(bitCount << 16) | bits`. */
+const LATCH = Object.freeze([
+  [0, 327708, 327710, 327709, 656318],
+  [590318, 0, 327710, 327709, 656318],
+  [262158, 590300, 0, 590301, 932798],
+  [327709, 327708, 656322, 0, 327710],
+  [327711, 656380, 656382, 656381, 0],
+]);
+
+/** @param {number} byte @returns {number} */
+function lowerValue(byte) {
+  if (byte === 0x20) return 1;
+  if (byte >= 0x61 && byte <= 0x7a) return byte - 0x61 + 2;
+  return -1;
+}
+
+/** @param {number} byte @returns {number} */
+function digitValue(byte) {
+  if (byte === 0x20) return 1;
+  if (byte >= 0x30 && byte <= 0x39) return byte - 0x30 + 2;
+  if (byte === 0x2c) return 12;
+  if (byte === 0x2e) return 13;
+  return -1;
+}
+
+const PUNCT = new Map([
+  [0x0d, 1], [0x21, 6], [0x22, 7], [0x23, 8], [0x24, 9], [0x25, 10],
+  [0x26, 11], [0x27, 12], [0x28, 13], [0x29, 14], [0x2a, 15], [0x2b, 16],
+  [0x2c, 17], [0x2d, 18], [0x2e, 19], [0x2f, 20], [0x3a, 21], [0x3b, 22],
+  [0x3c, 23], [0x3d, 24], [0x3e, 25], [0x3f, 26], [0x5b, 27], [0x5d, 28],
+  [0x7b, 29], [0x7d, 30],
+]);
+
+/** @param {number} byte @param {number} mode @returns {number} */
+function textValue(byte, mode) {
+  switch (mode) {
+    case HIGH_LEVEL_MODE.UPPER: return upperValue(byte);
+    case HIGH_LEVEL_MODE.LOWER: return lowerValue(byte);
+    case HIGH_LEVEL_MODE.DIGIT: return digitValue(byte);
+    case HIGH_LEVEL_MODE.PUNCT: return PUNCT.get(byte) ?? -1;
+    default: return -1;
+  }
+}
+
+/** @param {BitWriter} writer @param {number} from @param {number} to */
+function latch(writer, from, to) {
+  if (from === to) return;
+  const packed = LATCH[from][to];
+  writer.put(packed & 0xffff, packed >>> 16);
+}
+
+/** @param {number} mode @returns {number} */
+function characterWidth(mode) {
+  return mode === HIGH_LEVEL_MODE.DIGIT ? 4 : 5;
+}
+
+/**
+ * Write an Aztec binary-shift segment while in UPPER mode.
+ *
+ * B/S is `11111`; its five-bit length directly covers 1..31 bytes.  A zero
+ * length selects the extended eleven-bit form, whose stored value is n - 31.
+ * Splitting at 2078 keeps each control representable and makes arbitrarily
+ * long byte input well-defined.
+ *
+ * @param {BitWriter} writer
+ * @param {Uint8Array} bytes
+ * @param {number} start
+ * @param {number} length
+ */
+export function writeBinaryShift(writer, bytes, start, length) {
+  let at = start;
+  let left = length;
+  while (left > 0) {
+    const count = Math.min(left, MAX_BINARY_SHIFT);
+    writer.put(31, 5); // UPPER B/S
+    if (count <= 31) writer.put(count, 5);
+    else {
+      writer.put(0, 5);
+      writer.put(count - 31, 11);
+    }
+    for (let i = 0; i < count; i++) writer.put(bytes[at + i], 8);
+    at += count;
+    left -= count;
+  }
+}
+
+/**
+ * Build a valid Aztec high-level bitstream.
+ *
+ * @param {string|ArrayBuffer|ArrayBufferView} value
+ * @param {{charset?: 'utf-8'}} [options]
+ * @returns {BitWriter}
+ */
+export function encodeHighLevel(value, options = {}) {
+  const bytes = aztecBytes(value, options.charset ?? 'utf-8');
+  const writer = new BitWriter();
+  let mode = HIGH_LEVEL_MODE.UPPER;
+
+  for (let at = 0; at < bytes.length;) {
+    let bestMode = -1;
+    let bestValue = -1;
+    let bestCost = Number.POSITIVE_INFINITY;
+    for (const candidate of [HIGH_LEVEL_MODE.UPPER, HIGH_LEVEL_MODE.LOWER, HIGH_LEVEL_MODE.DIGIT, HIGH_LEVEL_MODE.PUNCT]) {
+      const value = textValue(bytes[at], candidate);
+      if (value < 0) continue;
+      const latchCost = candidate === mode ? 0 : LATCH[mode][candidate] >>> 16;
+      const cost = latchCost + characterWidth(candidate);
+      if (cost < bestCost) { bestCost = cost; bestMode = candidate; bestValue = value; }
+    }
+    if (bestMode >= 0) {
+      latch(writer, mode, bestMode);
+      writer.put(bestValue, characterWidth(bestMode));
+      mode = bestMode;
+      at++;
+    } else {
+      // B/S is defined from UPPER; the latch is retained after the shift.
+      latch(writer, mode, HIGH_LEVEL_MODE.UPPER);
+      mode = HIGH_LEVEL_MODE.UPPER;
+      const start = at;
+      while (at < bytes.length && ![HIGH_LEVEL_MODE.UPPER, HIGH_LEVEL_MODE.LOWER, HIGH_LEVEL_MODE.DIGIT, HIGH_LEVEL_MODE.PUNCT].some((m) => textValue(bytes[at], m) >= 0)) at++;
+      writeBinaryShift(writer, bytes, start, at - start);
+    }
+  }
+  return writer;
+}

package/src/aztec/index.js

@@ -0,0 +1,45 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/** Aztec Code entry points. @module aztec */
+
+export { encodeAztec } from './encoder.js';
+export { decodeAztec } from './decoder.js';
+export { detectAztec, detectAndDecodeAztec } from './detector.js';
+export {
+  AZTEC_COMPACT_LAYERS,
+  AZTEC_FULL_LAYERS,
+  AZTEC_LAYERS,
+  AZTEC_DEFAULT_ECC_PERCENT,
+  AZTEC_RS_GENERATOR_BASE,
+  aztecLayer,
+  aztecSymbolSize,
+  validateAztecTables,
+} from './tables.js';