@sythos/js_barcode_universal 1.5.8 → 1.5.9

package/src/ts/aztecrune/encoder.ts

@@ -0,0 +1,121 @@
+/*!
+ * 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 Rune encoder.
+ *
+ * A Rune carries exactly one byte. Numeric strings are accepted for convenient
+ * human-readable input and are normalized to the canonical three-digit text;
+ * binary callers can pass one byte in an ArrayBuffer or typed-array view.
+ *
+ * @module aztecrune/encoder
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { EncodeError } from '../core/errors.js';
+import { rsEncode } from '../core/reed-solomon.js';
+import {
+  AZTEC_RUNE_DATA_POSITIONS,
+  AZTEC_RUNE_ECC_CODEWORDS,
+  AZTEC_RUNE_MASK,
+  AZTEC_RUNE_SIZE,
+  aztecRuneField,
+  buildAztecRuneStructure,
+} from './tables.js';
+
+/** @param {unknown} value @returns {number} */
+export function normalizeAztecRuneValue(value) {
+  if (typeof value === 'number') {
+    if (Number.isInteger(value) && value >= 0 && value <= 255) return value;
+    throw new EncodeError('Aztec Rune: numeric value must be an integer from 0 to 255');
+  }
+
+  if (typeof value === 'string') {
+    if (!/^\d{1,3}$/.test(value)) throw new EncodeError('Aztec Rune: text input must contain one to three decimal digits');
+    const numeric = Number(value);
+    if (numeric > 255) throw new EncodeError('Aztec Rune: decimal value must be from 000 to 255');
+    return numeric;
+  }
+
+  let bytes = null;
+  if (value instanceof ArrayBuffer) bytes = new Uint8Array(value);
+  else if (ArrayBuffer.isView(value)) bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (bytes) {
+    if (bytes.length !== 1) throw new EncodeError('Aztec Rune: binary input must contain exactly one byte');
+    return bytes[0];
+  }
+  throw new EncodeError('Aztec Rune: expected a number, decimal string or one-byte binary value');
+}
+
+/** @param {number} value @returns {number[]} */
+function codewordsForValue(value) {
+  const data = [value >>> 4, value & 0x0f];
+  const parity = rsEncode(data, AZTEC_RUNE_ECC_CODEWORDS, aztecRuneField(), 1);
+  return data.concat(parity).map((word) => word ^ AZTEC_RUNE_MASK);
+}
+
+/** @param {BitMatrix} matrix @param {number[]} codewords */
+function writeDataRing(matrix, codewords) {
+  for (let word = 0; word < codewords.length; word++) {
+    for (let bit = 0; bit < 4; bit++) {
+      const at = word * 4 + bit;
+      const [x, y] = AZTEC_RUNE_DATA_POSITIONS[at];
+      matrix.setValue(x, y, ((codewords[word] >>> (3 - bit)) & 1) !== 0);
+    }
+  }
+}
+
+/**
+ * Encode one byte as an Aztec Rune.
+ *
+ * @param {number|string|ArrayBuffer|ArrayBufferView} value
+ * @param {{inverted?: boolean}} [options]
+ * @returns {import('../core/bit-matrix.js').BitMatrix & {
+ *   format: 'aztecrune', value: number, inverted: boolean
+ * }}
+ */
+export function encodeAztecRune(value, options = {}) {
+  const numeric = normalizeAztecRuneValue(value);
+  if (options.inverted !== undefined && typeof options.inverted !== 'boolean') {
+    throw new EncodeError('Aztec Rune: inverted must be boolean');
+  }
+  const inverted = options.inverted === true;
+  const matrix = buildAztecRuneStructure();
+  writeDataRing(matrix, codewordsForValue(numeric));
+  if (inverted) {
+    for (let y = 0; y < AZTEC_RUNE_SIZE; y++) for (let x = 0; x < AZTEC_RUNE_SIZE; x++) matrix.flip(x, y);
+  }
+  matrix.format = 'aztecrune';
+  matrix.value = numeric;
+  matrix.inverted = inverted;
+  return matrix;
+}
+
+export { codewordsForValue };

package/src/ts/aztecrune/index.ts

@@ -0,0 +1,49 @@
+/*!
+ * 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 Rune entry points. @module aztecrune */
+
+export { encodeAztecRune, normalizeAztecRuneValue } from './encoder.js';
+export { decodeAztecRune } from './decoder.js';
+export { detectAztecRune, detectAndDecodeAztecRune } from './detector.js';
+export {
+  AZTEC_RUNE_SIZE,
+  AZTEC_RUNE_DATA_BITS,
+  AZTEC_RUNE_WORD_SIZE,
+  AZTEC_RUNE_DATA_CODEWORDS,
+  AZTEC_RUNE_ECC_CODEWORDS,
+  AZTEC_RUNE_TOTAL_CODEWORDS,
+  AZTEC_RUNE_MASK,
+  AZTEC_RUNE_DATA_POSITIONS,
+  aztecRuneStructuralValue,
+  buildAztecRuneStructure,
+  aztecRuneField,
+  validateAztecRuneTables,
+} from './tables.js';

