quadqr-js 1.0.0 → 1.0.2

package/dist/quadqr.js

@@ -988,7 +988,7 @@ function luminance(rgb) {
   return 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b;
 }
 
-function buildGray(imageData) {
+function buildGray(imageData, mode = "luminance") {
   const gray = new Uint8Array(imageData.width * imageData.height);
   for (let i = 0; i < gray.length; i++) {
     const p = i * 4;
@@ -996,7 +996,15 @@ function buildGray(imageData) {
     const r = imageData.data[p] * a + 255 * (1 - a);
     const g = imageData.data[p + 1] * a + 255 * (1 - a);
     const b = imageData.data[p + 2] * a + 255 * (1 - a);
-    gray[i] = Math.round(0.2126 * r + 0.7152 * g + 0.0722 * b);
+
+    // Finder detection is special for QuadQR. Saturated red/green/blue data
+    // cells can look very dark in normal luminance, especially blue under a
+    // warm phone camera. The HSV "value" channel keeps any cell with one
+    // strong RGB component bright while structural black stays dark in all
+    // channels. That makes the black/white finder rings far easier to isolate.
+    gray[i] = Math.round(mode === "value"
+      ? Math.max(r, g, b)
+      : 0.2126 * r + 0.7152 * g + 0.0722 * b);
   }
   return gray;
 }
@@ -1032,12 +1040,28 @@ function otsuThreshold(gray) {
   return threshold;
 }
 
-function buildBinary(imageData) {
-  const gray = buildGray(imageData);
-  const threshold = otsuThreshold(gray);
+function binaryAtThreshold(gray, threshold) {
   const binary = new Uint8Array(gray.length);
   for (let i = 0; i < gray.length; i++) binary[i] = gray[i] <= threshold ? 1 : 0;
-  return { gray, binary, threshold };
+  return binary;
+}
+
+function buildBinary(imageData, options = {}) {
+  const grayMode = options.grayMode ?? "luminance";
+  const gray = buildGray(imageData, grayMode);
+  const baseThreshold = otsuThreshold(gray);
+  const threshold = clamp(
+    Math.round(baseThreshold + (options.thresholdOffset ?? 0)),
+    8,
+    247
+  );
+  return {
+    gray,
+    binary: binaryAtThreshold(gray, threshold),
+    threshold,
+    baseThreshold,
+    grayMode
+  };
 }
 
 function runsForRow(binary, width, row) {
@@ -1072,14 +1096,14 @@ function runsForColumn(binary, width, height, col) {
   return runs;
 }
 
-function finderRatioScore(lengths) {
+function finderRatioScore(lengths, toleranceScale = 1) {
   const total = lengths.reduce((sum, value) => sum + value, 0);
   if (total < 7) return Infinity;
   const module = total / 7;
   const expected = [module, module, 3 * module, module, module];
   let score = 0;
   for (let i = 0; i < 5; i++) {
-    const tolerance = i === 2 ? module * 1.25 : module * 0.8;
+    const tolerance = (i === 2 ? module * 1.25 : module * 0.8) * toleranceScale;
     const diff = Math.abs(lengths[i] - expected[i]);
     if (diff > tolerance) return Infinity;
     score += diff / Math.max(1, expected[i]);
@@ -1087,14 +1111,14 @@ function finderRatioScore(lengths) {
   return score;
 }
 
-function findWindowContainingCoordinate(runs, coordinate) {
+function findWindowContainingCoordinate(runs, coordinate, toleranceScale = 1) {
   for (let i = 2; i < runs.length - 2; i++) {
     const centerRun = runs[i];
     if (centerRun.color !== 1) continue;
     if (coordinate < centerRun.start || coordinate >= centerRun.start + centerRun.length) continue;
     const window = runs.slice(i - 2, i + 3);
     if (window.map((run) => run.color).join("") !== "10101") continue;
-    const score = finderRatioScore(window.map((run) => run.length));
+    const score = finderRatioScore(window.map((run) => run.length), toleranceScale);
     if (!Number.isFinite(score)) continue;
     const first = window[0].start;
     const total = window.reduce((sum, run) => sum + run.length, 0);
@@ -1107,17 +1131,17 @@ function findWindowContainingCoordinate(runs, coordinate) {
   return null;
 }
 
-function crossCheckVertical(binary, width, height, x, y) {
+function crossCheckVertical(binary, width, height, x, y, toleranceScale = 1) {
   const col = clamp(Math.round(x), 0, width - 1);
-  return findWindowContainingCoordinate(runsForColumn(binary, width, height, col), y);
+  return findWindowContainingCoordinate(runsForColumn(binary, width, height, col), y, toleranceScale);
 }
 
-function crossCheckHorizontal(binary, width, height, x, y) {
+function crossCheckHorizontal(binary, width, height, x, y, toleranceScale = 1) {
   const row = clamp(Math.round(y), 0, height - 1);
-  return findWindowContainingCoordinate(runsForRow(binary, width, row), x);
+  return findWindowContainingCoordinate(runsForRow(binary, width, row), x, toleranceScale);
 }
 
-function clusterFinderCandidates(raw) {
+function clusterFinderCandidates(raw, minConfirmations = 2) {
   const clusters = [];
   raw.sort((a, b) => a.moduleSize - b.moduleSize);
 
@@ -1150,7 +1174,7 @@ function clusterFinderCandidates(raw) {
   }
 
   return clusters
-    .filter((candidate) => candidate.confirmations >= 2)
+    .filter((candidate) => candidate.confirmations >= minConfirmations)
     .sort((a, b) =>
       (b.confirmations - a.confirmations) ||
       (a.score - b.score) ||
@@ -1158,9 +1182,12 @@ function clusterFinderCandidates(raw) {
     );
 }
 
-function detectFinderCandidates(binary, width, height) {
+function detectFinderCandidates(binary, width, height, options = {}) {
   const raw = [];
   const rowStep = height > 1200 ? 2 : 1;
+  const toleranceScale = options.toleranceScale ?? 1;
+  const moduleSpreadLimit = options.moduleSpreadLimit ?? 0.45;
+  const minConfirmations = options.minConfirmations ?? 2;
 
   for (let y = 0; y < height; y += rowStep) {
     const runs = runsForRow(binary, width, y);
@@ -1168,13 +1195,13 @@ function detectFinderCandidates(binary, width, height) {
       const window = runs.slice(i, i + 5);
       if (window.map((run) => run.color).join("") !== "10101") continue;
       const lengths = window.map((run) => run.length);
-      const ratioScore = finderRatioScore(lengths);
+      const ratioScore = finderRatioScore(lengths, toleranceScale);
       if (!Number.isFinite(ratioScore)) continue;
       const total = lengths.reduce((sum, value) => sum + value, 0);
       const centerX = window[0].start + total / 2;
-      const vertical = crossCheckVertical(binary, width, height, centerX, y);
+      const vertical = crossCheckVertical(binary, width, height, centerX, y, toleranceScale);
       if (!vertical) continue;
-      const horizontal = crossCheckHorizontal(binary, width, height, centerX, vertical.center);
+      const horizontal = crossCheckHorizontal(binary, width, height, centerX, vertical.center, toleranceScale);
       if (!horizontal) continue;
 
       const moduleSize = (total / 7 + vertical.moduleSize + horizontal.moduleSize) / 3;
@@ -1183,7 +1210,7 @@ function detectFinderCandidates(binary, width, height) {
         Math.abs(moduleSize - vertical.moduleSize),
         Math.abs(moduleSize - horizontal.moduleSize)
       ) / moduleSize;
-      if (moduleSpread > 0.45) continue;
+      if (moduleSpread > moduleSpreadLimit) continue;
 
       raw.push({
         x: horizontal.center,
@@ -1194,7 +1221,7 @@ function detectFinderCandidates(binary, width, height) {
     }
   }
 
-  return clusterFinderCandidates(raw);
+  return clusterFinderCandidates(raw, minConfirmations);
 }
 
 function dot(a, b) {
@@ -1418,15 +1445,11 @@ function projectPoint(h, u, v) {
   };
 }
 
-function detectCodeGeometry(imageData, options = {}) {
-  assert(imageData?.data && imageData.width && imageData.height, "Valid image data is required.");
+function geometryCandidatesFromBinary(binary, width, height, finders, threshold, options = {}) {
+  if (finders.length < 3) return [];
   const minVersion = options.minVersion ?? 1;
   const maxVersion = options.maxVersion ?? 40;
   const maxCandidates = options.maxCandidates ?? 8;
-  const { binary, threshold } = buildBinary(imageData);
-  const finders = detectFinderCandidates(binary, imageData.width, imageData.height);
-  if (finders.length < 3) return [];
-
   const triples = chooseFinderTriples(finders, 20);
   const geometries = [];
 
@@ -1439,8 +1462,8 @@ function detectCodeGeometry(imageData, options = {}) {
     for (const item of versions) {
       const version = item.version;
       const size = sizeForVersion(version);
-      const alignment = searchAlignment(binary, imageData.width, imageData.height, triple, version);
-      if (alignment.score < 0.72) continue;
+      const alignment = searchAlignment(binary, width, height, triple, version);
+      if (alignment.score < (options.alignmentThreshold ?? 0.72)) continue;
 
       const alignmentTarget = alignment.target;
       const dest = [
@@ -1463,8 +1486,8 @@ function detectCodeGeometry(imageData, options = {}) {
         continue;
       }
 
-      const alignmentGrid = scoreAlignmentGrid(binary, imageData.width, imageData.height, homography, version);
-      if (alignmentGrid.score < 0.68) continue;
+      const alignmentGrid = scoreAlignmentGrid(binary, width, height, homography, version);
+      if (alignmentGrid.score < (options.alignmentGridThreshold ?? 0.68)) continue;
 
       const versionPenalty = item.error / 4;
       const alignmentConfidence = 0.55 * alignment.score + 0.45 * alignmentGrid.score;
@@ -1486,13 +1509,13 @@ function detectCodeGeometry(imageData, options = {}) {
           patternScores: alignmentGrid.patternScores
         },
         threshold,
+        finderMethod: options.finderMethod,
         estimatedSize,
         score
       });
     }
   }
 
-  // Deduplicate roughly identical geometry/version hypotheses.
   const deduped = [];
   geometries.sort((a, b) => b.score - a.score);
   for (const geometry of geometries) {
@@ -1509,33 +1532,489 @@ function detectCodeGeometry(imageData, options = {}) {
   return deduped;
 }
 
+function pushFinderDiagnostic(options, finderMethod, threshold, finders, geometries) {
+  if (!options.diagnostics || typeof options.diagnostics !== "object") return;
+  const passes = Array.isArray(options.diagnostics.passes)
+    ? options.diagnostics.passes
+    : (options.diagnostics.passes = []);
+  passes.push({
+    label: options.diagnosticLabel ?? "perspective",
+    finderMethod,
+    width: options.width,
+    height: options.height,
+    threshold,
+    finderCount: finders.length,
+    finders: finders.map((finder) => ({
+      x: finder.x,
+      y: finder.y,
+      moduleSize: finder.moduleSize,
+      confirmations: finder.confirmations,
+      score: finder.score
+    })),
+    geometries: geometries.map((geometry) => ({
+      version: geometry.version,
+      size: geometry.size,
+      score: geometry.score,
+      estimatedSize: geometry.estimatedSize,
+      alignmentScore: geometry.alignment.score,
+      alignmentGridScore: geometry.alignment.gridScore,
+      finderMethod: geometry.finderMethod,
+      finders: {
+        topLeft: { ...geometry.finders.topLeft },
+        topRight: { ...geometry.finders.topRight },
+        bottomLeft: { ...geometry.finders.bottomLeft }
+      },
+      alignmentCenter: { ...geometry.alignment.center },
+      sourcePoints: geometry.sourcePoints.map((point) => ({ ...point }))
+    }))
+  });
+}
+
+function detectCodeGeometry(imageData, options = {}) {
+  assert(imageData?.data && imageData.width && imageData.height, "Valid image data is required.");
+  const width = imageData.width;
+  const height = imageData.height;
+  const maxCandidates = options.maxCandidates ?? 8;
+
+  const evaluatePass = (pass, recovery = false) => {
+    const finders = detectFinderCandidates(pass.binary, width, height, pass.detector ?? {});
+    const geometries = geometryCandidatesFromBinary(
+      pass.binary,
+      width,
+      height,
+      finders,
+      pass.threshold,
+      {
+        ...options,
+        finderMethod: pass.finderMethod,
+        alignmentThreshold: recovery ? 0.68 : 0.72,
+        alignmentGridThreshold: recovery ? 0.64 : 0.68
+      }
+    );
+
+    pushFinderDiagnostic(
+      { ...options, width, height },
+      pass.finderMethod,
+      pass.threshold,
+      finders,
+      geometries
+    );
+    return { finders, geometries };
+  };
+
+  // Fast path stays exactly one grayscale + finder pass. No Auto Color, extra
+  // thresholding, or luminance image is computed when a normal frame works.
+  const valueInfo = buildBinary(imageData, { grayMode: "value" });
+  const fast = evaluatePass({
+    finderMethod: "rgb-value-otsu",
+    binary: valueInfo.binary,
+    threshold: valueInfo.threshold,
+    detector: {}
+  }, false);
+  if (fast.geometries.length) return fast.geometries.slice(0, maxCandidates);
+  if (options.finderRecovery === false) return [];
+
+  // Camera recovery #1: Photoshop Auto Color-style per-channel levels before
+  // finder thresholding. Live camera frames are usually much larger than the
+  // QR itself, so a single global histogram can be dominated by dark room/UI
+  // pixels around the guide. Photoshop looked strong in the user's cropped
+  // sample because its statistics were effectively code-centric. We emulate
+  // that by trying a few center-weighted analysis windows, while still applying
+  // each correction to the full frame so finder coordinates never move.
+  const requestedInsets = Array.isArray(options.finderAutoColorAnalysisInsets)
+    ? options.finderAutoColorAnalysisInsets
+    : (Number.isFinite(options.finderAutoColorAnalysisInset)
+      ? [options.finderAutoColorAnalysisInset]
+      : [0.10, 0.20, 0.04]);
+  const autoColorInsets = [];
+  for (const value of requestedInsets) {
+    const inset = clamp(Number(value), 0, 0.30);
+    if (!autoColorInsets.some((item) => Math.abs(item - inset) < 0.001)) autoColorInsets.push(inset);
+  }
+
+  for (const analysisInset of autoColorInsets) {
+    try {
+      const autoColorGray = buildAutoColorValueGray(imageData, {
+        blackClip: options.finderAutoColorBlackClip ?? 0.0001,
+        whiteClip: options.finderAutoColorWhiteClip,
+        highlightPercentile: options.finderAutoColorHighlightPercentile ?? 0.95,
+        outputHighlight: options.finderAutoColorOutputHighlight ?? 190,
+        analysisInset,
+        minimumInputRange: options.finderAutoColorMinimumInputRange ?? 72,
+        targetSamples: options.finderAutoColorTargetSamples
+      });
+      const base = otsuThreshold(autoColorGray);
+      const insetLabel = String(Math.round(analysisInset * 100)).padStart(2, "0");
+      const thresholds = [
+        { suffix: "otsu", value: base },
+        { suffix: "high", value: clamp(base + 12, 8, 247) }
+      ];
+      for (const thresholdInfo of thresholds) {
+        const autoColor = evaluatePass({
+          finderMethod: `auto-color-center${insetLabel}-${thresholdInfo.suffix}`,
+          binary: binaryAtThreshold(autoColorGray, thresholdInfo.value),
+          threshold: thresholdInfo.value,
+          detector: { toleranceScale: 1.22, moduleSpreadLimit: 0.60 }
+        }, true);
+        if (autoColor.geometries.length) return autoColor.geometries.slice(0, maxCandidates);
+      }
+    } catch {
+      // Try the next center weighting, then continue with raw threshold bracketing.
+    }
+  }
+
+  // Camera recovery #2: bracket the raw value-channel threshold, then retain
+  // the legacy luminance pass for unusual captures. These are only built after
+  // both the normal and Auto Color finder passes fail.
+  const highThreshold = clamp(valueInfo.baseThreshold + 18, 8, 247);
+  const lowThreshold = clamp(valueInfo.baseThreshold - 14, 8, 247);
+  const recoveryPasses = [];
+  if (highThreshold !== valueInfo.threshold) {
+    recoveryPasses.push({
+      finderMethod: "rgb-value-high-threshold",
+      binary: binaryAtThreshold(valueInfo.gray, highThreshold),
+      threshold: highThreshold,
+      detector: { toleranceScale: 1.18, moduleSpreadLimit: 0.56 }
+    });
+  }
+  if (lowThreshold !== valueInfo.threshold) {
+    recoveryPasses.push({
+      finderMethod: "rgb-value-low-threshold",
+      binary: binaryAtThreshold(valueInfo.gray, lowThreshold),
+      threshold: lowThreshold,
+      detector: { toleranceScale: 1.14, moduleSpreadLimit: 0.54 }
+    });
+  }
+  const lumaInfo = buildBinary(imageData, { grayMode: "luminance" });
+  recoveryPasses.push({
+    finderMethod: "luminance-otsu",
+    binary: lumaInfo.binary,
+    threshold: lumaInfo.threshold,
+    detector: { toleranceScale: 1.10, moduleSpreadLimit: 0.52 }
+  });
+
+  for (const pass of recoveryPasses) {
+    const recovery = evaluatePass(pass, true);
+    if (recovery.geometries.length) return recovery.geometries.slice(0, maxCandidates);
+  }
+
+  return [];
+}
+
+function median(values) {
+  if (!values.length) return 0;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2
+    ? sorted[middle]
+    : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+
+function robustRgb(values) {
+  if (!values.length) throw new Error("No RGB samples available.");
+  return {
+    r: median(values.map((rgb) => rgb.r)),
+    g: median(values.map((rgb) => rgb.g)),
+    b: median(values.map((rgb) => rgb.b))
+  };
+}
+
 function averageProjectedSample(imageData, homography, moduleX, moduleY, radius = 0.16) {
   const offsets = radius > 0
     ? [[0, 0], [-radius, 0], [radius, 0], [0, -radius], [0, radius]]
     : [[0, 0]];
-  let r = 0;
-  let g = 0;
-  let b = 0;
-  let count = 0;
+  const values = [];
   for (const [dx, dy] of offsets) {
     const point = projectPoint(homography, moduleX + dx, moduleY + dy);
     if (point.x < 0 || point.y < 0 || point.x >= imageData.width || point.y >= imageData.height) continue;
-    const rgb = bilinearRgb(imageData, point.x, point.y);
-    r += rgb.r;
-    g += rgb.g;
-    b += rgb.b;
-    count++;
+    values.push(bilinearRgb(imageData, point.x, point.y));
+  }
+  if (!values.length) return { r: 255, g: 255, b: 255 };
+  return averageRgb(values);
+}
+
+function robustProjectedSample(imageData, homography, moduleX, moduleY, radius = 0.12) {
+  // Fallback for dirty/soft-focus camera frames. A compact 3x3 patch stays
+  // away from module edges and median aggregation rejects glare/speckles.
+  const offsets = radius > 0 ? [-radius, 0, radius] : [0];
+  const values = [];
+  for (const dy of offsets) {
+    for (const dx of offsets) {
+      const point = projectPoint(homography, moduleX + dx, moduleY + dy);
+      if (point.x < 0 || point.y < 0 || point.x >= imageData.width || point.y >= imageData.height) continue;
+      values.push(bilinearRgb(imageData, point.x, point.y));
+    }
+  }
+  return values.length ? robustRgb(values) : { r: 255, g: 255, b: 255 };
+}
+
+
+
+function histogramPercentile(histogram, total, fraction) {
+  if (!total) return 0;
+  const target = Math.max(1, Math.ceil(total * clamp(fraction, 0, 1)));
+  let seen = 0;
+  for (let i = 0; i < histogram.length; i++) {
+    seen += histogram[i];
+    if (seen >= target) return i;
+  }
+  return histogram.length - 1;
+}
+
+
+function buildAutoColorLevels(imageData, options = {}) {
+  const analysisInset = clamp(options.analysisInset ?? 0, 0, 0.30);
+  const x0 = Math.floor(imageData.width * analysisInset);
+  const y0 = Math.floor(imageData.height * analysisInset);
+  const x1 = Math.max(x0 + 1, Math.ceil(imageData.width * (1 - analysisInset)));
+  const y1 = Math.max(y0 + 1, Math.ceil(imageData.height * (1 - analysisInset)));
+  const analysisWidth = Math.max(1, x1 - x0);
+  const analysisHeight = Math.max(1, y1 - y0);
+  const pixelCount = analysisWidth * analysisHeight;
+  const targetSamples = Math.max(4000, Math.round(options.targetSamples ?? 90000));
+  const step = Math.max(1, Math.floor(pixelCount / targetSamples));
+  const histograms = [new Uint32Array(256), new Uint32Array(256), new Uint32Array(256)];
+  let samples = 0;
+
+  // Camera recovery deliberately supports analysing only the central part of
+  // the visible frame. A phone preview often contains very dark UI/screen
+  // edges outside the code; letting those pixels define the black point makes
+  // an otherwise useful Auto Color pass far too weak.
+  for (let index = 0; index < pixelCount; index += step) {
+    const x = x0 + (index % analysisWidth);
+    const y = y0 + Math.floor(index / analysisWidth);
+    const p = (y * imageData.width + x) * 4;
+    const a = imageData.data[p + 3] / 255;
+    const rgb = [
+      imageData.data[p] * a + 255 * (1 - a),
+      imageData.data[p + 1] * a + 255 * (1 - a),
+      imageData.data[p + 2] * a + 255 * (1 - a)
+    ];
+    for (let channel = 0; channel < 3; channel++) {
+      histograms[channel][clamp(Math.round(rgb[channel]), 0, 255)]++;
+    }
+    samples++;
+  }
+
+  const blackClip = clamp(options.blackClip ?? 0.004, 0, 0.06);
+  const whiteClip = clamp(options.whiteClip ?? 0.004, 0, 0.06);
+  const lows = histograms.map((histogram) => histogramPercentile(histogram, samples, blackClip));
+
+  let references;
+  let highs;
+  const outputHighlight = Number(options.outputHighlight);
+  if (Number.isFinite(outputHighlight)) {
+    // Strong Photoshop-like camera mode. Photoshop Auto Color on the supplied
+    // warm camera sample does not stretch the brightest observed paper/white
+    // cells all the way to 255. Instead it anchors the per-channel shadow
+    // points close to black while keeping the observed highlight around a
+    // neutral mid-high value. That produces much darker structural black and
+    // much stronger RGB separation without washing the whole code out.
+    const highlightPercentile = clamp(options.highlightPercentile ?? 0.95, 0.70, 0.9999);
+    const target = clamp(outputHighlight, 96, 250);
+    references = histograms.map((histogram) => histogramPercentile(histogram, samples, highlightPercentile));
+    const minimumInputRange = Math.max(32, Math.round(options.minimumInputRange ?? 72));
+    highs = references.map((reference, channel) => {
+      const observedRange = Math.max(minimumInputRange, reference - lows[channel]);
+      return lows[channel] + observedRange * 255 / target;
+    });
+  } else {
+    references = histograms.map((histogram) => histogramPercentile(histogram, samples, 1 - whiteClip));
+    highs = references.slice();
+    for (let channel = 0; channel < 3; channel++) {
+      highs[channel] = Math.max(lows[channel] + 24, highs[channel]);
+    }
+  }
+
+  const mapChannel = (value, channel) => clamp(
+    (value - lows[channel]) * 255 / Math.max(1, highs[channel] - lows[channel]),
+    0,
+    255
+  );
+
+  return { lows, highs, references, mapChannel };
+}
+
+function autoColorImageData(imageData, options = {}) {
+  const levels = buildAutoColorLevels(imageData, options);
+  const pixelCount = imageData.width * imageData.height;
+  const data = new Uint8ClampedArray(imageData.data.length);
+  for (let index = 0; index < pixelCount; index++) {
+    const p = index * 4;
+    const a = imageData.data[p + 3] / 255;
+    const r = imageData.data[p] * a + 255 * (1 - a);
+    const g = imageData.data[p + 1] * a + 255 * (1 - a);
+    const b = imageData.data[p + 2] * a + 255 * (1 - a);
+    data[p] = levels.mapChannel(r, 0);
+    data[p + 1] = levels.mapChannel(g, 1);
+    data[p + 2] = levels.mapChannel(b, 2);
+    data[p + 3] = 255;
+  }
+  return { width: imageData.width, height: imageData.height, data };
+}
+
+function buildAutoColorValueGray(imageData, options = {}) {
+  const levels = buildAutoColorLevels(imageData, options);
+  const gray = new Uint8Array(imageData.width * imageData.height);
+  for (let i = 0; i < gray.length; i++) {
+    const p = i * 4;
+    const a = imageData.data[p + 3] / 255;
+    const r = imageData.data[p] * a + 255 * (1 - a);
+    const g = imageData.data[p + 1] * a + 255 * (1 - a);
+    const b = imageData.data[p + 2] * a + 255 * (1 - a);
+    gray[i] = Math.round(Math.max(
+      levels.mapChannel(r, 0),
+      levels.mapChannel(g, 1),
+      levels.mapChannel(b, 2)
+    ));
+  }
+  return gray;
+}
+
+function buildAutoToneContrastColorTransform(samples, options = {}) {
+  if (!samples?.length) return (rgb) => rgb;
+  const blackClip = clamp(options.blackClip ?? 0.006, 0, 0.08);
+  const whiteClip = clamp(options.whiteClip ?? 0.004, 0, 0.08);
+  const highlightFraction = clamp(options.highlightFraction ?? 0.14, 0.04, 0.35);
+  const saturation = clamp(options.saturation ?? 1.12, 1, 1.5);
+
+  // Auto Color-style neutralization: use the brightest portion of the frame as
+  // a likely white reference. This is especially effective on warm/yellow
+  // phone-camera frames where the blue channel is suppressed.
+  const luminanceHistogram = new Uint32Array(256);
+  for (const rgb of samples) {
+    const y = clamp(Math.round(luminance(rgb)), 0, 255);
+    luminanceHistogram[y]++;
+  }
+  const highlightThreshold = histogramPercentile(
+    luminanceHistogram,
+    samples.length,
+    1 - highlightFraction
+  );
+  let highlightR = 0;
+  let highlightG = 0;
+  let highlightB = 0;
+  let highlightCount = 0;
+  for (const rgb of samples) {
+    if (luminance(rgb) < highlightThreshold) continue;
+    highlightR += rgb.r;
+    highlightG += rgb.g;
+    highlightB += rgb.b;
+    highlightCount++;
+  }
+  const highlightMean = highlightCount
+    ? { r: highlightR / highlightCount, g: highlightG / highlightCount, b: highlightB / highlightCount }
+    : { r: 255, g: 255, b: 255 };
+  const neutralTarget = (highlightMean.r + highlightMean.g + highlightMean.b) / 3;
+  const gains = {
+    r: clamp(neutralTarget / Math.max(24, highlightMean.r), 0.72, 1.42),
+    g: clamp(neutralTarget / Math.max(24, highlightMean.g), 0.72, 1.42),
+    b: clamp(neutralTarget / Math.max(24, highlightMean.b), 0.72, 1.42)
+  };
+
+  // Auto Tone-style per-channel levels after the neutralization above.
+  const histograms = [new Uint32Array(256), new Uint32Array(256), new Uint32Array(256)];
+  for (const rgb of samples) {
+    const corrected = [rgb.r * gains.r, rgb.g * gains.g, rgb.b * gains.b];
+    for (let channel = 0; channel < 3; channel++) {
+      histograms[channel][clamp(Math.round(corrected[channel]), 0, 255)]++;
+    }
+  }
+  const lows = histograms.map((histogram) => histogramPercentile(histogram, samples.length, blackClip));
+  const highs = histograms.map((histogram) => histogramPercentile(histogram, samples.length, 1 - whiteClip));
+  for (let channel = 0; channel < 3; channel++) {
+    highs[channel] = Math.max(lows[channel] + 20, highs[channel]);
+  }
+
+  const tone = (value, channel) => clamp(
+    (value * [gains.r, gains.g, gains.b][channel] - lows[channel]) * 255 / (highs[channel] - lows[channel]),
+    0,
+    255
+  );
+
+  // Auto Contrast-style common tonal expansion is calculated after the
+  // per-channel levels so it does not undo white-balance correction.
+  const toneLuminanceHistogram = new Uint32Array(256);
+  for (const rgb of samples) {
+    const corrected = { r: tone(rgb.r, 0), g: tone(rgb.g, 1), b: tone(rgb.b, 2) };
+    toneLuminanceHistogram[clamp(Math.round(luminance(corrected)), 0, 255)]++;
   }
-  if (!count) return { r: 255, g: 255, b: 255 };
-  return { r: r / count, g: g / count, b: b / count };
+  const contrastLow = histogramPercentile(toneLuminanceHistogram, samples.length, blackClip);
+  const contrastHigh = Math.max(
+    contrastLow + 28,
+    histogramPercentile(toneLuminanceHistogram, samples.length, 1 - whiteClip)
+  );
+  const contrast = (value) => clamp((value - contrastLow) * 255 / (contrastHigh - contrastLow), 0, 255);
+
+  return (rgb) => {
+    let r = contrast(tone(rgb.r, 0));
+    let g = contrast(tone(rgb.g, 1));
+    let b = contrast(tone(rgb.b, 2));
+
+    // A small saturation recovery restores separation lost to lens haze and
+    // bilinear camera scaling. It is intentionally conservative because this
+    // path runs only after the normal scanner has failed.
+    const y = luminance({ r, g, b });
+    r = clamp(y + (r - y) * saturation, 0, 255);
+    g = clamp(y + (g - y) * saturation, 0, 255);
+    b = clamp(y + (b - y) * saturation, 0, 255);
+    return { r, g, b };
+  };
+}
+
+function autoToneContrastColorRgbGrid(rgbGrid, options = {}) {
+  const samples = [];
+  for (const row of rgbGrid) for (const rgb of row) samples.push(rgb);
+  const transform = buildAutoToneContrastColorTransform(samples, options);
+  return rgbGrid.map((row) => row.map((rgb) => transform(rgb)));
+}
+
+function autoToneContrastColorImageData(imageData, options = {}) {
+  const pixelCount = imageData.width * imageData.height;
+  const targetSamples = Math.max(8000, Math.round(options.targetSamples ?? 160000));
+  const step = Math.max(1, Math.floor(pixelCount / targetSamples));
+  const samples = [];
+  for (let index = 0; index < pixelCount; index += step) {
+    const p = index * 4;
+    const a = imageData.data[p + 3] / 255;
+    samples.push({
+      r: imageData.data[p] * a + 255 * (1 - a),
+      g: imageData.data[p + 1] * a + 255 * (1 - a),
+      b: imageData.data[p + 2] * a + 255 * (1 - a)
+    });
+  }
+
+  const transform = buildAutoToneContrastColorTransform(samples, options);
+  const data = new Uint8ClampedArray(imageData.data.length);
+  for (let index = 0; index < pixelCount; index++) {
+    const p = index * 4;
+    const a = imageData.data[p + 3] / 255;
+    const corrected = transform({
+      r: imageData.data[p] * a + 255 * (1 - a),
+      g: imageData.data[p + 1] * a + 255 * (1 - a),
+      b: imageData.data[p + 2] * a + 255 * (1 - a)
+    });
+    data[p] = corrected.r;
+    data[p + 1] = corrected.g;
+    data[p + 2] = corrected.b;
+    data[p + 3] = 255;
+  }
+  return { width: imageData.width, height: imageData.height, data };
 }
 
 function samplePerspectiveMatrix(imageData, homography, size, options = {}) {
   const rgbGrid = Array.from({ length: size }, () => new Array(size));
-  const radius = options.sampleRadius ?? 0.16;
+  const mode = options.sampleMode ?? "cross";
+  const radius = options.sampleRadius ?? (mode === "median" ? 0.12 : 0.16);
+  const offsetX = Number.isFinite(options.sampleOffsetX) ? options.sampleOffsetX : 0;
+  const offsetY = Number.isFinite(options.sampleOffsetY) ? options.sampleOffsetY : 0;
   for (let r = 0; r < size; r++) {
     for (let c = 0; c < size; c++) {
-      rgbGrid[r][c] = averageProjectedSample(imageData, homography, c + 0.5, r + 0.5, radius);
+      const moduleX = c + 0.5 + offsetX;
+      const moduleY = r + 0.5 + offsetY;
+      rgbGrid[r][c] = mode === "median"
+        ? robustProjectedSample(imageData, homography, moduleX, moduleY, radius)
+        : averageProjectedSample(imageData, homography, moduleX, moduleY, radius);
     }
   }
   return { rgbGrid };
@@ -1566,13 +2045,14 @@ function pickCalibrationSamples(rgbGrid, positions, limit = 24) {
   return out;
 }
 
-function sampleObservedPalette(rgbGrid, calibration) {
+function sampleObservedPalette(rgbGrid, calibration, options = {}) {
+  const aggregate = options.robust ? robustRgb : averageRgb;
   const palette = {
-    black: averageRgb(pickCalibrationSamples(rgbGrid, calibration.black, 36)),
-    white: averageRgb(pickCalibrationSamples(rgbGrid, calibration.white, 36)),
-    red: averageRgb(pickCalibrationSamples(rgbGrid, calibration.red, 12)),
-    green: averageRgb(pickCalibrationSamples(rgbGrid, calibration.green, 12)),
-    blue: averageRgb(pickCalibrationSamples(rgbGrid, calibration.blue, 12))
+    black: aggregate(pickCalibrationSamples(rgbGrid, calibration.black, 36)),
+    white: aggregate(pickCalibrationSamples(rgbGrid, calibration.white, 36)),
+    red: aggregate(pickCalibrationSamples(rgbGrid, calibration.red, 12)),
+    green: aggregate(pickCalibrationSamples(rgbGrid, calibration.green, 12)),
+    blue: aggregate(pickCalibrationSamples(rgbGrid, calibration.blue, 12))
   };
 
   // All five observed classes must remain separated enough for reliable RGBW
@@ -1592,6 +2072,71 @@ function sampleObservedPalette(rgbGrid, calibration) {
   return palette;
 }
 
+function calibrationReferencePoints(rgbGrid, positions, limit = 64) {
+  if (!positions?.length) return [];
+  const step = Math.max(1, Math.floor(positions.length / limit));
+  const refs = [];
+  for (let i = 0; i < positions.length; i += step) {
+    const [row, col] = positions[i];
+    refs.push({ row, col, rgb: rgbGrid[row][col] });
+    if (refs.length >= limit) break;
+  }
+  return refs;
+}
+
+function estimateLocalReference(refs, row, col) {
+  if (!refs.length) return { r: 0, g: 0, b: 0 };
+  let wr = 0;
+  let wg = 0;
+  let wb = 0;
+  let total = 0;
+  for (const ref of refs) {
+    const dr = row - ref.row;
+    const dc = col - ref.col;
+    const distanceSq = dr * dr + dc * dc;
+    if (distanceSq < 1e-9) return ref.rgb;
+    // Smooth inverse-distance weighting. The +4 prevents one slightly blurred
+    // structural cell from dominating the local estimate.
+    const weight = 1 / (distanceSq + 4);
+    wr += ref.rgb.r * weight;
+    wg += ref.rgb.g * weight;
+    wb += ref.rgb.b * weight;
+    total += weight;
+  }
+  return {
+    r: wr / total,
+    g: wg / total,
+    b: wb / total
+  };
+}
+
+function spatiallyNormalizeRgbGrid(rgbGrid, calibration, options = {}) {
+  const size = rgbGrid.length;
+  const limit = options.referenceLimit ?? 64;
+  const blackRefs = calibrationReferencePoints(rgbGrid, calibration.black, limit);
+  const whiteRefs = calibrationReferencePoints(rgbGrid, calibration.white, limit);
+  if (!blackRefs.length || !whiteRefs.length) throw new Error("Black/white references are required for spatial color normalization.");
+
+  const normalized = Array.from({ length: size }, () => new Array(size));
+  for (let row = 0; row < size; row++) {
+    for (let col = 0; col < size; col++) {
+      const rgb = rgbGrid[row][col];
+      const black = estimateLocalReference(blackRefs, row, col);
+      const white = estimateLocalReference(whiteRefs, row, col);
+      const normalizeChannel = (value, low, high) => {
+        const range = Math.max(28, high - low);
+        return clamp((value - low) * 255 / range, -96, 384);
+      };
+      normalized[row][col] = {
+        r: normalizeChannel(rgb.r, black.r, white.r),
+        g: normalizeChannel(rgb.g, black.g, white.g),
+        b: normalizeChannel(rgb.b, black.b, white.b)
+      };
+    }
+  }
+  return normalized;
+}
+
 function rectifyImageData(imageData, homography, size, moduleSize = 8) {
   const outputSize = Math.max(1, Math.round(size * moduleSize));
   const data = new Uint8ClampedArray(outputSize * outputSize * 4);
@@ -1683,12 +2228,12 @@ const visionInternals = Object.freeze({
   luminance
 });
 
-return { computeHomography, projectPoint, detectCodeGeometry, samplePerspectiveMatrix, sampleObservedPalette, rectifyImageData, findActiveBounds, sampleAxisAlignedGrid, visionInternals };
+return { computeHomography, projectPoint, detectCodeGeometry, autoColorImageData, autoToneContrastColorRgbGrid, autoToneContrastColorImageData, samplePerspectiveMatrix, sampleObservedPalette, spatiallyNormalizeRgbGrid, rectifyImageData, findActiveBounds, sampleAxisAlignedGrid, visionInternals };
 })();
 const __qqr_quadqr_js = (function () {
 const { MAX_CODEWORD_SYMBOLS, rsEncode, rsDecode } = __qqr_reed_solomon_js;
 const { alignmentPatternCentersForVersion, alignmentPatternIsBlack, alignmentPatternRadius, sizeForVersion, versionFromSize } = __qqr_geometry_js;
-const { detectCodeGeometry, samplePerspectiveMatrix, rectifyImageData, sampleObservedPalette, findActiveBounds, sampleAxisAlignedGrid } = __qqr_vision_js;
+const { detectCodeGeometry, samplePerspectiveMatrix, rectifyImageData, sampleObservedPalette, spatiallyNormalizeRgbGrid, autoToneContrastColorRgbGrid, autoToneContrastColorImageData, autoColorImageData, findActiveBounds, sampleAxisAlignedGrid } = __qqr_vision_js;
 const { decryptSecurePayload, encryptSecurePayload, inspectSecureEnvelope, SECURITY_MODES, SECURITY_ALGORITHMS, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, generateRaw256Key, normalizeRaw256Key, bytesToHex } = __qqr_security_js;
 /**
  * QuadQR
@@ -3243,14 +3788,55 @@ function renderToImageData(codeOrMatrix, options = {}) {
   return { width: pixelSize, height: pixelSize, data };
 }
 
-function classifierFromPaletteRgb(observed) {
-  return [
-    { cell: CELL.BLACK, rgb: observed.black },
-    { cell: CELL.WHITE, rgb: observed.white },
-    { cell: CELL.RED, rgb: observed.red },
-    { cell: CELL.GREEN, rgb: observed.green },
-    { cell: CELL.BLUE, rgb: observed.blue }
+function clampNumber(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function identityColorTransform(rgb) {
+  return rgb;
+}
+
+function makeWhiteBalanceTransform(observed) {
+  const black = observed.black;
+  const white = observed.white;
+  const ranges = {
+    r: Math.max(32, white.r - black.r),
+    g: Math.max(32, white.g - black.g),
+    b: Math.max(32, white.b - black.b)
+  };
+
+  return (rgb) => ({
+    // Normalize the camera's observed black/white points per channel. This
+    // boosts a suppressed blue channel under warm/yellow illumination without
+    // changing the QuadQR palette or payload capacity.
+    r: clampNumber((rgb.r - black.r) * 255 / ranges.r, -96, 384),
+    g: clampNumber((rgb.g - black.g) * 255 / ranges.g, -96, 384),
+    b: clampNumber((rgb.b - black.b) * 255 / ranges.b, -96, 384)
+  });
+}
+
+function classifierFromPaletteRgb(observed, mode = "raw") {
+  const transform = mode === "balanced" || mode === "hue"
+    ? makeWhiteBalanceTransform(observed)
+    : identityColorTransform;
+  const entries = [
+    { cell: CELL.BLACK, rgb: transform(observed.black) },
+    { cell: CELL.WHITE, rgb: transform(observed.white) },
+    { cell: CELL.RED, rgb: transform(observed.red) },
+    { cell: CELL.GREEN, rgb: transform(observed.green) },
+    { cell: CELL.BLUE, rgb: transform(observed.blue) }
   ];
+  const colored = entries.filter(({ cell }) => cell === CELL.RED || cell === CELL.GREEN || cell === CELL.BLUE);
+  const chroma = (rgb) => Math.max(rgb.r, rgb.g, rgb.b) - Math.min(rgb.r, rgb.g, rgb.b);
+  const minimumColorChroma = Math.min(...colored.map(({ rgb }) => chroma(rgb)));
+  return {
+    entries,
+    transform,
+    mode,
+    dataMode: mode === "hue" ? "hue" : "distance",
+    whiteChroma: chroma(entries.find(({ cell }) => cell === CELL.WHITE).rgb),
+    minimumColorChroma
+  };
 }
 
 function colorDistanceSq(a, b) {
@@ -3261,12 +3847,13 @@ function colorDistanceSq(a, b) {
 }
 
 function classifyRgb(rgb, classifier) {
+  const transformed = classifier.transform(rgb);
   let best = null;
   let bestDistanceSq = Infinity;
   let secondDistanceSq = Infinity;
 
-  for (const candidate of classifier) {
-    const distanceSq = colorDistanceSq(rgb, candidate.rgb);
+  for (const candidate of classifier.entries) {
+    const distanceSq = colorDistanceSq(transformed, candidate.rgb);
     if (distanceSq < bestDistanceSq) {
       secondDistanceSq = bestDistanceSq;
       bestDistanceSq = distanceSq;
@@ -3278,17 +3865,47 @@ function classifyRgb(rgb, classifier) {
 
   const distance = Math.sqrt(bestDistanceSq);
   const secondDistance = Number.isFinite(secondDistanceSq) ? Math.sqrt(secondDistanceSq) : distance + 1;
-  // Confidence is the normalized separation between the nearest and second
-  // nearest calibrated palette states. 1 means unambiguous, 0 means tied.
   const confidence = Math.max(0, Math.min(1, (secondDistance - distance) / Math.max(secondDistance, 1e-6)));
   return { cell: best.cell, distance, confidence };
 }
 
+
+function classifyDataHue(rgb, classifier) {
+  const transformed = classifier.transform(rgb);
+  const channels = [
+    { cell: CELL.RED, value: transformed.r },
+    { cell: CELL.GREEN, value: transformed.g },
+    { cell: CELL.BLUE, value: transformed.b }
+  ].sort((a, b) => b.value - a.value);
+  const maxValue = channels[0].value;
+  const secondValue = channels[1].value;
+  const minValue = channels[2].value;
+  const chroma = maxValue - minValue;
+  const whiteThreshold = Math.max(18, Math.min(58, classifier.minimumColorChroma * 0.34));
+
+  if (chroma <= whiteThreshold) {
+    const confidence = clampNumber((whiteThreshold - chroma) / Math.max(whiteThreshold, 1), 0, 1);
+    return { cell: CELL.WHITE, distance: chroma, confidence: 0.35 + confidence * 0.65 };
+  }
+
+  const margin = maxValue - secondValue;
+  const hueConfidence = clampNumber(margin / Math.max(chroma, 1), 0, 1);
+  const saturationConfidence = clampNumber((chroma - whiteThreshold) / Math.max(classifier.minimumColorChroma - whiteThreshold, 1), 0, 1);
+  return {
+    cell: channels[0].cell,
+    distance: Math.max(0, classifier.minimumColorChroma - chroma),
+    confidence: clampNumber(0.18 + hueConfidence * 0.52 + saturationConfidence * 0.30, 0, 1)
+  };
+}
+
 function classifySampledRgbGrid(rgbGrid, classifier, layout = null) {
   const size = rgbGrid.length;
   const matrix = make2D(size, CELL.WHITE);
   const confidence = make2D(size, 1);
-  const dataClassifier = classifier.filter(({ cell }) => cell !== CELL.BLACK);
+  const dataClassifier = {
+    ...classifier,
+    entries: classifier.entries.filter(({ cell }) => cell !== CELL.BLACK)
+  };
   let distanceSum = 0;
   let confidenceSum = 0;
   let minimumConfidence = 1;
@@ -3299,8 +3916,11 @@ function classifySampledRgbGrid(rgbGrid, classifier, layout = null) {
       // Black is structural only. Restricting data modules to RGBW keeps a
       // shadowed/blurred data sample representable so confidence-aware ECC can
       // promote it to an erasure instead of aborting before RS gets a chance.
-      const candidates = layout && !layout.reserved[r][c] ? dataClassifier : classifier;
-      const classified = classifyRgb(rgbGrid[r][c], candidates);
+      const isDataCell = layout && !layout.reserved[r][c];
+      const candidates = isDataCell ? dataClassifier : classifier;
+      const classified = isDataCell && classifier.dataMode === "hue"
+        ? classifyDataHue(rgbGrid[r][c], classifier)
+        : classifyRgb(rgbGrid[r][c], candidates);
       matrix[r][c] = classified.cell;
       confidence[r][c] = classified.confidence;
       distanceSum += classified.distance;
@@ -3319,46 +3939,353 @@ function classifySampledRgbGrid(rgbGrid, classifier, layout = null) {
   };
 }
 
+function structuralAccuracy(matrix, layout) {
+  let matches = 0;
+  let total = 0;
+  for (let r = 0; r < layout.size; r++) {
+    for (let c = 0; c < layout.size; c++) {
+      if (!layout.reserved[r][c]) continue;
+      total++;
+      if (matrix[r][c] === layout.matrix[r][c]) matches++;
+    }
+  }
+  return total ? matches / total : 0;
+}
+
+function pushObservation(options, observation) {
+  if (!Array.isArray(options._observationCollector)) return;
+  options._observationCollector.push(observation);
+}
+
+function paletteClassifierAttempts(observedPalette) {
+  return [
+    { classifier: classifierFromPaletteRgb(observedPalette, "raw"), colorNormalization: "observed-rgb" },
+    { classifier: classifierFromPaletteRgb(observedPalette, "balanced"), colorNormalization: "white-balanced" },
+    { 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
+    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,
+    diagnostics: options._visionDiagnostics,
+    diagnosticLabel: options._diagnosticLabel ?? "normal"
   });
+  if (Array.isArray(options._geometryCollector)) options._geometryCollector.push(...geometryCandidates);
   const results = [];
 
   for (const geometry of geometryCandidates) {
-    try {
-      const layout = createLayout(geometry.version);
-      const sampled = samplePerspectiveMatrix(imageData, geometry.homography, layout.size, {
-        sampleRadius: options.sampleRadius ?? 0.16
-      });
-      const observedPalette = sampleObservedPalette(sampled.rgbGrid, layout.calibration);
-      const classifier = classifierFromPaletteRgb(observedPalette);
-      const classified = classifySampledRgbGrid(sampled.rgbGrid, classifier, layout);
-      const decoded = decodeMatrix(classified.matrix, {
-        structureTolerance: options.structureTolerance ?? 0.18,
-        cellConfidence: classified.confidence,
-        maxErasureConfidence: options.maxErasureConfidence
+    const layout = createLayout(geometry.version);
+    const sampleProfiles = [{
+      sampleMode: options.sampleMode ?? "cross",
+      sampleRadius: options.sampleRadius ?? 0.16,
+      robustCalibration: false
+    }];
+    if (options.adaptiveSampling !== false) {
+      sampleProfiles.push({
+        sampleMode: "median",
+        sampleRadius: options.robustSampleRadius ?? 0.12,
+        robustCalibration: true
       });
-      if (decoded.version !== geometry.version) continue;
+    }
 
-      results.push({
-        ...decoded,
-        perspectiveCorrected: true,
-        colorCalibrated: true,
-        geometry,
-        observedPalette,
-        averageColorDistance: classified.averageColorDistance,
-        averageCellConfidence: classified.averageCellConfidence,
-        minimumCellConfidence: classified.minimumCellConfidence,
-        lowConfidenceCells: classified.lowConfidenceCells,
-        rectified: options.includeRectified
-          ? rectifyImageData(imageData, geometry.homography, layout.size, options.rectifiedModuleSize ?? 8)
-          : undefined
-      });
-    } catch {
-      // Continue trying geometry hypotheses.
+    let geometryDecoded = false;
+    let bestStructureScore = 0;
+    for (const profile of sampleProfiles) {
+      let sampled;
+      let observedPalette;
+      try {
+        sampled = samplePerspectiveMatrix(imageData, geometry.homography, layout.size, profile);
+        observedPalette = sampleObservedPalette(sampled.rgbGrid, layout.calibration, {
+          robust: profile.robustCalibration
+        });
+      } catch {
+        continue;
+      }
+
+      const tryAttempt = (attempt, rgbGrid, metadata = {}) => {
+        const activeObservedPalette = metadata.observedPalette ?? observedPalette;
+        const activeSamplingMode = metadata.samplingMode ?? profile.sampleMode;
+        const classified = classifySampledRgbGrid(rgbGrid, attempt.classifier, layout);
+        const structureScore = structuralAccuracy(classified.matrix, layout);
+        bestStructureScore = Math.max(bestStructureScore, structureScore);
+        pushObservation(options, {
+          version: geometry.version,
+          matrix: classified.matrix,
+          confidence: classified.confidence,
+          geometry,
+          observedPalette: activeObservedPalette,
+          samplingMode: activeSamplingMode,
+          colorNormalization: attempt.colorNormalization,
+          structureScore,
+          averageCellConfidence: classified.averageCellConfidence,
+          lowConfidenceCells: classified.lowConfidenceCells
+        });
+
+        try {
+          const decoded = decodeMatrix(classified.matrix, {
+            structureTolerance: options.structureTolerance ?? 0.18,
+            cellConfidence: classified.confidence,
+            maxErasureConfidence: options.maxErasureConfidence
+          });
+          if (decoded.version !== geometry.version) return false;
+
+          results.push({
+            ...decoded,
+            perspectiveCorrected: true,
+            colorCalibrated: true,
+            colorNormalization: attempt.colorNormalization,
+            samplingMode: activeSamplingMode,
+            geometry,
+            observedPalette: activeObservedPalette,
+            autoEnhanced: metadata.autoEnhanced || undefined,
+            recoveryMode: metadata.recoveryMode,
+            averageColorDistance: classified.averageColorDistance,
+            averageCellConfidence: classified.averageCellConfidence,
+            minimumCellConfidence: classified.minimumCellConfidence,
+            lowConfidenceCells: classified.lowConfidenceCells,
+            rectified: options.includeRectified
+              ? rectifyImageData(imageData, geometry.homography, layout.size, options.rectifiedModuleSize ?? 8)
+              : undefined
+          });
+          return true;
+        } catch {
+          return false;
+        }
+      };
+
+      // 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)) {
+          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({
+            classifier: classifierFromPaletteRgb(normalizedPalette, "raw"),
+            colorNormalization: "spatial-white-balanced"
+          }, normalizedGrid);
+        } 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).
+      if (!geometryDecoded && options.autoEnhanceRecovery !== false) {
+        try {
+          const enhancedGrid = autoToneContrastColorRgbGrid(sampled.rgbGrid, {
+            blackClip: options.autoEnhanceBlackClip,
+            whiteClip: options.autoEnhanceWhiteClip,
+            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}`
+            };
+            if (tryAttempt(recoveredAttempt, enhancedGrid, {
+              observedPalette: enhancedPalette,
+              autoEnhanced: true,
+              recoveryMode: "module-grid-auto-tone-contrast-color"
+            })) {
+              geometryDecoded = true;
+              break;
+            }
+          }
+        } catch {
+          // Continue to the QR-region pixel recovery below.
+        }
+      }
+
+      // Camera-specific Photoshop-style 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 /
+      // Contrast / Color there at pixel level, then sample modules again. This
+      // closely matches what happens when the QR itself is corrected in an
+      // editor before photographing it, while staying off the clean fast path.
+      if (
+        !geometryDecoded &&
+        profile === sampleProfiles[sampleProfiles.length - 1] &&
+        options.autoEnhanceRecovery !== false &&
+        options.rectifiedAutoEnhanceRecovery !== false
+      ) {
+        try {
+          const recoveryModuleSize = Math.max(4, Math.min(10, Math.round(options.rectifiedRecoveryModuleSize ?? 6)));
+          const rectifiedRegion = rectifyImageData(
+            imageData,
+            geometry.homography,
+            layout.size,
+            recoveryModuleSize
+          );
+          const enhancedRegion = autoToneContrastColorImageData(rectifiedRegion, {
+            blackClip: options.rectifiedAutoEnhanceBlackClip ?? options.autoEnhanceBlackClip ?? 0.008,
+            whiteClip: options.rectifiedAutoEnhanceWhiteClip ?? options.autoEnhanceWhiteClip ?? 0.006,
+            saturation: options.rectifiedAutoEnhanceSaturation ?? options.autoEnhanceSaturation ?? 1.22,
+            highlightFraction: options.rectifiedAutoEnhanceHighlightFraction ?? 0.16,
+            targetSamples: Math.min(120000, rectifiedRegion.width * rectifiedRegion.height)
+          });
+          const enhancedSampled = sampleAxisAlignedGrid(
+            enhancedRegion,
+            { x: 0, y: 0, width: enhancedRegion.width, height: enhancedRegion.height },
+            layout.size,
+            options.rectifiedRecoveryRadiusRatio ?? 0.16
+          );
+          const enhancedPalette = sampleObservedPalette(
+            enhancedSampled.rgbGrid,
+            layout.calibration,
+            { robust: true }
+          );
+          for (const attempt of paletteClassifierAttempts(enhancedPalette)) {
+            const recoveredAttempt = {
+              ...attempt,
+              colorNormalization: `rectified-auto-tone-contrast-color/${attempt.colorNormalization}`
+            };
+            if (tryAttempt(recoveredAttempt, enhancedSampled.rgbGrid, {
+              observedPalette: enhancedPalette,
+              samplingMode: "rectified-auto-enhance",
+              autoEnhanced: true,
+              recoveryMode: "rectified-auto-tone-contrast-color"
+            })) {
+              geometryDecoded = true;
+              break;
+            }
+          }
+        } catch {
+          // Geometry refinement remains available as the final bounded fallback.
+        }
+      }
+
+      if (geometryDecoded) break;
+    }
+
+    // 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.
+    // On a strong-but-undecodable symbol, probe a tiny 3x3 offset neighbourhood
+    // using centre-only samples and attempt decoding from the best candidates.
+    if (
+      !geometryDecoded &&
+      options.geometryRefinement !== false &&
+      bestStructureScore >= (options.refinementStructureThreshold ?? 0.90)
+    ) {
+      const step = clampNumber(options.refinementOffset ?? 0.20, 0.05, 0.35);
+      const refinementOffsets = [
+        [step, 0], [-step, 0], [0, -step], [0, step],
+        [step, -step], [step, step], [-step, -step], [-step, step]
+      ];
+      const refinementCandidates = [];
+
+      for (const [offsetX, offsetY] of refinementOffsets) {
+        let sampled;
+        let observedPalette;
+        try {
+          sampled = samplePerspectiveMatrix(imageData, geometry.homography, layout.size, {
+            sampleMode: "cross",
+            sampleRadius: 0,
+            sampleOffsetX: offsetX,
+            sampleOffsetY: offsetY
+          });
+          observedPalette = sampleObservedPalette(sampled.rgbGrid, layout.calibration, { robust: true });
+        } catch {
+          continue;
+        }
+
+        // Raw observed-palette classification is deliberately first here too.
+        // It is cheap, and it handles the common case where blur biased the
+        // geometry slightly but the camera colors themselves remain usable.
+        const attempts = paletteClassifierAttempts(observedPalette);
+        for (const attempt of attempts) {
+          const classified = classifySampledRgbGrid(sampled.rgbGrid, attempt.classifier, layout);
+          const structureScore = structuralAccuracy(classified.matrix, layout);
+          bestStructureScore = Math.max(bestStructureScore, structureScore);
+          pushObservation(options, {
+            version: geometry.version,
+            matrix: classified.matrix,
+            confidence: classified.confidence,
+            geometry,
+            observedPalette,
+            samplingMode: "refined-center",
+            samplingOffset: { x: offsetX, y: offsetY },
+            colorNormalization: attempt.colorNormalization,
+            structureScore,
+            averageCellConfidence: classified.averageCellConfidence,
+            lowConfidenceCells: classified.lowConfidenceCells
+          });
+
+          // Do not spend RS work on a refinement that made the known finder /
+          // alignment structure worse. This keeps the recovery path bounded.
+          if (structureScore < (options.refinementDecodeThreshold ?? 0.95)) continue;
+          refinementCandidates.push({
+            attempt,
+            classified,
+            observedPalette,
+            offsetX,
+            offsetY,
+            structureScore
+          });
+        }
+      }
+
+      refinementCandidates.sort((a, b) =>
+        (b.structureScore - a.structureScore) ||
+        (b.classified.averageCellConfidence - a.classified.averageCellConfidence) ||
+        (a.classified.averageColorDistance - b.classified.averageColorDistance)
+      );
+
+      const decodeLimit = Math.max(1, Math.min(8, Math.round(options.refinementDecodeCandidates ?? 4)));
+      for (const candidate of refinementCandidates.slice(0, decodeLimit)) {
+        try {
+          const decoded = decodeMatrix(candidate.classified.matrix, {
+            structureTolerance: options.structureTolerance ?? 0.18,
+            cellConfidence: candidate.classified.confidence,
+            maxErasureConfidence: options.maxErasureConfidence
+          });
+          if (decoded.version !== geometry.version) continue;
+          results.push({
+            ...decoded,
+            perspectiveCorrected: true,
+            geometryRefined: true,
+            samplingOffset: { x: candidate.offsetX, y: candidate.offsetY },
+            colorCalibrated: true,
+            colorNormalization: candidate.attempt.colorNormalization,
+            samplingMode: "refined-center",
+            geometry,
+            observedPalette: candidate.observedPalette,
+            averageColorDistance: candidate.classified.averageColorDistance,
+            averageCellConfidence: candidate.classified.averageCellConfidence,
+            minimumCellConfidence: candidate.classified.minimumCellConfidence,
+            lowConfidenceCells: candidate.classified.lowConfidenceCells,
+            rectified: options.includeRectified
+              ? rectifyImageData(imageData, geometry.homography, layout.size, options.rectifiedModuleSize ?? 8)
+              : undefined
+          });
+          geometryDecoded = true;
+          break;
+        } catch {
+          // Try the next high-scoring micro-refinement.
+        }
+      }
     }
   }
 
@@ -3372,7 +4299,7 @@ function tryPerspectiveScan(imageData, options) {
 
 function tryAxisAlignedScan(imageData, options) {
   const bounds = options.bounds ?? findActiveBounds(imageData, options.whiteThreshold ?? 238);
-  const fixedClassifier = classifierFromPaletteRgb(paletteRgb(options.palette));
+  const fixedPalette = paletteRgb(options.palette);
   const minVersion = options.minVersion ?? MIN_VERSION;
   const maxVersion = options.maxVersion ?? MAX_VERSION;
   const candidates = [];
@@ -3385,49 +4312,95 @@ function tryAxisAlignedScan(imageData, options) {
     const aspectError = Math.abs(moduleW - moduleH) / Math.max(moduleW, moduleH);
     if (aspectError > (options.maxModuleAspectError ?? 0.16)) continue;
 
-    try {
-      const sampled = sampleAxisAlignedGrid(imageData, bounds, size, options.sampleRadius ?? 0.18);
-      const classifierAttempts = [];
-      const layout = createLayout(version);
-      try {
-        const observedPalette = sampleObservedPalette(sampled.rgbGrid, layout.calibration);
-        classifierAttempts.push({ classifier: classifierFromPaletteRgb(observedPalette), calibrated: true });
-      } catch {
-        // Fixed palette fallback below.
-      }
-      classifierAttempts.push({ classifier: fixedClassifier, calibrated: false });
+    const radiusProfiles = [options.sampleRadius ?? 0.18];
+    if (options.adaptiveSampling !== false) radiusProfiles.push(options.robustSampleRadius ?? 0.10);
+    let accepted = false;
 
-      let accepted = false;
-      for (const attempt of classifierAttempts) {
+    for (let profileIndex = 0; profileIndex < radiusProfiles.length && !accepted; profileIndex++) {
+      try {
+        const sampled = sampleAxisAlignedGrid(imageData, bounds, size, radiusProfiles[profileIndex]);
+        const layout = createLayout(version);
+        const classifierAttempts = [];
         try {
-          const classified = classifySampledRgbGrid(sampled.rgbGrid, attempt.classifier, layout);
-          const decoded = decodeMatrix(classified.matrix, {
-            structureTolerance: options.structureTolerance ?? 0.12,
-            cellConfidence: classified.confidence,
-            maxErasureConfidence: options.maxErasureConfidence
-          });
-          candidates.push({
-            ...decoded,
-            bounds,
-            sampledVersion: version,
-            moduleWidth: moduleW,
-            moduleHeight: moduleH,
-            perspectiveCorrected: false,
-            colorCalibrated: attempt.calibrated,
-            averageColorDistance: classified.averageColorDistance,
-            averageCellConfidence: classified.averageCellConfidence,
-            minimumCellConfidence: classified.minimumCellConfidence,
-            lowConfidenceCells: classified.lowConfidenceCells
+          const observedPalette = sampleObservedPalette(sampled.rgbGrid, layout.calibration, {
+            robust: profileIndex > 0
           });
-          accepted = true;
-          break;
+          classifierAttempts.push(...paletteClassifierAttempts(observedPalette).map((attempt) => ({
+            ...attempt,
+            calibrated: true,
+            observedPalette,
+            rgbGrid: sampled.rgbGrid
+          })));
+          if (options.spatialColorNormalization !== false) {
+            try {
+              const normalizedGrid = spatiallyNormalizeRgbGrid(sampled.rgbGrid, layout.calibration);
+              const normalizedPalette = sampleObservedPalette(normalizedGrid, layout.calibration, { robust: true });
+              classifierAttempts.push({
+                classifier: classifierFromPaletteRgb(normalizedPalette, "raw"),
+                calibrated: true,
+                colorNormalization: "spatial-white-balanced",
+                observedPalette,
+                rgbGrid: normalizedGrid
+              });
+            } catch {
+              // Continue with global calibration/fixed palette.
+            }
+          }
         } catch {
-          // Try next classifier.
+          // Fixed palette fallback below.
+        }
+        classifierAttempts.push({
+          classifier: classifierFromPaletteRgb(fixedPalette, "raw"),
+          calibrated: false,
+          colorNormalization: "fixed-rgb",
+          observedPalette: fixedPalette,
+          rgbGrid: sampled.rgbGrid
+        });
+
+        for (const attempt of classifierAttempts) {
+          try {
+            const classified = classifySampledRgbGrid(attempt.rgbGrid ?? sampled.rgbGrid, attempt.classifier, layout);
+            const structureScore = structuralAccuracy(classified.matrix, layout);
+            pushObservation(options, {
+              version,
+              matrix: classified.matrix,
+              confidence: classified.confidence,
+              bounds,
+              samplingMode: profileIndex === 0 ? "axis" : "axis-center",
+              colorNormalization: attempt.colorNormalization,
+              structureScore,
+              averageCellConfidence: classified.averageCellConfidence,
+              lowConfidenceCells: classified.lowConfidenceCells
+            });
+            const decoded = decodeMatrix(classified.matrix, {
+              structureTolerance: options.structureTolerance ?? 0.12,
+              cellConfidence: classified.confidence,
+              maxErasureConfidence: options.maxErasureConfidence
+            });
+            candidates.push({
+              ...decoded,
+              bounds,
+              sampledVersion: version,
+              moduleWidth: moduleW,
+              moduleHeight: moduleH,
+              perspectiveCorrected: false,
+              colorCalibrated: attempt.calibrated,
+              colorNormalization: attempt.colorNormalization,
+              samplingMode: profileIndex === 0 ? "axis" : "axis-center",
+              averageColorDistance: classified.averageColorDistance,
+              averageCellConfidence: classified.averageCellConfidence,
+              minimumCellConfidence: classified.minimumCellConfidence,
+              lowConfidenceCells: classified.lowConfidenceCells
+            });
+            accepted = true;
+            break;
+          } catch {
+            // Try next classifier/profile.
+          }
         }
+      } catch {
+        // Try a narrower centre sample, then next version.
       }
-      if (!accepted) throw new Error("Axis-aligned candidate did not decode.");
-    } catch {
-      // Try next version.
     }
   }
 
@@ -3444,16 +4417,90 @@ function scanImageData(imageData, options = {}) {
   validateVersion(minVersion);
   validateVersion(maxVersion);
 
+  const geometryCollector = [];
+  const scanOptions = { ...options, _geometryCollector: geometryCollector };
+
   if (options.perspective !== false) {
-    const perspective = tryPerspectiveScan(imageData, options);
+    const perspective = tryPerspectiveScan(imageData, scanOptions);
     if (perspective) return perspective;
   }
 
+  // If the normal scanner could see QuadQR geometry but could not decode the
+  // colors, retry the same frame after a single global Auto Tone / Contrast /
+  // Color-style pass. This is deliberately after the normal path so clean
+  // camera scanning remains unchanged and fast.
+  if (
+    options.autoEnhanceRecovery !== false &&
+    options.fullFrameAutoEnhanceRecovery !== false &&
+    !options._autoEnhancedRecovery &&
+    geometryCollector.length > 0
+  ) {
+    try {
+      const enhanced = autoToneContrastColorImageData(imageData, {
+        blackClip: options.autoEnhanceBlackClip,
+        whiteClip: options.autoEnhanceWhiteClip,
+        saturation: options.autoEnhanceSaturation,
+        targetSamples: options.autoEnhanceTargetSamples
+      });
+      const recovered = tryPerspectiveScan(enhanced, {
+        ...options,
+        _autoEnhancedRecovery: true,
+        autoEnhanceRecovery: false,
+        _geometryCollector: []
+      });
+      if (recovered) {
+        return {
+          ...recovered,
+          autoEnhanced: true,
+          recoveryMode: "auto-tone-contrast-color",
+          originalColorNormalization: recovered.colorNormalization
+        };
+      }
+    } catch {
+      // Continue to the axis-aligned fallback.
+    }
+  }
+
   if (options.axisAlignedFallback !== false) {
-    const axis = tryAxisAlignedScan(imageData, options);
+    const axis = tryAxisAlignedScan(imageData, scanOptions);
     if (axis) return axis;
   }
 
+  // Static images sometimes have such low contrast that locator detection itself
+  // fails. Permit one enhanced full retry in that case. The live camera disables
+  // this on its first pass so an empty frame never becomes expensive.
+  if (
+    options.autoEnhanceRecovery !== false &&
+    !options._autoEnhancedRecovery &&
+    geometryCollector.length === 0 &&
+    options.autoEnhanceWhenNoGeometry !== false
+  ) {
+    try {
+      const enhanced = autoToneContrastColorImageData(imageData, {
+        blackClip: options.autoEnhanceBlackClip,
+        whiteClip: options.autoEnhanceWhiteClip,
+        saturation: options.autoEnhanceSaturation,
+        targetSamples: options.autoEnhanceTargetSamples
+      });
+      const recoveryOptions = {
+        ...options,
+        _autoEnhancedRecovery: true,
+        autoEnhanceRecovery: false,
+        _geometryCollector: []
+      };
+      if (options.perspective !== false) {
+        const perspective = tryPerspectiveScan(enhanced, recoveryOptions);
+        if (perspective) return { ...perspective, autoEnhanced: true, recoveryMode: "auto-tone-contrast-color" };
+      }
+      if (options.axisAlignedFallback !== false) {
+        const axis = tryAxisAlignedScan(enhanced, recoveryOptions);
+        if (axis) return { ...axis, autoEnhanced: true, recoveryMode: "auto-tone-contrast-color" };
+      }
+    } catch {
+      // Fall through to the normal scan failure below.
+    }
+  }
+
   throw new Error(
     "No valid QuadQR code found. Try better lighting, fill more of the frame, keep all locator patterns visible, or use a less blurred image."
   );
@@ -3485,19 +4532,274 @@ async function scanFile(file, options = {}) {
   return scanImageData(ctx.getImageData(0, 0, canvas.width, canvas.height), options);
 }
 
+function parseObjectPositionFraction(value, fallback = 0.5) {
+  if (typeof value !== "string") return fallback;
+  const token = value.trim().toLowerCase();
+  if (token === "left" || token === "top") return 0;
+  if (token === "right" || token === "bottom") return 1;
+  if (token === "center") return 0.5;
+  if (token.endsWith("%")) {
+    const parsed = Number.parseFloat(token);
+    if (Number.isFinite(parsed)) return clampNumber(parsed / 100, 0, 1);
+  }
+  return fallback;
+}
+
+function visibleVideoSourceRect(video, options = {}) {
+  const sourceWidth = video.videoWidth;
+  const sourceHeight = video.videoHeight;
+  const full = { x: 0, y: 0, width: sourceWidth, height: sourceHeight, cropped: false };
+  if (options.videoCropMode === "full") return full;
+
+  let boxWidth = Number(video.clientWidth) || 0;
+  let boxHeight = Number(video.clientHeight) || 0;
+  if ((!boxWidth || !boxHeight) && typeof video.getBoundingClientRect === "function") {
+    const rect = video.getBoundingClientRect();
+    boxWidth = boxWidth || rect.width;
+    boxHeight = boxHeight || rect.height;
+  }
+  if (!boxWidth || !boxHeight) return full;
+
+  let objectFit = options.videoObjectFit;
+  let objectPosition = options.videoObjectPosition;
+  if ((!objectFit || !objectPosition) && typeof getComputedStyle === "function") {
+    try {
+      const style = getComputedStyle(video);
+      objectFit = objectFit || style.objectFit;
+      objectPosition = objectPosition || style.objectPosition;
+    } catch {
+      // Fall back to the demo's normal cover/center behavior.
+    }
+  }
+  objectFit = objectFit || "cover";
+  if (objectFit !== "cover") return full;
+
+  const scale = Math.max(boxWidth / sourceWidth, boxHeight / sourceHeight);
+  if (!Number.isFinite(scale) || scale <= 0) return full;
+  let cropWidth = Math.min(sourceWidth, boxWidth / scale);
+  let cropHeight = Math.min(sourceHeight, boxHeight / scale);
+  if (cropWidth >= sourceWidth - 1 && cropHeight >= sourceHeight - 1) return full;
+
+  const positionTokens = String(objectPosition || "50% 50%").trim().split(/\s+/);
+  const positionX = parseObjectPositionFraction(positionTokens[0], 0.5);
+  const positionY = parseObjectPositionFraction(positionTokens[1] ?? positionTokens[0], 0.5);
+  let x = (sourceWidth - cropWidth) * positionX;
+  let y = (sourceHeight - cropHeight) * positionY;
+
+  // Optional tiny inset removes the soft edge of a camera preview without
+  // changing the visible composition. Leave at zero unless explicitly set.
+  const inset = clampNumber(options.videoCropInset ?? 0, 0, 0.18);
+  if (inset > 0) {
+    const dx = cropWidth * inset;
+    const dy = cropHeight * inset;
+    x += dx;
+    y += dy;
+    cropWidth -= dx * 2;
+    cropHeight -= dy * 2;
+  }
+
+  x = clampNumber(x, 0, Math.max(0, sourceWidth - cropWidth));
+  y = clampNumber(y, 0, Math.max(0, sourceHeight - cropHeight));
+  return { x, y, width: cropWidth, height: cropHeight, cropped: true };
+}
+
+function cropImageDataInset(imageData, insetFraction = 0) {
+  const inset = clampNumber(Number(insetFraction) || 0, 0, 0.32);
+  if (inset <= 0) {
+    return {
+      imageData,
+      rect: { x: 0, y: 0, width: imageData.width, height: imageData.height }
+    };
+  }
+
+  const x = Math.max(0, Math.floor(imageData.width * inset));
+  const y = Math.max(0, Math.floor(imageData.height * inset));
+  const width = Math.max(1, imageData.width - x * 2);
+  const height = Math.max(1, imageData.height - y * 2);
+  const data = new Uint8ClampedArray(width * height * 4);
+  for (let row = 0; row < height; row++) {
+    const sourceStart = ((y + row) * imageData.width + x) * 4;
+    const sourceEnd = sourceStart + width * 4;
+    data.set(imageData.data.subarray(sourceStart, sourceEnd), row * width * 4);
+  }
+  return {
+    imageData: { width, height, data },
+    rect: { x, y, width, height }
+  };
+}
+
+function bestVisionDiagnosticPass(visionDiagnostics) {
+  const passes = visionDiagnostics?.passes;
+  if (!Array.isArray(passes) || !passes.length) return null;
+  return passes.slice().sort((a, b) => {
+    const aGeometry = a.geometries?.[0];
+    const bGeometry = b.geometries?.[0];
+    return (Boolean(bGeometry) - Boolean(aGeometry)) ||
+      ((b.finderCount ?? 0) - (a.finderCount ?? 0)) ||
+      ((bGeometry?.score ?? 0) - (aGeometry?.score ?? 0));
+  })[0];
+}
+
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
+function normalizeFrameDiagnostics(frameDiagnostics, source, width, height, visionDiagnostics) {
+  if (!frameDiagnostics || typeof frameDiagnostics !== "object") return;
+  frameDiagnostics.scanWidth = width;
+  frameDiagnostics.scanHeight = height;
+  frameDiagnostics.frameWidth = width;
+  frameDiagnostics.frameHeight = height;
+  frameDiagnostics.scanRect = { x: 0, y: 0, width, height };
+  frameDiagnostics.sourceRect = {
+    x: source.x,
+    y: source.y,
+    width: source.width,
+    height: source.height,
+    cropped: Boolean(source.cropped)
+  };
+  frameDiagnostics.vision = visionDiagnostics;
+  const bestPass = bestVisionDiagnosticPass(visionDiagnostics);
+  frameDiagnostics.bestPass = bestPass;
+  frameDiagnostics.finderCount = bestPass?.finderCount ?? 0;
+  frameDiagnostics.finders = bestPass?.finders ?? [];
+  frameDiagnostics.finderMethod = bestPass?.finderMethod ?? null;
+  frameDiagnostics.finderPasses = Array.isArray(visionDiagnostics?.passes)
+    ? visionDiagnostics.passes.map((pass) => ({
+        method: pass.finderMethod ?? pass.label,
+        finderCount: pass.finderCount ?? 0,
+        threshold: pass.threshold,
+        geometryCount: pass.geometries?.length ?? 0
+      }))
+    : [];
+  frameDiagnostics.geometry = bestPass?.geometries?.[0] ?? null;
+}
+
 function scanVideoFrame(video, options = {}) {
   assert(typeof document !== "undefined", "scanVideoFrame is a browser API.");
   assert(video && video.videoWidth && video.videoHeight, "Video frame is not ready.");
+
+  // Scan what the user actually sees. On phones the video element is usually a
+  // portrait box with object-fit: cover while the camera sensor stream is 16:9.
+  // Previously we scanned the entire hidden sensor frame, so the QR looked big
+  // in the guide but became much smaller after canvas downscaling. Cropping to
+  // the visible source region both improves module resolution and reduces work.
+  const source = visibleVideoSourceRect(video, options);
   const maxDimension = options.maxDimension ?? 960;
-  const scale = Math.min(1, maxDimension / Math.max(video.videoWidth, video.videoHeight));
-  const width = Math.max(1, Math.round(video.videoWidth * scale));
-  const height = Math.max(1, Math.round(video.videoHeight * scale));
+  const scale = Math.min(1, maxDimension / Math.max(source.width, source.height));
+  const width = Math.max(1, Math.round(source.width * scale));
+  const height = Math.max(1, Math.round(source.height * scale));
   const canvas = options.canvas ?? document.createElement("canvas");
   canvas.width = width;
   canvas.height = height;
   const ctx = canvas.getContext("2d", { alpha: false, willReadFrequently: true });
-  ctx.drawImage(video, 0, 0, width, height);
-  return scanImageData(ctx.getImageData(0, 0, width, height), options);
+  // High-quality downscaling is preferable for finder geometry, but visible-ROI
+  // cropping means many mobile frames now need little or no downscaling at all.
+  if ("imageSmoothingEnabled" in ctx) ctx.imageSmoothingEnabled = true;
+  if ("imageSmoothingQuality" in ctx) ctx.imageSmoothingQuality = "high";
+  ctx.drawImage(video, source.x, source.y, source.width, source.height, 0, 0, width, height);
+  const frameImageData = ctx.getImageData(0, 0, width, height);
+  if (options._capturedFrame && typeof options._capturedFrame === "object") {
+    options._capturedFrame.imageData = frameImageData;
+    options._capturedFrame.scanWidth = width;
+    options._capturedFrame.scanHeight = height;
+    options._capturedFrame.source = { ...source };
+  }
+  const visionDiagnostics = options._frameDiagnostics ? { passes: [] } : null;
+  try {
+    const result = scanImageData(frameImageData, {
+      ...options,
+      _visionDiagnostics: visionDiagnostics
+    });
+    normalizeFrameDiagnostics(options._frameDiagnostics, source, width, height, visionDiagnostics);
+    if (!source.cropped) return result;
+    return {
+      ...result,
+      cameraVisibleCrop: true,
+      cameraSourceRect: { x: source.x, y: source.y, width: source.width, height: source.height }
+    };
+  } catch (error) {
+    normalizeFrameDiagnostics(options._frameDiagnostics, source, width, height, visionDiagnostics);
+    throw error;
+  }
+}
+
+function selectBestFrameObservation(observations) {
+  if (!observations?.length) return null;
+  return observations
+    .filter((item) => item?.matrix && item.structureScore >= 0.82)
+    .sort((a, b) =>
+      (b.structureScore - a.structureScore) ||
+      (b.averageCellConfidence - a.averageCellConfidence) ||
+      ((b.geometry?.score ?? 0) - (a.geometry?.score ?? 0))
+    )[0] ?? null;
+}
+
+function combineFrameObservations(observations) {
+  if (!observations?.length) return null;
+  const version = observations[0].version;
+  const size = observations[0].matrix.length;
+  if (!observations.every((item) => item.version === version && item.matrix.length === size)) return null;
+
+  const matrix = make2D(size, CELL.WHITE);
+  const confidence = make2D(size, 0);
+  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) {
+        const cell = observation.matrix[r][c];
+        const sourceConfidence = clampNumber(observation.confidence?.[r]?.[c] ?? 0.5, 0, 1);
+        const weight = 0.35 + sourceConfidence * 0.65;
+        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);
+      }
+
+      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 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;
+
+      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);
+    }
+  }
+  return { version, matrix, confidence };
+}
+
+async function improveCameraTrack(stream) {
+  const track = stream.getVideoTracks?.()[0];
+  if (!track?.applyConstraints || !track.getCapabilities) return;
+  try {
+    const capabilities = track.getCapabilities();
+    const advanced = {};
+    if (Array.isArray(capabilities.focusMode) && capabilities.focusMode.includes("continuous")) {
+      advanced.focusMode = "continuous";
+    }
+    if (Array.isArray(capabilities.exposureMode) && capabilities.exposureMode.includes("continuous")) {
+      advanced.exposureMode = "continuous";
+    }
+    if (Array.isArray(capabilities.whiteBalanceMode) && capabilities.whiteBalanceMode.includes("continuous")) {
+      advanced.whiteBalanceMode = "continuous";
+    }
+    if (Object.keys(advanced).length) await track.applyConstraints({ advanced: [advanced] });
+  } catch {
+    // Browsers expose different subsets of camera controls. Scanner-side
+    // calibration remains the primary path when these hints are unsupported.
+  }
 }
 
 async function startCameraScanner(video, options = {}) {
@@ -3509,11 +4811,13 @@ async function startCameraScanner(video, options = {}) {
       audio: false,
       video: {
         facingMode: { ideal: "environment" },
-        width: { ideal: 1280 },
-        height: { ideal: 720 }
+        width: { ideal: 1920 },
+        height: { ideal: 1080 },
+        frameRate: { ideal: 30 }
       }
     }
   );
+  await improveCameraTrack(stream);
 
   video.srcObject = stream;
   video.setAttribute("playsinline", "");
@@ -3522,32 +4826,436 @@ async function startCameraScanner(video, options = {}) {
 
   const scanInterval = Math.max(80, options.scanInterval ?? 180);
   const scratchCanvas = document.createElement("canvas");
+  const multiFrameEnabled = options.multiFrame !== false;
+  const multiFrameWindow = Math.max(2, Math.min(8, Math.round(options.multiFrameWindow ?? 4)));
+  const multiFrameMinFrames = Math.max(2, Math.min(multiFrameWindow, Math.round(options.multiFrameMinFrames ?? 2)));
+  const observationHistory = new Map();
+  const cameraAutoColorEvery = Math.max(1, Math.round(options.cameraAutoColorEvery ?? 1));
+  const cameraAutoEnhanceEvery = Math.max(1, Math.round(options.cameraAutoEnhanceEvery ?? 2));
+  const cameraFinderRecoveryEvery = Math.max(1, Math.round(options.cameraFinderRecoveryEvery ?? 2));
+  let missStreak = 0;
   let stopped = false;
   let busy = false;
   let timer = null;
+  let frameNumber = 0;
+
+  const diagnosticsEnabled = typeof options.onDiagnostic === "function";
+  const emitDiagnostic = (event) => {
+    if (!diagnosticsEnabled) return;
+    try {
+      options.onDiagnostic({
+        timestamp: Date.now(),
+        frame: frameNumber,
+        ...event
+      });
+    } catch {
+      // Diagnostics are UI-only and must never interrupt scanning.
+    }
+  };
+
+
+  if (diagnosticsEnabled) {
+    const track = stream.getVideoTracks?.()[0];
+    const settings = track?.getSettings?.() ?? {};
+    emitDiagnostic({
+      type: "camera-ready",
+      method: "camera",
+      message: `Camera ready · ${settings.width ?? video.videoWidth}×${settings.height ?? video.videoHeight}` ,
+      camera: {
+        width: settings.width ?? video.videoWidth,
+        height: settings.height ?? video.videoHeight,
+        frameRate: settings.frameRate ?? null,
+        facingMode: settings.facingMode ?? null
+      }
+    });
+  }
 
   const stop = () => {
     stopped = true;
     if (timer) clearTimeout(timer);
+    observationHistory.clear();
     for (const track of stream.getTracks()) track.stop();
     if (video.srcObject === stream) video.srcObject = null;
   };
 
-  const scanNow = () => scanVideoFrame(video, { ...options, canvas: scratchCanvas });
+  const scanNow = () => scanVideoFrame(video, {
+    ...options,
+    maxDimension: options.maxDimension ?? 1080,
+    canvas: scratchCanvas
+  });
+
+  const emitResult = (result, capturedFrame = null, diagnostic = null) => {
+    const frameMeta = capturedFrame?.imageData ? {
+      frame: frameNumber,
+      imageData: capturedFrame.imageData,
+      scanWidth: capturedFrame.scanWidth,
+      scanHeight: capturedFrame.scanHeight,
+      sourceRect: capturedFrame.source ? { ...capturedFrame.source } : null,
+      enhancedImageData: capturedFrame.enhancedImageData ?? null,
+      enhancedRect: capturedFrame.enhancedRect ? { ...capturedFrame.enhancedRect } : null,
+      enhancement: capturedFrame.enhancement ? { ...capturedFrame.enhancement } : null,
+      diagnostic
+    } : null;
+    options.onResult?.(result, frameMeta);
+    options.onDecode?.(result, frameMeta);
+    if (options.stopOnResult ?? true) {
+      stop();
+      return true;
+    }
+    return false;
+  };
+
+  const tryMultiFrameDecode = (observations) => {
+    if (!multiFrameEnabled) return null;
+    const best = selectBestFrameObservation(observations);
+    if (!best) return null;
+    const history = observationHistory.get(best.version) ?? [];
+    history.push(best);
+    while (history.length > multiFrameWindow) history.shift();
+    observationHistory.set(best.version, history);
+    if (history.length < multiFrameMinFrames) return null;
+
+    const combined = combineFrameObservations(history);
+    if (!combined) return null;
+    try {
+      const decoded = decodeMatrix(combined.matrix, {
+        structureTolerance: options.structureTolerance ?? 0.20,
+        cellConfidence: combined.confidence,
+        maxErasureConfidence: options.maxErasureConfidence
+      });
+      if (decoded.version !== best.version) return null;
+      return {
+        ...decoded,
+        perspectiveCorrected: Boolean(best.geometry),
+        colorCalibrated: true,
+        colorNormalization: "multi-frame-vote",
+        samplingMode: "multi-frame-vote",
+        multiFrameCombined: history.length,
+        geometry: best.geometry,
+        observedPalette: best.observedPalette,
+        averageCellConfidence: best.averageCellConfidence,
+        lowConfidenceCells: best.lowConfidenceCells
+      };
+    } catch {
+      return null;
+    }
+  };
 
   const loop = async () => {
     if (stopped) return;
     if (!busy && video.readyState >= 2) {
       busy = true;
+      frameNumber++;
+      const observations = [];
+      const frameDiagnostics = diagnosticsEnabled ? {} : null;
+      const capturedFrame = {};
+      const frameStarted = nowMs();
+      let allowAutoEnhance = false;
+      let allowFinderRecovery = false;
       try {
-        const result = scanNow();
-        options.onResult?.(result);
-        if (options.stopOnResult ?? true) {
-          stop();
-          return;
-        }
+        // The first frame stays minimal. The primary finder pass itself is now
+        // QuadQR-aware (max RGB/value channel), so it remains cheap while no
+        // longer confusing dark blue data with structural black. After a miss,
+        // alternate frames may bracket finder thresholds and then use the
+        // stronger color recovery path. Empty camera frames therefore do not
+        // pay every recovery cost on every scan tick.
+        allowFinderRecovery = options.finderRecovery !== false &&
+          missStreak > 0 && ((missStreak - 1) % cameraFinderRecoveryEvery === 0);
+        allowAutoEnhance = options.autoEnhanceRecovery !== false &&
+          missStreak > 0 && ((missStreak - 1) % cameraAutoEnhanceEvery === 0);
+        const method = allowAutoEnhance
+          ? "progressive-color-recovery"
+          : (allowFinderRecovery ? "finder-recovery" : "fast-scan");
+        const result = scanVideoFrame(video, {
+          ...options,
+          _diagnosticLabel: method,
+          finderRecovery: allowFinderRecovery,
+          autoEnhanceRecovery: allowAutoEnhance,
+          autoEnhanceWhenNoGeometry: allowAutoEnhance,
+          // If geometry exists, the rectified QR-only pixel enhancer is both
+          // stronger and much cheaper than reprocessing the whole live frame.
+          fullFrameAutoEnhanceRecovery: options.fullFrameAutoEnhanceRecovery ?? false,
+          maxDimension: options.maxDimension ?? 1080,
+          canvas: scratchCanvas,
+          _capturedFrame: capturedFrame,
+          _observationCollector: observations,
+          _frameDiagnostics: frameDiagnostics
+        });
+        const elapsedMs = nowMs() - frameStarted;
+        emitDiagnostic({
+          type: "frame",
+          state: "decoded",
+          method: result.recoveryMode ?? result.samplingMode ?? method,
+          elapsedMs,
+          missStreak,
+          ...frameDiagnostics
+        });
+        emitDiagnostic({
+          type: "success",
+          state: "decoded",
+          method: result.recoveryMode ?? result.samplingMode ?? method,
+          elapsedMs,
+          message: `Decoded v${result.version} · ECC ${result.eccLevel} · ${Math.round(elapsedMs)} ms`,
+          ...frameDiagnostics
+        });
+        missStreak = 0;
+        observationHistory.clear();
+        if (emitResult(result, capturedFrame, frameDiagnostics)) return;
       } catch (error) {
-        options.onScanMiss?.(error);
+        missStreak++;
+        const fastElapsedMs = nowMs() - frameStarted;
+        emitDiagnostic({
+          type: "frame",
+          state: "miss",
+          method: allowAutoEnhance
+            ? "progressive-color-recovery"
+            : (allowFinderRecovery ? "finder-recovery" : "fast-scan"),
+          elapsedMs: fastElapsedMs,
+          missStreak,
+          error: error?.message ?? String(error),
+          ...frameDiagnostics
+        });
+
+        // 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
+        // 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 &&
+          capturedFrame.imageData &&
+          ((missStreak - 1) % cameraAutoColorEvery === 0);
+        if (shouldTryCameraAutoColor) {
+          const requestedCrops = Array.isArray(options.cameraAutoColorCropInsets)
+            ? options.cameraAutoColorCropInsets
+            : [0.08, 0.16, 0.22, 0];
+          const cropInsets = [];
+          for (const value of requestedCrops) {
+            const inset = clampNumber(Number(value), 0, 0.30);
+            if (!cropInsets.some((item) => Math.abs(item - inset) < 0.001)) cropInsets.push(inset);
+          }
+          const explicitAnalysisInsets = Array.isArray(options.cameraAutoColorAnalysisInsets)
+            ? options.cameraAutoColorAnalysisInsets
+            : null;
+
+          emitDiagnostic({
+            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(" → ")})`,
+            ...frameDiagnostics
+          });
+
+          let autoColorDecoded = false;
+          for (let profileIndex = 0; profileIndex < cropInsets.length; profileIndex++) {
+            const cropInset = cropInsets[profileIndex];
+            const cropped = cropImageDataInset(capturedFrame.imageData, cropInset);
+            const defaultAnalysisInsets = [0.10, 0.08, 0.04, 0.10];
+            const analysisInset = clampNumber(
+              Number(explicitAnalysisInsets?.[profileIndex]
+                ?? options.cameraAutoColorAnalysisInset
+                ?? defaultAnalysisInsets[Math.min(profileIndex, defaultAnalysisInsets.length - 1)]),
+              0,
+              0.30
+            );
+            const autoColorObservations = [];
+            const autoColorVisionDiagnostics = diagnosticsEnabled ? { passes: [] } : null;
+            const autoColorFrameDiagnostics = diagnosticsEnabled ? {} : null;
+            const cropLabel = cropInset ? `${Math.round(cropInset * 100)}pct-crop` : "full";
+            const profileName = `camera-auto-color-${cropLabel}`;
+            try {
+              const recoveryStarted = nowMs();
+              const correctedFrame = autoColorImageData(cropped.imageData, {
+                // 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.
+                blackClip: options.cameraAutoColorBlackClip ?? 0.0001,
+                whiteClip: options.cameraAutoColorWhiteClip ?? 0.004,
+                highlightPercentile: options.cameraAutoColorHighlightPercentile ?? 0.95,
+                outputHighlight: options.cameraAutoColorOutputHighlight ?? 190,
+                analysisInset,
+                minimumInputRange: options.cameraAutoColorMinimumInputRange ?? 72,
+                targetSamples: options.cameraAutoColorTargetSamples ?? 90000
+              });
+              const recovered = scanImageData(correctedFrame, {
+                ...options,
+                _diagnosticLabel: profileName,
+                _visionDiagnostics: autoColorVisionDiagnostics,
+                finderRecovery: true,
+                autoEnhanceRecovery: false,
+                fullFrameAutoEnhanceRecovery: false,
+                _observationCollector: autoColorObservations
+              });
+              if (autoColorFrameDiagnostics) {
+                normalizeFrameDiagnostics(
+                  autoColorFrameDiagnostics,
+                  capturedFrame.source ?? { x: 0, y: 0, width: capturedFrame.scanWidth, height: capturedFrame.scanHeight, cropped: false },
+                  correctedFrame.width,
+                  correctedFrame.height,
+                  autoColorVisionDiagnostics
+                );
+                autoColorFrameDiagnostics.frameWidth = capturedFrame.scanWidth;
+                autoColorFrameDiagnostics.frameHeight = capturedFrame.scanHeight;
+                autoColorFrameDiagnostics.scanRect = { ...cropped.rect };
+                autoColorFrameDiagnostics.autoColorCropInset = cropInset;
+                autoColorFrameDiagnostics.autoColorAnalysisInset = analysisInset;
+              }
+              const recoveryElapsedMs = nowMs() - recoveryStarted;
+              emitDiagnostic({
+                type: "frame",
+                state: "decoded",
+                method: profileName,
+                elapsedMs: recoveryElapsedMs,
+                missStreak,
+                ...(autoColorFrameDiagnostics ?? frameDiagnostics)
+              });
+              emitDiagnostic({
+                type: "success",
+                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`,
+                ...(autoColorFrameDiagnostics ?? frameDiagnostics)
+              });
+              capturedFrame.enhancedImageData = correctedFrame;
+              capturedFrame.enhancedRect = { ...cropped.rect };
+              capturedFrame.enhancement = {
+                method: "camera-auto-color",
+                cropInset,
+                analysisInset
+              };
+              missStreak = 0;
+              observationHistory.clear();
+              autoColorDecoded = true;
+              if (emitResult({
+                ...recovered,
+                autoColorCorrected: true,
+                cameraProgressiveRecovery: true,
+                recoveryMode: "camera-auto-color",
+                cameraAutoColorCropInset: cropInset,
+                cameraAutoColorAnalysisInset: analysisInset
+              }, capturedFrame, autoColorFrameDiagnostics ?? frameDiagnostics)) return;
+              break;
+            } catch (recoveryError) {
+              observations.push(...autoColorObservations);
+              if (autoColorFrameDiagnostics) {
+                normalizeFrameDiagnostics(
+                  autoColorFrameDiagnostics,
+                  capturedFrame.source ?? { x: 0, y: 0, width: capturedFrame.scanWidth, height: capturedFrame.scanHeight, cropped: false },
+                  cropped.imageData.width,
+                  cropped.imageData.height,
+                  autoColorVisionDiagnostics
+                );
+                autoColorFrameDiagnostics.frameWidth = capturedFrame.scanWidth;
+                autoColorFrameDiagnostics.frameHeight = capturedFrame.scanHeight;
+                autoColorFrameDiagnostics.scanRect = { ...cropped.rect };
+                autoColorFrameDiagnostics.autoColorCropInset = cropInset;
+                autoColorFrameDiagnostics.autoColorAnalysisInset = analysisInset;
+                emitDiagnostic({
+                  type: "frame",
+                  state: "miss",
+                  method: profileName,
+                  elapsedMs: nowMs() - frameStarted,
+                  missStreak,
+                  error: recoveryError?.message ?? String(recoveryError),
+                  ...autoColorFrameDiagnostics
+                });
+              }
+              emitDiagnostic({
+                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)` : ""}`,
+                ...(autoColorFrameDiagnostics ?? frameDiagnostics)
+              });
+            }
+          }
+          if (!autoColorDecoded) {
+            emitDiagnostic({
+              type: "method",
+              state: "failed",
+              method: "camera-auto-color",
+              message: "All camera Auto Color profiles failed · continuing deeper recovery",
+              ...frameDiagnostics
+            });
+          }
+        }
+
+        // If the fast pass already saw a convincing QuadQR structure, retry
+        // the exact same captured ROI immediately with the stronger QR-region
+        // color correction. Empty/non-QR frames do not pay this cost. This is
+        // the live equivalent of: normal scan first, then Auto Tone / Contrast
+        // / Color only when the normal decode actually needs help.
+        if (!allowAutoEnhance && options.autoEnhanceRecovery !== false) {
+          const strongObservation = selectBestFrameObservation(observations);
+          if (strongObservation && scratchCanvas.width && scratchCanvas.height) {
+            emitDiagnostic({
+              type: "method",
+              state: "trying",
+              method: "qr-region-auto-enhance",
+              message: "Fast decode failed · trying QR-region Auto Tone / Contrast / Color",
+              ...frameDiagnostics
+            });
+            try {
+              const recoveryStarted = nowMs();
+              const frameContext = scratchCanvas.getContext("2d", { alpha: false, willReadFrequently: true });
+              const capturedImageData = frameContext.getImageData(0, 0, scratchCanvas.width, scratchCanvas.height);
+              const recoveryObservations = [];
+              const recoveryVisionDiagnostics = diagnosticsEnabled ? { passes: [] } : null;
+              const recovered = scanImageData(capturedImageData, {
+                ...options,
+                _diagnosticLabel: "qr-region-auto-enhance",
+                _visionDiagnostics: recoveryVisionDiagnostics,
+                autoEnhanceRecovery: true,
+                autoEnhanceWhenNoGeometry: false,
+                fullFrameAutoEnhanceRecovery: false,
+                _observationCollector: recoveryObservations
+              });
+              const recoveryElapsedMs = nowMs() - recoveryStarted;
+              emitDiagnostic({
+                type: "success",
+                state: "decoded",
+                method: recovered.recoveryMode ?? recovered.samplingMode ?? "qr-region-auto-enhance",
+                elapsedMs: recoveryElapsedMs,
+                message: `Recovery decoded v${recovered.version} · ECC ${recovered.eccLevel} · ${Math.round(recoveryElapsedMs)} ms`,
+                ...frameDiagnostics
+              });
+              missStreak = 0;
+              observationHistory.clear();
+              if (emitResult({
+                ...recovered,
+                cameraProgressiveRecovery: true
+              }, capturedFrame, frameDiagnostics)) return;
+            } catch {
+              emitDiagnostic({
+                type: "method",
+                state: "failed",
+                method: "qr-region-auto-enhance",
+                message: "QR-region color recovery did not decode · trying multi-frame ECC",
+                ...frameDiagnostics
+              });
+              // Keep the original observations for multi-frame voting below.
+            }
+          }
+        }
+
+        const combined = tryMultiFrameDecode(observations);
+        if (combined) {
+          emitDiagnostic({
+            type: "success",
+            state: "decoded",
+            method: "multi-frame-vote",
+            message: `Multi-frame recovery decoded v${combined.version} from ${combined.multiFrameCombined} frames`,
+            ...frameDiagnostics
+          });
+          missStreak = 0;
+          if (emitResult(combined, capturedFrame, frameDiagnostics)) return;
+        } else {
+          options.onScanMiss?.(error);
+        }
       } finally {
         busy = false;
       }
@@ -3605,6 +5313,10 @@ const internals = Object.freeze({
   decodeRsAdaptive,
   encodeProtectedHeader,
   decodeProtectedHeader,
+  selectBestFrameObservation,
+  combineFrameObservations,
+  visibleVideoSourceRect,
+  cropImageDataInset,
   HEADER_CODEWORD_CELLS,
   COMPACT_HEADER_CODEWORD_CELLS,
   CELLS_PER_BYTE,