@sythos/js_barcode_universal 1.5.8 → 1.5.10

package/src/js/rmqr/tables.js

@@ -27,128 +27,151 @@
  *
  * Original work. No code from any other barcode implementation.
  */
-
 import { BitMatrix } from '../core/bit-matrix.js';
-
 /** The 32 rMQR dimensions in ISO/IEC 23941 order (width, height). */
 export const RMQR_SIZES = Object.freeze([
-  [43, 7], [59, 7], [77, 7], [99, 7], [139, 7],
-  [43, 9], [59, 9], [77, 9], [99, 9], [139, 9],
-  [27, 11], [43, 11], [59, 11], [77, 11], [99, 11], [139, 11],
-  [27, 13], [43, 13], [59, 13], [77, 13], [99, 13], [139, 13],
-  [43, 15], [59, 15], [77, 15], [99, 15], [139, 15],
-  [43, 17], [59, 17], [77, 17], [99, 17], [139, 17],
+    [43, 7], [59, 7], [77, 7], [99, 7], [139, 7],
+    [43, 9], [59, 9], [77, 9], [99, 9], [139, 9],
+    [27, 11], [43, 11], [59, 11], [77, 11], [99, 11], [139, 11],
+    [27, 13], [43, 13], [59, 13], [77, 13], [99, 13], [139, 13],
+    [43, 15], [59, 15], [77, 15], [99, 15], [139, 15],
+    [43, 17], [59, 17], [77, 17], [99, 17], [139, 17],
 ]);
-
 const REMAINDER_BITS = Object.freeze([0, 3, 5, 6, 1, 2, 3, 1, 4, 5, 2, 1, 0, 2, 7, 6, 4, 1, 6, 4, 3, 0, 1, 4, 6, 7, 2, 1, 2, 0, 3, 4]);
 const TOTAL_CODEWORDS = Object.freeze([13, 21, 32, 44, 68, 21, 33, 49, 66, 99, 15, 31, 47, 67, 89, 132, 21, 41, 60, 85, 113, 166, 51, 74, 103, 136, 199, 61, 88, 122, 160, 232]);