package/src/ts/aztecrune/tables.ts

@@ -0,0 +1,137 @@
+/*!
+ * 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 Rune geometry.
+ *
+ * Aztec Rune is the 11x11, one-byte member of the Aztec family. Two 4-bit
+ * data words and five 4-bit Reed-Solomon check words are XORed with the fixed
+ * Aztec Rune mask and written clockwise on the outer data ring. The finder and
+ * corner orientation marks are independent of the value.
+ *
+ * The constants below are derived from the public Aztec Code specification and
+ * are kept separate from the general Aztec implementation so a normal Aztec
+ * decoder can never accidentally treat an 11x11 Rune as a regular symbol.
+ *
+ * @module aztecrune/tables
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { fieldForWordSize } from '../aztec/tables.js';
+
+export const AZTEC_RUNE_SIZE = 11;
+export const AZTEC_RUNE_DATA_BITS = 8;
+export const AZTEC_RUNE_WORD_SIZE = 4;
+export const AZTEC_RUNE_DATA_CODEWORDS = 2;
+export const AZTEC_RUNE_ECC_CODEWORDS = 5;
+export const AZTEC_RUNE_TOTAL_CODEWORDS = AZTEC_RUNE_DATA_CODEWORDS + AZTEC_RUNE_ECC_CODEWORDS;
+export const AZTEC_RUNE_MASK = 0b1010;
+
+/**
+ * Data-module coordinates in wire order: clockwise, starting at the top.
+ * Every side contributes seven modules, for 28 bits in total.
+ */
+export const AZTEC_RUNE_DATA_POSITIONS = Object.freeze([
+  ...Array.from({ length: 7 }, (_, i) => [i + 2, 0]),
+  ...Array.from({ length: 7 }, (_, i) => [10, i + 2]),
+  ...Array.from({ length: 7 }, (_, i) => [8 - i, 10]),
+  ...Array.from({ length: 7 }, (_, i) => [0, 8 - i]),
+].map(([x, y]) => Object.freeze([x, y])));
+
+const DATA_KEYS = new Set(AZTEC_RUNE_DATA_POSITIONS.map(([x, y]) => `${x},${y}`));
+
+/** @param {number} x @param {number} y @returns {boolean} */
+export function isAztecRuneDataPosition(x, y) {
+  return DATA_KEYS.has(`${x},${y}`);
+}
+/**
+ * Return the value of a structural module. Data positions return `null`.
+ * The bull's-eye has five square rings including its one-module centre; its
+ * even-radius rings are dark. The four corner groups are the orientation marks
+ * described by the Aztec Rune specification.
+ *
+ * @param {number} x @param {number} y
+ * @returns {boolean|null}
+ */
+export function aztecRuneStructuralValue(x, y) {
+  if (!Number.isInteger(x) || !Number.isInteger(y) || x < 0 || y < 0 || x >= AZTEC_RUNE_SIZE || y >= AZTEC_RUNE_SIZE) {
+    return null;
+  }
+  if (isAztecRuneDataPosition(x, y)) return null;
+
+  const distance = Math.max(Math.abs(x - 5), Math.abs(y - 5));
+  if (distance <= 4) return (distance & 1) === 0;
+
+  // Corner orientation groups, clockwise from the upper-left corner:
+  // three dark, white-dark-dark, dark-white-white, three white.
+  if ((x === 0 && y <= 1) || (y === 0 && x <= 1)) return true;
+  if ((x === 10 && y <= 1) || (y === 0 && x === 10)) return true;
+  if (x === 9 && y === 0) return false;
+  if (x === 10 && y === 10) return false;
+  if (y === 10 && x >= 0 && x <= 1) return false;
+  if (x === 0 && y >= 9) return false;
+  if (x === 10 && y === 9) return true;
+
+  // All non-data cells are covered by the bull's-eye or the four corners.
+  return false;
+}
+
+/** Build only the fixed finder/orientation structure. */
+export function buildAztecRuneStructure() {
+  const matrix = new BitMatrix(AZTEC_RUNE_SIZE);
+  for (let y = 0; y < AZTEC_RUNE_SIZE; y++) {
+    for (let x = 0; x < AZTEC_RUNE_SIZE; x++) {
+      const value = aztecRuneStructuralValue(x, y);
+      if (value === true) matrix.set(x, y);
+    }
+  }
+  return matrix;
+}
+
+/** Return the field used by Rune data/check words. */
+export function aztecRuneField() {
+  return fieldForWordSize(AZTEC_RUNE_WORD_SIZE);
+}
+
+/** Validate the fixed Rune contract and coordinate layout. */
+export function validateAztecRuneTables() {
+  const problems = [];
+  if (AZTEC_RUNE_SIZE !== 11) problems.push('Rune symbol size must be 11');
+  if (AZTEC_RUNE_TOTAL_CODEWORDS * AZTEC_RUNE_WORD_SIZE !== 28) problems.push('Rune outer ring must carry 28 bits');
+  if (AZTEC_RUNE_DATA_POSITIONS.length !== 28) problems.push('Rune data ring must contain 28 modules');
+  if (new Set(AZTEC_RUNE_DATA_POSITIONS.map(([x, y]) => `${x},${y}`)).size !== 28) problems.push('Rune data coordinates must be unique');
+  const structure = buildAztecRuneStructure();
+  for (let y = 0; y < AZTEC_RUNE_SIZE; y++) for (let x = 0; x < AZTEC_RUNE_SIZE; x++) {
+    if (isAztecRuneDataPosition(x, y)) continue;
+    const expected = aztecRuneStructuralValue(x, y) === true;
+    if (structure.get(x, y) !== expected) problems.push(`Rune structure mismatch at ${x},${y}`);
+  }
+  return problems;
+}

