@sythos/js_barcode_universal 1.3.1 → 1.4.1

package/src/aztecrune/decoder.js

@@ -0,0 +1,156 @@
+/*!
+ * 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-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Aztec Rune decoder.
+ *
+ * The input is a square 11x11 module matrix. Structural modules are checked
+ * before the seven masked GF(16) codewords are Reed-Solomon corrected. The
+ * decoder tries the four in-plane quarter turns and both polarities, allowing
+ * it to consume an oriented sampled image while still rejecting ordinary
+ * Aztec/QR matrices.
+ *
+ * @module aztecrune/decoder
+ */
+
+import { FormatError } from '../core/errors.js';
+import { rsDecode } from '../core/reed-solomon.js';
+import {
+  AZTEC_RUNE_DATA_CODEWORDS,
+  AZTEC_RUNE_DATA_POSITIONS,
+  AZTEC_RUNE_ECC_CODEWORDS,
+  AZTEC_RUNE_MASK,
+  AZTEC_RUNE_SIZE,
+  aztecRuneField,
+  aztecRuneStructuralValue,
+} from './tables.js';
+
+/** @param {import('../core/bit-matrix.js').BitMatrix} source @param {number} turns */
+function rotateClockwise(source, turns) {
+  let current = source.clone();
+  for (let turn = 0; turn < turns; turn++) {
+    const out = new source.constructor(current.height, current.width);
+    for (let y = 0; y < current.height; y++) for (let x = 0; x < current.width; x++) {
+      if (current.get(x, y)) out.set(current.height - 1 - y, x);
+    }
+    current = out;
+  }
+  return current;
+}
+
+/** @param {import('../core/bit-matrix.js').BitMatrix} matrix */
+function invert(matrix) {
+  const out = matrix.clone();
+  for (let y = 0; y < out.height; y++) for (let x = 0; x < out.width; x++) out.flip(x, y);
+  return out;
+}
+
+/** @param {import('../core/bit-matrix.js').BitMatrix} matrix @param {boolean} inverted */
+function structureMatches(matrix, inverted) {
+  for (let y = 0; y < AZTEC_RUNE_SIZE; y++) for (let x = 0; x < AZTEC_RUNE_SIZE; x++) {
+    const expected = aztecRuneStructuralValue(x, y);
+    if (expected === null) continue;
+    if (matrix.get(x, y) !== (inverted ? !expected : expected)) return false;
+  }
+  return true;
+}
+
+/** @param {import('../core/bit-matrix.js').BitMatrix} matrix @param {boolean} inverted */
+function readCodewords(matrix, inverted) {
+  const words = new Array(2 + AZTEC_RUNE_ECC_CODEWORDS).fill(0);
+  for (let at = 0; at < AZTEC_RUNE_DATA_POSITIONS.length; at++) {
+    const [x, y] = AZTEC_RUNE_DATA_POSITIONS[at];
+    const bit = matrix.get(x, y) !== inverted;
+    words[at >>> 2] = (words[at >>> 2] << 1) | (bit ? 1 : 0);
+  }
+  return words.map((word) => word ^ AZTEC_RUNE_MASK);
+}
+
+/** @param {number} value @param {boolean} inverted @param {number} rotation @param {number} corrections */
+function result(value, inverted, rotation, corrections) {
+  return {
+    format: 'aztecrune',
+    value,
+    text: String(value).padStart(3, '0'),
+    bytes: Uint8Array.of(value),
+    dimension: AZTEC_RUNE_SIZE,
+    inverted,
+    rotation,
+    corrections,
+  };
+}
+
+/**
+ * Decode a square Aztec Rune matrix.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {{inverted?: boolean|'auto', rotation?: number|'auto'}} [options]
+ * @returns {{format:'aztecrune',value:number,text:string,bytes:Uint8Array,dimension:number,inverted:boolean,rotation:number,corrections:number}}
+ * @throws {FormatError} For non-Rune geometry, structure or uncorrectable data.
+ */
+export function decodeAztecRune(matrix, options = {}) {
+  if (!matrix || matrix.width !== AZTEC_RUNE_SIZE || matrix.height !== AZTEC_RUNE_SIZE) {
+    throw new FormatError(`Aztec Rune: expected an ${AZTEC_RUNE_SIZE}x${AZTEC_RUNE_SIZE} module matrix`);
+  }
+  const invertedModes = options.inverted === true ? [true] : options.inverted === false ? [false] : [false, true];
+  const rotations = Number.isInteger(options.rotation)
+    ? [((options.rotation % 360) + 360) % 360]
+    : [0, 90, 180, 270];
+
+  let checksumError = null;
+  for (const requestedRotation of rotations) {
+    if (requestedRotation % 90 !== 0) continue;
+    // To canonicalize an input rotated clockwise by k degrees, rotate it
+    // counter-clockwise by k. `turns` is the clockwise operation we apply.
+    const turns = (4 - requestedRotation / 90) % 4;
+    const canonicalRotation = requestedRotation;
+    const rotated = turns === 0 ? matrix.clone() : rotateClockwise(matrix, turns);
+    for (const inverted of invertedModes) {
+      const canonical = inverted ? invert(rotated) : rotated;
+      if (!structureMatches(canonical, false)) continue;
+      const words = readCodewords(canonical, false);
+      try {
+        const corrections = rsDecode(words, AZTEC_RUNE_ECC_CODEWORDS, aztecRuneField(), 1);
+        const value = (words[0] << 4) | words[1];
+        return result(value, inverted, canonicalRotation, corrections);
+      } catch (error) {
+        checksumError = error;
+      }
+    }
+  }
+
+  if (checksumError) {
+    throw new FormatError(`Aztec Rune: Reed-Solomon check failed: ${checksumError.message}`);
+  }
+  throw new FormatError('Aztec Rune: structural pattern or orientation is invalid');
+}
+
+export { readCodewords, structureMatches };

