quadqr-js 1.3.0 → 1.5.2

package/dist/esm/quadqr.js

@@ -24,6 +24,8 @@ import {
   alignmentPatternCentersForVersion,
   alignmentPatternIsBlack,
   alignmentPatternRadius,
+  ALIGNMENT_PROFILE_STANDARD_5,
+  ALIGNMENT_PROFILE_LEGACY_3,
   sizeForVersion,
   versionFromSize
 } from "./geometry.js";
@@ -53,10 +55,26 @@ import {
   DEFAULT_PBKDF2_ITERATIONS,
   generateRaw256Key,
   normalizeRaw256Key,
-  bytesToHex
+  bytesToHex,
+  estimateSecureEnvelopeOverhead
 } from "./security.js";
-
-export const FORMAT_VERSION = 5;
+import {
+  compressDeflatePayload as compressDeflateBytes,
+  decompressDeflatePayload as decompressDeflateBytes,
+  DEFAULT_DEFLATE_LEVEL,
+  DEFLATE_LEVEL_MIN,
+  DEFLATE_LEVEL_MAX
+} from "./deflate.js";
+import {
+  compressBrotliPayload as compressBrotliBytes,
+  decompressBrotliPayload as decompressBrotliBytes,
+  DEFAULT_BROTLI_QUALITY,
+  BROTLI_QUALITY_MIN,
+  BROTLI_QUALITY_MAX
+} from "./brotli.js";
+
+export const FORMAT_VERSION = 6;
+export const LEGACY_FORMAT_VERSION = 5;
 export const MIN_VERSION = 1;
 export const MAX_VERSION = 40;
 export const DEFAULT_ECC_LEVEL = "M";