-
 // Each block is [number of blocks, total codewords per block, data codewords per block].
 const M_BLOCKS = [
-  [[1, 13, 6]], [[1, 21, 12]], [[1, 32, 20]], [[1, 44, 28]], [[1, 68, 44]],
-  [[1, 21, 12]], [[1, 33, 21]], [[1, 49, 31]], [[1, 66, 42]], [[1, 49, 31], [1, 50, 32]],
-  [[1, 15, 7]], [[1, 31, 19]], [[1, 47, 31]], [[1, 67, 43]], [[1, 44, 28], [1, 45, 29]], [[2, 66, 42]],
-  [[1, 21, 14]], [[1, 41, 27]], [[1, 60, 38]], [[1, 42, 26], [1, 43, 27]], [[1, 56, 36], [1, 57, 37]], [[2, 55, 35], [1, 56, 36]],
-  [[1, 51, 33]], [[1, 74, 48]], [[1, 51, 33], [1, 52, 34]], [[2, 68, 44]], [[2, 66, 42], [1, 67, 43]],
-  [[1, 60, 39]], [[2, 44, 28]], [[2, 61, 39]], [[2, 53, 33], [1, 54, 34]], [[4, 58, 38]],
+    [[1, 13, 6]], [[1, 21, 12]], [[1, 32, 20]], [[1, 44, 28]], [[1, 68, 44]],
+    [[1, 21, 12]], [[1, 33, 21]], [[1, 49, 31]], [[1, 66, 42]], [[1, 49, 31], [1, 50, 32]],
+    [[1, 15, 7]], [[1, 31, 19]], [[1, 47, 31]], [[1, 67, 43]], [[1, 44, 28], [1, 45, 29]], [[2, 66, 42]],
+    [[1, 21, 14]], [[1, 41, 27]], [[1, 60, 38]], [[1, 42, 26], [1, 43, 27]], [[1, 56, 36], [1, 57, 37]], [[2, 55, 35], [1, 56, 36]],
+    [[1, 51, 33]], [[1, 74, 48]], [[1, 51, 33], [1, 52, 34]], [[2, 68, 44]], [[2, 66, 42], [1, 67, 43]],
+    [[1, 60, 39]], [[2, 44, 28]], [[2, 61, 39]], [[2, 53, 33], [1, 54, 34]], [[4, 58, 38]],
 ];
 const H_BLOCKS = [
-  [[1, 13, 3]], [[1, 21, 7]], [[1, 32, 10]], [[1, 44, 14]], [[2, 34, 12]],
-  [[1, 21, 7]], [[1, 33, 11]], [[1, 24, 8], [1, 25, 9]], [[2, 33, 11]], [[3, 33, 11]],
-  [[1, 15, 5]], [[1, 31, 11]], [[1, 23, 7], [1, 24, 8]], [[1, 33, 11], [1, 34, 12]], [[1, 44, 14], [1, 45, 15]], [[3, 44, 14]],
-  [[1, 21, 7]], [[1, 41, 13]], [[2, 30, 10]], [[1, 42, 14], [1, 43, 15]], [[1, 37, 11], [2, 38, 12]], [[2, 41, 13], [2, 42, 14]],
-  [[1, 25, 7], [1, 26, 8]], [[2, 37, 13]], [[2, 34, 10], [1, 35, 11]], [[4, 34, 12]], [[1, 39, 13], [4, 40, 14]],
-  [[1, 30, 10], [1, 31, 11]], [[2, 44, 14]], [[1, 40, 12], [2, 41, 13]], [[4, 40, 14]], [[2, 38, 12], [4, 39, 13]],
+    [[1, 13, 3]], [[1, 21, 7]], [[1, 32, 10]], [[1, 44, 14]], [[2, 34, 12]],
+    [[1, 21, 7]], [[1, 33, 11]], [[1, 24, 8], [1, 25, 9]], [[2, 33, 11]], [[3, 33, 11]],
+    [[1, 15, 5]], [[1, 31, 11]], [[1, 23, 7], [1, 24, 8]], [[1, 33, 11], [1, 34, 12]], [[1, 44, 14], [1, 45, 15]], [[3, 44, 14]],
+    [[1, 21, 7]], [[1, 41, 13]], [[2, 30, 10]], [[1, 42, 14], [1, 43, 15]], [[1, 37, 11], [2, 38, 12]], [[2, 41, 13], [2, 42, 14]],
+    [[1, 25, 7], [1, 26, 8]], [[2, 37, 13]], [[2, 34, 10], [1, 35, 11]], [[4, 34, 12]], [[1, 39, 13], [4, 40, 14]],
+    [[1, 30, 10], [1, 31, 11]], [[2, 44, 14]], [[1, 40, 12], [2, 41, 13]], [[4, 40, 14]], [[2, 38, 12], [4, 39, 13]],
 ];
-
 const COUNT_BITS = Object.freeze({
-  numeric: [4, 5, 6, 7, 7, 5, 6, 7, 7, 8, 4, 6, 7, 7, 8, 8, 5, 6, 7, 7, 8, 8, 7, 7, 8, 8, 9, 7, 8, 8, 8, 9],
-  alphanumeric: [3, 5, 5, 6, 6, 5, 5, 6, 6, 7, 4, 5, 6, 6, 7, 7, 5, 6, 6, 7, 7, 8, 6, 7, 7, 7, 8, 6, 7, 7, 8, 8],
-  byte: [3, 4, 5, 5, 6, 4, 5, 5, 6, 6, 3, 5, 5, 6, 6, 7, 4, 6, 6, 7, 7, 7, 6, 6, 7, 7, 7, 6, 6, 7, 7, 8],
-  kanji: [2, 3, 4, 5, 5, 3, 4, 5, 5, 6, 2, 4, 5, 5, 6, 6, 3, 5, 5, 6, 6, 7, 5, 5, 6, 6, 7, 5, 6, 6, 6, 7],
+    numeric: [4, 5, 6, 7, 7, 5, 6, 7, 7, 8, 4, 6, 7, 7, 8, 8, 5, 6, 7, 7, 8, 8, 7, 7, 8, 8, 9, 7, 8, 8, 8, 9],
+    alphanumeric: [3, 5, 5, 6, 6, 5, 5, 6, 6, 7, 4, 5, 6, 6, 7, 7, 5, 6, 6, 7, 7, 8, 6, 7, 7, 7, 8, 6, 7, 7, 8, 8],
+    byte: [3, 4, 5, 5, 6, 4, 5, 5, 6, 6, 3, 5, 5, 6, 6, 7, 4, 6, 6, 7, 7, 7, 6, 6, 7, 7, 7, 6, 6, 7, 7, 8],
+    kanji: [2, 3, 4, 5, 5, 3, 4, 5, 5, 6, 2, 4, 5, 5, 6, 6, 3, 5, 5, 6, 6, 7, 5, 5, 6, 6, 7, 5, 6, 6, 6, 7],
 });