package/src/ts/compactpdf417/decoder.ts

@@ -0,0 +1,128 @@
+/*!
+ * 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.
+ */
+
+/** Compact PDF417 decoder. @module compactpdf417/decoder */
+
+import { FormatError } from '../core/errors.js';
+import { decodePdf417CompactionDetailed } from '../pdf417/compaction.js';
+import { pdf417CorrectErrors, pdf417EccLength } from '../pdf417/error-correction.js';
+import { pdf417CodewordForPattern } from '../pdf417/tables.js';
+import {
+  COMPACT_PDF417_START_BITS,
+  compactPdf417Geometry,
+  compactPdf417Indicators,
+  compactPdf417MatchingLevels,
+} from './tables.js';
+
+function bits(matrix, y, x, width) {
+  let value = 0;
+  for (let index = 0; index < width; index++) value = (value << 1) | (matrix.get(x + index, y) ? 1 : 0);
+  return value;
+}
+
+function patternString(matrix, y, x, width) {
+  return bits(matrix, y, x, width).toString(2).padStart(width, '0');
+}
+
+/**
+ * Decode a compact/truncated PDF417 module matrix.
+ *
+ * The high-level payload uses the normal PDF417 Text/Byte/Numeric compaction
+ * rules. This function only changes the physical row parser: no right row
+ * indicator is expected and the final module of each row must be dark.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {object} [options]
+ * @param {number} [options.rowHeight]
+ */
+export function decodeCompactPDF417(matrix, options = {}) {
+  if (!matrix?.width || !matrix?.height) throw new FormatError('Compact PDF417: no matrix supplied');
+  const rowHeight = options.rowHeight ?? matrix.compactPdf417?.rowHeight ?? 3;
+  let geometry;
+  try { geometry = compactPdf417Geometry(matrix.width, matrix.height, rowHeight); }
+  catch (error) { throw new FormatError(error.message); }
+
+  const { rows, columns } = geometry;
+  const all = [];
+  const erasures = [];
+  const leftIndicators = [];
+
+  for (let row = 0; row < rows; row++) {
+    const y = row * rowHeight;
+    if (patternString(matrix, y, 0, 17) !== COMPACT_PDF417_START_BITS) {
+      throw new FormatError('Compact PDF417: missing start pattern');
+    }
+    const cluster = (row % 3) * 3;
+    const leftDecoded = pdf417CodewordForPattern(bits(matrix, y, 17, 17));
+    if (!leftDecoded || leftDecoded.cluster !== cluster) {
+      throw new FormatError('Compact PDF417: invalid left row indicator');
+    }
+    leftIndicators.push(leftDecoded.codeword);
+
+    const dataStart = 34;
+    const stopX = dataStart + columns * 17;
+    if (!matrix.get(stopX, y)) throw new FormatError('Compact PDF417: missing reduced stop module');
+    for (let column = 0; column < columns; column++) {
+      const decoded = pdf417CodewordForPattern(bits(matrix, y, dataStart + column * 17, 17));
+      if (!decoded || decoded.cluster !== cluster) {
+        erasures.push(all.length);
+        all.push(0);
+      } else {
+        all.push(decoded.codeword);
+      }
+    }
+  }
+
+  const levels = compactPdf417MatchingLevels(leftIndicators, rows, columns);
+  if (levels.length !== 1) throw new FormatError('Compact PDF417: row indicator mismatch');
+  const level = levels[0];
+  const eccLength = pdf417EccLength(level);
+  if (all.length <= eccLength) throw new FormatError('Compact PDF417: insufficient codewords for ECC');
+
+  const corrected = all.slice();
+  const corrections = pdf417CorrectErrors(corrected, level, erasures);
+  const length = corrected[0];
+  if (length < 1 || length > corrected.length - eccLength) {
+    throw new FormatError('Compact PDF417: invalid symbol length descriptor');
+  }
+  const payload = corrected.slice(1, length);
+  const decoded = decodePdf417CompactionDetailed(payload);
+  return {
+    ...decoded,
+    format: 'compact-pdf417',
+    compact: true,
+    codewords: corrected,
+    rows,
+    columns,
+    eccLevel: level,
+    rowHeight,
+    corrections,
+  };
+}