@@ -85,7 +103,30 @@ export const PRINT_PALETTE = Object.freeze({
 export const COMPRESSION_MODES = Object.freeze({
   NONE: "none",
   AUTO: "auto",
-  LZ: "lz"
+  SMART: "smart",
+  LZ: "lz",
+  DEFLATE: "deflate",
+  BROTLI: "brotli"
+});
+
+export const LZ_LEVEL_MIN = 1;
+export const LZ_LEVEL_MAX = 9;
+export const DEFAULT_LZ_LEVEL = 6;
+
+export const COMPRESSION_LEVELS = Object.freeze({
+  lz: Object.freeze({ min: LZ_LEVEL_MIN, max: LZ_LEVEL_MAX, default: DEFAULT_LZ_LEVEL }),
+  deflate: Object.freeze({ min: DEFLATE_LEVEL_MIN, max: DEFLATE_LEVEL_MAX, default: DEFAULT_DEFLATE_LEVEL }),
+  brotli: Object.freeze({ min: BROTLI_QUALITY_MIN, max: BROTLI_QUALITY_MAX, default: DEFAULT_BROTLI_QUALITY }),
+  auto: Object.freeze({ lz: DEFAULT_LZ_LEVEL, deflate: DEFAULT_DEFLATE_LEVEL, brotli: 6 }),
+  smart: Object.freeze({
+    initialLz: DEFAULT_LZ_LEVEL,
+    initialDeflate: DEFAULT_DEFLATE_LEVEL,
+    initialBrotli: 6,
+    strongDeflate: 8,
+    strongBrotli: 9,
+    maximumDeflate: 9,
+    maximumBrotli: 11
+  })
 });
 export const SIGNATURE_ALGORITHMS = Object.freeze({ ED25519: "Ed25519" });
 
@@ -162,14 +203,14 @@ const TRIANGLE16_FLAG = 1 << 6;
 // Internal payload extension envelope. This is deliberately not a public
 // payload mode or content-type system. It exists only when compression or
 // signing needs metadata around an otherwise normal text/binary payload.
-const PAYLOAD_ENVELOPE_VERSION = 2;
+const PAYLOAD_ENVELOPE_VERSION = 3;
 const PAYLOAD_ENVELOPE_MAGIC = new Uint8Array([0x51, 0x50, 0x58, 0x31]); // QPX1
 const PAYLOAD_ENVELOPE_HEADER_BYTES = 16;
 const PAYLOAD_ENVELOPE_SIGNED_FLAG = 1;
 const PAYLOAD_ENVELOPE_COMPRESSED_FLAG = 1 << 1;
 const PAYLOAD_ENVELOPE_EMBEDDED_KEY_FLAG = 1 << 2;
-const PAYLOAD_ENVELOPE_COMPRESSION_IDS = Object.freeze({ none: 0, lz: 1 });
-const PAYLOAD_ENVELOPE_COMPRESSION_BY_ID = Object.freeze({ 0: "none", 1: "lz" });
+const PAYLOAD_ENVELOPE_COMPRESSION_IDS = Object.freeze({ none: 0, lz: 1, deflate: 2, brotli: 3 });
+const PAYLOAD_ENVELOPE_COMPRESSION_BY_ID = Object.freeze({ 0: "none", 1: "lz", 2: "deflate", 3: "brotli" });
 const PAYLOAD_ENVELOPE_SIGNATURE_IDS = Object.freeze({ none: 0, Ed25519: 1 });
 const PAYLOAD_ENVELOPE_SIGNATURE_BY_ID = Object.freeze({ 0: null, 1: "Ed25519" });
 const ECC_SHIFT = 1;
@@ -301,10 +342,36 @@ function readU16be(bytes, offset = 0) {
 
 function normalizeCompressionMode(value = "none") {
   const key = String(value).toLowerCase();
-  assert(["none", "auto", "lz"].includes(key), "compression must be none, auto, or lz.");
+  assert(["none", "auto", "smart", "lz", "deflate", "brotli"].includes(key), "compression must be none, auto, smart, lz, deflate, or brotli.");
   return key;
 }
 
+function normalizeExplicitCompressionLevel(mode, options = {}) {
+  const generic = options.compressionLevel;
+  if (mode === "lz") {
+    const value = Number(generic ?? options.lzLevel ?? DEFAULT_LZ_LEVEL);
+    assert(Number.isInteger(value) && value >= LZ_LEVEL_MIN && value <= LZ_LEVEL_MAX, `LZ compressionLevel must be ${LZ_LEVEL_MIN}..${LZ_LEVEL_MAX}.`);
+    return value;
+  }
+  if (mode === "deflate") {
+    const value = Number(generic ?? options.deflateLevel ?? DEFAULT_DEFLATE_LEVEL);
+    assert(Number.isInteger(value) && value >= DEFLATE_LEVEL_MIN && value <= DEFLATE_LEVEL_MAX, `DEFLATE compressionLevel must be ${DEFLATE_LEVEL_MIN}..${DEFLATE_LEVEL_MAX}.`);
+    return value;
+  }
+  if (mode === "brotli") {
+    const value = Number(generic ?? options.brotliQuality ?? DEFAULT_BROTLI_QUALITY);
+    assert(Number.isInteger(value) && value >= BROTLI_QUALITY_MIN && value <= BROTLI_QUALITY_MAX, `Brotli compressionLevel must be ${BROTLI_QUALITY_MIN}..${BROTLI_QUALITY_MAX}.`);
+    return value;
+  }
+  if (generic != null || options.lzLevel != null || options.deflateLevel != null || options.brotliQuality != null) {
+    assert(
+      mode === "auto" || mode === "smart",
+      "compressionLevel is only meaningful with compression: lz, compression: deflate, or compression: brotli."
+    );
+  }
+  return null;
+}
+
 function asBytes(input) {
   if (input instanceof Uint8Array) return input;
   if (ArrayBuffer.isView(input)) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
@@ -312,10 +379,27 @@ function asBytes(input) {
   return new Uint8Array(input);
 }
 
-/** Portable LZSS-style compressor used by QuadQR payload compression. */
-export function compressPayload(input) {
+/** Portable LZSS-style compressor used by QuadQR payload compression.
+ * Levels 1..9 only change encoder search effort. The wire format is unchanged,
+ * so every level is decoded by the same legacy LZ decoder. Level 6 preserves
+ * the historical QuadQR search depth and is the default.
+ */
+export function compressPayload(input, options = {}) {
   const bytes = asBytes(input);
-  if (bytes.length < 4) return bytes.slice();
+  const requestedLevel = typeof options === "number"
+    ? options
+    : (options.level ?? options.compressionLevel ?? DEFAULT_LZ_LEVEL);
+  const level = Number(requestedLevel);
+  assert(Number.isInteger(level) && level >= LZ_LEVEL_MIN && level <= LZ_LEVEL_MAX, `LZ level must be ${LZ_LEVEL_MIN}..${LZ_LEVEL_MAX}.`);
+
+  // Level 6 deliberately matches the original compressor's 32-candidate
+  // history exactly. Higher levels walk deeper chains and add bounded lazy
+  // lookahead, while lower levels reduce CPU work for faster encoding.
+  const candidateDepth = [0, 4, 8, 12, 16, 24, 32, 48, 64, 96][level];
+  const lazyDepth = [0, 0, 0, 0, 0, 0, 0, 12, 24, 48][level];
+  const lazyGain = level >= 9 ? 0 : level >= 7 ? 1 : 2;
+  const historyLimit = Math.max(candidateDepth, lazyDepth, 4);
+
   const out = [];
   const recent = new Map();
   let pos = 0;
@@ -327,38 +411,50 @@ export function compressPayload(input) {
     let list = recent.get(key);
     if (!list) recent.set(key, list = []);
     list.push(i);
-    while (list.length > 32) list.shift();
+    while (list.length > historyLimit) list.shift();
     while (list.length && i - list[0] > 4095) list.shift();
   };
 
+  const findBest = (position, maxCandidates) => {
+    let bestLength = 0;
+    let bestOffset = 0;
+    const key = keyAt(position);
+    const candidates = key >= 0 ? (recent.get(key) ?? []) : [];
+    for (let ci = candidates.length - 1, checked = 0; ci >= 0 && checked < maxCandidates; ci--, checked++) {
+      const candidate = candidates[ci];
+      const offset = position - candidate;
+      if (offset <= 0 || offset > 4095) continue;
+      let length = 0;
+      while (length < 18 && position + length < bytes.length && bytes[candidate + length] === bytes[position + length]) length++;
+      if (length >= 3 && length > bestLength) {
+        bestLength = length;
+        bestOffset = offset;
+        if (length === 18) break;
+      }
+    }
+    return { length: bestLength, offset: bestOffset };
+  };
+
   while (pos < bytes.length) {
     const flagIndex = out.length;
     out.push(0);
     let flags = 0;
     for (let token = 0; token < 8 && pos < bytes.length; token++) {
-      let bestLength = 0;
-      let bestOffset = 0;
-      const key = keyAt(pos);
-      const candidates = key >= 0 ? (recent.get(key) ?? []) : [];
-      for (let ci = candidates.length - 1; ci >= 0; ci--) {
-        const candidate = candidates[ci];
-        const offset = pos - candidate;
-        if (offset <= 0 || offset > 4095) continue;
-        let length = 0;
-        while (length < 18 && pos + length < bytes.length && bytes[candidate + length] === bytes[pos + length]) length++;
-        if (length >= 3 && length > bestLength) {
-          bestLength = length;
-          bestOffset = offset;
-          if (length === 18) break;
-        }
+      let best = findBest(pos, candidateDepth);
+
+      // Strong levels may emit one literal when the next byte begins a
+      // meaningfully longer match. This changes encoder effort only.
+      if (best.length >= 3 && lazyDepth > 0 && pos + 1 < bytes.length) {
+        const next = findBest(pos + 1, lazyDepth);
+        if (next.length > best.length + lazyGain) best = { length: 0, offset: 0 };
       }
 
-      if (bestLength >= 3) {
+      if (best.length >= 3) {
         flags |= (1 << token);
-        const encoded = ((bestOffset & 0x0fff) << 4) | ((bestLength - 3) & 0x0f);
+        const encoded = ((best.offset & 0x0fff) << 4) | ((best.length - 3) & 0x0f);
         out.push((encoded >>> 8) & 0xff, encoded & 0xff);
-        for (let i = 0; i < bestLength; i++) remember(pos + i);
-        pos += bestLength;
+        for (let i = 0; i < best.length; i++) remember(pos + i);
+        pos += best.length;
       } else {
         out.push(bytes[pos]);
         remember(pos);
@@ -394,14 +490,210 @@ export function decompressPayload(input, expectedLength = null) {
   return Uint8Array.from(out);
 }
 
-function prepareCompressedBody(payload, compression = "none") {
+/** Raw RFC 1951 fixed-Huffman DEFLATE helper used by Compression 3.0. */
+export function compressDeflatePayload(input, options = {}) {
+  return compressDeflateBytes(asBytes(input), options);
+}
+
+/** Restore a raw DEFLATE payload produced by compressDeflatePayload(). */
+export function decompressDeflatePayload(input, expectedLength = null) {
+  return decompressDeflateBytes(asBytes(input), expectedLength);
+}
+
+/** Portable Brotli helper used by Compression 3.0 in browsers and Node.js. */
+export function compressBrotliPayload(input, options = {}) {
+  return compressBrotliBytes(asBytes(input), options);
+}
+
+/** Restore a Brotli payload produced by compressBrotliPayload(). */
+export function decompressBrotliPayload(input, expectedLength = null) {
+  return decompressBrotliBytes(asBytes(input), expectedLength);
+}
+
+function makeCompressionCandidate(payload, compression, compressionLevel = null) {
+  if (compression === "none") return { body: payload, compression: "none", compressionLevel: null };
+  if (compression === "lz") {
+    return {
+      body: compressPayload(payload, { level: compressionLevel ?? DEFAULT_LZ_LEVEL }),
+      compression: "lz",
+      compressionLevel: compressionLevel ?? DEFAULT_LZ_LEVEL
+    };
+  }
+  if (compression === "deflate") {
+    return {
+      body: compressDeflatePayload(payload, { level: compressionLevel ?? DEFAULT_DEFLATE_LEVEL }),
+      compression: "deflate",
+      compressionLevel: compressionLevel ?? DEFAULT_DEFLATE_LEVEL
+    };
+  }
+  if (compression === "brotli") {
+    return {
+      body: compressBrotliPayload(payload, { quality: compressionLevel ?? DEFAULT_BROTLI_QUALITY }),
+      compression: "brotli",
+      compressionLevel: compressionLevel ?? DEFAULT_BROTLI_QUALITY
+    };
+  }
+  throw new Error(`Unsupported compression candidate ${compression}.`);
+}
+
+function candidateFinalPayloadLength(candidate, payload, options = {}) {
+  const outerFixedBytes = Math.max(0, Number(options.outerFixedBytes ?? 0) || 0);
+  if (options.envelopeAlreadyRequired) {
+    const envelopeFixedBytes = Math.max(
+      PAYLOAD_ENVELOPE_HEADER_BYTES,
+      Number(options.envelopeFixedBytes ?? PAYLOAD_ENVELOPE_HEADER_BYTES) || PAYLOAD_ENVELOPE_HEADER_BYTES
+    );
+    return outerFixedBytes + envelopeFixedBytes + candidate.body.length;
+  }
+  const innerBytes = candidate.compression === "none"
+    ? candidate.body.length
+    : PAYLOAD_ENVELOPE_HEADER_BYTES + candidate.body.length;
+  return outerFixedBytes + innerBytes;
+}
+
+function compareCompressionCandidates(a, b) {
+  if (a.finalLength !== b.finalLength) return a.finalLength - b.finalLength;
+  // Prefer the cheaper decoder when storage is exactly tied.
+  const rank = { none: 0, lz: 1, deflate: 2, brotli: 3 };
+  return (rank[a.compression] ?? 9) - (rank[b.compression] ?? 9);
+}
+
+function annotateCompressionCandidate(candidate, payload, options = {}) {
+  return { ...candidate, finalLength: candidateFinalPayloadLength(candidate, payload, options) };
+}
+
+function safeChooseCompressionVersion(payloadLength, versionOptions = {}) {
+  try {
+    return chooseVersion(payloadLength, versionOptions);
+  } catch {
+    return null;
+  }
+}
+
+function smartCompressionTarget(candidate, versionOptions = {}) {
+  const requested = versionOptions.version ?? "auto";
+  const minVersion = versionOptions.minVersion ?? MIN_VERSION;
+  const maxVersion = versionOptions.maxVersion ?? MAX_VERSION;
+
+  // A fixed version cannot become physically smaller, but Smart may still
+  // spend extra CPU when stronger compression is needed to make that exact
+  // requested version fit.
+  if (requested !== "auto") {
+    validateVersion(requested);
+    const info = getVersionInfo(requested, versionOptions);
+    if (candidate.finalLength <= info.capacityBytes) return null;
+    const gapBytes = candidate.finalLength - info.capacityBytes;
+    return {
+      currentVersion: null,
+      targetVersion: requested,
+      targetCapacityBytes: info.capacityBytes,
+      gapBytes,
+      gapRatio: candidate.finalLength > 0 ? gapBytes / candidate.finalLength : 0
+    };
+  }
+
+  const currentVersion = safeChooseCompressionVersion(candidate.finalLength, versionOptions);
+  const targetVersion = currentVersion == null ? maxVersion : currentVersion - 1;
+  if (targetVersion < minVersion) return null;
+  const info = getVersionInfo(targetVersion, versionOptions);
+  const gapBytes = Math.max(0, candidate.finalLength - info.capacityBytes);
+  return {
+    currentVersion,
+    targetVersion,
+    targetCapacityBytes: info.capacityBytes,
+    gapBytes,
+    gapRatio: candidate.finalLength > 0 ? gapBytes / candidate.finalLength : 0
+  };
+}
+
+function compressionCandidates(payload, options = {}) {
+  return [
+    makeCompressionCandidate(payload, "none"),
+    makeCompressionCandidate(payload, "lz", DEFAULT_LZ_LEVEL),
+    makeCompressionCandidate(payload, "deflate", DEFAULT_DEFLATE_LEVEL),
+    makeCompressionCandidate(payload, "brotli", 6)
+  ].map((candidate) => annotateCompressionCandidate(candidate, payload, options));
+}
+
+function chooseBestCompressionCandidate(candidates) {
+  return candidates.slice().sort(compareCompressionCandidates)[0];
+}
+
+function prepareSmartCompressedBody(payload, options = {}) {
+  const versionOptions = options.versionOptions ?? {};
+  const tried = [];
+  const seen = new Set();
+  const add = (compression, level = null) => {
+    const key = `${compression}:${level ?? ""}`;
+    if (seen.has(key)) return null;
+    seen.add(key);
+    const candidate = annotateCompressionCandidate(makeCompressionCandidate(payload, compression, level), payload, options);
+    tried.push(candidate);
+    return candidate;
+  };
+
+  add("none");
+  add("lz", DEFAULT_LZ_LEVEL);
+  add("deflate", DEFAULT_DEFLATE_LEVEL);
+  add("brotli", 6);
+  let best = chooseBestCompressionCandidate(tried);
+  const initialVersion = safeChooseCompressionVersion(best.finalLength, versionOptions);
+
+  // Smart is intentionally CPU-heavy, but it still avoids maximum-quality
+  // passes when the next smaller matrix is far outside realistic reach.
+  let target = smartCompressionTarget(best, versionOptions);
+  if (target && (target.gapRatio <= 0.30 || target.gapBytes <= 192)) {
+    add("deflate", 8);
+    add("brotli", 9);
+    best = chooseBestCompressionCandidate(tried);
+    target = smartCompressionTarget(best, versionOptions);
+
+    // Maximum passes are reserved for a genuinely close version boundary, or
+    // when the strong pass already crossed one boundary and another is close.
+    if (target && (target.gapRatio <= 0.16 || target.gapBytes <= 96)) {
+      add("deflate", 9);
+      add("brotli", 11);
+      best = chooseBestCompressionCandidate(tried);
+    }
+  }
+
+  const finalVersion = safeChooseCompressionVersion(best.finalLength, versionOptions);
+  return {
+    ...best,
+    compressionStrategy: "smart",
+    smartCompression: {
+      cpuHeavy: true,
+      initialVersion,
+      finalVersion,
+      levelsTried: tried
+        .filter((candidate) => candidate.compression === "deflate" || candidate.compression === "brotli")
+        .map((candidate) => ({ algorithm: candidate.compression, level: candidate.compressionLevel, bytes: candidate.body.length, finalBytes: candidate.finalLength }))
+    }
+  };
+}
+
+function prepareCompressedBody(payload, compression = "none", options = {}) {
   const mode = normalizeCompressionMode(compression);
-  if (mode === "none") return { body: payload, compression: "none" };
-  const compressed = compressPayload(payload);
-  if (mode === "auto" && compressed.length >= payload.length - 2) {
-    return { body: payload, compression: "none" };
+  if (mode === "none") return { ...makeCompressionCandidate(payload, "none"), compressionStrategy: "none" };
+  if (mode === "lz") {
+    const level = normalizeExplicitCompressionLevel(mode, options);
+    return { ...makeCompressionCandidate(payload, "lz", level), compressionStrategy: "explicit" };
+  }
+  if (mode === "deflate") {
+    const level = normalizeExplicitCompressionLevel(mode, options);
+    return { ...makeCompressionCandidate(payload, "deflate", level), compressionStrategy: "explicit" };
+  }
+  if (mode === "brotli") {
+    const level = normalizeExplicitCompressionLevel(mode, options);
+    return { ...makeCompressionCandidate(payload, "brotli", level), compressionStrategy: "explicit" };
   }
-  return { body: compressed, compression: "lz" };
+  if (mode === "smart") return prepareSmartCompressedBody(payload, options);
+
+  // Auto deliberately performs one balanced pass per codec. It is the fast
+  // default; Smart is the opt-in mode that spends extra CPU near QR-version
+  // boundaries.
+  const best = chooseBestCompressionCandidate(compressionCandidates(payload, options));
+  return { ...best, compressionStrategy: "auto" };
 }
 
 
@@ -435,9 +727,7 @@ function isPayloadEnvelope(input) {
   return bytes.length >= PAYLOAD_ENVELOPE_HEADER_BYTES && PAYLOAD_ENVELOPE_MAGIC.every((value, index) => bytes[index] === value);
 }
 
-function packPayloadEnvelope(input, options = {}) {
-  const payload = asBytes(input);
-  const prepared = prepareCompressedBody(payload, options.compression ?? "none");
+function packPreparedPayloadEnvelope(payload, prepared) {
   const flags = prepared.compression !== "none" ? PAYLOAD_ENVELOPE_COMPRESSED_FLAG : 0;
   const header = makePayloadEnvelopeHeader({
     compression: prepared.compression,
@@ -447,11 +737,17 @@ function packPayloadEnvelope(input, options = {}) {
   return concatBytes(header, prepared.body);
 }
 
+function packPayloadEnvelope(input, options = {}) {
+  const payload = asBytes(input);
+  const prepared = prepareCompressedBody(payload, options.compression ?? "none", options);
+  return packPreparedPayloadEnvelope(payload, prepared);
+}
+
 function parsePayloadEnvelope(input) {
   const container = asBytes(input);
   assert(isPayloadEnvelope(container), "Payload extension envelope is not recognized.");
   const version = container[4];
-  assert(version === 1 || version === PAYLOAD_ENVELOPE_VERSION, `Unsupported payload extension version ${version}.`);
+  assert(version >= 1 && version <= PAYLOAD_ENVELOPE_VERSION, `Unsupported payload extension version ${version}.`);
   const flags = container[5];
   const compression = PAYLOAD_ENVELOPE_COMPRESSION_BY_ID[container[6]];
   assert(compression != null, `Unknown payload compression id ${container[6]}.`);
@@ -469,7 +765,13 @@ function parsePayloadEnvelope(input) {
   const publicKey = container.slice(endMetadata, endPublicKey);
   const signature = container.slice(endPublicKey, endSignature);
   const stored = container.slice(endSignature);
-  const payload = compression === "lz" ? decompressPayload(stored, originalLength) : stored;
+  const payload = compression === "lz"
+    ? decompressPayload(stored, originalLength)
+    : compression === "deflate"
+      ? decompressDeflatePayload(stored, originalLength)
+      : compression === "brotli"
+        ? decompressBrotliPayload(stored, originalLength)
+        : stored;
   assert(payload.length === originalLength, "Payload length mismatch after extension decoding.");
   const signed = Boolean(flags & PAYLOAD_ENVELOPE_SIGNED_FLAG);
   const signedBytes = signed ? concatBytes(container.slice(0, PAYLOAD_ENVELOPE_HEADER_BYTES), metadataBytes, publicKey, stored) : null;
@@ -558,7 +860,6 @@ async function packSignedPayloadEnvelope(input, options = {}) {
   const payload = asBytes(input);
   assert(options.privateKey, "privateKey is required to sign a QuadQR payload.");
   const subtle = subtleCrypto();
-  const prepared = prepareCompressedBody(payload, options.compression ?? "auto");
   const keyIdBytes = normalizeSigningKeyId(options.keyId);
 
   let publicKeyBytes = new Uint8Array(0);
@@ -568,6 +869,14 @@ async function packSignedPayloadEnvelope(input, options = {}) {
     publicKeyBytes = new Uint8Array(await subtle.exportKey("raw", publicKeyObject));
   }
 
+  const signedEnvelopeFixedBytes = PAYLOAD_ENVELOPE_HEADER_BYTES + keyIdBytes.length + publicKeyBytes.length + 64;
+  const prepared = prepareCompressedBody(payload, options.compression ?? "auto", {
+    ...options,
+    envelopeAlreadyRequired: true,
+    envelopeFixedBytes: signedEnvelopeFixedBytes,
+    versionOptions: options.versionOptions ?? options
+  });
+
   const flags = PAYLOAD_ENVELOPE_SIGNED_FLAG |
     (prepared.compression !== "none" ? PAYLOAD_ENVELOPE_COMPRESSED_FLAG : 0) |
     (publicKeyBytes.length ? PAYLOAD_ENVELOPE_EMBEDDED_KEY_FLAG : 0);
@@ -584,7 +893,13 @@ async function packSignedPayloadEnvelope(input, options = {}) {
   const privateKey = await normalizeEd25519PrivateKey(options.privateKey);
   const signature = new Uint8Array(await subtle.sign({ name: "Ed25519" }, privateKey, signedBytes));
   assert(signature.length === 64, "Unexpected Ed25519 signature length.");
-  return concatBytes(header, keyIdBytes, publicKeyBytes, signature, prepared.body);
+  return {
+    envelope: concatBytes(header, keyIdBytes, publicKeyBytes, signature, prepared.body),
+    compression: prepared.compression,
+    compressionLevel: prepared.compressionLevel ?? null,
+    compressionStrategy: prepared.compressionStrategy ?? null,
+    smartCompression: prepared.smartCompression ?? null
+  };
 }
 
 function lookupTrustedSigningKey(trustedKeys, keyId) {
@@ -604,7 +919,7 @@ async function verifyPayloadEnvelopeSignature(input, options = {}) {
   let trustSource = trusted ? "external" : null;
 
   // Legacy v1 symbols embedded the public key by default, so preserve their
-  // historical self-verification behavior. v2 requires explicit opt-in.
+  // historical self-verification behavior. v2+ require explicit opt-in.
   if (!trusted && parsed.publicKey.length && (parsed.version === 1 || options.allowEmbeddedKey === true)) {
     trusted = parsed.publicKey;
     trustSource = "embedded";
@@ -635,19 +950,31 @@ async function verifyPayloadEnvelopeSignature(input, options = {}) {
   };
 }
 
-function prepareOptionalCompressedPayload(input, compression = "none") {
+function prepareOptionalCompressedPayload(input, compression = "none", options = {}) {
   const payload = asBytes(input);
   const mode = normalizeCompressionMode(compression);
-  if (mode === "none") return { payload, extended: false, compression: "none" };
-  const prepared = prepareCompressedBody(payload, mode);
-  // Auto mode is truly zero-overhead when compression does not help.
-  if (mode === "auto" && prepared.compression === "none") {
-    return { payload, extended: false, compression: "none" };
+  if (mode === "none") {
+    return { payload, extended: false, compression: "none", compressionLevel: null, compressionStrategy: "none", smartCompression: null };
+  }
+  const prepared = prepareCompressedBody(payload, mode, { ...options, versionOptions: options.versionOptions ?? options });
+  // Auto and Smart are truly zero-overhead when compression does not help.
+  if ((mode === "auto" || mode === "smart") && prepared.compression === "none") {
+    return {
+      payload,
+      extended: false,
+      compression: "none",
+      compressionLevel: null,
+      compressionStrategy: prepared.compressionStrategy,
+      smartCompression: prepared.smartCompression ?? null
+    };
   }
   return {
-    payload: packPayloadEnvelope(payload, { compression: prepared.compression }),
+    payload: packPreparedPayloadEnvelope(payload, prepared),
     extended: true,
-    compression: prepared.compression
+    compression: prepared.compression,
+    compressionLevel: prepared.compressionLevel ?? null,
+    compressionStrategy: prepared.compressionStrategy ?? mode,
+    smartCompression: prepared.smartCompression ?? null
   };
 }
 
@@ -809,7 +1136,7 @@ function getEffectiveEcc(version, eccLevel) {
   return version === COMPACT_VERSION ? COMPACT_ECC_LEVELS[normalized] : ECC_LEVELS[normalized];
 }
 
-function makeHeader(payloadLength, flags, version) {
+function makeHeader(payloadLength, flags, version, formatVersion = FORMAT_VERSION) {
   assert(payloadLength >= 0 && payloadLength <= 0xffffffff, "Payload is too large.");
 
   if (version === COMPACT_VERSION) {
@@ -824,7 +1151,7 @@ function makeHeader(payloadLength, flags, version) {
 
   const header = new Uint8Array(HEADER_BYTES);
   header.set(MAGIC, 0);
-  header[4] = FORMAT_VERSION;
+  header[4] = formatVersion;
   header[5] = flags & 0xff;
   header.set(u32be(payloadLength), 6);
   return header;
@@ -846,14 +1173,22 @@ function parseHeader(header, version) {
     return { flags: header[1], payloadLength: header[2] };
   }
 
-  if (!magicMatches(header) || header[4] !== FORMAT_VERSION) {
+  const formatVersion = header[4];
+  if (!magicMatches(header) || (formatVersion !== FORMAT_VERSION && formatVersion !== LEGACY_FORMAT_VERSION)) {
     throw new Error("QuadQR magic/version mismatch.");
   }
-  return { flags: header[5], payloadLength: readU32be(header, 6) };
+  return { formatVersion, flags: header[5], payloadLength: readU32be(header, 6) };
+}
+
+function alignmentProfileForFormat(formatVersion = FORMAT_VERSION) {
+  return formatVersion === LEGACY_FORMAT_VERSION
+    ? ALIGNMENT_PROFILE_LEGACY_3
+    : ALIGNMENT_PROFILE_STANDARD_5;
 }
 
-function createLayout(version) {
+function createLayout(version, options = {}) {
   validateVersion(version);
+  const alignmentProfile = options.alignmentProfile ?? alignmentProfileForFormat(options.formatVersion ?? FORMAT_VERSION);
   const size = sizeForVersion(version);
   const matrix = make2D(size, CELL.WHITE);
   const reserved = make2D(size, false);
@@ -981,7 +1316,7 @@ function createLayout(version) {
     reserveAndSet(row, 6, row % 2 === 0 ? CELL.BLACK : CELL.WHITE);
   }
 
-  const alignments = alignmentPatternCentersForVersion(version).map(drawAlignmentPattern);
+  const alignments = alignmentPatternCentersForVersion(version, { profile: alignmentProfile }).map(drawAlignmentPattern);
   const alignment = alignments[alignments.length - 1];
   const calibrationStrip = drawCalibrationStrip();
 
@@ -1005,6 +1340,7 @@ function createLayout(version) {
   return {
     version,
     size,
+    alignmentProfile,
     matrix,
     reserved,
     dataPositions,
@@ -1367,6 +1703,9 @@ function finalizeMatrix(layout, rawCells, meta) {
     secure: Boolean(meta.secure),
     compressed: meta.compression != null && meta.compression !== "none",
     compression: meta.compression ?? "none",
+    compressionLevel: meta.compressionLevel ?? null,
+    compressionStrategy: meta.compressionStrategy ?? null,
+    smartCompression: meta.smartCompression ?? null,
     signed: Boolean(meta.signed),
     signingKeyId: meta.signingKeyId ?? null,
     hasEmbeddedPublicKey: Boolean(meta.hasEmbeddedPublicKey),
@@ -1427,6 +1766,9 @@ function encodePreparedBytes(input, options = {}) {
     extended,
     signed,
     compression: options.compressionMetadata ?? "none",
+    compressionLevel: options.compressionLevelMetadata ?? null,
+    compressionStrategy: options.compressionStrategyMetadata ?? null,
+    smartCompression: options.smartCompressionMetadata ?? null,
     signingKeyId: options.signingKeyId ?? null,
     hasEmbeddedPublicKey: Boolean(options.hasEmbeddedPublicKey),
     security: options.securityMetadata ?? null,
@@ -1442,25 +1784,31 @@ function encodePreparedBytes(input, options = {}) {
 export function encodeText(text, options = {}) {
   assert(typeof text === "string", "encodeText expects a string.");
   const source = getTextEncoder().encode(text);
-  const prepared = prepareOptionalCompressedPayload(source, options.compression ?? "none");
+  const prepared = prepareOptionalCompressedPayload(source, options.compression ?? "none", options);
   return encodePreparedBytes(prepared.payload, {
     ...options,
     text: true,
     extended: prepared.extended,
     sourcePayloadBytes: source.length,
-    compressionMetadata: prepared.compression
+    compressionMetadata: prepared.compression,
+    compressionLevelMetadata: prepared.compressionLevel,
+    compressionStrategyMetadata: prepared.compressionStrategy,
+    smartCompressionMetadata: prepared.smartCompression
   });
 }
 
 export function encodeBytes(input, options = {}) {
   const source = asBytes(input);
-  const prepared = prepareOptionalCompressedPayload(source, options.compression ?? "none");
+  const prepared = prepareOptionalCompressedPayload(source, options.compression ?? "none", options);
   return encodePreparedBytes(prepared.payload, {
     ...options,
     text: Boolean(options.text),
     extended: prepared.extended,
     sourcePayloadBytes: source.length,
-    compressionMetadata: prepared.compression
+    compressionMetadata: prepared.compression,
+    compressionLevelMetadata: prepared.compressionLevel,
+    compressionStrategyMetadata: prepared.compressionStrategy,
+    smartCompressionMetadata: prepared.smartCompression
   });
 }
 
@@ -1472,15 +1820,18 @@ export function encodeUint8Array(input, options = {}) {
 /** Encode and sign a normal payload using an internal Ed25519 envelope. */
 export async function encodeSignedBytes(input, options = {}) {
   const source = asBytes(input);
-  const envelope = await packSignedPayloadEnvelope(source, options);
-  const parsed = parsePayloadEnvelope(envelope);
-  return encodePreparedBytes(envelope, {
+  const packed = await packSignedPayloadEnvelope(source, options);
+  const parsed = parsePayloadEnvelope(packed.envelope);
+  return encodePreparedBytes(packed.envelope, {
     ...options,
     text: Boolean(options.text),
     extended: true,
     signed: true,
     sourcePayloadBytes: source.length,
     compressionMetadata: parsed.compression,
+    compressionLevelMetadata: packed.compressionLevel,
+    compressionStrategyMetadata: packed.compressionStrategy,
+    smartCompressionMetadata: packed.smartCompression,
     signingKeyId: parsed.keyId,
     hasEmbeddedPublicKey: parsed.hasEmbeddedPublicKey
   });
@@ -1505,30 +1856,47 @@ export async function encodeSecureText(text, options = {}) {
 export async function encodeSecureBytes(input, options = {}) {
   const sourcePayload = asBytes(input);
   const security = options.security ?? {};
+  const secureOuterFixedBytes = estimateSecureEnvelopeOverhead(security);
   let protectedPayload = sourcePayload;
   let extended = false;
   let signed = false;
   let compression = "none";
+  let compressionLevel = null;
+  let compressionStrategy = null;
+  let smartCompression = null;
   let signingKeyId = null;
   let hasEmbeddedPublicKey = false;
 
   if (options.signing) {
-    protectedPayload = await packSignedPayloadEnvelope(sourcePayload, {
+    const packed = await packSignedPayloadEnvelope(sourcePayload, {
       ...options,
       ...options.signing,
-      compression: options.compression ?? "auto"
+      compression: options.compression ?? "auto",
+      outerFixedBytes: secureOuterFixedBytes,
+      versionOptions: options
     });
+    protectedPayload = packed.envelope;
     const parsed = parsePayloadEnvelope(protectedPayload);
     extended = true;
     signed = true;
     compression = parsed.compression;
+    compressionLevel = packed.compressionLevel;
+    compressionStrategy = packed.compressionStrategy;
+    smartCompression = packed.smartCompression;
     signingKeyId = parsed.keyId;
     hasEmbeddedPublicKey = parsed.hasEmbeddedPublicKey;
   } else {
-    const prepared = prepareOptionalCompressedPayload(sourcePayload, options.compression ?? "none");
+    const prepared = prepareOptionalCompressedPayload(sourcePayload, options.compression ?? "none", {
+      ...options,
+      outerFixedBytes: secureOuterFixedBytes,
+      versionOptions: options
+    });
     protectedPayload = prepared.payload;
     extended = prepared.extended;
     compression = prepared.compression;
+    compressionLevel = prepared.compressionLevel;
+    compressionStrategy = prepared.compressionStrategy;
+    smartCompression = prepared.smartCompression;
   }
 
   const encrypted = await encryptSecurePayload(protectedPayload, security);
@@ -1540,6 +1908,9 @@ export async function encodeSecureBytes(input, options = {}) {
     signed,
     sourcePayloadBytes: sourcePayload.length,
     compressionMetadata: compression,
+    compressionLevelMetadata: compressionLevel,
+    compressionStrategyMetadata: compressionStrategy,
+    smartCompressionMetadata: smartCompression,
     signingKeyId,
     hasEmbeddedPublicKey,
     securityMetadata: encrypted.metadata
@@ -1618,8 +1989,8 @@ function alignmentPatternMismatchRatio(matrix, pattern) {
   return mismatches / total;
 }
 
-function alignmentGridMismatchRatio(matrix, version) {
-  const patterns = alignmentPatternCentersForVersion(version);
+function alignmentGridMismatchRatio(matrix, version, alignmentProfile = ALIGNMENT_PROFILE_STANDARD_5) {
+  const patterns = alignmentPatternCentersForVersion(version, { profile: alignmentProfile });
   let weightedMismatch = 0;
   let totalWeight = 0;
   for (const pattern of patterns) {
@@ -1631,7 +2002,7 @@ function alignmentGridMismatchRatio(matrix, version) {
   return totalWeight ? weightedMismatch / totalWeight : 0;
 }
 
-function validateStructure(matrix, tolerance = 0) {
+function validateStructure(matrix, tolerance = 0, alignmentProfile = ALIGNMENT_PROFILE_STANDARD_5) {
   const size = matrix.length;
   if (size < 21 || matrix.some((row) => row.length !== size)) return false;
   const version = versionFromSize(size);
@@ -1644,11 +2015,11 @@ function validateStructure(matrix, tolerance = 0) {
   if (finderRatios.some((ratio) => ratio > tolerance)) return false;
 
   const alignmentTolerance = Math.max(tolerance, 0.12);
-  const primary = alignmentPatternCentersForVersion(version).at(-1);
+  const primary = alignmentPatternCentersForVersion(version, { profile: alignmentProfile }).at(-1);
   if (primary && alignmentPatternMismatchRatio(matrix, primary) > alignmentTolerance) {
     return false;
   }
-  if (alignmentGridMismatchRatio(matrix, version) > alignmentTolerance) return false;
+  if (alignmentGridMismatchRatio(matrix, version, alignmentProfile) > alignmentTolerance) return false;
   return true;
 }
 
@@ -1836,13 +2207,13 @@ function decodeProtectedBody(rawCells, payloadLength, eccLevel, version, rawConf
   };
 }
 
-function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = null, options = {}) {
+function decodeCanonicalWithProfile(matrix, rotation, tolerance = 0, confidenceMatrix = null, options = {}, alignmentProfile = ALIGNMENT_PROFILE_STANDARD_5) {
   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.");
+  if (!validateStructure(matrix, tolerance, alignmentProfile)) throw new Error("QuadQR finder/alignment structure does not match.");
 
-  const layout = createLayout(version);
+  const layout = createLayout(version, { alignmentProfile });
   const errors = [];
   const hintedEncoding = options.cellEncodingHint != null
     ? normalizeCellEncoding(options.cellEncodingHint)
@@ -1892,6 +2263,10 @@ function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = nul
           );
           const header = headerDecoded.header;
           const flags = headerDecoded.flags;
+          const decodedFormatVersion = headerDecoded.formatVersion ?? FORMAT_VERSION;
+          if (version >= 7 && alignmentProfileForFormat(decodedFormatVersion) !== alignmentProfile) {
+            throw new Error(`Format v${decodedFormatVersion} uses a different alignment profile.`);
+          }
           const declaredCellEncoding = cellEncodingFromFlags(flags);
           if (declaredCellEncoding !== cellEncoding) {
             throw new Error(`Header declares ${declaredCellEncoding}, not ${cellEncoding}.`);
@@ -1929,10 +2304,11 @@ function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = nul
           return {
             ok: true,
             format: "QuadQR",
-            formatVersion: FORMAT_VERSION,
+            formatVersion: decodedFormatVersion,
             version,
             size,
             alignmentPatterns: layout.alignments.length,
+            alignmentProfile,
             maskId,
             rotation,
             flags,
@@ -1980,10 +2356,93 @@ function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = nul
   throw new Error(`QuadQR decode failed. ${errors.join(" | ")}`);
 }
 
+function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = null, options = {}) {
+  const hinted = options.alignmentProfileHint;
+  const profiles = hinted
+    ? [hinted]
+    : [ALIGNMENT_PROFILE_STANDARD_5, ALIGNMENT_PROFILE_LEGACY_3];
+  const errors = [];
+  for (const alignmentProfile of profiles) {
+    try {
+      return decodeCanonicalWithProfile(matrix, rotation, tolerance, confidenceMatrix, options, alignmentProfile);
+    } catch (error) {
+      errors.push(`${alignmentProfile}: ${error.message}`);
+    }
+  }
+  throw new Error(`QuadQR decode failed for all alignment profiles. ${errors.join(" | ")}`);
+}
+
+function trySoftMatrixDecode(matrix, alternatives, confidenceMatrix, degrees, tolerance, options = {}) {
+  if (!alternatives || !confidenceMatrix || options.softDecoding === false) return null;
+  const version = versionFromSize(matrix.length);
+  if (!version) return null;
+  const layout = createLayout(version);
+  const legacyLayout = createLayout(version, { alignmentProfile: ALIGNMENT_PROFILE_LEGACY_3 });
+  const softPositions = [];
+  const seenSoftPositions = new Set();
+  for (const [row, col] of [...layout.dataPositions, ...legacyLayout.dataPositions]) {
+    const key = `${row},${col}`;
+    if (seenSoftPositions.has(key)) continue;
+    seenSoftPositions.add(key);
+    softPositions.push([row, col]);
+  }
+  const threshold = clampNumber(options.softDecodeConfidence ?? 0.72, 0.05, 0.95);
+  const maxCells = Math.max(2, Math.min(16, Math.round(options.softDecodeMaxCells ?? 10)));
+  const pairCells = Math.max(2, Math.min(maxCells, Math.round(options.softDecodePairCells ?? 6)));
+  const ranked = [];
+
+  for (const [row, col] of softPositions) {
+    const alternative = alternatives[row]?.[col];
+    const confidence = confidenceMatrix[row]?.[col] ?? 1;
+    if (!Number.isInteger(alternative) || alternative === matrix[row][col] || confidence > threshold) continue;
+    ranked.push({ row, col, alternative, confidence });
+  }
+  ranked.sort((a, b) => (a.confidence - b.confidence) || (a.row - b.row) || (a.col - b.col));
+  const candidates = ranked.slice(0, maxCells);
+  let attempts = 0;
+
+  const attempt = (changes) => {
+    const trial = cloneMatrix(matrix);
+    for (const change of changes) trial[change.row][change.col] = change.alternative;
+    attempts++;
+    try {
+      const decoded = decodeCanonical(trial, degrees, tolerance, confidenceMatrix, {
+        ...options,
+        softDecoding: false
+      });
+      return {
+        ...decoded,
+        spectrumEccVersion: 2,
+        softDecoded: true,
+        softSubstitutions: changes.length,
+        softDecodeAttempts: attempts,
+        softDecodeCellsConsidered: candidates.length
+      };
+    } catch {
+      return null;
+    }
+  };
+
+  for (const candidate of candidates) {
+    const decoded = attempt([candidate]);
+    if (decoded) return decoded;
+  }
+
+  const pairCandidates = candidates.slice(0, pairCells);
+  for (let i = 0; i < pairCandidates.length; i++) {
+    for (let j = i + 1; j < pairCandidates.length; j++) {
+      const decoded = attempt([pairCandidates[i], pairCandidates[j]]);
+      if (decoded) return decoded;
+    }
+  }
+  return null;
+}
+
 export 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;
+  let alternativeMatrix = options.cellAlternatives ? cloneMatrix(options.cellAlternatives) : null;
   const errors = [];
   const tolerance = options.structureTolerance ?? 0;
 
@@ -1993,16 +2452,38 @@ export function decodeMatrix(inputMatrix, options = {}) {
       "cellConfidence must be a square matrix matching the QuadQR matrix."
     );
   }
+  if (alternativeMatrix) {
+    assert(
+      alternativeMatrix.length === matrix.length && alternativeMatrix.every((row) => row.length === matrix.length),
+      "cellAlternatives 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);
+      const decoded = decodeCanonical(matrix, degrees, tolerance, confidenceMatrix, options);
+      return {
+        spectrumEccVersion: 2,
+        softDecoded: false,
+        softSubstitutions: 0,
+        ...decoded
+      };
     } catch (error) {
       errors.push(`${degrees}°: ${error.message}`);
+      const softDecoded = trySoftMatrixDecode(
+        matrix,
+        alternativeMatrix,
+        confidenceMatrix,
+        degrees,
+        tolerance,
+        options
+      );
+      if (softDecoded) return softDecoded;
     }
     matrix = rotate90(matrix);
     if (confidenceMatrix) confidenceMatrix = rotate90(confidenceMatrix);
+    if (alternativeMatrix) alternativeMatrix = rotate90(alternativeMatrix);
   }
 
   throw new Error(`Unable to decode matrix. ${errors.join(" || ")}`);
@@ -2944,11 +3425,96 @@ function makeWhiteBalanceTransform(observed) {
   });
 }
 
+function solveLinearSystem(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-9) return null;
+    [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 makeAffineCalibrationTransform(observed) {
+  const ideal = {
+    black: { r: 0, g: 0, b: 0 },
+    white: { r: 255, g: 255, b: 255 },
+    red: { r: 255, g: 0, b: 0 },
+    green: { r: 0, g: 255, b: 0 },
+    blue: { r: 0, g: 0, b: 255 }
+  };
+  const keys = ["black", "white", "red", "green", "blue"];
+  const rows = keys.map((key) => {
+    const rgb = observed[key];
+    return [rgb.r, rgb.g, rgb.b, 1];
+  });
+  const normal = Array.from({ length: 4 }, () => Array(4).fill(0));
+  for (const row of rows) {
+    for (let i = 0; i < 4; i++) {
+      for (let j = 0; j < 4; j++) normal[i][j] += row[i] * row[j];
+    }
+  }
+  // A tiny ridge term keeps the transform stable if the photographed palette
+  // becomes nearly singular under severe clipping or monochromatic lighting.
+  const ridge = 1e-4;
+  for (let i = 0; i < 4; i++) normal[i][i] += ridge;
+
+  const coefficients = {};
+  for (const channel of ["r", "g", "b"]) {
+    const rhs = Array(4).fill(0);
+    for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+      const x = rows[rowIndex];
+      const y = ideal[keys[rowIndex]][channel];
+      for (let i = 0; i < 4; i++) rhs[i] += x[i] * y;
+    }
+    coefficients[channel] = solveLinearSystem(normal, rhs);
+    if (!coefficients[channel]) return null;
+  }
+
+  const transform = (rgb) => {
+    const x = [rgb.r, rgb.g, rgb.b, 1];
+    const mapChannel = (channel) => coefficients[channel].reduce((sum, value, index) => sum + value * x[index], 0);
+    return {
+      r: clampNumber(mapChannel("r"), -96, 384),
+      g: clampNumber(mapChannel("g"), -96, 384),
+      b: clampNumber(mapChannel("b"), -96, 384)
+    };
+  };
+
+  let errorSq = 0;
+  for (const key of keys) {
+    const mapped = transform(observed[key]);
+    const target = ideal[key];
+    errorSq += colorDistanceSq(mapped, target);
+  }
+  return { transform, ideal, rmsError: Math.sqrt(errorSq / (keys.length * 3)) };
+}
+
 function classifierFromPaletteRgb(observed, mode = "raw") {
-  const transform = mode === "balanced" || mode === "hue"
+  const affine = mode === "affine" ? makeAffineCalibrationTransform(observed) : null;
+  const transform = affine?.transform ?? (mode === "balanced" || mode === "hue"
     ? makeWhiteBalanceTransform(observed)
-    : identityColorTransform;
-  const entries = [
+    : identityColorTransform);
+  const idealEntries = affine ? [
+    { cell: CELL.BLACK, rgb: affine.ideal.black },
+    { cell: CELL.WHITE, rgb: affine.ideal.white },
+    { cell: CELL.RED, rgb: affine.ideal.red },
+    { cell: CELL.GREEN, rgb: affine.ideal.green },
+    { cell: CELL.BLUE, rgb: affine.ideal.blue }
+  ] : null;
+  const entries = idealEntries ?? [
     { cell: CELL.BLACK, rgb: transform(observed.black) },
     { cell: CELL.WHITE, rgb: transform(observed.white) },
     { cell: CELL.RED, rgb: transform(observed.red) },
@@ -2962,6 +3528,8 @@ function classifierFromPaletteRgb(observed, mode = "raw") {
     entries,
     transform,
     mode,
+    calibrationModel: affine ? "affine-3x4" : (mode === "balanced" || mode === "hue" ? "black-white-balance" : "observed-palette"),
+    calibrationError: affine?.rmsError ?? null,
     dataMode: mode === "hue" ? "hue" : "distance",
     whiteChroma: chroma(entries.find(({ cell }) => cell === CELL.WHITE).rgb),
     minimumColorChroma
@@ -2975,27 +3543,30 @@ function colorDistanceSq(a, b) {
   return dr * dr + dg * dg + db * db;
 }
 
-function classifyRgb(rgb, classifier) {
+function rankRgbCandidates(rgb, classifier) {
   const transformed = classifier.transform(rgb);
-  let best = null;
-  let bestDistanceSq = Infinity;
-  let secondDistanceSq = Infinity;
-
-  for (const candidate of classifier.entries) {
-    const distanceSq = colorDistanceSq(transformed, candidate.rgb);
-    if (distanceSq < bestDistanceSq) {
-      secondDistanceSq = bestDistanceSq;
-      bestDistanceSq = distanceSq;
-      best = candidate;
-    } else if (distanceSq < secondDistanceSq) {
-      secondDistanceSq = distanceSq;
-    }
-  }
+  return classifier.entries
+    .map((candidate) => ({
+      cell: candidate.cell,
+      rgb: candidate.rgb,
+      distance: Math.sqrt(colorDistanceSq(transformed, candidate.rgb))
+    }))
+    .sort((a, b) => (a.distance - b.distance) || (a.cell - b.cell));
+}
 
-  const distance = Math.sqrt(bestDistanceSq);
-  const secondDistance = Number.isFinite(secondDistanceSq) ? Math.sqrt(secondDistanceSq) : distance + 1;
-  const confidence = Math.max(0, Math.min(1, (secondDistance - distance) / Math.max(secondDistance, 1e-6)));
-  return { cell: best.cell, distance, confidence };
+function classifyRgb(rgb, classifier) {
+  const ranked = rankRgbCandidates(rgb, classifier);
+  const best = ranked[0];
+  const second = ranked[1] ?? { cell: best.cell, distance: best.distance + 1 };
+  const confidence = Math.max(0, Math.min(1, (second.distance - best.distance) / Math.max(second.distance, 1e-6)));
+  return {
+    cell: best.cell,
+    distance: best.distance,
+    confidence,
+    alternativeCell: second.cell,
+    alternativeDistance: second.distance,
+    ambiguity: 1 - confidence
+  };
 }
 
 
@@ -3031,6 +3602,7 @@ function classifySampledRgbGrid(rgbGrid, classifier, layout = null) {
   const size = rgbGrid.length;
   const matrix = make2D(size, CELL.WHITE);
   const confidence = make2D(size, 1);
+  const alternatives = make2D(size, null);
   const dataClassifier = {
     ...classifier,
     entries: classifier.entries.filter(({ cell }) => cell !== CELL.BLACK)
@@ -3050,8 +3622,11 @@ function classifySampledRgbGrid(rgbGrid, classifier, layout = null) {
       const classified = isDataCell && classifier.dataMode === "hue"
         ? classifyDataHue(rgbGrid[r][c], classifier)
         : classifyRgb(rgbGrid[r][c], candidates);
+      const ranked = rankRgbCandidates(rgbGrid[r][c], candidates);
+      const alternate = ranked.find((candidate) => candidate.cell !== classified.cell);
       matrix[r][c] = classified.cell;
       confidence[r][c] = classified.confidence;
+      alternatives[r][c] = alternate?.cell ?? null;
       distanceSum += classified.distance;
       confidenceSum += classified.confidence;
       minimumConfidence = Math.min(minimumConfidence, classified.confidence);
@@ -3061,6 +3636,7 @@ function classifySampledRgbGrid(rgbGrid, classifier, layout = null) {
   return {
     matrix,
     confidence,
+    alternatives,
     averageColorDistance: distanceSum / (size * size),
     averageCellConfidence: confidenceSum / (size * size),
     minimumCellConfidence: minimumConfidence,
@@ -3072,6 +3648,7 @@ function classifyTriangleSampledRgbGrid(rgbGrid, triangleGrid, classifier, layou
   const size = rgbGrid.length;
   const matrix = make2D(size, CELL.WHITE);
   const confidence = make2D(size, 1);
+  const alternatives = make2D(size, null);
   const dataClassifier = {
     ...classifier,
     entries: classifier.entries.filter(({ cell }) => cell !== CELL.BLACK)
@@ -3088,6 +3665,7 @@ function classifyTriangleSampledRgbGrid(rgbGrid, triangleGrid, classifier, layou
         const classified = classifyRgb(rgbGrid[r][c], classifier);
         matrix[r][c] = classified.cell;
         confidence[r][c] = classified.confidence;
+        alternatives[r][c] = classified.alternativeCell ?? null;
         distanceSum += classified.distance;
         confidenceSum += classified.confidence;
         minimumConfidence = Math.min(minimumConfidence, classified.confidence);
@@ -3102,19 +3680,35 @@ function classifyTriangleSampledRgbGrid(rgbGrid, triangleGrid, classifier, layou
         : classifyRgb(rgb, dataClassifier);
       const first = classifyData(samples.first);
       const second = classifyData(samples.second);
-      const cellConfidence = Math.min(first.confidence, second.confidence);
+      const firstRanked = rankRgbCandidates(samples.first, dataClassifier);
+      const secondRanked = rankRgbCandidates(samples.second, dataClassifier);
+      const firstAlt = firstRanked.find((candidate) => candidate.cell !== first.cell)?.cell ?? first.cell;
+      const secondAlt = secondRanked.find((candidate) => candidate.cell !== second.cell)?.cell ?? second.cell;
+      const firstSpread = Number(samples.firstSpread ?? 0);
+      const secondSpread = Number(samples.secondSpread ?? 0);
+      const stability = clampNumber(1 - Math.max(firstSpread, secondSpread) / 110, 0.35, 1);
+      const cellConfidence = Math.min(first.confidence, second.confidence) * (0.68 + stability * 0.32);
       matrix[r][c] = packTriangleCell(first.cell, second.cell);
-      confidence[r][c] = cellConfidence;
+      // Prefer changing the region with the weaker classification. If both are
+      // similarly uncertain, changing the more spatially unstable region first
+      // gives Spectrum ECC 2.0 a better second hypothesis.
+      const firstRisk = (1 - first.confidence) + firstSpread / 255;
+      const secondRisk = (1 - second.confidence) + secondSpread / 255;
+      alternatives[r][c] = firstRisk >= secondRisk
+        ? packTriangleCell(firstAlt, second.cell)
+        : packTriangleCell(first.cell, secondAlt);
+      confidence[r][c] = clampNumber(cellConfidence, 0, 1);
       distanceSum += (first.distance + second.distance) / 2;
-      confidenceSum += cellConfidence;
-      minimumConfidence = Math.min(minimumConfidence, cellConfidence);
-      if (cellConfidence < 0.4) lowConfidenceCells++;
+      confidenceSum += confidence[r][c];
+      minimumConfidence = Math.min(minimumConfidence, confidence[r][c]);
+      if (confidence[r][c] < 0.4) lowConfidenceCells++;
     }
   }
 
   return {
     matrix,
     confidence,
+    alternatives,
     averageColorDistance: distanceSum / (size * size),
     averageCellConfidence: confidenceSum / (size * size),
     minimumCellConfidence: minimumConfidence,
@@ -3144,32 +3738,37 @@ function paletteClassifierAttempts(observedPalette) {
   return [
     { classifier: classifierFromPaletteRgb(observedPalette, "raw"), colorNormalization: "observed-rgb" },
     { classifier: classifierFromPaletteRgb(observedPalette, "balanced"), colorNormalization: "white-balanced" },
+    { classifier: classifierFromPaletteRgb(observedPalette, "affine"), colorNormalization: "affine-calibrated" },
     { classifier: classifierFromPaletteRgb(observedPalette, "hue"), colorNormalization: "white-balanced-hue" }
   ];
 }
 
 function tryPerspectiveScan(imageData, options) {
-  const geometryCandidates = detectCodeGeometry(imageData, {
-    minVersion: options.minVersion ?? MIN_VERSION,
-    maxVersion: options.maxVersion ?? MAX_VERSION,
-    maxCandidates: options.maxGeometryCandidates ?? 8,
-    finderRecovery: options.finderRecovery,
-    finderAutoColorBlackClip: options.finderAutoColorBlackClip,
-    finderAutoColorWhiteClip: options.finderAutoColorWhiteClip,
-    finderAutoColorHighlightPercentile: options.finderAutoColorHighlightPercentile,
-    finderAutoColorOutputHighlight: options.finderAutoColorOutputHighlight,
-    finderAutoColorAnalysisInset: options.finderAutoColorAnalysisInset,
-    finderAutoColorMinimumInputRange: options.finderAutoColorMinimumInputRange,
-    finderAutoColorTargetSamples: options.finderAutoColorTargetSamples,
-    preciseAlignment: options.preciseAlignment,
-    diagnostics: options._visionDiagnostics,
-    diagnosticLabel: options._diagnosticLabel ?? "normal"
-  });
+  const geometryCandidates = Array.isArray(options._geometryCandidatesOverride) && options._geometryCandidatesOverride.length
+    ? options._geometryCandidatesOverride
+    : detectCodeGeometry(imageData, {
+        minVersion: options.minVersion ?? MIN_VERSION,
+        maxVersion: options.maxVersion ?? MAX_VERSION,
+        maxCandidates: options.maxGeometryCandidates ?? 8,
+        finderRecovery: options.finderRecovery,
+        finderAutoColorBlackClip: options.finderAutoColorBlackClip,
+        finderAutoColorWhiteClip: options.finderAutoColorWhiteClip,
+        finderAutoColorHighlightPercentile: options.finderAutoColorHighlightPercentile,
+        finderAutoColorOutputHighlight: options.finderAutoColorOutputHighlight,
+        finderAutoColorAnalysisInset: options.finderAutoColorAnalysisInset,
+        finderAutoColorMinimumInputRange: options.finderAutoColorMinimumInputRange,
+        finderAutoColorTargetSamples: options.finderAutoColorTargetSamples,
+        preciseAlignment: options.preciseAlignment,
+        diagnostics: options._visionDiagnostics,
+        diagnosticLabel: options._diagnosticLabel ?? "normal"
+      });
   if (Array.isArray(options._geometryCollector)) options._geometryCollector.push(...geometryCandidates);
   const results = [];
 
   for (const geometry of geometryCandidates) {
-    const layout = createLayout(geometry.version);
+    const layout = createLayout(geometry.version, {
+      alignmentProfile: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5
+    });
     const sampleProfiles = [{
       sampleMode: options.sampleMode ?? "cross",
       sampleRadius: options.sampleRadius ?? 0.16,
@@ -3206,7 +3805,7 @@ function tryPerspectiveScan(imageData, options) {
         continue;
       }
 
-      const tryAttempt = (attempt, rgbGrid, metadata = {}) => {
+      const tryAttempt = (attempt, rgbGrid, metadata = {}, allowSoftDecoding = options.softDecoding !== false) => {
         const activeObservedPalette = metadata.observedPalette ?? observedPalette;
         const activeSamplingMode = metadata.samplingMode ?? profile.sampleMode;
         const classified = classifySampledRgbGrid(rgbGrid, attempt.classifier, layout);
@@ -3216,6 +3815,7 @@ function tryPerspectiveScan(imageData, options) {
           version: geometry.version,
           matrix: classified.matrix,
           confidence: classified.confidence,
+          alternatives: classified.alternatives,
           geometry,
           observedPalette: activeObservedPalette,
           samplingMode: activeSamplingMode,
@@ -3229,6 +3829,10 @@ function tryPerspectiveScan(imageData, options) {
           const decoded = decodeMatrix(classified.matrix, {
             structureTolerance: options.structureTolerance ?? 0.18,
             cellConfidence: classified.confidence,
+            cellAlternatives: classified.alternatives,
+            cellEncodingHint: CELL_ENCODINGS.RGBW,
+            alignmentProfileHint: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
+            softDecoding: allowSoftDecoding,
             maxErasureConfidence: options.maxErasureConfidence
           });
           if (decoded.version !== geometry.version) return false;
@@ -3257,7 +3861,7 @@ function tryPerspectiveScan(imageData, options) {
         }
       };
 
-      const tryTriangleAttempt = (attempt, metadata = {}) => {
+      const tryTriangleAttempt = (attempt, metadata = {}, allowSoftDecoding = options.softDecoding !== false) => {
         if (!triangleSampled?.triangleGrid) return false;
         const activeObservedPalette = metadata.observedPalette ?? observedPalette;
         const activeSamplingMode = metadata.samplingMode ?? `${profile.sampleMode}-triangle16`;
@@ -3273,6 +3877,7 @@ function tryPerspectiveScan(imageData, options) {
           version: geometry.version,
           matrix: classified.matrix,
           confidence: classified.confidence,
+          alternatives: classified.alternatives,
           geometry,
           observedPalette: activeObservedPalette,
           samplingMode: activeSamplingMode,
@@ -3287,7 +3892,10 @@ function tryPerspectiveScan(imageData, options) {
           const decoded = decodeMatrix(classified.matrix, {
             structureTolerance: options.structureTolerance ?? 0.18,
             cellConfidence: classified.confidence,
+            cellAlternatives: classified.alternatives,
             cellEncodingHint: CELL_ENCODINGS.TRIANGLE16,
+            alignmentProfileHint: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
+            softDecoding: allowSoftDecoding,
             maxErasureConfidence: options.maxErasureConfidence
           });
           if (decoded.version !== geometry.version) return false;
@@ -3316,29 +3924,46 @@ function tryPerspectiveScan(imageData, options) {
       // Fast path: preserve the original observed-RGB classifier first, then
       // try per-channel white balancing. Most clean frames stop here without
       // paying for the more expensive spatial normalization fallback.
-      for (const attempt of paletteClassifierAttempts(observedPalette)) {
-        if (tryAttempt(attempt, sampled.rgbGrid) || tryTriangleAttempt(attempt)) {
+      const basePaletteAttempts = paletteClassifierAttempts(observedPalette);
+      for (const attempt of basePaletteAttempts) {
+        if (tryAttempt(attempt, sampled.rgbGrid, {}, false) || tryTriangleAttempt(attempt, {}, false)) {
           geometryDecoded = true;
           break;
         }
       }
+      // Spectrum ECC soft decoding is intentionally deferred until every cheap
+      // hard classifier has had a chance. This preserves the exact recovery
+      // candidates while avoiding expensive second-hypothesis RS searches when
+      // a later normal color model can decode the frame immediately.
+      if (!geometryDecoded && options.softDecoding !== false) {
+        for (const attempt of basePaletteAttempts) {
+          if (tryAttempt(attempt, sampled.rgbGrid, {}, true) || tryTriangleAttempt(attempt, {}, true)) {
+            geometryDecoded = true;
+            break;
+          }
+        }
+      }
 
       if (!geometryDecoded && options.spatialColorNormalization !== false) {
         try {
           const normalizedGrid = spatiallyNormalizeRgbGrid(sampled.rgbGrid, layout.calibration);
           const normalizedPalette = sampleObservedPalette(normalizedGrid, layout.calibration, { robust: true });
-          geometryDecoded = tryAttempt({
+          const spatialAttempt = {
             classifier: classifierFromPaletteRgb(normalizedPalette, "raw"),
             colorNormalization: "spatial-white-balanced"
-          }, normalizedGrid);
+          };
+          geometryDecoded = tryAttempt(spatialAttempt, normalizedGrid, {}, false);
+          if (!geometryDecoded && options.softDecoding !== false) {
+            geometryDecoded = tryAttempt(spatialAttempt, normalizedGrid, {}, true);
+          }
         } catch {
           // Continue to the recovery profile below.
         }
       }
 
-      // Very cheap Photoshop-like recovery on the already-sampled module grid.
-      // Normal camera frames never reach this path. The transform approximates
-      // Auto Color + Auto Tone + Auto Contrast and costs only O(moduleCount).
+      // Lightweight QuadQR color recovery on the already-sampled module grid.
+      // Normal camera frames never reach this path. The transform combines
+      // QuadQR Auto Color + Auto Tone + Auto Contrast and costs only O(moduleCount).
       if (!geometryDecoded && options.autoEnhanceRecovery !== false) {
         try {
           const enhancedGrid = autoToneContrastColorRgbGrid(sampled.rgbGrid, {
@@ -3347,26 +3972,38 @@ function tryPerspectiveScan(imageData, options) {
             saturation: options.autoEnhanceSaturation
           });
           const enhancedPalette = sampleObservedPalette(enhancedGrid, layout.calibration, { robust: true });
-          for (const attempt of paletteClassifierAttempts(enhancedPalette)) {
-            const recoveredAttempt = {
-              ...attempt,
-              colorNormalization: `auto-tone-contrast-color/${attempt.colorNormalization}`
-            };
+          const enhancedAttempts = paletteClassifierAttempts(enhancedPalette).map((attempt) => ({
+            ...attempt,
+            colorNormalization: `auto-tone-contrast-color/${attempt.colorNormalization}`
+          }));
+          for (const recoveredAttempt of enhancedAttempts) {
             if (tryAttempt(recoveredAttempt, enhancedGrid, {
               observedPalette: enhancedPalette,
               autoEnhanced: true,
               recoveryMode: "module-grid-auto-tone-contrast-color"
-            })) {
+            }, false)) {
               geometryDecoded = true;
               break;
             }
           }
+          if (!geometryDecoded && options.softDecoding !== false) {
+            for (const recoveredAttempt of enhancedAttempts) {
+              if (tryAttempt(recoveredAttempt, enhancedGrid, {
+                observedPalette: enhancedPalette,
+                autoEnhanced: true,
+                recoveryMode: "module-grid-auto-tone-contrast-color"
+              }, true)) {
+                geometryDecoded = true;
+                break;
+              }
+            }
+          }
         } catch {
           // Continue to the QR-region pixel recovery below.
         }
       }
 
-      // Camera-specific Photoshop-style fallback. Enhancing the whole camera
+      // Camera-specific QuadQR color-recovery fallback. Enhancing the whole camera
       // frame is often ineffective because dark surroundings, browser/UI
       // reflections and unrelated objects skew the histograms. Once finder
       // geometry is known, rectify only the QuadQR region, run Auto Tone /
@@ -3405,21 +4042,34 @@ function tryPerspectiveScan(imageData, options) {
             layout.calibration,
             { robust: true }
           );
-          for (const attempt of paletteClassifierAttempts(enhancedPalette)) {
-            const recoveredAttempt = {
-              ...attempt,
-              colorNormalization: `rectified-auto-tone-contrast-color/${attempt.colorNormalization}`
-            };
+          const rectifiedAttempts = paletteClassifierAttempts(enhancedPalette).map((attempt) => ({
+            ...attempt,
+            colorNormalization: `rectified-auto-tone-contrast-color/${attempt.colorNormalization}`
+          }));
+          for (const recoveredAttempt of rectifiedAttempts) {
             if (tryAttempt(recoveredAttempt, enhancedSampled.rgbGrid, {
               observedPalette: enhancedPalette,
               samplingMode: "rectified-auto-enhance",
               autoEnhanced: true,
               recoveryMode: "rectified-auto-tone-contrast-color"
-            })) {
+            }, false)) {
               geometryDecoded = true;
               break;
             }
           }
+          if (!geometryDecoded && options.softDecoding !== false) {
+            for (const recoveredAttempt of rectifiedAttempts) {
+              if (tryAttempt(recoveredAttempt, enhancedSampled.rgbGrid, {
+                observedPalette: enhancedPalette,
+                samplingMode: "rectified-auto-enhance",
+                autoEnhanced: true,
+                recoveryMode: "rectified-auto-tone-contrast-color"
+              }, true)) {
+                geometryDecoded = true;
+                break;
+              }
+            }
+          }
         } catch {
           // Geometry refinement remains available as the final bounded fallback.
         }
@@ -3428,6 +4078,15 @@ function tryPerspectiveScan(imageData, options) {
       if (geometryDecoded) break;
     }
 
+    // A decoded QuadQR has already passed structural validation, Spectrum ECC,
+    // and the payload CRC. Continuing through every lower-ranked geometry after
+    // that point used to spend most of the camera scan time proving the same
+    // frame again. Return the first authenticated decode immediately. An opt-in
+    // diagnostic mode can still collect every successful geometry if needed.
+    if (geometryDecoded && options.collectAllGeometryResults !== true) {
+      return results[results.length - 1] ?? null;
+    }
+
     // Slow-path geometry micro-refinement. Finder/alignment detection can be
     // correct while a soft-focus or smeared camera shifts the effective module
     // centres by a small fraction of a cell. Clean scans never reach this code.
@@ -3485,6 +4144,7 @@ function tryPerspectiveScan(imageData, options) {
             version: geometry.version,
             matrix: classified.matrix,
             confidence: classified.confidence,
+            alternatives: classified.alternatives,
             geometry,
             observedPalette,
             samplingMode: "refined-center",
@@ -3523,6 +4183,7 @@ function tryPerspectiveScan(imageData, options) {
               version: geometry.version,
               matrix: triangleClassified.matrix,
               confidence: triangleClassified.confidence,
+              alternatives: triangleClassified.alternatives,
               geometry,
               observedPalette,
               samplingMode: "refined-triangle16",
@@ -3570,7 +4231,9 @@ function tryPerspectiveScan(imageData, options) {
           const decoded = decodeMatrix(candidate.classified.matrix, {
             structureTolerance: options.structureTolerance ?? 0.18,
             cellConfidence: candidate.classified.confidence,
+            cellAlternatives: candidate.classified.alternatives,
             cellEncodingHint: candidate.cellEncoding,
+            alignmentProfileHint: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
             maxErasureConfidence: options.maxErasureConfidence
           });
           if (decoded.version !== geometry.version) continue;
@@ -3599,6 +4262,11 @@ function tryPerspectiveScan(imageData, options) {
         }
       }
     }
+
+
+    if (geometryDecoded && options.collectAllGeometryResults !== true) {
+      return results[results.length - 1] ?? null;
+    }
   }
 
   results.sort((a, b) =>
@@ -3707,6 +4375,7 @@ function tryAxisAlignedScan(imageData, options) {
                 version,
                 matrix: classified.matrix,
                 confidence: classified.confidence,
+                alternatives: classified.alternatives,
                 bounds,
                 samplingMode: classifiedAttempt.samplingMode,
                 colorNormalization: attempt.colorNormalization,
@@ -3718,6 +4387,7 @@ function tryAxisAlignedScan(imageData, options) {
               const decoded = decodeMatrix(classified.matrix, {
                 structureTolerance: options.structureTolerance ?? 0.12,
                 cellConfidence: classified.confidence,
+                cellAlternatives: classified.alternatives,
                 cellEncodingHint: classifiedAttempt.cellEncoding,
                 maxErasureConfidence: options.maxErasureConfidence
               });
@@ -3770,6 +4440,31 @@ export const STRESS_PROFILES = Object.freeze([
   Object.freeze({ id: "downscale", label: "Downscale", type: "downscale", severity: 0.52, weight: 0.9 })
 ]);
 
+
+export const RELIABILITY_PROFILES = Object.freeze([
+  Object.freeze({ id: "clean", label: "Clean reference", category: "Baseline", type: "clean", severity: 0, weight: 2, suite: "quick" }),
+  Object.freeze({ id: "blur", label: "Lens blur", category: "Optics", type: "blur", severity: 0.40, weight: 1, suite: "quick" }),
+  Object.freeze({ id: "motion", label: "Motion blur", category: "Optics", type: "motion-blur", severity: 0.42, weight: 1, suite: "full" }),
+  Object.freeze({ id: "dark", label: "Low light", category: "Exposure", type: "brightness-low", severity: 0.50, weight: 1, suite: "quick" }),
+  Object.freeze({ id: "bright", label: "High exposure", category: "Exposure", type: "brightness-high", severity: 0.38, weight: 1, suite: "full" }),
+  Object.freeze({ id: "shadow", label: "Gradient shadow", category: "Lighting", type: "shadow", severity: 0.58, weight: 1.2, suite: "quick" }),
+  Object.freeze({ id: "glare", label: "Specular glare", category: "Lighting", type: "glare", severity: 0.34, weight: 1.1, suite: "full" }),
+  Object.freeze({ id: "warm", label: "Warm color cast", category: "Color", type: "warm", severity: 0.62, weight: 1, suite: "quick" }),
+  Object.freeze({ id: "cool", label: "Cool color cast", category: "Color", type: "cool", severity: 0.60, weight: 1, suite: "full" }),
+  Object.freeze({ id: "contrast", label: "Contrast loss", category: "Color", type: "contrast-loss", severity: 0.46, weight: 1, suite: "full" }),
+  Object.freeze({ id: "noise", label: "Sensor noise", category: "Sensor", type: "noise", severity: 0.42, weight: 0.9, suite: "full" }),
+  Object.freeze({ id: "jpeg", label: "JPEG-like damage", category: "Resampling", type: "jpeg", severity: 0.52, weight: 0.8, suite: "full" }),
+  Object.freeze({ id: "downscale", label: "Aggressive downscale", category: "Resampling", type: "downscale", severity: 0.55, weight: 1, suite: "quick" }),
+  Object.freeze({ id: "perspective-2d", label: "Projective skew", category: "Perspective", type: "perspective", severity: 0.52, weight: 1.3, suite: "quick" }),
+  Object.freeze({ id: "yaw-35", label: "3D yaw 35°", category: "Perspective", type: "perspective-3d", severity: 0.55, yawDegrees: 35, pitchDegrees: 0, rollDegrees: 0, weight: 1.4, suite: "quick" }),
+  Object.freeze({ id: "pitch-30", label: "3D pitch 30°", category: "Perspective", type: "perspective-3d", severity: 0.50, yawDegrees: 0, pitchDegrees: 30, rollDegrees: 0, weight: 1.3, suite: "full" }),
+  Object.freeze({ id: "z-rotation-55", label: "Z rotation 55°", category: "Perspective", type: "perspective-3d", severity: 0.45, yawDegrees: 0, pitchDegrees: 0, rollDegrees: 55, weight: 1.1, suite: "quick" }),
+  Object.freeze({ id: "combined-3d", label: "Combined 3D tilt", category: "Perspective", type: "perspective-3d", severity: 0.62, yawDegrees: 30, pitchDegrees: 15, rollDegrees: 18, weight: 1.5, suite: "full" }),
+  Object.freeze({ id: "yaw-55", label: "Extreme yaw 55°", category: "Extreme perspective", type: "perspective-3d", severity: 0.82, yawDegrees: 55, pitchDegrees: 0, rollDegrees: 0, weight: 1.5, suite: "extreme" }),
+  Object.freeze({ id: "pitch-40", label: "Extreme pitch 40°", category: "Extreme perspective", type: "perspective-3d", severity: 0.78, yawDegrees: 0, pitchDegrees: 40, rollDegrees: 0, weight: 1.4, suite: "extreme" }),
+  Object.freeze({ id: "z-rotation-75", label: "Z rotation 75°", category: "Extreme perspective", type: "perspective-3d", severity: 0.72, yawDegrees: 0, pitchDegrees: 0, rollDegrees: 75, weight: 1.1, suite: "extreme" })
+]);
+
 function cloneImageDataLike(imageData) {
   return { width: imageData.width, height: imageData.height, data: new Uint8ClampedArray(imageData.data) };
 }
@@ -3869,13 +4564,151 @@ function perspectiveStress(imageData, severity) {
   return { width, height, data: out };
 }
 
+
+function fillWhiteRgba(data) {
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = 255;
+    data[i + 1] = 255;
+    data[i + 2] = 255;
+    data[i + 3] = 255;
+  }
+}
+
+function projectPlaneQuad(width, height, options = {}) {
+  const pitch = Number(options.pitchDegrees ?? options.pitch ?? 0) * Math.PI / 180;
+  const yaw = Number(options.yawDegrees ?? options.yaw ?? 0) * Math.PI / 180;
+  const roll = Number(options.rollDegrees ?? options.roll ?? 0) * Math.PI / 180;
+  const cameraDistance = Math.max(1.8, Number(options.cameraDistance ?? 3.0));
+  const fill = clampNumber(Number(options.fill ?? 0.84), 0.45, 0.94);
+  const aspect = width / Math.max(1, height);
+  // Point order intentionally follows TL, TR, BL, BR to match the
+  // destination->source homography convention used throughout the scanner.
+  const corners = [
+    { x: -aspect, y: -1, z: 0 },
+    { x: aspect, y: -1, z: 0 },
+    { x: -aspect, y: 1, z: 0 },
+    { x: aspect, y: 1, z: 0 }
+  ];
+  const cp = Math.cos(pitch), sp = Math.sin(pitch);
+  const cy = Math.cos(yaw), sy = Math.sin(yaw);
+  const cr = Math.cos(roll), sr = Math.sin(roll);
+  const projected = corners.map((point) => {
+    // Yaw around Y.
+    const x1 = point.x * cy + point.z * sy;
+    const z1 = -point.x * sy + point.z * cy;
+    const y1 = point.y;
+    // Pitch around X.
+    const y2 = y1 * cp - z1 * sp;
+    const z2 = y1 * sp + z1 * cp;
+    const x2 = x1;
+    // Roll around Z, i.e. in-plane camera/code rotation.
+    const x3 = x2 * cr - y2 * sr;
+    const y3 = x2 * sr + y2 * cr;
+    const depth = Math.max(0.35, cameraDistance + z2);
+    const perspective = cameraDistance / depth;
+    return { x: x3 * perspective, y: y3 * perspective };
+  });
+  const minX = Math.min(...projected.map((point) => point.x));
+  const maxX = Math.max(...projected.map((point) => point.x));
+  const minY = Math.min(...projected.map((point) => point.y));
+  const maxY = Math.max(...projected.map((point) => point.y));
+  const projectedWidth = Math.max(0.001, maxX - minX);
+  const projectedHeight = Math.max(0.001, maxY - minY);
+  const scale = Math.min(width * fill / projectedWidth, height * fill / projectedHeight);
+  const centerX = (minX + maxX) / 2;
+  const centerY = (minY + maxY) / 2;
+  return projected.map((point) => ({
+    x: width / 2 + (point.x - centerX) * scale,
+    y: height / 2 + (point.y - centerY) * scale
+  }));
+}
+
+function warpToQuad(imageData, destination) {
+  const { width, height } = imageData;
+  const source = [
+    { x: 0, y: 0 },
+    { x: width - 1, y: 0 },
+    { x: 0, y: height - 1 },
+    { x: width - 1, y: height - 1 }
+  ];
+  const inverse = computeHomography(source, destination);
+  const out = new Uint8ClampedArray(width * height * 4);
+  fillWhiteRgba(out);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const src = projectPoint(inverse, x, y);
+      if (src.x < 0 || src.y < 0 || src.x >= width || src.y >= height) continue;
+      const rgba = sampleRgbaBilinear(imageData, src.x, src.y);
+      const p = (y * width + x) * 4;
+      out[p] = rgba[0];
+      out[p + 1] = rgba[1];
+      out[p + 2] = rgba[2];
+      out[p + 3] = 255;
+    }
+  }
+  return { width, height, data: out };
+}
+
+function perspective3dStress(imageData, severity, options = {}) {
+  const s = clampNumber(Number(severity), 0, 1);
+  const destination = projectPlaneQuad(imageData.width, imageData.height, {
+    pitchDegrees: options.pitchDegrees ?? (8 + s * 28),
+    yawDegrees: options.yawDegrees ?? (12 + s * 43),
+    rollDegrees: options.rollDegrees ?? (s * 18),
+    cameraDistance: options.cameraDistance ?? 3,
+    fill: options.fill ?? (0.88 - s * 0.06)
+  });
+  return warpToQuad(imageData, destination);
+}
+
+function motionBlurImage(imageData, severity, options = {}) {
+  const radius = Math.max(1, Math.round(Number(options.radius ?? (2 + severity * 5))));
+  const slope = Number(options.slope ?? 0.35);
+  const { width, height } = imageData;
+  const out = new Uint8ClampedArray(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const p = (y * width + x) * 4;
+      for (let ch = 0; ch < 3; ch++) {
+        let sum = 0;
+        let count = 0;
+        for (let k = -radius; k <= radius; k++) {
+          const sx = x + k;
+          const sy = y + Math.round(k * slope);
+          if (sx < 0 || sy < 0 || sx >= width || sy >= height) continue;
+          sum += imageData.data[(sy * width + sx) * 4 + ch];
+          count++;
+        }
+        out[p + ch] = count ? sum / count : imageData.data[p + ch];
+      }
+      out[p + 3] = 255;
+    }
+  }
+  return { width, height, data: out };
+}
+
+function deterministicNoise(x, y, channel) {
+  let value = Math.imul((x + 1) ^ (channel * 374761393), 668265263) ^ Math.imul(y + 11, 2246822519);
+  value = Math.imul(value ^ (value >>> 13), 1274126177);
+  return ((value ^ (value >>> 16)) >>> 0) / 0xffffffff * 2 - 1;
+}
+
 /** Apply one deterministic camera/print-style distortion to ImageData. */
 export function applyStressDistortion(imageData, type, severity = 0.5, options = {}) {
   assert(imageData?.data && imageData.width && imageData.height, "applyStressDistortion requires ImageData-like input.");
   const s = clampNumber(Number(severity), 0, 1);
   if (type === "clean") return cloneImageDataLike(imageData);
   if (type === "blur") return boxBlurImage(imageData, 1 + s * 2.2);
+  if (type === "motion-blur") return motionBlurImage(imageData, s, options);
   if (type === "perspective") return perspectiveStress(imageData, s);
+  if (type === "perspective-3d" || type === "rotate-z") {
+    return perspective3dStress(imageData, s, {
+      ...options,
+      pitchDegrees: type === "rotate-z" ? 0 : options.pitchDegrees,
+      yawDegrees: type === "rotate-z" ? 0 : options.yawDegrees,
+      rollDegrees: type === "rotate-z" ? (options.rollDegrees ?? 20 + s * 70) : options.rollDegrees
+    });
+  }
   if (type === "downscale") {
     const scale = Math.max(0.20, 1 - s * 0.72);
     const small = resizeImageDataLike(imageData, imageData.width * scale, imageData.height * scale);
@@ -3904,7 +4737,22 @@ export function applyStressDistortion(imageData, type, severity = 0.5, options =
           value += block * s * 3;
         } else if (type === "warm") {
           if (ch === 0) value *= 1 + s * 0.12;
+          if (ch === 1) value *= 1 + s * 0.03;
           if (ch === 2) value *= 1 - s * 0.22;
+        } else if (type === "cool") {
+          if (ch === 0) value *= 1 - s * 0.20;
+          if (ch === 1) value *= 1 + s * 0.02;
+          if (ch === 2) value *= 1 + s * 0.14;
+        } else if (type === "noise") {
+          value += deterministicNoise(x, y, ch) * (5 + s * 34);
+        } else if (type === "glare") {
+          const nx = (x / Math.max(1, width - 1) - 0.68) / 0.28;
+          const ny = (y / Math.max(1, height - 1) - 0.30) / 0.20;
+          const falloff = Math.exp(-(nx * nx + ny * ny) * 2.2);
+          value += (255 - value) * falloff * s * 0.82;
+        } else if (type === "gamma") {
+          const gamma = 1 + (s - 0.5) * 1.2;
+          value = 255 * Math.pow(value / 255, gamma);
         }
         data[p + ch] = clampNumber(Math.round(value), 0, 255);
       }
@@ -3974,16 +4822,122 @@ export function runImageStressTest(imageData, expected = {}, options = {}) {
   };
 }
 
-/** Render and run the standard scanability torture suite. */
-export function assessScanability(code, renderOptions = {}, options = {}) {
-  assert(code?.matrix, "assessScanability expects an encoded QuadQR object.");
-  const testImageSize = Math.max(240, Math.min(Number(options.testImageSize ?? 480), Number(renderOptions.imageSize ?? 720)));
-  const image = renderToImageData(code, { ...renderOptions, imageSize: testImageSize });
-  const report = runImageStressTest(image, { version: code.version, crc32: code.crc32 }, options);
-  const autoLogoSize = renderOptions.logo ? estimateSafeLogoSize(code, renderOptions) : null;
+
+function reliabilityProfilesForSuite(suite = "full") {
+  const rank = { quick: 0, full: 1, extreme: 2 };
+  const requested = rank[suite] ?? rank.full;
+  return RELIABILITY_PROFILES.filter((profile) => (rank[profile.suite] ?? 1) <= requested);
+}
+
+/** Run the broader Reliability Lab suite and return category-level scores. */
+export function runReliabilityLab(imageData, expected = {}, options = {}) {
+  const suite = options.suite ?? "full";
+  const profiles = options.profiles ?? reliabilityProfilesForSuite(suite);
+  const report = runImageStressTest(imageData, expected, { ...options, profiles });
+  const categoryMap = new Map();
+  for (const result of report.results) {
+    const profile = profiles.find((item) => item.id === result.id) ?? {};
+    const category = profile.category ?? "Other";
+    const weight = Number(profile.weight ?? 1);
+    if (!categoryMap.has(category)) categoryMap.set(category, { category, passedWeight: 0, totalWeight: 0, passed: 0, total: 0 });
+    const entry = categoryMap.get(category);
+    entry.totalWeight += weight;
+    entry.total++;
+    if (result.passed) {
+      entry.passedWeight += weight;
+      entry.passed++;
+    }
+    result.category = category;
+    result.pitchDegrees = profile.pitchDegrees ?? null;
+    result.yawDegrees = profile.yawDegrees ?? null;
+    result.rollDegrees = profile.rollDegrees ?? null;
+  }
+  const categories = [...categoryMap.values()].map((entry) => ({
+    category: entry.category,
+    passed: entry.passed,
+    total: entry.total,
+    score: entry.totalWeight ? entry.passedWeight / entry.totalWeight * 100 : 0
+  })).sort((a, b) => a.score - b.score || a.category.localeCompare(b.category));
   return {
     ...report,
-    version: code.version,
+    suite,
+    categories,
+    weakestCategory: categories[0] ?? null
+  };
+}
+
+/** Sweep one 3D perspective axis to measure the largest passing angle. */
+export function runPerspectiveSweep(imageData, expected = {}, options = {}) {
+  const axis = options.axis ?? "yaw";
+  const defaultAngles = axis === "roll"
+    ? [0, 25, 45, 60, 75]
+    : [0, 15, 25, 35, 45, 55];
+  const angles = (options.angles ?? defaultAngles).map(Number).filter(Number.isFinite);
+  const results = [];
+  let maxPassedAngle = null;
+  for (const angle of angles) {
+    const transform = {
+      pitchDegrees: Number(options.pitchDegrees ?? 0),
+      yawDegrees: Number(options.yawDegrees ?? 0),
+      rollDegrees: Number(options.rollDegrees ?? 0),
+      fill: options.fill ?? 0.84,
+      cameraDistance: options.cameraDistance ?? 3
+    };
+    if (axis === "pitch") transform.pitchDegrees = angle;
+    else if (axis === "roll" || axis === "z") transform.rollDegrees = angle;
+    else transform.yawDegrees = angle;
+    const distorted = applyStressDistortion(imageData, "perspective-3d", 0.5, transform);
+    const started = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+    try {
+      const decoded = scanImageData(distorted, {
+        minVersion: expected.version ?? options.minVersion ?? MIN_VERSION,
+        maxVersion: expected.version ?? options.maxVersion ?? MAX_VERSION,
+        debug: false
+      });
+      const passed = expected.crc32 == null || decoded.crc32 === expected.crc32;
+      if (passed) maxPassedAngle = Math.max(maxPassedAngle ?? angle, angle);
+      results.push({
+        angle,
+        axis,
+        passed,
+        confidence: decoded.confidence ?? decoded.diagnostics?.confidence ?? null,
+        correctedSymbols: decoded.correctedSymbols ?? 0,
+        elapsedMs: (typeof performance !== "undefined" && performance.now ? performance.now() : Date.now()) - started,
+        image: options.includeImages ? distorted : undefined,
+        error: passed ? null : "Decoded payload did not match expected CRC."
+      });
+    } catch (error) {
+      results.push({
+        angle,
+        axis,
+        passed: false,
+        confidence: 0,
+        correctedSymbols: null,
+        elapsedMs: (typeof performance !== "undefined" && performance.now ? performance.now() : Date.now()) - started,
+        image: options.includeImages ? distorted : undefined,
+        error: error.message
+      });
+    }
+  }
+  return {
+    axis,
+    maxPassedAngle,
+    passed: results.filter((item) => item.passed).length,
+    total: results.length,
+    results
+  };
+}
+
+/** Render and run the standard scanability torture suite. */
+export function assessScanability(code, renderOptions = {}, options = {}) {
+  assert(code?.matrix, "assessScanability expects an encoded QuadQR object.");
+  const testImageSize = Math.max(240, Math.min(Number(options.testImageSize ?? 480), Number(renderOptions.imageSize ?? 720)));
+  const image = renderToImageData(code, { ...renderOptions, imageSize: testImageSize });
+  const report = runImageStressTest(image, { version: code.version, crc32: code.crc32 }, options);
+  const autoLogoSize = renderOptions.logo ? estimateSafeLogoSize(code, renderOptions) : null;
+  return {
+    ...report,
+    version: code.version,
     eccLevel: code.eccLevel,
     utilization: code.utilization,
     testImageSize,
@@ -4135,6 +5089,38 @@ export function scanImageData(imageData, options = {}) {
   };
 
   if (options.perspective !== false) {
+    const geometryHints = Array.isArray(options._geometryHints)
+      ? options._geometryHints.filter((item) => item?.homography && Number.isInteger(item.version)).slice(0, 2)
+      : [];
+    if (geometryHints.length) {
+      try {
+        const hinted = tryPerspectiveScan(imageData, {
+          ...scanOptions,
+          _diagnosticLabel: options._diagnosticLabel ? `${options._diagnosticLabel}-geometry-reuse` : "geometry-reuse",
+          _geometryCandidatesOverride: geometryHints,
+          _geometryCollector: [],
+          _observationCollector: [],
+          adaptiveSampling: options._geometryReuseAdaptiveSampling ?? false,
+          geometryRefinement: false
+        });
+        if (hinted) {
+          geometryCollector.push(hinted.geometry ?? geometryHints[0]);
+          return decorateScanResult({
+            ...hinted,
+            geometryReused: true,
+            recoveryMode: hinted.recoveryMode ?? "geometry-reuse"
+          }, debugContext, options);
+        }
+      } catch {
+        // A stale geometry hint is expected when the camera/code moves. The
+        // camera worker can request a hint-only attempt when it is reusing
+        // low-resolution locator geometry on a higher-detail frame.
+      }
+      if (options._geometryHintOnly === true) {
+        throw new Error("Geometry hint did not decode this frame.");
+      }
+    }
+
     const perspective = tryPerspectiveScan(imageData, scanOptions);
     if (perspective) return decorateScanResult(perspective, debugContext, options);
   }
@@ -4460,6 +5446,21 @@ export function scanVideoFrame(video, options = {}) {
       _visionDiagnostics: visionDiagnostics
     });
     normalizeFrameDiagnostics(options._frameDiagnostics, source, width, height, visionDiagnostics);
+    if (options._frameDiagnostics && result?.geometry && !options._frameDiagnostics.geometry) {
+      const geometry = result.geometry;
+      options._frameDiagnostics.geometry = geometry;
+      options._frameDiagnostics.geometryReused = Boolean(result.geometryReused);
+      if (geometry.finders) {
+        const reusedFinders = [
+          geometry.finders.topLeft,
+          geometry.finders.topRight,
+          geometry.finders.bottomLeft
+        ].filter(Boolean);
+        options._frameDiagnostics.finders = reusedFinders;
+        options._frameDiagnostics.finderCount = reusedFinders.length;
+        if (result.geometryReused) options._frameDiagnostics.finderMethod = "geometry-reuse";
+      }
+    }
     if (!source.cropped) return result;
     return {
       ...result,
@@ -4483,47 +5484,111 @@ function selectBestFrameObservation(observations) {
     )[0] ?? null;
 }
 
+function observationDataAgreement(a, b) {
+  if (!a?.matrix || !b?.matrix || a.version !== b.version || a.matrix.length !== b.matrix.length) return 0;
+  if ((a.cellEncoding ?? null) !== (b.cellEncoding ?? null)) return 0;
+  const layout = createLayout(a.version);
+  let agreed = 0;
+  let compared = 0;
+  for (const [row, col] of layout.dataPositions) {
+    const ca = a.confidence?.[row]?.[col] ?? 0;
+    const cb = b.confidence?.[row]?.[col] ?? 0;
+    if (Math.min(ca, cb) < 0.48) continue;
+    compared++;
+    if (a.matrix[row][col] === b.matrix[row][col]) agreed++;
+  }
+  return compared ? agreed / compared : 0;
+}
+
 function combineFrameObservations(observations) {
   if (!observations?.length) return null;
   const version = observations[0].version;
+  const cellEncoding = observations[0].cellEncoding ?? null;
   const size = observations[0].matrix.length;
-  if (!observations.every((item) => item.version === version && item.matrix.length === size)) return null;
+  if (!observations.every((item) =>
+    item.version === version &&
+    (item.cellEncoding ?? null) === cellEncoding &&
+    item.matrix.length === size
+  )) return null;
 
   const matrix = make2D(size, CELL.WHITE);
   const confidence = make2D(size, 0);
+  const alternatives = make2D(size, null);
+  const frameCount = observations.length;
+  const latest = observations[frameCount - 1];
+  let agreementSum = 0;
+  let agreementCount = 0;
+  for (let i = 0; i < frameCount - 1; i++) {
+    const agreement = observationDataAgreement(observations[i], latest);
+    if (agreement > 0) {
+      agreementSum += agreement;
+      agreementCount++;
+    }
+  }
+
   for (let r = 0; r < size; r++) {
     for (let c = 0; c < size; c++) {
       const votes = new Map();
       const confidenceByCell = new Map();
-      for (const observation of observations) {
+      for (let index = 0; index < observations.length; index++) {
+        const observation = observations[index];
         const cell = observation.matrix[r][c];
         const sourceConfidence = clampNumber(observation.confidence?.[r]?.[c] ?? 0.5, 0, 1);
-        const weight = 0.35 + sourceConfidence * 0.65;
+        const age = observations.length - 1 - index;
+        const recency = Math.pow(0.88, age);
+        const frameQuality = clampNumber(
+          0.45 +
+          (observation.structureScore ?? 0.82) * 0.30 +
+          (observation.averageCellConfidence ?? 0.5) * 0.25,
+          0.45,
+          1
+        );
+        const weight = (0.25 + sourceConfidence * 0.75) * recency * frameQuality;
         votes.set(cell, (votes.get(cell) ?? 0) + weight);
         const stats = confidenceByCell.get(cell) ?? { weighted: 0, weight: 0 };
         stats.weighted += sourceConfidence * weight;
         stats.weight += weight;
         confidenceByCell.set(cell, stats);
+
+        // The per-frame second hypothesis also contributes weak evidence. It
+        // never outranks a strong primary vote by itself, but it preserves a
+        // plausible alternative for Spectrum ECC 2.0 when several frames are
+        // individually ambiguous in the same region.
+        const alternative = observation.alternatives?.[r]?.[c];
+        if (Number.isInteger(alternative) && alternative !== cell) {
+          const altWeight = weight * (1 - sourceConfidence) * 0.42;
+          votes.set(alternative, (votes.get(alternative) ?? 0) + altWeight);
+        }
       }
 
       const ranked = Array.from(votes.entries()).sort((a, b) => b[1] - a[1]);
       const [bestCell, bestWeight] = ranked[0];
-      const secondWeight = ranked[1]?.[1] ?? 0;
+      const [secondCell, secondWeight] = ranked[1] ?? [null, 0];
       const totalWeight = ranked.reduce((sum, item) => sum + item[1], 0);
       const sourceStats = confidenceByCell.get(bestCell);
       const sourceConfidence = sourceStats?.weight ? sourceStats.weighted / sourceStats.weight : 0.5;
       const support = totalWeight ? bestWeight / totalWeight : 0;
       const margin = totalWeight ? (bestWeight - secondWeight) / totalWeight : 0;
-      const agreement = 0.5 * support + 0.5 * margin;
+      const temporalBoost = clampNumber((frameCount - 1) / 5, 0, 0.18);
+      const fusedConfidence = clampNumber(
+        sourceConfidence * 0.50 + support * 0.30 + margin * 0.20 + temporalBoost,
+        0,
+        1
+      );
 
       matrix[r][c] = bestCell;
-      // Do not become overconfident just because several blurry frames agree.
-      // Retaining source uncertainty lets Reed-Solomon treat repeated ambiguous
-      // cells as erasures instead of hard, supposedly-certain errors.
-      confidence[r][c] = clampNumber(sourceConfidence * 0.58 + agreement * 0.42, 0, 1);
+      confidence[r][c] = fusedConfidence;
+      alternatives[r][c] = Number.isInteger(secondCell) && secondCell !== bestCell ? secondCell : null;
     }
   }
-  return { version, matrix, confidence };
+  return {
+    version,
+    cellEncoding,
+    matrix,
+    confidence,
+    alternatives,
+    frameAgreement: agreementCount ? agreementSum / agreementCount : 1
+  };
 }
 
 async function improveCameraTrack(stream) {
@@ -4548,7 +5613,7 @@ async function improveCameraTrack(stream) {
   }
 }
 
-export async function startCameraScanner(video, options = {}) {
+async function startCameraScannerMainThread(video, options = {}) {
   assert(typeof navigator !== "undefined" && navigator.mediaDevices?.getUserMedia, "Camera API is unavailable.");
   assert(video, "A video element is required.");
 
@@ -4557,8 +5622,8 @@ export async function startCameraScanner(video, options = {}) {
       audio: false,
       video: {
         facingMode: { ideal: "environment" },
-        width: { ideal: 1920 },
-        height: { ideal: 1080 },
+        width: { ideal: 1280 },
+        height: { ideal: 720 },
         frameRate: { ideal: 30 }
       }
     }
@@ -4570,7 +5635,11 @@ export async function startCameraScanner(video, options = {}) {
   video.muted = true;
   await video.play();
 
-  const scanInterval = Math.max(80, options.scanInterval ?? 180);
+  // Keep scanning responsive without queueing stale camera frames. The old
+  // 180 ms post-scan timeout made effective cadence equal scan time + 180 ms.
+  // The scheduler below measures from scan start and uses real video frames
+  // when requestVideoFrameCallback() is available.
+  const scanInterval = Math.max(24, Number(options.scanInterval ?? 80));
   const scratchCanvas = document.createElement("canvas");
   const highResolutionCanvas = document.createElement("canvas");
   const multiFrameEnabled = options.multiFrame !== false;
@@ -4581,16 +5650,23 @@ export async function startCameraScanner(video, options = {}) {
   const cameraAutoEnhanceEvery = Math.max(1, Math.round(options.cameraAutoEnhanceEvery ?? 2));
   const cameraFinderRecoveryEvery = Math.max(1, Math.round(options.cameraFinderRecoveryEvery ?? 2));
   const cameraHighResolutionEvery = Math.max(1, Math.round(options.cameraHighResolutionEvery ?? 2));
-  const baseCameraMaxDimension = Math.max(480, Math.round(options.maxDimension ?? 1080));
+  const baseCameraMaxDimension = Math.max(480, Math.round(options.maxDimension ?? 640));
   const cameraHighResolutionMaxDimension = Math.max(
     baseCameraMaxDimension,
-    Math.round(options.cameraHighResolutionMaxDimension ?? 1600)
+    Math.round(options.cameraHighResolutionMaxDimension ?? 960)
   );
   let missStreak = 0;
   let stopped = false;
   let busy = false;
   let timer = null;
+  let frameCallbackId = null;
+  let lastScanStartedAt = -Infinity;
   let frameNumber = 0;
+  let cameraGeometryHint = null;
+  let cameraGeometryHintMisses = 0;
+  const cameraGeometryReuseMaxMisses = Math.max(1, Math.round(options.cameraGeometryReuseMaxMisses ?? 5));
+  const useVideoFrameCallback = options.useVideoFrameCallback !== false &&
+    typeof video.requestVideoFrameCallback === "function";
 
   const diagnosticsEnabled = typeof options.onDiagnostic === "function";
   const emitDiagnostic = (event) => {
@@ -4626,6 +5702,12 @@ export async function startCameraScanner(video, options = {}) {
   const stop = () => {
     stopped = true;
     if (timer) clearTimeout(timer);
+    if (frameCallbackId != null && typeof video.cancelVideoFrameCallback === "function") {
+      try { video.cancelVideoFrameCallback(frameCallbackId); } catch {}
+    }
+    timer = null;
+    frameCallbackId = null;
+    cameraGeometryHint = null;
     observationHistory.clear();
     for (const track of stream.getTracks()) track.stop();
     if (video.srcObject === stream) video.srcObject = null;
@@ -4634,9 +5716,30 @@ export async function startCameraScanner(video, options = {}) {
   const scanNow = () => scanVideoFrame(video, {
     ...options,
     maxDimension: baseCameraMaxDimension,
-    canvas: scratchCanvas
+    canvas: scratchCanvas,
+    _geometryHints: options.cameraGeometryReuse === false || !cameraGeometryHint ? undefined : [cameraGeometryHint]
   });
 
+  const updateCameraGeometryHint = (frameDiagnostics, result = null) => {
+    if (options.cameraGeometryReuse === false) {
+      cameraGeometryHint = null;
+      return;
+    }
+    const geometry = result?.geometry ?? frameDiagnostics?.geometry ?? null;
+    if (geometry?.homography && Number.isInteger(geometry.version)) {
+      cameraGeometryHint = geometry;
+      cameraGeometryHintMisses = 0;
+      return;
+    }
+    if (cameraGeometryHint) {
+      cameraGeometryHintMisses++;
+      if (cameraGeometryHintMisses >= cameraGeometryReuseMaxMisses) {
+        cameraGeometryHint = null;
+        cameraGeometryHintMisses = 0;
+      }
+    }
+  };
+
   const emitResult = (result, capturedFrame = null, diagnostic = null) => {
     const frameMeta = capturedFrame?.imageData ? {
       frame: frameNumber,
@@ -4662,10 +5765,25 @@ export async function startCameraScanner(video, options = {}) {
     if (!multiFrameEnabled) return null;
     const best = selectBestFrameObservation(observations);
     if (!best) return null;
-    const history = observationHistory.get(best.version) ?? [];
+    const trackKey = `${best.version}:${best.cellEncoding ?? "auto"}`;
+    let history = observationHistory.get(trackKey) ?? [];
+
+    // Only fuse observations that appear to describe the same payload. Finder
+    // structure alone is not enough because two different QuadQR symbols of the
+    // same version would otherwise contaminate each other's history. High-
+    // confidence data-cell agreement gives us a cheap identity check without
+    // needing the header to decode first.
+    if (history.length) {
+      const agreement = observationDataAgreement(history[history.length - 1], best);
+      const minimumAgreement = best.cellEncoding === CELL_ENCODINGS.TRIANGLE16
+        ? (options.multiFrameMinAgreementHighDensity ?? 0.58)
+        : (options.multiFrameMinAgreement ?? 0.62);
+      if (agreement > 0 && agreement < minimumAgreement) history = [];
+    }
+
     history.push(best);
     while (history.length > multiFrameWindow) history.shift();
-    observationHistory.set(best.version, history);
+    observationHistory.set(trackKey, history);
     if (history.length < multiFrameMinFrames) return null;
 
     const combined = combineFrameObservations(history);
@@ -4674,16 +5792,21 @@ export async function startCameraScanner(video, options = {}) {
       const decoded = decodeMatrix(combined.matrix, {
         structureTolerance: options.structureTolerance ?? 0.20,
         cellConfidence: combined.confidence,
-        maxErasureConfidence: options.maxErasureConfidence
+        cellAlternatives: combined.alternatives,
+        cellEncodingHint: best.cellEncoding ?? undefined,
+        maxErasureConfidence: options.maxErasureConfidence,
+        softDecoding: options.softDecoding
       });
       if (decoded.version !== best.version) return null;
       return {
         ...decoded,
         perspectiveCorrected: Boolean(best.geometry),
         colorCalibrated: true,
-        colorNormalization: "multi-frame-vote",
-        samplingMode: "multi-frame-vote",
+        colorNormalization: "multi-frame-confidence-fusion",
+        samplingMode: "multi-frame-confidence-fusion",
         multiFrameCombined: history.length,
+        multiFrameAgreement: combined.frameAgreement,
+        multiFrameMode: "confidence-fusion",
         geometry: best.geometry,
         observedPalette: best.observedPalette,
         averageCellConfidence: best.averageCellConfidence,
@@ -4694,6 +5817,33 @@ export async function startCameraScanner(video, options = {}) {
     }
   };
 
+  const scheduleNextScan = () => {
+    if (stopped) return;
+    const runWhenDue = () => {
+      frameCallbackId = null;
+      if (stopped) return;
+      const remaining = scanInterval - (nowMs() - lastScanStartedAt);
+      if (remaining > 1) {
+        timer = setTimeout(() => {
+          timer = null;
+          scheduleNextScan();
+        }, remaining);
+        return;
+      }
+      void loop();
+    };
+
+    if (useVideoFrameCallback) {
+      frameCallbackId = video.requestVideoFrameCallback(runWhenDue);
+    } else {
+      const remaining = Math.max(0, scanInterval - (nowMs() - lastScanStartedAt));
+      timer = setTimeout(() => {
+        timer = null;
+        runWhenDue();
+      }, remaining);
+    }
+  };
+
   const loop = async () => {
     if (stopped) return;
     if (!busy && video.readyState >= 2) {
@@ -4703,6 +5853,7 @@ export async function startCameraScanner(video, options = {}) {
       const frameDiagnostics = {};
       const capturedFrame = {};
       const frameStarted = nowMs();
+      lastScanStartedAt = frameStarted;
       let allowAutoEnhance = false;
       let allowFinderRecovery = false;
       try {
@@ -4730,11 +5881,13 @@ export async function startCameraScanner(video, options = {}) {
           fullFrameAutoEnhanceRecovery: options.fullFrameAutoEnhanceRecovery ?? false,
           maxDimension: baseCameraMaxDimension,
           canvas: scratchCanvas,
+          _geometryHints: options.cameraGeometryReuse === false || !cameraGeometryHint ? undefined : [cameraGeometryHint],
           _capturedFrame: capturedFrame,
           _observationCollector: observations,
           _frameDiagnostics: frameDiagnostics
         });
         const elapsedMs = nowMs() - frameStarted;
+        updateCameraGeometryHint(frameDiagnostics, result);
         emitDiagnostic({
           type: "frame",
           state: "decoded",
@@ -4756,6 +5909,7 @@ export async function startCameraScanner(video, options = {}) {
         if (emitResult(result, capturedFrame, frameDiagnostics)) return;
       } catch (error) {
         missStreak++;
+        updateCameraGeometryHint(frameDiagnostics);
         const fastElapsedMs = nowMs() - frameStarted;
         emitDiagnostic({
           type: "frame",
@@ -4771,7 +5925,7 @@ export async function startCameraScanner(video, options = {}) {
 
         // Geometry-aware high-resolution retry. A dense QuadQR can look large
         // enough in the preview while each individual module has become too
-        // small after the normal 1080 px scanner cap. If the fast pass already
+        // small after the normal 640 px scanner cap. If the fast pass already
         // sees at least two convincing finders, spend one bounded retry on a
         // higher-resolution copy of the visible camera ROI. Empty frames and
         // ordinary small codes never pay this cost.
@@ -4834,10 +5988,9 @@ export async function startCameraScanner(video, options = {}) {
           }
         }
 
-        // The user's real phone-camera case is dominated by color cast before
-        // finder detection: Photoshop Auto Color alone makes the same live QR
-        // immediately detectable. Retry the exact captured frame with a cheap
-        // per-channel Auto Color levels correction before any geometry-dependent
+        // Strong color casts can hide finder structure before normal geometry
+        // recovery begins. QuadQR Auto Color retries the exact captured frame with a cheap
+        // per-channel QuadQR Auto Color levels correction before any geometry-dependent
         // recovery. This runs only after the normal fast scan fails, and by
         // default only on every other missed frame after the first one.
         const shouldTryCameraAutoColor = options.cameraAutoColorRecovery !== false &&
@@ -4860,7 +6013,7 @@ export async function startCameraScanner(video, options = {}) {
             type: "method",
             state: "trying",
             method: "camera-auto-color",
-            message: `Fast scan failed · Auto Color recovery inside camera guide (${cropInsets.map((v) => v ? `${Math.round(v * 100)}% crop` : "full frame").join(" → ")})`,
+            message: `Fast scan failed · QuadQR Auto Color recovery inside camera guide (${cropInsets.map((v) => v ? `${Math.round(v * 100)}% crop` : "full frame").join(" → ")})`,
             ...frameDiagnostics
           });
 
@@ -4887,9 +6040,9 @@ export async function startCameraScanner(video, options = {}) {
                 // This is intentionally performed on a centered recovery crop.
                 // A live preview can contain large dark borders, browser UI, a
                 // monitor bezel or room background. Those pixels completely
-                // change global Auto Color/Otsu statistics even though the QR
-                // itself looks identical to a saved crop. Photoshop succeeded
-                // because the user's edited image was effectively QR-centric.
+                // change global QuadQR Auto Color/Otsu statistics even though the QR
+                // itself looks identical to a saved crop. QuadQR recovery stays
+                // QR-centric so surrounding scene pixels do not dominate the correction.
                 blackClip: options.cameraAutoColorBlackClip ?? 0.0001,
                 whiteClip: options.cameraAutoColorWhiteClip ?? 0.004,
                 highlightPercentile: options.cameraAutoColorHighlightPercentile ?? 0.95,
@@ -4935,7 +6088,7 @@ export async function startCameraScanner(video, options = {}) {
                 state: "decoded",
                 method: "camera-auto-color",
                 elapsedMs: recoveryElapsedMs,
-                message: `Auto Color ${cropInset ? `${Math.round(cropInset * 100)}% crop` : "full frame"} decoded v${recovered.version} · ECC ${recovered.eccLevel} · ${Math.round(recoveryElapsedMs)} ms`,
+                message: `QuadQR Auto Color ${cropInset ? `${Math.round(cropInset * 100)}% crop` : "full frame"} decoded v${recovered.version} · ECC ${recovered.eccLevel} · ${Math.round(recoveryElapsedMs)} ms`,
                 ...(autoColorFrameDiagnostics ?? frameDiagnostics)
               });
               capturedFrame.enhancedImageData = correctedFrame;
@@ -4986,7 +6139,7 @@ export async function startCameraScanner(video, options = {}) {
                 type: "method",
                 state: "failed",
                 method: profileName,
-                message: `Auto Color ${cropInset ? `${Math.round(cropInset * 100)}% crop` : "full frame"} did not decode${autoColorFrameDiagnostics?.finderCount != null ? ` · ${autoColorFrameDiagnostics.finderCount} finder(s)` : ""}`,
+                message: `QuadQR Auto Color ${cropInset ? `${Math.round(cropInset * 100)}% crop` : "full frame"} did not decode${autoColorFrameDiagnostics?.finderCount != null ? ` · ${autoColorFrameDiagnostics.finderCount} finder(s)` : ""}`,
                 ...(autoColorFrameDiagnostics ?? frameDiagnostics)
               });
             }
@@ -4996,7 +6149,7 @@ export async function startCameraScanner(video, options = {}) {
               type: "method",
               state: "failed",
               method: "camera-auto-color",
-              message: "All camera Auto Color profiles failed · continuing deeper recovery",
+              message: "All camera QuadQR Auto Color profiles failed · continuing deeper recovery",
               ...frameDiagnostics
             });
           }
@@ -5065,8 +6218,8 @@ export async function startCameraScanner(video, options = {}) {
           emitDiagnostic({
             type: "success",
             state: "decoded",
-            method: "multi-frame-vote",
-            message: `Multi-frame recovery decoded v${combined.version} from ${combined.multiFrameCombined} frames`,
+            method: "multi-frame-confidence-fusion",
+            message: `Multi-frame confidence fusion decoded v${combined.version} from ${combined.multiFrameCombined} frames`,
             ...frameDiagnostics
           });
           missStreak = 0;
@@ -5078,13 +6231,570 @@ export async function startCameraScanner(video, options = {}) {
         busy = false;
       }
     }
-    timer = setTimeout(loop, scanInterval);
+    scheduleNextScan();
   };
 
-  timer = setTimeout(loop, 0);
+  scheduleNextScan();
   return { stream, stop, scanNow, video };
 }
 
+
+function cameraWorkerSupported(options = {}) {
+  if (options.cameraWorker === false) return false;
+  return typeof Worker === "function" &&
+    typeof createImageBitmap === "function" &&
+    typeof OffscreenCanvas === "function";
+}
+
+function serializableCameraWorkerOptions(options = {}) {
+  const skip = new Set([
+    "canvas",
+    "constraints",
+    "onDecode",
+    "onDiagnostic",
+    "onResult",
+    "onScanMiss",
+    "cameraWorkerUrl"
+  ]);
+  const out = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (skip.has(key) || typeof value === "function" || value == null) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+      continue;
+    }
+    if (Array.isArray(value)) {
+      out[key] = value.map((item) => {
+        if (item && typeof item === "object") return { ...item };
+        return item;
+      });
+      continue;
+    }
+    if (Object.getPrototypeOf(value) === Object.prototype) out[key] = { ...value };
+  }
+  return out;
+}
+
+function resolveCameraWorkerUrl(options = {}) {
+  if (options.cameraWorkerUrl) {
+    return new URL(
+      options.cameraWorkerUrl,
+      typeof document !== "undefined" ? document.baseURI : import.meta.url
+    );
+  }
+  return new URL("./camera-scanner-worker.js", import.meta.url);
+}
+
+async function initializeCameraWorker(options = {}) {
+  const worker = new Worker(resolveCameraWorkerUrl(options), {
+    type: "module",
+    name: "quadqr-camera-scanner"
+  });
+  let sequence = 0;
+  const pending = new Map();
+  let fatalError = null;
+
+  const rejectPending = (error) => {
+    fatalError = error instanceof Error ? error : new Error(String(error));
+    for (const { reject } of pending.values()) reject(fatalError);
+    pending.clear();
+  };
+
+  worker.addEventListener("message", (event) => {
+    const message = event.data ?? {};
+    const entry = pending.get(message.id);
+    if (!entry) return;
+    pending.delete(message.id);
+    if (message.ok) entry.resolve(message.result);
+    else {
+      const error = new Error(message.error?.message ?? "QuadQR camera worker failed.");
+      error.name = message.error?.name ?? "Error";
+      error.stack = message.error?.stack ?? error.stack;
+      error.debug = message.error?.debug ?? null;
+      entry.reject(error);
+    }
+  });
+  worker.addEventListener("error", (event) => {
+    rejectPending(new Error(event?.message || "QuadQR camera worker crashed."));
+  });
+  worker.addEventListener("messageerror", () => {
+    rejectPending(new Error("QuadQR camera worker returned an unreadable message."));
+  });
+
+  const request = (type, payload = {}, transfer = []) => {
+    if (fatalError) return Promise.reject(fatalError);
+    const id = `qqr-camera-${++sequence}`;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      try {
+        worker.postMessage({ id, type, ...payload }, transfer);
+      } catch (error) {
+        pending.delete(id);
+        reject(error);
+      }
+    });
+  };
+
+  try {
+    const state = await request("init", { options: serializableCameraWorkerOptions(options) });
+    if (!state?.offscreenCanvas) throw new Error("OffscreenCanvas is unavailable in the QuadQR camera worker.");
+    return {
+      worker,
+      state,
+      request,
+      terminate() {
+        rejectPending(new Error("QuadQR camera worker stopped."));
+        worker.terminate();
+      }
+    };
+  } catch (error) {
+    worker.terminate();
+    throw error;
+  }
+}
+
+async function captureCameraBitmap(video, source, maxDimension) {
+  const cap = Math.max(1, Math.round(maxDimension));
+  const videoWidth = Math.max(1, Math.round(video.videoWidth || source.width || 1));
+  const videoHeight = Math.max(1, Math.round(video.videoHeight || source.height || 1));
+  const sx = clampNumber(Math.round(source.x || 0), 0, Math.max(0, videoWidth - 1));
+  const sy = clampNumber(Math.round(source.y || 0), 0, Math.max(0, videoHeight - 1));
+  const sw = Math.max(1, Math.min(videoWidth - sx, Math.round(source.width || videoWidth)));
+  const sh = Math.max(1, Math.min(videoHeight - sy, Math.round(source.height || videoHeight)));
+  const scale = Math.min(1, cap / Math.max(sw, sh));
+  const width = Math.max(1, Math.round(sw * scale));
+  const height = Math.max(1, Math.round(sh * scale));
+
+  // Crop and resize before crossing the worker boundary. Previously every
+  // 640px scan transferred a full 1080p camera bitmap and only then shrank it
+  // inside OffscreenCanvas. On phones that creates unnecessary GPU/memory
+  // pressure and can delay fresh-frame acquisition even though decoding is
+  // off-thread. The fallback preserves compatibility with browsers that do not
+  // implement the resize overload for video-backed ImageBitmap creation.
+  try {
+    const bitmap = await createImageBitmap(video, sx, sy, sw, sh, {
+      resizeWidth: width,
+      resizeHeight: height,
+      resizeQuality: "medium"
+    });
+    return {
+      bitmap,
+      source: { x: 0, y: 0, width: bitmap.width, height: bitmap.height, cropped: Boolean(source.cropped) },
+      originalSource: { ...source },
+      preScaled: true
+    };
+  } catch {
+    const bitmap = await createImageBitmap(video);
+    return {
+      bitmap,
+      source: { ...source },
+      originalSource: { ...source },
+      preScaled: false
+    };
+  }
+}
+
+function maximumFinderCount(workerResult) {
+  let count = 0;
+  for (const diagnostic of workerResult?.diagnostics ?? []) {
+    count = Math.max(
+      count,
+      Number(diagnostic?.finderCount) || 0,
+      Number(diagnostic?.bestPass?.finderCount) || 0
+    );
+    for (const pass of diagnostic?.finderPasses ?? []) {
+      count = Math.max(count, Number(pass?.finderCount) || 0);
+    }
+  }
+  return count;
+}
+
+async function startCameraScannerWorker(video, options = {}) {
+  assert(typeof navigator !== "undefined" && navigator.mediaDevices?.getUserMedia, "Camera API is unavailable.");
+  assert(video, "A video element is required.");
+
+  // Keep fresh-frame scanning independent from the expensive damaged/color
+  // recovery pipeline. Finder detection itself remains JavaScript; WASM is
+  // only an optional grayscale/binary + CRC accelerator beneath both workers.
+  // The fast worker can therefore inspect the newest frame even while the
+  // recovery worker is spending hundreds of milliseconds on an older difficult
+  // frame. No recovery method is removed.
+  const fastWorkerOptions = {
+    ...options,
+    cameraPipelineMode: "fast",
+    cameraHighResolutionRecovery: false,
+    cameraAutoColorRecovery: false,
+    autoEnhanceRecovery: false,
+    fullFrameAutoEnhanceRecovery: false,
+    multiFrame: false
+  };
+  const fastWorkerClient = await initializeCameraWorker(fastWorkerOptions);
+
+  let stream = null;
+  try {
+    stream = await navigator.mediaDevices.getUserMedia(
+      options.constraints ?? {
+        audio: false,
+        video: {
+          facingMode: { ideal: "environment" },
+          width: { ideal: 1280 },
+          height: { ideal: 720 },
+          frameRate: { ideal: 30 }
+        }
+      }
+    );
+    await improveCameraTrack(stream);
+
+    video.srcObject = stream;
+    video.setAttribute("playsinline", "");
+    video.muted = true;
+    await video.play();
+  } catch (error) {
+    fastWorkerClient.terminate();
+    for (const track of stream?.getTracks?.() ?? []) track.stop();
+    if (video.srcObject === stream) video.srcObject = null;
+    throw error;
+  }
+
+  const scanInterval = Math.max(24, Number(options.scanInterval ?? 33));
+  const fastCaptureMaxDimension = Math.max(480, Math.round(options.maxDimension ?? 640));
+  const recoveryCaptureMaxDimension = Math.max(
+    fastCaptureMaxDimension,
+    Math.round(options.cameraHighResolutionMaxDimension ?? 960)
+  );
+  const recoveryStrongFinderInterval = Math.max(80, Number(options.cameraRecoveryStrongFinderInterval ?? 120));
+  const recoveryWeakFinderInterval = Math.max(recoveryStrongFinderInterval, Number(options.cameraRecoveryWeakFinderInterval ?? 260));
+  const recoveryNoFinderInterval = Math.max(recoveryWeakFinderInterval, Number(options.cameraRecoveryNoFinderInterval ?? 850));
+  const useVideoFrameCallback = options.useVideoFrameCallback !== false &&
+    typeof video.requestVideoFrameCallback === "function";
+
+  let stopped = false;
+  let busy = false;
+  let recoveryBusy = false;
+  let recoveryWorkerClient = null;
+  let recoveryWorkerPromise = null;
+  let recoveryWorkerFailed = false;
+  let timer = null;
+  let frameCallbackId = null;
+  let lastScanStartedAt = -Infinity;
+  let lastRecoveryStartedAt = -Infinity;
+  let frameNumber = 0;
+  let requestToken = 0;
+  let recoveryToken = 0;
+
+  const diagnosticsEnabled = typeof options.onDiagnostic === "function";
+  const emitDiagnostic = (event) => {
+    if (!diagnosticsEnabled) return;
+    try {
+      options.onDiagnostic({
+        timestamp: Date.now(),
+        frame: event?.frame ?? frameNumber,
+        cameraWorker: true,
+        ...event
+      });
+    } catch {
+      // Diagnostics are UI-only and must never interrupt scanning.
+    }
+  };
+
+  const ensureRecoveryWorker = async () => {
+    if (recoveryWorkerClient) return recoveryWorkerClient;
+    if (recoveryWorkerFailed) return null;
+    if (!recoveryWorkerPromise) {
+      recoveryWorkerPromise = initializeCameraWorker({ ...options, cameraPipelineMode: "full" })
+        .then((client) => {
+          if (stopped) {
+            client.terminate();
+            return null;
+          }
+          recoveryWorkerClient = client;
+          return client;
+        })
+        .catch((error) => {
+          recoveryWorkerFailed = true;
+          emitDiagnostic({
+            type: "recovery-worker-error",
+            state: "fallback",
+            method: "camera-fast-worker",
+            message: `Parallel recovery worker unavailable · fast scanner remains active (${error?.message ?? String(error)})`
+          });
+          return null;
+        })
+        .finally(() => {
+          recoveryWorkerPromise = null;
+        });
+    }
+    return recoveryWorkerPromise;
+  };
+
+  const track = stream.getVideoTracks?.()[0];
+  const settings = track?.getSettings?.() ?? {};
+  emitDiagnostic({
+    type: "camera-ready",
+    method: "camera-dual-worker",
+    message: `Camera ready · ${settings.width ?? video.videoWidth}×${settings.height ?? video.videoHeight} · fast fresh-frame scanner + parallel recovery`,
+    camera: {
+      width: settings.width ?? video.videoWidth,
+      height: settings.height ?? video.videoHeight,
+      frameRate: settings.frameRate ?? null,
+      facingMode: settings.facingMode ?? null
+    },
+    worker: fastWorkerClient.state,
+    scanMaxDimension: fastCaptureMaxDimension,
+    recoveryMaxDimension: recoveryCaptureMaxDimension
+  });
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    requestToken++;
+    recoveryToken++;
+    if (timer) clearTimeout(timer);
+    if (frameCallbackId != null && typeof video.cancelVideoFrameCallback === "function") {
+      try { video.cancelVideoFrameCallback(frameCallbackId); } catch {}
+    }
+    timer = null;
+    frameCallbackId = null;
+    fastWorkerClient.terminate();
+    if (recoveryWorkerClient) {
+      recoveryWorkerClient.terminate();
+      recoveryWorkerClient = null;
+    } else if (recoveryWorkerPromise) {
+      void recoveryWorkerPromise.then((client) => client?.terminate()).catch(() => {});
+    }
+    for (const cameraTrack of stream.getTracks()) cameraTrack.stop();
+    if (video.srcObject === stream) video.srcObject = null;
+  };
+
+  // Preserve the historical immediate/manual helper as a synchronous scan of
+  // the current video element. The continuous scanner itself stays off-thread.
+  const scanNow = () => scanVideoFrame(video, {
+    ...options,
+    maxDimension: fastCaptureMaxDimension
+  });
+
+  const emitResult = (result, frameMeta = null) => {
+    if (stopped) return true;
+    const normalizedMeta = frameMeta
+      ? { frame: frameMeta.frame ?? frameNumber, ...frameMeta }
+      : null;
+    options.onResult?.(result, normalizedMeta);
+    options.onDecode?.(result, normalizedMeta);
+    if (options.stopOnResult ?? true) {
+      stop();
+      return true;
+    }
+    return false;
+  };
+
+  const runRecovery = async (triggerFrame, finderCount) => {
+    if (stopped || recoveryBusy) return;
+    recoveryBusy = true;
+    lastRecoveryStartedAt = nowMs();
+    const token = ++recoveryToken;
+    let bitmap = null;
+    try {
+      const client = await ensureRecoveryWorker();
+      if (stopped || token !== recoveryToken) return;
+      const recoveryClient = client ?? fastWorkerClient;
+      const singleWorkerFallback = !client;
+
+      // Capture only after the recovery execution path is ready. This guarantees
+      // the expensive path receives a fresh frame rather than a bitmap that sat
+      // in memory while a recovery worker was starting.
+      const visibleSource = visibleVideoSourceRect(video, options);
+      const captured = await captureCameraBitmap(video, visibleSource, recoveryCaptureMaxDimension);
+      bitmap = captured.bitmap;
+      if (stopped || token !== recoveryToken) {
+        bitmap.close?.();
+        return;
+      }
+
+      emitDiagnostic({
+        type: "recovery-dispatch",
+        state: "trying",
+        method: "parallel-full-recovery",
+        frame: triggerFrame,
+        finderCount,
+        message: finderCount > 0
+          ? `Fast frame saw ${finderCount} finder${finderCount === 1 ? "" : "s"} · full recovery running in parallel`
+          : "Periodic full recovery running in parallel while fast fresh-frame scanning continues"
+      });
+
+      const recoveryPayload = { bitmap, source: captured.source, frame: triggerFrame };
+      if (singleWorkerFallback) recoveryPayload.options = serializableCameraWorkerOptions(options);
+      const workerResult = await recoveryClient.request(
+        singleWorkerFallback ? "scan-full" : "scan",
+        recoveryPayload,
+        [bitmap]
+      );
+      bitmap = null;
+      if (stopped || token !== recoveryToken) return;
+
+      for (const diagnostic of workerResult?.diagnostics ?? []) {
+        emitDiagnostic({
+          ...diagnostic,
+          recoveryWorker: !singleWorkerFallback,
+          singleWorkerRecoveryFallback: singleWorkerFallback,
+          frame: triggerFrame
+        });
+      }
+      if (workerResult?.ok) {
+        emitResult(workerResult.result, { ...workerResult.frameMeta, frame: triggerFrame });
+      }
+    } catch (error) {
+      try { bitmap?.close?.(); } catch {}
+      if (!stopped) {
+        emitDiagnostic({
+          type: "recovery-worker-error",
+          state: "error",
+          method: "parallel-full-recovery",
+          frame: triggerFrame,
+          message: error?.message ?? String(error)
+        });
+      }
+    } finally {
+      recoveryBusy = false;
+    }
+  };
+
+  const maybeDispatchRecovery = (workerResult, triggerFrame) => {
+    if (stopped || recoveryBusy) return;
+    const finderCount = maximumFinderCount(workerResult);
+    const elapsed = nowMs() - lastRecoveryStartedAt;
+    const minimumInterval = finderCount >= 2
+      ? recoveryStrongFinderInterval
+      : finderCount === 1
+        ? recoveryWeakFinderInterval
+        : recoveryNoFinderInterval;
+    if (elapsed >= minimumInterval) void runRecovery(triggerFrame, finderCount);
+  };
+
+  const scheduleNextScan = () => {
+    if (stopped) return;
+    const runWhenDue = () => {
+      frameCallbackId = null;
+      if (stopped) return;
+      const remaining = scanInterval - (nowMs() - lastScanStartedAt);
+      if (remaining > 1) {
+        timer = setTimeout(() => {
+          timer = null;
+          scheduleNextScan();
+        }, remaining);
+        return;
+      }
+      void loop();
+    };
+
+    if (useVideoFrameCallback) {
+      frameCallbackId = video.requestVideoFrameCallback(runWhenDue);
+    } else {
+      const remaining = Math.max(0, scanInterval - (nowMs() - lastScanStartedAt));
+      timer = setTimeout(() => {
+        timer = null;
+        runWhenDue();
+      }, remaining);
+    }
+  };
+
+  const loop = async () => {
+    if (stopped) return;
+    if (!busy && video.readyState >= 2) {
+      busy = true;
+      frameNumber++;
+      const currentFrame = frameNumber;
+      lastScanStartedAt = nowMs();
+      const token = ++requestToken;
+      let bitmap = null;
+      try {
+        const visibleSource = visibleVideoSourceRect(video, options);
+        const captured = await captureCameraBitmap(video, visibleSource, fastCaptureMaxDimension);
+        bitmap = captured.bitmap;
+        if (stopped || token !== requestToken) {
+          bitmap.close?.();
+          return;
+        }
+        const workerResult = await fastWorkerClient.request(
+          "scan",
+          { bitmap, source: captured.source, frame: currentFrame },
+          [bitmap]
+        );
+        bitmap = null;
+        if (stopped || token !== requestToken) return;
+
+        for (const diagnostic of workerResult?.diagnostics ?? []) {
+          emitDiagnostic({ ...diagnostic, fastWorker: true, frame: currentFrame });
+        }
+        if (workerResult?.ok) {
+          if (emitResult(workerResult.result, { ...workerResult.frameMeta, frame: currentFrame })) return;
+        } else {
+          // Full perspective/color/damage recovery runs independently. Do not
+          // await it here: the next camera callback must remain free to inspect
+          // a newer frame immediately.
+          maybeDispatchRecovery(workerResult, currentFrame);
+          const error = new Error(workerResult?.error?.message ?? "Unable to decode QuadQR frame.");
+          error.name = workerResult?.error?.name ?? "Error";
+          error.debug = workerResult?.error?.debug ?? null;
+          options.onScanMiss?.(error);
+        }
+      } catch (error) {
+        try { bitmap?.close?.(); } catch {}
+        if (!stopped) {
+          emitDiagnostic({
+            type: "worker-error",
+            state: "error",
+            method: "camera-fast-worker",
+            frame: currentFrame,
+            message: error?.message ?? String(error)
+          });
+          options.onScanMiss?.(error);
+        }
+      } finally {
+        busy = false;
+      }
+    }
+    scheduleNextScan();
+  };
+
+  scheduleNextScan();
+  return {
+    stream,
+    stop,
+    scanNow,
+    video,
+    worker: true,
+    workerMode: "dual-pipeline",
+    workerState: fastWorkerClient.state
+  };
+}
+
+/**
+ * Start continuous camera scanning. Modern browsers use a dedicated module
+ * worker by default so the complete recovery pipeline can remain enabled
+ * without blocking rendering/input. Unsupported/CSP-restricted environments
+ * automatically fall back to the original main-thread scanner.
+ */
+export async function startCameraScanner(video, options = {}) {
+  if (cameraWorkerSupported(options)) {
+    try {
+      return await startCameraScannerWorker(video, options);
+    } catch (error) {
+      if (options.cameraWorkerRequired) throw error;
+      try {
+        options.onDiagnostic?.({
+          timestamp: Date.now(),
+          frame: 0,
+          type: "worker-fallback",
+          state: "fallback",
+          method: "camera-main-thread",
+          message: `Background scanner unavailable · using main-thread fallback (${error?.message ?? String(error)})`
+        });
+      } catch {}
+    }
+  }
+  return startCameraScannerMainThread(video, options);
+}
+
 export function rectifyDetectedCode(imageData, options = {}) {
   const candidates = detectCodeGeometry(imageData, {
     minVersion: options.minVersion ?? MIN_VERSION,
@@ -5129,6 +6839,9 @@ export const internals = Object.freeze({
   restoreLogicalOrder,
   cellsToSymbolConfidences,
   decodeRsAdaptive,
+  classifierFromPaletteRgb,
+  classifyRgb,
+  observationDataAgreement,
   encodeProtectedHeader,
   decodeProtectedHeader,
   selectBestFrameObservation,