@sythos/js_barcode_universal 1.0.0 → 1.2.5

package/src/micropdf417/tables.js

@@ -0,0 +1,184 @@
+/*!
+ * 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.
+ */
+
+/**
+ * MicroPDF417 format facts and Row Address Pattern (RAP) helpers.
+ *
+ * The tables are represented as compact, immutable data and are guarded by
+ * {@link validateMicroPdf417Tables}. They are deliberately separate from the
+ * PDF417 symbol-character table: MicroPDF417 has a fixed family of symbols and
+ * its own row-address system.
+ *
+ * Values are derived from publicly available symbology documentation and
+ * independently checked against black-box reference output. This module makes
+ * no certification or conformance claim.
+ *
+ * @module micropdf417/tables
+ */
+
+const variant = (id, columns, rows, eccCodewords, rapStart, rapRotation) => Object.freeze({
+  id,
+  columns,
+  rows,
+  totalCodewords: columns * rows,
+  dataCodewords: columns * rows - eccCodewords,
+  eccCodewords,
+  rapStart,
+  rapRotation,
+});
+
+/** All 34 predefined MicroPDF417 symbol variants, in format-table order. */
+export const MICROPDF417_VARIANTS = Object.freeze([
+  variant(1, 1, 11, 7, 1, 8), variant(2, 1, 14, 7, 8, 0),
+  variant(3, 1, 17, 7, 36, 0), variant(4, 1, 20, 8, 19, 0),
+  variant(5, 1, 24, 8, 9, 8), variant(6, 1, 28, 8, 25, 8),
+  variant(7, 2, 8, 8, 1, 0), variant(8, 2, 11, 9, 1, 8),
+  variant(9, 2, 14, 9, 8, 0), variant(10, 2, 17, 10, 36, 0),
+  variant(11, 2, 20, 11, 19, 0), variant(12, 2, 23, 13, 9, 8),
+  variant(13, 2, 26, 15, 27, 8),
+  variant(14, 3, 6, 12, 1, 0), variant(15, 3, 8, 14, 7, 0),
+  variant(16, 3, 10, 16, 15, 0), variant(17, 3, 12, 18, 25, 0),
+  variant(18, 3, 15, 21, 37, 0), variant(19, 3, 20, 26, 1, 16),
+  variant(20, 3, 26, 32, 1, 8), variant(21, 3, 32, 38, 21, 8),
+  variant(22, 3, 38, 44, 15, 16), variant(23, 3, 44, 50, 1, 24),
+  variant(24, 4, 4, 8, 47, 24), variant(25, 4, 6, 12, 1, 0),
+  variant(26, 4, 8, 14, 7, 0), variant(27, 4, 10, 16, 15, 0),
+  variant(28, 4, 12, 18, 25, 0), variant(29, 4, 15, 21, 37, 0),
+  variant(30, 4, 20, 26, 1, 16), variant(31, 4, 26, 32, 1, 8),
+  variant(32, 4, 32, 38, 21, 8), variant(33, 4, 38, 44, 15, 16),
+  variant(34, 4, 44, 50, 1, 24),
+]);
+
+const byId = new Map(MICROPDF417_VARIANTS.map((entry) => [entry.id, entry]));
+
+// Six run widths, ordered bar-space-bar-space-bar-space.  A RAP is ten
+// modules wide; the right RAP has one additional one-module stop bar when
+// rendered. Keeping runs rather than bitmap literals makes each invariant
+// inspectable and avoids a rendering-specific representation here.
+const SIDE_RAP_RUNS = Object.freeze([
+  '221311', '311311', '312211', '222211', '213211', '214111', '223111', '313111',
+  '322111', '412111', '421111', '331111', '241111', '232111', '231211', '321211',
+  '411211', '411121', '411112', '321112', '312112', '311212', '311221', '311131',
+  '311122', '311113', '221113', '221122', '221131', '221221', '222121', '312121',
+  '321121', '231121', '231112', '222112', '213112', '212212', '212221', '212131',
+  '212122', '212113', '211213', '211123', '211132', '211141', '211231', '211222',
+  '211312', '211321', '211411', '212311',
+]);
+
+const CENTER_RAP_RUNS = Object.freeze([
+  '112231', '121231', '122131', '131131', '131221', '132121', '141121', '141211',
+  '142111', '133111', '132211', '131311', '122311', '123211', '124111', '115111',
+  '114211', '114121', '123121', '123112', '122212', '122221', '121321', '121411',
+  '112411', '113311', '113221', '113212', '113122', '122122', '131122', '131113',
+  '122113', '113113', '112213', '112222', '112312', '112321', '111421', '111331',
+  '111322', '111232', '111223', '111133', '111124', '111214', '112114', '121114',
+  '121123', '121132', '112132', '112141',
+]);
+
+/** @param {number} value @param {number} offset @returns {number} */
+export function microPdf417NextRap(value, offset = 1) {
+  if (!Number.isInteger(value) || value < 1 || value > 52) throw new RangeError('MicroPDF417: RAP number must be in 1..52');
+  if (!Number.isInteger(offset)) throw new RangeError('MicroPDF417: RAP offset must be an integer');
+  return ((value - 1 + offset) % 52 + 52) % 52 + 1;
+}
+
+/** @param {number} id @returns {Readonly<typeof MICROPDF417_VARIANTS[number]>} */
+export function microPdf417VariantByNumber(id) {
+  const entry = byId.get(id);
+  if (!entry) throw new RangeError('MicroPDF417: variant must be an integer in 1..34');
+  return entry;
+}
+
+/**
+ * Return the smallest data-region candidate that fits `codewords`.
+ * Ties are resolved by width, then height, so selection is deterministic.
+ */
+export function microPdf417VariantForCapacity(codewords) {
+  if (!Number.isInteger(codewords) || codewords < 1) throw new RangeError('MicroPDF417: codeword capacity must be a positive integer');
+  const candidates = MICROPDF417_VARIANTS.filter((entry) => entry.dataCodewords >= codewords);
+  if (!candidates.length) throw new RangeError('MicroPDF417: payload exceeds the largest symbol data region');
+  return candidates.slice().sort((a, b) => a.totalCodewords - b.totalCodewords || a.columns - b.columns || a.rows - b.rows)[0];
+}
+
+/** Return the six bar/space run widths for a numbered side or center RAP. */
+export function microPdf417RapSequence(number, kind = 'side') {
+  if (!Number.isInteger(number) || number < 1 || number > 52) throw new RangeError('MicroPDF417: RAP number must be in 1..52');
+  if (kind === 'side') return SIDE_RAP_RUNS[number - 1];
+  if (kind === 'center') return CENTER_RAP_RUNS[number - 1];
+  throw new RangeError('MicroPDF417: RAP kind must be side or center');
+}
+
+/**
+ * Resolve all row-address data for a zero-based row within a variant.
+ * @returns {{left: number, center: number|null, right: number, cluster: 0|3|6}}
+ */
+export function microPdf417RowAddress(entry, row) {
+  if (!entry || !Number.isInteger(entry.columns) || !Number.isInteger(entry.rows)) throw new TypeError('MicroPDF417: a variant entry is required');
+  if (!Number.isInteger(row) || row < 0 || row >= entry.rows) throw new RangeError(`MicroPDF417: row must be in 0..${entry.rows - 1}`);
+  const left = microPdf417NextRap(entry.rapStart, row);
+  const cluster = /** @type {0|3|6} */ (((left - 1) % 3) * 3);
+  if (entry.columns < 3) return { left, center: null, right: microPdf417NextRap(left, entry.rapRotation), cluster };
+  const center = microPdf417NextRap(left, entry.rapRotation);
+  return { left, center, right: microPdf417NextRap(center, entry.rapRotation), cluster };
+}
+
+const validRuns = (runs) => runs.length === 6 && /^[1-9]{6}$/.test(runs) && [...runs].reduce((sum, digit) => sum + Number(digit), 0) === 10;
+const oneEdgeShift = (from, to) => [...from].reduce((sum, digit, index) => sum + Math.abs(Number(digit) - Number(to[index])), 0) === 2;
+
+/** Return any table-invariant failures; an empty result means the table is coherent. */
+export function validateMicroPdf417Tables() {
+  const issues = [];
+  if (MICROPDF417_VARIANTS.length !== 34) issues.push('expected 34 variants');
+  const ids = new Set();
+  const formats = new Set();
+  for (const entry of MICROPDF417_VARIANTS) {
+    if (ids.has(entry.id)) issues.push(`duplicate variant ${entry.id}`); ids.add(entry.id);
+    const format = `${entry.columns}x${entry.rows}`;
+    if (formats.has(format)) issues.push(`duplicate format ${format}`); formats.add(format);
+    if (entry.totalCodewords !== entry.columns * entry.rows) issues.push(`${format}: total codeword geometry mismatch`);
+    if (entry.dataCodewords + entry.eccCodewords !== entry.totalCodewords) issues.push(`${format}: data/ECC capacity mismatch`);
+    if (entry.eccCodewords < 7 || entry.eccCodewords > 50) issues.push(`${format}: invalid ECC length`);
+    if (entry.rapStart < 1 || entry.rapStart > 52 || entry.rapRotation < 0 || entry.rapRotation > 51) issues.push(`${format}: invalid RAP assignment`);
+    for (let row = 0; row < entry.rows; row++) {
+      const address = microPdf417RowAddress(entry, row);
+      if (address.cluster !== ((address.left - 1) % 3) * 3) issues.push(`${format}: cluster mismatch at row ${row}`);
+      if ((entry.columns < 3) !== (address.center === null)) issues.push(`${format}: center RAP layout mismatch`);
+    }
+  }
+  for (const [kind, runs] of [['side', SIDE_RAP_RUNS], ['center', CENTER_RAP_RUNS]]) {
+    if (runs.length !== 52) issues.push(`${kind}: expected 52 RAPs`);
+    if (new Set(runs).size !== runs.length) issues.push(`${kind}: duplicate RAP`);
+    for (let i = 0; i < runs.length; i++) {
+      if (!validRuns(runs[i])) issues.push(`${kind}: invalid RAP ${i + 1}`);
+      if (runs.length && !oneEdgeShift(runs[i], runs[(i + 1) % runs.length])) issues.push(`${kind}: RAP ${i + 1} is not adjacent to its successor`);
+    }
+  }
+  return issues;
+}