-
 const ALIGNMENT_BY_WIDTH = Object.freeze({ 27: [], 43: [21], 59: [19, 39], 77: [25, 51], 99: [23, 49, 75], 139: [27, 55, 83, 111] });
-
 /** @param {number} version */
 export function versionInfo(version) {
-  if (!Number.isInteger(version) || version < 1 || version > 32) throw new RangeError(`rMQR: version must be 1-32, got ${version}`);
-  const [width, height] = RMQR_SIZES[version - 1];
-  const blockTable = (ecc) => ecc === 'M' ? M_BLOCKS[version - 1] : H_BLOCKS[version - 1];
-  const blockLayout = (ecc) => {
-    if (ecc !== 'M' && ecc !== 'H') throw new RangeError(`rMQR: ECC must be M or H, got ${ecc}`);
-    const blocks = [];
-    for (const [count, total, data] of blockTable(ecc)) for (let i = 0; i < count; i++) blocks.push({ total, data, ecc: total - data });
-    return { blocks, totalCodewords: TOTAL_CODEWORDS[version - 1], totalDataCodewords: blocks.reduce((n, b) => n + b.data, 0), eccCodewords: blocks.reduce((n, b) => n + b.ecc, 0) };
-  };
-  return Object.freeze({ version, width, height, name: `R${height}x${width}`, indicator: version - 1, remainderBits: REMAINDER_BITS[version - 1], totalCodewords: TOTAL_CODEWORDS[version - 1], countBits(mode) { return COUNT_BITS[mode]?.[version - 1] ?? 0; }, blockLayout });
+    if (!Number.isInteger(version) || version < 1 || version > 32)
+        throw new RangeError(`rMQR: version must be 1-32, got ${version}`);
+    const [width, height] = RMQR_SIZES[version - 1];
+    const blockTable = (ecc) => ecc === 'M' ? M_BLOCKS[version - 1] : H_BLOCKS[version - 1];
+    const blockLayout = (ecc) => {
+        if (ecc !== 'M' && ecc !== 'H')
+            throw new RangeError(`rMQR: ECC must be M or H, got ${ecc}`);
+        const blocks = [];
+        for (const [count, total, data] of blockTable(ecc))
+            for (let i = 0; i < count; i++)
+                blocks.push({ total, data, ecc: total - data });
+        return { blocks, totalCodewords: TOTAL_CODEWORDS[version - 1], totalDataCodewords: blocks.reduce((n, b) => n + b.data, 0), eccCodewords: blocks.reduce((n, b) => n + b.ecc, 0) };
+    };
+    return Object.freeze({ version, width, height, name: `R${height}x${width}`, indicator: version - 1, remainderBits: REMAINDER_BITS[version - 1], totalCodewords: TOTAL_CODEWORDS[version - 1], countBits(mode) { return COUNT_BITS[mode]?.[version - 1] ?? 0; }, blockLayout });
 }
-
 /** @param {number} width @param {number} height */
 export function versionForSize(width, height) {
-  const i = RMQR_SIZES.findIndex(([w, h]) => w === width && h === height);
-  return i < 0 ? null : versionInfo(i + 1);
+    const i = RMQR_SIZES.findIndex(([w, h]) => w === width && h === height);
+    return i < 0 ? null : versionInfo(i + 1);
 }
-
 /** @param {number} version */
 export function alignmentCoordinates(version) { return ALIGNMENT_BY_WIDTH[versionInfo(version).width] || []; }
