@sythos/js_barcode_universal 1.2.5 → 1.3.1

package/src/microqr/encoder.js

@@ -0,0 +1,269 @@
+/*!
+ * 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.
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { BitWriter } from '../core/bit-buffer.js';
+import { EncodeError } from '../core/errors.js';
+import { GF256_QR } from '../core/galois-field.js';
+import { rsEncode } from '../core/reed-solomon.js';
+import {
+  MICROQR_VERSIONS, microQrBlockLayout, microQrDataModuleOrder,
+  microQrFormatInfo, microQrFormatInfoPositions, microQrMaskBit,
+  microQrSymbolNumber, microQrVersionSize,
+} from './tables.js';
+
+export const MICROQR_ALPHANUMERIC = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:';
+const MODE = { numeric: 0, alphanumeric: 1, byte: 2, kanji: 3 };
+const MODE_MIN_VERSION = { numeric: 1, alphanumeric: 2, byte: 3, kanji: 3 };
+const COUNT_BITS = {
+  numeric: [0, 3, 4, 5, 6], alphanumeric: [0, 0, 3, 4, 5],
+  byte: [0, 0, 0, 4, 5], kanji: [0, 0, 0, 3, 4],
+};
+
+function parseVersion(value) {
+  if (value == null) return null;
+  const match = /^M?([1-4])$/i.exec(String(value));
+  if (!match) throw new EncodeError(`Micro QR: version must be M1-M4, got ${value}`);
+  return Number(match[1]);
+}
+
+function versionNumber(version) {
+  return typeof version === 'number' ? version : Number(String(version).slice(1));
+}
+
+function latin1Bytes(text) {
+  const bytes = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) {
+    const cp = text.charCodeAt(i);
+    if (cp > 0xff) throw new EncodeError('Micro QR: byte mode supports ISO-8859-1 only (ECI is unavailable)');
+    bytes[i] = cp;
+  }
+  return bytes;
+}
+
+let sjisReverseMap;
+
+function sjisToThirteenBits(sjis) {
+  const trail = sjis & 0xff;
+  if (trail < 0x40 || trail === 0x7f || trail > 0xfc) return -1;
+  let adjusted;
+  if (sjis >= 0x8140 && sjis <= 0x9ffc) adjusted = sjis - 0x8140;
+  else if (sjis >= 0xe040 && sjis <= 0xebbf) adjusted = sjis - 0xc140;
+  else return -1;
+  const packed = (adjusted >>> 8) * 0xc0 + (adjusted & 0xff);
+  return packed <= 0x1fff ? packed : -1;
+}
+
+function getSjisReverseMap() {
+  if (sjisReverseMap !== undefined) return sjisReverseMap;
+  let decoder;
+  try {
+    decoder = new TextDecoder('shift_jis', { fatal: true });
+    if (decoder.decode(new Uint8Array([0x82, 0xa0])) !== 'あ') return (sjisReverseMap = null);
+  } catch {
+    return (sjisReverseMap = null);
+  }
+  const result = new Map();
+  const bytes = new Uint8Array(2);
+  for (const [start, end] of [[0x8140, 0x9ffc], [0xe040, 0xebbf]]) {
+    for (let value = start; value <= end; value++) {
+      if (sjisToThirteenBits(value) < 0) continue;
+      bytes[0] = value >>> 8;
+      bytes[1] = value & 0xff;
+      let character;
+      try { character = decoder.decode(bytes); } catch { continue; }
+      if (Array.from(character).length === 1 && !result.has(character)) result.set(character, value);
+    }
+  }
+  sjisReverseMap = result;
+  return result;
+}
+
+function kanjiValues(text) {
+  const reverse = getSjisReverseMap();
+  if (!reverse) return null;
+  const values = [];
+  for (const character of text) {
+    const sjis = reverse.get(character);
+    if (sjis == null) return null;
+    values.push(sjisToThirteenBits(sjis));
+  }
+  return values;
+}
+
+function chooseMode(text, forced) {
+  const mode = forced == null ? (/^\d+$/.test(text) ? 'numeric' :
+    [...text].every((ch) => MICROQR_ALPHANUMERIC.includes(ch)) ? 'alphanumeric' :
+      kanjiValues(text) ? 'kanji' : 'byte') :
+    String(forced).toLowerCase();
+  if (!(mode in MODE)) throw new EncodeError(`Micro QR: unsupported mode "${forced}"`);
+  if (mode === 'numeric' && !/^\d+$/.test(text)) throw new EncodeError('Micro QR: numeric mode accepts digits only');
+  if (mode === 'alphanumeric' && ![...text].every((ch) => MICROQR_ALPHANUMERIC.includes(ch))) {
+    throw new EncodeError('Micro QR: alphanumeric mode contains an unsupported character');
+  }
+  if (mode === 'kanji' && !kanjiValues(text)) {
+    throw new EncodeError('Micro QR: kanji mode requires characters representable in the QR Shift_JIS ranges');
+  }
+  return mode;
+}
+
+function encodePayload(text, mode) {
+  const w = new BitWriter();
+  if (mode === 'numeric') {
+    for (let i = 0; i < text.length; i += 3) {
+      const n = Math.min(3, text.length - i);
+      w.put(Number(text.slice(i, i + n)), n === 3 ? 10 : n === 2 ? 7 : 4);
+    }
+  } else if (mode === 'alphanumeric') {
+    let i = 0;
+    for (; i + 1 < text.length; i += 2) {
+      w.put(MICROQR_ALPHANUMERIC.indexOf(text[i]) * 45 + MICROQR_ALPHANUMERIC.indexOf(text[i + 1]), 11);
+    }
+    if (i < text.length) w.put(MICROQR_ALPHANUMERIC.indexOf(text[i]), 6);
+  } else if (mode === 'byte') {
+    w.putBytes(latin1Bytes(text));
+  } else {
+    for (const value of kanjiValues(text)) w.put(value, 13);
+  }
+  return w;
+}
+
+function getBit(writer, index) {
+  return ((writer.bytes[index >>> 3] >>> (7 - (index & 7))) & 1) === 1;
+}
+
+function writeData(text, mode, version, layout) {
+  const numericVersion = versionNumber(version);
+  const payload = encodePayload(text, mode);
+  const writer = new BitWriter();
+  if (numericVersion > 1) writer.put(MODE[mode], numericVersion - 1);
+  const count = mode === 'byte' ? latin1Bytes(text).length : [...text].length;
+  const countWidth = COUNT_BITS[mode][numericVersion];
+  if (countWidth === 0 || count >= 2 ** countWidth) return null;
+  writer.put(count, countWidth);
+  for (let i = 0; i < payload.length; i++) writer.putBit(getBit(payload, i));
+  if (writer.length > layout.dataBits) return null;
+  for (let i = 0, n = Math.min(2 * numericVersion + 1, layout.dataBits - writer.length); i < n; i++) writer.putBit(false);
+  if (numericVersion !== 1 && numericVersion !== 3) {
+    while ((writer.length & 7) && writer.length < layout.dataBits) writer.putBit(false);
+  }
+  if (numericVersion === 1 || numericVersion === 3) {
+    while (writer.length < layout.dataBits) writer.putBit(false);
+    return writer;
+  }
+  let pad = 0;
+  while (writer.length + 8 <= layout.dataBits) writer.put(pad++ & 1 ? 0x11 : 0xec, 8);
+  while (writer.length < layout.dataBits) writer.putBit(false);
+  return writer;
+}
+
+function finalMessage(dataWriter, layout) {
+  const bytes = Array.from(dataWriter.toBytes());
+  if (layout.shortDataCodewordBits === 4) bytes[bytes.length - 1] &= 0xf0;
+  const ecc = rsEncode(bytes, layout.eccCodewords, GF256_QR, 0);
+  const out = [];
+  const full = layout.shortDataCodewordBits === 4 ? bytes.length - 1 : bytes.length;
+  for (let i = 0; i < full; i++) for (let b = 7; b >= 0; b--) out.push((bytes[i] >>> b) & 1);
+  if (layout.shortDataCodewordBits === 4) for (let b = 7; b >= 4; b--) out.push((bytes[bytes.length - 1] >>> b) & 1);
+  for (const value of ecc) for (let b = 7; b >= 0; b--) out.push((value >>> b) & 1);
+  return out;
+}
+
+function drawFunctions(matrix) {
+  const size = matrix.width;
+  for (let y = 0; y < 7; y++) for (let x = 0; x < 7; x++) {
+    const ring = x === 0 || x === 6 || y === 0 || y === 6;
+    const core = x >= 2 && x <= 4 && y >= 2 && y <= 4;
+    matrix.setValue(x, y, ring || core);
+  }
+  for (let i = 0; i < 8; i++) { matrix.unset(7, i); matrix.unset(i, 7); }
+  for (let i = 8; i < size; i++) if ((i & 1) === 0) { matrix.set(i, 0); matrix.set(0, i); }
+}
+
+function microMaskScore(matrix) {
+  let right = 0, bottom = 0;
+  for (let i = 1; i < matrix.width; i++) {
+    if (matrix.get(matrix.width - 1, i)) right++;
+    if (matrix.get(i, matrix.height - 1)) bottom++;
+  }
+  return Math.min(right, bottom) * 16 + Math.max(right, bottom);
+}
+
+function buildMatrix(version, ecc, mask, bits) {
+  const matrix = new BitMatrix(microQrVersionSize(version));
+  drawFunctions(matrix);
+  const order = microQrDataModuleOrder(version);
+  for (let i = 0; i < bits.length; i++) {
+    const x = order[i * 2], y = order[i * 2 + 1];
+    matrix.setValue(x, y, (bits[i] === 1) !== microQrMaskBit(mask, x, y));
+  }
+  const format = microQrFormatInfo(microQrSymbolNumber(version, ecc), mask);
+  const positions = microQrFormatInfoPositions(matrix.width);
+  for (let i = 0; i < 15; i++) matrix.setValue(positions[i][0], positions[i][1], ((format >>> i) & 1) === 1);
+  return matrix;
+}
+
+export function encodeMicroQR(text, options = {}) {
+  text = String(text);
+  if (!text) throw new EncodeError('Micro QR: payload must not be empty');
+  if (options.eci != null || options.gs1 === true) throw new EncodeError('Micro QR: ECI and GS1/FNC1 are unavailable');
+  const mode = chooseMode(text, options.mode);
+  const wantedVersion = parseVersion(options.version);
+  const wantedEcc = options.ecc == null ? null : String(options.ecc).toUpperCase();
+  if (wantedEcc === 'H') throw new EncodeError('Micro QR: error correction level H is unavailable');
+  if (options.mask != null && (!Number.isInteger(options.mask) || options.mask < 0 || options.mask > 3)) {
+    throw new EncodeError(`Micro QR: mask must be an integer 0-3, got ${options.mask}`);
+  }
+
+  let selected;
+  for (const version of MICROQR_VERSIONS) {
+    if (wantedVersion != null && version !== wantedVersion) continue;
+    const numericVersion = versionNumber(version);
+    if (numericVersion < MODE_MIN_VERSION[mode]) continue;
+    const levels = numericVersion === 1 ? ['DETECT'] : numericVersion < 4 ? ['L', 'M'] : ['L', 'M', 'Q'];
+    for (const ecc of levels) {
+      if (wantedEcc != null && ecc !== wantedEcc) continue;
+      const layout = microQrBlockLayout(version, ecc);
+      const data = writeData(text, mode, version, layout);
+      if (data) { selected = { version, ecc, layout, data }; break; }
+    }
+    if (selected) break;
+  }
+  if (!selected) throw new EncodeError('Micro QR: payload does not fit the requested version/error level');
+  const bits = finalMessage(selected.data, selected.layout);
+  if (options.mask != null) return buildMatrix(selected.version, selected.ecc, options.mask, bits);
+  let best, score = -1;
+  for (let mask = 0; mask < 4; mask++) {
+    const candidate = buildMatrix(selected.version, selected.ecc, mask, bits);
+    const candidateScore = microMaskScore(candidate);
+    if (candidateScore > score) { score = candidateScore; best = candidate; }
+  }
+  return best;
+}

package/src/microqr/index.js

@@ -0,0 +1,36 @@
+/*!
+ * 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.
+ */
+
+/** Micro QR Code M1-M4 public module surface. @module microqr */
+
+export { encodeMicroQR } from './encoder.js';
+export { decodeMicroQR } from './decoder.js';
+export { detectMicroQR, detectAndDecodeMicroQR } from './detector.js';
+export { validateMicroQrTables } from './tables.js';