package/src/pdf417/compaction.js

@@ -0,0 +1,298 @@
+/*!
+ * 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.
+ */
+
+/** PDF417 high-level text, byte and numeric compaction. @module pdf417/compaction */
+
+import { EncodeError, FormatError } from '../core/errors.js';
+
+const ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ ';
+const LOWER = 'abcdefghijklmnopqrstuvwxyz ';
+const MIXED = '0123456789&\r\t,:#-.$/+%*=^';
+const PUNCT = ';<>@[\\]_`~!\r\t,:\n-.$/"|*()?{}\'';
+
+function packBase30(values) {
+  const out = [];
+  for (let i = 0; i < values.length; i += 2) out.push(values[i] * 30 + (i + 1 < values.length ? values[i + 1] : 29));
+  return out;
+}
+
+/** Compact a value using the PDF417 Text Compaction alphabet. */
+export function compactPdf417Text(value) {
+  if (typeof value !== 'string') throw new EncodeError('PDF417 text: value must be a string');
+  const values = [];
+  let submode = 'alpha';
+  for (const character of value) {
+    const inAlpha = ALPHA.indexOf(character), inLower = LOWER.indexOf(character);
+    const inMixed = MIXED.indexOf(character), inPunct = PUNCT.indexOf(character);
+    if (submode === 'alpha') {
+      if (inAlpha >= 0) values.push(inAlpha);
+      else if (inLower >= 0) { values.push(27, inLower); submode = 'lower'; }
+      else if (inMixed >= 0 || character === ' ') { values.push(28, character === ' ' ? 26 : inMixed); submode = 'mixed'; }
+      else if (inPunct >= 0) values.push(29, inPunct);
+      else throw new EncodeError(`PDF417 text: unsupported character ${JSON.stringify(character)}`);
+    } else if (submode === 'lower') {
+      if (inLower >= 0) values.push(inLower);
+      else if (inAlpha >= 0) values.push(27, inAlpha);
+      else if (inMixed >= 0 || character === ' ') { values.push(28, character === ' ' ? 26 : inMixed); submode = 'mixed'; }
+      else if (inPunct >= 0) values.push(29, inPunct);
+      else throw new EncodeError(`PDF417 text: unsupported character ${JSON.stringify(character)}`);
+    } else {
+      if (inMixed >= 0) values.push(inMixed);
+      else if (character === ' ') values.push(26);
+      else if (inAlpha >= 0) { values.push(28); submode = 'alpha'; values.push(inAlpha); }
+      else if (inLower >= 0) { values.push(27); submode = 'lower'; values.push(inLower); }
+      else if (inPunct >= 0) values.push(29, inPunct);
+      else throw new EncodeError(`PDF417 text: unsupported character ${JSON.stringify(character)}`);
+    }
+  }
+  return packBase30(values);
+}
+
+function asBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (typeof value === 'string') return new TextEncoder().encode(value);
+  throw new EncodeError('PDF417 byte: value must be text or a byte array');
+}
+
+/** Compact bytes using latch 924 for exact six-byte blocks and 901 otherwise. */
+export function compactPdf417Bytes(value) {
+  const bytes = asBytes(value);
+  const utf8 = typeof value === 'string' && /[^\x00-\x7f]/.test(value);
+  const out = utf8 ? [927, 26] : [];
+  out.push(bytes.length > 0 && bytes.length % 6 === 0 ? 924 : 901);
+  let at = 0;
+  while (at + 6 <= bytes.length) {
+    let number = 0n;
+    for (let i = 0; i < 6; i++) number = (number << 8n) | BigInt(bytes[at++]);
+    const group = new Array(5);
+    for (let i = 4; i >= 0; i--) { group[i] = Number(number % 900n); number /= 900n; }
+    out.push(...group);
+  }
+  while (at < bytes.length) out.push(bytes[at++]);
+  return out;
+}
+
+/** Compact decimal digits using latch 902 and groups of at most 44 digits. */
+export function compactPdf417Numeric(value) {
+  if (typeof value !== 'string' || !/^\d+$/.test(value)) throw new EncodeError('PDF417 numeric: value must contain decimal digits only');
+  const out = [902];
+  for (let at = 0; at < value.length; at += 44) {
+    let number = BigInt(`1${value.slice(at, at + 44)}`);
+    const group = [];
+    do { group.unshift(Number(number % 900n)); number /= 900n; } while (number > 0n);
+    out.push(...group);
+  }
+  return out;
+}
+
+/** Compact a single value, selecting text, numeric or byte mode. */
+export function compactPdf417(value, options = {}) {
+  const mode = options.compaction ?? 'auto';
+  if (mode === 'text') return compactPdf417Text(value);
+  if (mode === 'byte') return compactPdf417Bytes(value);
+  if (mode === 'numeric') return compactPdf417Numeric(value);
+  if (mode !== 'auto') throw new EncodeError(`PDF417: unsupported compaction mode ${JSON.stringify(mode)}`);
+  if (typeof value === 'string' && /^\d{13,}$/.test(value)) return compactPdf417Numeric(value);
+  if (typeof value === 'string') {
+    try { return compactPdf417Text(value); } catch (error) { if (!(error instanceof EncodeError)) throw error; }
+  }
+  return compactPdf417Bytes(value);
+}
+
+function assertCodeword(codeword) {
+  if (!Number.isInteger(codeword) || codeword < 0 || codeword > 928) throw new FormatError('PDF417: codeword is outside 0..928');
+}
+
+function decodeUtf8(bytes, eci) {
+  if (eci === 3) return Array.from(bytes, (byte) => String.fromCharCode(byte)).join('');
+  if (eci !== 26) throw new FormatError(`PDF417 ECI: unsupported assignment number ${eci}`);
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(new Uint8Array(bytes)); }
+  catch { throw new FormatError('PDF417 byte: invalid UTF-8 sequence'); }
+}
+
+function decodeByteSegment(codewords, at, eci, sixOnly = false) {
+  const values = [];
+  while (at < codewords.length && codewords[at] < 900) values.push(codewords[at++]);
+  if (sixOnly && values.length % 5) throw new FormatError('PDF417 byte: 924 segment must contain complete six-byte groups');
+  const bytes = [];
+  // In 901 mode an encoder can use five terminal literal codewords. The
+  // unambiguous groups are therefore the ones followed by another codeword;
+  // 924 is available whenever a segment consists exclusively of six-byte groups.
+  const groupCount = sixOnly ? values.length / 5 : Math.max(0, Math.floor((values.length - 1) / 5));
+  for (let groupAt = 0; groupAt < groupCount * 5; groupAt += 5) {
+    let number = 0n;
+    for (let i = 0; i < 5; i++) number = number * 900n + BigInt(values[groupAt + i]);
+    const group = new Uint8Array(6);
+    for (let i = 5; i >= 0; i--) { group[i] = Number(number & 255n); number >>= 8n; }
+    if (number !== 0n) throw new FormatError('PDF417 byte: base-900 group exceeds six bytes');
+    bytes.push(...group);
+  }
+  for (let i = groupCount * 5; i < values.length; i++) {
+    if (values[i] > 255) throw new FormatError('PDF417 byte: literal tail is outside 0..255');
+    bytes.push(values[i]);
+  }
+  return { at, text: decodeUtf8(bytes, eci), bytes: Uint8Array.from(bytes) };
+}
+
+function decodeTextSegment(codewords, at, eci) {
+  let mode = 'alpha';
+  let output = '';
+  let shift = null;
+  let shiftedBytes = [];
+  const bytes = [];
+  const flushShiftedBytes = () => {
+    if (shiftedBytes.length) {
+      output += decodeUtf8(shiftedBytes, eci);
+      bytes.push(...shiftedBytes);
+      shiftedBytes = [];
+    }
+  };
+  const emit = (alphabet, value) => {
+    if (value < 0 || value >= alphabet.length) throw new FormatError('PDF417 text: invalid submode value');
+    output += alphabet[value];
+  };
+  const process = (value) => {
+    if (shift) { emit(shift === 'alpha' ? ALPHA : PUNCT, value); shift = null; return; }
+    if (mode === 'alpha') {
+      if (value < 26) emit(ALPHA, value);
+      else if (value === 26) output += ' ';
+      else if (value === 27) mode = 'lower';
+      else if (value === 28) mode = 'mixed';
+      else if (value === 29) shift = 'punct';
+    } else if (mode === 'lower') {
+      if (value < 26) emit(LOWER, value);
+      else if (value === 26) output += ' ';
+      else if (value === 27) shift = 'alpha';
+      else if (value === 28) mode = 'mixed';
+      else if (value === 29) shift = 'punct';
+    } else if (mode === 'mixed') {
+      if (value < 25) emit(MIXED, value);
+      else if (value === 25) mode = 'punct';
+      else if (value === 26) output += ' ';
+      else if (value === 27) mode = 'lower';
+      else if (value === 28) mode = 'alpha';
+      else if (value === 29) shift = 'punct';
+    } else {
+      if (value < 29) emit(PUNCT, value);
+      else if (value === 29) mode = 'alpha';
+    }
+  };
+  while (at < codewords.length) {
+    const codeword = codewords[at];
+    if (codeword >= 900 && codeword !== 913) break;
+    at++;
+    if (codeword === 913) {
+      if (at >= codewords.length || codewords[at] > 255) throw new FormatError('PDF417 text: invalid byte shift');
+      shiftedBytes.push(codewords[at++]);
+      continue;
+    }
+    flushShiftedBytes();
+    process(Math.floor(codeword / 30));
+    process(codeword % 30);
+  }
+  flushShiftedBytes();
+  return { at, text: output, bytes: Uint8Array.from(bytes) };
+}
+
+function decodeNumericSegment(codewords, at) {
+  let output = '';
+  while (at < codewords.length && codewords[at] < 900) {
+    const end = Math.min(at + 15, codewords.length);
+    let number = 0n;
+    for (; at < end && codewords[at] < 900; at++) number = number * 900n + BigInt(codewords[at]);
+    const decimal = number.toString();
+    if (!decimal.startsWith('1')) throw new FormatError('PDF417 numeric: missing leading sentinel');
+    output += decimal.slice(1);
+  }
+  return { at, text: output, bytes: new Uint8Array(0) };
+}
+
+/**
+ * Decode PDF417 compaction while preserving raw Byte Compaction and byte-shift
+ * payloads. Text and Numeric Compaction do not manufacture bytes: their text
+ * is available on each segment, while `bytes` contains only octets carried by
+ * modes that encode octets explicitly.
+ */
+export function decodePdf417CompactionDetailed(codewords) {
+  if (!Array.isArray(codewords) && !ArrayBuffer.isView(codewords)) throw new FormatError('PDF417: codewords must be an array');
+  for (const codeword of codewords) assertCodeword(codeword);
+  let at = 0;
+  // ISO/IEC 8859-1 is the PDF417 default; UTF-8 is selected explicitly with ECI 26.
+  let eci = 3;
+  let output = '';
+  const bytes = [];
+  const segments = [];
+  while (at < codewords.length) {
+    const codeword = codewords[at];
+    if (codeword < 900 || codeword === 900 || codeword === 913) {
+      const start = at;
+      const latch = codeword === 900 ? codeword : null;
+      if (latch !== null) at++;
+      const segment = decodeTextSegment(codewords, at, eci);
+      at = segment.at;
+      output += segment.text;
+      bytes.push(...segment.bytes);
+      if (segment.text.length || segment.bytes.length) segments.push({ mode: 'text', text: segment.text, bytes: segment.bytes, eci, latch, codewordStart: start, codewordEnd: at });
+      continue;
+    }
+    const start = at;
+    at++;
+    if (codeword === 901) {
+      const segment = decodeByteSegment(codewords, at, eci);
+      at = segment.at;
+      output += segment.text;
+      bytes.push(...segment.bytes);
+      segments.push({ mode: 'byte', text: segment.text, bytes: segment.bytes, eci, latch: codeword, codewordStart: start, codewordEnd: at });
+    } else if (codeword === 924) {
+      const segment = decodeByteSegment(codewords, at, eci, true);
+      at = segment.at;
+      output += segment.text;
+      bytes.push(...segment.bytes);
+      segments.push({ mode: 'byte', text: segment.text, bytes: segment.bytes, eci, latch: codeword, codewordStart: start, codewordEnd: at });
+    } else if (codeword === 902) {
+      const segment = decodeNumericSegment(codewords, at);
+      at = segment.at;
+      output += segment.text;
+      segments.push({ mode: 'numeric', text: segment.text, bytes: segment.bytes, eci, latch: codeword, codewordStart: start, codewordEnd: at });
+    } else if (codeword === 927) {
+      if (at >= codewords.length || codewords[at] > 899) throw new FormatError('PDF417 ECI: missing assignment number');
+      eci = codewords[at++];
+    } else {
+      throw new FormatError(`PDF417: unsupported compaction codeword ${codeword}`);
+    }
+  }
+  return { text: output, bytes: Uint8Array.from(bytes), segments };
+}
+
+/** Decode PDF417 Text, Byte, Numeric and UTF-8 ECI compaction segments in source order. */
+export function decodePdf417Compaction(codewords) {
+  return decodePdf417CompactionDetailed(codewords).text;
+}