package/src/aztecrune/detector.js

@@ -0,0 +1,167 @@
+/*!
+ * 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-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Detector for Aztec Rune symbols.
+ *
+ * Rune has a fixed 11x11 geometry and a distinctive five-ring bull's-eye. This
+ * detector targets binarized, module-aligned rasters (including an integer
+ * scale, quiet zone and quarter turns). Arbitrary perspective and severe blur
+ * remain detector-level limitations; callers needing those conditions should
+ * pass a rectified 11x11 matrix to decodeAztecRune.
+ *
+ * @module aztecrune/detector
+ */
+
+import { NotFoundError } from '../core/errors.js';
+import { BitMatrix } from '../core/bit-matrix.js';
+import { decodeAztecRune } from './decoder.js';
+import { AZTEC_RUNE_SIZE } from './tables.js';
+
+/** @typedef {{x:number,y:number}} Point */
+
+/**
+ * Find connected components of a polarity. Components touching the image
+ * border are ignored when they exceed the plausible module area; this avoids
+ * returning the light background as a candidate while retaining an inverted
+ * Rune's isolated light centre module.
+ */
+function components(image, value) {
+  const width = image.width;
+  const height = image.height;
+  const seen = new Uint8Array(width * height);
+  const limit = Math.max(64, Math.floor(width * height * 0.04));
+  const found = [];
+
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    const start = y * width + x;
+    if (seen[start] || image.get(x, y) !== value) continue;
+    const queue = [[x, y]];
+    seen[start] = 1;
+    let head = 0;
+    let minX = x; let maxX = x; let minY = y; let maxY = y;
+    let count = 0;
+    let touchesBorder = false;
+
+    while (head < queue.length) {
+      const [px, py] = queue[head++];
+      count++;
+      minX = Math.min(minX, px); maxX = Math.max(maxX, px);
+      minY = Math.min(minY, py); maxY = Math.max(maxY, py);
+      if (px === 0 || py === 0 || px === width - 1 || py === height - 1) touchesBorder = true;
+      for (const [nx, ny] of [[px - 1, py], [px + 1, py], [px, py - 1], [px, py + 1]]) {
+        if (nx < 0 || ny < 0 || nx >= width || ny >= height) continue;
+        const at = ny * width + nx;
+        if (!seen[at] && image.get(nx, ny) === value) {
+          seen[at] = 1;
+          queue.push([nx, ny]);
+        }
+      }
+    }
+
+    const boxWidth = maxX - minX + 1;
+    const boxHeight = maxY - minY + 1;
+    if (count <= limit && !touchesBorder &&
+      Math.abs(boxWidth - boxHeight) <= Math.max(1, Math.ceil(Math.max(boxWidth, boxHeight) * 0.35)) &&
+      count >= boxWidth * boxHeight * 0.45) {
+      found.push({ x: (minX + maxX) / 2, y: (minY + maxY) / 2, width: boxWidth, height: boxHeight, count });
+    }
+  }
+  return found.sort((a, b) => b.count - a.count);
+}
+/** @param {import('../core/bit-matrix.js').BitMatrix} image @param {Point} center @param {number} pitch */
+function sample(image, center, pitch) {
+  const matrix = new BitMatrix(AZTEC_RUNE_SIZE);
+  for (let y = 0; y < AZTEC_RUNE_SIZE; y++) for (let x = 0; x < AZTEC_RUNE_SIZE; x++) {
+    const px = Math.round(center.x + (x - 5) * pitch);
+    const py = Math.round(center.y + (y - 5) * pitch);
+    if (px >= 0 && py >= 0 && px < image.width && py < image.height && image.get(px, py)) matrix.set(x, y);
+  }
+  return matrix;
+}
+
+function corners(center, pitch) {
+  const half = AZTEC_RUNE_SIZE * pitch / 2;
+  return [
+    { x: center.x - half, y: center.y - half },
+    { x: center.x + half, y: center.y - half },
+    { x: center.x + half, y: center.y + half },
+    { x: center.x - half, y: center.y + half },
+  ];
+}
+
+function sameCandidate(left, right) {
+  return Math.hypot(left.center.x - right.center.x, left.center.y - right.center.y) <= Math.max(left.moduleSize, right.moduleSize) * 2;
+}
+
+/**
+ * Detect the most prominent Aztec Rune in a binarized image.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} binaryImage
+ * @returns {{corners:Point[],dimension:11,moduleSize:number,matrix:BitMatrix,result:object}|null}
+ */
+export function detectAztecRune(binaryImage) {
+  if (!binaryImage || !binaryImage.width || !binaryImage.height) {
+    throw new NotFoundError('detectAztecRune: no image supplied');
+  }
+  const candidates = [];
+  for (const value of [true, false]) {
+    for (const component of components(binaryImage, value)) {
+      const pitch = (component.width + component.height) / 2;
+      if (pitch < 0.8) continue;
+      const matrix = sample(binaryImage, component, pitch);
+      let decoded;
+      try { decoded = decodeAztecRune(matrix); } catch { continue; }
+      const candidate = {
+        center: component,
+        corners: corners(component, pitch),
+        dimension: AZTEC_RUNE_SIZE,
+        moduleSize: pitch,
+        matrix,
+        result: decoded,
+      };
+      if (!candidates.some((entry) => sameCandidate(entry, candidate))) candidates.push(candidate);
+    }
+  }
+  candidates.sort((a, b) => b.moduleSize - a.moduleSize);
+  const best = candidates[0];
+  if (!best) return null;
+  delete best.center;
+  return best;
+}
+
+/** Detect and decode one Aztec Rune, or return `null` when none is verified. */
+export function detectAndDecodeAztecRune(binaryImage) {
+  let detection;
+  try { detection = detectAztecRune(binaryImage); } catch { return null; }
+  if (!detection) return null;
+  return { ...detection.result, corners: detection.corners, moduleSize: detection.moduleSize };
+}

package/src/aztecrune/encoder.js

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

package/src/aztecrune/index.js

@@ -0,0 +1,50 @@
+/*!
+ * 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-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/** Aztec Rune entry points. @module aztecrune */
+
+export { encodeAztecRune, normalizeAztecRuneValue } from './encoder.js';
+export { decodeAztecRune } from './decoder.js';
+export { detectAztecRune, detectAndDecodeAztecRune } from './detector.js';
+export {
+  AZTEC_RUNE_SIZE,
+  AZTEC_RUNE_DATA_BITS,
+  AZTEC_RUNE_WORD_SIZE,
+  AZTEC_RUNE_DATA_CODEWORDS,
+  AZTEC_RUNE_ECC_CODEWORDS,
+  AZTEC_RUNE_TOTAL_CODEWORDS,
+  AZTEC_RUNE_MASK,
+  AZTEC_RUNE_DATA_POSITIONS,
+  aztecRuneStructuralValue,
+  buildAztecRuneStructure,
+  aztecRuneField,
+  validateAztecRuneTables,
+} from './tables.js';

package/src/aztecrune/tables.js

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