@sythos/js_barcode_universal 1.5.14 → 1.5.15

package/src/ts/databar/expanded.ts

@@ -0,0 +1,948 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ * SPDX-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ *
+ * 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.
+ */
+
+/**
+ * GS1 DataBar Expanded (RSS Expanded) writer, strict matrix reader and
+ * clean-raster detector.
+ *
+ * The implementation deliberately handles the linear Expanded symbol only.
+ * Expanded Stacked has a different row layout and remains in `stacked.ts`.
+ * Width construction is performed from the normative constrained-composition
+ * rules, so no third-party barcode table or runtime dependency is needed.
+ *
+ * @module databar/expanded
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { ChecksumError, EncodeError, FormatError } from '../core/errors.js';
+import { createDetectionCandidate } from '../core/detection-contract.js';
+import { dataBarWidths } from './patterns.js';
+import {
+  GS1_SEPARATOR,
+  decodeGS1ElementString,
+  encodeGS1ElementString,
+} from './gs1.js';
+
+const DATA_CHARACTER_MODULES = 17;
+const FINDER_PATTERN_MODULES = 15;
+const MIN_HEIGHT_MODULES = 34;
+const MIN_DATA_CHARACTERS = 4;
+const MAX_DATA_CHARACTERS = 21;
+const MAX_CHARACTER_VALUE = 4_191;
+const MAX_DIMENSION = 32_768;
+const MAX_MODULES = 16_777_216;
+
+/*
+ * Finder codes are five-run physical patterns. Codes 1, 3, 5, 7, 9 and 11
+ * are the reflected forms used when the finder is read in the opposite
+ * parity position.
+ */
+const FINDER_PATTERNS = Object.freeze([
+  Object.freeze([1, 8, 4, 1, 1]),
+  Object.freeze([1, 1, 4, 8, 1]),
+  Object.freeze([3, 6, 4, 1, 1]),
+  Object.freeze([1, 1, 4, 6, 3]),
+  Object.freeze([3, 4, 6, 1, 1]),
+  Object.freeze([1, 1, 6, 4, 3]),
+  Object.freeze([3, 2, 8, 1, 1]),
+  Object.freeze([1, 1, 8, 2, 3]),
+  Object.freeze([2, 6, 5, 1, 1]),
+  Object.freeze([1, 1, 5, 6, 2]),
+  Object.freeze([2, 2, 9, 1, 1]),
+  Object.freeze([1, 1, 9, 2, 2]),
+]);
+
+/* Finder codes for 2..11 data-character pairs, in their normative order. */
+const FINDER_SEQUENCES = Object.freeze([
+  Object.freeze([0, 1]),
+  Object.freeze([0, 3, 2]),
+  Object.freeze([0, 5, 2, 7]),
+  Object.freeze([0, 9, 2, 7, 4]),
+  Object.freeze([0, 9, 2, 7, 6, 11]),
+  Object.freeze([0, 9, 2, 7, 8, 11, 10]),
+  Object.freeze([0, 1, 2, 3, 4, 5, 6, 7]),
+  Object.freeze([0, 1, 2, 3, 4, 5, 6, 9, 8]),
+  Object.freeze([0, 1, 2, 3, 4, 5, 6, 9, 10, 11]),
+  Object.freeze([0, 1, 2, 3, 4, 7, 6, 9, 8, 11, 10]),
+]);
+
+/*
+ * Expanded character groups. `oddRanks` and `evenRanks` are the number of
+ * legal constrained compositions. Data characters carry 12 information bits;
+ * the check character also uses the normative values through 4191.
+ */
+const GROUPS = Object.freeze([
+  Object.freeze({ gsum: 0, oddTotal: 12, evenTotal: 5, oddWidest: 7, evenWidest: 2, oddRanks: 87, evenRanks: 4 }),
+  Object.freeze({ gsum: 348, oddTotal: 10, evenTotal: 7, oddWidest: 5, evenWidest: 4, oddRanks: 52, evenRanks: 20 }),
+  Object.freeze({ gsum: 1388, oddTotal: 8, evenTotal: 9, oddWidest: 4, evenWidest: 5, oddRanks: 30, evenRanks: 52 }),
+  Object.freeze({ gsum: 2948, oddTotal: 6, evenTotal: 11, oddWidest: 3, evenWidest: 6, oddRanks: 10, evenRanks: 104 }),
+  Object.freeze({ gsum: 3988, oddTotal: 4, evenTotal: 13, oddWidest: 1, evenWidest: 8, oddRanks: 1, evenRanks: 204 }),
+]);
+
+/* Checksum blocks derive from the repeating power-of-three sequence. */
+const CHECKSUM_POWERS = Object.freeze(Array.from({ length: 184 }, (_, exponent) => {
+  let value = 1;
+  for (let index = 0; index < exponent; index++) value = (value * 3) % 211;
+  return value;
+}));
+
+const CHECKSUM_WEIGHT_BLOCKS = Object.freeze([
+  Object.freeze([
+    -1, -1, -1, -1, -1, -1, -1, -1,
+    ...Array.from({ length: 8 }, (_, index) => CHECKSUM_POWERS[7 - index]),
+  ]),
+  ...Array.from({ length: 11 }, (_, index) => Object.freeze([
+    ...CHECKSUM_POWERS.slice(8 + index * 16, 16 + index * 16),
+    ...Array.from({ length: 8 }, (_, offset) => CHECKSUM_POWERS[23 + index * 16 - offset]),
+  ])),
+]);
+
+const ISO646_VALUES = new Map([
+  ['!', 232], ['"', 233], ['%', 234], ['&', 235], ["'", 236],
+  ['(', 237], [')', 238], ['*', 239], ['+', 240], [',', 241],
+  ['-', 242], ['.', 243], ['/', 244], [':', 245], [';', 246],
+  ['<', 247], ['=', 248], ['>', 249], ['?', 250], ['_', 251],
+  [' ', 252],
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function positiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new EncodeError(`GS1 DataBar Expanded ${label} must be a positive integer`);
+  }
+  return value;
+}
+
+function resolveGeometry(options, logicalWidth) {
+  if (options === undefined) options = {};
+  if (!isRecord(options)) throw new TypeError('GS1 DataBar Expanded options must be an object');
+  if (options.linkage !== undefined && typeof options.linkage !== 'boolean') {
+    throw new TypeError('GS1 DataBar linkage must be a boolean');
+  }
+  if (options.moduleScale !== undefined && options.scale !== undefined
+    && options.moduleScale !== options.scale) {
+    throw new EncodeError('GS1 DataBar Expanded moduleScale and scale disagree');
+  }
+  const scale = positiveInteger(options.moduleScale ?? options.scale ?? 1, 'moduleScale');
+  const height = positiveInteger(options.height ?? MIN_HEIGHT_MODULES * scale, 'height');
+  if (height < MIN_HEIGHT_MODULES * scale) {
+    throw new EncodeError('GS1 DataBar Expanded height is below the normative 34-module minimum');
+  }
+  const width = logicalWidth * scale;
+  if (!Number.isSafeInteger(width) || width > MAX_DIMENSION
+    || height > MAX_DIMENSION || width * height > MAX_MODULES) {
+    throw new EncodeError('GS1 DataBar Expanded dimensions exceed the safe matrix limit');
+  }
+  return Object.freeze({
+    scale,
+    height,
+    width,
+    linkage: options.linkage === true,
+  });
+}
+
+function combinations(n, r) {
+  if (n < r || r < 0) return 0;
+  if (r === 0 || n === r) return 1;
+  const k = Math.min(r, n - r);
+  let result = 1;
+  for (let index = 1; index <= k; index++) {
+    result = result * (n - k + index) / index;
+  }
+  return result;
+}
+
+/*
+ * Rank the same constrained composition that `dataBarWidths` un-ranks. This
+ * local inverse lets the reader reject width sequences that merely resemble a
+ * data character instead of silently normalising them.
+ */
+function candidateCount(remaining, bar, width, elements, maximumWidth, noNarrow, narrowMask) {
+  let count = combinations(remaining - width - 1, elements - bar - 2);
+  if (noNarrow && narrowMask === 0
+    && remaining - width - (elements - bar - 1) >= elements - bar - 1) {
+    count -= combinations(remaining - width - (elements - bar), elements - bar - 2);
+  }
+  if (elements - bar - 1 > 1) {
+    let tooWide = 0;
+    for (let last = remaining - width - (elements - bar - 2); last > maximumWidth; last--) {
+      tooWide += combinations(remaining - width - last - 1, elements - bar - 3);
+    }
+    count -= tooWide * (elements - 1 - bar);
+  } else if (remaining - width > maximumWidth) {
+    count--;
+  }
+  return count;
+}
+
+function rankWidths(widths, modules, maximumWidth, noNarrow) {
+  if (!Array.isArray(widths) || widths.length !== 4
+    || widths.some((width) => !Number.isSafeInteger(width) || width < 1 || width > maximumWidth)
+    || widths.reduce((sum, width) => sum + width, 0) !== modules) {
+    throw new FormatError('GS1 DataBar Expanded subset widths are invalid');
+  }
+  let rank = 0;
+  let remaining = modules;
+  let narrowMask = 0;
+  for (let bar = 0; bar < 3; bar++) {
+    const selected = widths[bar];
+    for (let width = 1; width < selected; width++) {
+      if (width === 1) narrowMask |= 1 << bar;
+      rank += candidateCount(remaining, bar, width, 4, maximumWidth, noNarrow, narrowMask);
+      narrowMask &= ~(1 << bar);
+    }
+    if (selected === 1) narrowMask |= 1 << bar;
+    else narrowMask &= ~(1 << bar);
+    remaining -= selected;
+  }
+  if (widths[3] !== remaining) throw new FormatError('GS1 DataBar Expanded subset rank is not canonical');
+  return rank;
+}
+
+function groupForValue(value) {
+  for (let index = GROUPS.length - 1; index >= 0; index--) {
+    if (value >= GROUPS[index].gsum) return GROUPS[index];
+  }
+  throw new RangeError('GS1 DataBar Expanded character value is out of range');
+}
+
+function expandedCharacterWidths(value) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > MAX_CHARACTER_VALUE) {
+    throw new RangeError('GS1 DataBar Expanded character value is outside the normative range');
+  }
+  const group = groupForValue(value);
+  const offset = value - group.gsum;
+  const oddRank = Math.floor(offset / group.evenRanks);
+  const evenRank = offset % group.evenRanks;
+  if (oddRank >= group.oddRanks || evenRank >= group.evenRanks) {
+    throw new RangeError('GS1 DataBar Expanded character value is outside its group');
+  }
+  const odd = dataBarWidths(oddRank, group.oddTotal, 4, group.oddWidest, true);
+  const even = dataBarWidths(evenRank, group.evenTotal, 4, group.evenWidest, false);
+  const widths = [];
+  for (let index = 0; index < 4; index++) widths.push(odd[index], even[index]);
+  if (widths.reduce((sum, width) => sum + width, 0) !== DATA_CHARACTER_MODULES) {
+    throw new EncodeError('GS1 DataBar Expanded data character width total is invalid');
+  }
+  return widths;
+}
+
+function physicalDataCharacterWidths(value, characterIndex) {
+  const canonical = expandedCharacterWidths(value);
+  /* The first payload character follows the check character in reverse order. */
+  return characterIndex % 2 === 1 ? canonical.slice().reverse() : canonical;
+}
+
+const dataCharacterMaps = new Map();
+const checkCharacterMap = new Map();
+
+function getCharacterMap(characterIndex, check = false) {
+  const key = check ? 'check' : (characterIndex & 1);
+  const cache = check ? checkCharacterMap : dataCharacterMaps;
+  if (cache.has(key)) return cache.get(key);
+  const map = new Map();
+  const maximum = check ? MAX_CHARACTER_VALUE : 4095;
+  for (let value = 0; value <= maximum; value++) {
+    const widths = check ? expandedCharacterWidths(value) : physicalDataCharacterWidths(value, characterIndex);
+    map.set(widths.join(','), value);
+  }
+  cache.set(key, map);
+  return map;
+}
+
+function valueForWidths(widths, characterIndex, check = false) {
+  const value = getCharacterMap(characterIndex, check).get(widths.join(','));
+  if (value === undefined) throw new FormatError('GS1 DataBar Expanded character widths are invalid');
+  return value;
+}
+
+function finderWidths(finderCode) {
+  const pattern = FINDER_PATTERNS[finderCode];
+  if (!pattern) throw new FormatError('GS1 DataBar Expanded finder type is invalid');
+  return pattern;
+}
+
+function appendWidths(bits, widths, dark) {
+  let colour = dark;
+  for (const width of widths) {
+    for (let index = 0; index < width; index++) bits.push(colour);
+    colour = !colour;
+  }
+  return colour;
+}
+
+function bitsToValue(bits, offset, length) {
+  let value = 0;
+  for (let index = 0; index < length; index++) value = (value << 1) | (bits[offset + index] ? 1 : 0);
+  return value;
+}
+
+function appendBits(target, value, length) {
+  for (let shift = length - 1; shift >= 0; shift--) target.push(((value >>> shift) & 1) !== 0);
+}
+
+function isDigit(value) {
+  return value >= '0' && value <= '9';
+}
+
+function isDigitOrFNC1(value) {
+  return isDigit(value) || value === GS1_SEPARATOR;
+}
+
+function appendNumericPair(bits, first, second) {
+  if (first === GS1_SEPARATOR) {
+    if (second !== GS1_SEPARATOR) throw new EncodeError('GS1 DataBar Expanded cannot start a field with FNC1');
+    appendBits(bits, 0, 4);
+    return;
+  }
+  const firstValue = first === GS1_SEPARATOR ? 10 : Number(first);
+  const secondValue = second === GS1_SEPARATOR ? 10 : Number(second);
+  if (firstValue > 9 || secondValue > 10) throw new EncodeError('GS1 DataBar Expanded numeric value is invalid');
+  if (second === GS1_SEPARATOR) {
+    appendBits(bits, firstValue + 1, 4);
+  } else {
+    appendBits(bits, 8 + 11 * firstValue + secondValue, 7);
+  }
+}
+
+function alphaValue(value) {
+  if (isDigit(value)) return { value: Number(value) + 5, length: 5 };
+  if (value === GS1_SEPARATOR) return { value: 15, length: 5, fnc1: true };
+  if (value >= 'A' && value <= 'Z') return { value: value.charCodeAt(0) - 33, length: 6 };
+  if (value === '*') return { value: 58, length: 6 };
+  if (value >= ',' && value <= '/') return { value: value.charCodeAt(0) + 15, length: 6 };
+  return undefined;
+}
+
+function isoValue(value) {
+  if (isDigit(value)) return { value: Number(value) + 5, length: 5 };
+  if (value === GS1_SEPARATOR) return { value: 15, length: 5, fnc1: true };
+  if (value >= 'A' && value <= 'Z') return { value: value.charCodeAt(0) - 1, length: 7 };
+  if (value >= 'a' && value <= 'z') return { value: value.charCodeAt(0) + 7, length: 7 };
+  const encoded = ISO646_VALUES.get(value);
+  return encoded === undefined ? undefined : { value: encoded, length: 8 };
+}
+
+/* Encode the general-purpose field from numeric mode, as required by Expanded. */
+function encodeGeneralPurpose(raw) {
+  const bits = [];
+  let mode = 'numeric';
+  let offset = 0;
+  while (offset < raw.length) {
+    const value = raw[offset];
+    if (mode === 'numeric') {
+      if (offset + 1 < raw.length && isDigitOrFNC1(value) && isDigitOrFNC1(raw[offset + 1])
+        && value !== GS1_SEPARATOR && raw[offset + 1] !== GS1_SEPARATOR) {
+        appendNumericPair(bits, value, raw[offset + 1]);
+        offset += 2;
+        continue;
+      }
+      if (offset + 1 < raw.length && isDigit(value) && raw[offset + 1] === GS1_SEPARATOR) {
+        appendNumericPair(bits, value, raw[offset + 1]);
+        offset += 2;
+        continue;
+      }
+      /* A lone digit before an alphanumeric value is encoded in alpha mode. */
+      appendBits(bits, 0, 4);
+      mode = 'alpha';
+      continue;
+    }
+
+    if (mode === 'alpha') {
+      if (value === GS1_SEPARATOR) {
+        appendBits(bits, 15, 5);
+        mode = 'numeric';
+        offset++;
+        continue;
+      }
+      const encoded = alphaValue(value);
+      if (encoded) {
+        appendBits(bits, encoded.value, encoded.length);
+        offset++;
+        continue;
+      }
+      /* Alpha-to-ISO/IEC 646 latch. */
+      appendBits(bits, 4, 5);
+      mode = 'iso646';
+      continue;
+    }
+
+    if (value === GS1_SEPARATOR) {
+      appendBits(bits, 15, 5);
+      mode = 'numeric';
+      offset++;
+      continue;
+    }
+    const encoded = isoValue(value);
+    if (!encoded) {
+      throw new EncodeError(`GS1 DataBar Expanded value contains unsupported character "${value}"`);
+    }
+    appendBits(bits, encoded.value, encoded.length);
+    offset++;
+  }
+  return Object.freeze({ bits, finalMode: mode });
+}
+
+function padGeneralPurpose(bits, finalMode, dataCharacters) {
+  const output = bits.slice();
+  const headerLength = 5;
+  const targetLength = dataCharacters * 12;
+  let remaining = targetLength - headerLength - output.length;
+  if (remaining < 0) throw new EncodeError('GS1 DataBar Expanded general-purpose field exceeds the selected symbol size');
+  if (finalMode === 'numeric' && remaining >= 4) {
+    appendBits(output, 0, 4);
+    remaining -= 4;
+  }
+  const fill = [false, false, true, false, false];
+  for (let index = 0; index < remaining; index++) output.push(fill[index % fill.length]);
+  if (output.length !== targetLength - headerLength) {
+    throw new EncodeError('GS1 DataBar Expanded padding length is invalid');
+  }
+  return output;
+}
+
+function encodePayload(raw, linkage) {
+  const general = encodeGeneralPurpose(raw);
+  let dataCharacters = Math.max(
+    MIN_DATA_CHARACTERS,
+    Math.ceil((12 + 1 + 2 + 2 + general.bits.length) / 12),
+  );
+  if (dataCharacters > MAX_DATA_CHARACTERS) {
+    throw new EncodeError('GS1 DataBar Expanded payload is too long for the 21 data-character limit');
+  }
+  const vlf = [dataCharacters & 1, dataCharacters > 14 ? 1 : 0];
+  const generalBits = padGeneralPurpose(general.bits, general.finalMode, dataCharacters);
+  const information = [Boolean(linkage), false, false, Boolean(vlf[0]), Boolean(vlf[1]), ...generalBits];
+  if (information.length !== dataCharacters * 12) {
+    throw new EncodeError('GS1 DataBar Expanded information field has an invalid length');
+  }
+  const values = [];
+  for (let offset = 0; offset < information.length; offset += 12) {
+    values.push(bitsToValue(information, offset, 12));
+  }
+  return Object.freeze({ values, dataCharacters, information });
+}
+
+function checksumWeightSequence(dataCharacters) {
+  const sequenceIndex = Math.floor((dataCharacters - 2) / 2);
+  const sequence = FINDER_SEQUENCES[sequenceIndex];
+  if (!sequence) throw new FormatError('GS1 DataBar Expanded finder sequence is invalid');
+  const weights = [];
+  for (const finderCode of sequence) {
+    const block = CHECKSUM_WEIGHT_BLOCKS[finderCode];
+    if (!block) throw new FormatError('GS1 DataBar Expanded checksum weight block is invalid');
+    weights.push(...block);
+  }
+  const payloadWeights = weights.slice(8, 8 + dataCharacters * 8);
+  if (payloadWeights.length !== dataCharacters * 8) {
+    throw new FormatError('GS1 DataBar Expanded checksum weight sequence is truncated');
+  }
+  return payloadWeights;
+}
+
+function checkCharacterValue(physicalWidths, dataCharacters) {
+  const weights = checksumWeightSequence(dataCharacters);
+  let checksum = 0;
+  for (let dataIndex = 0; dataIndex < physicalWidths.length; dataIndex++) {
+    for (let widthIndex = 0; widthIndex < 8; widthIndex++) {
+      checksum += physicalWidths[dataIndex][widthIndex] * weights[dataIndex * 8 + widthIndex];
+    }
+  }
+  const check = 211 * (dataCharacters - 3) + (checksum % 211);
+  if (check < 0 || check > MAX_CHARACTER_VALUE) throw new EncodeError('GS1 DataBar Expanded checksum value is out of range');
+  return check;
+}
+
+function buildPhysicalBits(dataValues, linkage) {
+  const dataCharacters = dataValues.length;
+  const pairCount = Math.ceil((dataCharacters + 1) / 2);
+  const sequenceIndex = Math.floor((dataCharacters - 2) / 2);
+  const sequence = FINDER_SEQUENCES[sequenceIndex];
+  if (!sequence || sequence.length !== pairCount) {
+    throw new EncodeError('GS1 DataBar Expanded data-character count has no valid finder sequence');
+  }
+  const dataWidths = dataValues.map((value, index) => physicalDataCharacterWidths(value, index + 1));
+  const checksumValue = checkCharacterValue(dataWidths, dataCharacters);
+  const widths = [expandedCharacterWidths(checksumValue), ...dataWidths];
+  let dark = true;
+  const bits = [];
+  dark = appendWidths(bits, [1, 1], dark);
+  for (let index = 0; index < widths.length; index++) {
+    dark = appendWidths(bits, widths[index], dark);
+    if ((index & 1) === 0) dark = appendWidths(bits, finderWidths(sequence[index / 2]), dark);
+  }
+  appendWidths(bits, [1, 1], dark);
+  const expectedWidth = 2 + widths.length * DATA_CHARACTER_MODULES
+    + pairCount * FINDER_PATTERN_MODULES + 2;
+  if (bits.length !== expectedWidth) throw new EncodeError('GS1 DataBar Expanded physical width is invalid');
+  return Object.freeze({ bits, widths, dataCharacters, pairCount, linkage, checksum: checksumValue });
+}
+
+function paint(bits, height, scale) {
+  const matrix = new BitMatrix(bits.length * scale, height);
+  for (let x = 0; x < bits.length; x++) {
+    if (bits[x]) matrix.setRegion(x * scale, 0, scale, height);
+  }
+  return matrix;
+}
+
+/** Encode a GS1 element string as linear GS1 DataBar Expanded. */
+export function encodeDataBarExpanded(value, options = {}) {
+  const raw = encodeGS1ElementString(value);
+  const linkage = options?.linkage === true;
+  const payload = encodePayload(raw, linkage);
+  const physical = buildPhysicalBits(payload.values, linkage);
+  const logicalWidth = physical.bits.length;
+  const geometry = resolveGeometry(options, logicalWidth);
+  const matrix = paint(physical.bits, geometry.height, geometry.scale);
+  matrix.databar = Object.freeze({
+    variant: 'expanded',
+    raw,
+    linkage,
+    dataCharacters: payload.dataCharacters,
+    pairs: physical.pairCount,
+    modules: logicalWidth,
+    moduleScale: geometry.scale,
+    height: geometry.height,
+  });
+  return matrix;
+}
+
+function requireMatrix(matrix) {
+  if (!matrix || !Number.isInteger(matrix.width) || !Number.isInteger(matrix.height)
+    || matrix.width < 1 || matrix.height < 1 || typeof matrix.get !== 'function') {
+    throw new TypeError('GS1 DataBar Expanded decoder expects a BitMatrix-like value');
+  }
+}
+
+function runWidths(bits) {
+  if (!bits.length) return [];
+  const widths = [];
+  let colour = bits[0];
+  let width = 0;
+  for (const bit of bits) {
+    if (bit === colour) width++;
+    else {
+      widths.push(width);
+      colour = bit;
+      width = 1;
+    }
+  }
+  widths.push(width);
+  return widths;
+}
+
+function logicalRow(matrix) {
+  requireMatrix(matrix);
+  const candidates = [];
+  for (let dataCharacters = MIN_DATA_CHARACTERS; dataCharacters <= MAX_DATA_CHARACTERS; dataCharacters++) {
+    const pairCount = Math.ceil((dataCharacters + 1) / 2);
+    const logicalWidth = 2 + (dataCharacters + 1) * DATA_CHARACTER_MODULES
+      + pairCount * FINDER_PATTERN_MODULES + 2;
+    if (matrix.width % logicalWidth === 0) candidates.push({ dataCharacters, logicalWidth, scale: matrix.width / logicalWidth });
+  }
+  if (candidates.length === 0) throw new FormatError('GS1 DataBar Expanded matrix width is not a valid symbol width');
+  const candidate = candidates.find(({ scale }) => Number.isSafeInteger(scale) && scale >= 1);
+  if (!candidate || matrix.height < MIN_HEIGHT_MODULES * candidate.scale) {
+    throw new FormatError('GS1 DataBar Expanded matrix scale or height is invalid');
+  }
+  const { dataCharacters, logicalWidth, scale } = candidate;
+  const row = [];
+  for (let x = 0; x < logicalWidth; x++) {
+    const sample = Boolean(matrix.get(x * scale + Math.floor(scale / 2), Math.floor(matrix.height / 2)));
+    for (let dx = 0; dx < scale; dx++) {
+      if (Boolean(matrix.get(x * scale + dx, Math.floor(matrix.height / 2))) !== sample) {
+        throw new FormatError('GS1 DataBar Expanded horizontal modules are not integer-scaled');
+      }
+    }
+    row.push(sample);
+  }
+  for (let y = 0; y < matrix.height; y++) {
+    for (let x = 0; x < logicalWidth; x++) {
+      const expected = row[x];
+      for (let dx = 0; dx < scale; dx++) {
+        if (Boolean(matrix.get(x * scale + dx, y)) !== expected) {
+          throw new FormatError('GS1 DataBar Expanded rows are inconsistent');
+        }
+      }
+    }
+  }
+  return { row, dataCharacters, logicalWidth, scale };
+}
+
+function decodePhysical(row, dataCharacters) {
+  const pairCount = Math.ceil((dataCharacters + 1) / 2);
+  const sequenceIndex = Math.floor((dataCharacters - 2) / 2);
+  const sequence = FINDER_SEQUENCES[sequenceIndex];
+  if (!sequence || sequence.length !== pairCount) throw new FormatError('GS1 DataBar Expanded finder sequence is invalid');
+  if (row.length < 4 || !row[0] || row[1]) throw new FormatError('GS1 DataBar Expanded left guard is invalid');
+  const values = [];
+  const physicalWidths = [];
+  let cursor = 2;
+  for (let index = 0; index <= dataCharacters; index++) {
+    const charBits = row.slice(cursor, cursor + DATA_CHARACTER_MODULES);
+    const widths = runWidths(charBits);
+    if (widths.length !== 8 || widths.reduce((sum, width) => sum + width, 0) !== DATA_CHARACTER_MODULES) {
+      throw new FormatError('GS1 DataBar Expanded data-character run count is invalid');
+    }
+    physicalWidths.push(widths);
+    values.push(valueForWidths(widths, index, index === 0));
+    cursor += DATA_CHARACTER_MODULES;
+    if ((index & 1) === 0) {
+      const finderBits = row.slice(cursor, cursor + FINDER_PATTERN_MODULES);
+      const observed = runWidths(finderBits);
+      const expected = finderWidths(sequence[index / 2]);
+      if (observed.length !== 5 || observed.some((width, position) => width !== expected[position])) {
+        throw new FormatError('GS1 DataBar Expanded finder pattern is invalid');
+      }
+      cursor += FINDER_PATTERN_MODULES;
+    }
+  }
+  const end = row.slice(cursor);
+  if (end.length !== 2 || end[0] === end[1]) throw new FormatError('GS1 DataBar Expanded right guard is invalid');
+  if (cursor + 2 !== row.length) throw new FormatError('GS1 DataBar Expanded trailing modules are invalid');
+  const weights = checksumWeightSequence(dataCharacters);
+  let checksum = 0;
+  for (let index = 1; index < values.length; index++) {
+    for (let widthIndex = 0; widthIndex < 8; widthIndex++) {
+      checksum += physicalWidths[index][widthIndex] * weights[(index - 1) * 8 + widthIndex];
+    }
+  }
+  const expected = 211 * (dataCharacters - 3) + (checksum % 211);
+  if (values[0] !== expected) throw new ChecksumError('GS1 DataBar Expanded checksum mismatch');
+  return Object.freeze({ values, physicalWidths, dataCharacters, pairCount, scale: 1 });
+}
+
+function decodeGeneralPurpose(payload) {
+  let position = 0;
+  let mode = 'numeric';
+  let raw = '';
+  const allZero = (offset) => {
+    for (let index = offset; index < payload.length; index++) if (payload[index]) return false;
+    return true;
+  };
+  const isPaddingTail = (offset) => {
+    const fill = [false, false, true, false, false];
+    for (let phase = 0; phase < fill.length; phase++) {
+      let matches = true;
+      for (let index = offset; index < payload.length; index++) {
+        if (payload[index] !== fill[(phase + index - offset) % fill.length]) {
+          matches = false;
+          break;
+        }
+      }
+      if (matches) return true;
+    }
+    return false;
+  };
+  const read = (length) => {
+    if (position + length > payload.length) throw new FormatError('GS1 DataBar Expanded general-purpose field is truncated');
+    const value = bitsToValue(payload, position, length);
+    position += length;
+    return value;
+  };
+  let guard = 0;
+  while (position < payload.length && guard++ < payload.length + 4) {
+    if (mode === 'numeric') {
+      if (position + 7 <= payload.length && !allZero(position)) {
+        const value = bitsToValue(payload, position, 7);
+        if (value >= 8 && value <= 117) {
+          const first = Math.floor((value - 8) / 11);
+          const second = (value - 8) % 11;
+          if (first > 9 || second > 9) throw new FormatError('GS1 DataBar Expanded numeric digit is invalid');
+          position += 7;
+          raw += `${first}${second}`;
+          continue;
+        }
+      }
+      if (position + 4 <= payload.length) {
+        const value = read(4);
+        if (value === 0) {
+          if (position >= payload.length || allZero(position)) break;
+          mode = 'alpha';
+          continue;
+        }
+        if (value >= 1 && value <= 10) {
+          raw += `${value - 1}${GS1_SEPARATOR}`;
+          mode = 'numeric';
+          continue;
+        }
+      }
+      throw new FormatError('GS1 DataBar Expanded numeric block is invalid');
+    }
+
+    if (mode === 'alpha') {
+      if (position + 3 <= payload.length && bitsToValue(payload, position, 3) === 0) {
+        position += 3;
+        mode = 'numeric';
+        continue;
+      }
+      if (position + 5 > payload.length) {
+        if (allZero(position) || isPaddingTail(position)) break;
+        throw new FormatError('GS1 DataBar Expanded alphanumeric block is truncated');
+      }
+      const five = bitsToValue(payload, position, 5);
+      if (five === 4) {
+        position += 5;
+        mode = 'iso646';
+        continue;
+      }
+      if (five >= 5 && five <= 15) {
+        position += 5;
+        if (five === 15) { raw += GS1_SEPARATOR; mode = 'numeric'; }
+        else raw += String(five - 5);
+        continue;
+      }
+      if (position + 6 > payload.length) throw new FormatError('GS1 DataBar Expanded alphanumeric character is truncated');
+      const six = read(6);
+      if (six >= 32 && six <= 57) raw += String.fromCharCode(six + 33);
+      else if (six === 58) raw += '*';
+      else if (six >= 59 && six <= 62) raw += String.fromCharCode(six - 15);
+      else throw new FormatError('GS1 DataBar Expanded alphanumeric character is invalid');
+      continue;
+    }
+
+    if (position + 3 <= payload.length && bitsToValue(payload, position, 3) === 0) {
+      position += 3;
+      mode = 'numeric';
+      continue;
+    }
+    if (position + 5 > payload.length) {
+      if (allZero(position) || isPaddingTail(position)) break;
+      throw new FormatError('GS1 DataBar Expanded ISO/IEC 646 block is truncated');
+    }
+    const five = bitsToValue(payload, position, 5);
+    if (five === 4) {
+      position += 5;
+      mode = 'alpha';
+      continue;
+    }
+    if (five >= 5 && five <= 15) {
+      position += 5;
+      if (five === 15) { raw += GS1_SEPARATOR; mode = 'numeric'; }
+      else raw += String(five - 5);
+      continue;
+    }
+    if (position + 7 <= payload.length) {
+      const seven = read(7);
+      if (seven >= 64 && seven <= 89) raw += String.fromCharCode(seven + 1);
+      else if (seven >= 90 && seven <= 115) raw += String.fromCharCode(seven + 7);
+      else {
+        if (position < 7) throw new FormatError('GS1 DataBar Expanded ISO/IEC 646 character is invalid');
+        position -= 7;
+        const eight = read(8);
+        const entry = [...ISO646_VALUES.entries()].find(([, encoded]) => encoded === eight);
+        if (!entry) throw new FormatError('GS1 DataBar Expanded ISO/IEC 646 character is invalid');
+        raw += entry[0];
+      }
+      continue;
+    }
+    throw new FormatError('GS1 DataBar Expanded ISO/IEC 646 block is truncated');
+  }
+  if (guard >= payload.length + 4) throw new FormatError('GS1 DataBar Expanded general-purpose field did not terminate');
+  return raw;
+}
+
+function gtinCheckDigit(value) {
+  let sum = 0;
+  for (let index = value.length - 1; index >= 0; index--) {
+    sum += Number(value[index]) * ((value.length - index) % 2 === 1 ? 3 : 1);
+  }
+  return String((10 - (sum % 10)) % 10);
+}
+
+function decodeMethodOne(bits, dataCharacters) {
+  if (bits.length < 48) throw new FormatError('GS1 DataBar Expanded method 1 information is truncated');
+  const symbolCharacters = dataCharacters + 1;
+  const expectedVlf = [symbolCharacters % 2 === 1, symbolCharacters > 14];
+  if (bits[2] !== expectedVlf[0] || bits[3] !== expectedVlf[1]) {
+    throw new FormatError('GS1 DataBar Expanded method 1 variable-length field is invalid');
+  }
+  const chunks = [bitsToValue(bits, 4, 4)];
+  for (let offset = 8; offset < 48; offset += 10) chunks.push(bitsToValue(bits, offset, 10));
+  if (chunks[0] > 9 || chunks.slice(1).some((value) => value > 999)) {
+    throw new FormatError('GS1 DataBar Expanded method 1 GTIN is invalid');
+  }
+  const gtinWithoutCheck = `${chunks[0]}${chunks.slice(1).map((value) => String(value).padStart(3, '0')).join('')}`;
+  const general = bits.length === 48 ? '' : decodeGeneralPurpose(bits.slice(48));
+  return `01${gtinWithoutCheck}${gtinCheckDigit(gtinWithoutCheck)}${general}`;
+}
+
+function decodeInformation(values, linkage, dataCharacters) {
+  const bits = [];
+  for (const value of values) appendBits(bits, value, 12);
+  if (bits.length < 5 || bits[0] !== linkage) {
+    throw new FormatError('GS1 DataBar Expanded information header is invalid');
+  }
+  let raw;
+  if (!bits[1] && !bits[2]) {
+    raw = decodeGeneralPurpose(bits.slice(5));
+  } else if (bits[1]) {
+    raw = decodeMethodOne(bits, dataCharacters);
+  } else {
+    throw new FormatError('GS1 DataBar Expanded information header is invalid');
+  }
+  const elements = decodeGS1ElementString(raw);
+  return Object.freeze({ raw, elements });
+}
+
+/** Decode a clean or integer-scaled GS1 DataBar Expanded matrix. */
+export function decodeDataBarExpanded(matrix) {
+  const geometry = logicalRow(matrix);
+  const decoded = decodePhysical(geometry.row, geometry.dataCharacters);
+  const linkage = (decoded.values[1] & 0x800) !== 0;
+  const information = decodeInformation(decoded.values.slice(1), linkage, decoded.dataCharacters);
+  return Object.freeze({
+    format: 'databar-expanded',
+    variant: 'expanded',
+    text: information.raw,
+    raw: information.raw,
+    gs1: true,
+    linkage,
+    checksum: decoded.values[0],
+    checksumValid: true,
+    dataCharacters: decoded.dataCharacters,
+    pairs: decoded.pairCount,
+    moduleScale: geometry.scale,
+    height: matrix.height,
+    symbologyIdentifier: ']e0',
+    elements: information.elements,
+  });
+}
+
+function crop(source, box) {
+  const output = new BitMatrix(box.width, box.height);
+  for (let y = 0; y < box.height; y++) {
+    for (let x = 0; x < box.width; x++) if (source.get(box.x + x, box.y + y)) output.set(x, y);
+  }
+  return output;
+}
+
+function rotateClockwise(source) {
+  const output = 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)) output.set(source.height - 1 - y, x);
+  }
+  return output;
+}
+
+function mapPoint(point, previous) {
+  return { x: point.y, y: previous.height - point.x };
+}
+
+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 canonicalCorners(points) {
+  const ordered = [...points].sort((left, right) => left.y - right.y || left.x - right.x);
+  const [topLeft, topRight] = ordered.slice(0, 2).sort((left, right) => left.x - right.x);
+  const [bottomLeft, bottomRight] = ordered.slice(2).sort((left, right) => left.x - right.x);
+  return [topLeft, topRight, bottomRight, bottomLeft];
+}
+
+function validImage(image) {
+  return isRecord(image) && typeof image.get === 'function'
+    && Number.isSafeInteger(image.width) && Number.isSafeInteger(image.height)
+    && image.width > 0 && image.height > 0
+    && image.width <= MAX_DIMENSION && image.height <= MAX_DIMENSION
+    && image.width * image.height <= MAX_MODULES;
+}
+
+/** Detect one complete, dark-on-light Expanded symbol in a clean raster. */
+export function detectDataBarExpanded(binaryImage, options = {}) {
+  if (!validImage(binaryImage) || !isRecord(options)) 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 && bounds.width > 0 && bounds.height > 0) {
+      const candidate = crop(oriented, bounds);
+      try {
+        const result = decodeDataBarExpanded(candidate);
+        const geometry = createDetectionCandidate({
+          corners: canonicalCorners(cornersFor(bounds).map((point) => toOriginal(point))),
+          moduleSize: result.moduleScale,
+          rotation: rotation * 90,
+          matrix: candidate,
+          confidence: 1,
+        }, {
+          result,
+          quality: {
+            quietZone: bounds.x > 0 && bounds.y > 0
+              && bounds.x + bounds.width < oriented.width
+              && bounds.y + bounds.height < oriented.height,
+            checksum: true,
+            rows: 1,
+            consistency: 1,
+          },
+          score: 1,
+        });
+        return Object.freeze({ ...result, ...geometry });
+      } catch {
+        /* A complete dark component belonging to another symbol is ignored. */
+      }
+    }
+    const previous = oriented;
+    const previousToOriginal = toOriginal;
+    oriented = rotateClockwise(previous);
+    toOriginal = (point) => previousToOriginal(mapPoint(point, previous));
+  }
+  return null;
+}
+
+/** Detect-and-decode alias matching the other DataBar modules. */
+export const detectAndDecodeDataBarExpanded = detectDataBarExpanded;
+
+/** Decode one complete, unscaled binary scanline. */
+export function decodeDataBarExpandedScanline(row) {
+  if (!row || typeof row.length !== 'number' || row.length < 1) return null;
+  const matrix = new BitMatrix(row.length, MIN_HEIGHT_MODULES);
+  for (let x = 0; x < row.length; x++) if (row[x]) matrix.setRegion(x, 0, 1, MIN_HEIGHT_MODULES);
+  try {
+    return decodeDataBarExpanded(matrix);
+  } catch {
+    return null;
+  }
+}
+
+export const encodeGS1DataBarExpanded = encodeDataBarExpanded;
+export const decodeGS1DataBarExpanded = decodeDataBarExpanded;
+export const detectGS1DataBarExpanded = detectDataBarExpanded;
+export const detectAndDecodeGS1DataBarExpanded = detectAndDecodeDataBarExpanded;