quadqr-js 1.0.0 → 1.0.2

package/dist/esm/quadqr.js

@@ -32,6 +32,10 @@ import {
   samplePerspectiveMatrix,
   rectifyImageData,
   sampleObservedPalette,
+  spatiallyNormalizeRgbGrid,
+  autoToneContrastColorRgbGrid,
+  autoToneContrastColorImageData,
+  autoColorImageData,
   findActiveBounds,
   sampleAxisAlignedGrid
 } from "./vision.js";
@@ -1592,14 +1596,55 @@ export 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) {
@@ -1610,12 +1655,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;
@@ -1627,17 +1673,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;
@@ -1648,8 +1724,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;
@@ -1668,46 +1747,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.
+        }
+      }
     }
   }
 
@@ -1721,7 +2107,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 = [];
@@ -1734,49 +2120,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.
     }
   }
 
@@ -1793,16 +2225,90 @@ export 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."
   );
@@ -1834,19 +2340,274 @@ export 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;
+}
+
 export 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.
+  }
 }
 
 export async function startCameraScanner(video, options = {}) {
@@ -1858,11 +2619,13 @@ export 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", "");
@@ -1871,32 +2634,436 @@ export 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;
       }
@@ -1954,6 +3121,10 @@ export const internals = Object.freeze({
   decodeRsAdaptive,
   encodeProtectedHeader,
   decodeProtectedHeader,
+  selectBestFrameObservation,
+  combineFrameObservations,
+  visibleVideoSourceRect,
+  cropImageDataInset,
   HEADER_CODEWORD_CELLS,
   COMPACT_HEADER_CODEWORD_CELLS,
   CELLS_PER_BYTE,