package/src/pdf417/decoder.js

@@ -0,0 +1,75 @@
+/*!
+ * 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.
+ */
+
+import { FormatError } from '../core/errors.js';
+import { decodePdf417CompactionDetailed } from './compaction.js';
+import { pdf417CorrectErrors, pdf417EccLength } from './error-correction.js';
+import { pdf417CodewordForPattern } from './tables.js';
+
+const START = '11111111010101000';
+const STOP = '111111101000101001';
+function bits(matrix, y, x, width) { let value = 0; for (let i = 0; i < width; i++) value = (value << 1) | (matrix.get(x + i, y) ? 1 : 0); return value; }
+function indicators(row, rows, cols, level) { const group = Math.floor(row / 3), y = Math.floor((rows - 1) / 3), z = level * 3 + (rows - 1) % 3, v = cols - 1; return row % 3 === 0 ? [30 * group + y, 30 * group + v] : row % 3 === 1 ? [30 * group + z, 30 * group + y] : [30 * group + v, 30 * group + z]; }
+
+export function decodePDF417(matrix, options = {}) {
+  if (!matrix?.width || !matrix?.height || (matrix.width - 69) % 17) throw new FormatError('PDF417: invalid matrix dimensions');
+  const cols = (matrix.width - 69) / 17, rowHeight = options.rowHeight ?? matrix.pdf417?.rowHeight ?? 3;
+  if (!Number.isInteger(rowHeight) || matrix.height % rowHeight) throw new FormatError('PDF417: invalid row height');
+  const rows = matrix.height / rowHeight;
+  if (rows < 3 || rows > 90 || cols < 1 || cols > 30) throw new FormatError('PDF417: dimensions outside the standard range');
+  const all = [];
+  const erasures = [];
+  for (let row = 0; row < rows; row++) {
+    const y = row * rowHeight, cluster = (row % 3) * 3;
+    if (bits(matrix, y, 0, 17).toString(2).padStart(17, '0') !== START || bits(matrix, y, matrix.width - 18, 18).toString(2).padStart(18, '0') !== STOP) throw new FormatError('PDF417: missing start or stop pattern');
+    const read = (x) => { const result = pdf417CodewordForPattern(bits(matrix, y, x, 17)); if (!result || result.cluster !== cluster) throw new FormatError('PDF417: invalid codeword pattern'); return result.codeword; };
+    const left = read(17), right = read(34 + cols * 17);
+    let matched = false; for (let level = 0; level <= 8; level++) { const expected = indicators(row, rows, cols, level); if (left === expected[0] && right === expected[1]) { matched = true; break; } }
+    if (!matched) throw new FormatError('PDF417: row indicator mismatch');
+    for (let col = 0; col < cols; col++) {
+      try { all.push(read(34 + col * 17)); }
+      catch {
+        erasures.push(all.length);
+        all.push(0);
+      }
+    }
+  }
+  let level = -1; for (let candidate = 0; candidate <= 8; candidate++) if (all.length > pdf417EccLength(candidate)) { level = candidate; break; }
+  // The row indicators determine the level uniquely across the symbol.
+  for (let candidate = 0; candidate <= 8; candidate++) {
+    let ok = true; for (let row = 0; row < rows; row++) { const y = row * rowHeight, cluster = (row % 3) * 3, expected = indicators(row, rows, cols, candidate); const left = pdf417CodewordForPattern(bits(matrix, y, 17, 17)); const right = pdf417CodewordForPattern(bits(matrix, y, 34 + cols * 17, 17)); if (!left || !right || left.cluster !== cluster || right.cluster !== cluster || left.codeword !== expected[0] || right.codeword !== expected[1]) { ok = false; break; } } if (ok) { level = candidate; break; }
+  }
+  if (level < 0) throw new FormatError('PDF417: could not determine error correction level');
+  const corrected = all.slice(); const corrections = pdf417CorrectErrors(corrected, level, erasures);
+  const length = corrected[0]; if (length < 1 || length > corrected.length - pdf417EccLength(level)) throw new FormatError('PDF417: invalid symbol length descriptor');
+  const payload = corrected.slice(1, length);
+  const decoded = decodePdf417CompactionDetailed(payload);
+  return { ...decoded, codewords: corrected, rows, columns: cols, eccLevel: level, corrections };
+}