-
 function bchRemainder(value) {
-  const generator = 0x1f25;
-  let v = value << 12;
-  while (v !== 0 && v.toString(2).length >= 13) v ^= generator << (v.toString(2).length - 13);
-  return v;
+    const generator = 0x1f25;
+    let v = value << 12;
+    while (v !== 0 && v.toString(2).length >= 13)
+        v ^= generator << (v.toString(2).length - 13);
+    return v;
 }
-
 /** Unmasked 18-bit format sequence: 5-bit version indicator plus ECC bit. */
 export function formatBits(version, ecc) {
-  const v = versionInfo(version);
-  if (ecc !== 'M' && ecc !== 'H') throw new RangeError(`rMQR: ECC must be M or H, got ${ecc}`);
-  const data = v.indicator | (ecc === 'H' ? 1 << 5 : 0);
-  return (data << 12) | bchRemainder(data);
+    const v = versionInfo(version);
+    if (ecc !== 'M' && ecc !== 'H')
+        throw new RangeError(`rMQR: ECC must be M or H, got ${ecc}`);
+    const data = v.indicator | (ecc === 'H' ? 1 << 5 : 0);
+    return (data << 12) | bchRemainder(data);
 }
-
 export const FORMAT_MASK_FINDER = 0b011111101010110010;
 export const FORMAT_MASK_SUB = 0b100000101001111011;
-
 /** rMQR has one fixed mask: floor(y/2)+floor(x/3) even. */
 export function maskBit(x, y) { return (Math.floor(y / 2) + Math.floor(x / 3)) % 2 === 0; }
-
 /** Function modules; set bits are non-data cells. */
 export function functionModules(version) {
-  const v = versionInfo(version); const m = new BitMatrix(v.width, v.height); const { width: w, height: h } = v;
-  m.setRegion(0, 0, w, 1); m.setRegion(0, h - 1, w, 1); m.setRegion(0, 1, 1, h - 2); m.setRegion(w - 1, 1, 1, h - 2);
-  for (const cx of alignmentCoordinates(version)) { m.setRegion(cx - 1, 1, 3, 2); m.setRegion(cx - 1, h - 3, 3, 2); m.setRegion(cx, 3, 1, h - 6); }
-  m.setRegion(1, 1, 7, h === 7 ? 5 : 7); m.setRegion(8, 1, 3, 5); m.setRegion(11, 1, 1, 3);
-  m.setRegion(w - 5, h - 5, 4, 4); m.setRegion(w - 8, h - 6, 3, 5); m.setRegion(w - 5, h - 6, 3, 1);
-  m.set(w - 2, 1); if (h > 9) m.set(1, h - 2);
-  return m;
+    const v = versionInfo(version);
+    const m = new BitMatrix(v.width, v.height);
+    const { width: w, height: h } = v;
+    m.setRegion(0, 0, w, 1);
+    m.setRegion(0, h - 1, w, 1);
+    m.setRegion(0, 1, 1, h - 2);
+    m.setRegion(w - 1, 1, 1, h - 2);
+    for (const cx of alignmentCoordinates(version)) {
+        m.setRegion(cx - 1, 1, 3, 2);
+        m.setRegion(cx - 1, h - 3, 3, 2);
+        m.setRegion(cx, 3, 1, h - 6);
+    }
+    m.setRegion(1, 1, 7, h === 7 ? 5 : 7);
+    m.setRegion(8, 1, 3, 5);
+    m.setRegion(11, 1, 1, 3);
+    m.setRegion(w - 5, h - 5, 4, 4);
+    m.setRegion(w - 8, h - 6, 3, 5);
+    m.setRegion(w - 5, h - 6, 3, 1);
+    m.set(w - 2, 1);
+    if (h > 9)
+        m.set(1, h - 2);
+    return m;
 }
