@sythos/js_barcode_universal 0.1.0 → 1.1.0

package/licenses/README.md

@@ -10,7 +10,9 @@ appendix carries the consolidated inventory these files expand on.
 
 | Format | File | `[TO VERIFY]` items |
 |---|---|---:|
+| Aztec Code | [`aztec-code.license`](aztec-code.license) | 7 |
 | QR Code | [`qr-code.license`](qr-code.license) | 5 |
+| Data Matrix ECC 200 | [`data-matrix.license`](data-matrix.license) | 9 |
 | EAN-13 | [`ean-13.license`](ean-13.license) | 5 |
 | EAN-8 | [`ean-8.license`](ean-8.license) | 5 |
 | UPC-A | [`upc-a.license`](upc-a.license) | 6 |

package/licenses/aztec-code.license

@@ -0,0 +1,74 @@
+Aztec Code — format provenance and usability
+==========================================================================
+
+This file records where the Aztec Code symbology comes from, what governs
+it, and the basis on which this project implements and redistributes it.
+
+It is an ENGINEERING INVENTORY, NOT LEGAL ADVICE. Items marked [TO VERIFY]
+have not been independently confirmed by the author.
+
+
+ORIGIN
+--------------------------------------------------------------------------
+
+Created by Andrew Longacre, Jr. of Welch Allyn in the 1990s. The exact
+attribution, ownership history and release terms have not been
+independently confirmed by the author. [TO VERIFY]
+
+
+SPECIFICATION
+--------------------------------------------------------------------------
+
+ISO/IEC 24778:2024 — Aztec Code bar code symbology specification.
+Published by ISO/IEC. The specification TEXT is copyrighted by its
+publisher and is paywalled; it is not reproduced here.
+
+Specification TEXT is copyrighted by its publisher. The SYMBOLOGY it
+describes is not — an encoding scheme is a system, not a work of
+authorship. This project implements the symbology; it does not reproduce,
+redistribute or excerpt any specification document.
+
+
+PATENT STATUS
+--------------------------------------------------------------------------
+
+The status of patents associated with Aztec Code, including any original
+rights-holder statements and their current effect, has not been
+independently confirmed by the author. [TO VERIFY]
+
+
+TRADEMARK
+--------------------------------------------------------------------------
+
+The current registration status and ownership of the words "Aztec Code"
+have not been independently established. [TO VERIFY] The name is used
+descriptively here and does not imply endorsement by any rights holder.
+
+A trademark does not restrict implementing a symbology. It restricts
+branding — how a product names and presents itself.
+
+
+IMPLEMENTATION BASIS IN THIS PROJECT
+--------------------------------------------------------------------------
+
+Aztec Code is implemented here from published descriptions of the format,
+which are systems and facts rather than works of authorship. No source
+code and no constant table from any other barcode implementation was used,
+consulted or copied, under any licence.
+
+
+CONCLUSION
+--------------------------------------------------------------------------
+
+This project's original implementation is distributed under the MIT
+License. The ISO/IEC reference establishes the technical standard; this
+engineering inventory does not claim to have resolved the patent or
+trademark entries that remain marked [TO VERIFY].
+
+References relied upon:
+  - ISO/IEC 24778:2024, ISO/IEC
+  - Aztec Code origin, patent position and trademark status [TO VERIFY]
+
+This is an engineering assessment, not legal advice. Items marked
+[TO VERIFY] have not been independently confirmed by the author. If your
+use is commercially sensitive, obtain your own legal review.

package/licenses/data-matrix.license

@@ -0,0 +1,82 @@
+Data Matrix ECC 200 — format provenance and usability
+==========================================================================
+
+This file records where the Data Matrix ECC 200 symbology comes from, what governs
+it, and the basis on which this project implements and redistributes it.
+
+It is an ENGINEERING INVENTORY, NOT LEGAL ADVICE. Items marked [TO VERIFY]
+have not been independently confirmed by the author.
+
+
+ORIGIN
+--------------------------------------------------------------------------
+
+Data Matrix emerged from industrial automatic-identification work
+associated with International Data Matrix and later RVSI/CI Matrix in the
+late 1980s and early 1990s. The exact corporate chronology and attribution
+have not been independently confirmed by the author. [TO VERIFY]
+
+
+SPECIFICATION
+--------------------------------------------------------------------------
+
+ISO/IEC 16022:2024 — Data Matrix bar code symbology specification.
+Published by ISO/IEC. The specification TEXT is copyrighted by its
+publisher and is paywalled; it is not reproduced here.
+GS1 General Specifications and the GS1 DataMatrix Guideline govern use
+of ECC 200 with a leading FNC1 and GS1 Application Identifiers.
+
+Specification TEXT is copyrighted by its publisher. The SYMBOLOGY it
+describes is not — an encoding scheme is a system, not a work of
+authorship. This project implements the symbology; it does not reproduce,
+redistribute or excerpt any specification document.
+
+
+PATENT STATUS
+--------------------------------------------------------------------------
+
+Patent rights associated with ECC 200 have been reported as released for
+public use by an earlier rights holder, but the original patents, chain of
+title and release terms have not been independently confirmed by the
+author. [TO VERIFY]
+
+
+TRADEMARK
+--------------------------------------------------------------------------
+
+The current registration status and ownership of the words "Data Matrix"
+have not been independently established. [TO VERIFY] "GS1" and "GS1
+DataMatrix" are GS1 designations; their use is descriptive here and does
+not imply endorsement. [TO VERIFY]
+
+A trademark does not restrict implementing a symbology. It restricts
+branding — how a product names and presents itself.
+
+
+IMPLEMENTATION BASIS IN THIS PROJECT
+--------------------------------------------------------------------------
+
+Data Matrix ECC 200 is implemented here from published descriptions of the format,
+which are systems and facts rather than works of authorship. No source
+code and no constant table from any other barcode implementation was used,
+consulted or copied, under any licence.
+
+
+CONCLUSION
+--------------------------------------------------------------------------
+
+This project's original implementation is distributed under the MIT
+License. The ISO/IEC and GS1 references establish the technical standards;
+this engineering inventory does not claim to have resolved the
+patent-release or trademark entries that remain marked [TO VERIFY].
+
+References relied upon:
+  - ISO/IEC 16022:2024, ISO/IEC
+  - GS1 General Specifications, GS1 AISBL
+  - GS1 DataMatrix Guideline, GS1 AISBL
+  - Reported ECC 200 patent-release position [TO VERIFY]
+  - Data Matrix trademark status and ownership [TO VERIFY]
+
+This is an engineering assessment, not legal advice. Items marked
+[TO VERIFY] have not been independently confirmed by the author. If your
+use is commercially sensitive, obtain your own legal review.

