@sythos/js_barcode_universal 0.1.0

package/src/qr/tables.js

@@ -0,0 +1,737 @@
+/*!
+ * 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.
+ */
+
+/**
+ * QR Code structural tables.
+ *
+ * The design principle here is that as little as possible is *recalled* and as
+ * much as possible is *derived*, because a barcode table is the one place where
+ * a single mistyped digit produces a symbol that looks perfect and scans as
+ * garbage — or, worse, scans correctly for the payload you tested and fails for
+ * the payload your user sends.
+ *
+ * So:
+ *
+ *   - Symbol size, function-pattern layout and total codeword capacity are
+ *     computed from geometry. Nothing is tabulated that the module grid already
+ *     knows.
+ *   - Alignment centres come from the spec's spacing rule, not a 40-row table.
+ *   - The group-1 / group-2 block split is arithmetic, not data.
+ *
+ * That leaves exactly three recalled numbers per (version, level): the error
+ * correction codewords per block, the block count, and the total data codeword
+ * count. Those three are deliberately redundant — they must satisfy
+ *
+ *     blocks * eccPerBlock + totalDataCodewords === geometricTotalCodewords(v)
+ *
+ * for all 160 combinations, where the right-hand side is counted off the module
+ * grid. Any single typo on either side breaks the identity. {@link validateTables}
+ * enforces it, and the test suite asserts it returns no problems.
+ *
+ * @module qr/tables
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+
+/** Error correction levels, weakest to strongest. */
+export const ECC_LEVELS = ['L', 'M', 'Q', 'H'];
+
+/**
+ * Two-bit level indicator used in the format information.
+ * Note this is *not* the L/M/Q/H ordering — the spec assigns them out of order.
+ */
+export const ECC_LEVEL_BITS = { L: 0b01, M: 0b00, Q: 0b11, H: 0b10 };
+
+/** Inverse of {@link ECC_LEVEL_BITS}, indexed by the 2-bit value. */
+export const ECC_LEVEL_BY_BITS = ['M', 'L', 'H', 'Q'];
+
+export const MIN_VERSION = 1;
+export const MAX_VERSION = 40;
+
+/** Version at and above which an 18-bit version information block is carried. */
+export const VERSION_INFO_MIN = 7;
+
+/** Mode indicator nibbles. */
+export const MODE = {
+  TERMINATOR: 0x0,
+  NUMERIC: 0x1,
+  ALPHANUMERIC: 0x2,
+  STRUCTURED_APPEND: 0x3,
+  BYTE: 0x4,
+  FNC1_FIRST: 0x5,
+  ECI: 0x7,
+  KANJI: 0x8,
+  FNC1_SECOND: 0x9,
+};
+
+/**
+ * Character count indicator width, in bits, by mode and version band.
+ *
+ * The bands are versions 1-9, 10-26 and 27-40. They are the reason segment
+ * selection and version selection are mutually dependent: widening the count
+ * field can push a payload over a version boundary, which widens it again.
+ */
+const COUNT_BITS = {
+  [MODE.NUMERIC]: [10, 12, 14],
+  [MODE.ALPHANUMERIC]: [9, 11, 13],
+  [MODE.BYTE]: [8, 16, 16],
+  [MODE.KANJI]: [8, 10, 12],
+};
+
+/**
+ * @param {number} version 1-40
+ * @returns {number} Modules per side.
+ */
+export function versionSize(version) {
+  return 17 + 4 * version;
+}
+
+/**
+ * Bits in the character count indicator.
+ *
+ * @param {number} mode One of {@link MODE}.
+ * @param {number} version
+ * @returns {number}
+ */
+export function countBits(mode, version) {
+  const widths = COUNT_BITS[mode];
+  if (!widths) return 0;
+  if (version <= 9) return widths[0];
+  if (version <= 26) return widths[1];
+  return widths[2];
+}
+
+/**
+ * Centre coordinates of the alignment patterns for a version.
+ *
+ * The spec's rule: the first centre is always 6 and the last is always
+ * `size - 7`; the count grows by one every seven versions; and the centres are
+ * evenly spaced with the *first* gap absorbing the rounding slack. Expressing
+ * that as arithmetic rather than a 40-row table means there is no table to
+ * mistype, and {@link validateTables} can then assert the shape of the result.
+ *
+ * @param {number} version
+ * @returns {number[]} Ascending centres. Empty for version 1.
+ */
+export function alignmentCoordinates(version) {
+  if (version < 2) return [];
+
+  const size = versionSize(version);
+  const count = Math.floor(version / 7) + 2;
+  const last = size - 7;
+
+  // Spacing is rounded up to an even number of modules so every centre lands on
+  // the same parity as the timing pattern, which is what keeps the patterns
+  // aligned with the module grid rather than straddling it.
+  const step = Math.ceil((size - 13) / (2 * count - 2)) * 2;
+
+  const coords = [6];
+  // Walk backwards from the final centre so the slack lands in the first gap.
+  for (let i = count - 1; i >= 1; i--) coords.push(last - (count - 1 - i) * step);
+  coords.sort((a, b) => a - b);
+  return coords;
+}
+
+/**
+ * Centres of the alignment patterns actually drawn, as [x, y] pairs.
+ *
+ * The three combinations that would sit on top of a finder pattern are omitted.
+ *
+ * @param {number} version
+ * @returns {Array<[number, number]>}
+ */
+export function alignmentCentres(version) {
+  const coords = alignmentCoordinates(version);
+  if (coords.length === 0) return [];
+
+  const size = versionSize(version);
+  const lo = 6;
+  const hi = size - 7;
+  const out = [];
+  for (let i = 0; i < coords.length; i++) {
+    for (let j = 0; j < coords.length; j++) {
+      const x = coords[j];
+      const y = coords[i];
+      // Skip the three finder corners.
+      if (x === lo && y === lo) continue;
+      if (x === lo && y === hi) continue;
+      if (x === hi && y === lo) continue;
+      out.push([x, y]);
+    }
+  }
+  return out;
+}
+
+const reservedCache = new Map();
+
+/**
+ * Map of modules that carry function patterns rather than payload.
+ *
+ * A set bit means "reserved": finder, separator, timing, alignment, format
+ * information, the dark module, and the version information blocks. This is the
+ * single source of truth used by the encoder to skip modules while laying out
+ * the bitstream, by the decoder to read them back in the same order, and by
+ * {@link geometricTotalCodewords} to count what is left.
+ *
+ * Deriving capacity this way rather than by hand arithmetic is what makes the
+ * awkward cases free: an alignment pattern that overlaps the timing pattern is
+ * counted once because it is the same set of modules, not because anyone
+ * remembered to subtract five.
+ *
+ * @param {number} version
+ * @returns {BitMatrix} Shared, cached — treat as immutable.
+ */
+export function reservedModules(version) {
+  const cached = reservedCache.get(version);
+  if (cached) return cached;
+
+  const size = versionSize(version);
+  const m = new BitMatrix(size, size);
+
+  // Finder patterns with their separators: an 8x8 reserved block at each of
+  // three corners (7x7 pattern plus a one-module light border on the inner
+  // sides, which the corner blocks absorb).
+  m.setRegion(0, 0, 8, 8);
+  m.setRegion(size - 8, 0, 8, 8);
+  m.setRegion(0, size - 8, 8, 8);
+
+  // Timing patterns, spanning the gap between the separators.
+  for (let i = 8; i < size - 8; i++) {
+    m.set(i, 6);
+    m.set(6, i);
+  }
+
+  // Alignment patterns, 5x5 each.
+  const centres = alignmentCentres(version);
+  for (let i = 0; i < centres.length; i++) {
+    m.setRegion(centres[i][0] - 2, centres[i][1] - 2, 5, 5);
+  }
+
+  // Format information: two copies plus the dark module. The copies partly
+  // fall inside the 8x8 finder blocks already reserved; setting them again is
+  // harmless and keeps the intent explicit.
+  const [copyA, copyB] = formatInfoPositions(size);
+  for (let i = 0; i < 15; i++) {
+    m.set(copyA[i][0], copyA[i][1]);
+    m.set(copyB[i][0], copyB[i][1]);
+  }
+  m.set(8, size - 8); // dark module
+
+  // Version information, two 6x3 blocks.
+  if (version >= VERSION_INFO_MIN) {
+    m.setRegion(size - 11, 0, 3, 6);
+    m.setRegion(0, size - 11, 6, 3);
+  }
+
+  reservedCache.set(version, m);
+  return m;
+}
+
+/**
+ * Module positions of the two format information copies.
+ *
+ * Index `i` in each array is bit `i` of the 15-bit format value, bit 0 being
+ * the least significant.
+ *
+ * CAVEAT WORTH READING: the *direction* of this numbering is the one thing in
+ * this file that a round-trip test cannot falsify. Encoder and decoder share
+ * these tables, so a mirrored layout would pass every test in the suite and
+ * fail only against a real scanner. The layout below is the standard one; both
+ * sides deliberately consume this single definition so there is no second place
+ * for the convention to drift.
+ *
+ * @param {number} size Modules per side.
+ * @returns {[Array<[number, number]>, Array<[number, number]>]} [copyA, copyB]
+ */
+export function formatInfoPositions(size) {
+  /** @type {Array<[number, number]>} */
+  const a = [];
+  /** @type {Array<[number, number]>} */
+  const b = [];
+
+  for (let i = 0; i < 15; i++) {
+    // Copy A wraps the top-left finder: down column 8, then left along row 8,
+    // stepping over the two timing modules.
+    if (i < 6) a.push([8, i]);
+    else if (i === 6) a.push([8, 7]);
+    else if (i === 7) a.push([8, 8]);
+    else if (i === 8) a.push([7, 8]);
+    else a.push([14 - i, 8]);
+
+    // Copy B is split: the low bits run right-to-left along row 8 beside the
+    // top-right finder, the high bits run bottom-up beside the bottom-left one.
+    if (i < 8) b.push([size - 1 - i, 8]);
+    else b.push([8, size - 15 + i]);
+  }
+
+  return [a, b];
+}
+
+/**
+ * Modules available to data and error correction, counted off the grid.
+ *
+ * @param {number} version
+ * @returns {number}
+ */
+export function freeModuleCount(version) {
+  const reserved = reservedModules(version);
+  const size = versionSize(version);
+  let free = 0;
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      if (!reserved.get(x, y)) free++;
+    }
+  }
+  return free;
+}
+
+/**
+ * Total codewords (data + error correction) a version holds.
+ *
+ * Geometric, not tabulated — this is the reference the ECC table is checked
+ * against.
+ *
+ * @param {number} version
+ * @returns {number}
+ */
+export function geometricTotalCodewords(version) {
+  return Math.floor(freeModuleCount(version) / 8);
+}
+
+/**
+ * Bits left over after the last whole codeword, written as zeroes.
+ *
+ * @param {number} version
+ * @returns {number} 0, 3, 4 or 7.
+ */
+export function remainderBits(version) {
+  return freeModuleCount(version) % 8;
+}
+
+const orderCache = new Map();
+
+/**
+ * Module positions in bitstream order, as interleaved x, y pairs.
+ *
+ * The layout walks two-module-wide columns from the bottom-right corner
+ * leftward, alternating upward and downward, right module of the pair before
+ * the left, skipping the vertical timing column and every reserved module.
+ *
+ * Encoder and decoder both consume this one function. That is not tidiness: a
+ * placement order that disagrees between the two would still round-trip
+ * perfectly within this library while producing symbols no scanner can read.
+ * There is only one order because there is only one implementation of it.
+ *
+ * @param {number} version
+ * @returns {Int32Array} Shared, cached — treat as immutable. Length is
+ *   `2 * freeModuleCount(version)`.
+ */
+export function dataModuleOrder(version) {
+  const cached = orderCache.get(version);
+  if (cached) return cached;
+
+  const size = versionSize(version);
+  const reserved = reservedModules(version);
+  const out = new Int32Array(freeModuleCount(version) * 2);
+  let n = 0;
+
+  let upward = true;
+  for (let col = size - 1; col > 0; col -= 2) {
+    // Column 6 is the vertical timing pattern. Stepping over it shifts the
+    // whole remaining schedule left by one, so the loop variable itself has to
+    // move — adjusting only the current pair would visit column 4 twice and
+    // column 0 never, which is self-consistent between encoder and decoder and
+    // therefore invisible to a round-trip test.
+    if (col === 6) col--;
+    for (let i = 0; i < size; i++) {
+      const y = upward ? size - 1 - i : i;
+      for (let c = 0; c < 2; c++) {
+        const x = col - c;
+        if (reserved.get(x, y)) continue;
+        out[n++] = x;
+        out[n++] = y;
+      }
+    }
+    upward = !upward;
+  }
+
+  orderCache.set(version, out);
+  return out;
+}
+
+/**
+ * The eight data mask predicates.
+ *
+ * A true result means the module at (x, y) is inverted. Masks apply to payload
+ * modules only; function patterns are laid down after masking and are never
+ * touched.
+ *
+ * @param {number} mask 0-7
+ * @param {number} x Column.
+ * @param {number} y Row.
+ * @returns {boolean}
+ */
+export function maskBit(mask, x, y) {
+  switch (mask) {
+    case 0: return ((y + x) & 1) === 0;
+    case 1: return (y & 1) === 0;
+    case 2: return x % 3 === 0;
+    case 3: return (y + x) % 3 === 0;
+    case 4: return (((y >> 1) + Math.floor(x / 3)) & 1) === 0;
+    case 5: return ((y * x) & 1) + ((y * x) % 3) === 0;
+    case 6: return ((((y * x) & 1) + ((y * x) % 3)) & 1) === 0;
+    case 7: return ((((y + x) & 1) + ((y * x) % 3)) & 1) === 0;
+    default:
+      throw new RangeError(`QR: mask must be 0-7, got ${mask}`);
+  }
+}
+
+/**
+ * Error correction parameters, indexed `[version - 1]` then by level.
+ *
+ * Each entry is `[eccCodewordsPerBlock, blockCount, totalDataCodewords]`.
+ *
+ * The third number is redundant with the first two given the geometric
+ * capacity, and that is the entire point: it turns a silent typo into a loud
+ * failure. See the module note.
+ *
+ * @type {Array<{L: number[], M: number[], Q: number[], H: number[]}>}
+ */
+const ECC_TABLE = [
+  /*  1 */ { L: [7, 1, 19], M: [10, 1, 16], Q: [13, 1, 13], H: [17, 1, 9] },
+  /*  2 */ { L: [10, 1, 34], M: [16, 1, 28], Q: [22, 1, 22], H: [28, 1, 16] },
+  /*  3 */ { L: [15, 1, 55], M: [26, 1, 44], Q: [18, 2, 34], H: [22, 2, 26] },
+  /*  4 */ { L: [20, 1, 80], M: [18, 2, 64], Q: [26, 2, 48], H: [16, 4, 36] },
+  /*  5 */ { L: [26, 1, 108], M: [24, 2, 86], Q: [18, 4, 62], H: [22, 4, 46] },
+  /*  6 */ { L: [18, 2, 136], M: [16, 4, 108], Q: [24, 4, 76], H: [28, 4, 60] },
+  /*  7 */ { L: [20, 2, 156], M: [18, 4, 124], Q: [18, 6, 88], H: [26, 5, 66] },
+  /*  8 */ { L: [24, 2, 194], M: [22, 4, 154], Q: [22, 6, 110], H: [26, 6, 86] },
+  /*  9 */ { L: [30, 2, 232], M: [22, 5, 182], Q: [20, 8, 132], H: [24, 8, 100] },
+  /* 10 */ { L: [18, 4, 274], M: [26, 5, 216], Q: [24, 8, 154], H: [28, 8, 122] },
+  /* 11 */ { L: [20, 4, 324], M: [30, 5, 254], Q: [28, 8, 180], H: [24, 11, 140] },
+  /* 12 */ { L: [24, 4, 370], M: [22, 8, 290], Q: [26, 10, 206], H: [28, 11, 158] },
+  /* 13 */ { L: [26, 4, 428], M: [22, 9, 334], Q: [24, 12, 244], H: [22, 16, 180] },
+  /* 14 */ { L: [30, 4, 461], M: [24, 9, 365], Q: [20, 16, 261], H: [24, 16, 197] },
+  /* 15 */ { L: [22, 6, 523], M: [24, 10, 415], Q: [30, 12, 295], H: [24, 18, 223] },
+  /* 16 */ { L: [24, 6, 589], M: [28, 10, 453], Q: [24, 17, 325], H: [30, 16, 253] },
+  /* 17 */ { L: [28, 6, 647], M: [28, 11, 507], Q: [28, 16, 367], H: [28, 19, 283] },
+  /* 18 */ { L: [30, 6, 721], M: [26, 13, 563], Q: [28, 18, 397], H: [28, 21, 313] },
+  /* 19 */ { L: [28, 7, 795], M: [26, 14, 627], Q: [26, 21, 445], H: [26, 25, 341] },
+  /* 20 */ { L: [28, 8, 861], M: [26, 16, 669], Q: [30, 20, 485], H: [28, 25, 385] },
+  /* 21 */ { L: [28, 8, 932], M: [26, 17, 714], Q: [28, 23, 512], H: [30, 25, 406] },
+  /* 22 */ { L: [28, 9, 1006], M: [28, 17, 782], Q: [30, 23, 568], H: [24, 34, 442] },
+  /* 23 */ { L: [30, 9, 1094], M: [28, 18, 860], Q: [30, 25, 614], H: [30, 30, 464] },
+  /* 24 */ { L: [30, 10, 1174], M: [28, 20, 914], Q: [30, 27, 664], H: [30, 32, 514] },
+  /* 25 */ { L: [26, 12, 1276], M: [28, 21, 1000], Q: [30, 29, 718], H: [30, 35, 538] },
+  /* 26 */ { L: [28, 12, 1370], M: [28, 23, 1062], Q: [28, 34, 754], H: [30, 37, 596] },
+  /* 27 */ { L: [30, 12, 1468], M: [28, 25, 1128], Q: [30, 34, 808], H: [30, 40, 628] },
+  /* 28 */ { L: [30, 13, 1531], M: [28, 26, 1193], Q: [30, 35, 871], H: [30, 42, 661] },
+  /* 29 */ { L: [30, 14, 1631], M: [28, 28, 1267], Q: [30, 38, 911], H: [30, 45, 701] },
+  /* 30 */ { L: [30, 15, 1735], M: [28, 29, 1373], Q: [30, 40, 985], H: [30, 48, 745] },
+  /* 31 */ { L: [30, 16, 1843], M: [28, 31, 1455], Q: [30, 43, 1033], H: [30, 51, 793] },
+  /* 32 */ { L: [30, 17, 1955], M: [28, 33, 1541], Q: [30, 45, 1115], H: [30, 54, 845] },
+  /* 33 */ { L: [30, 18, 2071], M: [28, 35, 1631], Q: [30, 48, 1171], H: [30, 57, 901] },
+  /* 34 */ { L: [30, 19, 2191], M: [28, 37, 1725], Q: [30, 51, 1231], H: [30, 60, 961] },
+  /* 35 */ { L: [30, 19, 2306], M: [28, 38, 1812], Q: [30, 53, 1286], H: [30, 63, 986] },
+  /* 36 */ { L: [30, 20, 2434], M: [28, 40, 1914], Q: [30, 56, 1354], H: [30, 66, 1054] },
+  /* 37 */ { L: [30, 21, 2566], M: [28, 43, 1992], Q: [30, 59, 1426], H: [30, 70, 1096] },
+  /* 38 */ { L: [30, 22, 2702], M: [28, 45, 2102], Q: [30, 62, 1502], H: [30, 74, 1142] },
+  /* 39 */ { L: [30, 24, 2812], M: [28, 47, 2216], Q: [30, 65, 1582], H: [30, 77, 1222] },
+  /* 40 */ { L: [30, 25, 2956], M: [28, 49, 2334], Q: [30, 68, 1666], H: [30, 81, 1276] },
+];
+
+/**
+ * @typedef {object} BlockLayout
+ * @property {number} version
+ * @property {string} ecc
+ * @property {number} totalCodewords    Data + error correction.
+ * @property {number} totalDataCodewords
+ * @property {number} eccPerBlock
+ * @property {number} blockCount
+ * @property {number} group1Blocks      Blocks holding the smaller data count.
+ * @property {number} group1DataCount
+ * @property {number} group2Blocks      Blocks holding one extra data codeword.
+ * @property {number} group2DataCount
+ * @property {number} remainderBits
+ */
+
+/**
+ * Block structure for a (version, level).
+ *
+ * The group split is derived: the spec distributes the remainder of
+ * `data / blocks` one codeword at a time into the *trailing* blocks, so the
+ * short blocks come first. That is arithmetic, and tabulating it would only
+ * create somewhere else for a typo to hide.
+ *
+ * @param {number} version
+ * @param {string} ecc 'L' | 'M' | 'Q' | 'H'
+ * @returns {BlockLayout}
+ */
+export function blockLayout(version, ecc) {
+  if (version < MIN_VERSION || version > MAX_VERSION || (version | 0) !== version) {
+    throw new RangeError(`QR: version must be an integer 1-40, got ${version}`);
+  }
+  const entry = ECC_TABLE[version - 1][ecc];
+  if (!entry) throw new RangeError(`QR: unknown error correction level "${ecc}"`);
+
+  const eccPerBlock = entry[0];
+  const blockCount = entry[1];
+  const totalDataCodewords = entry[2];
+
+  const base = Math.floor(totalDataCodewords / blockCount);
+  const extra = totalDataCodewords % blockCount;
+
+  return {
+    version,
+    ecc,
+    totalCodewords: totalDataCodewords + eccPerBlock * blockCount,
+    totalDataCodewords,
+    eccPerBlock,
+    blockCount,
+    group1Blocks: blockCount - extra,
+    group1DataCount: base,
+    group2Blocks: extra,
+    group2DataCount: base + 1,
+    remainderBits: remainderBits(version),
+  };
+}
+
+/**
+ * Data capacity in codewords.
+ *
+ * @param {number} version
+ * @param {string} ecc
+ * @returns {number}
+ */
+export function dataCodewords(version, ecc) {
+  return ECC_TABLE[version - 1][ecc][2];
+}
+
+/**
+ * Data capacity in bits.
+ *
+ * @param {number} version
+ * @param {string} ecc
+ * @returns {number}
+ */
+export function dataBitCapacity(version, ecc) {
+  return dataCodewords(version, ecc) * 8;
+}
+
+/** Error correction codewords per block are drawn from this set and no other. */
+const VALID_ECC_PER_BLOCK = [7, 10, 13, 15, 16, 17, 18, 20, 22, 24, 26, 28, 30];
+
+/**
+ * Remainder bits by version band, from the spec. Independent of anything the
+ * ECC table says, so it validates the *geometry* — chiefly the alignment
+ * pattern spacing rule, which is otherwise only checked by its own shape.
+ *
+ * @param {number} version
+ * @returns {number}
+ */
+function expectedRemainderBits(version) {
+  if (version === 1) return 0;
+  if (version <= 6) return 7;
+  if (version <= 13) return 0;
+  if (version <= 20) return 3;
+  if (version <= 27) return 4;
+  if (version <= 34) return 3;
+  return 0;
+}
+
+/**
+ * Self-check every table in this file.
+ *
+ * The load-bearing assertion is the capacity identity across all 160
+ * (version, level) combinations, but a pair of compensating typos could in
+ * principle slip past it, so the surrounding checks each constrain a different
+ * axis: monotonicity, the closed set of ECC block sizes, the field size limit,
+ * and the shape of the alignment coordinate sequence.
+ *
+ * @returns {string[]} Human-readable problems; empty means everything holds.
+ */
+export function validateTables() {
+  const problems = [];
+
+  for (let version = MIN_VERSION; version <= MAX_VERSION; version++) {
+    const size = versionSize(version);
+    const total = geometricTotalCodewords(version);
+
+    // --- Geometry ------------------------------------------------------
+    const rem = remainderBits(version);
+    if (rem !== expectedRemainderBits(version)) {
+      problems.push(
+        `v${version}: remainder bits ${rem}, expected ${expectedRemainderBits(version)} ` +
+        `(free modules ${freeModuleCount(version)}) — check the alignment spacing rule`
+      );
+    }
+
+    // --- Placement order ----------------------------------------------
+    // Every free module must be visited exactly once. A placement order that
+    // skips one module and visits another twice is still perfectly
+    // self-consistent — the encoder writes and the decoder reads the same
+    // wrong sequence — so a round-trip test cannot see it. What it does is
+    // silently burn error correction budget on every symbol produced. This is
+    // the only check that catches it.
+    const order = dataModuleOrder(version);
+    const free = freeModuleCount(version);
+    if (order.length !== free * 2) {
+      problems.push(
+        `v${version}: placement order visits ${order.length / 2} modules, expected ${free}`
+      );
+    } else {
+      const seen = new Uint8Array(size * size);
+      let duplicates = 0;
+      let reservedHits = 0;
+      const reserved = reservedModules(version);
+      for (let p = 0; p < order.length; p += 2) {
+        const x = order[p];
+        const y = order[p + 1];
+        if (reserved.get(x, y)) reservedHits++;
+        if (seen[y * size + x]++) duplicates++;
+      }
+      if (duplicates > 0) {
+        problems.push(`v${version}: placement order visits ${duplicates} modules more than once`);
+      }
+      if (reservedHits > 0) {
+        problems.push(`v${version}: placement order includes ${reservedHits} function modules`);
+      }
+    }
+
+    // --- Alignment coordinates ----------------------------------------
+    const coords = alignmentCoordinates(version);
+    if (version === 1) {
+      if (coords.length !== 0) problems.push(`v1: expected no alignment coordinates, got ${coords.length}`);
+    } else {
+      const expectedCount = Math.floor(version / 7) + 2;
+      if (coords.length !== expectedCount) {
+        problems.push(`v${version}: ${coords.length} alignment coordinates, expected ${expectedCount}`);
+      }
+      if (coords[0] !== 6) {
+        problems.push(`v${version}: first alignment coordinate ${coords[0]}, expected 6`);
+      }
+      if (coords[coords.length - 1] !== size - 7) {
+        problems.push(
+          `v${version}: last alignment coordinate ${coords[coords.length - 1]}, expected ${size - 7}`
+        );
+      }
+      for (let i = 1; i < coords.length; i++) {
+        if (coords[i] <= coords[i - 1]) {
+          problems.push(`v${version}: alignment coordinates not strictly increasing at index ${i}`);
+        }
+      }
+      if (coords.length >= 3) {
+        // Every gap after the first must be identical, and the first gap must
+        // not exceed it — the slack is absorbed at the start, never the end.
+        const step = coords[2] - coords[1];
+        for (let i = 3; i < coords.length; i++) {
+          if (coords[i] - coords[i - 1] !== step) {
+            problems.push(
+              `v${version}: alignment gap ${coords[i] - coords[i - 1]} at index ${i}, expected ${step}`
+            );
+          }
+        }
+        if (coords[1] - coords[0] > step) {
+          problems.push(
+            `v${version}: first alignment gap ${coords[1] - coords[0]} exceeds step ${step}`
+          );
+        }
+        if (step % 2 !== 0) {
+          problems.push(`v${version}: alignment step ${step} is odd`);
+        }
+      }
+    }
+
+    // --- Error correction table ---------------------------------------
+    for (let l = 0; l < ECC_LEVELS.length; l++) {
+      const ecc = ECC_LEVELS[l];
+      const layout = blockLayout(version, ecc);
+      const tag = `v${version}-${ecc}`;
+
+      // THE identity. Everything else is a supporting check.
+      if (layout.totalCodewords !== total) {
+        problems.push(
+          `${tag}: ${layout.blockCount} blocks x ${layout.eccPerBlock} ECC + ` +
+          `${layout.totalDataCodewords} data = ${layout.totalCodewords} codewords, ` +
+          `but the grid holds ${total}`
+        );
+      }
+
+      if (VALID_ECC_PER_BLOCK.indexOf(layout.eccPerBlock) === -1) {
+        problems.push(`${tag}: ${layout.eccPerBlock} ECC codewords per block is not a valid value`);
+      }
+      if (layout.blockCount < 1) {
+        problems.push(`${tag}: block count ${layout.blockCount}`);
+      }
+      if (layout.group1DataCount < 1) {
+        problems.push(`${tag}: ${layout.totalDataCodewords} data codewords across ${layout.blockCount} blocks`);
+      }
+      if (layout.group1Blocks + layout.group2Blocks !== layout.blockCount) {
+        problems.push(`${tag}: group split does not sum to the block count`);
+      }
+      if (
+        layout.group1Blocks * layout.group1DataCount +
+        layout.group2Blocks * layout.group2DataCount !== layout.totalDataCodewords
+      ) {
+        problems.push(`${tag}: group sizes do not sum to the data codeword count`);
+      }
+      // Reed-Solomon over GF(256) cannot address a codeword longer than 255.
+      if (layout.group2DataCount + layout.eccPerBlock > 255) {
+        problems.push(
+          `${tag}: block length ${layout.group2DataCount + layout.eccPerBlock} exceeds GF(256)`
+        );
+      }
+
+      // Stronger correction must cost capacity, never gain it.
+      if (l > 0) {
+        const weaker = dataCodewords(version, ECC_LEVELS[l - 1]);
+        if (layout.totalDataCodewords >= weaker) {
+          problems.push(
+            `${tag}: ${layout.totalDataCodewords} data codewords is not less than ` +
+            `${ECC_LEVELS[l - 1]}'s ${weaker}`
+          );
+        }
+      }
+
+      // Capacity must grow with version.
+      if (version > MIN_VERSION) {
+        const smaller = dataCodewords(version - 1, ecc);
+        if (layout.totalDataCodewords <= smaller) {
+          problems.push(
+            `${tag}: ${layout.totalDataCodewords} data codewords is not more than ` +
+            `v${version - 1}-${ecc}'s ${smaller}`
+          );
+        }
+      }
+    }
+  }
+
+  return problems;
+}