package/src/microqr/tables.js

@@ -0,0 +1,316 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Micro QR Code structural facts and geometry.
+ *
+ * Only the irreducible public symbology values are tabulated. Grid capacity,
+ * reserved areas and placement order are derived independently and checked by
+ * {@link validateMicroQrTables}. M1 and M3 have a four-bit final data symbol
+ * character; `dataBits` therefore is authoritative and must not be inferred as
+ * `dataCodewords * 8` for those versions.
+ *
+ * @module microqr/tables
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+
+/** Numeric version identifiers used by the encoder selection loop. */
+export const MICROQR_VERSIONS = Object.freeze([1, 2, 3, 4]);
+export const MICROQR_VERSION_NAMES = Object.freeze(['M1', 'M2', 'M3', 'M4']);
+export const MICROQR_ECC_LEVELS = Object.freeze(['DETECT', 'L', 'M', 'Q']);
+export const MICROQR_FORMAT_MASK = 0x4445;
+export const MICROQR_FORMAT_GENERATOR = 0x537;
+
+const symbol = (version, ecc, symbolNumber, totalCodewords, dataCodewords, dataBits, eccCodewords) => Object.freeze({
+  version,
+  ecc,
+  symbolNumber,
+  size: 9 + Number(version.slice(1)) * 2,
+  totalCodewords,
+  dataCodewords,
+  dataBits,
+  eccCodewords,
+  blockCount: 1,
+  shortDataCodewordBits: dataBits % 8 || 8,
+  remainderBits: 0,
+});
+
+/** The eight legal Micro QR version/error-correction combinations. */
+export const MICROQR_SYMBOLS = Object.freeze([
+  symbol('M1', 'DETECT', 0, 5, 3, 20, 2),
+  symbol('M2', 'L',      1, 10, 5, 40, 5),
+  symbol('M2', 'M',      2, 10, 4, 32, 6),
+  symbol('M3', 'L',      3, 17, 11, 84, 6),
+  symbol('M3', 'M',      4, 17, 9, 68, 8),
+  symbol('M4', 'L',      5, 24, 16, 128, 8),
+  symbol('M4', 'M',      6, 24, 14, 112, 10),
+  symbol('M4', 'Q',      7, 24, 10, 80, 14),
+]);
+
+const symbolByKey = new Map(MICROQR_SYMBOLS.map((entry) => [`${entry.version}:${entry.ecc}`, entry]));
+const symbolByNumber = new Map(MICROQR_SYMBOLS.map((entry) => [entry.symbolNumber, entry]));
+
+function canonicalVersion(version) {
+  const result = typeof version === 'number' ? `M${version}` : String(version).toUpperCase();
+  if (!MICROQR_VERSION_NAMES.includes(result)) throw new RangeError(`Micro QR: version must be M1-M4, got ${version}`);
+  return result;
+}
+
+/** @param {string|number} version @returns {number} */
+export function microQrVersionSize(version) {
+  return 9 + Number(canonicalVersion(version).slice(1)) * 2;
+}
+
+/** Resolve the format symbol number for a legal version/ECC pair. */
+export function microQrSymbolNumber(version, ecc) {
+  return microQrBlockLayout(version, ecc).symbolNumber;
+}
+
+/** Resolve the immutable single-block layout for a legal version/ECC pair. */
+export function microQrBlockLayout(version, ecc) {
+  const canonical = canonicalVersion(version);
+  const level = ecc == null && canonical === 'M1' ? 'DETECT' : String(ecc).toUpperCase();
+  const entry = symbolByKey.get(`${canonical}:${level}`);
+  if (!entry) throw new RangeError(`Micro QR: error correction level ${ecc} is not valid for ${canonical}`);
+  return entry;
+}
+
+/** @returns {number} Usable message bits, including mode/count overhead. */
+export function microQrDataCapacityBits(version, ecc) {
+  return microQrBlockLayout(version, ecc).dataBits;
+}
+
+/**
+ * Encode the five format data bits with BCH(15,5), then apply the Micro QR
+ * format mask. `symbolNumber` occupies the high three data bits and `mask`
+ * the low two.
+ */
+export function microQrFormatInfo(symbolNumber, mask, maybeMask) {
+  // Public convenience overload: (version, ecc, mask).
+  if (arguments.length === 3) {
+    symbolNumber = microQrSymbolNumber(symbolNumber, mask);
+    mask = maybeMask;
+  }
+  if (!Number.isInteger(symbolNumber) || symbolNumber < 0 || symbolNumber > 7) {
+    throw new RangeError('Micro QR: symbol number must be an integer in 0..7');
+  }
+  if (!Number.isInteger(mask) || mask < 0 || mask > 3) {
+    throw new RangeError('Micro QR: mask must be an integer in 0..3');
+  }
+  const data = (symbolNumber << 2) | mask;
+  let remainder = data << 10;
+  for (let bit = 14; bit >= 10; bit--) {
+    if ((remainder & (1 << bit)) !== 0) remainder ^= MICROQR_FORMAT_GENERATOR << (bit - 10);
+  }
+  return ((data << 10) | remainder) ^ MICROQR_FORMAT_MASK;
+}
+
+function hammingDistance(a, b) {
+  let bits = (a ^ b) & 0x7fff;
+  let count = 0;
+  while (bits) { bits &= bits - 1; count++; }
+  return count;
+}
+
+/** Decode/correct a 15-bit format word. Returns null beyond three errors. */
+export function microQrDecodeFormatInfo(bits) {
+  if (!Number.isInteger(bits) || bits < 0 || bits > 0x7fff) {
+    throw new RangeError('Micro QR: format information must be a 15-bit integer');
+  }
+  let best = null;
+  let bestDistance = 16;
+  for (const entry of MICROQR_SYMBOLS) for (let mask = 0; mask < 4; mask++) {
+    const expected = microQrFormatInfo(entry.symbolNumber, mask);
+    const distance = hammingDistance(bits, expected);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = { version: entry.version, ecc: entry.ecc, symbolNumber: entry.symbolNumber, mask, correctedBits: distance, bits: expected };
+    }
+  }
+  return bestDistance <= 3 ? best : null;
+}
+
+/**
+ * Format modules in bit-number order, least significant bit first. Bits 0..7
+ * run down column 8; bits 8..14 continue right-to-left along row 8.
+ * Position (8,8) is shared by the two arms and appears once.
+ */
+export function microQrFormatInfoPositions(sizeOrVersion) {
+  const size = typeof sizeOrVersion === 'number' && sizeOrVersion >= 11
+    ? sizeOrVersion
+    : microQrVersionSize(sizeOrVersion);
+  if (![11, 13, 15, 17].includes(size)) throw new RangeError(`Micro QR: invalid symbol size ${size}`);
+  const positions = [];
+  for (let y = 1; y <= 8; y++) positions.push([8, y]);
+  for (let x = 7; x >= 1; x--) positions.push([x, 8]);
+  return positions;
+}
+
+const reservedCache = new Map();
+const functionCache = new Map();
+
+/**
+ * Fixed dark function modules before format information is written. Light
+ * separator and light timing modules remain unset; use
+ * {@link microQrReservedModules} to distinguish them from payload modules.
+ */
+export function microQrFunctionModules(version) {
+  const canonical = canonicalVersion(version);
+  const cached = functionCache.get(canonical);
+  if (cached) return cached;
+  const size = microQrVersionSize(canonical);
+  const matrix = new BitMatrix(size, size);
+  for (let y = 0; y < 7; y++) for (let x = 0; x < 7; x++) {
+    const outer = x === 0 || x === 6 || y === 0 || y === 6;
+    const centre = x >= 2 && x <= 4 && y >= 2 && y <= 4;
+    if (outer || centre) matrix.set(x, y);
+  }
+  for (let coordinate = 8; coordinate < size; coordinate += 2) {
+    matrix.set(coordinate, 0);
+    matrix.set(0, coordinate);
+  }
+  functionCache.set(canonical, matrix);
+  return matrix;
+}
+
+/** Shared immutable-in-use map of finder, separator, timing and format modules. */
+export function microQrReservedModules(version) {
+  const canonical = canonicalVersion(version);
+  const cached = reservedCache.get(canonical);
+  if (cached) return cached;
+  const size = microQrVersionSize(canonical);
+  const matrix = new BitMatrix(size, size);
+  matrix.setRegion(0, 0, 8, 8); // 7x7 finder plus inner separator
+  for (let coordinate = 8; coordinate < size; coordinate++) {
+    matrix.set(coordinate, 0); // horizontal timing
+    matrix.set(0, coordinate); // vertical timing
+  }
+  for (const [x, y] of microQrFormatInfoPositions(size)) matrix.set(x, y);
+  reservedCache.set(canonical, matrix);
+  return matrix;
+}
+
+/** Number of modules carrying data or error-correction bits. */
+export function microQrFreeModuleCount(version) {
+  const size = microQrVersionSize(version);
+  const reserved = microQrReservedModules(version);
+  let count = 0;
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    if (!reserved.get(x, y)) count++;
+  }
+  return count;
+}
+
+const orderCache = new Map();
+
+/** Payload module coordinates as interleaved x,y pairs, MSB-first stream order. */
+export function microQrDataModuleOrder(version) {
+  const canonical = canonicalVersion(version);
+  const cached = orderCache.get(canonical);
+  if (cached) return cached;
+  const size = microQrVersionSize(canonical);
+  const reserved = microQrReservedModules(canonical);
+  const order = new Int32Array(microQrFreeModuleCount(canonical) * 2);
+  let offset = 0;
+  let upward = true;
+  for (let column = size - 1; column > 0; column -= 2) {
+    for (let rowOffset = 0; rowOffset < size; rowOffset++) {
+      const y = upward ? size - 1 - rowOffset : rowOffset;
+      for (let side = 0; side < 2; side++) {
+        const x = column - side;
+        if (reserved.get(x, y)) continue;
+        order[offset++] = x;
+        order[offset++] = y;
+      }
+    }
+    upward = !upward;
+  }
+  orderCache.set(canonical, order);
+  return order;
+}
+
+/** The four Micro QR data-mask predicates. */
+export function microQrMaskBit(mask, x, y) {
+  switch (mask) {
+    case 0: return (y & 1) === 0;
+    case 1: return (((y >> 1) + Math.floor(x / 3)) & 1) === 0;
+    case 2: return ((((y * x) & 1) + ((y * x) % 3)) & 1) === 0;
+    case 3: return ((((y + x) & 1) + ((y * x) % 3)) & 1) === 0;
+    default: throw new RangeError(`Micro QR: mask must be an integer in 0..3, got ${mask}`);
+  }
+}
+
+/** Return all internal table/geometry invariant failures. */
+export function validateMicroQrTables() {
+  const issues = [];
+  if (MICROQR_SYMBOLS.length !== 8) issues.push('expected eight symbol/ECC combinations');
+  const numbers = new Set();
+  for (const entry of MICROQR_SYMBOLS) {
+    const tag = `${entry.version}-${entry.ecc}`;
+    if (numbers.has(entry.symbolNumber)) issues.push(`${tag}: duplicate symbol number`);
+    numbers.add(entry.symbolNumber);
+    if (entry.blockCount !== 1) issues.push(`${tag}: Micro QR must use one block`);
+    if (entry.dataBits + entry.eccCodewords * 8 !== microQrFreeModuleCount(entry.version)) {
+      issues.push(`${tag}: data/ECC bits do not fill the encoding region`);
+    }
+    if (entry.totalCodewords !== entry.dataCodewords + entry.eccCodewords) issues.push(`${tag}: codeword count mismatch`);
+    if (entry.dataBits !== (entry.dataCodewords - 1) * 8 + entry.shortDataCodewordBits) issues.push(`${tag}: final data codeword mismatch`);
+    if (entry.shortDataCodewordBits !== (entry.version === 'M1' || entry.version === 'M3' ? 4 : 8)) issues.push(`${tag}: wrong final data codeword width`);
+  }
+  for (const version of MICROQR_VERSIONS) {
+    const size = microQrVersionSize(version);
+    const positions = microQrFormatInfoPositions(size);
+    const unique = new Set(positions.map(([x, y]) => `${x},${y}`));
+    if (positions.length !== 15 || unique.size !== 15) issues.push(`${version}: format positions must be 15 unique modules`);
+    const order = microQrDataModuleOrder(version);
+    const orderUnique = new Set();
+    for (let i = 0; i < order.length; i += 2) {
+      const x = order[i], y = order[i + 1];
+      if (microQrReservedModules(version).get(x, y)) issues.push(`${version}: placement enters reserved module ${x},${y}`);
+      orderUnique.add(`${x},${y}`);
+    }
+    if (orderUnique.size * 2 !== order.length) issues.push(`${version}: placement repeats a module`);
+    if (order.length !== microQrFreeModuleCount(version) * 2) issues.push(`${version}: placement does not cover encoding region`);
+    const functions = microQrFunctionModules(version);
+    for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+      if (functions.get(x, y) && !microQrReservedModules(version).get(x, y)) {
+        issues.push(`${version}: dark function module ${x},${y} is not reserved`);
+      }
+    }
+  }
+  for (const entry of MICROQR_SYMBOLS) for (let mask = 0; mask < 4; mask++) {
+    const decoded = microQrDecodeFormatInfo(microQrFormatInfo(entry.symbolNumber, mask));
+    if (!decoded || decoded.symbolNumber !== entry.symbolNumber || decoded.mask !== mask || decoded.correctedBits !== 0) {
+      issues.push(`${entry.version}-${entry.ecc}: format round-trip failed for mask ${mask}`);
+    }
+  }
+  return issues;
+}