-
 /** Data coordinates in the standard right-to-left two-column traversal. */
 export function dataModuleOrder(version) {
-  const v = versionInfo(version); const fn = functionModules(version); const out = [];
-  let cx = v.width - 2, cy = v.height - 6, dy = -1;
-  // The data path starts beside the lower-right format area, then snakes
-  // through each pair of columns between the one-module outer border.
-  while (cx > 0) {
-    for (const xx of [cx, cx - 1]) if (!fn.get(xx, cy)) out.push([xx, cy]);
-    if (dy < 0 && cy === 1) { cx -= 2; dy = 1; }
-    else if (dy > 0 && cy === v.height - 2) { cx -= 2; dy = -1; }
-    else cy += dy;
-  }
-  return out;
+    const v = versionInfo(version);
+    const fn = functionModules(version);
+    const out = [];
+    let cx = v.width - 2, cy = v.height - 6, dy = -1;
+    // The data path starts beside the lower-right format area, then snakes
+    // through each pair of columns between the one-module outer border.
+    while (cx > 0) {
+        for (const xx of [cx, cx - 1])
+            if (!fn.get(xx, cy))
+                out.push([xx, cy]);
+        if (dy < 0 && cy === 1) {
+            cx -= 2;
+            dy = 1;
+        }
+        else if (dy > 0 && cy === v.height - 2) {
+            cx -= 2;
+            dy = -1;
+        }
+        else
+            cy += dy;
+    }
+    return out;
 }
-
 export function dataBitCapacity(version, ecc) { const b = versionInfo(version).blockLayout(ecc); return b.totalDataCodewords * 8; }
-
 export function validateTables() {
-  const problems = [];
-  if (RMQR_SIZES.length !== 32) problems.push(`expected 32 sizes, got ${RMQR_SIZES.length}`);
-  for (let i = 1; i <= 32; i++) {
-    const v = versionInfo(i); const order = dataModuleOrder(i); const expected = v.totalCodewords * 8 + v.remainderBits;
-    if (order.length !== expected) problems.push(`${v.name}: data modules ${order.length}, expected ${expected}`);
-    for (const ecc of ['M', 'H']) { const b = v.blockLayout(ecc); if (b.totalCodewords !== v.totalCodewords) problems.push(`${v.name}-${ecc}: block total mismatch`); }
-  }
-  return problems;
+    const problems = [];
+    if (RMQR_SIZES.length !== 32)
+        problems.push(`expected 32 sizes, got ${RMQR_SIZES.length}`);
+    for (let i = 1; i <= 32; i++) {
+        const v = versionInfo(i);
+        const order = dataModuleOrder(i);
+        const expected = v.totalCodewords * 8 + v.remainderBits;
+        if (order.length !== expected)
+            problems.push(`${v.name}: data modules ${order.length}, expected ${expected}`);
+        for (const ecc of ['M', 'H']) {
+            const b = v.blockLayout(ecc);
+            if (b.totalCodewords !== v.totalCodewords)
+                problems.push(`${v.name}-${ecc}: block total mismatch`);
+        }
+    }
+    return problems;
 }

package/src/ts/aztec/decoder.ts