package/src/ts/compactpdf417/detector.ts

@@ -0,0 +1,139 @@
+/*!
+ * 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.
+ */
+
+/** Compact PDF417 detector for clean, integer-scaled rasters. @module compactpdf417/detector */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { compactPdf417Width } from './tables.js';
+import { decodeCompactPDF417 } from './decoder.js';
+
+function rotateClockwise(source) {
+  const out = new BitMatrix(source.height, source.width);
+  for (let y = 0; y < source.height; y++) {
+    for (let x = 0; x < source.width; x++) {
+      if (source.get(x, y)) out.set(source.height - 1 - y, x);
+    }
+  }
+  return out;
+}
+function cropAndDownsample(source, box, width, height, scale) {
+  const out = new BitMatrix(width, height);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      let dark = 0;
+      for (let dy = 0; dy < scale; dy++) {
+        for (let dx = 0; dx < scale; dx++) {
+          if (source.get(box.x + x * scale + dx, box.y + y * scale + dy)) dark++;
+        }
+      }
+      if (dark * 2 >= scale * scale) out.set(x, y);
+    }
+  }
+  return out;
+}
+
+function cornersFor(box) {
+  return [
+    { x: box.x, y: box.y },
+    { x: box.x + box.width, y: box.y },
+    { x: box.x + box.width, y: box.y + box.height },
+    { x: box.x, y: box.y + box.height },
+  ];
+}
+
+function mapCorners(corners, toOriginal) {
+  return corners.map((point) => toOriginal(point));
+}
+
+/**
+ * Detect one Compact PDF417 symbol in a binarized raster.
+ *
+ * The clean-raster detector uses the dark bounding box and enumerates legal
+ * compact widths, integer module scales, row counts and row heights. It is
+ * deliberately conservative: arbitrary perspective, non-integer resampling,
+ * grayscale thresholding and damaged stop bars belong to a future photo
+ * detector and are not claimed here.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} binaryImage
+ * @param {object} [options]
+ * @param {number} [options.rowHeight] Restrict the row-height search.
+ * @returns {object|null}
+ */
+export function detectCompactPDF417(binaryImage, options = {}) {
+  if (!binaryImage?.width || !binaryImage?.height || typeof binaryImage.get !== 'function') return null;
+
+  let oriented = binaryImage;
+  let toOriginal = (point) => ({ x: point.x, y: point.y });
+  for (let rotation = 0; rotation < 4; rotation++) {
+    const bounds = oriented.getBounds();
+    if (bounds) {
+      for (let columns = 1; columns <= 30; columns++) {
+        const width = compactPdf417Width(columns);
+        const scale = bounds.width / width;
+        if (!Number.isInteger(scale) || scale < 1) continue;
+        const baseHeight = bounds.height / scale;
+        const rowHeights = Number.isInteger(options.rowHeight)
+          ? [options.rowHeight]
+          : Array.from({ length: 18 }, (_, index) => index + 3);
+        for (const rowHeight of rowHeights) {
+          if (!Number.isInteger(baseHeight / rowHeight)) continue;
+          const rows = baseHeight / rowHeight;
+          if (rows < 3 || rows > 90) continue;
+          const matrix = cropAndDownsample(oriented, bounds, width, baseHeight, scale);
+          try {
+            const result = decodeCompactPDF417(matrix, { rowHeight });
+            const corners = mapCorners(cornersFor(bounds), toOriginal);
+            return {
+              ...result,
+              matrix,
+              corners,
+              rotation: rotation * 90,
+              moduleSize: scale,
+              compact: true,
+            };
+          } catch {
+            // Try another geometry; a standard PDF417 or random artwork should
+            // never be accepted unless the compact decoder validates every row.
+          }
+        }
+      }
+    }
+
+    const previous = oriented;
+    const previousToOriginal = toOriginal;
+    oriented = rotateClockwise(previous);
+    toOriginal = (point) => previousToOriginal({ x: point.y, y: previous.height - point.x });
+  }
+  return null;
+}
+
+export function detectAndDecodeCompactPDF417(binaryImage, options = {}) {
+  return detectCompactPDF417(binaryImage, options);
+}