quadqr-js 0.7.0

package/dist/quadqr.min.js

@@ -0,0 +1,3593 @@
+(function (global) {
+"use strict";
+const __qqrScriptSrc = typeof document !== 'undefined' ? document.currentScript?.src || null : null;
+const __qqr_geometry_js = (function () {
+
+const MIN_GEOMETRY_VERSION = 1;
+const MAX_GEOMETRY_VERSION = 40;
+
+// Index by version. Entry 0 is unused. Values are module indices of alignment
+// pattern centers, matching the standard QR Code version layout for v2..v40.
+const ALIGNMENT_PATTERN_AXES = Object.freeze([
+  null,
+  Object.freeze([]),
+  Object.freeze([6, 18]),
+  Object.freeze([6, 22]),
+  Object.freeze([6, 26]),
+  Object.freeze([6, 30]),
+  Object.freeze([6, 34]),
+  Object.freeze([6, 22, 38]),
+  Object.freeze([6, 24, 42]),
+  Object.freeze([6, 26, 46]),
+  Object.freeze([6, 28, 50]),
+  Object.freeze([6, 30, 54]),
+  Object.freeze([6, 32, 58]),
+  Object.freeze([6, 34, 62]),
+  Object.freeze([6, 26, 46, 66]),
+  Object.freeze([6, 26, 48, 70]),
+  Object.freeze([6, 26, 50, 74]),
+  Object.freeze([6, 30, 54, 78]),
+  Object.freeze([6, 30, 56, 82]),
+  Object.freeze([6, 30, 58, 86]),
+  Object.freeze([6, 34, 62, 90]),
+  Object.freeze([6, 28, 50, 72, 94]),
+  Object.freeze([6, 26, 50, 74, 98]),
+  Object.freeze([6, 30, 54, 78, 102]),
+  Object.freeze([6, 28, 54, 80, 106]),
+  Object.freeze([6, 32, 58, 84, 110]),
+  Object.freeze([6, 30, 58, 86, 114]),
+  Object.freeze([6, 34, 62, 90, 118]),
+  Object.freeze([6, 26, 50, 74, 98, 122]),
+  Object.freeze([6, 30, 54, 78, 102, 126]),
+  Object.freeze([6, 26, 52, 78, 104, 130]),
+  Object.freeze([6, 30, 56, 82, 108, 134]),
+  Object.freeze([6, 34, 60, 86, 112, 138]),
+  Object.freeze([6, 30, 58, 86, 114, 142]),
+  Object.freeze([6, 34, 62, 90, 118, 146]),
+  Object.freeze([6, 30, 54, 78, 102, 126, 150]),
+  Object.freeze([6, 24, 50, 76, 102, 128, 154]),
+  Object.freeze([6, 28, 54, 80, 106, 132, 158]),
+  Object.freeze([6, 32, 58, 84, 110, 136, 162]),
+  Object.freeze([6, 26, 54, 82, 110, 138, 166]),
+  Object.freeze([6, 30, 58, 86, 114, 142, 170])
+]);
+
+function assertVersion(version) {
+  if (!Number.isInteger(version) || version < MIN_GEOMETRY_VERSION || version > MAX_GEOMETRY_VERSION) {
+    throw new Error(`Version must be ${MIN_GEOMETRY_VERSION}..${MAX_GEOMETRY_VERSION}.`);
+  }
+}
+
+function sizeForVersion(version) {
+  assertVersion(version);
+  return 21 + 4 * (version - 1);
+}
+
+function versionFromSize(size) {
+  const delta = size - 21;
+  if (delta < 0 || delta % 4 !== 0) return null;
+  const version = delta / 4 + 1;
+  return Number.isInteger(version) && version >= MIN_GEOMETRY_VERSION && version <= MAX_GEOMETRY_VERSION
+    ? version
+    : null;
+}
+
+function alignmentPatternCentersForVersion(version) {
+  assertVersion(version);
+  const size = sizeForVersion(version);
+
+  if (version === 1) {
+    const center = size - 4;
+    return [{
+      row: center,
+      col: center,
+      size: 5,
+      primary: true,
+      bootstrap: true,
+      separator: true
+    }];
+  }
+
+  const axes = ALIGNMENT_PATTERN_AXES[version];
+  const last = axes[axes.length - 1];
+  const centers = [];
+
+  for (const row of axes) {
+    for (const col of axes) {
+      // These three locations are occupied by the primary finder patterns.
+      if (
+        (row === 6 && col === 6) ||
+        (row === 6 && col === last) ||
+        (row === last && col === 6)
+      ) {
+        continue;
+      }
+      const primary = row === last && col === last;
+      centers.push({
+        row,
+        col,
+        size: primary ? 5 : 3,
+        primary,
+        bootstrap: false,
+        separator: false
+      });
+    }
+  }
+
+  return centers;
+}
+
+function primaryAlignmentPatternForVersion(version) {
+  const centers = alignmentPatternCentersForVersion(version);
+  return centers.find((pattern) => pattern.primary) ?? centers[centers.length - 1];
+}
+
+function alignmentPatternRadius(pattern) {
+  return pattern.size === 3 ? 1 : 2;
+}
+
+function alignmentPatternIsBlack(pattern, rowOffset, colOffset) {
+  const radius = alignmentPatternRadius(pattern);
+  if (Math.abs(rowOffset) > radius || Math.abs(colOffset) > radius) return null;
+
+  if (pattern.size === 3) {
+    // Compact secondary marker: black 3x3 ring with a white center.
+    return rowOffset !== 0 || colOffset !== 0;
+  }
+
+  // Primary 5x5 marker: black outer ring, white inner ring, black center.
+  const outer = Math.abs(rowOffset) === 2 || Math.abs(colOffset) === 2;
+  const center = rowOffset === 0 && colOffset === 0;
+  return outer || center;
+}
+
+return { sizeForVersion, versionFromSize, alignmentPatternCentersForVersion, primaryAlignmentPatternForVersion, alignmentPatternRadius, alignmentPatternIsBlack, MIN_GEOMETRY_VERSION, MAX_GEOMETRY_VERSION, ALIGNMENT_PATTERN_AXES };
+})();
+const __qqr_reed_solomon_js = (function () {
+
+const FIELD_SIZE = 256;
+const FIELD_ORDER = 255;
+const MAX_CODEWORD_SYMBOLS = 255;
+
+const PRIMITIVE_POLYNOMIAL = 0x11d;
+const EXP = new Uint16Array(FIELD_ORDER * 2);
+const LOG = new Int16Array(FIELD_SIZE);
+LOG.fill(-1);
+
+(function initTables() {
+  let value = 1;
+  for (let i = 0; i < FIELD_ORDER; i++) {
+    EXP[i] = value;
+    LOG[value] = i;
+    value <<= 1;
+    if (value & 0x100) value ^= PRIMITIVE_POLYNOMIAL;
+  }
+  for (let i = FIELD_ORDER; i < EXP.length; i++) {
+    EXP[i] = EXP[i - FIELD_ORDER];
+  }
+})();
+
+function assertFieldValue(value) {
+  if (!Number.isInteger(value) || value < 0 || value >= FIELD_SIZE) {
+    throw new Error("GF(256) symbol must be an integer from 0 to 255.");
+  }
+}
+
+function gfAdd(a, b) {
+  return a ^ b;
+}
+
+function gfNeg(a) {
+  return a;
+}
+
+function gfSub(a, b) {
+  return a ^ b;
+}
+
+function gfMul(a, b) {
+  if (a === 0 || b === 0) return 0;
+  return EXP[(LOG[a] + LOG[b]) % FIELD_ORDER];
+}
+
+function gfDiv(a, b) {
+  if (b === 0) throw new Error("Division by zero in GF(256).");
+  if (a === 0) return 0;
+  let power = LOG[a] - LOG[b];
+  if (power < 0) power += FIELD_ORDER;
+  return EXP[power];
+}
+
+function gfPow(a, power) {
+  if (power === 0) return 1;
+  if (a === 0) return 0;
+  let p = (LOG[a] * power) % FIELD_ORDER;
+  if (p < 0) p += FIELD_ORDER;
+  return EXP[p];
+}
+
+function gfAlphaPow(power) {
+  let p = power % FIELD_ORDER;
+  if (p < 0) p += FIELD_ORDER;
+  return EXP[p];
+}
+
+function polyEvalHigh(coeffs, x) {
+  let y = 0;
+  for (const coeff of coeffs) y = gfAdd(gfMul(y, x), coeff);
+  return y;
+}
+
+function locatorEvalLow(coeffs, x) {
+  let y = 0;
+  let xp = 1;
+  for (const coeff of coeffs) {
+    y = gfAdd(y, gfMul(coeff, xp));
+    xp = gfMul(xp, x);
+  }
+  return y;
+}
+
+function buildGenerator(paritySymbols, firstConsecutiveRoot = 0) {
+  let generator = [1];
+  for (let i = 0; i < paritySymbols; i++) {
+    const root = gfAlphaPow(firstConsecutiveRoot + i);
+    const factor = [1, root]; // x - root === x + root in characteristic 2
+    const next = new Array(generator.length + 1).fill(0);
+    for (let a = 0; a < generator.length; a++) {
+      for (let b = 0; b < factor.length; b++) {
+        next[a + b] = gfAdd(next[a + b], gfMul(generator[a], factor[b]));
+      }
+    }
+    generator = next;
+  }
+  return generator;
+}
+
+const GENERATOR_CACHE = new Map();
+function getGenerator(paritySymbols, firstConsecutiveRoot = 0) {
+  const key = `${paritySymbols}:${firstConsecutiveRoot}`;
+  if (!GENERATOR_CACHE.has(key)) {
+    GENERATOR_CACHE.set(key, buildGenerator(paritySymbols, firstConsecutiveRoot));
+  }
+  return GENERATOR_CACHE.get(key);
+}
+
+function rsEncode(dataSymbols, paritySymbols, options = {}) {
+  const data = Array.from(dataSymbols);
+  const fcr = options.firstConsecutiveRoot ?? 0;
+
+  if (!Number.isInteger(paritySymbols) || paritySymbols <= 0) {
+    throw new Error("paritySymbols must be a positive integer.");
+  }
+  if (data.length + paritySymbols > MAX_CODEWORD_SYMBOLS) {
+    throw new Error(`RS codeword exceeds ${MAX_CODEWORD_SYMBOLS} GF(256) symbols.`);
+  }
+  for (const value of data) assertFieldValue(value);
+
+  const generator = getGenerator(paritySymbols, fcr);
+  const work = data.concat(new Array(paritySymbols).fill(0));
+
+  for (let i = 0; i < data.length; i++) {
+    const coef = work[i];
+    if (coef === 0) continue;
+    for (let j = 0; j < generator.length; j++) {
+      work[i + j] = gfSub(work[i + j], gfMul(coef, generator[j]));
+    }
+  }
+
+  const parity = work.slice(data.length).map(gfNeg);
+  return data.concat(parity);
+}
+
+function rsSyndromes(codeword, paritySymbols, options = {}) {
+  const fcr = options.firstConsecutiveRoot ?? 0;
+  const values = Array.from(codeword);
+  return Array.from({ length: paritySymbols }, (_, i) =>
+    polyEvalHigh(values, gfAlphaPow(fcr + i))
+  );
+}
+
+function allZero(values) {
+  return values.every((value) => value === 0);
+}
+
+function berlekampMassey(syndromes) {
+  const n = syndromes.length;
+  const C = new Array(n + 1).fill(0);
+  const B = new Array(n + 1).fill(0);
+  C[0] = 1;
+  B[0] = 1;
+
+  let L = 0;
+  let m = 1;
+  let b = 1;
+
+  for (let index = 0; index < n; index++) {
+    let discrepancy = syndromes[index];
+    for (let i = 1; i <= L; i++) {
+      discrepancy = gfAdd(discrepancy, gfMul(C[i], syndromes[index - i]));
+    }
+
+    if (discrepancy === 0) {
+      m++;
+      continue;
+    }
+
+    const T = C.slice();
+    const scale = gfDiv(discrepancy, b);
+    for (let i = 0; i + m < C.length; i++) {
+      if (B[i] !== 0) C[i + m] = gfSub(C[i + m], gfMul(scale, B[i]));
+    }
+
+    if (2 * L <= index) {
+      L = index + 1 - L;
+      for (let i = 0; i < B.length; i++) B[i] = T[i];
+      b = discrepancy;
+      m = 1;
+    } else {
+      m++;
+    }
+  }
+
+  return { locator: C.slice(0, L + 1), errorCount: L };
+}
+
+function findErrorPositions(locator, codewordLength) {
+  const positions = [];
+  for (let power = 0; power < codewordLength; power++) {
+    const x = gfAlphaPow(-power);
+    if (locatorEvalLow(locator, x) === 0) {
+      positions.push(codewordLength - 1 - power);
+    }
+  }
+  return positions;
+}
+
+function solveLinearSystem(matrix, vector) {
+  const n = vector.length;
+  const a = matrix.map((row, r) => row.slice().concat([vector[r]]));
+
+  for (let col = 0; col < n; col++) {
+    let pivot = col;
+    while (pivot < n && a[pivot][col] === 0) pivot++;
+    if (pivot === n) throw new Error("Singular GF(256) system while solving RS magnitudes.");
+
+    if (pivot !== col) [a[col], a[pivot]] = [a[pivot], a[col]];
+
+    const invPivot = gfDiv(1, a[col][col]);
+    for (let j = col; j <= n; j++) a[col][j] = gfMul(a[col][j], invPivot);
+
+    for (let row = 0; row < n; row++) {
+      if (row === col || a[row][col] === 0) continue;
+      const factor = a[row][col];
+      for (let j = col; j <= n; j++) {
+        a[row][j] = gfSub(a[row][j], gfMul(factor, a[col][j]));
+      }
+    }
+  }
+
+  return a.map((row) => row[n]);
+}
+
+function solveErrorMagnitudes(syndromes, positions, codewordLength, firstConsecutiveRoot) {
+  const count = positions.length;
+  const matrix = Array.from({ length: count }, () => new Array(count).fill(0));
+  const vector = syndromes.slice(0, count);
+
+  for (let row = 0; row < count; row++) {
+    const rootPower = firstConsecutiveRoot + row;
+    for (let col = 0; col < count; col++) {
+      const polynomialPower = codewordLength - 1 - positions[col];
+      matrix[row][col] = gfAlphaPow(rootPower * polynomialPower);
+    }
+  }
+
+  return solveLinearSystem(matrix, vector);
+}
+
+function normalizeErasurePositions(positions, codewordLength) {
+  if (positions == null) return [];
+  if (!Array.isArray(positions)) throw new Error("erasurePositions must be an array of symbol indexes.");
+  const unique = [...new Set(positions)];
+  for (const position of unique) {
+    if (!Number.isInteger(position) || position < 0 || position >= codewordLength) {
+      throw new Error(`Invalid Reed-Solomon erasure position ${position}.`);
+    }
+  }
+  return unique.sort((a, b) => a - b);
+}
+
+// Remove the contribution of known erasure locations from the syndrome
+// sequence. Berlekamp-Massey can then solve only for the remaining unknown
+// errors. This is the standard Forney-syndrome reduction, expressed using the
+// same coefficient/root convention as the rest of this small codec.
+function forneySyndromes(syndromes, erasurePositions, codewordLength) {
+  const reduced = syndromes.slice();
+  for (const position of erasurePositions) {
+    const polynomialPower = codewordLength - 1 - position;
+    const x = gfAlphaPow(polynomialPower);
+    for (let i = 0; i < reduced.length - 1; i++) {
+      reduced[i] = gfAdd(gfMul(reduced[i], x), reduced[i + 1]);
+    }
+    reduced.pop();
+  }
+  return reduced;
+}
+
+function rsDecode(codeword, paritySymbols, options = {}) {
+  const values = Array.from(codeword);
+  const fcr = options.firstConsecutiveRoot ?? 0;
+
+  if (values.length > MAX_CODEWORD_SYMBOLS) {
+    throw new Error(`RS codeword exceeds ${MAX_CODEWORD_SYMBOLS} GF(256) symbols.`);
+  }
+  if (paritySymbols <= 0 || paritySymbols >= values.length) {
+    throw new Error("Invalid Reed-Solomon parity length.");
+  }
+  for (const value of values) assertFieldValue(value);
+
+  const erasurePositions = normalizeErasurePositions(options.erasurePositions, values.length);
+  if (erasurePositions.length > paritySymbols) {
+    throw new Error(
+      `Reed-Solomon has ${erasurePositions.length} erasures but only ${paritySymbols} parity symbols.`
+    );
+  }
+
+  const syndromes = rsSyndromes(values, paritySymbols, { firstConsecutiveRoot: fcr });
+  if (allZero(syndromes)) {
+    return {
+      corrected: values,
+      data: values.slice(0, values.length - paritySymbols),
+      correctedSymbols: 0,
+      erasureSymbols: 0,
+      unknownErrorSymbols: 0,
+      errorPositions: []
+    };
+  }
+
+  let unknownPositions = [];
+  if (erasurePositions.length < paritySymbols) {
+    const reducedSyndromes = erasurePositions.length
+      ? forneySyndromes(syndromes, erasurePositions, values.length)
+      : syndromes;
+
+    if (!allZero(reducedSyndromes)) {
+      const { locator, errorCount } = berlekampMassey(reducedSyndromes);
+      const unknownCorrectionLimit = Math.floor((paritySymbols - erasurePositions.length) / 2);
+      if (errorCount <= 0 || errorCount > unknownCorrectionLimit) {
+        throw new Error(
+          `Reed-Solomon found ${errorCount} unknown symbol errors with ${erasurePositions.length} erasures; ` +
+          `limit is ${unknownCorrectionLimit} unknown errors.`
+        );
+      }
+
+      unknownPositions = findErrorPositions(locator, values.length)
+        .filter((position) => !erasurePositions.includes(position));
+      if (unknownPositions.length !== errorCount) {
+        throw new Error(`Reed-Solomon locator found ${unknownPositions.length}/${errorCount} unknown error positions.`);
+      }
+    }
+  }
+
+  const positions = [...new Set(erasurePositions.concat(unknownPositions))].sort((a, b) => a - b);
+  if (positions.length === 0) {
+    throw new Error("Reed-Solomon syndromes are non-zero but no correction positions were found.");
+  }
+  if (2 * unknownPositions.length + erasurePositions.length > paritySymbols) {
+    throw new Error(
+      `Reed-Solomon error/erasure budget exceeded: 2*${unknownPositions.length} + ` +
+      `${erasurePositions.length} > ${paritySymbols}.`
+    );
+  }
+
+  const magnitudes = solveErrorMagnitudes(syndromes, positions, values.length, fcr);
+  const corrected = values.slice();
+  for (let i = 0; i < positions.length; i++) {
+    corrected[positions[i]] = gfSub(corrected[positions[i]], magnitudes[i]);
+  }
+
+  const check = rsSyndromes(corrected, paritySymbols, { firstConsecutiveRoot: fcr });
+  if (!allZero(check)) throw new Error("Reed-Solomon correction failed syndrome verification.");
+
+  return {
+    corrected,
+    data: corrected.slice(0, corrected.length - paritySymbols),
+    correctedSymbols: positions.length,
+    erasureSymbols: erasurePositions.length,
+    unknownErrorSymbols: unknownPositions.length,
+    errorPositions: positions
+  };
+}
+
+const gf256Internals = Object.freeze({
+  EXP,
+  LOG,
+  PRIMITIVE_POLYNOMIAL,
+  buildGenerator,
+  berlekampMassey,
+  findErrorPositions
+});
+
+return { gfAdd, gfNeg, gfSub, gfMul, gfDiv, gfPow, gfAlphaPow, rsEncode, rsSyndromes, rsDecode, FIELD_SIZE, FIELD_ORDER, MAX_CODEWORD_SYMBOLS, gf256Internals };
+})();
+const __qqr_security_js = (function () {
+
+const SECURE_PAYLOAD_VERSION = 1;
+const DEFAULT_PBKDF2_ITERATIONS = 600_000;
+const MIN_PBKDF2_ITERATIONS = 100_000;
+const MAX_PBKDF2_ITERATIONS = 2_000_000;
+
+const SECURITY_MODES = Object.freeze({
+  PASSWORD: "password",
+  RAW_KEY: "raw-key"
+});
+
+const SECURITY_ALGORITHMS = Object.freeze({
+  AES_256_GCM: "AES-256-GCM"
+});
+
+const MAGIC = new Uint8Array([0x51, 0x53, 0x45, 0x43]); // QSEC
+const MODE_PASSWORD = 1;
+const MODE_RAW_KEY = 2;
+const ALGORITHM_AES_256_GCM = 1;
+const KDF_NONE = 0;
+const KDF_PBKDF2_SHA256 = 1;
+const FLAG_KEY_ID_UTF8 = 1;
+const FLAG_KEY_ID_AUTO = 1 << 1;
+const FIXED_HEADER_BYTES = 24;
+const SALT_BYTES = 16;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const AUTO_KEY_ID_BYTES = 8;
+const MAX_KEY_ID_BYTES = 32;
+
+const encoder = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
+const decoder = typeof TextDecoder !== "undefined" ? new TextDecoder("utf-8", { fatal: false }) : null;
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function cryptoApi() {
+  const api = globalThis.crypto;
+  assert(api?.subtle && typeof api.getRandomValues === "function", "Web Crypto API is required for QuadQR secure payloads.");
+  return api;
+}
+
+function concatBytes(...arrays) {
+  const length = arrays.reduce((sum, value) => sum + value.length, 0);
+  const output = new Uint8Array(length);
+  let offset = 0;
+  for (const value of arrays) {
+    output.set(value, offset);
+    offset += value.length;
+  }
+  return output;
+}
+
+function u32be(value) {
+  const v = value >>> 0;
+  return new Uint8Array([
+    (v >>> 24) & 0xff,
+    (v >>> 16) & 0xff,
+    (v >>> 8) & 0xff,
+    v & 0xff
+  ]);
+}
+
+function readU32be(bytes, offset) {
+  return (
+    ((bytes[offset] << 24) >>> 0) |
+    (bytes[offset + 1] << 16) |
+    (bytes[offset + 2] << 8) |
+    bytes[offset + 3]
+  ) >>> 0;
+}
+
+function equalPrefix(bytes, prefix) {
+  if (bytes.length < prefix.length) return false;
+  for (let index = 0; index < prefix.length; index++) {
+    if (bytes[index] !== prefix[index]) return false;
+  }
+  return true;
+}
+
+function toBytes(value) {
+  if (value instanceof Uint8Array) return new Uint8Array(value);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  }
+  return new Uint8Array(value);
+}
+
+function bytesToHex(bytes) {
+  return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+
+function hexToBytes(hex) {
+  const clean = String(hex).trim().replace(/^0x/i, "").replace(/[\s:-]/g, "");
+  assert(clean.length % 2 === 0 && /^[0-9a-f]*$/i.test(clean), "Expected a hexadecimal byte string.");
+  const output = new Uint8Array(clean.length / 2);
+  for (let index = 0; index < output.length; index++) {
+    output[index] = parseInt(clean.slice(index * 2, index * 2 + 2), 16);
+  }
+  return output;
+}
+
+function normalizeRaw256Key(key) {
+  const bytes = typeof key === "string" ? hexToBytes(key) : toBytes(key);
+  assert(bytes.length === 32, "Raw QuadQR encryption key must be exactly 32 bytes (256 bits / 64 hex characters).");
+  return bytes;
+}
+
+function generateRaw256Key() {
+  const key = new Uint8Array(32);
+  cryptoApi().getRandomValues(key);
+  return key;
+}
+
+function randomBytes(length) {
+  const bytes = new Uint8Array(length);
+  cryptoApi().getRandomValues(bytes);
+  return bytes;
+}
+
+function normalizeMode(mode) {
+  const value = String(mode ?? "").toLowerCase();
+  if (["password", "passphrase"].includes(value)) return SECURITY_MODES.PASSWORD;
+  if (["raw-key", "raw", "key", "raw256", "raw-256"].includes(value)) return SECURITY_MODES.RAW_KEY;
+  throw new Error('Security mode must be "password" or "raw-key".');
+}
+
+function encodeKeyId(keyId) {
+  if (keyId == null || keyId === false) return { bytes: new Uint8Array(0), utf8: false, auto: false };
+  if (typeof keyId === "string") {
+    assert(encoder, "TextEncoder is required for string key IDs.");
+    const bytes = encoder.encode(keyId);
+    assert(bytes.length > 0 && bytes.length <= MAX_KEY_ID_BYTES, `Key ID must be 1..${MAX_KEY_ID_BYTES} UTF-8 bytes.`);
+    return { bytes, utf8: true, auto: false };
+  }
+  const bytes = toBytes(keyId);
+  assert(bytes.length > 0 && bytes.length <= MAX_KEY_ID_BYTES, `Key ID must be 1..${MAX_KEY_ID_BYTES} bytes.`);
+  return { bytes, utf8: false, auto: false };
+}
+
+async function autoKeyId(rawKey) {
+  const digest = new Uint8Array(await cryptoApi().subtle.digest("SHA-256", rawKey));
+  return digest.slice(0, AUTO_KEY_ID_BYTES);
+}
+
+async function derivePasswordKey(password, salt, iterations, usages) {
+  assert(typeof password === "string" && password.length > 0, "A non-empty password is required.");
+  assert(encoder, "TextEncoder is required for password encryption.");
+  assert(Number.isInteger(iterations), "PBKDF2 iteration count must be an integer.");
+  assert(
+    iterations >= MIN_PBKDF2_ITERATIONS && iterations <= MAX_PBKDF2_ITERATIONS,
+    `PBKDF2 iterations must be ${MIN_PBKDF2_ITERATIONS}..${MAX_PBKDF2_ITERATIONS}.`
+  );
+
+  const baseKey = await cryptoApi().subtle.importKey(
+    "raw",
+    encoder.encode(password),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+
+  return cryptoApi().subtle.deriveKey(
+    { name: "PBKDF2", hash: "SHA-256", salt, iterations },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    usages
+  );
+}
+
+async function importRawAesKey(rawKey, usages) {
+  return cryptoApi().subtle.importKey(
+    "raw",
+    normalizeRaw256Key(rawKey),
+    { name: "AES-GCM", length: 256 },
+    false,
+    usages
+  );
+}
+
+function makeFixedHeader({ modeId, kdfId, flags, saltLength, nonceLength, keyIdLength, iterations, plaintextLength }) {
+  const header = new Uint8Array(FIXED_HEADER_BYTES);
+  header.set(MAGIC, 0);
+  header[4] = SECURE_PAYLOAD_VERSION;
+  header[5] = modeId;
+  header[6] = ALGORITHM_AES_256_GCM;
+  header[7] = kdfId;
+  header[8] = flags;
+  header[9] = saltLength;
+  header[10] = nonceLength;
+  header[11] = TAG_BYTES;
+  header[12] = keyIdLength;
+  header[13] = 0;
+  header[14] = 0;
+  header[15] = 0;
+  header.set(u32be(iterations), 16);
+  header.set(u32be(plaintextLength), 20);
+  return header;
+}
+
+function parseEnvelope(envelope) {
+  const bytes = toBytes(envelope);
+  assert(bytes.length >= FIXED_HEADER_BYTES + NONCE_BYTES + TAG_BYTES, "Secure payload envelope is too short.");
+  assert(equalPrefix(bytes, MAGIC), "Secure payload magic mismatch.");
+  assert(bytes[4] === SECURE_PAYLOAD_VERSION, `Unsupported secure payload version ${bytes[4]}.`);
+  assert(bytes[6] === ALGORITHM_AES_256_GCM, `Unsupported secure payload algorithm id ${bytes[6]}.`);
+
+  const modeId = bytes[5];
+  const kdfId = bytes[7];
+  const flags = bytes[8];
+  const saltLength = bytes[9];
+  const nonceLength = bytes[10];
+  const tagLength = bytes[11];
+  const keyIdLength = bytes[12];
+  const iterations = readU32be(bytes, 16);
+  const plaintextLength = readU32be(bytes, 20);
+
+  assert(nonceLength === NONCE_BYTES, `Unsupported AES-GCM nonce length ${nonceLength}.`);
+  assert(tagLength === TAG_BYTES, `Unsupported AES-GCM tag length ${tagLength}.`);
+  assert(keyIdLength <= MAX_KEY_ID_BYTES, "Secure payload key ID is too long.");
+
+  let mode;
+  if (modeId === MODE_PASSWORD) {
+    mode = SECURITY_MODES.PASSWORD;
+    assert(kdfId === KDF_PBKDF2_SHA256, "Password payload uses an unsupported KDF.");
+    assert(saltLength === SALT_BYTES, `Password payload salt must be ${SALT_BYTES} bytes.`);
+    assert(iterations >= MIN_PBKDF2_ITERATIONS && iterations <= MAX_PBKDF2_ITERATIONS, "Password payload PBKDF2 iteration count is outside the supported safety range.");
+  } else if (modeId === MODE_RAW_KEY) {
+    mode = SECURITY_MODES.RAW_KEY;
+    assert(kdfId === KDF_NONE, "Raw-key payload must not declare a password KDF.");
+    assert(saltLength === 0, "Raw-key payload must not contain a password salt.");
+    assert(iterations === 0, "Raw-key payload must not declare PBKDF2 iterations.");
+  } else {
+    throw new Error(`Unsupported secure payload mode id ${modeId}.`);
+  }
+
+  const metadataLength = FIXED_HEADER_BYTES + keyIdLength + saltLength + nonceLength;
+  const expectedLength = metadataLength + plaintextLength + tagLength;
+  assert(bytes.length === expectedLength, `Secure payload length mismatch: expected ${expectedLength} bytes, got ${bytes.length}.`);
+
+  let cursor = FIXED_HEADER_BYTES;
+  const keyIdBytes = bytes.slice(cursor, cursor + keyIdLength);
+  cursor += keyIdLength;
+  const salt = bytes.slice(cursor, cursor + saltLength);
+  cursor += saltLength;
+  const nonce = bytes.slice(cursor, cursor + nonceLength);
+  cursor += nonceLength;
+  const ciphertextWithTag = bytes.slice(cursor);
+  const aad = bytes.slice(0, cursor);
+  const keyIdUtf8 = Boolean(flags & FLAG_KEY_ID_UTF8);
+  const keyIdAuto = Boolean(flags & FLAG_KEY_ID_AUTO);
+
+  return {
+    bytes,
+    mode,
+    modeId,
+    kdfId,
+    flags,
+    salt,
+    nonce,
+    iterations,
+    plaintextLength,
+    keyIdBytes,
+    keyIdUtf8,
+    keyIdAuto,
+    ciphertextWithTag,
+    aad
+  };
+}
+
+function inspectSecureEnvelope(envelope) {
+  const parsed = parseEnvelope(envelope);
+  return {
+    securePayloadVersion: SECURE_PAYLOAD_VERSION,
+    mode: parsed.mode,
+    algorithm: SECURITY_ALGORITHMS.AES_256_GCM,
+    kdf: parsed.mode === SECURITY_MODES.PASSWORD ? "PBKDF2-HMAC-SHA-256" : null,
+    iterations: parsed.mode === SECURITY_MODES.PASSWORD ? parsed.iterations : null,
+    keyId: parsed.keyIdUtf8 && decoder ? decoder.decode(parsed.keyIdBytes) : null,
+    keyIdHex: parsed.keyIdBytes.length ? bytesToHex(parsed.keyIdBytes) : null,
+    keyIdAuto: parsed.keyIdAuto,
+    plaintextBytes: parsed.plaintextLength,
+    envelopeBytes: parsed.bytes.length,
+    overheadBytes: parsed.bytes.length - parsed.plaintextLength,
+    authenticated: true
+  };
+}
+
+async function encryptSecurePayload(input, security = {}) {
+  const plaintext = toBytes(input);
+  const mode = normalizeMode(security.mode);
+  const nonce = randomBytes(NONCE_BYTES);
+  let aesKey;
+  let salt = new Uint8Array(0);
+  let iterations = 0;
+  let modeId;
+  let kdfId;
+  let keyId = { bytes: new Uint8Array(0), utf8: false, auto: false };
+
+  if (mode === SECURITY_MODES.PASSWORD) {
+    modeId = MODE_PASSWORD;
+    kdfId = KDF_PBKDF2_SHA256;
+    iterations = security.iterations ?? DEFAULT_PBKDF2_ITERATIONS;
+    salt = randomBytes(SALT_BYTES);
+    aesKey = await derivePasswordKey(security.password, salt, iterations, ["encrypt"]);
+    if (security.keyId != null && security.keyId !== false) keyId = encodeKeyId(security.keyId);
+  } else {
+    modeId = MODE_RAW_KEY;
+    kdfId = KDF_NONE;
+    const rawKey = normalizeRaw256Key(security.key);
+    aesKey = await importRawAesKey(rawKey, ["encrypt"]);
+    if (security.keyId === false) {
+      keyId = { bytes: new Uint8Array(0), utf8: false, auto: false };
+    } else if (security.keyId != null) {
+      keyId = encodeKeyId(security.keyId);
+    } else {
+      keyId = { bytes: await autoKeyId(rawKey), utf8: false, auto: true };
+    }
+  }
+
+  const flags = (keyId.utf8 ? FLAG_KEY_ID_UTF8 : 0) | (keyId.auto ? FLAG_KEY_ID_AUTO : 0);
+  const fixedHeader = makeFixedHeader({
+    modeId,
+    kdfId,
+    flags,
+    saltLength: salt.length,
+    nonceLength: nonce.length,
+    keyIdLength: keyId.bytes.length,
+    iterations,
+    plaintextLength: plaintext.length
+  });
+  const aad = concatBytes(fixedHeader, keyId.bytes, salt, nonce);
+  const ciphertextWithTag = new Uint8Array(await cryptoApi().subtle.encrypt(
+    { name: "AES-GCM", iv: nonce, additionalData: aad, tagLength: TAG_BYTES * 8 },
+    aesKey,
+    plaintext
+  ));
+  const envelope = concatBytes(aad, ciphertextWithTag);
+
+  return {
+    envelope,
+    metadata: inspectSecureEnvelope(envelope)
+  };
+}
+
+async function decryptSecurePayload(envelope, security = {}) {
+  const parsed = parseEnvelope(envelope);
+  let aesKey;
+
+  if (parsed.mode === SECURITY_MODES.PASSWORD) {
+    aesKey = await derivePasswordKey(security.password, parsed.salt, parsed.iterations, ["decrypt"]);
+  } else {
+    aesKey = await importRawAesKey(security.key, ["decrypt"]);
+
+    // Key IDs are routing hints, not secrets. When the envelope has an auto
+    // fingerprint ID, verify it before doing the more expensive GCM operation.
+    if (parsed.keyIdBytes.length && parsed.keyIdAuto && security.verifyKeyId !== false) {
+      const expected = await autoKeyId(normalizeRaw256Key(security.key));
+      if (expected.length === parsed.keyIdBytes.length) {
+        let mismatch = 0;
+        for (let index = 0; index < expected.length; index++) mismatch |= expected[index] ^ parsed.keyIdBytes[index];
+        assert(mismatch === 0, "Raw encryption key does not match this QuadQR key ID.");
+      }
+    }
+  }
+
+  try {
+    const plaintext = new Uint8Array(await cryptoApi().subtle.decrypt(
+      { name: "AES-GCM", iv: parsed.nonce, additionalData: parsed.aad, tagLength: TAG_BYTES * 8 },
+      aesKey,
+      parsed.ciphertextWithTag
+    ));
+    assert(plaintext.length === parsed.plaintextLength, "Secure payload plaintext length mismatch after decryption.");
+    return plaintext;
+  } catch (error) {
+    if (/key ID/i.test(error?.message ?? "")) throw error;
+    throw new Error("Secure QuadQR decryption failed. The password/key is wrong or the encrypted payload was modified.");
+  }
+}
+
+const securityInternals = Object.freeze({
+  FIXED_HEADER_BYTES,
+  SALT_BYTES,
+  NONCE_BYTES,
+  TAG_BYTES,
+  AUTO_KEY_ID_BYTES,
+  parseEnvelope
+});
+
+return { bytesToHex, hexToBytes, normalizeRaw256Key, generateRaw256Key, inspectSecureEnvelope, encryptSecurePayload, decryptSecurePayload, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, MIN_PBKDF2_ITERATIONS, MAX_PBKDF2_ITERATIONS, SECURITY_MODES, SECURITY_ALGORITHMS, securityInternals };
+})();
+const __qqr_vision_js = (function () {
+const { alignmentPatternCentersForVersion, alignmentPatternIsBlack, alignmentPatternRadius, primaryAlignmentPatternForVersion, sizeForVersion } = __qqr_geometry_js;
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function pixelRgb(imageData, x, y) {
+  const ix = clamp(Math.round(x), 0, imageData.width - 1);
+  const iy = clamp(Math.round(y), 0, imageData.height - 1);
+  const index = (iy * imageData.width + ix) * 4;
+  const a = imageData.data[index + 3] / 255;
+  return {
+    r: imageData.data[index] * a + 255 * (1 - a),
+    g: imageData.data[index + 1] * a + 255 * (1 - a),
+    b: imageData.data[index + 2] * a + 255 * (1 - a)
+  };
+}
+
+function bilinearRgb(imageData, x, y) {
+  const x0 = clamp(Math.floor(x), 0, imageData.width - 1);
+  const y0 = clamp(Math.floor(y), 0, imageData.height - 1);
+  const x1 = clamp(x0 + 1, 0, imageData.width - 1);
+  const y1 = clamp(y0 + 1, 0, imageData.height - 1);
+  const fx = clamp(x - x0, 0, 1);
+  const fy = clamp(y - y0, 0, 1);
+
+  const p00 = pixelRgb(imageData, x0, y0);
+  const p10 = pixelRgb(imageData, x1, y0);
+  const p01 = pixelRgb(imageData, x0, y1);
+  const p11 = pixelRgb(imageData, x1, y1);
+
+  const mix = (a, b, t) => a + (b - a) * t;
+  return {
+    r: mix(mix(p00.r, p10.r, fx), mix(p01.r, p11.r, fx), fy),
+    g: mix(mix(p00.g, p10.g, fx), mix(p01.g, p11.g, fx), fy),
+    b: mix(mix(p00.b, p10.b, fx), mix(p01.b, p11.b, fx), fy)
+  };
+}
+
+function luminance(rgb) {
+  return 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b;
+}
+
+function buildGray(imageData) {
+  const gray = new Uint8Array(imageData.width * imageData.height);
+  for (let i = 0; i < gray.length; i++) {
+    const p = i * 4;
+    const a = imageData.data[p + 3] / 255;
+    const r = imageData.data[p] * a + 255 * (1 - a);
+    const g = imageData.data[p + 1] * a + 255 * (1 - a);
+    const b = imageData.data[p + 2] * a + 255 * (1 - a);
+    gray[i] = Math.round(0.2126 * r + 0.7152 * g + 0.0722 * b);
+  }
+  return gray;
+}
+
+function otsuThreshold(gray) {
+  const histogram = new Uint32Array(256);
+  for (const value of gray) histogram[value]++;
+  const total = gray.length;
+  let sum = 0;
+  for (let i = 0; i < 256; i++) sum += i * histogram[i];
+
+  let sumBackground = 0;
+  let weightBackground = 0;
+  let maxVariance = -1;
+  let threshold = 127;
+
+  for (let t = 0; t < 256; t++) {
+    weightBackground += histogram[t];
+    if (weightBackground === 0) continue;
+    const weightForeground = total - weightBackground;
+    if (weightForeground === 0) break;
+    sumBackground += t * histogram[t];
+    const meanBackground = sumBackground / weightBackground;
+    const meanForeground = (sum - sumBackground) / weightForeground;
+    const diff = meanBackground - meanForeground;
+    const variance = weightBackground * weightForeground * diff * diff;
+    if (variance > maxVariance) {
+      maxVariance = variance;
+      threshold = t;
+    }
+  }
+
+  return threshold;
+}
+
+function buildBinary(imageData) {
+  const gray = buildGray(imageData);
+  const threshold = otsuThreshold(gray);
+  const binary = new Uint8Array(gray.length);
+  for (let i = 0; i < gray.length; i++) binary[i] = gray[i] <= threshold ? 1 : 0;
+  return { gray, binary, threshold };
+}
+
+function runsForRow(binary, width, row) {
+  const runs = [];
+  let color = binary[row * width];
+  let start = 0;
+  for (let x = 1; x < width; x++) {
+    const next = binary[row * width + x];
+    if (next !== color) {
+      runs.push({ color, start, length: x - start });
+      color = next;
+      start = x;
+    }
+  }
+  runs.push({ color, start, length: width - start });
+  return runs;
+}
+
+function runsForColumn(binary, width, height, col) {
+  const runs = [];
+  let color = binary[col];
+  let start = 0;
+  for (let y = 1; y < height; y++) {
+    const next = binary[y * width + col];
+    if (next !== color) {
+      runs.push({ color, start, length: y - start });
+      color = next;
+      start = y;
+    }
+  }
+  runs.push({ color, start, length: height - start });
+  return runs;
+}
+
+function finderRatioScore(lengths) {
+  const total = lengths.reduce((sum, value) => sum + value, 0);
+  if (total < 7) return Infinity;
+  const module = total / 7;
+  const expected = [module, module, 3 * module, module, module];
+  let score = 0;
+  for (let i = 0; i < 5; i++) {
+    const tolerance = i === 2 ? module * 1.25 : module * 0.8;
+    const diff = Math.abs(lengths[i] - expected[i]);
+    if (diff > tolerance) return Infinity;
+    score += diff / Math.max(1, expected[i]);
+  }
+  return score;
+}
+
+function findWindowContainingCoordinate(runs, coordinate) {
+  for (let i = 2; i < runs.length - 2; i++) {
+    const centerRun = runs[i];
+    if (centerRun.color !== 1) continue;
+    if (coordinate < centerRun.start || coordinate >= centerRun.start + centerRun.length) continue;
+    const window = runs.slice(i - 2, i + 3);
+    if (window.map((run) => run.color).join("") !== "10101") continue;
+    const score = finderRatioScore(window.map((run) => run.length));
+    if (!Number.isFinite(score)) continue;
+    const first = window[0].start;
+    const total = window.reduce((sum, run) => sum + run.length, 0);
+    return {
+      center: first + total / 2,
+      moduleSize: total / 7,
+      score
+    };
+  }
+  return null;
+}
+
+function crossCheckVertical(binary, width, height, x, y) {
+  const col = clamp(Math.round(x), 0, width - 1);
+  return findWindowContainingCoordinate(runsForColumn(binary, width, height, col), y);
+}
+
+function crossCheckHorizontal(binary, width, height, x, y) {
+  const row = clamp(Math.round(y), 0, height - 1);
+  return findWindowContainingCoordinate(runsForRow(binary, width, row), x);
+}
+
+function clusterFinderCandidates(raw) {
+  const clusters = [];
+  raw.sort((a, b) => a.moduleSize - b.moduleSize);
+
+  for (const candidate of raw) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const cluster of clusters) {
+      const moduleRatio = Math.abs(cluster.moduleSize - candidate.moduleSize) /
+        Math.max(cluster.moduleSize, candidate.moduleSize);
+      if (moduleRatio > 0.45) continue;
+      const dx = cluster.x - candidate.x;
+      const dy = cluster.y - candidate.y;
+      const distance = Math.hypot(dx, dy);
+      if (distance <= Math.max(cluster.moduleSize, candidate.moduleSize) * 2.25 && distance < bestDistance) {
+        best = cluster;
+        bestDistance = distance;
+      }
+    }
+
+    if (!best) {
+      clusters.push({ ...candidate, confirmations: 1 });
+    } else {
+      const n = best.confirmations;
+      best.x = (best.x * n + candidate.x) / (n + 1);
+      best.y = (best.y * n + candidate.y) / (n + 1);
+      best.moduleSize = (best.moduleSize * n + candidate.moduleSize) / (n + 1);
+      best.score = (best.score * n + candidate.score) / (n + 1);
+      best.confirmations++;
+    }
+  }
+
+  return clusters
+    .filter((candidate) => candidate.confirmations >= 2)
+    .sort((a, b) =>
+      (b.confirmations - a.confirmations) ||
+      (a.score - b.score) ||
+      (b.moduleSize - a.moduleSize)
+    );
+}
+
+function detectFinderCandidates(binary, width, height) {
+  const raw = [];
+  const rowStep = height > 1200 ? 2 : 1;
+
+  for (let y = 0; y < height; y += rowStep) {
+    const runs = runsForRow(binary, width, y);
+    for (let i = 0; i <= runs.length - 5; i++) {
+      const window = runs.slice(i, i + 5);
+      if (window.map((run) => run.color).join("") !== "10101") continue;
+      const lengths = window.map((run) => run.length);
+      const ratioScore = finderRatioScore(lengths);
+      if (!Number.isFinite(ratioScore)) continue;
+      const total = lengths.reduce((sum, value) => sum + value, 0);
+      const centerX = window[0].start + total / 2;
+      const vertical = crossCheckVertical(binary, width, height, centerX, y);
+      if (!vertical) continue;
+      const horizontal = crossCheckHorizontal(binary, width, height, centerX, vertical.center);
+      if (!horizontal) continue;
+
+      const moduleSize = (total / 7 + vertical.moduleSize + horizontal.moduleSize) / 3;
+      const moduleSpread = Math.max(
+        Math.abs(moduleSize - total / 7),
+        Math.abs(moduleSize - vertical.moduleSize),
+        Math.abs(moduleSize - horizontal.moduleSize)
+      ) / moduleSize;
+      if (moduleSpread > 0.45) continue;
+
+      raw.push({
+        x: horizontal.center,
+        y: vertical.center,
+        moduleSize,
+        score: ratioScore + vertical.score + horizontal.score
+      });
+    }
+  }
+
+  return clusterFinderCandidates(raw);
+}
+
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y;
+}
+
+function sub(a, b) {
+  return { x: a.x - b.x, y: a.y - b.y };
+}
+
+function cross(a, b) {
+  return a.x * b.y - a.y * b.x;
+}
+
+function chooseFinderTriples(candidates, maxTriples = 16) {
+  const top = candidates.slice(0, Math.min(candidates.length, 14));
+  const triples = [];
+
+  for (let a = 0; a < top.length - 2; a++) {
+    for (let b = a + 1; b < top.length - 1; b++) {
+      for (let c = b + 1; c < top.length; c++) {
+        const points = [top[a], top[b], top[c]];
+        for (let corner = 0; corner < 3; corner++) {
+          const tl = points[corner];
+          const other = points.filter((_, index) => index !== corner);
+          let tr = other[0];
+          let bl = other[1];
+          let u = sub(tr, tl);
+          let v = sub(bl, tl);
+          let d1 = Math.hypot(u.x, u.y);
+          let d2 = Math.hypot(v.x, v.y);
+          if (d1 < tl.moduleSize * 10 || d2 < tl.moduleSize * 10) continue;
+          const cos = Math.abs(dot(u, v) / (d1 * d2));
+          if (cos > 0.55) continue;
+          if (cross(u, v) < 0) {
+            [tr, bl] = [bl, tr];
+            u = sub(tr, tl);
+            v = sub(bl, tl);
+            d1 = Math.hypot(u.x, u.y);
+            d2 = Math.hypot(v.x, v.y);
+          }
+          const moduleMean = (tl.moduleSize + tr.moduleSize + bl.moduleSize) / 3;
+          const moduleSpread = Math.max(
+            Math.abs(tl.moduleSize - moduleMean),
+            Math.abs(tr.moduleSize - moduleMean),
+            Math.abs(bl.moduleSize - moduleMean)
+          ) / moduleMean;
+          if (moduleSpread > 0.5) continue;
+          const legRatio = Math.max(d1, d2) / Math.min(d1, d2);
+          if (legRatio > 2.1) continue;
+          const area = Math.abs(cross(u, v));
+          const confirmScore = tl.confirmations + tr.confirmations + bl.confirmations;
+          const score = area / (1 + cos * 8 + moduleSpread * 5 + Math.max(0, legRatio - 1) * 2) + confirmScore * 100;
+          triples.push({ tl, tr, bl, moduleMean, score, orthogonality: 1 - cos });
+        }
+      }
+    }
+  }
+
+  triples.sort((a, b) => b.score - a.score);
+  return triples.slice(0, maxTriples);
+}
+
+function nearestVersionFromEstimate(value, minVersion, maxVersion) {
+  const candidates = [];
+  for (let version = minVersion; version <= maxVersion; version++) {
+    const size = sizeForVersion(version);
+    candidates.push({ version, error: Math.abs(size - value) });
+  }
+  candidates.sort((a, b) => a.error - b.error);
+  return candidates;
+}
+
+function sampleBinaryAt(binary, width, height, x, y) {
+  const ix = Math.round(x);
+  const iy = Math.round(y);
+  if (ix < 0 || iy < 0 || ix >= width || iy >= height) return null;
+  return binary[iy * width + ix];
+}
+
+function alignmentTemplateValue(pattern, r, c) {
+  return alignmentPatternIsBlack(pattern, r, c) ? 1 : 0;
+}
+
+function alignmentScore(binary, width, height, center, basisU, basisV, scale, pattern) {
+  let matches = 0;
+  let total = 0;
+  const radius = alignmentPatternRadius(pattern);
+  for (let r = -radius; r <= radius; r++) {
+    for (let c = -radius; c <= radius; c++) {
+      const x = center.x + basisU.x * c * scale + basisV.x * r * scale;
+      const y = center.y + basisU.y * c * scale + basisV.y * r * scale;
+      const value = sampleBinaryAt(binary, width, height, x, y);
+      if (value === null) continue;
+      total++;
+      if (value === alignmentTemplateValue(pattern, r, c)) matches++;
+    }
+  }
+  return total ? matches / total : 0;
+}
+
+function searchAlignment(binary, width, height, triple, version) {
+  const size = sizeForVersion(version);
+  const separation = size - 7;
+  const basisU = {
+    x: (triple.tr.x - triple.tl.x) / separation,
+    y: (triple.tr.y - triple.tl.y) / separation
+  };
+  const basisV = {
+    x: (triple.bl.x - triple.tl.x) / separation,
+    y: (triple.bl.y - triple.tl.y) / separation
+  };
+  const target = primaryAlignmentPatternForVersion(version);
+  const targetX = target.col + 0.5;
+  const targetY = target.row + 0.5;
+  const predicted = {
+    x: triple.tl.x + basisU.x * (targetX - 3.5) + basisV.x * (targetY - 3.5),
+    y: triple.tl.y + basisU.y * (targetX - 3.5) + basisV.y * (targetY - 3.5)
+  };
+
+  let best = { score: 0, center: predicted, scale: 1 };
+  const offsets = [-2.5, -1.5, -0.75, 0, 0.75, 1.5, 2.5];
+  const scales = [0.72, 0.85, 1, 1.15, 1.3];
+
+  for (const ou of offsets) {
+    for (const ov of offsets) {
+      const center = {
+        x: predicted.x + basisU.x * ou + basisV.x * ov,
+        y: predicted.y + basisU.y * ou + basisV.y * ov
+      };
+      for (const scale of scales) {
+        const score = alignmentScore(binary, width, height, center, basisU, basisV, scale, target);
+        if (score > best.score) best = { score, center, scale };
+      }
+    }
+  }
+
+  return { ...best, basisU, basisV, predicted, target };
+}
+
+function projectedAlignmentScore(binary, width, height, homography, pattern) {
+  let matches = 0;
+  let total = 0;
+  const radius = alignmentPatternRadius(pattern);
+  for (let r = -radius; r <= radius; r++) {
+    for (let c = -radius; c <= radius; c++) {
+      const point = projectPoint(homography, pattern.col + c + 0.5, pattern.row + r + 0.5);
+      const value = sampleBinaryAt(binary, width, height, point.x, point.y);
+      if (value === null) continue;
+      total++;
+      if (value === alignmentTemplateValue(pattern, r, c)) matches++;
+    }
+  }
+  return total ? matches / total : 0;
+}
+
+function scoreAlignmentGrid(binary, width, height, homography, version) {
+  const patterns = alignmentPatternCentersForVersion(version);
+  if (!patterns.length) return { score: 1, patternScores: [] };
+  const patternScores = patterns.map((pattern) => ({
+    row: pattern.row,
+    col: pattern.col,
+    size: pattern.size,
+    primary: Boolean(pattern.primary),
+    score: projectedAlignmentScore(binary, width, height, homography, pattern)
+  }));
+  const totalWeight = patternScores.reduce((sum, item) => sum + (item.primary ? 2 : 1), 0);
+  const score = patternScores.reduce(
+    (sum, item) => sum + item.score * (item.primary ? 2 : 1),
+    0
+  ) / totalWeight;
+  return { score, patternScores };
+}
+
+function solveLinearSystemFloat(matrix, vector) {
+  const n = vector.length;
+  const a = matrix.map((row, index) => row.slice().concat([vector[index]]));
+  for (let col = 0; col < n; col++) {
+    let pivot = col;
+    for (let row = col + 1; row < n; row++) {
+      if (Math.abs(a[row][col]) > Math.abs(a[pivot][col])) pivot = row;
+    }
+    if (Math.abs(a[pivot][col]) < 1e-10) throw new Error("Singular homography system.");
+    if (pivot !== col) [a[col], a[pivot]] = [a[pivot], a[col]];
+    const divisor = a[col][col];
+    for (let j = col; j <= n; j++) a[col][j] /= divisor;
+    for (let row = 0; row < n; row++) {
+      if (row === col) continue;
+      const factor = a[row][col];
+      if (Math.abs(factor) < 1e-12) continue;
+      for (let j = col; j <= n; j++) a[row][j] -= factor * a[col][j];
+    }
+  }
+  return a.map((row) => row[n]);
+}
+
+function computeHomography(sourcePoints, destinationPoints) {
+  // Returns transform mapping destination -> source.
+  assert(sourcePoints.length === 4 && destinationPoints.length === 4, "Four point pairs are required.");
+  const A = [];
+  const b = [];
+  for (let i = 0; i < 4; i++) {
+    const u = destinationPoints[i].x;
+    const v = destinationPoints[i].y;
+    const x = sourcePoints[i].x;
+    const y = sourcePoints[i].y;
+    A.push([u, v, 1, 0, 0, 0, -u * x, -v * x]);
+    b.push(x);
+    A.push([0, 0, 0, u, v, 1, -u * y, -v * y]);
+    b.push(y);
+  }
+  const h = solveLinearSystemFloat(A, b);
+  return [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7], 1];
+}
+
+function projectPoint(h, u, v) {
+  const denominator = h[6] * u + h[7] * v + h[8];
+  return {
+    x: (h[0] * u + h[1] * v + h[2]) / denominator,
+    y: (h[3] * u + h[4] * v + h[5]) / denominator
+  };
+}
+
+function detectCodeGeometry(imageData, options = {}) {
+  assert(imageData?.data && imageData.width && imageData.height, "Valid image data is required.");
+  const minVersion = options.minVersion ?? 1;
+  const maxVersion = options.maxVersion ?? 40;
+  const maxCandidates = options.maxCandidates ?? 8;
+  const { binary, threshold } = buildBinary(imageData);
+  const finders = detectFinderCandidates(binary, imageData.width, imageData.height);
+  if (finders.length < 3) return [];
+
+  const triples = chooseFinderTriples(finders, 20);
+  const geometries = [];
+
+  for (const triple of triples) {
+    const legH = Math.hypot(triple.tr.x - triple.tl.x, triple.tr.y - triple.tl.y);
+    const legV = Math.hypot(triple.bl.x - triple.tl.x, triple.bl.y - triple.tl.y);
+    const estimatedSize = ((legH + legV) / 2) / triple.moduleMean + 7;
+    const versions = nearestVersionFromEstimate(estimatedSize, minVersion, maxVersion).slice(0, 9);
+
+    for (const item of versions) {
+      const version = item.version;
+      const size = sizeForVersion(version);
+      const alignment = searchAlignment(binary, imageData.width, imageData.height, triple, version);
+      if (alignment.score < 0.72) continue;
+
+      const alignmentTarget = alignment.target;
+      const dest = [
+        { x: 3.5, y: 3.5 },
+        { x: size - 3.5, y: 3.5 },
+        { x: 3.5, y: size - 3.5 },
+        { x: alignmentTarget.col + 0.5, y: alignmentTarget.row + 0.5 }
+      ];
+      const src = [
+        { x: triple.tl.x, y: triple.tl.y },
+        { x: triple.tr.x, y: triple.tr.y },
+        { x: triple.bl.x, y: triple.bl.y },
+        alignment.center
+      ];
+
+      let homography;
+      try {
+        homography = computeHomography(src, dest);
+      } catch {
+        continue;
+      }
+
+      const alignmentGrid = scoreAlignmentGrid(binary, imageData.width, imageData.height, homography, version);
+      if (alignmentGrid.score < 0.68) continue;
+
+      const versionPenalty = item.error / 4;
+      const alignmentConfidence = 0.55 * alignment.score + 0.45 * alignmentGrid.score;
+      const score = triple.score * (0.5 + 0.5 * alignmentConfidence) / (1 + versionPenalty * 0.08);
+      geometries.push({
+        version,
+        size,
+        sourcePoints: src,
+        destinationPoints: dest,
+        homography,
+        finders: { topLeft: triple.tl, topRight: triple.tr, bottomLeft: triple.bl },
+        alignment: {
+          center: alignment.center,
+          score: alignment.score,
+          scale: alignment.scale,
+          target: { row: alignmentTarget.row, col: alignmentTarget.col },
+          patterns: alignmentGrid.patternScores.length,
+          gridScore: alignmentGrid.score,
+          patternScores: alignmentGrid.patternScores
+        },
+        threshold,
+        estimatedSize,
+        score
+      });
+    }
+  }
+
+  // Deduplicate roughly identical geometry/version hypotheses.
+  const deduped = [];
+  geometries.sort((a, b) => b.score - a.score);
+  for (const geometry of geometries) {
+    const duplicate = deduped.some((other) =>
+      other.version === geometry.version &&
+      Math.hypot(
+        other.sourcePoints[0].x - geometry.sourcePoints[0].x,
+        other.sourcePoints[0].y - geometry.sourcePoints[0].y
+      ) < Math.max(3, geometry.finders.topLeft.moduleSize * 2)
+    );
+    if (!duplicate) deduped.push(geometry);
+    if (deduped.length >= maxCandidates) break;
+  }
+  return deduped;
+}
+
+function averageProjectedSample(imageData, homography, moduleX, moduleY, radius = 0.16) {
+  const offsets = radius > 0
+    ? [[0, 0], [-radius, 0], [radius, 0], [0, -radius], [0, radius]]
+    : [[0, 0]];
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let count = 0;
+  for (const [dx, dy] of offsets) {
+    const point = projectPoint(homography, moduleX + dx, moduleY + dy);
+    if (point.x < 0 || point.y < 0 || point.x >= imageData.width || point.y >= imageData.height) continue;
+    const rgb = bilinearRgb(imageData, point.x, point.y);
+    r += rgb.r;
+    g += rgb.g;
+    b += rgb.b;
+    count++;
+  }
+  if (!count) return { r: 255, g: 255, b: 255 };
+  return { r: r / count, g: g / count, b: b / count };
+}
+
+function samplePerspectiveMatrix(imageData, homography, size, options = {}) {
+  const rgbGrid = Array.from({ length: size }, () => new Array(size));
+  const radius = options.sampleRadius ?? 0.16;
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) {
+      rgbGrid[r][c] = averageProjectedSample(imageData, homography, c + 0.5, r + 0.5, radius);
+    }
+  }
+  return { rgbGrid };
+}
+
+function meanRgb(values) {
+  if (!values.length) throw new Error("No calibration samples available.");
+  return values.reduce(
+    (sum, rgb) => ({ r: sum.r + rgb.r, g: sum.g + rgb.g, b: sum.b + rgb.b }),
+    { r: 0, g: 0, b: 0 }
+  );
+}
+
+function averageRgb(values) {
+  const sum = meanRgb(values);
+  return { r: sum.r / values.length, g: sum.g / values.length, b: sum.b / values.length };
+}
+
+function pickCalibrationSamples(rgbGrid, positions, limit = 24) {
+  if (!positions?.length) return [];
+  const step = Math.max(1, Math.floor(positions.length / limit));
+  const out = [];
+  for (let i = 0; i < positions.length; i += step) {
+    const [row, col] = positions[i];
+    out.push(rgbGrid[row][col]);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+function sampleObservedPalette(rgbGrid, calibration) {
+  const palette = {
+    black: averageRgb(pickCalibrationSamples(rgbGrid, calibration.black, 36)),
+    white: averageRgb(pickCalibrationSamples(rgbGrid, calibration.white, 36)),
+    red: averageRgb(pickCalibrationSamples(rgbGrid, calibration.red, 12)),
+    green: averageRgb(pickCalibrationSamples(rgbGrid, calibration.green, 12)),
+    blue: averageRgb(pickCalibrationSamples(rgbGrid, calibration.blue, 12))
+  };
+
+  // All five observed classes must remain separated enough for reliable RGBW
+  // classification: structural black plus the four visible data states.
+  const colors = [palette.black, palette.red, palette.green, palette.blue, palette.white];
+  const distances = [];
+  for (let i = 0; i < colors.length; i++) {
+    for (let j = i + 1; j < colors.length; j++) {
+      distances.push(Math.hypot(
+        colors[i].r - colors[j].r,
+        colors[i].g - colors[j].g,
+        colors[i].b - colors[j].b
+      ));
+    }
+  }
+  if (Math.min(...distances) < 28) throw new Error("RGBW calibration references are not separable in this image.");
+  return palette;
+}
+
+function rectifyImageData(imageData, homography, size, moduleSize = 8) {
+  const outputSize = Math.max(1, Math.round(size * moduleSize));
+  const data = new Uint8ClampedArray(outputSize * outputSize * 4);
+  for (let y = 0; y < outputSize; y++) {
+    for (let x = 0; x < outputSize; x++) {
+      const moduleX = (x + 0.5) / moduleSize;
+      const moduleY = (y + 0.5) / moduleSize;
+      const source = projectPoint(homography, moduleX, moduleY);
+      const rgb = bilinearRgb(imageData, source.x, source.y);
+      const p = (y * outputSize + x) * 4;
+      data[p] = clamp(Math.round(rgb.r), 0, 255);
+      data[p + 1] = clamp(Math.round(rgb.g), 0, 255);
+      data[p + 2] = clamp(Math.round(rgb.b), 0, 255);
+      data[p + 3] = 255;
+    }
+  }
+  return { width: outputSize, height: outputSize, data };
+}
+
+function findActiveBounds(imageData, whiteThreshold = 238) {
+  const { width, height, data } = imageData;
+  let minX = width;
+  let minY = height;
+  let maxX = -1;
+  let maxY = -1;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = (y * width + x) * 4;
+      const a = data[i + 3];
+      const active = a > 16 && (data[i] < whiteThreshold || data[i + 1] < whiteThreshold || data[i + 2] < whiteThreshold);
+      if (!active) continue;
+      minX = Math.min(minX, x);
+      maxX = Math.max(maxX, x);
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+    }
+  }
+  if (maxX < minX || maxY < minY) throw new Error("No code-like non-white area found.");
+  return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+}
+
+function sampleAverageAxis(imageData, centerX, centerY, radius) {
+  const { width, height, data } = imageData;
+  const minX = Math.max(0, Math.floor(centerX - radius));
+  const maxX = Math.min(width - 1, Math.ceil(centerX + radius));
+  const minY = Math.max(0, Math.floor(centerY - radius));
+  const maxY = Math.min(height - 1, Math.ceil(centerY + radius));
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let count = 0;
+  for (let y = minY; y <= maxY; y++) {
+    for (let x = minX; x <= maxX; x++) {
+      const i = (y * width + x) * 4;
+      const a = data[i + 3] / 255;
+      r += data[i] * a + 255 * (1 - a);
+      g += data[i + 1] * a + 255 * (1 - a);
+      b += data[i + 2] * a + 255 * (1 - a);
+      count++;
+    }
+  }
+  return count ? { r: r / count, g: g / count, b: b / count } : { r: 255, g: 255, b: 255 };
+}
+
+function sampleAxisAlignedGrid(imageData, bounds, size, radiusRatio = 0.18) {
+  const moduleW = bounds.width / size;
+  const moduleH = bounds.height / size;
+  const radius = Math.max(0, Math.min(moduleW, moduleH) * radiusRatio);
+  const rgbGrid = Array.from({ length: size }, () => new Array(size));
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) {
+      const x = bounds.x + (c + 0.5) * moduleW;
+      const y = bounds.y + (r + 0.5) * moduleH;
+      rgbGrid[r][c] = sampleAverageAxis(imageData, x, y, radius);
+    }
+  }
+  return { rgbGrid, moduleWidth: moduleW, moduleHeight: moduleH };
+}
+
+const visionInternals = Object.freeze({
+  buildGray,
+  otsuThreshold,
+  buildBinary,
+  finderRatioScore,
+  detectFinderCandidates,
+  chooseFinderTriples,
+  searchAlignment,
+  bilinearRgb,
+  luminance
+});
+
+return { computeHomography, projectPoint, detectCodeGeometry, samplePerspectiveMatrix, sampleObservedPalette, rectifyImageData, findActiveBounds, sampleAxisAlignedGrid, visionInternals };
+})();
+const __qqr_quadqr_js = (function () {
+const { MAX_CODEWORD_SYMBOLS, rsEncode, rsDecode } = __qqr_reed_solomon_js;
+const { alignmentPatternCentersForVersion, alignmentPatternIsBlack, alignmentPatternRadius, sizeForVersion, versionFromSize } = __qqr_geometry_js;
+const { detectCodeGeometry, samplePerspectiveMatrix, rectifyImageData, sampleObservedPalette, findActiveBounds, sampleAxisAlignedGrid } = __qqr_vision_js;
+const { decryptSecurePayload, encryptSecurePayload, inspectSecureEnvelope, SECURITY_MODES, SECURITY_ALGORITHMS, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, generateRaw256Key, normalizeRaw256Key, bytesToHex } = __qqr_security_js;
+
+const FORMAT_VERSION = 5;
+const MIN_VERSION = 1;
+const MAX_VERSION = 40;
+const DEFAULT_ECC_LEVEL = "M";
+
+// Data cells are the four values 0..3. Structural white deliberately shares
+// value 3 with data-white because both render and scan identically.
+const CELL = Object.freeze({
+  BLACK: -1,
+  RED: 0,
+  GREEN: 1,
+  BLUE: 2,
+  WHITE: 3
+});
+
+const DEFAULT_PALETTE = Object.freeze({
+  black: "#000000",
+  white: "#ffffff",
+  red: "#ef233c",
+  green: "#16a34a",
+  blue: "#2563eb"
+});
+
+const RENDER_STYLES = Object.freeze({
+  CLASSIC: "classic",
+  DEPTH: "depth",
+  SOFT: "soft",
+  INSET: "inset"
+});
+
+const ECC_LEVELS = Object.freeze({
+  L: Object.freeze({ id: 0, paritySymbols: 12, correctableSymbolsPerBlock: 6 }),
+  M: Object.freeze({ id: 1, paritySymbols: 24, correctableSymbolsPerBlock: 12 }),
+  Q: Object.freeze({ id: 2, paritySymbols: 36, correctableSymbolsPerBlock: 18 }),
+  H: Object.freeze({ id: 3, paritySymbols: 48, correctableSymbolsPerBlock: 24 })
+});
+
+const ECC_BY_ID = Object.freeze(
+  Object.fromEntries(Object.entries(ECC_LEVELS).map(([name, info]) => [info.id, name]))
+);
+
+const MAGIC = new Uint8Array([0x51, 0x51, 0x52, 0x57]); // QQRW (QuadQR RGBW)
+const HEADER_BYTES = 10;
+const HEADER_RS_PARITY = 8;
+const HEADER_CODEWORD_BYTES = HEADER_BYTES + HEADER_RS_PARITY;
+const CELLS_PER_BYTE = 4;
+const HEADER_CODEWORD_CELLS = HEADER_CODEWORD_BYTES * CELLS_PER_BYTE;
+
+// Version 1 is a deliberately compact small-symbol profile. A 21x21 matrix
+// cannot afford the normal 18-byte protected header plus a 24-byte M body
+// parity block. The matrix size already identifies v1, so it uses a compact
+// 4-byte logical header protected by 4 RS parity bytes and size-appropriate
+// body parity. Larger versions keep the normal framing unchanged.
+const COMPACT_VERSION = 1;
+const COMPACT_HEADER_MAGIC = 0xc3;
+const COMPACT_HEADER_BYTES = 4;
+const COMPACT_HEADER_RS_PARITY = 4;
+const COMPACT_HEADER_CODEWORD_BYTES = COMPACT_HEADER_BYTES + COMPACT_HEADER_RS_PARITY;
+const COMPACT_HEADER_CODEWORD_CELLS = COMPACT_HEADER_CODEWORD_BYTES * CELLS_PER_BYTE;
+const COMPACT_ECC_LEVELS = Object.freeze({
+  L: Object.freeze({ paritySymbols: 4, correctableSymbolsPerBlock: 2 }),
+  M: Object.freeze({ paritySymbols: 8, correctableSymbolsPerBlock: 4 }),
+  Q: Object.freeze({ paritySymbols: 12, correctableSymbolsPerBlock: 6 }),
+  H: Object.freeze({ paritySymbols: 16, correctableSymbolsPerBlock: 8 })
+});
+
+const CRC_BYTES = 4;
+const TEXT_FLAG = 1;
+const SECURE_FLAG = 1 << 3;
+const ECC_SHIFT = 1;
+const ECC_MASK = 0b00000110;
+
+const textEncoder = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
+const textDecoder = typeof TextDecoder !== "undefined"
+  ? new TextDecoder("utf-8", { fatal: false })
+  : null;
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function getTextEncoder() {
+  assert(textEncoder, "TextEncoder is required in this environment.");
+  return textEncoder;
+}
+
+function getTextDecoder() {
+  assert(textDecoder, "TextDecoder is required in this environment.");
+  return textDecoder;
+}
+
+function cloneMatrix(matrix) {
+  return matrix.map((row) => row.slice());
+}
+
+function make2D(size, valueFactory) {
+  return Array.from({ length: size }, (_, r) =>
+    Array.from({ length: size }, (_, c) =>
+      typeof valueFactory === "function" ? valueFactory(r, c) : valueFactory
+    )
+  );
+}
+
+function validateVersion(version) {
+  assert(Number.isInteger(version), "Version must be an integer.");
+  assert(
+    version >= MIN_VERSION && version <= MAX_VERSION,
+    `Version must be ${MIN_VERSION}..${MAX_VERSION}.`
+  );
+}
+
+function normalizeEccLevel(level = DEFAULT_ECC_LEVEL) {
+  const value = String(level).toUpperCase();
+  assert(ECC_LEVELS[value], `ECC level must be one of ${Object.keys(ECC_LEVELS).join(", ")}.`);
+  return value;
+}
+
+function concatBytes(...arrays) {
+  const total = arrays.reduce((sum, item) => sum + item.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const item of arrays) {
+    out.set(item, offset);
+    offset += item.length;
+  }
+  return out;
+}
+
+function u32be(value) {
+  const v = value >>> 0;
+  return new Uint8Array([
+    (v >>> 24) & 0xff,
+    (v >>> 16) & 0xff,
+    (v >>> 8) & 0xff,
+    v & 0xff
+  ]);
+}
+
+function readU32be(bytes, offset = 0) {
+  return (
+    ((bytes[offset] << 24) >>> 0) |
+    (bytes[offset + 1] << 16) |
+    (bytes[offset + 2] << 8) |
+    bytes[offset + 3]
+  ) >>> 0;
+}
+
+let CRC_TABLE = null;
+let CRC32_ACCELERATOR = null;
+
+function installCrc32Accelerator(accelerator = null) {
+  assert(
+    accelerator == null || typeof accelerator === "function",
+    "CRC-32 accelerator must be a function or null."
+  );
+  CRC32_ACCELERATOR = accelerator;
+}
+
+function getCrcTable() {
+  if (CRC_TABLE) return CRC_TABLE;
+  CRC_TABLE = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    CRC_TABLE[n] = c >>> 0;
+  }
+  return CRC_TABLE;
+}
+
+function crc32(bytes) {
+  if (CRC32_ACCELERATOR) return CRC32_ACCELERATOR(bytes) >>> 0;
+  const table = getCrcTable();
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = table[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function bytesToCells(bytes) {
+  const out = new Array(bytes.length * CELLS_PER_BYTE);
+  let cursor = 0;
+  for (const byte of bytes) {
+    out[cursor++] = (byte >>> 6) & 0b11;
+    out[cursor++] = (byte >>> 4) & 0b11;
+    out[cursor++] = (byte >>> 2) & 0b11;
+    out[cursor++] = byte & 0b11;
+  }
+  return out;
+}
+
+function cellsToBytes(cells, byteCount = Math.floor(cells.length / CELLS_PER_BYTE)) {
+  assert(cells.length >= byteCount * CELLS_PER_BYTE, "Not enough RGBW cells to rebuild bytes.");
+  const out = new Uint8Array(byteCount);
+  for (let i = 0; i < byteCount; i++) {
+    const offset = i * CELLS_PER_BYTE;
+    const a = cells[offset];
+    const b = cells[offset + 1];
+    const c = cells[offset + 2];
+    const d = cells[offset + 3];
+    for (const value of [a, b, c, d]) {
+      assert(Number.isInteger(value) && value >= 0 && value <= 3, "Invalid RGBW data cell.");
+    }
+    out[i] = (a << 6) | (b << 4) | (c << 2) | d;
+  }
+  return out;
+}
+
+function flagsFor(text, eccLevel, secure = false) {
+  return (text ? TEXT_FLAG : 0) |
+    (secure ? SECURE_FLAG : 0) |
+    ((ECC_LEVELS[eccLevel].id << ECC_SHIFT) & ECC_MASK);
+}
+
+function eccFromFlags(flags) {
+  const id = (flags & ECC_MASK) >> ECC_SHIFT;
+  const name = ECC_BY_ID[id];
+  if (!name) throw new Error(`Unknown ECC profile id ${id}.`);
+  return name;
+}
+
+function getHeaderPlan(version) {
+  if (version === COMPACT_VERSION) {
+    return {
+      compact: true,
+      headerBytes: COMPACT_HEADER_BYTES,
+      paritySymbols: COMPACT_HEADER_RS_PARITY,
+      codewordBytes: COMPACT_HEADER_CODEWORD_BYTES,
+      codewordCells: COMPACT_HEADER_CODEWORD_CELLS,
+      correctableSymbols: COMPACT_HEADER_RS_PARITY / 2
+    };
+  }
+  return {
+    compact: false,
+    headerBytes: HEADER_BYTES,
+    paritySymbols: HEADER_RS_PARITY,
+    codewordBytes: HEADER_CODEWORD_BYTES,
+    codewordCells: HEADER_CODEWORD_CELLS,
+    correctableSymbols: HEADER_RS_PARITY / 2
+  };
+}
+
+function getEffectiveEcc(version, eccLevel) {
+  const normalized = normalizeEccLevel(eccLevel);
+  return version === COMPACT_VERSION ? COMPACT_ECC_LEVELS[normalized] : ECC_LEVELS[normalized];
+}
+
+function makeHeader(payloadLength, flags, version) {
+  assert(payloadLength >= 0 && payloadLength <= 0xffffffff, "Payload is too large.");
+
+  if (version === COMPACT_VERSION) {
+    assert(payloadLength <= 0xff, "Version 1 compact header supports payloads up to 255 bytes.");
+    const header = new Uint8Array(COMPACT_HEADER_BYTES);
+    header[0] = COMPACT_HEADER_MAGIC;
+    header[1] = flags & 0xff;
+    header[2] = payloadLength & 0xff;
+    header[3] = (payloadLength ^ 0xff) & 0xff;
+    return header;
+  }
+
+  const header = new Uint8Array(HEADER_BYTES);
+  header.set(MAGIC, 0);
+  header[4] = FORMAT_VERSION;
+  header[5] = flags & 0xff;
+  header.set(u32be(payloadLength), 6);
+  return header;
+}
+
+function magicMatches(header) {
+  return MAGIC.every((value, index) => header[index] === value);
+}
+
+function parseHeader(header, version) {
+  if (version === COMPACT_VERSION) {
+    if (
+      header.length !== COMPACT_HEADER_BYTES ||
+      header[0] !== COMPACT_HEADER_MAGIC ||
+      header[3] !== ((header[2] ^ 0xff) & 0xff)
+    ) {
+      throw new Error("QuadQR compact header mismatch.");
+    }
+    return { flags: header[1], payloadLength: header[2] };
+  }
+
+  if (!magicMatches(header) || header[4] !== FORMAT_VERSION) {
+    throw new Error("QuadQR magic/version mismatch.");
+  }
+  return { flags: header[5], payloadLength: readU32be(header, 6) };
+}
+
+function createLayout(version) {
+  validateVersion(version);
+  const size = sizeForVersion(version);
+  const matrix = make2D(size, CELL.WHITE);
+  const reserved = make2D(size, false);
+  const calibration = { red: [], green: [], blue: [], black: [], white: [] };
+
+  function reserveAndSet(row, col, value, calibrationKey = null) {
+    if (row < 0 || col < 0 || row >= size || col >= size) return;
+    reserved[row][col] = true;
+    matrix[row][col] = value;
+    if (calibrationKey) calibration[calibrationKey].push([row, col]);
+  }
+
+  function drawFinder(top, left) {
+    for (let r = -1; r <= 7; r++) {
+      for (let c = -1; c <= 7; c++) {
+        const rr = top + r;
+        const cc = left + c;
+        if (rr < 0 || cc < 0 || rr >= size || cc >= size) continue;
+        if (r === -1 || c === -1 || r === 7 || c === 7) {
+          reserveAndSet(rr, cc, CELL.WHITE, "white");
+        }
+      }
+    }
+
+    for (let r = 0; r < 7; r++) {
+      for (let c = 0; c < 7; c++) {
+        const outer = r === 0 || c === 0 || r === 6 || c === 6;
+        const center = r >= 2 && r <= 4 && c >= 2 && c <= 4;
+        const black = outer || center;
+        reserveAndSet(top + r, left + c, black ? CELL.BLACK : CELL.WHITE, black ? "black" : "white");
+      }
+    }
+  }
+
+  function drawAlignmentPattern(definition) {
+    const { row: centerRow, col: centerCol, separator = false } = definition;
+    const radius = alignmentPatternRadius(definition);
+
+    if (separator) {
+      const separatorRadius = radius + 1;
+      for (let r = -separatorRadius; r <= separatorRadius; r++) {
+        for (let c = -separatorRadius; c <= separatorRadius; c++) {
+          if (Math.abs(r) === separatorRadius || Math.abs(c) === separatorRadius) {
+            reserveAndSet(centerRow + r, centerCol + c, CELL.WHITE, "white");
+          }
+        }
+      }
+    }
+
+    for (let r = -radius; r <= radius; r++) {
+      for (let c = -radius; c <= radius; c++) {
+        const black = alignmentPatternIsBlack(definition, r, c);
+        reserveAndSet(
+          centerRow + r,
+          centerCol + c,
+          black ? CELL.BLACK : CELL.WHITE,
+          black ? "black" : "white"
+        );
+      }
+    }
+
+    return {
+      row: centerRow,
+      col: centerCol,
+      size: definition.size,
+      primary: Boolean(definition.primary),
+      center: [centerCol + 0.5, centerRow + 0.5],
+      bootstrap: Boolean(definition.bootstrap),
+      separator: Boolean(separator)
+    };
+  }
+
+  function isAreaFree(row0, col0, height, width) {
+    if (row0 < 0 || col0 < 0 || row0 + height > size || col0 + width > size) return false;
+    for (let r = row0; r < row0 + height; r++) {
+      for (let c = col0; c < col0 + width; c++) {
+        if (reserved[r][c]) return false;
+      }
+    }
+    return true;
+  }
+
+  function findCalibrationStripOrigin() {
+    const preferred = { row: size - 6, col: size - 13 };
+    if (isAreaFree(preferred.row, preferred.col, 2, 6)) return preferred;
+
+    // Keep the swatches away from the three large finders and timing axes, but
+    // allow their location to move when a version's alignment grid occupies
+    // the old bottom-right calibration area.
+    for (let row = size - 8; row >= 8; row--) {
+      for (let col = size - 8; col >= 8; col--) {
+        if (isAreaFree(row, col, 2, 6)) return { row, col };
+      }
+    }
+
+    throw new Error(`Unable to reserve QuadQR calibration strip for version ${version}.`);
+  }
+
+  function drawCalibrationStrip() {
+    const origin = findCalibrationStripOrigin();
+    const entries = [
+      { key: "red", cell: CELL.RED, offset: 0 },
+      { key: "green", cell: CELL.GREEN, offset: 2 },
+      { key: "blue", cell: CELL.BLUE, offset: 4 }
+    ];
+
+    for (const entry of entries) {
+      for (const row of [origin.row, origin.row + 1]) {
+        for (let dc = 0; dc < 2; dc++) {
+          reserveAndSet(row, origin.col + entry.offset + dc, entry.cell, entry.key);
+        }
+      }
+    }
+    return { top: origin.row, left: origin.col, width: 6, height: 2 };
+  }
+
+  drawFinder(0, 0);
+  drawFinder(0, size - 7);
+  drawFinder(size - 7, 0);
+
+  for (let col = 8; col < size - 8; col++) {
+    reserveAndSet(6, col, col % 2 === 0 ? CELL.BLACK : CELL.WHITE);
+  }
+  for (let row = 8; row < size - 8; row++) {
+    reserveAndSet(row, 6, row % 2 === 0 ? CELL.BLACK : CELL.WHITE);
+  }
+
+  const alignments = alignmentPatternCentersForVersion(version).map(drawAlignmentPattern);
+  const alignment = alignments[alignments.length - 1];
+  const calibrationStrip = drawCalibrationStrip();
+
+  const dataPositions = [];
+  let upward = true;
+  let col = size - 1;
+  while (col >= 0) {
+    if (col === 6) col--;
+    for (let i = 0; i < size; i++) {
+      const row = upward ? size - 1 - i : i;
+      for (let dx = 0; dx < 2; dx++) {
+        const c = col - dx;
+        if (c < 0) continue;
+        if (!reserved[row][c]) dataPositions.push([row, c]);
+      }
+    }
+    upward = !upward;
+    col -= 2;
+  }
+
+  return {
+    version,
+    size,
+    matrix,
+    reserved,
+    dataPositions,
+    calibration,
+    calibrationStrip,
+    alignment,
+    alignments
+  };
+}
+
+function maskValue(row, col, maskId) {
+  switch (maskId) {
+    case 0: return (row + col) & 3;
+    case 1: return (2 * row + col) & 3;
+    case 2: return (row + 2 * col) & 3;
+    case 3: return (row * col + row + col) & 3;
+    default: throw new Error(`Unknown mask ${maskId}.`);
+  }
+}
+
+function makePaddingCells(count, seed) {
+  let state = (seed >>> 0) || 0x6d2b79f5;
+  const out = new Array(count);
+  for (let i = 0; i < count; i++) {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    state >>>= 0;
+    out[i] = state & 3;
+  }
+  return out;
+}
+
+const SPECTRAL_PERMUTATION_CACHE = new Map();
+
+function spectralPermutation(length, version) {
+  const cacheKey = `${version}:${length}`;
+  const cached = SPECTRAL_PERMUTATION_CACHE.get(cacheKey);
+  if (cached) return cached;
+
+  const permutation = Array.from({ length }, (_, index) => index);
+  let state = (0x9e3779b9 ^ Math.imul(version + 1, 0x85ebca6b) ^ Math.imul(length + 17, 0xc2b2ae35)) >>> 0;
+
+  function nextRandom() {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    state >>>= 0;
+    return state;
+  }
+
+  // Deterministic Fisher-Yates shuffle. The mapping costs no cells and makes
+  // neighboring logical symbols land at widely separated physical modules.
+  for (let index = length - 1; index > 0; index--) {
+    const swapIndex = nextRandom() % (index + 1);
+    [permutation[index], permutation[swapIndex]] = [permutation[swapIndex], permutation[index]];
+  }
+  SPECTRAL_PERMUTATION_CACHE.set(cacheKey, permutation);
+  return permutation;
+}
+
+function applyData(layout, rawCells, maskId, spectralInterleaving = true) {
+  const matrix = cloneMatrix(layout.matrix);
+  const permutation = spectralInterleaving
+    ? spectralPermutation(layout.dataPositions.length, layout.version)
+    : null;
+
+  for (let logicalIndex = 0; logicalIndex < layout.dataPositions.length; logicalIndex++) {
+    const physicalIndex = permutation ? permutation[logicalIndex] : logicalIndex;
+    const [row, col] = layout.dataPositions[physicalIndex];
+    matrix[row][col] = rawCells[logicalIndex] ^ maskValue(row, col, maskId);
+  }
+  return matrix;
+}
+
+function quaternaryPenalty(matrix, reserved) {
+  const size = matrix.length;
+  let penalty = 0;
+  const counts = [0, 0, 0, 0];
+  let dataCount = 0;
+
+  for (let r = 0; r < size; r++) {
+    let previous = null;
+    let run = 0;
+    for (let c = 0; c < size; c++) {
+      if (reserved[r][c]) {
+        previous = null;
+        run = 0;
+        continue;
+      }
+      const value = matrix[r][c];
+      counts[value]++;
+      dataCount++;
+      if (value === previous) {
+        run++;
+        if (run >= 4) penalty += 2;
+      } else {
+        previous = value;
+        run = 1;
+      }
+    }
+  }
+
+  for (let c = 0; c < size; c++) {
+    let previous = null;
+    let run = 0;
+    for (let r = 0; r < size; r++) {
+      if (reserved[r][c]) {
+        previous = null;
+        run = 0;
+        continue;
+      }
+      const value = matrix[r][c];
+      if (value === previous) {
+        run++;
+        if (run >= 4) penalty += 2;
+      } else {
+        previous = value;
+        run = 1;
+      }
+    }
+  }
+
+  if (dataCount > 0) {
+    const ideal = dataCount / 4;
+    penalty += counts.reduce((sum, count) => sum + Math.abs(count - ideal), 0) / 2;
+  }
+  return penalty;
+}
+
+function interleaveBlocks(blocks) {
+  const maxLength = Math.max(...blocks.map((block) => block.length), 0);
+  const out = [];
+  for (let index = 0; index < maxLength; index++) {
+    for (const block of blocks) {
+      if (index < block.length) out.push(block[index]);
+    }
+  }
+  return out;
+}
+
+function deinterleaveBlocks(stream, blockLengths) {
+  const blocks = blockLengths.map((length) => new Array(length));
+  let cursor = 0;
+  const maxLength = Math.max(...blockLengths, 0);
+  for (let index = 0; index < maxLength; index++) {
+    for (let blockIndex = 0; blockIndex < blocks.length; blockIndex++) {
+      if (index < blockLengths[blockIndex]) blocks[blockIndex][index] = stream[cursor++];
+    }
+  }
+  assert(cursor === stream.length, "Interleaved RS symbol length mismatch.");
+  return blocks;
+}
+
+function getBodyRsPlan(payloadLength, eccLevel, version = 2) {
+  const ecc = getEffectiveEcc(version, eccLevel);
+  const bodyByteCount = payloadLength + CRC_BYTES;
+  const dataSymbols = bodyByteCount;
+  const maxDataPerBlock = MAX_CODEWORD_SYMBOLS - ecc.paritySymbols;
+  const dataBlockLengths = [];
+  let remaining = dataSymbols;
+  while (remaining > 0) {
+    const length = Math.min(maxDataPerBlock, remaining);
+    dataBlockLengths.push(length);
+    remaining -= length;
+  }
+  const codewordBlockLengths = dataBlockLengths.map((length) => length + ecc.paritySymbols);
+  const encodedSymbols = codewordBlockLengths.reduce((sum, value) => sum + value, 0);
+  return {
+    bodyByteCount,
+    dataSymbols,
+    paritySymbols: ecc.paritySymbols,
+    correctableSymbolsPerBlock: ecc.correctableSymbolsPerBlock,
+    dataBlockLengths,
+    codewordBlockLengths,
+    encodedSymbols,
+    encodedCells: encodedSymbols * CELLS_PER_BYTE
+  };
+}
+
+function streamCellCount(payloadLength, eccLevel, version) {
+  return getHeaderPlan(version).codewordCells + getBodyRsPlan(payloadLength, eccLevel, version).encodedCells;
+}
+
+function streamFitsLayout(layout, eccLevel, payloadLength, version) {
+  return streamCellCount(payloadLength, eccLevel, version) <= layout.dataPositions.length;
+}
+
+function getCapacityForLayout(layout, eccLevel, version) {
+  if (!streamFitsLayout(layout, eccLevel, 0, version)) return 0;
+  let low = 0;
+  let high = Math.floor(layout.dataPositions.length / CELLS_PER_BYTE);
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (streamFitsLayout(layout, eccLevel, mid, version)) low = mid;
+    else high = mid - 1;
+  }
+  return low;
+}
+
+function getVersionInfo(version, options = {}) {
+  validateVersion(version);
+  const eccLevel = normalizeEccLevel(options.ecc ?? DEFAULT_ECC_LEVEL);
+  const layout = createLayout(version);
+  const headerPlan = getHeaderPlan(version);
+  const effectiveEcc = getEffectiveEcc(version, eccLevel);
+  return {
+    version,
+    formatVersion: FORMAT_VERSION,
+    eccLevel,
+    size: layout.size,
+    dataCells: layout.dataPositions.length,
+    theoreticalBits: layout.dataPositions.length * 2,
+    capacityBytes: getCapacityForLayout(layout, eccLevel, version),
+    headerCells: headerPlan.codewordCells,
+    headerBytes: headerPlan.headerBytes,
+    headerParitySymbols: headerPlan.paritySymbols,
+    bodyParitySymbols: effectiveEcc.paritySymbols,
+    correctableHeaderSymbols: headerPlan.correctableSymbols,
+    correctableSymbolsPerBlock: effectiveEcc.correctableSymbolsPerBlock,
+    compactSmallSymbol: version === COMPACT_VERSION,
+    calibrationCells: 12,
+    hasAlignmentMarker: true,
+    alignmentPatterns: layout.alignments.length,
+    alignmentCenters: layout.alignments.map(({ row, col }) => [row, col]),
+    bitsPerDataCell: 2,
+    colors: 4,
+    spectralInterleaving: true,
+    confidenceAwareEcc: true
+  };
+}
+
+function chooseVersion(payloadLength, options = {}) {
+  const requested = options.version ?? "auto";
+  const minVersion = options.minVersion ?? MIN_VERSION;
+  const maxVersion = options.maxVersion ?? MAX_VERSION;
+  const ecc = normalizeEccLevel(options.ecc ?? DEFAULT_ECC_LEVEL);
+
+  validateVersion(minVersion);
+  validateVersion(maxVersion);
+  assert(minVersion <= maxVersion, "minVersion must be <= maxVersion.");
+
+  if (requested !== "auto") {
+    validateVersion(requested);
+    assert(requested >= minVersion && requested <= maxVersion, "Requested version is outside selected bounds.");
+    const info = getVersionInfo(requested, { ecc });
+    const layout = createLayout(requested);
+    assert(
+      payloadLength <= info.capacityBytes && streamFitsLayout(layout, ecc, payloadLength, requested),
+      `Payload does not fit version ${requested} with ${ecc} ECC. Maximum is ${info.capacityBytes} bytes.`
+    );
+    return requested;
+  }
+
+  for (let version = minVersion; version <= maxVersion; version++) {
+    const layout = createLayout(version);
+    if (streamFitsLayout(layout, ecc, payloadLength, version)) return version;
+  }
+  throw new Error(`Payload is too large for versions ${minVersion}..${maxVersion}.`);
+}
+
+function encodeProtectedHeader(header, version) {
+  const plan = getHeaderPlan(version);
+  const codeword = rsEncode(Array.from(header), plan.paritySymbols);
+  assert(codeword.length === plan.codewordBytes, "Header RS symbol calculation mismatch.");
+  return bytesToCells(codeword);
+}
+
+function encodeProtectedBody(bodyBytes, eccLevel, version) {
+  const plan = getBodyRsPlan(bodyBytes.length - CRC_BYTES, eccLevel, version);
+  assert(bodyBytes.length === plan.dataSymbols, "Body RS symbol calculation mismatch.");
+
+  const blocks = [];
+  let offset = 0;
+  for (const length of plan.dataBlockLengths) {
+    blocks.push(rsEncode(Array.from(bodyBytes.slice(offset, offset + length)), plan.paritySymbols));
+    offset += length;
+  }
+  return { cells: bytesToCells(interleaveBlocks(blocks)), plan };
+}
+
+function finalizeMatrix(layout, rawCells, meta) {
+  let bestMaskId = 0;
+  let bestMatrix = null;
+  let bestPenalty = Infinity;
+
+  for (let maskId = 0; maskId < 4; maskId++) {
+    const candidate = applyData(layout, rawCells, maskId, true);
+    const penalty = quaternaryPenalty(candidate, layout.reserved);
+    if (penalty < bestPenalty) {
+      bestPenalty = penalty;
+      bestMaskId = maskId;
+      bestMatrix = candidate;
+    }
+  }
+
+  const info = getVersionInfo(meta.version, { ecc: meta.eccLevel });
+  return {
+    format: "QuadQR",
+    formatVersion: FORMAT_VERSION,
+    version: meta.version,
+    size: layout.size,
+    matrix: bestMatrix,
+    maskId: bestMaskId,
+    payloadBytes: meta.payloadBytes,
+    sourcePayloadBytes: meta.sourcePayloadBytes ?? meta.payloadBytes,
+    secure: Boolean(meta.secure),
+    requiresDecryption: Boolean(meta.secure),
+    security: meta.security ?? null,
+    meaningfulCells: meta.meaningfulCells,
+    dataCells: layout.dataPositions.length,
+    capacityBytes: info.capacityBytes,
+    alignmentPatterns: layout.alignments.length,
+    utilization: meta.meaningfulCells / layout.dataPositions.length,
+    bitsPerDataCell: 2,
+    eccLevel: meta.eccLevel,
+    eccParitySymbols: meta.eccParitySymbols,
+    eccBlocks: meta.eccBlocks,
+    correctableSymbolsPerBlock: meta.correctableSymbolsPerBlock,
+    spectralInterleaving: true,
+    confidenceAwareEcc: true,
+    crc32: meta.crc >>> 0
+  };
+}
+
+function encodeText(text, options = {}) {
+  assert(typeof text === "string", "encodeText expects a string.");
+  return encodeBytes(getTextEncoder().encode(text), { ...options, text: true });
+}
+
+function encodeBytes(input, options = {}) {
+  if (options.formatVersion != null && options.formatVersion !== FORMAT_VERSION) {
+    throw new Error(`Only QuadQR format version ${FORMAT_VERSION} is supported.`);
+  }
+
+  const payload = input instanceof Uint8Array ? input : new Uint8Array(input);
+  const eccLevel = normalizeEccLevel(options.ecc ?? DEFAULT_ECC_LEVEL);
+  const secure = Boolean(options.secure);
+  const flags = flagsFor(Boolean(options.text), eccLevel, secure);
+  const version = chooseVersion(payload.length, { ...options, ecc: eccLevel });
+  const layout = createLayout(version);
+  const header = makeHeader(payload.length, flags, version);
+  const crc = crc32(concatBytes(header, payload));
+  const headerCells = encodeProtectedHeader(header, version);
+  const bodyEncoded = encodeProtectedBody(concatBytes(payload, u32be(crc)), eccLevel, version);
+  const meaningfulCells = headerCells.concat(bodyEncoded.cells);
+  assert(meaningfulCells.length <= layout.dataPositions.length, "Internal QuadQR capacity calculation error.");
+
+  const padding = makePaddingCells(
+    layout.dataPositions.length - meaningfulCells.length,
+    crc ^ payload.length ^ (version << 24) ^ (ECC_LEVELS[eccLevel].id << 16)
+  );
+
+  return finalizeMatrix(layout, meaningfulCells.concat(padding), {
+    version,
+    payloadBytes: payload.length,
+    sourcePayloadBytes: options.sourcePayloadBytes ?? payload.length,
+    secure,
+    security: options.securityMetadata ?? null,
+    meaningfulCells: meaningfulCells.length,
+    eccLevel,
+    eccParitySymbols: bodyEncoded.plan.paritySymbols,
+    eccBlocks: bodyEncoded.plan.dataBlockLengths.length,
+    correctableSymbolsPerBlock: bodyEncoded.plan.correctableSymbolsPerBlock,
+    crc
+  });
+}
+
+/**
+ * Encode text using the optional QuadQR Secure Payload v1 layer.
+ * This API is async because Web Crypto performs AES-GCM and password KDF work asynchronously.
+ */
+async function encodeSecureText(text, options = {}) {
+  assert(typeof text === "string", "encodeSecureText expects a string.");
+  return encodeSecureBytes(getTextEncoder().encode(text), { ...options, text: true });
+}
+
+/** Encode arbitrary bytes using password or raw 256-bit key security. */
+async function encodeSecureBytes(input, options = {}) {
+  const sourcePayload = input instanceof Uint8Array ? input : new Uint8Array(input);
+  const security = options.security ?? {};
+  const encrypted = await encryptSecurePayload(sourcePayload, security);
+  return encodeBytes(encrypted.envelope, {
+    ...options,
+    text: Boolean(options.text),
+    secure: true,
+    sourcePayloadBytes: sourcePayload.length,
+    securityMetadata: encrypted.metadata
+  });
+}
+
+/**
+ * Decrypt a result returned by decodeMatrix/scanImageData/scanFile.
+ * The encrypted envelope remains available as encryptedPayload.
+ */
+async function decryptDecoded(result, security = {}) {
+  assert(result?.secure && result?.payload, "decryptDecoded expects an encrypted QuadQR decode result.");
+  const plaintext = await decryptSecurePayload(result.payload, security);
+  const isText = (result.flags & TEXT_FLAG) !== 0;
+  return {
+    ...result,
+    encryptedPayload: result.payload,
+    encryptedPayloadBytes: result.payload.length,
+    payload: plaintext,
+    text: isText ? getTextDecoder().decode(plaintext) : null,
+    decrypted: true,
+    requiresDecryption: false,
+    security: { ...result.security, decrypted: true }
+  };
+}
+
+function finderMismatchRatio(matrix, top, left) {
+  let mismatches = 0;
+  let total = 0;
+  for (let r = 0; r < 7; r++) {
+    for (let c = 0; c < 7; c++) {
+      const outer = r === 0 || c === 0 || r === 6 || c === 6;
+      const center = r >= 2 && r <= 4 && c >= 2 && c <= 4;
+      const expected = outer || center ? CELL.BLACK : CELL.WHITE;
+      total++;
+      if (matrix[top + r]?.[left + c] !== expected) mismatches++;
+    }
+  }
+  return mismatches / total;
+}
+
+function alignmentPatternMismatchRatio(matrix, pattern) {
+  let mismatches = 0;
+  let total = 0;
+  const radius = alignmentPatternRadius(pattern);
+  for (let r = -radius; r <= radius; r++) {
+    for (let c = -radius; c <= radius; c++) {
+      const black = alignmentPatternIsBlack(pattern, r, c);
+      const expected = black ? CELL.BLACK : CELL.WHITE;
+      total++;
+      if (matrix[pattern.row + r]?.[pattern.col + c] !== expected) mismatches++;
+    }
+  }
+  return mismatches / total;
+}
+
+function alignmentGridMismatchRatio(matrix, version) {
+  const patterns = alignmentPatternCentersForVersion(version);
+  let weightedMismatch = 0;
+  let totalWeight = 0;
+  for (const pattern of patterns) {
+    // Give the 5x5 primary marker a little more influence than compact 3x3 markers.
+    const weight = pattern.primary ? 2 : 1;
+    weightedMismatch += alignmentPatternMismatchRatio(matrix, pattern) * weight;
+    totalWeight += weight;
+  }
+  return totalWeight ? weightedMismatch / totalWeight : 0;
+}
+
+function validateStructure(matrix, tolerance = 0) {
+  const size = matrix.length;
+  if (size < 21 || matrix.some((row) => row.length !== size)) return false;
+  const version = versionFromSize(size);
+  if (!version) return false;
+  const finderRatios = [
+    finderMismatchRatio(matrix, 0, 0),
+    finderMismatchRatio(matrix, 0, size - 7),
+    finderMismatchRatio(matrix, size - 7, 0)
+  ];
+  if (finderRatios.some((ratio) => ratio > tolerance)) return false;
+
+  const alignmentTolerance = Math.max(tolerance, 0.12);
+  const primary = alignmentPatternCentersForVersion(version).at(-1);
+  if (primary && alignmentPatternMismatchRatio(matrix, primary) > alignmentTolerance) {
+    return false;
+  }
+  if (alignmentGridMismatchRatio(matrix, version) > alignmentTolerance) return false;
+  return true;
+}
+
+function rotate90(matrix) {
+  const size = matrix.length;
+  const out = make2D(size, CELL.WHITE);
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) out[c][size - 1 - r] = matrix[r][c];
+  }
+  return out;
+}
+
+function extractVisibleCells(matrix, layout) {
+  const out = [];
+  for (const [row, col] of layout.dataPositions) {
+    const value = matrix[row][col];
+    if (!Number.isInteger(value) || value < 0 || value > 3) {
+      throw new Error("Data region contains an invalid QuadQR data cell.");
+    }
+    out.push(value);
+  }
+  return out;
+}
+
+function unmaskCells(visibleCells, positions, maskId) {
+  return visibleCells.map((value, index) => {
+    const [row, col] = positions[index];
+    return value ^ maskValue(row, col, maskId);
+  });
+}
+
+function restoreLogicalOrder(physicalValues, version, spectralInterleaving) {
+  if (!spectralInterleaving) return physicalValues.slice();
+  const permutation = spectralPermutation(physicalValues.length, version);
+  const logical = new Array(physicalValues.length);
+  for (let logicalIndex = 0; logicalIndex < permutation.length; logicalIndex++) {
+    logical[logicalIndex] = physicalValues[permutation[logicalIndex]];
+  }
+  return logical;
+}
+
+function cellsToSymbolConfidences(confidences, byteCount) {
+  if (!confidences) return null;
+  if (confidences.length < byteCount * CELLS_PER_BYTE) return null;
+  const out = new Array(byteCount);
+  for (let symbolIndex = 0; symbolIndex < byteCount; symbolIndex++) {
+    const offset = symbolIndex * CELLS_PER_BYTE;
+    // A single wrong 2-bit cell changes the GF(256) symbol, so the weakest
+    // constituent cell is the useful confidence bound for that symbol.
+    out[symbolIndex] = Math.min(
+      confidences[offset] ?? 1,
+      confidences[offset + 1] ?? 1,
+      confidences[offset + 2] ?? 1,
+      confidences[offset + 3] ?? 1
+    );
+  }
+  return out;
+}
+
+function decodeRsAdaptive(codeword, paritySymbols, symbolConfidences, options = {}) {
+  try {
+    return { ...rsDecode(codeword, paritySymbols), confidenceAssisted: false };
+  } catch (hardError) {
+    if (!symbolConfidences || symbolConfidences.length !== codeword.length) throw hardError;
+
+    const maxErasureConfidence = options.maxErasureConfidence ?? 0.68;
+    const ranked = symbolConfidences
+      .map((confidence, position) => ({ confidence: Number.isFinite(confidence) ? confidence : 1, position }))
+      .filter(({ confidence }) => confidence <= maxErasureConfidence)
+      .sort((a, b) => (a.confidence - b.confidence) || (a.position - b.position));
+
+    const limit = Math.min(paritySymbols, ranked.length);
+    let lastError = hardError;
+    // Start with the least-confident symbol and progressively promote more
+    // uncertain symbols to erasures. Syndrome verification inside rsDecode
+    // prevents accepting an invalid correction.
+    for (let count = 1; count <= limit; count++) {
+      const erasurePositions = ranked.slice(0, count).map(({ position }) => position);
+      try {
+        return {
+          ...rsDecode(codeword, paritySymbols, { erasurePositions }),
+          confidenceAssisted: true
+        };
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError;
+  }
+}
+
+function decodeProtectedHeader(rawCells, version, rawConfidences = null, options = {}) {
+  const plan = getHeaderPlan(version);
+  const headerCells = rawCells.slice(0, plan.codewordCells);
+  const codeword = Array.from(cellsToBytes(headerCells, plan.codewordBytes));
+  const confidences = cellsToSymbolConfidences(rawConfidences?.slice(0, plan.codewordCells), plan.codewordBytes);
+  const decoded = decodeRsAdaptive(codeword, plan.paritySymbols, confidences, options);
+  const header = new Uint8Array(decoded.data);
+  const parsed = parseHeader(header, version);
+  return {
+    header,
+    ...parsed,
+    correctedSymbols: decoded.correctedSymbols,
+    erasureSymbols: decoded.erasureSymbols ?? 0,
+    unknownErrorSymbols: decoded.unknownErrorSymbols ?? decoded.correctedSymbols,
+    confidenceAssisted: decoded.confidenceAssisted,
+    plan
+  };
+}
+
+function decodeProtectedBody(rawCells, payloadLength, eccLevel, version, rawConfidences = null, options = {}) {
+  const plan = getBodyRsPlan(payloadLength, eccLevel, version);
+  const bodyStart = getHeaderPlan(version).codewordCells;
+  const encodedCells = rawCells.slice(bodyStart, bodyStart + plan.encodedCells);
+  if (encodedCells.length !== plan.encodedCells) throw new Error("Protected body is incomplete.");
+
+  const encodedSymbols = Array.from(cellsToBytes(encodedCells, plan.encodedSymbols));
+  const symbolConfidences = cellsToSymbolConfidences(
+    rawConfidences?.slice(bodyStart, bodyStart + plan.encodedCells),
+    plan.encodedSymbols
+  );
+  const blocks = deinterleaveBlocks(encodedSymbols, plan.codewordBlockLengths);
+  const confidenceBlocks = symbolConfidences
+    ? deinterleaveBlocks(symbolConfidences, plan.codewordBlockLengths)
+    : blocks.map(() => null);
+  const decodedDataSymbols = [];
+  let correctedSymbols = 0;
+  let erasureSymbols = 0;
+  let unknownErrorSymbols = 0;
+  let confidenceAssisted = false;
+
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex++) {
+    const decoded = decodeRsAdaptive(
+      blocks[blockIndex],
+      plan.paritySymbols,
+      confidenceBlocks[blockIndex],
+      options
+    );
+    correctedSymbols += decoded.correctedSymbols;
+    erasureSymbols += decoded.erasureSymbols ?? 0;
+    unknownErrorSymbols += decoded.unknownErrorSymbols ?? decoded.correctedSymbols;
+    confidenceAssisted ||= decoded.confidenceAssisted;
+    decodedDataSymbols.push(...decoded.data);
+  }
+
+  return {
+    body: new Uint8Array(decodedDataSymbols.slice(0, plan.bodyByteCount)),
+    correctedSymbols,
+    erasureSymbols,
+    unknownErrorSymbols,
+    confidenceAssisted,
+    plan
+  };
+}
+
+function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = null, options = {}) {
+  const size = matrix.length;
+  const version = versionFromSize(size);
+  if (!version) throw new Error(`Unsupported matrix size ${size}.`);
+  if (!validateStructure(matrix, tolerance)) throw new Error("QuadQR finder/alignment structure does not match.");
+
+  const layout = createLayout(version);
+  const visible = extractVisibleCells(matrix, layout);
+  const visibleConfidences = confidenceMatrix
+    ? layout.dataPositions.map(([row, col]) => confidenceMatrix[row]?.[col] ?? 1)
+    : null;
+  const errors = [];
+
+  // New symbols use spectral-spatial interleaving. Legacy order remains a
+  // decode fallback so existing QuadQR images do not become unreadable.
+  for (const spectralInterleaving of [true, false]) {
+    for (let maskId = 0; maskId < 4; maskId++) {
+      try {
+        const physicalRaw = unmaskCells(visible, layout.dataPositions, maskId);
+        const raw = restoreLogicalOrder(physicalRaw, version, spectralInterleaving);
+        const rawConfidences = visibleConfidences
+          ? restoreLogicalOrder(visibleConfidences, version, spectralInterleaving)
+          : null;
+        const headerDecoded = decodeProtectedHeader(raw, version, rawConfidences, options);
+        const header = headerDecoded.header;
+        const flags = headerDecoded.flags;
+        const eccLevel = eccFromFlags(flags);
+        const payloadLength = headerDecoded.payloadLength;
+        if (streamCellCount(payloadLength, eccLevel, version) > raw.length) {
+          throw new Error("Declared payload exceeds matrix capacity.");
+        }
+
+        const bodyDecoded = decodeProtectedBody(
+          raw,
+          payloadLength,
+          eccLevel,
+          version,
+          rawConfidences,
+          options
+        );
+        const body = bodyDecoded.body;
+        const payload = body.slice(0, payloadLength);
+        const expectedCrc = readU32be(body, payloadLength);
+        const actualCrc = crc32(concatBytes(header, payload));
+        if (expectedCrc !== actualCrc) throw new Error("CRC mismatch after ECC.");
+
+        const isText = (flags & TEXT_FLAG) !== 0;
+        const secure = (flags & SECURE_FLAG) !== 0;
+        const security = secure ? inspectSecureEnvelope(payload) : null;
+        const erasureSymbols = headerDecoded.erasureSymbols + bodyDecoded.erasureSymbols;
+        const unknownErrorSymbols = headerDecoded.unknownErrorSymbols + bodyDecoded.unknownErrorSymbols;
+        return {
+          ok: true,
+          format: "QuadQR",
+          formatVersion: FORMAT_VERSION,
+          version,
+          size,
+          alignmentPatterns: layout.alignments.length,
+          maskId,
+          rotation,
+          flags,
+          eccLevel,
+          eccParitySymbols: bodyDecoded.plan.paritySymbols,
+          eccBlocks: bodyDecoded.plan.dataBlockLengths.length,
+          correctableSymbolsPerBlock: bodyDecoded.plan.correctableSymbolsPerBlock,
+          spectralInterleaving,
+          confidenceAwareEcc: Boolean(rawConfidences),
+          confidenceAssisted: headerDecoded.confidenceAssisted || bodyDecoded.confidenceAssisted,
+          erasureSymbols,
+          unknownErrorSymbols,
+          correctedHeaderSymbols: headerDecoded.correctedSymbols,
+          correctedBodySymbols: bodyDecoded.correctedSymbols,
+          correctedSymbols: headerDecoded.correctedSymbols + bodyDecoded.correctedSymbols,
+          payload,
+          text: isText && !secure ? getTextDecoder().decode(payload) : null,
+          secure,
+          encrypted: secure,
+          decrypted: false,
+          requiresDecryption: secure,
+          security,
+          crc32: actualCrc >>> 0
+        };
+      } catch (error) {
+        errors.push(`${spectralInterleaving ? "spectral" : "legacy"} mask ${maskId}: ${error.message}`);
+      }
+    }
+  }
+
+  throw new Error(`QuadQR decode failed. ${errors.join(" | ")}`);
+}
+
+function decodeMatrix(inputMatrix, options = {}) {
+  assert(Array.isArray(inputMatrix) && inputMatrix.length > 0, "Matrix is required.");
+  let matrix = cloneMatrix(inputMatrix);
+  let confidenceMatrix = options.cellConfidence ? cloneMatrix(options.cellConfidence) : null;
+  const errors = [];
+  const tolerance = options.structureTolerance ?? 0;
+
+  if (confidenceMatrix) {
+    assert(
+      confidenceMatrix.length === matrix.length && confidenceMatrix.every((row) => row.length === matrix.length),
+      "cellConfidence must be a square matrix matching the QuadQR matrix."
+    );
+  }
+
+  for (let rotationIndex = 0; rotationIndex < 4; rotationIndex++) {
+    const degrees = rotationIndex * 90;
+    try {
+      return decodeCanonical(matrix, degrees, tolerance, confidenceMatrix, options);
+    } catch (error) {
+      errors.push(`${degrees}°: ${error.message}`);
+    }
+    matrix = rotate90(matrix);
+    if (confidenceMatrix) confidenceMatrix = rotate90(confidenceMatrix);
+  }
+
+  throw new Error(`Unable to decode matrix. ${errors.join(" || ")}`);
+}
+
+function hexToRgb(hex) {
+  const clean = hex.replace("#", "");
+  assert(clean.length === 6, `Invalid hex color ${hex}.`);
+  return {
+    r: parseInt(clean.slice(0, 2), 16),
+    g: parseInt(clean.slice(2, 4), 16),
+    b: parseInt(clean.slice(4, 6), 16)
+  };
+}
+
+function resolvePalette(palette = {}) {
+  return { ...DEFAULT_PALETTE, ...palette };
+}
+
+function paletteRgb(palette = {}) {
+  const p = resolvePalette(palette);
+  return {
+    black: hexToRgb(p.black),
+    white: hexToRgb(p.white),
+    red: hexToRgb(p.red),
+    green: hexToRgb(p.green),
+    blue: hexToRgb(p.blue)
+  };
+}
+
+function cellColor(cell, palette) {
+  switch (cell) {
+    case CELL.BLACK: return palette.black;
+    case CELL.RED: return palette.red;
+    case CELL.GREEN: return palette.green;
+    case CELL.BLUE: return palette.blue;
+    case CELL.WHITE: return palette.white;
+    default: throw new Error(`Unknown cell value ${cell}.`);
+  }
+}
+
+function cellRgb(cell, palette) {
+  switch (cell) {
+    case CELL.BLACK: return palette.black;
+    case CELL.RED: return palette.red;
+    case CELL.GREEN: return palette.green;
+    case CELL.BLUE: return palette.blue;
+    case CELL.WHITE: return palette.white;
+    default: throw new Error(`Unknown cell value ${cell}.`);
+  }
+}
+
+function normalizeRenderStyle(style = RENDER_STYLES.CLASSIC) {
+  const value = String(style).toLowerCase();
+  const allowed = Object.values(RENDER_STYLES);
+  assert(allowed.includes(value), `Render style must be one of ${allowed.join(", ")}.`);
+  return value;
+}
+
+function renderLayoutForMatrix(matrix) {
+  const version = versionFromSize(matrix.length);
+  if (!version) return null;
+  try {
+    return createLayout(version);
+  } catch {
+    return null;
+  }
+}
+
+function isStructuralRenderCell(layout, row, col, cell) {
+  // BLACK never represents payload data in QuadQR. The layout check also keeps
+  // structural white and RGB calibration cells untouched by visual styles.
+  return Boolean(layout?.reserved?.[row]?.[col]) || cell === CELL.BLACK;
+}
+
+function renderNoise(row, col, cell) {
+  let value = (
+    Math.imul(row + 1, 0x9e3779b1) ^
+    Math.imul(col + 1, 0x85ebca6b) ^
+    Math.imul((cell + 2) & 0xff, 0xc2b2ae35)
+  ) >>> 0;
+  value ^= value >>> 16;
+  value = Math.imul(value, 0x7feb352d) >>> 0;
+  value ^= value >>> 15;
+  value = Math.imul(value, 0x846ca68b) >>> 0;
+  value ^= value >>> 16;
+  return (value >>> 0) / 0xffffffff;
+}
+
+function depthOpacity(row, col, cell) {
+  const value = renderNoise(row, col, cell);
+  if (value < 0.16) return 0.80;
+  if (value < 0.36) return 0.87;
+  if (value < 0.56) return 0.94;
+  return 1;
+}
+
+function mixRgb(a, b, amount) {
+  const t = Math.max(0, Math.min(1, amount));
+  return {
+    r: Math.round(a.r + (b.r - a.r) * t),
+    g: Math.round(a.g + (b.g - a.g) * t),
+    b: Math.round(a.b + (b.b - a.b) * t)
+  };
+}
+
+function rgbCss(rgb) {
+  return `rgb(${rgb.r} ${rgb.g} ${rgb.b})`;
+}
+
+// Scan-safe decorative profiles deliberately alter only a narrow edge band.
+// The scanner samples around the center of each module (roughly +/- 0.16 to
+// 0.18 module widths), so the central classification area remains the exact
+// encoded R/G/B/W color. Structural/calibration cells bypass styling entirely.
+function safeStyleEdge(moduleSize) {
+  if (moduleSize < 5) return 0;
+  return Math.max(1, Math.min(Math.floor(moduleSize * 0.10), Math.floor(moduleSize * 0.16)));
+}
+
+function insetStyleColors(rgb, palette) {
+  return {
+    highlight: mixRgb(rgb, palette.white, 0.12),
+    shadow: mixRgb(rgb, palette.black, 0.10)
+  };
+}
+
+function roundedRectPath(ctx, x, y, width, height, radius) {
+  const r = Math.max(0, Math.min(radius, width / 2, height / 2));
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.lineTo(x + width - r, y);
+  ctx.quadraticCurveTo(x + width, y, x + width, y + r);
+  ctx.lineTo(x + width, y + height - r);
+  ctx.quadraticCurveTo(x + width, y + height, x + width - r, y + height);
+  ctx.lineTo(x + r, y + height);
+  ctx.quadraticCurveTo(x, y + height, x, y + height - r);
+  ctx.lineTo(x, y + r);
+  ctx.quadraticCurveTo(x, y, x + r, y);
+  ctx.closePath();
+}
+
+function setImagePixel(data, width, x, y, rgb) {
+  if (x < 0 || y < 0 || x >= width) return;
+  const height = data.length / 4 / width;
+  if (y >= height) return;
+  const p = (y * width + x) * 4;
+  data[p] = rgb.r;
+  data[p + 1] = rgb.g;
+  data[p + 2] = rgb.b;
+  data[p + 3] = 255;
+}
+
+function fillImageRect(data, width, x, y, rectWidth, rectHeight, rgb) {
+  for (let yy = y; yy < y + rectHeight; yy++) {
+    for (let xx = x; xx < x + rectWidth; xx++) setImagePixel(data, width, xx, yy, rgb);
+  }
+}
+
+function fillImageRoundedRect(data, width, x, y, rectWidth, rectHeight, radius, rgb) {
+  const r = Math.max(0, Math.min(radius, Math.floor(rectWidth / 2), Math.floor(rectHeight / 2)));
+  if (r <= 0) {
+    fillImageRect(data, width, x, y, rectWidth, rectHeight, rgb);
+    return;
+  }
+  const leftCenter = x + r;
+  const rightCenter = x + rectWidth - r - 1;
+  const topCenter = y + r;
+  const bottomCenter = y + rectHeight - r - 1;
+  const rr = r * r;
+  for (let yy = y; yy < y + rectHeight; yy++) {
+    for (let xx = x; xx < x + rectWidth; xx++) {
+      let dx = 0;
+      let dy = 0;
+      if (xx < leftCenter) dx = leftCenter - xx;
+      else if (xx > rightCenter) dx = xx - rightCenter;
+      if (yy < topCenter) dy = topCenter - yy;
+      else if (yy > bottomCenter) dy = yy - bottomCenter;
+      if (dx * dx + dy * dy <= rr) setImagePixel(data, width, xx, yy, rgb);
+    }
+  }
+}
+
+function renderToCanvas(codeOrMatrix, canvas, options = {}) {
+  assert(canvas && typeof canvas.getContext === "function", "A canvas element is required.");
+  const matrix = Array.isArray(codeOrMatrix) ? codeOrMatrix : codeOrMatrix.matrix;
+  assert(Array.isArray(matrix) && matrix.length > 0, "A matrix is required.");
+  const moduleSize = Math.max(1, Math.floor(options.moduleSize ?? 12));
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
+  const palette = resolvePalette(options.palette);
+  const paletteValues = paletteRgb(options.palette);
+  const style = normalizeRenderStyle(options.style);
+  const layout = renderLayoutForMatrix(matrix);
+  const size = matrix.length;
+  const pixelSize = (size + quietZone * 2) * moduleSize;
+
+  canvas.width = pixelSize;
+  canvas.height = pixelSize;
+  const ctx = canvas.getContext("2d", { alpha: false, willReadFrequently: true });
+  ctx.imageSmoothingEnabled = false;
+  ctx.fillStyle = palette.white;
+  ctx.fillRect(0, 0, pixelSize, pixelSize);
+
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) {
+      const cell = matrix[r][c];
+      const structural = isStructuralRenderCell(layout, r, c, cell);
+      const x = (c + quietZone) * moduleSize;
+      const y = (r + quietZone) * moduleSize;
+
+      if (style === RENDER_STYLES.CLASSIC || structural) {
+        ctx.fillStyle = cellColor(cell, palette);
+        ctx.fillRect(x, y, moduleSize, moduleSize);
+        continue;
+      }
+
+      const rgb = cellRgb(cell, paletteValues);
+
+      if (style === RENDER_STYLES.DEPTH) {
+        const opacity = depthOpacity(r, c, cell);
+        const base = mixRgb(paletteValues.white, rgb, opacity);
+        ctx.fillStyle = rgbCss(base);
+        ctx.fillRect(x, y, moduleSize, moduleSize);
+
+        if (moduleSize >= 6) {
+          const edge = Math.max(1, Math.floor(moduleSize * 0.08));
+          const highlight = mixRgb(base, paletteValues.white, 0.17);
+          const shadow = mixRgb(base, paletteValues.black, 0.12);
+          ctx.fillStyle = rgbCss(highlight);
+          ctx.fillRect(x, y, moduleSize, edge);
+          ctx.fillRect(x, y, edge, moduleSize);
+          ctx.fillStyle = rgbCss(shadow);
+          ctx.fillRect(x, y + moduleSize - edge, moduleSize, edge);
+          ctx.fillRect(x + moduleSize - edge, y, edge, moduleSize);
+        }
+        continue;
+      }
+
+      if (style === RENDER_STYLES.SOFT) {
+        const inset = moduleSize >= 6 ? Math.max(1, Math.floor(moduleSize * 0.07)) : 0;
+        const width = moduleSize - inset * 2;
+        const radius = Math.max(1, Math.floor(moduleSize * 0.20));
+        ctx.fillStyle = cellColor(cell, palette);
+        roundedRectPath(ctx, x + inset, y + inset, width, width, radius);
+        ctx.fill();
+        continue;
+      }
+
+      if (style === RENDER_STYLES.INSET) {
+        // Keep the exact encoded color across the full module, then limit the
+        // recessed effect to a narrow edge band so center sampling stays intact.
+        ctx.fillStyle = cellColor(cell, palette);
+        ctx.fillRect(x, y, moduleSize, moduleSize);
+        if (cell === CELL.WHITE) continue;
+
+        const edge = safeStyleEdge(moduleSize);
+        if (edge > 0) {
+          const fx = insetStyleColors(rgb, paletteValues);
+          ctx.fillStyle = rgbCss(fx.shadow);
+          ctx.fillRect(x, y, moduleSize, edge);
+          ctx.fillRect(x, y, edge, moduleSize);
+          ctx.fillStyle = rgbCss(fx.highlight);
+          ctx.fillRect(x, y + moduleSize - edge, moduleSize, edge);
+          ctx.fillRect(x + moduleSize - edge, y, edge, moduleSize);
+        }
+      }
+    }
+  }
+  return canvas;
+}
+
+function renderToImageData(codeOrMatrix, options = {}) {
+  const matrix = Array.isArray(codeOrMatrix) ? codeOrMatrix : codeOrMatrix.matrix;
+  assert(Array.isArray(matrix) && matrix.length > 0, "A matrix is required.");
+  const moduleSize = Math.max(1, Math.floor(options.moduleSize ?? 8));
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
+  const palette = paletteRgb(options.palette);
+  const style = normalizeRenderStyle(options.style);
+  const layout = renderLayoutForMatrix(matrix);
+  const size = matrix.length;
+  const pixelSize = (size + quietZone * 2) * moduleSize;
+  const data = new Uint8ClampedArray(pixelSize * pixelSize * 4);
+  const white = palette.white;
+
+  for (let i = 0; i < pixelSize * pixelSize; i++) {
+    const p = i * 4;
+    data[p] = white.r;
+    data[p + 1] = white.g;
+    data[p + 2] = white.b;
+    data[p + 3] = 255;
+  }
+
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) {
+      const cell = matrix[r][c];
+      const rgb = cellRgb(cell, palette);
+      const structural = isStructuralRenderCell(layout, r, c, cell);
+      const y0 = (r + quietZone) * moduleSize;
+      const x0 = (c + quietZone) * moduleSize;
+
+      if (style === RENDER_STYLES.CLASSIC || structural) {
+        fillImageRect(data, pixelSize, x0, y0, moduleSize, moduleSize, rgb);
+        continue;
+      }
+
+      if (style === RENDER_STYLES.DEPTH) {
+        const opacity = depthOpacity(r, c, cell);
+        const base = mixRgb(white, rgb, opacity);
+        fillImageRect(data, pixelSize, x0, y0, moduleSize, moduleSize, base);
+        if (moduleSize >= 6) {
+          const edge = Math.max(1, Math.floor(moduleSize * 0.08));
+          const highlight = mixRgb(base, white, 0.17);
+          const shadow = mixRgb(base, palette.black, 0.12);
+          fillImageRect(data, pixelSize, x0, y0, moduleSize, edge, highlight);
+          fillImageRect(data, pixelSize, x0, y0, edge, moduleSize, highlight);
+          fillImageRect(data, pixelSize, x0, y0 + moduleSize - edge, moduleSize, edge, shadow);
+          fillImageRect(data, pixelSize, x0 + moduleSize - edge, y0, edge, moduleSize, shadow);
+        }
+        continue;
+      }
+
+      if (style === RENDER_STYLES.SOFT) {
+        const inset = moduleSize >= 6 ? Math.max(1, Math.floor(moduleSize * 0.07)) : 0;
+        const width = moduleSize - inset * 2;
+        const radius = Math.max(1, Math.floor(moduleSize * 0.20));
+        fillImageRoundedRect(data, pixelSize, x0 + inset, y0 + inset, width, width, radius, rgb);
+        continue;
+      }
+
+      if (style === RENDER_STYLES.INSET) {
+        fillImageRect(data, pixelSize, x0, y0, moduleSize, moduleSize, rgb);
+        if (cell === CELL.WHITE) continue;
+        const edge = safeStyleEdge(moduleSize);
+        if (edge > 0) {
+          const fx = insetStyleColors(rgb, palette);
+          fillImageRect(data, pixelSize, x0, y0, moduleSize, edge, fx.shadow);
+          fillImageRect(data, pixelSize, x0, y0, edge, moduleSize, fx.shadow);
+          fillImageRect(data, pixelSize, x0, y0 + moduleSize - edge, moduleSize, edge, fx.highlight);
+          fillImageRect(data, pixelSize, x0 + moduleSize - edge, y0, edge, moduleSize, fx.highlight);
+        }
+      }
+    }
+  }
+
+  return { width: pixelSize, height: pixelSize, data };
+}
+
+function classifierFromPaletteRgb(observed) {
+  return [
+    { cell: CELL.BLACK, rgb: observed.black },
+    { cell: CELL.WHITE, rgb: observed.white },
+    { cell: CELL.RED, rgb: observed.red },
+    { cell: CELL.GREEN, rgb: observed.green },
+    { cell: CELL.BLUE, rgb: observed.blue }
+  ];
+}
+
+function colorDistanceSq(a, b) {
+  const dr = a.r - b.r;
+  const dg = a.g - b.g;
+  const db = a.b - b.b;
+  return dr * dr + dg * dg + db * db;
+}
+
+function classifyRgb(rgb, classifier) {
+  let best = null;
+  let bestDistanceSq = Infinity;
+  let secondDistanceSq = Infinity;
+
+  for (const candidate of classifier) {
+    const distanceSq = colorDistanceSq(rgb, candidate.rgb);
+    if (distanceSq < bestDistanceSq) {
+      secondDistanceSq = bestDistanceSq;
+      bestDistanceSq = distanceSq;
+      best = candidate;
+    } else if (distanceSq < secondDistanceSq) {
+      secondDistanceSq = distanceSq;
+    }
+  }
+
+  const distance = Math.sqrt(bestDistanceSq);
+  const secondDistance = Number.isFinite(secondDistanceSq) ? Math.sqrt(secondDistanceSq) : distance + 1;
+  // Confidence is the normalized separation between the nearest and second
+  // nearest calibrated palette states. 1 means unambiguous, 0 means tied.
+  const confidence = Math.max(0, Math.min(1, (secondDistance - distance) / Math.max(secondDistance, 1e-6)));
+  return { cell: best.cell, distance, confidence };
+}
+
+function classifySampledRgbGrid(rgbGrid, classifier, layout = null) {
+  const size = rgbGrid.length;
+  const matrix = make2D(size, CELL.WHITE);
+  const confidence = make2D(size, 1);
+  const dataClassifier = classifier.filter(({ cell }) => cell !== CELL.BLACK);
+  let distanceSum = 0;
+  let confidenceSum = 0;
+  let minimumConfidence = 1;
+  let lowConfidenceCells = 0;
+
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) {
+      // Black is structural only. Restricting data modules to RGBW keeps a
+      // shadowed/blurred data sample representable so confidence-aware ECC can
+      // promote it to an erasure instead of aborting before RS gets a chance.
+      const candidates = layout && !layout.reserved[r][c] ? dataClassifier : classifier;
+      const classified = classifyRgb(rgbGrid[r][c], candidates);
+      matrix[r][c] = classified.cell;
+      confidence[r][c] = classified.confidence;
+      distanceSum += classified.distance;
+      confidenceSum += classified.confidence;
+      minimumConfidence = Math.min(minimumConfidence, classified.confidence);
+      if (classified.confidence < 0.4) lowConfidenceCells++;
+    }
+  }
+  return {
+    matrix,
+    confidence,
+    averageColorDistance: distanceSum / (size * size),
+    averageCellConfidence: confidenceSum / (size * size),
+    minimumCellConfidence: minimumConfidence,
+    lowConfidenceCells
+  };
+}
+
+function tryPerspectiveScan(imageData, options) {
+  const geometryCandidates = detectCodeGeometry(imageData, {
+    minVersion: options.minVersion ?? MIN_VERSION,
+    maxVersion: options.maxVersion ?? MAX_VERSION,
+    maxCandidates: options.maxGeometryCandidates ?? 8
+  });
+  const results = [];
+
+  for (const geometry of geometryCandidates) {
+    try {
+      const layout = createLayout(geometry.version);
+      const sampled = samplePerspectiveMatrix(imageData, geometry.homography, layout.size, {
+        sampleRadius: options.sampleRadius ?? 0.16
+      });
+      const observedPalette = sampleObservedPalette(sampled.rgbGrid, layout.calibration);
+      const classifier = classifierFromPaletteRgb(observedPalette);
+      const classified = classifySampledRgbGrid(sampled.rgbGrid, classifier, layout);
+      const decoded = decodeMatrix(classified.matrix, {
+        structureTolerance: options.structureTolerance ?? 0.18,
+        cellConfidence: classified.confidence,
+        maxErasureConfidence: options.maxErasureConfidence
+      });
+      if (decoded.version !== geometry.version) continue;
+
+      results.push({
+        ...decoded,
+        perspectiveCorrected: true,
+        colorCalibrated: true,
+        geometry,
+        observedPalette,
+        averageColorDistance: classified.averageColorDistance,
+        averageCellConfidence: classified.averageCellConfidence,
+        minimumCellConfidence: classified.minimumCellConfidence,
+        lowConfidenceCells: classified.lowConfidenceCells,
+        rectified: options.includeRectified
+          ? rectifyImageData(imageData, geometry.homography, layout.size, options.rectifiedModuleSize ?? 8)
+          : undefined
+      });
+    } catch {
+      // Continue trying geometry hypotheses.
+    }
+  }
+
+  results.sort((a, b) =>
+    (a.correctedSymbols - b.correctedSymbols) ||
+    (a.averageColorDistance - b.averageColorDistance) ||
+    (b.geometry.score - a.geometry.score)
+  );
+  return results[0] ?? null;
+}
+
+function tryAxisAlignedScan(imageData, options) {
+  const bounds = options.bounds ?? findActiveBounds(imageData, options.whiteThreshold ?? 238);
+  const fixedClassifier = classifierFromPaletteRgb(paletteRgb(options.palette));
+  const minVersion = options.minVersion ?? MIN_VERSION;
+  const maxVersion = options.maxVersion ?? MAX_VERSION;
+  const candidates = [];
+
+  for (let version = minVersion; version <= maxVersion; version++) {
+    const size = sizeForVersion(version);
+    const moduleW = bounds.width / size;
+    const moduleH = bounds.height / size;
+    if (moduleW < 0.75 || moduleH < 0.75) continue;
+    const aspectError = Math.abs(moduleW - moduleH) / Math.max(moduleW, moduleH);
+    if (aspectError > (options.maxModuleAspectError ?? 0.16)) continue;
+
+    try {
+      const sampled = sampleAxisAlignedGrid(imageData, bounds, size, options.sampleRadius ?? 0.18);
+      const classifierAttempts = [];
+      const layout = createLayout(version);
+      try {
+        const observedPalette = sampleObservedPalette(sampled.rgbGrid, layout.calibration);
+        classifierAttempts.push({ classifier: classifierFromPaletteRgb(observedPalette), calibrated: true });
+      } catch {
+        // Fixed palette fallback below.
+      }
+      classifierAttempts.push({ classifier: fixedClassifier, calibrated: false });
+
+      let accepted = false;
+      for (const attempt of classifierAttempts) {
+        try {
+          const classified = classifySampledRgbGrid(sampled.rgbGrid, attempt.classifier, layout);
+          const decoded = decodeMatrix(classified.matrix, {
+            structureTolerance: options.structureTolerance ?? 0.12,
+            cellConfidence: classified.confidence,
+            maxErasureConfidence: options.maxErasureConfidence
+          });
+          candidates.push({
+            ...decoded,
+            bounds,
+            sampledVersion: version,
+            moduleWidth: moduleW,
+            moduleHeight: moduleH,
+            perspectiveCorrected: false,
+            colorCalibrated: attempt.calibrated,
+            averageColorDistance: classified.averageColorDistance,
+            averageCellConfidence: classified.averageCellConfidence,
+            minimumCellConfidence: classified.minimumCellConfidence,
+            lowConfidenceCells: classified.lowConfidenceCells
+          });
+          accepted = true;
+          break;
+        } catch {
+          // Try next classifier.
+        }
+      }
+      if (!accepted) throw new Error("Axis-aligned candidate did not decode.");
+    } catch {
+      // Try next version.
+    }
+  }
+
+  candidates.sort((a, b) =>
+    (a.correctedSymbols - b.correctedSymbols) || (a.averageColorDistance - b.averageColorDistance)
+  );
+  return candidates[0] ?? null;
+}
+
+function scanImageData(imageData, options = {}) {
+  assert(imageData && imageData.data && imageData.width && imageData.height, "Valid ImageData is required.");
+  const minVersion = options.minVersion ?? MIN_VERSION;
+  const maxVersion = options.maxVersion ?? MAX_VERSION;
+  validateVersion(minVersion);
+  validateVersion(maxVersion);
+
+  if (options.perspective !== false) {
+    const perspective = tryPerspectiveScan(imageData, options);
+    if (perspective) return perspective;
+  }
+
+  if (options.axisAlignedFallback !== false) {
+    const axis = tryAxisAlignedScan(imageData, options);
+    if (axis) return axis;
+  }
+
+  throw new Error(
+    "No valid QuadQR code found. Try better lighting, fill more of the frame, keep all locator patterns visible, or use a less blurred image."
+  );
+}
+
+async function scanFile(file, options = {}) {
+  assert(typeof document !== "undefined", "scanFile is a browser API.");
+  assert(file, "A file is required.");
+  let bitmap;
+
+  if (typeof createImageBitmap === "function") {
+    bitmap = await createImageBitmap(file);
+  } else {
+    bitmap = await new Promise((resolve, reject) => {
+      const img = new Image();
+      const url = URL.createObjectURL(file);
+      img.onload = () => { URL.revokeObjectURL(url); resolve(img); };
+      img.onerror = () => { URL.revokeObjectURL(url); reject(new Error("Unable to load image.")); };
+      img.src = url;
+    });
+  }
+
+  const canvas = document.createElement("canvas");
+  canvas.width = bitmap.width;
+  canvas.height = bitmap.height;
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  ctx.drawImage(bitmap, 0, 0);
+  if (typeof bitmap.close === "function") bitmap.close();
+  return scanImageData(ctx.getImageData(0, 0, canvas.width, canvas.height), options);
+}
+
+function scanVideoFrame(video, options = {}) {
+  assert(typeof document !== "undefined", "scanVideoFrame is a browser API.");
+  assert(video && video.videoWidth && video.videoHeight, "Video frame is not ready.");
+  const maxDimension = options.maxDimension ?? 960;
+  const scale = Math.min(1, maxDimension / Math.max(video.videoWidth, video.videoHeight));
+  const width = Math.max(1, Math.round(video.videoWidth * scale));
+  const height = Math.max(1, Math.round(video.videoHeight * scale));
+  const canvas = options.canvas ?? document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d", { alpha: false, willReadFrequently: true });
+  ctx.drawImage(video, 0, 0, width, height);
+  return scanImageData(ctx.getImageData(0, 0, width, height), options);
+}
+
+async function startCameraScanner(video, options = {}) {
+  assert(typeof navigator !== "undefined" && navigator.mediaDevices?.getUserMedia, "Camera API is unavailable.");
+  assert(video, "A video element is required.");
+
+  const stream = await navigator.mediaDevices.getUserMedia(
+    options.constraints ?? {
+      audio: false,
+      video: {
+        facingMode: { ideal: "environment" },
+        width: { ideal: 1280 },
+        height: { ideal: 720 }
+      }
+    }
+  );
+
+  video.srcObject = stream;
+  video.setAttribute("playsinline", "");
+  video.muted = true;
+  await video.play();
+
+  const scanInterval = Math.max(80, options.scanInterval ?? 180);
+  const scratchCanvas = document.createElement("canvas");
+  let stopped = false;
+  let busy = false;
+  let timer = null;
+
+  const stop = () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    for (const track of stream.getTracks()) track.stop();
+    if (video.srcObject === stream) video.srcObject = null;
+  };
+
+  const scanNow = () => scanVideoFrame(video, { ...options, canvas: scratchCanvas });
+
+  const loop = async () => {
+    if (stopped) return;
+    if (!busy && video.readyState >= 2) {
+      busy = true;
+      try {
+        const result = scanNow();
+        options.onResult?.(result);
+        if (options.stopOnResult ?? true) {
+          stop();
+          return;
+        }
+      } catch (error) {
+        options.onScanMiss?.(error);
+      } finally {
+        busy = false;
+      }
+    }
+    timer = setTimeout(loop, scanInterval);
+  };
+
+  timer = setTimeout(loop, 0);
+  return { stream, stop, scanNow, video };
+}
+
+function rectifyDetectedCode(imageData, options = {}) {
+  const candidates = detectCodeGeometry(imageData, {
+    minVersion: options.minVersion ?? MIN_VERSION,
+    maxVersion: options.maxVersion ?? MAX_VERSION,
+    maxCandidates: 1
+  });
+  if (!candidates.length) throw new Error("Unable to locate QuadQR geometry.");
+  const geometry = candidates[0];
+  return {
+    geometry,
+    imageData: rectifyImageData(
+      imageData,
+      geometry.homography,
+      sizeForVersion(geometry.version),
+      options.moduleSize ?? 8
+    )
+  };
+}
+
+function rotateMatrix(matrix, quarterTurns = 1) {
+  let out = cloneMatrix(matrix);
+  const turns = ((quarterTurns % 4) + 4) % 4;
+  for (let i = 0; i < turns; i++) out = rotate90(out);
+  return out;
+}
+
+const internals = Object.freeze({
+  sizeForVersion,
+  versionFromSize,
+  streamCellCount,
+  createLayout,
+  alignmentPatternCentersForVersion,
+  bytesToCells,
+  cellsToBytes,
+  getBodyRsPlan,
+  getHeaderPlan,
+  interleaveBlocks,
+  deinterleaveBlocks,
+  spectralPermutation,
+  applyData,
+  unmaskCells,
+  restoreLogicalOrder,
+  cellsToSymbolConfidences,
+  decodeRsAdaptive,
+  encodeProtectedHeader,
+  decodeProtectedHeader,
+  HEADER_CODEWORD_CELLS,
+  COMPACT_HEADER_CODEWORD_CELLS,
+  CELLS_PER_BYTE,
+  TEXT_FLAG,
+  SECURE_FLAG
+});
+
+return { installCrc32Accelerator, crc32, getVersionInfo, encodeText, encodeBytes, encodeSecureText, encodeSecureBytes, decryptDecoded, decodeMatrix, renderToCanvas, renderToImageData, scanImageData, scanFile, scanVideoFrame, startCameraScanner, rectifyDetectedCode, rotateMatrix, FORMAT_VERSION, MIN_VERSION, MAX_VERSION, DEFAULT_ECC_LEVEL, CELL, DEFAULT_PALETTE, RENDER_STYLES, ECC_LEVELS, internals, SECURITY_MODES, SECURITY_ALGORITHMS, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, generateRaw256Key, normalizeRaw256Key, bytesToHex };
+})();
+const QuadQR = __qqr_quadqr_js;
+
+QuadQR.initWasm = async function initWasm(options = {}) {
+  const url = options.url
+    ? new URL(options.url, __qqrScriptSrc || (typeof location !== "undefined" ? location.href : undefined))
+    : (__qqrScriptSrc
+      ? new URL("./wasm/quadqr-core.wasm", __qqrScriptSrc)
+      : new URL("./wasm/quadqr-core.wasm", location.href));
+  const response = options.bytes ? null : await fetch(url);
+  if (response && !response.ok) throw new Error("Unable to load QuadQR WASM (" + response.status + ").");
+  const bytes = options.bytes instanceof Uint8Array
+    ? options.bytes
+    : options.bytes
+      ? new Uint8Array(options.bytes)
+      : new Uint8Array(await response.arrayBuffer());
+  const result = await WebAssembly.instantiate(bytes, {});
+  const instance = result.instance;
+  const memory = instance.exports.memory;
+  const crc32Bytes = instance.exports.crc32_bytes;
+  const heapExport = instance.exports.__heap_base;
+  const heapBase = Number((heapExport && heapExport.value) || heapExport || 65536);
+  if (!(memory instanceof WebAssembly.Memory) || typeof crc32Bytes !== "function") {
+    throw new Error("QuadQR WASM exports are invalid.");
+  }
+  QuadQR.installCrc32Accelerator(function (input) {
+    const data = input instanceof Uint8Array ? input : new Uint8Array(input);
+    const required = heapBase + data.length;
+    if (required > memory.buffer.byteLength) memory.grow(Math.ceil((required - memory.buffer.byteLength) / 65536));
+    new Uint8Array(memory.buffer, heapBase, data.length).set(data);
+    return crc32Bytes(heapBase, data.length) >>> 0;
+  });
+  return Object.freeze({ enabled: true, module: "quadqr-core", accelerators: Object.freeze(["crc32"]), bytes: bytes.length });
+};
+global.QuadQR = QuadQR;
+})(typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : this);