@@ -0,0 +1,317 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Decoder for a sampled Aztec symbol.
+ *
+ * This module deliberately accepts only a square, module-aligned BitMatrix.
+ * Locating a bull's-eye in a photograph and perspective sampling are detector
+ * concerns. Keeping the two stages apart makes all bit order and ECC rules
+ * testable without image-processing noise.
+ *
+ * Contract with tables.js:
+ *   - aztecSymbolForLayers(compact, layers) returns the nominal symbol data;
+ *   - aztecWordSizeForLayers(layers) returns 6, 8, 10 or 12;
+ *   - aztecFieldForLayers(layers) returns the matching binary Galois field;
+ *   - aztecMatrixSize(compact, layers) returns the rendered square size.
+ *
+ * @module aztec/decoder
+ */
+
+import { FormatError } from '../core/errors.js';
+import { rsDecode } from '../core/reed-solomon.js';
+import {
+  aztecLayer as aztecSymbolForLayers,
+  wordSizeForLayers as aztecWordSizeForLayers,
+  fieldForLayers as aztecFieldForLayers,
+  fieldForWordSize,
+  aztecSymbolSize as aztecMatrixSize,
+} from './tables.js';
+
+const UPPER = ['CTRL_PS', ' ', ...'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'CTRL_LL', 'CTRL_ML', 'CTRL_DL', 'CTRL_BS'];
+const LOWER = ['CTRL_PS', ' ', ...'abcdefghijklmnopqrstuvwxyz', 'CTRL_US', 'CTRL_ML', 'CTRL_DL', 'CTRL_BS'];
+const MIXED = [
+  'CTRL_PS', ' ', '\x01', '\x02', '\x03', '\x04', '\x05', '\x06', '\x07', '\b', '\t', '\n', '\x0b', '\f', '\r', '\x1b',
+  '\x1c', '\x1d', '\x1e', '\x1f', '@', '\\', '^', '_', '`', '|', '~', '\x7f', 'CTRL_LL', 'CTRL_UL', 'CTRL_PL', 'CTRL_BS',
+];
+const PUNCT = ['FLG(n)', '\r', '\r\n', '. ', ', ', ': ', '!', '"', '#', '$', '%', '&', "'", '(', ')', '*', '+', ',', '-', '.', '/', ':', ';', '<', '=', '>', '?', '[', ']', '{', '}', 'CTRL_UL'];
+const DIGIT = ['CTRL_PS', ' ', ...'0123456789', ',', '.', 'CTRL_UL'];
+const TABLES = { UPPER, LOWER, MIXED, PUNCT, DIGIT };
+
+/** @param {boolean[]} bits @param {number} offset @param {number} count */
+function readBits(bits, offset, count) {
+  if (offset + count > bits.length) throw new FormatError('Aztec: truncated high-level stream');
+  let value = 0;
+  for (let i = 0; i < count; i++) value = (value << 1) | (bits[offset + i] ? 1 : 0);
+  return value;
+}
+
+/** @param {number} value @param {number} count @param {boolean[]} out */
+function appendBits(value, count, out) {
+  for (let i = count - 1; i >= 0; i--) out.push(((value >>> i) & 1) !== 0);
+}
+
+/**
+ * Decode an Aztec high-level bit stream to its exact byte payload.
+ *
+ * Text tables contribute their ISO-8859-1 byte values; Binary Shift appends
+ * raw bytes. ECI markers are consumed but intentionally not emitted: callers
+ * receive the transported byte payload and may select their own charset.
+ *
+ * @param {boolean[]} bits
+ * @returns {Uint8Array}
+ */
+export function decodeHighLevelBits(bits) {
+  const output = [];
+  let latch = 'UPPER';
+  let shift = 'UPPER';
+  let offset = 0;
+
+  while (offset < bits.length) {
+    if (shift === 'BINARY') {
+      if (offset + 5 > bits.length) break; // legal trailing pad
+      let length = readBits(bits, offset, 5);
+      offset += 5;
+      if (length === 0) {
+        if (offset + 11 > bits.length) throw new FormatError('Aztec: truncated Binary Shift length');
+        length = readBits(bits, offset, 11) + 31;
+        offset += 11;
+      }
+      if (offset + length * 8 > bits.length) throw new FormatError('Aztec: truncated Binary Shift data');
+      for (let i = 0; i < length; i++) {
+        output.push(readBits(bits, offset, 8));
+        offset += 8;
+      }
+      shift = latch;
+      continue;
+    }
+
+    const size = shift === 'DIGIT' ? 4 : 5;
+    if (offset + size > bits.length) break; // trailing pad after unstuffing
+    const code = readBits(bits, offset, size);
+    offset += size;
+    const table = TABLES[shift];
+    const token = table[code];
+    if (token === undefined) throw new FormatError(`Aztec: invalid ${shift} code ${code}`);
+
+    if (token === 'FLG(n)') {
+      if (offset + 3 > bits.length) throw new FormatError('Aztec: truncated FLG(n)');
+      const count = readBits(bits, offset, 3);
+      offset += 3;
+      if (count === 0) output.push(0x1d); // FNC1 / GS
+      else if (count <= 6) {
+        // ECI assignment number, encoded as count decimal digits. It changes
+        // interpretation, not the wire bytes, so consume it without output.
+        for (let i = 0; i < count; i++) {
+          if (offset + 4 > bits.length) throw new FormatError('Aztec: truncated ECI');
+          const digit = readBits(bits, offset, 4);
+          offset += 4;
+          if (digit < 2 || digit > 11) throw new FormatError('Aztec: invalid ECI digit');
+        }
+      } else {
+        throw new FormatError(`Aztec: unsupported FLG(${count})`);
+      }
+      shift = latch;
+      continue;
+    }
+
+    if (token.startsWith('CTRL_')) {
+      const targetCode = token.slice(5, -1);
+      const latchMode = token.endsWith('L');
+      const target = ({ P: 'PUNCT', L: 'LOWER', M: 'MIXED', D: 'DIGIT', U: 'UPPER', B: 'BINARY' })[targetCode];
+      if (!target) throw new FormatError(`Aztec: invalid control ${token}`);
+      shift = target;
+      if (latchMode) latch = shift;
+      continue;
+    }
+
+    for (let i = 0; i < token.length; i++) output.push(token.charCodeAt(i));
+    shift = latch;
+  }
+  return Uint8Array.from(output);
+}
+
+/** @param {boolean} compact @param {number} layers */
+function alignmentMap(compact, layers) {
+  const baseSize = (compact ? 11 : 14) + layers * 4;
+  if (compact) return Array.from({ length: baseSize }, (_, i) => i);
+  const size = aztecMatrixSize(layers, false);
+  const map = new Array(baseSize);
+  const baseCenter = baseSize >> 1;
+  const center = size >> 1;
+  for (let i = 0; i < baseCenter; i++) {
+    const offset = i + Math.floor(i / 15);
+    map[baseCenter - i - 1] = center - offset - 1;
+    map[baseCenter + i] = center + offset + 1;
+  }
+  return map;
+}
+
+/**
+ * Read the four sides of the parameter message. The order mirrors the
+ * clockwise write order and is independent of the data spiral.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {boolean} compact
+ * @returns {boolean[]}
+ */
+function readModeBits(matrix, compact) {
+  const center = matrix.width >> 1;
+  const side = compact ? 7 : 10;
+  const offset = compact ? 5 : 7;
+  // Full symbols skip the reference grid line through the bull's-eye. This
+  // exact sequence is also used by drawModeMessage() in encoder.js.
+  const positions = Array.from(
+    { length: side },
+    (_, i) => compact ? center - 3 + i : center - 5 + i + Math.floor(i / 5),
+  );
+  const bits = [];
+  for (let i = 0; i < side; i++) bits.push(matrix.get(positions[i], center - offset));
+  for (let i = 0; i < side; i++) bits.push(matrix.get(center + offset, positions[i]));
+  for (let i = 0; i < side; i++) bits.push(matrix.get(positions[side - 1 - i], center + offset));
+  for (let i = 0; i < side; i++) bits.push(matrix.get(center - offset, positions[side - 1 - i]));
+  return bits;
+}
+
+/** @param {boolean[]} bits @param {boolean} compact */
+function decodeModeMessage(bits, compact) {
+  const total = compact ? 7 : 10;
+  const dataWords = compact ? 2 : 4;
+  const words = new Array(total);
+  for (let i = 0; i < total; i++) words[i] = readBits(bits, i * 4, 4);
+  const corrections = rsDecode(words, total - dataWords, fieldForWordSize(4), 1);
+  let data = 0;
+  for (let i = 0; i < dataWords; i++) data = (data << 4) | words[i];
+  const layers = compact ? (data >>> 6) + 1 : (data >>> 11) + 1;
+  const dataCodewords = compact ? (data & 0x3f) + 1 : (data & 0x7ff) + 1;
+  return { layers, dataCodewords, corrections };
+}
+
+/** @param {boolean} compact @param {number} layers */
+function totalBitsInLayers(compact, layers) {
+  return ((compact ? 88 : 112) + 16 * layers) * layers;
+}
+
+/**
+ * Extract raw, stuffed codeword bits in logical ring order.
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {boolean} compact @param {number} layers
+ * @returns {boolean[]}
+ */
+function extractBits(matrix, compact, layers) {
+  const baseSize = (compact ? 11 : 14) + layers * 4;
+  const map = alignmentMap(compact, layers);
+  const raw = new Array(totalBitsInLayers(compact, layers));
+  let offset = 0;
+  for (let layer = 0; layer < layers; layer++) {
+    const rowSize = (layers - layer) * 4 + (compact ? 9 : 12);
+    for (let j = 0; j < rowSize; j++) {
+      const col = j * 2;
+      for (let k = 0; k < 2; k++) {
+        raw[offset + col + k] = matrix.get(map[layer * 2 + k], map[layer * 2 + j]);
+        raw[offset + rowSize * 2 + col + k] = matrix.get(map[layer * 2 + j], map[baseSize - 1 - layer * 2 - k]);
+        raw[offset + rowSize * 4 + col + k] = matrix.get(map[baseSize - 1 - layer * 2 - k], map[baseSize - 1 - layer * 2 - j]);
+        raw[offset + rowSize * 6 + col + k] = matrix.get(map[baseSize - 1 - layer * 2 - j], map[layer * 2 + k]);
+      }
+    }
+    offset += rowSize * 8;
+  }
+  return raw;
+}
+
+/** @param {boolean[]} raw @param {number} layers @param {number} dataCodewords */
+function correctAndUnstuff(raw, layers, dataCodewords) {
+  const wordSize = aztecWordSizeForLayers(layers);
+  const totalWords = Math.floor(raw.length / wordSize);
+  if (dataCodewords <= 0 || dataCodewords > totalWords) throw new FormatError('Aztec: invalid data word count');
+  const start = raw.length % wordSize;
+  const words = new Array(totalWords);
+  for (let i = 0; i < totalWords; i++) words[i] = readBits(raw, start + i * wordSize, wordSize);
+  const corrections = rsDecode(words, totalWords - dataCodewords, aztecFieldForLayers(layers), 1);
+  const mask = (1 << wordSize) - 1;
+  const corrected = [];
+  for (let i = 0; i < dataCodewords; i++) {
+    const word = words[i];
+    if (word === 0 || word === mask) throw new FormatError('Aztec: invalid stuffed codeword');
+    if (word === 1 || word === mask - 1) {
+      for (let j = 0; j < wordSize - 1; j++) corrected.push(word === mask - 1);
+    } else {
+      appendBits(word, wordSize, corrected);
+    }
+  }
+  return { bits: corrected, corrections };
+}
+
+/** @param {Uint8Array} bytes */
+function bytesToText(bytes) {
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+  catch { return new TextDecoder('latin1').decode(bytes); }
+}
+
+/**
+ * Decode a square Aztec symbol with one bit per module and no quiet zone.
+ * The matrix must already be oriented with the mode message at the top.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @returns {{text: string, bytes: Uint8Array, compact: boolean, layers: number, corrections: number, eccPercent: number}}
+ */
+export function decodeAztec(matrix) {
+  if (!matrix || matrix.width !== matrix.height) throw new FormatError('Aztec: expected a square BitMatrix');
+  let compact;
+  let mode;
+  // Compact and full dimensions are disjoint; trying both also makes malformed
+  // candidate handling deterministic for the future image detector.
+  for (const candidate of [true, false]) {
+    try {
+      const value = decodeModeMessage(readModeBits(matrix, candidate), candidate);
+      if (value.layers < 1 || value.layers > (candidate ? 4 : 32)) continue;
+      if (aztecMatrixSize(value.layers, candidate) !== matrix.width) continue;
+      compact = candidate;
+      mode = value;
+      break;
+    } catch { /* Try the other family. */ }
+  }
+  if (compact === undefined || !mode) throw new FormatError('Aztec: invalid mode message or dimensions');
+  // Ensure the declared layer data agrees with the table module, so a future
+  // tables refactor cannot silently make decoder capacity calculations stale.
+  aztecSymbolForLayers(mode.layers, compact);
+  const raw = extractBits(matrix, compact, mode.layers);
+  const payload = correctAndUnstuff(raw, mode.layers, mode.dataCodewords);
+  const bytes = decodeHighLevelBits(payload.bits);
+  const totalWords = Math.floor(raw.length / aztecWordSizeForLayers(mode.layers));
+  return {
+    text: bytesToText(bytes),
+    bytes,
+    compact,
+    layers: mode.layers,
+    corrections: mode.corrections + payload.corrections,
+    eccPercent: Math.round(((totalWords - mode.dataCodewords) * 100) / totalWords),
+  };
+}