package/package.json

@@ -1,89 +1,95 @@
-{
-  "name": "@sythos/js_barcode_universal",
-  "version": "0.1.0",
-  "description": "Read and write barcodes in JavaScript. 100% original code, zero runtime dependencies. QR Code, EAN/UPC, ISBN, Code 128, Code 39, Code 93, ITF, Codabar, MSI, Code 11 and Pharmacode.",
-  "author": "Sythos",
-  "license": "MIT",
-  "type": "module",
-  "main": "./src/index.js",
-  "module": "./src/index.js",
-  "browser": "./bundle/sythos-barcode.js",
-  "unpkg": "./bundle/sythos-barcode.js",
-  "jsdelivr": "./bundle/sythos-barcode.js",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    ".": "./src/index.js",
-    "./core": "./src/core/index.js",
-    "./image": "./src/image/index.js",
-    "./oned": "./src/oned/index.js",
+{
+  "name": "@sythos/js_barcode_universal",
+  "version": "1.1.0",
+  "description": "Read and write barcodes in JavaScript. 100% original code, zero runtime dependencies. Aztec Code, Data Matrix ECC 200, QR Code, EAN/UPC, ISBN, Code 128, Code 39, Code 93, ITF, Codabar, MSI, Code 11 and Pharmacode.",
+  "author": "Sythos",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "browser": "./bundle/sythos-barcode.js",
+  "unpkg": "./bundle/sythos-barcode.js",
+  "jsdelivr": "./bundle/sythos-barcode.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core/index.js",
+    "./image": "./src/image/index.js",
+    "./oned": "./src/oned/index.js",
     "./qr": "./src/qr/index.js",
-    "./render": "./src/render/index.js",
-    "./render/svg": "./src/render/svg.js",
-    "./render/png": "./src/render/png.js",
-    "./render/image-data": "./src/render/image-data.js",
-    "./bundle": "./bundle/sythos-barcode.esm.js",
-    "./bundle/iife": "./bundle/sythos-barcode.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "src",
-    "bundle",
-    "examples",
-    "licenses",
-    "LICENSE",
-    "NOTICE.md",
-    "README.md"
-  ],
-  "keywords": [
-    "barcode",
-    "barcode-generator",
-    "barcode-scanner",
-    "qrcode",
-    "qr",
-    "qr-code",
-    "ean",
-    "ean13",
-    "ean8",
-    "upc",
-    "upca",
-    "upce",
-    "isbn",
-    "code128",
-    "gs1-128",
-    "code39",
-    "code93",
-    "itf",
-    "itf14",
-    "codabar",
-    "msi",
-    "code11",
-    "pharmacode",
-    "scanner",
-    "decoder",
-    "encoder",
-    "generator",
-    "reader",
-    "writer",
-    "zero-dependencies",
-    "no-dependencies",
-    "browser",
-    "nodejs",
-    "esm"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Sythos/JS_Barcode_Universal.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Sythos/JS_Barcode_Universal/issues"
-  },
-  "homepage": "https://github.com/Sythos/JS_Barcode_Universal#readme",
-  "dependencies": {},
-  "devDependencies": {}
-}
+    "./datamatrix": "./src/datamatrix/index.js",
+    "./aztec": "./src/aztec/index.js",
+    "./render": "./src/render/index.js",
+    "./render/svg": "./src/render/svg.js",
+    "./render/png": "./src/render/png.js",
+    "./render/image-data": "./src/render/image-data.js",
+    "./bundle": "./bundle/sythos-barcode.esm.js",
+    "./bundle/iife": "./bundle/sythos-barcode.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "bundle",
+    "examples",
+    "licenses",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md"
+  ],
+  "keywords": [
+    "barcode",
+    "datamatrix",
+    "ecc200",
+    "aztec",
+    "aztec-code",
+    "barcode-generator",
+    "barcode-scanner",
+    "qrcode",
+    "qr",
+    "qr-code",
+    "ean",
+    "ean13",
+    "ean8",
+    "upc",
+    "upca",
+    "upce",
+    "isbn",
+    "code128",
+    "gs1-128",
+    "code39",
+    "code93",
+    "itf",
+    "itf14",
+    "codabar",
+    "msi",
+    "code11",
+    "pharmacode",
+    "scanner",
+    "decoder",
+    "encoder",
+    "generator",
+    "reader",
+    "writer",
+    "zero-dependencies",
+    "no-dependencies",
+    "browser",
+    "nodejs",
+    "esm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sythos/JS_Barcode_Universal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sythos/JS_Barcode_Universal/issues"
+  },
+  "homepage": "https://github.com/Sythos/JS_Barcode_Universal#readme",
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/aztec/decoder.js

@@ -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),
+  };
+}