quadqr-js 1.4.2 → 1.5.2

package/dist/quadqr.js

@@ -8,8 +8,9 @@ const __qqr_geometry_js = (function () {
  *
  * Versions 2..40 use the same alignment-pattern center schedule as standard
  * QR Code matrices. QuadQR remains its own symbology, but reuses that proven
- * spatial distribution for alignment references. QuadQR uses one 5x5 primary
- * alignment reference at the bottom-right and compact 3x3 secondary markers.
+ * spatial distribution for alignment references. QuadQR format v6 uses the same
+ * proven 5x5 nested alignment marker shape at every scheduled alignment center.
+ * Legacy format v5 used one 5x5 primary marker plus compact 3x3 secondaries.
  * Version 1 keeps the legacy QuadQR bottom-right bootstrap marker because standard QR v1 has no
  * alignment pattern and the QuadQR camera scanner needs a fourth projective
  * reference point.
@@ -18,6 +19,14 @@ const __qqr_geometry_js = (function () {
 const MIN_GEOMETRY_VERSION = 1;
 const MAX_GEOMETRY_VERSION = 40;
 
+const ALIGNMENT_PROFILE_STANDARD_5 = "standard5";
+const ALIGNMENT_PROFILE_LEGACY_3 = "compact3";
+
+function normalizeAlignmentProfile(profile = ALIGNMENT_PROFILE_STANDARD_5) {
+  if (profile === ALIGNMENT_PROFILE_STANDARD_5 || profile === ALIGNMENT_PROFILE_LEGACY_3) return profile;
+  throw new Error(`Unsupported alignment profile ${profile}.`);
+}
+
 // Index by version. Entry 0 is unused. Values are module indices of alignment
 // pattern centers, matching the standard QR Code version layout for v2..v40.
 const ALIGNMENT_PATTERN_AXES = Object.freeze([
@@ -84,9 +93,11 @@ function versionFromSize(size) {
     : null;
 }
 
-function alignmentPatternCentersForVersion(version) {
+function alignmentPatternCentersForVersion(version, options = {}) {
   assertVersion(version);
   const size = sizeForVersion(version);
+  const requestedProfile = typeof options === "string" ? options : options.profile;
+  const profile = normalizeAlignmentProfile(requestedProfile ?? ALIGNMENT_PROFILE_STANDARD_5);
 
   if (version === 1) {
     const center = size - 4;
@@ -96,7 +107,8 @@ function alignmentPatternCentersForVersion(version) {
       size: 5,
       primary: true,
       bootstrap: true,
-      separator: true
+      separator: true,
+      profile
     }];
   }
 
@@ -118,10 +130,13 @@ function alignmentPatternCentersForVersion(version) {
       centers.push({
         row,
         col,
-        size: primary ? 5 : 3,
+        // Format v6 uses a real QR-style 5x5 black/white/black alignment eye
+        // everywhere. Legacy v5 kept compact 3x3 secondaries to save cells.
+        size: profile === ALIGNMENT_PROFILE_LEGACY_3 && !primary ? 3 : 5,
         primary,
         bootstrap: false,
-        separator: false
+        separator: false,
+        profile
       });
     }
   }
@@ -129,8 +144,8 @@ function alignmentPatternCentersForVersion(version) {
   return centers;
 }
 
-function primaryAlignmentPatternForVersion(version) {
-  const centers = alignmentPatternCentersForVersion(version);
+function primaryAlignmentPatternForVersion(version, options = {}) {
+  const centers = alignmentPatternCentersForVersion(version, options);
   return centers.find((pattern) => pattern.primary) ?? centers[centers.length - 1];
 }
 
@@ -143,17 +158,17 @@ function alignmentPatternIsBlack(pattern, rowOffset, colOffset) {
   if (Math.abs(rowOffset) > radius || Math.abs(colOffset) > radius) return null;
 
   if (pattern.size === 3) {
-    // Compact secondary marker: black 3x3 ring with a white center.
+    // Legacy format-v5 secondary marker: black 3x3 ring with a white center.
     return rowOffset !== 0 || colOffset !== 0;
   }
 
-  // Primary 5x5 marker: black outer ring, white inner ring, black center.
+  // QR-style 5x5 marker: black outer ring, white inner ring, black center.
   const outer = Math.abs(rowOffset) === 2 || Math.abs(colOffset) === 2;
   const center = rowOffset === 0 && colOffset === 0;
   return outer || center;
 }
 
-return { sizeForVersion, versionFromSize, alignmentPatternCentersForVersion, primaryAlignmentPatternForVersion, alignmentPatternRadius, alignmentPatternIsBlack, MIN_GEOMETRY_VERSION, MAX_GEOMETRY_VERSION, ALIGNMENT_PATTERN_AXES };
+return { normalizeAlignmentProfile, sizeForVersion, versionFromSize, alignmentPatternCentersForVersion, primaryAlignmentPatternForVersion, alignmentPatternRadius, alignmentPatternIsBlack, MIN_GEOMETRY_VERSION, MAX_GEOMETRY_VERSION, ALIGNMENT_PROFILE_STANDARD_5, ALIGNMENT_PROFILE_LEGACY_3, ALIGNMENT_PATTERN_AXES };
 })();
 const __qqr_reed_solomon_js = (function () {
 /**
@@ -956,10 +971,10 @@ const securityInternals = Object.freeze({
 return { bytesToHex, hexToBytes, normalizeRaw256Key, generateRaw256Key, estimateSecureEnvelopeOverhead, inspectSecureEnvelope, encryptSecurePayload, decryptSecurePayload, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, MIN_PBKDF2_ITERATIONS, MAX_PBKDF2_ITERATIONS, SECURITY_MODES, SECURITY_ALGORITHMS, securityInternals };
 })();
 const __qqr_vision_js = (function () {
-const { alignmentPatternCentersForVersion, alignmentPatternIsBlack, alignmentPatternRadius, primaryAlignmentPatternForVersion, sizeForVersion } = __qqr_geometry_js;
+const { alignmentPatternCentersForVersion, alignmentPatternIsBlack, alignmentPatternRadius, primaryAlignmentPatternForVersion, ALIGNMENT_PROFILE_STANDARD_5, ALIGNMENT_PROFILE_LEGACY_3, sizeForVersion } = __qqr_geometry_js;
 /**
  * Image geometry and sampling helpers for QuadQR.
- * Pure JavaScript. No DOM dependency except callers may pass browser ImageData.
+ * JavaScript fallback with optional WASM hot-loop acceleration. No DOM dependency except callers may pass browser ImageData.
  */
 
 function assert(condition, message) {
@@ -970,6 +985,20 @@ function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
 
+let visionAccelerator = null;
+
+// Repeated recovery stages often inspect the exact same captured ImageData.
+// Cache immutable grayscale/binary preprocessing by ImageData identity so the
+// stronger scanner can reuse work instead of rebuilding millions of pixels.
+// WeakMap keeps camera frames collectible as soon as the scan finishes.
+const binaryPreprocessCache = new WeakMap();
+const autoColorGrayCache = new WeakMap();
+
+/** Install or remove optional scanner hot-loop acceleration. Internal WASM wiring hook. */
+function installVisionAccelerator(accelerator = null) {
+  visionAccelerator = accelerator && typeof accelerator.buildBinary === "function" ? accelerator : null;
+}
+
 function pixelRgb(imageData, x, y) {
   const ix = clamp(Math.round(x), 0, imageData.width - 1);
   const iy = clamp(Math.round(y), 0, imageData.height - 1);
@@ -1065,54 +1094,140 @@ function binaryAtThreshold(gray, threshold) {
   return binary;
 }
 
+function hybridLocalBinary(gray, width, height) {
+  // QR-specific local thresholding inspired by the same block strategy used by
+  // ZXing's HybridBinarizer. It is intentionally a locator fallback, not a
+  // replacement for QuadQR's color correction. 8x8 blocks + smoothed local
+  // black points make finder rings survive shadows and screen gradients that
+  // defeat one global threshold.
+  const BLOCK = 8;
+  const MIN_DIMENSION = 40;
+  const MIN_DYNAMIC_RANGE = 24;
+  if (width < MIN_DIMENSION || height < MIN_DIMENSION) return null;
+
+  const subWidth = Math.ceil(width / BLOCK);
+  const subHeight = Math.ceil(height / BLOCK);
+  const blackPoints = new Uint16Array(subWidth * subHeight);
+  const maxXOffset = Math.max(0, width - BLOCK);
+  const maxYOffset = Math.max(0, height - BLOCK);
+
+  for (let by = 0; by < subHeight; by++) {
+    const y0 = Math.min(by * BLOCK, maxYOffset);
+    for (let bx = 0; bx < subWidth; bx++) {
+      const x0 = Math.min(bx * BLOCK, maxXOffset);
+      let sum = 0;
+      let min = 255;
+      let max = 0;
+      for (let yy = 0; yy < BLOCK; yy++) {
+        const row = (y0 + yy) * width + x0;
+        for (let xx = 0; xx < BLOCK; xx++) {
+          const value = gray[row + xx];
+          sum += value;
+          if (value < min) min = value;
+          if (value > max) max = value;
+        }
+      }
+      let average = sum >> 6;
+      if (max - min <= MIN_DYNAMIC_RANGE) {
+        average = min >> 1;
+        if (by > 0 && bx > 0) {
+          const above = blackPoints[(by - 1) * subWidth + bx];
+          const left = blackPoints[by * subWidth + bx - 1];
+          const diag = blackPoints[(by - 1) * subWidth + bx - 1];
+          const neighbor = (above + 2 * left + diag) >> 2;
+          if (min < neighbor) average = neighbor;
+        }
+      }
+      blackPoints[by * subWidth + bx] = average;
+    }
+  }
+
+  const binary = new Uint8Array(width * height);
+  for (let by = 0; by < subHeight; by++) {
+    const y0 = Math.min(by * BLOCK, maxYOffset);
+    const centerY = clamp(by, 2, Math.max(2, subHeight - 3));
+    for (let bx = 0; bx < subWidth; bx++) {
+      const x0 = Math.min(bx * BLOCK, maxXOffset);
+      const centerX = clamp(bx, 2, Math.max(2, subWidth - 3));
+      let sum = 0;
+      let count = 0;
+      for (let oy = -2; oy <= 2; oy++) {
+        const py = clamp(centerY + oy, 0, subHeight - 1);
+        for (let ox = -2; ox <= 2; ox++) {
+          const px = clamp(centerX + ox, 0, subWidth - 1);
+          sum += blackPoints[py * subWidth + px];
+          count++;
+        }
+      }
+      const threshold = Math.round(sum / Math.max(1, count));
+      for (let yy = 0; yy < BLOCK; yy++) {
+        const y = y0 + yy;
+        if (y >= height) break;
+        const row = y * width;
+        for (let xx = 0; xx < BLOCK; xx++) {
+          const x = x0 + xx;
+          if (x >= width) break;
+          if (gray[row + x] <= threshold) binary[row + x] = 1;
+        }
+      }
+    }
+  }
+  return binary;
+}
+
 function buildBinary(imageData, options = {}) {
   const grayMode = options.grayMode ?? "luminance";
+  const thresholdOffset = Math.round(Number(options.thresholdOffset) || 0);
+  const canCache = imageData && typeof imageData === "object" && options.cache !== false;
+  const cacheKey = `${grayMode}:${thresholdOffset}`;
+  if (canCache) {
+    const cached = binaryPreprocessCache.get(imageData)?.get(cacheKey);
+    if (cached) return cached;
+  }
+
+  let result;
+  if (visionAccelerator) {
+    try {
+      const accelerated = visionAccelerator.buildBinary(imageData, {
+        grayMode,
+        thresholdOffset
+      });
+      if (accelerated?.gray && accelerated?.binary) {
+        result = accelerated;
+        if (canCache) {
+          let entries = binaryPreprocessCache.get(imageData);
+          if (!entries) binaryPreprocessCache.set(imageData, entries = new Map());
+          entries.set(cacheKey, result);
+        }
+        return result;
+      }
+    } catch {
+      // A WASM/runtime failure must never make scanning unavailable. Fall back
+      // to the exact JavaScript implementation for this and future calls.
+      visionAccelerator = null;
+    }
+  }
+
   const gray = buildGray(imageData, grayMode);
   const baseThreshold = otsuThreshold(gray);
   const threshold = clamp(
-    Math.round(baseThreshold + (options.thresholdOffset ?? 0)),
+    Math.round(baseThreshold + thresholdOffset),
     8,
     247
   );
-  return {
+  result = {
     gray,
     binary: binaryAtThreshold(gray, threshold),
     threshold,
     baseThreshold,
     grayMode
   };
-}
-
-function runsForRow(binary, width, row) {
-  const runs = [];
-  let color = binary[row * width];
-  let start = 0;
-  for (let x = 1; x < width; x++) {
-    const next = binary[row * width + x];
-    if (next !== color) {
-      runs.push({ color, start, length: x - start });
-      color = next;
-      start = x;
-    }
+  if (canCache) {
+    let entries = binaryPreprocessCache.get(imageData);
+    if (!entries) binaryPreprocessCache.set(imageData, entries = new Map());
+    entries.set(cacheKey, result);
   }
-  runs.push({ color, start, length: width - start });
-  return runs;
-}
-
-function runsForColumn(binary, width, height, col) {
-  const runs = [];
-  let color = binary[col];
-  let start = 0;
-  for (let y = 1; y < height; y++) {
-    const next = binary[y * width + col];
-    if (next !== color) {
-      runs.push({ color, start, length: y - start });
-      color = next;
-      start = y;
-    }
-  }
-  runs.push({ color, start, length: height - start });
-  return runs;
+  return result;
 }
 
 function finderRatioScore(lengths, toleranceScale = 1) {
@@ -1130,34 +1245,85 @@ function finderRatioScore(lengths, toleranceScale = 1) {
   return score;
 }
 
-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), toleranceScale);
-    if (!Number.isFinite(score)) continue;
-    const first = window[0].start;
-    const total = window.reduce((sum, run) => sum + run.length, 0);
-    return {
-      center: first + total / 2,
-      moduleSize: total / 7,
-      score
-    };
-  }
-  return null;
-}
-
-function crossCheckVertical(binary, width, height, x, y, toleranceScale = 1) {
-  const col = clamp(Math.round(x), 0, width - 1);
-  return findWindowContainingCoordinate(runsForColumn(binary, width, height, col), y, toleranceScale);
-}
-
-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, toleranceScale);
+function finderCenterFromEnd(stateCount, end) {
+  return end - stateCount[4] - stateCount[3] - stateCount[2] / 2;
+}
+
+function directCrossCheckVertical(binary, width, height, startY, centerX, maxCount, originalTotal, toleranceScale = 1) {
+  const x = clamp(Math.round(centerX), 0, width - 1);
+  const state = [0, 0, 0, 0, 0];
+  let y = clamp(Math.round(startY), 0, height - 1);
+
+  while (y >= 0 && binary[y * width + x]) { state[2]++; y--; }
+  if (y < 0) return null;
+  while (y >= 0 && !binary[y * width + x] && state[1] <= maxCount) { state[1]++; y--; }
+  if (y < 0 || state[1] > maxCount) return null;
+  while (y >= 0 && binary[y * width + x] && state[0] <= maxCount) { state[0]++; y--; }
+  if (state[0] > maxCount) return null;
+
+  y = clamp(Math.round(startY), 0, height - 1) + 1;
+  while (y < height && binary[y * width + x]) { state[2]++; y++; }
+  if (y === height) return null;
+  while (y < height && !binary[y * width + x] && state[3] < maxCount) { state[3]++; y++; }
+  if (y === height || state[3] >= maxCount) return null;
+  while (y < height && binary[y * width + x] && state[4] < maxCount) { state[4]++; y++; }
+  if (state[4] >= maxCount) return null;
+
+  const total = state.reduce((sum, value) => sum + value, 0);
+  if (Math.abs(total - originalTotal) > originalTotal * 0.40) return null;
+  const score = finderRatioScore(state, toleranceScale);
+  if (!Number.isFinite(score)) return null;
+  return { center: finderCenterFromEnd(state, y), moduleSize: total / 7, score };
+}
+
+function directCrossCheckHorizontal(binary, width, height, startX, centerY, maxCount, originalTotal, toleranceScale = 1) {
+  const y = clamp(Math.round(centerY), 0, height - 1);
+  const row = y * width;
+  const state = [0, 0, 0, 0, 0];
+  let x = clamp(Math.round(startX), 0, width - 1);
+
+  while (x >= 0 && binary[row + x]) { state[2]++; x--; }
+  if (x < 0) return null;
+  while (x >= 0 && !binary[row + x] && state[1] <= maxCount) { state[1]++; x--; }
+  if (x < 0 || state[1] > maxCount) return null;
+  while (x >= 0 && binary[row + x] && state[0] <= maxCount) { state[0]++; x--; }
+  if (state[0] > maxCount) return null;
+
+  x = clamp(Math.round(startX), 0, width - 1) + 1;
+  while (x < width && binary[row + x]) { state[2]++; x++; }
+  if (x === width) return null;
+  while (x < width && !binary[row + x] && state[3] < maxCount) { state[3]++; x++; }
+  if (x === width || state[3] >= maxCount) return null;
+  while (x < width && binary[row + x] && state[4] < maxCount) { state[4]++; x++; }
+  if (state[4] >= maxCount) return null;
+
+  const total = state.reduce((sum, value) => sum + value, 0);
+  if (Math.abs(total - originalTotal) > originalTotal * 0.25) return null;
+  const score = finderRatioScore(state, toleranceScale);
+  if (!Number.isFinite(score)) return null;
+  return { center: finderCenterFromEnd(state, x), moduleSize: total / 7, score };
+}
+
+function directCrossCheckDiagonal(binary, width, height, centerX, centerY, toleranceScale = 1) {
+  const cx = clamp(Math.round(centerX), 0, width - 1);
+  const cy = clamp(Math.round(centerY), 0, height - 1);
+  const state = [0, 0, 0, 0, 0];
+  let step = 0;
+  while (cx - step >= 0 && cy - step >= 0 && binary[(cy - step) * width + (cx - step)]) { state[2]++; step++; }
+  if (!state[2]) return false;
+  while (cx - step >= 0 && cy - step >= 0 && !binary[(cy - step) * width + (cx - step)]) { state[1]++; step++; }
+  if (!state[1]) return false;
+  while (cx - step >= 0 && cy - step >= 0 && binary[(cy - step) * width + (cx - step)]) { state[0]++; step++; }
+  if (!state[0]) return false;
+
+  step = 1;
+  while (cx + step < width && cy + step < height && binary[(cy + step) * width + (cx + step)]) { state[2]++; step++; }
+  while (cx + step < width && cy + step < height && !binary[(cy + step) * width + (cx + step)]) { state[3]++; step++; }
+  if (!state[3]) return false;
+  while (cx + step < width && cy + step < height && binary[(cy + step) * width + (cx + step)]) { state[4]++; step++; }
+  if (!state[4]) return false;
+
+  return Number.isFinite(finderRatioScore(state, toleranceScale * 1.35));
 }
 
 function clusterFinderCandidates(raw, minConfirmations = 2) {
@@ -1202,47 +1368,180 @@ function clusterFinderCandidates(raw, minConfirmations = 2) {
 }
 
 function detectFinderCandidates(binary, width, height, options = {}) {
+  // Finder acquisition follows the same broad strategy that makes mature QR
+  // readers feel immediate: scan a subset of rows for 1:1:3:1:1, then confirm
+  // each hit directly across the orthogonal axes. Unlike the previous scanner,
+  // this does not allocate complete run arrays for every row and column.
   const raw = [];
-  const rowStep = height > 1200 ? 2 : 1;
   const toleranceScale = options.toleranceScale ?? 1;
   const moduleSpreadLimit = options.moduleSpreadLimit ?? 0.45;
   const minConfirmations = options.minConfirmations ?? 2;
+  const rowStep = Math.max(1, Math.round(options.rowStep ?? (height > 900 ? 2 : 1)));
+  const diagonalCheck = options.diagonalCheck === true;
+  const maxRawCandidates = Math.max(24, Math.round(options.maxRawCandidates ?? 160));
+
+  const handlePossibleCenter = (stateCount, y, endX) => {
+    const ratioScore = finderRatioScore(stateCount, toleranceScale);
+    if (!Number.isFinite(ratioScore)) return false;
+    const total = stateCount.reduce((sum, value) => sum + value, 0);
+    const centerX = finderCenterFromEnd(stateCount, endX);
+    const maxCount = Math.max(2, Math.ceil(stateCount[2] * 1.25));
+    const vertical = directCrossCheckVertical(binary, width, height, y, centerX, maxCount, total, toleranceScale);
+    if (!vertical) return false;
+    const horizontal = directCrossCheckHorizontal(binary, width, height, centerX, vertical.center, maxCount, total, toleranceScale);
+    if (!horizontal) return false;
+    if (diagonalCheck && !directCrossCheckDiagonal(binary, width, height, horizontal.center, vertical.center, toleranceScale)) return false;
+
+    const moduleSize = (total / 7 + vertical.moduleSize + horizontal.moduleSize) / 3;
+    const moduleSpread = Math.max(
+      Math.abs(moduleSize - total / 7),
+      Math.abs(moduleSize - vertical.moduleSize),
+      Math.abs(moduleSize - horizontal.moduleSize)
+    ) / Math.max(0.01, moduleSize);
+    if (moduleSpread > moduleSpreadLimit) return false;
+
+    raw.push({
+      x: horizontal.center,
+      y: vertical.center,
+      moduleSize,
+      score: ratioScore + vertical.score + horizontal.score
+    });
+    return true;
+  };
 
-  for (let y = 0; y < height; y += rowStep) {
-    const runs = runsForRow(binary, width, y);
-    for (let i = 0; i <= runs.length - 5; i++) {
-      const window = runs.slice(i, i + 5);
-      if (window.map((run) => run.color).join("") !== "10101") continue;
-      const lengths = window.map((run) => run.length);
-      const ratioScore = finderRatioScore(lengths, 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, toleranceScale);
-      if (!vertical) continue;
-      const horizontal = crossCheckHorizontal(binary, width, height, centerX, vertical.center, toleranceScale);
-      if (!horizontal) continue;
-
-      const moduleSize = (total / 7 + vertical.moduleSize + horizontal.moduleSize) / 3;
-      const moduleSpread = Math.max(
-        Math.abs(moduleSize - total / 7),
-        Math.abs(moduleSize - vertical.moduleSize),
-        Math.abs(moduleSize - horizontal.moduleSize)
-      ) / moduleSize;
-      if (moduleSpread > moduleSpreadLimit) continue;
-
-      raw.push({
-        x: horizontal.center,
-        y: vertical.center,
-        moduleSize,
-        score: ratioScore + vertical.score + horizontal.score
-      });
+  for (let y = rowStep - 1; y < height; y += rowStep) {
+    const state = [0, 0, 0, 0, 0];
+    let currentState = 0;
+    const row = y * width;
+
+    for (let x = 0; x < width; x++) {
+      if (binary[row + x]) {
+        if ((currentState & 1) === 1) currentState++;
+        state[currentState]++;
+      } else {
+        if ((currentState & 1) === 0) {
+          if (currentState === 4) {
+            handlePossibleCenter(state, y, x);
+            state[0] = state[2];
+            state[1] = state[3];
+            state[2] = state[4];
+            state[3] = 1;
+            state[4] = 0;
+            currentState = 3;
+          } else {
+            currentState++;
+            state[currentState]++;
+          }
+        } else {
+          state[currentState]++;
+        }
+      }
     }
+    if (currentState === 4) handlePossibleCenter(state, y, width);
+    if (raw.length >= maxRawCandidates) break;
   }
 
   return clusterFinderCandidates(raw, minConfirmations);
 }
 
+function detectFinderCandidatesByComponents(binary, width, height, options = {}) {
+  const visited = new Uint8Array(width * height);
+  const stack = [];
+  const candidates = [];
+  const minArea = Math.max(16, Math.round(options.componentMinArea ?? 20));
+  const minSpan = Math.max(5, Math.round(options.componentMinSpan ?? 7));
+  const maxComponents = Math.max(64, Math.round(options.componentMaxCount ?? 600));
+  let componentsSeen = 0;
+
+  const templateScore = (minX, minY, maxX, maxY) => {
+    const spanX = maxX - minX + 1;
+    const spanY = maxY - minY + 1;
+    let matches = 0;
+    let total = 0;
+    for (let r = 0; r < 7; r++) {
+      for (let c = 0; c < 7; c++) {
+        const x = minX + ((c + 0.5) / 7) * spanX;
+        const y = minY + ((r + 0.5) / 7) * spanY;
+        const actual = sampleBinaryAt(binary, width, height, x, y);
+        if (actual == null) continue;
+        const expected = r === 0 || r === 6 || c === 0 || c === 6 || (r >= 2 && r <= 4 && c >= 2 && c <= 4);
+        total++;
+        if (Boolean(actual) === expected) matches++;
+      }
+    }
+    return total ? matches / total : 0;
+  };
+
+  for (let index = 0; index < binary.length; index++) {
+    if (!binary[index] || visited[index]) continue;
+    componentsSeen++;
+    if (componentsSeen > maxComponents) break;
+    visited[index] = 1;
+    stack.length = 0;
+    stack.push(index);
+    let area = 0;
+    let minX = width;
+    let minY = height;
+    let maxX = -1;
+    let maxY = -1;
+
+    while (stack.length) {
+      const current = stack.pop();
+      const y = Math.floor(current / width);
+      const x = current - y * width;
+      area++;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+
+      if (x > 0) {
+        const next = current - 1;
+        if (binary[next] && !visited[next]) { visited[next] = 1; stack.push(next); }
+      }
+      if (x + 1 < width) {
+        const next = current + 1;
+        if (binary[next] && !visited[next]) { visited[next] = 1; stack.push(next); }
+      }
+      if (y > 0) {
+        const next = current - width;
+        if (binary[next] && !visited[next]) { visited[next] = 1; stack.push(next); }
+      }
+      if (y + 1 < height) {
+        const next = current + width;
+        if (binary[next] && !visited[next]) { visited[next] = 1; stack.push(next); }
+      }
+    }
+
+    const spanX = maxX - minX + 1;
+    const spanY = maxY - minY + 1;
+    if (area < minArea || spanX < minSpan || spanY < minSpan) continue;
+    const aspect = spanX / spanY;
+    if (aspect < 0.18 || aspect > 5.5) continue;
+    const density = area / (spanX * spanY);
+    if (density < 0.10 || density > 0.78) continue;
+    const centerX = (minX + maxX) / 2;
+    const centerY = (minY + maxY) / 2;
+    if (sampleBinaryAt(binary, width, height, centerX, centerY) !== 1) continue;
+    const score = templateScore(minX, minY, maxX, maxY);
+    if (score < (options.componentTemplateThreshold ?? 0.63)) continue;
+
+    candidates.push({
+      x: centerX,
+      y: centerY,
+      moduleSize: Math.max(0.75, Math.sqrt(area / 24)),
+      score: (1 - score) * 3,
+      componentScore: score,
+      componentArea: area
+    });
+  }
+
+  return candidates.sort((a, b) =>
+    (b.componentScore - a.componentScore) ||
+    (b.componentArea - a.componentArea)
+  ).slice(0, Math.max(3, Math.round(options.componentMaxCandidates ?? 12)));
+}
+
 function recoverFinderSetFromTwo(binary, width, height, strongFinders, detector = {}) {
   if (strongFinders.length !== 2) return strongFinders;
   const moduleMean = (strongFinders[0].moduleSize + strongFinders[1].moduleSize) / 2;
@@ -1348,6 +1647,61 @@ function chooseFinderTriples(candidates, maxTriples = 16, options = {}) {
   return triples.slice(0, maxTriples);
 }
 
+function rayDistanceToImageBoundary(width, height, x, y, dx, dy) {
+  let limit = Infinity;
+  if (dx > 1e-9) limit = Math.min(limit, (width - 1 - x) / dx);
+  else if (dx < -1e-9) limit = Math.min(limit, (0 - x) / dx);
+  if (dy > 1e-9) limit = Math.min(limit, (height - 1 - y) / dy);
+  else if (dy < -1e-9) limit = Math.min(limit, (0 - y) / dy);
+  return Number.isFinite(limit) ? Math.max(0, limit) : 0;
+}
+
+function finderHalfRunDistance(binary, width, height, center, direction) {
+  const length = Math.hypot(direction.x, direction.y);
+  if (length < 1e-6) return NaN;
+  const dx = direction.x / length;
+  const dy = direction.y / length;
+  const maxDistance = rayDistanceToImageBoundary(width, height, center.x, center.y, dx, dy);
+  let previous = sampleBinaryAt(binary, width, height, center.x, center.y);
+  if (previous !== 1) return NaN;
+  let transitions = 0;
+  let lastDistance = 0;
+  // Half-pixel stepping keeps the measured boundary stable at small module
+  // sizes without becoming expensive. A finder needs only three transitions:
+  // center black -> white ring -> black ring -> outside white.
+  for (let distance = 0.5; distance <= maxDistance; distance += 0.5) {
+    const value = sampleBinaryAt(binary, width, height, center.x + dx * distance, center.y + dy * distance);
+    if (value == null) break;
+    if (value !== previous) {
+      transitions++;
+      previous = value;
+      if (transitions === 3) return distance;
+    }
+    lastDistance = distance;
+    if (distance > 80 && transitions === 0) break;
+  }
+  return transitions >= 2 ? lastDistance : NaN;
+}
+
+function directionalFinderModuleSize(binary, width, height, pattern, otherPattern) {
+  const direction = { x: otherPattern.x - pattern.x, y: otherPattern.y - pattern.y };
+  const forward = finderHalfRunDistance(binary, width, height, pattern, direction);
+  const backward = finderHalfRunDistance(binary, width, height, pattern, { x: -direction.x, y: -direction.y });
+  if (!Number.isFinite(forward) && !Number.isFinite(backward)) return NaN;
+  if (!Number.isFinite(forward)) return (backward * 2) / 7;
+  if (!Number.isFinite(backward)) return (forward * 2) / 7;
+  return (forward + backward) / 7;
+}
+
+function moduleSizeBetweenFinders(binary, width, height, a, b) {
+  const fromA = directionalFinderModuleSize(binary, width, height, a, b);
+  const fromB = directionalFinderModuleSize(binary, width, height, b, a);
+  if (Number.isFinite(fromA) && Number.isFinite(fromB)) return (fromA + fromB) / 2;
+  if (Number.isFinite(fromA)) return fromA;
+  if (Number.isFinite(fromB)) return fromB;
+  return (a.moduleSize + b.moduleSize) / 2;
+}
+
 function nearestVersionFromEstimate(value, minVersion, maxVersion) {
   const candidates = [];
   for (let version = minVersion; version <= maxVersion; version++) {
@@ -1418,6 +1772,112 @@ function preciseAlignmentScore(binary, width, height, center, basisU, basisV, sc
   return total ? matches / total : 0;
 }
 
+// Fast 5x5 nested-eye probe used before the heavier alignment template search.
+// A standard 5x5 alignment pattern has a particularly strong signature along
+// its centre axes: black / white / black / white / black. We also probe the
+// inner and outer diagonals so random payload modules are much less likely to
+// impersonate an alignment eye. This is deliberately tiny: at most 17 binary
+// samples per candidate instead of a full 25/125-sample template evaluation.
+const FAST_ALIGNMENT_PROBES = Object.freeze([
+  Object.freeze([0, 0, 1, 2.2]),
+  Object.freeze([-1, 0, 0, 1.4]), Object.freeze([1, 0, 0, 1.4]),
+  Object.freeze([0, -1, 0, 1.4]), Object.freeze([0, 1, 0, 1.4]),
+  Object.freeze([-2, 0, 1, 1.2]), Object.freeze([2, 0, 1, 1.2]),
+  Object.freeze([0, -2, 1, 1.2]), Object.freeze([0, 2, 1, 1.2]),
+  Object.freeze([-1, -1, 0, 0.9]), Object.freeze([1, -1, 0, 0.9]),
+  Object.freeze([-1, 1, 0, 0.9]), Object.freeze([1, 1, 0, 0.9]),
+  Object.freeze([-2, -2, 1, 0.8]), Object.freeze([2, -2, 1, 0.8]),
+  Object.freeze([-2, 2, 1, 0.8]), Object.freeze([2, 2, 1, 0.8])
+]);
+
+function fastNestedAlignmentScore(binary, width, height, center, basisU, basisV, scale) {
+  let matched = 0;
+  let total = 0;
+  for (const [c, r, expected, weight] of FAST_ALIGNMENT_PROBES) {
+    const x = center.x + basisU.x * c * scale + basisV.x * r * scale;
+    const y = center.y + basisU.y * c * scale + basisV.y * r * scale;
+    const value = sampleBinaryAt(binary, width, height, x, y);
+    if (value === null) continue;
+    total += weight;
+    if (value === expected) matched += weight;
+  }
+  return total ? matched / total : 0;
+}
+
+function searchNestedAlignmentFast(binary, width, height, predicted, basisU, basisV, target, options = {}) {
+  if (target?.size !== 5 || options.fastAlignmentLocator === false) return null;
+
+  const inferredScale = clamp(Number(options.inferredTargetScale ?? 1), 0.5, 2.1);
+  const radius = clamp(Number(options.radius ?? 5), 2.5, 18);
+  const coarseStep = radius >= 14 ? 2 : radius >= 9 ? 1.5 : 1;
+  const scales = [...new Set([
+    Number((inferredScale * 0.78).toFixed(3)),
+    Number((inferredScale * 0.90).toFixed(3)),
+    Number(inferredScale.toFixed(3)),
+    Number((inferredScale * 1.12).toFixed(3)),
+    Number((inferredScale * 1.28).toFixed(3)),
+    0.75, 1, 1.25
+  ])].filter((value) => value >= 0.48 && value <= 2.1);
+
+  const candidates = [];
+  for (let offsetV = -radius; offsetV <= radius + 0.001; offsetV += coarseStep) {
+    for (let offsetU = -radius; offsetU <= radius + 0.001; offsetU += coarseStep) {
+      const center = {
+        x: predicted.x + basisU.x * offsetU + basisV.x * offsetV,
+        y: predicted.y + basisU.y * offsetU + basisV.y * offsetV
+      };
+      let bestScore = 0;
+      let bestScale = 1;
+      for (const scale of scales) {
+        const score = fastNestedAlignmentScore(binary, width, height, center, basisU, basisV, scale);
+        if (score > bestScore) {
+          bestScore = score;
+          bestScale = scale;
+        }
+      }
+      // Keeping only plausible nested eyes makes the fine phase effectively
+      // constant-time even on very dense symbols.
+      if (bestScore >= (options.fastAlignmentSeedThreshold ?? 0.73)) {
+        candidates.push({ score: bestScore, center, scale: bestScale, offsetU, offsetV });
+      }
+    }
+  }
+
+  if (!candidates.length) return null;
+  candidates.sort((a, b) => b.score - a.score);
+  const fineSeeds = candidates.slice(0, Math.max(1, Math.round(options.fastAlignmentFineSeeds ?? 5)));
+  const fineOffsets = [-0.75, -0.35, 0, 0.35, 0.75];
+  let best = null;
+
+  for (const seed of fineSeeds) {
+    const fineScales = [...new Set([
+      Number((seed.scale * 0.90).toFixed(3)),
+      Number((seed.scale * 0.96).toFixed(3)),
+      Number(seed.scale.toFixed(3)),
+      Number((seed.scale * 1.05).toFixed(3)),
+      Number((seed.scale * 1.12).toFixed(3))
+    ])].filter((value) => value >= 0.46 && value <= 2.15);
+    for (const du of fineOffsets) {
+      for (const dv of fineOffsets) {
+        const offsetU = seed.offsetU + du;
+        const offsetV = seed.offsetV + dv;
+        const center = {
+          x: predicted.x + basisU.x * offsetU + basisV.x * offsetV,
+          y: predicted.y + basisU.y * offsetU + basisV.y * offsetV
+        };
+        for (const scale of fineScales) {
+          const score = alignmentScore(binary, width, height, center, basisU, basisV, scale, target);
+          if (!best || score > best.score) {
+            best = { score, center, scale, offsetU, offsetV, broadSearch: radius > 4, fastNested: true };
+          }
+        }
+      }
+    }
+  }
+
+  return best;
+}
+
 function searchAlignment(binary, width, height, triple, version, options = {}) {
   const size = sizeForVersion(version);
   const separation = size - 7;
@@ -1429,7 +1889,7 @@ function searchAlignment(binary, width, height, triple, version, options = {}) {
     x: (triple.bl.x - triple.tl.x) / separation,
     y: (triple.bl.y - triple.tl.y) / separation
   };
-  const target = primaryAlignmentPatternForVersion(version);
+  const target = primaryAlignmentPatternForVersion(version, { profile: options.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5 });
   const targetX = target.col + 0.5;
   const targetY = target.row + 0.5;
   const predicted = {
@@ -1437,11 +1897,6 @@ function searchAlignment(binary, width, height, triple, version, options = {}) {
     y: triple.tl.y + basisU.y * (targetX - 3.5) + basisV.y * (targetY - 3.5)
   };
 
-  const precise = options.preciseAlignment === true;
-  const localScoreFn = precise ? preciseAlignmentScore : alignmentScore;
-  const localOffsets = precise
-    ? [-2.5, -1.5, -0.75, -0.5, -0.25, 0, 0.25, 0.5, 0.75, 1.5, 2.5]
-    : [-2.5, -1.5, -0.75, 0, 0.75, 1.5, 2.5];
   const finderSizes = [triple.tl.moduleSize, triple.tr.moduleSize, triple.bl.moduleSize];
   const finderMin = Math.max(0.01, Math.min(...finderSizes));
   const finderMax = Math.max(...finderSizes);
@@ -1461,11 +1916,62 @@ function searchAlignment(binary, width, height, triple, version, options = {}) {
     Number((inferredTargetScale * 1.12).toFixed(3))
   ])].filter((scale) => scale >= 0.52 && scale <= 1.9);
 
+  const cornerSkew = Math.max(0, 1 - (triple.orthogonality ?? 1));
+  const projectiveSignal = Math.max(
+    Math.max(0, finderScaleRatio - 1),
+    Math.max(0, (triple.moduleSpread ?? 0) * 1.25),
+    cornerSkew * 0.75
+  );
+
+  // Try the nested-eye locator first. It searches a projective-sized region
+  // using only a handful of binary samples per location and therefore remains
+  // cheap even when the affine prediction is several modules off.
+  const fastRadius = clamp(
+    Number(options.fastAlignmentRadius ?? (3 + projectiveSignal * 13)),
+    3,
+    options.fastAlignmentMaxRadius ?? 16
+  );
+  const fastNested = searchNestedAlignmentFast(
+    binary,
+    width,
+    height,
+    predicted,
+    basisU,
+    basisV,
+    target,
+    {
+      ...options,
+      inferredTargetScale,
+      radius: fastRadius
+    }
+  );
+
+  const fastAccept = options.fastAlignmentAccept ?? (options.preciseAlignment ? 0.88 : 0.80);
+  if (fastNested && fastNested.score >= fastAccept) {
+    return {
+      ...fastNested,
+      basisU,
+      basisV,
+      predicted,
+      target,
+      finderScaleRatio,
+      projectiveSignal
+    };
+  }
+
+  const precise = options.preciseAlignment === true;
+  const localScoreFn = precise ? preciseAlignmentScore : alignmentScore;
+  const localOffsets = precise
+    ? [-2.5, -1.5, -0.75, -0.5, -0.25, 0, 0.25, 0.5, 0.75, 1.5, 2.5]
+    : [-2.5, -1.5, -0.75, 0, 0.75, 1.5, 2.5];
+
   const centerAt = (offsetU, offsetV) => ({
     x: predicted.x + basisU.x * offsetU + basisV.x * offsetV,
     y: predicted.y + basisU.y * offsetU + basisV.y * offsetV
   });
-  let best = { score: 0, center: predicted, scale: 1, offsetU: 0, offsetV: 0, broadSearch: false };
+  let best = fastNested && fastNested.score > 0
+    ? fastNested
+    : { score: 0, center: predicted, scale: 1, offsetU: 0, offsetV: 0, broadSearch: false };
 
   const evaluateIntoBest = (offsetU, offsetV, scales, scoreFn, broadSearch = false) => {
     const center = centerAt(offsetU, offsetV);
@@ -1485,12 +1991,6 @@ function searchAlignment(binary, width, height, triple, version, options = {}) {
   // prediction even though all three finder patterns remain strong. Use a
   // bounded coarse-to-fine search only when the locator geometry signals that
   // projective foreshortening is present.
-  const cornerSkew = Math.max(0, 1 - (triple.orthogonality ?? 1));
-  const projectiveSignal = Math.max(
-    Math.max(0, finderScaleRatio - 1),
-    Math.max(0, (triple.moduleSpread ?? 0) * 1.25),
-    cornerSkew * 0.75
-  );
   const broadEnabled = options.perspectiveAlignmentRecovery !== false && (
     options.perspectiveRecovery === true ||
     projectiveSignal >= (options.perspectiveAlignmentSignalThreshold ?? 0.32)
@@ -1607,8 +2107,8 @@ function projectedAlignmentScore(binary, width, height, homography, pattern) {
   return total ? matches / total : 0;
 }
 
-function scoreAlignmentGrid(binary, width, height, homography, version) {
-  const patterns = alignmentPatternCentersForVersion(version);
+function scoreAlignmentGrid(binary, width, height, homography, version, options = {}) {
+  const patterns = alignmentPatternCentersForVersion(version, { profile: options.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5 });
   if (!patterns.length) return { score: 1, patternScores: [] };
   const patternScores = patterns.map((pattern) => ({
     row: pattern.row,
@@ -1701,7 +2201,7 @@ function refineHomographyWithAlignmentGrid(
   initialGrid,
   options = {}
 ) {
-  const patterns = alignmentPatternCentersForVersion(version);
+  const patterns = alignmentPatternCentersForVersion(version, { profile: options.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5 });
   if (patterns.length <= 1 || options.alignmentRefinement === false) {
     return {
       homography: initialHomography,
@@ -1756,9 +2256,9 @@ function refineHomographyWithAlignmentGrid(
       x: candidate.pattern.col + 0.5,
       y: candidate.pattern.row + 0.5
     });
-    // A 3x3 marker carries less evidence than the 5x5 primary and the three
-    // finder patterns, so it helps average geometry without overpowering them.
-    weights.push(0.8 + candidate.score * 1.7);
+    // Distributed 5x5 alignment eyes now carry stronger evidence while remaining
+    // below the three primary finder patterns in the projective fit.
+    weights.push(1.15 + candidate.score * 1.95);
     pointInfo.push({
       row: candidate.pattern.row,
       col: candidate.pattern.col,
@@ -1776,7 +2276,7 @@ function refineHomographyWithAlignmentGrid(
     return { homography: initialHomography, grid: initialGrid, refined: false, points: [] };
   }
 
-  const refinedGrid = scoreAlignmentGrid(binary, width, height, refinedHomography, version);
+  const refinedGrid = scoreAlignmentGrid(binary, width, height, refinedHomography, version, options);
   const primaryBefore = primary
     ? projectedAlignmentScore(binary, width, height, initialHomography, primary)
     : 1;
@@ -1899,12 +2399,118 @@ function geometryCandidatesFromBinary(binary, width, height, finders, threshold,
   for (const triple of triples) {
     const legH = Math.hypot(triple.tr.x - triple.tl.x, triple.tr.y - triple.tl.y);
     const legV = Math.hypot(triple.bl.x - triple.tl.x, triple.bl.y - triple.tl.y);
-    const estimatedSize = ((legH + legV) / 2) / triple.moduleMean + 7;
-    const versions = nearestVersionFromEstimate(estimatedSize, minVersion, maxVersion).slice(0, 9);
+    const moduleH = moduleSizeBetweenFinders(binary, width, height, triple.tl, triple.tr);
+    const moduleV = moduleSizeBetweenFinders(binary, width, height, triple.tl, triple.bl);
+    const estimatedSizeH = legH / Math.max(0.5, moduleH) + 7;
+    const estimatedSizeV = legV / Math.max(0.5, moduleV) + 7;
+    const estimateSpread = Math.abs(estimatedSizeH - estimatedSizeV);
+    const fallbackEstimate = ((legH + legV) / 2) / triple.moduleMean + 7;
+    const estimatedSize = Number.isFinite(estimatedSizeH) && Number.isFinite(estimatedSizeV)
+      ? (estimatedSizeH + estimatedSizeV) / 2
+      : fallbackEstimate;
+    // Wrong finder triples often produce wildly different horizontal/vertical
+    // module counts. Reject only the most implausible sets here; full projective
+    // recovery remains intentionally permissive for real extreme camera angles.
+    const maxEstimateSpread = options.maxDimensionEstimateSpread ?? (options.perspectiveRecovery ? 18 : 10);
+    if (estimateSpread > maxEstimateSpread) continue;
+    const versions = nearestVersionFromEstimate(estimatedSize, minVersion, maxVersion).slice(0, Math.max(1, Math.round(options.versionSearchLimit ?? 9)));
 
     for (const item of versions) {
       const version = item.version;
       const size = sizeForVersion(version);
+
+      // Near-front-facing symbols do not need to wait for a fourth locator.
+      // With three reliable finder centres we already have an affine mapping.
+      // Validate that cheap mapping against the distributed 5x5 alignment grid;
+      // when it agrees strongly, return it immediately and let payload decoding
+      // provide the final integrity check. Strongly projective symbols skip this
+      // shortcut and continue into the full alignment/homography path below.
+      const affineProjectiveSignal = Math.max(
+        Math.max(0, triple.moduleSpread ?? 0),
+        Math.max(0, 1 - (triple.orthogonality ?? 1)) * 0.85,
+        Math.max(0, (triple.legRatio ?? 1) - 1) * 0.12
+      );
+      const allowAffineFastPath = options.finderAffineFastPath !== false &&
+        options.preciseAlignment !== true &&
+        options.perspectiveRecovery !== true &&
+        item.error <= (options.finderAffineVersionError ?? 2.6) &&
+        affineProjectiveSignal <= (options.finderAffineMaxProjectiveSignal ?? 0.24);
+
+      if (allowAffineFastPath) {
+        const separation = size - 7;
+        const basisU = {
+          x: (triple.tr.x - triple.tl.x) / separation,
+          y: (triple.tr.y - triple.tl.y) / separation
+        };
+        const basisV = {
+          x: (triple.bl.x - triple.tl.x) / separation,
+          y: (triple.bl.y - triple.tl.y) / separation
+        };
+        const target = primaryAlignmentPatternForVersion(version, {
+          profile: options.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5
+        });
+        const targetX = target.col + 0.5;
+        const targetY = target.row + 0.5;
+        const predictedAlignment = {
+          x: triple.tl.x + basisU.x * (targetX - 3.5) + basisV.x * (targetY - 3.5),
+          y: triple.tl.y + basisU.y * (targetX - 3.5) + basisV.y * (targetY - 3.5)
+        };
+        const affineDest = [
+          { x: 3.5, y: 3.5 },
+          { x: size - 3.5, y: 3.5 },
+          { x: 3.5, y: size - 3.5 },
+          { x: targetX, y: targetY }
+        ];
+        const affineSrc = [
+          { x: triple.tl.x, y: triple.tl.y },
+          { x: triple.tr.x, y: triple.tr.y },
+          { x: triple.bl.x, y: triple.bl.y },
+          predictedAlignment
+        ];
+        try {
+          const affineHomography = computeHomography(affineSrc, affineDest);
+          const affineGrid = scoreAlignmentGrid(binary, width, height, affineHomography, version, options);
+          if (affineGrid.score >= (options.finderAffineGridThreshold ?? 0.84)) {
+            const versionPenalty = item.error / 4;
+            geometries.push({
+              version,
+              size,
+              sourcePoints: affineSrc,
+              destinationPoints: affineDest,
+              homography: affineHomography,
+              finders: { topLeft: triple.tl, topRight: triple.tr, bottomLeft: triple.bl },
+              alignment: {
+                center: predictedAlignment,
+                predicted: predictedAlignment,
+                score: affineGrid.score,
+                scale: 1,
+                target: { row: target.row, col: target.col },
+                patterns: affineGrid.patternScores.length,
+                gridScore: affineGrid.score,
+                initialGridScore: affineGrid.score,
+                refined: false,
+                refinementPoints: [],
+                patternScores: affineGrid.patternScores,
+                method: "finder-affine"
+              },
+              threshold,
+              finderMethod: `${options.finderMethod ?? "finder"}-affine`,
+              alignmentProfile: options.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
+              estimatedSize,
+              estimatedSizeH,
+              estimatedSizeV,
+              directionalModuleSizeH: moduleH,
+              directionalModuleSizeV: moduleV,
+              score: triple.score * (0.58 + 0.42 * affineGrid.score) / (1 + versionPenalty * 0.08),
+              finderAffineFastPath: true
+            });
+            continue;
+          }
+        } catch {
+          // Full alignment search below remains the authoritative path.
+        }
+      }
+
       const alignment = searchAlignment(binary, width, height, triple, version, options);
       if (alignment.score < (options.alignmentThreshold ?? 0.72)) continue;
 
@@ -1929,7 +2535,7 @@ function geometryCandidatesFromBinary(binary, width, height, finders, threshold,
         continue;
       }
 
-      const initialAlignmentGrid = scoreAlignmentGrid(binary, width, height, homography, version);
+      const initialAlignmentGrid = scoreAlignmentGrid(binary, width, height, homography, version, options);
       const alignmentGridThreshold = options.alignmentGridThreshold ?? 0.68;
       const refinementFloor = Math.max(0, alignmentGridThreshold - (options.alignmentRefineCandidateMargin ?? 0.10));
       const skipRefinementScore = options.alignmentRefineSkipScore ?? 0.985;
@@ -1982,7 +2588,12 @@ function geometryCandidatesFromBinary(binary, width, height, finders, threshold,
         },
         threshold,
         finderMethod: options.finderMethod,
+        alignmentProfile: options.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
         estimatedSize,
+        estimatedSizeH,
+        estimatedSizeV,
+        directionalModuleSizeH: moduleH,
+        directionalModuleSizeV: moduleV,
         score
       });
     }
@@ -2031,6 +2642,7 @@ function pushFinderDiagnostic(options, finderMethod, threshold, finders, geometr
       alignmentScore: geometry.alignment.score,
       alignmentGridScore: geometry.alignment.gridScore,
       finderMethod: geometry.finderMethod,
+      alignmentProfile: geometry.alignmentProfile,
       finders: {
         topLeft: { ...geometry.finders.topLeft },
         topRight: { ...geometry.finders.topRight },
@@ -2056,7 +2668,10 @@ function detectCodeGeometry(imageData, options = {}) {
       finderMethod: pass.finderMethod,
       perspectiveRecovery: recovery || options.perspectiveRecovery === true,
       alignmentThreshold: recovery ? 0.68 : 0.72,
-      alignmentGridThreshold: recovery ? 0.64 : 0.68
+      alignmentGridThreshold: recovery ? 0.64 : 0.68,
+      versionSearchLimit: recovery
+        ? (options.recoveryVersionSearchLimit ?? 9)
+        : (options.fastVersionSearchLimit ?? 4)
     };
     let geometries = geometryCandidatesFromBinary(
       pass.binary,
@@ -2064,9 +2679,38 @@ function detectCodeGeometry(imageData, options = {}) {
       height,
       finders,
       pass.threshold,
-      geometryOptions
+      { ...geometryOptions, alignmentProfile: ALIGNMENT_PROFILE_STANDARD_5 }
     );
 
+    // New format-v6 symbols use 5x5 alignment eyes. Only if that geometry does
+    // not validate do we spend a compatibility attempt on format-v5's compact
+    // 3x3 secondary markers. This keeps the modern path fast.
+    if (!geometries.length && options.legacyAlignmentRecovery !== false && finders.length >= 3) {
+      const legacyMethod = `${pass.finderMethod}-legacy-align`;
+      const legacyOptions = {
+        ...geometryOptions,
+        finderMethod: legacyMethod,
+        alignmentProfile: ALIGNMENT_PROFILE_LEGACY_3
+      };
+      geometries = geometryCandidatesFromBinary(
+        pass.binary,
+        width,
+        height,
+        finders,
+        pass.threshold,
+        legacyOptions
+      );
+      if (geometries.length) {
+        pushFinderDiagnostic(
+          { ...options, width, height, diagnosticLabel: `${options.diagnosticLabel ?? "normal"}-legacy-align` },
+          legacyMethod,
+          pass.threshold,
+          finders,
+          geometries
+        );
+      }
+    }
+
     pushFinderDiagnostic(
       { ...options, width, height },
       pass.finderMethod,
@@ -2113,9 +2757,123 @@ function detectCodeGeometry(imageData, options = {}) {
     finderMethod: "rgb-value-otsu",
     binary: valueInfo.binary,
     threshold: valueInfo.threshold,
-    detector: {}
+    detector: {
+      toleranceScale: options.finderToleranceScale ?? 1.0,
+      moduleSpreadLimit: options.finderModuleSpreadLimit ?? 0.45,
+      minConfirmations: options.finderMinConfirmations ?? 2,
+      diagonalCheck: false
+    }
   }, false);
+  const fastEstimateMatched = fast.geometries.some((geometry) =>
+    Math.abs(sizeForVersion(geometry.version) - geometry.estimatedSize) <= (options.fastDimensionAcceptance ?? 2.0)
+  );
+  if (fast.geometries.length && fastEstimateMatched) {
+    return fast.geometries.slice(0, maxCandidates);
+  }
+
+  // Seeing three finder patterns should immediately unlock perspective-aware
+  // geometry. The previous first pass used stricter near-front-facing triple
+  // limits, so a code could visibly have all three eyes yet still fall through
+  // into color recovery. Reuse the exact same binary/finders with broader
+  // projective geometry before doing any additional pixel processing.
+  if (fast.finders.length >= 3) {
+    const finderMethod = "rgb-value-otsu-projective";
+    const projectiveGeometries = geometryCandidatesFromBinary(
+      valueInfo.binary,
+      width,
+      height,
+      fast.finders,
+      valueInfo.threshold,
+      {
+        ...options,
+        finderMethod,
+        perspectiveRecovery: true,
+        alignmentThreshold: 0.60,
+        alignmentGridThreshold: 0.58,
+        versionSearchLimit: options.fastPerspectiveVersionSearchLimit ?? 4,
+        perspectiveAlignmentFineSeeds: options.fastPerspectiveAlignmentFineSeeds ?? 3,
+        perspectiveAlignmentMaxRadius: options.fastPerspectiveAlignmentMaxRadius ?? 12
+      }
+    );
+    pushFinderDiagnostic(
+      { ...options, width, height, diagnosticLabel: `${options.diagnosticLabel ?? "normal"}-projective` },
+      finderMethod,
+      valueInfo.threshold,
+      fast.finders,
+      projectiveGeometries
+    );
+    if (projectiveGeometries.length) return projectiveGeometries.slice(0, maxCandidates);
+  }
+
+  // Keep the original strict geometry as a fallback if the projective pass did
+  // not produce anything better. This preserves historical behavior while
+  // avoiding an early wrong-version lock-in when the directional size estimate
+  // clearly points at another version.
   if (fast.geometries.length) return fast.geometries.slice(0, maxCandidates);
+
+  // A local block threshold is part of the normal locator path, not the heavy
+  // color/damage recovery stack. It is especially effective when one finder is
+  // under a shadow or a phone-screen gradient while the other two are bright.
+  // At camera locator resolution this costs far less than escalating to a
+  // high-resolution scan or running full-frame Auto Color.
+  let localBinary = null;
+  if (options.localFinderThreshold !== false && fast.finders.length < 3) {
+    localBinary = hybridLocalBinary(valueInfo.gray, width, height);
+    if (localBinary) {
+      const local = evaluatePass({
+        finderMethod: "rgb-value-hybrid-local",
+        binary: localBinary,
+        threshold: null,
+        detector: {
+          toleranceScale: 1.10,
+          moduleSpreadLimit: 0.58,
+          diagonalCheck: false
+        }
+      }, true);
+      if (local.geometries.length) return local.geometries.slice(0, maxCandidates);
+    }
+  }
+
+  if (options.componentFinderFallback !== false && fast.finders.length < 3) {
+    for (const [binary, method] of [
+      [valueInfo.binary, "rgb-value-component"],
+      [localBinary, "rgb-value-hybrid-component"]
+    ]) {
+      if (!binary) continue;
+      const componentFinders = detectFinderCandidatesByComponents(binary, width, height, options);
+      const merged = clusterFinderCandidates([
+        ...fast.finders.map((finder) => ({ ...finder })),
+        ...componentFinders
+      ], 1);
+      if (merged.length < 3) continue;
+      const componentGeometries = geometryCandidatesFromBinary(
+        binary,
+        width,
+        height,
+        merged,
+        method.includes("hybrid") ? null : valueInfo.threshold,
+        {
+          ...options,
+          finderMethod: method,
+          perspectiveRecovery: true,
+          alignmentThreshold: 0.60,
+          alignmentGridThreshold: 0.58,
+          versionSearchLimit: options.fastPerspectiveVersionSearchLimit ?? 4,
+          perspectiveAlignmentFineSeeds: options.fastPerspectiveAlignmentFineSeeds ?? 3,
+          perspectiveAlignmentMaxRadius: options.fastPerspectiveAlignmentMaxRadius ?? 12
+        }
+      );
+      pushFinderDiagnostic(
+        { ...options, width, height, diagnosticLabel: `${options.diagnosticLabel ?? "normal"}-component` },
+        method,
+        method.includes("hybrid") ? null : valueInfo.threshold,
+        merged,
+        componentGeometries
+      );
+      if (componentGeometries.length) return componentGeometries.slice(0, maxCandidates);
+    }
+  }
+
   if (options.finderRecovery === false) return [];
 
   // If the clean threshold already found exactly two strong locators, try the
@@ -2390,6 +3148,21 @@ function autoColorImageData(imageData, options = {}) {
 }
 
 function buildAutoColorValueGray(imageData, options = {}) {
+  const canCache = imageData && typeof imageData === "object" && options.cache !== false;
+  const cacheKey = [
+    options.blackClip ?? 0.0001,
+    options.whiteClip ?? "default",
+    options.highlightPercentile ?? 0.95,
+    options.outputHighlight ?? 190,
+    options.analysisInset ?? 0,
+    options.minimumInputRange ?? 72,
+    options.targetSamples ?? "default"
+  ].join(":");
+  if (canCache) {
+    const cached = autoColorGrayCache.get(imageData)?.get(cacheKey);
+    if (cached) return cached;
+  }
+
   const levels = buildAutoColorLevels(imageData, options);
   const gray = new Uint8Array(imageData.width * imageData.height);
   for (let i = 0; i < gray.length; i++) {
@@ -2404,6 +3177,11 @@ function buildAutoColorValueGray(imageData, options = {}) {
       levels.mapChannel(b, 2)
     ));
   }
+  if (canCache) {
+    let entries = autoColorGrayCache.get(imageData);
+    if (!entries) autoColorGrayCache.set(imageData, entries = new Map());
+    entries.set(cacheKey, gray);
+  }
   return gray;
 }
 
@@ -2863,7 +3641,7 @@ const visionInternals = Object.freeze({
   luminance
 });
 
-return { computeHomography, projectPoint, detectCodeGeometry, autoColorImageData, autoToneContrastColorRgbGrid, autoToneContrastColorImageData, samplePerspectiveMatrix, samplePerspectiveTriangleMatrix, sampleObservedPalette, spatiallyNormalizeRgbGrid, rectifyImageData, findActiveBounds, sampleAxisAlignedGrid, sampleAxisAlignedTriangleGrid, visionInternals };
+return { installVisionAccelerator, buildBinary, detectFinderCandidates, chooseFinderTriples, searchAlignment, computeHomography, projectPoint, detectCodeGeometry, autoColorImageData, autoToneContrastColorRgbGrid, autoToneContrastColorImageData, samplePerspectiveMatrix, samplePerspectiveTriangleMatrix, sampleObservedPalette, spatiallyNormalizeRgbGrid, rectifyImageData, findActiveBounds, sampleAxisAlignedGrid, sampleAxisAlignedTriangleGrid, visionInternals };
 })();
 const __qqr_deflate_js = (function () {
 /**
@@ -5466,7 +6244,7 @@ return { compressBrotliPayload, decompressBrotliPayload, BROTLI_QUALITY_MIN, BRO
 })();
 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 { alignmentPatternCentersForVersion, alignmentPatternIsBlack, alignmentPatternRadius, ALIGNMENT_PROFILE_STANDARD_5, ALIGNMENT_PROFILE_LEGACY_3, sizeForVersion, versionFromSize } = __qqr_geometry_js;
 const { detectCodeGeometry, computeHomography, projectPoint, samplePerspectiveMatrix, samplePerspectiveTriangleMatrix, rectifyImageData, sampleObservedPalette, spatiallyNormalizeRgbGrid, autoToneContrastColorRgbGrid, autoToneContrastColorImageData, autoColorImageData, findActiveBounds, sampleAxisAlignedGrid, sampleAxisAlignedTriangleGrid } = __qqr_vision_js;
 const { decryptSecurePayload, encryptSecurePayload, inspectSecureEnvelope, SECURITY_MODES, SECURITY_ALGORITHMS, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, generateRaw256Key, normalizeRaw256Key, bytesToHex, estimateSecureEnvelopeOverhead } = __qqr_security_js;
 const { compressDeflatePayload: compressDeflateBytes, decompressDeflatePayload: decompressDeflateBytes, DEFAULT_DEFLATE_LEVEL, DEFLATE_LEVEL_MIN, DEFLATE_LEVEL_MAX } = __qqr_deflate_js;
@@ -5488,7 +6266,8 @@ const { compressBrotliPayload: compressBrotliBytes, decompressBrotliPayload: dec
  * - camera color calibration and image scanning
  */
 
-const FORMAT_VERSION = 5;
+const FORMAT_VERSION = 6;
+const LEGACY_FORMAT_VERSION = 5;
 const MIN_VERSION = 1;
 const MAX_VERSION = 40;
 const DEFAULT_ECC_LEVEL = "M";
@@ -6550,7 +7329,7 @@ function getEffectiveEcc(version, eccLevel) {
   return version === COMPACT_VERSION ? COMPACT_ECC_LEVELS[normalized] : ECC_LEVELS[normalized];
 }
 
-function makeHeader(payloadLength, flags, version) {
+function makeHeader(payloadLength, flags, version, formatVersion = FORMAT_VERSION) {
   assert(payloadLength >= 0 && payloadLength <= 0xffffffff, "Payload is too large.");
 
   if (version === COMPACT_VERSION) {
@@ -6565,7 +7344,7 @@ function makeHeader(payloadLength, flags, version) {
 
   const header = new Uint8Array(HEADER_BYTES);
   header.set(MAGIC, 0);
-  header[4] = FORMAT_VERSION;
+  header[4] = formatVersion;
   header[5] = flags & 0xff;
   header.set(u32be(payloadLength), 6);
   return header;
@@ -6587,14 +7366,22 @@ function parseHeader(header, version) {
     return { flags: header[1], payloadLength: header[2] };
   }
 
-  if (!magicMatches(header) || header[4] !== FORMAT_VERSION) {
+  const formatVersion = header[4];
+  if (!magicMatches(header) || (formatVersion !== FORMAT_VERSION && formatVersion !== LEGACY_FORMAT_VERSION)) {
     throw new Error("QuadQR magic/version mismatch.");
   }
-  return { flags: header[5], payloadLength: readU32be(header, 6) };
+  return { formatVersion, flags: header[5], payloadLength: readU32be(header, 6) };
 }
 
-function createLayout(version) {
+function alignmentProfileForFormat(formatVersion = FORMAT_VERSION) {
+  return formatVersion === LEGACY_FORMAT_VERSION
+    ? ALIGNMENT_PROFILE_LEGACY_3
+    : ALIGNMENT_PROFILE_STANDARD_5;
+}
+
+function createLayout(version, options = {}) {
   validateVersion(version);
+  const alignmentProfile = options.alignmentProfile ?? alignmentProfileForFormat(options.formatVersion ?? FORMAT_VERSION);
   const size = sizeForVersion(version);
   const matrix = make2D(size, CELL.WHITE);
   const reserved = make2D(size, false);
@@ -6722,7 +7509,7 @@ function createLayout(version) {
     reserveAndSet(row, 6, row % 2 === 0 ? CELL.BLACK : CELL.WHITE);
   }
 
-  const alignments = alignmentPatternCentersForVersion(version).map(drawAlignmentPattern);
+  const alignments = alignmentPatternCentersForVersion(version, { profile: alignmentProfile }).map(drawAlignmentPattern);
   const alignment = alignments[alignments.length - 1];
   const calibrationStrip = drawCalibrationStrip();
 
@@ -6746,6 +7533,7 @@ function createLayout(version) {
   return {
     version,
     size,
+    alignmentProfile,
     matrix,
     reserved,
     dataPositions,
@@ -7386,8 +8174,8 @@ function alignmentPatternMismatchRatio(matrix, pattern) {
   return mismatches / total;
 }
 
-function alignmentGridMismatchRatio(matrix, version) {
-  const patterns = alignmentPatternCentersForVersion(version);
+function alignmentGridMismatchRatio(matrix, version, alignmentProfile = ALIGNMENT_PROFILE_STANDARD_5) {
+  const patterns = alignmentPatternCentersForVersion(version, { profile: alignmentProfile });
   let weightedMismatch = 0;
   let totalWeight = 0;
   for (const pattern of patterns) {
@@ -7399,7 +8187,7 @@ function alignmentGridMismatchRatio(matrix, version) {
   return totalWeight ? weightedMismatch / totalWeight : 0;
 }
 
-function validateStructure(matrix, tolerance = 0) {
+function validateStructure(matrix, tolerance = 0, alignmentProfile = ALIGNMENT_PROFILE_STANDARD_5) {
   const size = matrix.length;
   if (size < 21 || matrix.some((row) => row.length !== size)) return false;
   const version = versionFromSize(size);
@@ -7412,11 +8200,11 @@ function validateStructure(matrix, tolerance = 0) {
   if (finderRatios.some((ratio) => ratio > tolerance)) return false;
 
   const alignmentTolerance = Math.max(tolerance, 0.12);
-  const primary = alignmentPatternCentersForVersion(version).at(-1);
+  const primary = alignmentPatternCentersForVersion(version, { profile: alignmentProfile }).at(-1);
   if (primary && alignmentPatternMismatchRatio(matrix, primary) > alignmentTolerance) {
     return false;
   }
-  if (alignmentGridMismatchRatio(matrix, version) > alignmentTolerance) return false;
+  if (alignmentGridMismatchRatio(matrix, version, alignmentProfile) > alignmentTolerance) return false;
   return true;
 }
 
@@ -7604,13 +8392,13 @@ function decodeProtectedBody(rawCells, payloadLength, eccLevel, version, rawConf
   };
 }
 
-function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = null, options = {}) {
+function decodeCanonicalWithProfile(matrix, rotation, tolerance = 0, confidenceMatrix = null, options = {}, alignmentProfile = ALIGNMENT_PROFILE_STANDARD_5) {
   const size = matrix.length;
   const version = versionFromSize(size);
   if (!version) throw new Error(`Unsupported matrix size ${size}.`);
-  if (!validateStructure(matrix, tolerance)) throw new Error("QuadQR finder/alignment structure does not match.");
+  if (!validateStructure(matrix, tolerance, alignmentProfile)) throw new Error("QuadQR finder/alignment structure does not match.");
 
-  const layout = createLayout(version);
+  const layout = createLayout(version, { alignmentProfile });
   const errors = [];
   const hintedEncoding = options.cellEncodingHint != null
     ? normalizeCellEncoding(options.cellEncodingHint)
@@ -7660,6 +8448,10 @@ function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = nul
           );
           const header = headerDecoded.header;
           const flags = headerDecoded.flags;
+          const decodedFormatVersion = headerDecoded.formatVersion ?? FORMAT_VERSION;
+          if (version >= 7 && alignmentProfileForFormat(decodedFormatVersion) !== alignmentProfile) {
+            throw new Error(`Format v${decodedFormatVersion} uses a different alignment profile.`);
+          }
           const declaredCellEncoding = cellEncodingFromFlags(flags);
           if (declaredCellEncoding !== cellEncoding) {
             throw new Error(`Header declares ${declaredCellEncoding}, not ${cellEncoding}.`);
@@ -7697,10 +8489,11 @@ function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = nul
           return {
             ok: true,
             format: "QuadQR",
-            formatVersion: FORMAT_VERSION,
+            formatVersion: decodedFormatVersion,
             version,
             size,
             alignmentPatterns: layout.alignments.length,
+            alignmentProfile,
             maskId,
             rotation,
             flags,
@@ -7748,17 +8541,42 @@ function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = nul
   throw new Error(`QuadQR decode failed. ${errors.join(" | ")}`);
 }
 
+function decodeCanonical(matrix, rotation, tolerance = 0, confidenceMatrix = null, options = {}) {
+  const hinted = options.alignmentProfileHint;
+  const profiles = hinted
+    ? [hinted]
+    : [ALIGNMENT_PROFILE_STANDARD_5, ALIGNMENT_PROFILE_LEGACY_3];
+  const errors = [];
+  for (const alignmentProfile of profiles) {
+    try {
+      return decodeCanonicalWithProfile(matrix, rotation, tolerance, confidenceMatrix, options, alignmentProfile);
+    } catch (error) {
+      errors.push(`${alignmentProfile}: ${error.message}`);
+    }
+  }
+  throw new Error(`QuadQR decode failed for all alignment profiles. ${errors.join(" | ")}`);
+}
+
 function trySoftMatrixDecode(matrix, alternatives, confidenceMatrix, degrees, tolerance, options = {}) {
   if (!alternatives || !confidenceMatrix || options.softDecoding === false) return null;
   const version = versionFromSize(matrix.length);
   if (!version) return null;
   const layout = createLayout(version);
+  const legacyLayout = createLayout(version, { alignmentProfile: ALIGNMENT_PROFILE_LEGACY_3 });
+  const softPositions = [];
+  const seenSoftPositions = new Set();
+  for (const [row, col] of [...layout.dataPositions, ...legacyLayout.dataPositions]) {
+    const key = `${row},${col}`;
+    if (seenSoftPositions.has(key)) continue;
+    seenSoftPositions.add(key);
+    softPositions.push([row, col]);
+  }
   const threshold = clampNumber(options.softDecodeConfidence ?? 0.72, 0.05, 0.95);
   const maxCells = Math.max(2, Math.min(16, Math.round(options.softDecodeMaxCells ?? 10)));
   const pairCells = Math.max(2, Math.min(maxCells, Math.round(options.softDecodePairCells ?? 6)));
   const ranked = [];
 
-  for (const [row, col] of layout.dataPositions) {
+  for (const [row, col] of softPositions) {
     const alternative = alternatives[row]?.[col];
     const confidence = confidenceMatrix[row]?.[col] ?? 1;
     if (!Number.isInteger(alternative) || alternative === matrix[row][col] || confidence > threshold) continue;
@@ -9111,27 +9929,31 @@ function paletteClassifierAttempts(observedPalette) {
 }
 
 function tryPerspectiveScan(imageData, options) {
-  const geometryCandidates = detectCodeGeometry(imageData, {
-    minVersion: options.minVersion ?? MIN_VERSION,
-    maxVersion: options.maxVersion ?? MAX_VERSION,
-    maxCandidates: options.maxGeometryCandidates ?? 8,
-    finderRecovery: options.finderRecovery,
-    finderAutoColorBlackClip: options.finderAutoColorBlackClip,
-    finderAutoColorWhiteClip: options.finderAutoColorWhiteClip,
-    finderAutoColorHighlightPercentile: options.finderAutoColorHighlightPercentile,
-    finderAutoColorOutputHighlight: options.finderAutoColorOutputHighlight,
-    finderAutoColorAnalysisInset: options.finderAutoColorAnalysisInset,
-    finderAutoColorMinimumInputRange: options.finderAutoColorMinimumInputRange,
-    finderAutoColorTargetSamples: options.finderAutoColorTargetSamples,
-    preciseAlignment: options.preciseAlignment,
-    diagnostics: options._visionDiagnostics,
-    diagnosticLabel: options._diagnosticLabel ?? "normal"
-  });
+  const geometryCandidates = Array.isArray(options._geometryCandidatesOverride) && options._geometryCandidatesOverride.length
+    ? options._geometryCandidatesOverride
+    : detectCodeGeometry(imageData, {
+        minVersion: options.minVersion ?? MIN_VERSION,
+        maxVersion: options.maxVersion ?? MAX_VERSION,
+        maxCandidates: options.maxGeometryCandidates ?? 8,
+        finderRecovery: options.finderRecovery,
+        finderAutoColorBlackClip: options.finderAutoColorBlackClip,
+        finderAutoColorWhiteClip: options.finderAutoColorWhiteClip,
+        finderAutoColorHighlightPercentile: options.finderAutoColorHighlightPercentile,
+        finderAutoColorOutputHighlight: options.finderAutoColorOutputHighlight,
+        finderAutoColorAnalysisInset: options.finderAutoColorAnalysisInset,
+        finderAutoColorMinimumInputRange: options.finderAutoColorMinimumInputRange,
+        finderAutoColorTargetSamples: options.finderAutoColorTargetSamples,
+        preciseAlignment: options.preciseAlignment,
+        diagnostics: options._visionDiagnostics,
+        diagnosticLabel: options._diagnosticLabel ?? "normal"
+      });
   if (Array.isArray(options._geometryCollector)) options._geometryCollector.push(...geometryCandidates);
   const results = [];
 
   for (const geometry of geometryCandidates) {
-    const layout = createLayout(geometry.version);
+    const layout = createLayout(geometry.version, {
+      alignmentProfile: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5
+    });
     const sampleProfiles = [{
       sampleMode: options.sampleMode ?? "cross",
       sampleRadius: options.sampleRadius ?? 0.16,
@@ -9168,7 +9990,7 @@ function tryPerspectiveScan(imageData, options) {
         continue;
       }
 
-      const tryAttempt = (attempt, rgbGrid, metadata = {}) => {
+      const tryAttempt = (attempt, rgbGrid, metadata = {}, allowSoftDecoding = options.softDecoding !== false) => {
         const activeObservedPalette = metadata.observedPalette ?? observedPalette;
         const activeSamplingMode = metadata.samplingMode ?? profile.sampleMode;
         const classified = classifySampledRgbGrid(rgbGrid, attempt.classifier, layout);
@@ -9193,6 +10015,9 @@ function tryPerspectiveScan(imageData, options) {
             structureTolerance: options.structureTolerance ?? 0.18,
             cellConfidence: classified.confidence,
             cellAlternatives: classified.alternatives,
+            cellEncodingHint: CELL_ENCODINGS.RGBW,
+            alignmentProfileHint: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
+            softDecoding: allowSoftDecoding,
             maxErasureConfidence: options.maxErasureConfidence
           });
           if (decoded.version !== geometry.version) return false;
@@ -9221,7 +10046,7 @@ function tryPerspectiveScan(imageData, options) {
         }
       };
 
-      const tryTriangleAttempt = (attempt, metadata = {}) => {
+      const tryTriangleAttempt = (attempt, metadata = {}, allowSoftDecoding = options.softDecoding !== false) => {
         if (!triangleSampled?.triangleGrid) return false;
         const activeObservedPalette = metadata.observedPalette ?? observedPalette;
         const activeSamplingMode = metadata.samplingMode ?? `${profile.sampleMode}-triangle16`;
@@ -9254,6 +10079,8 @@ function tryPerspectiveScan(imageData, options) {
             cellConfidence: classified.confidence,
             cellAlternatives: classified.alternatives,
             cellEncodingHint: CELL_ENCODINGS.TRIANGLE16,
+            alignmentProfileHint: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
+            softDecoding: allowSoftDecoding,
             maxErasureConfidence: options.maxErasureConfidence
           });
           if (decoded.version !== geometry.version) return false;
@@ -9282,21 +10109,38 @@ function tryPerspectiveScan(imageData, options) {
       // Fast path: preserve the original observed-RGB classifier first, then
       // try per-channel white balancing. Most clean frames stop here without
       // paying for the more expensive spatial normalization fallback.
-      for (const attempt of paletteClassifierAttempts(observedPalette)) {
-        if (tryAttempt(attempt, sampled.rgbGrid) || tryTriangleAttempt(attempt)) {
+      const basePaletteAttempts = paletteClassifierAttempts(observedPalette);
+      for (const attempt of basePaletteAttempts) {
+        if (tryAttempt(attempt, sampled.rgbGrid, {}, false) || tryTriangleAttempt(attempt, {}, false)) {
           geometryDecoded = true;
           break;
         }
       }
+      // Spectrum ECC soft decoding is intentionally deferred until every cheap
+      // hard classifier has had a chance. This preserves the exact recovery
+      // candidates while avoiding expensive second-hypothesis RS searches when
+      // a later normal color model can decode the frame immediately.
+      if (!geometryDecoded && options.softDecoding !== false) {
+        for (const attempt of basePaletteAttempts) {
+          if (tryAttempt(attempt, sampled.rgbGrid, {}, true) || tryTriangleAttempt(attempt, {}, true)) {
+            geometryDecoded = true;
+            break;
+          }
+        }
+      }
 
       if (!geometryDecoded && options.spatialColorNormalization !== false) {
         try {
           const normalizedGrid = spatiallyNormalizeRgbGrid(sampled.rgbGrid, layout.calibration);
           const normalizedPalette = sampleObservedPalette(normalizedGrid, layout.calibration, { robust: true });
-          geometryDecoded = tryAttempt({
+          const spatialAttempt = {
             classifier: classifierFromPaletteRgb(normalizedPalette, "raw"),
             colorNormalization: "spatial-white-balanced"
-          }, normalizedGrid);
+          };
+          geometryDecoded = tryAttempt(spatialAttempt, normalizedGrid, {}, false);
+          if (!geometryDecoded && options.softDecoding !== false) {
+            geometryDecoded = tryAttempt(spatialAttempt, normalizedGrid, {}, true);
+          }
         } catch {
           // Continue to the recovery profile below.
         }
@@ -9313,20 +10157,32 @@ function tryPerspectiveScan(imageData, options) {
             saturation: options.autoEnhanceSaturation
           });
           const enhancedPalette = sampleObservedPalette(enhancedGrid, layout.calibration, { robust: true });
-          for (const attempt of paletteClassifierAttempts(enhancedPalette)) {
-            const recoveredAttempt = {
-              ...attempt,
-              colorNormalization: `auto-tone-contrast-color/${attempt.colorNormalization}`
-            };
+          const enhancedAttempts = paletteClassifierAttempts(enhancedPalette).map((attempt) => ({
+            ...attempt,
+            colorNormalization: `auto-tone-contrast-color/${attempt.colorNormalization}`
+          }));
+          for (const recoveredAttempt of enhancedAttempts) {
             if (tryAttempt(recoveredAttempt, enhancedGrid, {
               observedPalette: enhancedPalette,
               autoEnhanced: true,
               recoveryMode: "module-grid-auto-tone-contrast-color"
-            })) {
+            }, false)) {
               geometryDecoded = true;
               break;
             }
           }
+          if (!geometryDecoded && options.softDecoding !== false) {
+            for (const recoveredAttempt of enhancedAttempts) {
+              if (tryAttempt(recoveredAttempt, enhancedGrid, {
+                observedPalette: enhancedPalette,
+                autoEnhanced: true,
+                recoveryMode: "module-grid-auto-tone-contrast-color"
+              }, true)) {
+                geometryDecoded = true;
+                break;
+              }
+            }
+          }
         } catch {
           // Continue to the QR-region pixel recovery below.
         }
@@ -9371,21 +10227,34 @@ function tryPerspectiveScan(imageData, options) {
             layout.calibration,
             { robust: true }
           );
-          for (const attempt of paletteClassifierAttempts(enhancedPalette)) {
-            const recoveredAttempt = {
-              ...attempt,
-              colorNormalization: `rectified-auto-tone-contrast-color/${attempt.colorNormalization}`
-            };
+          const rectifiedAttempts = paletteClassifierAttempts(enhancedPalette).map((attempt) => ({
+            ...attempt,
+            colorNormalization: `rectified-auto-tone-contrast-color/${attempt.colorNormalization}`
+          }));
+          for (const recoveredAttempt of rectifiedAttempts) {
             if (tryAttempt(recoveredAttempt, enhancedSampled.rgbGrid, {
               observedPalette: enhancedPalette,
               samplingMode: "rectified-auto-enhance",
               autoEnhanced: true,
               recoveryMode: "rectified-auto-tone-contrast-color"
-            })) {
+            }, false)) {
               geometryDecoded = true;
               break;
             }
           }
+          if (!geometryDecoded && options.softDecoding !== false) {
+            for (const recoveredAttempt of rectifiedAttempts) {
+              if (tryAttempt(recoveredAttempt, enhancedSampled.rgbGrid, {
+                observedPalette: enhancedPalette,
+                samplingMode: "rectified-auto-enhance",
+                autoEnhanced: true,
+                recoveryMode: "rectified-auto-tone-contrast-color"
+              }, true)) {
+                geometryDecoded = true;
+                break;
+              }
+            }
+          }
         } catch {
           // Geometry refinement remains available as the final bounded fallback.
         }
@@ -9394,6 +10263,15 @@ function tryPerspectiveScan(imageData, options) {
       if (geometryDecoded) break;
     }
 
+    // A decoded QuadQR has already passed structural validation, Spectrum ECC,
+    // and the payload CRC. Continuing through every lower-ranked geometry after
+    // that point used to spend most of the camera scan time proving the same
+    // frame again. Return the first authenticated decode immediately. An opt-in
+    // diagnostic mode can still collect every successful geometry if needed.
+    if (geometryDecoded && options.collectAllGeometryResults !== true) {
+      return results[results.length - 1] ?? null;
+    }
+
     // Slow-path geometry micro-refinement. Finder/alignment detection can be
     // correct while a soft-focus or smeared camera shifts the effective module
     // centres by a small fraction of a cell. Clean scans never reach this code.
@@ -9540,6 +10418,7 @@ function tryPerspectiveScan(imageData, options) {
             cellConfidence: candidate.classified.confidence,
             cellAlternatives: candidate.classified.alternatives,
             cellEncodingHint: candidate.cellEncoding,
+            alignmentProfileHint: geometry.alignmentProfile ?? ALIGNMENT_PROFILE_STANDARD_5,
             maxErasureConfidence: options.maxErasureConfidence
           });
           if (decoded.version !== geometry.version) continue;
@@ -9568,6 +10447,11 @@ function tryPerspectiveScan(imageData, options) {
         }
       }
     }
+
+
+    if (geometryDecoded && options.collectAllGeometryResults !== true) {
+      return results[results.length - 1] ?? null;
+    }
   }
 
   results.sort((a, b) =>
@@ -10390,6 +11274,38 @@ function scanImageData(imageData, options = {}) {
   };
 
   if (options.perspective !== false) {
+    const geometryHints = Array.isArray(options._geometryHints)
+      ? options._geometryHints.filter((item) => item?.homography && Number.isInteger(item.version)).slice(0, 2)
+      : [];
+    if (geometryHints.length) {
+      try {
+        const hinted = tryPerspectiveScan(imageData, {
+          ...scanOptions,
+          _diagnosticLabel: options._diagnosticLabel ? `${options._diagnosticLabel}-geometry-reuse` : "geometry-reuse",
+          _geometryCandidatesOverride: geometryHints,
+          _geometryCollector: [],
+          _observationCollector: [],
+          adaptiveSampling: options._geometryReuseAdaptiveSampling ?? false,
+          geometryRefinement: false
+        });
+        if (hinted) {
+          geometryCollector.push(hinted.geometry ?? geometryHints[0]);
+          return decorateScanResult({
+            ...hinted,
+            geometryReused: true,
+            recoveryMode: hinted.recoveryMode ?? "geometry-reuse"
+          }, debugContext, options);
+        }
+      } catch {
+        // A stale geometry hint is expected when the camera/code moves. The
+        // camera worker can request a hint-only attempt when it is reusing
+        // low-resolution locator geometry on a higher-detail frame.
+      }
+      if (options._geometryHintOnly === true) {
+        throw new Error("Geometry hint did not decode this frame.");
+      }
+    }
+
     const perspective = tryPerspectiveScan(imageData, scanOptions);
     if (perspective) return decorateScanResult(perspective, debugContext, options);
   }
@@ -10715,6 +11631,21 @@ function scanVideoFrame(video, options = {}) {
       _visionDiagnostics: visionDiagnostics
     });
     normalizeFrameDiagnostics(options._frameDiagnostics, source, width, height, visionDiagnostics);
+    if (options._frameDiagnostics && result?.geometry && !options._frameDiagnostics.geometry) {
+      const geometry = result.geometry;
+      options._frameDiagnostics.geometry = geometry;
+      options._frameDiagnostics.geometryReused = Boolean(result.geometryReused);
+      if (geometry.finders) {
+        const reusedFinders = [
+          geometry.finders.topLeft,
+          geometry.finders.topRight,
+          geometry.finders.bottomLeft
+        ].filter(Boolean);
+        options._frameDiagnostics.finders = reusedFinders;
+        options._frameDiagnostics.finderCount = reusedFinders.length;
+        if (result.geometryReused) options._frameDiagnostics.finderMethod = "geometry-reuse";
+      }
+    }
     if (!source.cropped) return result;
     return {
       ...result,
@@ -10867,7 +11798,7 @@ async function improveCameraTrack(stream) {
   }
 }
 
-async function startCameraScanner(video, options = {}) {
+async function startCameraScannerMainThread(video, options = {}) {
   assert(typeof navigator !== "undefined" && navigator.mediaDevices?.getUserMedia, "Camera API is unavailable.");
   assert(video, "A video element is required.");
 
@@ -10876,8 +11807,8 @@ async function startCameraScanner(video, options = {}) {
       audio: false,
       video: {
         facingMode: { ideal: "environment" },
-        width: { ideal: 1920 },
-        height: { ideal: 1080 },
+        width: { ideal: 1280 },
+        height: { ideal: 720 },
         frameRate: { ideal: 30 }
       }
     }
@@ -10889,7 +11820,11 @@ async function startCameraScanner(video, options = {}) {
   video.muted = true;
   await video.play();
 
-  const scanInterval = Math.max(80, options.scanInterval ?? 180);
+  // Keep scanning responsive without queueing stale camera frames. The old
+  // 180 ms post-scan timeout made effective cadence equal scan time + 180 ms.
+  // The scheduler below measures from scan start and uses real video frames
+  // when requestVideoFrameCallback() is available.
+  const scanInterval = Math.max(24, Number(options.scanInterval ?? 80));
   const scratchCanvas = document.createElement("canvas");
   const highResolutionCanvas = document.createElement("canvas");
   const multiFrameEnabled = options.multiFrame !== false;
@@ -10900,16 +11835,23 @@ async function startCameraScanner(video, options = {}) {
   const cameraAutoEnhanceEvery = Math.max(1, Math.round(options.cameraAutoEnhanceEvery ?? 2));
   const cameraFinderRecoveryEvery = Math.max(1, Math.round(options.cameraFinderRecoveryEvery ?? 2));
   const cameraHighResolutionEvery = Math.max(1, Math.round(options.cameraHighResolutionEvery ?? 2));
-  const baseCameraMaxDimension = Math.max(480, Math.round(options.maxDimension ?? 1080));
+  const baseCameraMaxDimension = Math.max(480, Math.round(options.maxDimension ?? 640));
   const cameraHighResolutionMaxDimension = Math.max(
     baseCameraMaxDimension,
-    Math.round(options.cameraHighResolutionMaxDimension ?? 1600)
+    Math.round(options.cameraHighResolutionMaxDimension ?? 960)
   );
   let missStreak = 0;
   let stopped = false;
   let busy = false;
   let timer = null;
+  let frameCallbackId = null;
+  let lastScanStartedAt = -Infinity;
   let frameNumber = 0;
+  let cameraGeometryHint = null;
+  let cameraGeometryHintMisses = 0;
+  const cameraGeometryReuseMaxMisses = Math.max(1, Math.round(options.cameraGeometryReuseMaxMisses ?? 5));
+  const useVideoFrameCallback = options.useVideoFrameCallback !== false &&
+    typeof video.requestVideoFrameCallback === "function";
 
   const diagnosticsEnabled = typeof options.onDiagnostic === "function";
   const emitDiagnostic = (event) => {
@@ -10945,6 +11887,12 @@ async function startCameraScanner(video, options = {}) {
   const stop = () => {
     stopped = true;
     if (timer) clearTimeout(timer);
+    if (frameCallbackId != null && typeof video.cancelVideoFrameCallback === "function") {
+      try { video.cancelVideoFrameCallback(frameCallbackId); } catch {}
+    }
+    timer = null;
+    frameCallbackId = null;
+    cameraGeometryHint = null;
     observationHistory.clear();
     for (const track of stream.getTracks()) track.stop();
     if (video.srcObject === stream) video.srcObject = null;
@@ -10953,9 +11901,30 @@ async function startCameraScanner(video, options = {}) {
   const scanNow = () => scanVideoFrame(video, {
     ...options,
     maxDimension: baseCameraMaxDimension,
-    canvas: scratchCanvas
+    canvas: scratchCanvas,
+    _geometryHints: options.cameraGeometryReuse === false || !cameraGeometryHint ? undefined : [cameraGeometryHint]
   });
 
+  const updateCameraGeometryHint = (frameDiagnostics, result = null) => {
+    if (options.cameraGeometryReuse === false) {
+      cameraGeometryHint = null;
+      return;
+    }
+    const geometry = result?.geometry ?? frameDiagnostics?.geometry ?? null;
+    if (geometry?.homography && Number.isInteger(geometry.version)) {
+      cameraGeometryHint = geometry;
+      cameraGeometryHintMisses = 0;
+      return;
+    }
+    if (cameraGeometryHint) {
+      cameraGeometryHintMisses++;
+      if (cameraGeometryHintMisses >= cameraGeometryReuseMaxMisses) {
+        cameraGeometryHint = null;
+        cameraGeometryHintMisses = 0;
+      }
+    }
+  };
+
   const emitResult = (result, capturedFrame = null, diagnostic = null) => {
     const frameMeta = capturedFrame?.imageData ? {
       frame: frameNumber,
@@ -11033,6 +12002,33 @@ async function startCameraScanner(video, options = {}) {
     }
   };
 
+  const scheduleNextScan = () => {
+    if (stopped) return;
+    const runWhenDue = () => {
+      frameCallbackId = null;
+      if (stopped) return;
+      const remaining = scanInterval - (nowMs() - lastScanStartedAt);
+      if (remaining > 1) {
+        timer = setTimeout(() => {
+          timer = null;
+          scheduleNextScan();
+        }, remaining);
+        return;
+      }
+      void loop();
+    };
+
+    if (useVideoFrameCallback) {
+      frameCallbackId = video.requestVideoFrameCallback(runWhenDue);
+    } else {
+      const remaining = Math.max(0, scanInterval - (nowMs() - lastScanStartedAt));
+      timer = setTimeout(() => {
+        timer = null;
+        runWhenDue();
+      }, remaining);
+    }
+  };
+
   const loop = async () => {
     if (stopped) return;
     if (!busy && video.readyState >= 2) {
@@ -11042,6 +12038,7 @@ async function startCameraScanner(video, options = {}) {
       const frameDiagnostics = {};
       const capturedFrame = {};
       const frameStarted = nowMs();
+      lastScanStartedAt = frameStarted;
       let allowAutoEnhance = false;
       let allowFinderRecovery = false;
       try {
@@ -11069,11 +12066,13 @@ async function startCameraScanner(video, options = {}) {
           fullFrameAutoEnhanceRecovery: options.fullFrameAutoEnhanceRecovery ?? false,
           maxDimension: baseCameraMaxDimension,
           canvas: scratchCanvas,
+          _geometryHints: options.cameraGeometryReuse === false || !cameraGeometryHint ? undefined : [cameraGeometryHint],
           _capturedFrame: capturedFrame,
           _observationCollector: observations,
           _frameDiagnostics: frameDiagnostics
         });
         const elapsedMs = nowMs() - frameStarted;
+        updateCameraGeometryHint(frameDiagnostics, result);
         emitDiagnostic({
           type: "frame",
           state: "decoded",
@@ -11095,6 +12094,7 @@ async function startCameraScanner(video, options = {}) {
         if (emitResult(result, capturedFrame, frameDiagnostics)) return;
       } catch (error) {
         missStreak++;
+        updateCameraGeometryHint(frameDiagnostics);
         const fastElapsedMs = nowMs() - frameStarted;
         emitDiagnostic({
           type: "frame",
@@ -11110,7 +12110,7 @@ async function startCameraScanner(video, options = {}) {
 
         // Geometry-aware high-resolution retry. A dense QuadQR can look large
         // enough in the preview while each individual module has become too
-        // small after the normal 1080 px scanner cap. If the fast pass already
+        // small after the normal 640 px scanner cap. If the fast pass already
         // sees at least two convincing finders, spend one bounded retry on a
         // higher-resolution copy of the visible camera ROI. Empty frames and
         // ordinary small codes never pay this cost.
@@ -11416,13 +12416,570 @@ async function startCameraScanner(video, options = {}) {
         busy = false;
       }
     }
-    timer = setTimeout(loop, scanInterval);
+    scheduleNextScan();
   };
 
-  timer = setTimeout(loop, 0);
+  scheduleNextScan();
   return { stream, stop, scanNow, video };
 }
 
+
+function cameraWorkerSupported(options = {}) {
+  if (options.cameraWorker === false) return false;
+  return typeof Worker === "function" &&
+    typeof createImageBitmap === "function" &&
+    typeof OffscreenCanvas === "function";
+}
+
+function serializableCameraWorkerOptions(options = {}) {
+  const skip = new Set([
+    "canvas",
+    "constraints",
+    "onDecode",
+    "onDiagnostic",
+    "onResult",
+    "onScanMiss",
+    "cameraWorkerUrl"
+  ]);
+  const out = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (skip.has(key) || typeof value === "function" || value == null) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+      continue;
+    }
+    if (Array.isArray(value)) {
+      out[key] = value.map((item) => {
+        if (item && typeof item === "object") return { ...item };
+        return item;
+      });
+      continue;
+    }
+    if (Object.getPrototypeOf(value) === Object.prototype) out[key] = { ...value };
+  }
+  return out;
+}
+
+function resolveCameraWorkerUrl(options = {}) {
+  if (options.cameraWorkerUrl) {
+    return new URL(
+      options.cameraWorkerUrl,
+      typeof document !== "undefined" ? document.baseURI : (__qqrScriptSrc || (typeof location !== 'undefined' ? location.href : ''))
+    );
+  }
+  return new URL("./camera-scanner-worker.js", (__qqrScriptSrc || (typeof location !== 'undefined' ? location.href : '')));
+}
+
+async function initializeCameraWorker(options = {}) {
+  const worker = new Worker(resolveCameraWorkerUrl(options), {
+    type: "module",
+    name: "quadqr-camera-scanner"
+  });
+  let sequence = 0;
+  const pending = new Map();
+  let fatalError = null;
+
+  const rejectPending = (error) => {
+    fatalError = error instanceof Error ? error : new Error(String(error));
+    for (const { reject } of pending.values()) reject(fatalError);
+    pending.clear();
+  };
+
+  worker.addEventListener("message", (event) => {
+    const message = event.data ?? {};
+    const entry = pending.get(message.id);
+    if (!entry) return;
+    pending.delete(message.id);
+    if (message.ok) entry.resolve(message.result);
+    else {
+      const error = new Error(message.error?.message ?? "QuadQR camera worker failed.");
+      error.name = message.error?.name ?? "Error";
+      error.stack = message.error?.stack ?? error.stack;
+      error.debug = message.error?.debug ?? null;
+      entry.reject(error);
+    }
+  });
+  worker.addEventListener("error", (event) => {
+    rejectPending(new Error(event?.message || "QuadQR camera worker crashed."));
+  });
+  worker.addEventListener("messageerror", () => {
+    rejectPending(new Error("QuadQR camera worker returned an unreadable message."));
+  });
+
+  const request = (type, payload = {}, transfer = []) => {
+    if (fatalError) return Promise.reject(fatalError);
+    const id = `qqr-camera-${++sequence}`;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      try {
+        worker.postMessage({ id, type, ...payload }, transfer);
+      } catch (error) {
+        pending.delete(id);
+        reject(error);
+      }
+    });
+  };
+
+  try {
+    const state = await request("init", { options: serializableCameraWorkerOptions(options) });
+    if (!state?.offscreenCanvas) throw new Error("OffscreenCanvas is unavailable in the QuadQR camera worker.");
+    return {
+      worker,
+      state,
+      request,
+      terminate() {
+        rejectPending(new Error("QuadQR camera worker stopped."));
+        worker.terminate();
+      }
+    };
+  } catch (error) {
+    worker.terminate();
+    throw error;
+  }
+}
+
+async function captureCameraBitmap(video, source, maxDimension) {
+  const cap = Math.max(1, Math.round(maxDimension));
+  const videoWidth = Math.max(1, Math.round(video.videoWidth || source.width || 1));
+  const videoHeight = Math.max(1, Math.round(video.videoHeight || source.height || 1));
+  const sx = clampNumber(Math.round(source.x || 0), 0, Math.max(0, videoWidth - 1));
+  const sy = clampNumber(Math.round(source.y || 0), 0, Math.max(0, videoHeight - 1));
+  const sw = Math.max(1, Math.min(videoWidth - sx, Math.round(source.width || videoWidth)));
+  const sh = Math.max(1, Math.min(videoHeight - sy, Math.round(source.height || videoHeight)));
+  const scale = Math.min(1, cap / Math.max(sw, sh));
+  const width = Math.max(1, Math.round(sw * scale));
+  const height = Math.max(1, Math.round(sh * scale));
+
+  // Crop and resize before crossing the worker boundary. Previously every
+  // 640px scan transferred a full 1080p camera bitmap and only then shrank it
+  // inside OffscreenCanvas. On phones that creates unnecessary GPU/memory
+  // pressure and can delay fresh-frame acquisition even though decoding is
+  // off-thread. The fallback preserves compatibility with browsers that do not
+  // implement the resize overload for video-backed ImageBitmap creation.
+  try {
+    const bitmap = await createImageBitmap(video, sx, sy, sw, sh, {
+      resizeWidth: width,
+      resizeHeight: height,
+      resizeQuality: "medium"
+    });
+    return {
+      bitmap,
+      source: { x: 0, y: 0, width: bitmap.width, height: bitmap.height, cropped: Boolean(source.cropped) },
+      originalSource: { ...source },
+      preScaled: true
+    };
+  } catch {
+    const bitmap = await createImageBitmap(video);
+    return {
+      bitmap,
+      source: { ...source },
+      originalSource: { ...source },
+      preScaled: false
+    };
+  }
+}
+
+function maximumFinderCount(workerResult) {
+  let count = 0;
+  for (const diagnostic of workerResult?.diagnostics ?? []) {
+    count = Math.max(
+      count,
+      Number(diagnostic?.finderCount) || 0,
+      Number(diagnostic?.bestPass?.finderCount) || 0
+    );
+    for (const pass of diagnostic?.finderPasses ?? []) {
+      count = Math.max(count, Number(pass?.finderCount) || 0);
+    }
+  }
+  return count;
+}
+
+async function startCameraScannerWorker(video, options = {}) {
+  assert(typeof navigator !== "undefined" && navigator.mediaDevices?.getUserMedia, "Camera API is unavailable.");
+  assert(video, "A video element is required.");
+
+  // Keep fresh-frame scanning independent from the expensive damaged/color
+  // recovery pipeline. Finder detection itself remains JavaScript; WASM is
+  // only an optional grayscale/binary + CRC accelerator beneath both workers.
+  // The fast worker can therefore inspect the newest frame even while the
+  // recovery worker is spending hundreds of milliseconds on an older difficult
+  // frame. No recovery method is removed.
+  const fastWorkerOptions = {
+    ...options,
+    cameraPipelineMode: "fast",
+    cameraHighResolutionRecovery: false,
+    cameraAutoColorRecovery: false,
+    autoEnhanceRecovery: false,
+    fullFrameAutoEnhanceRecovery: false,
+    multiFrame: false
+  };
+  const fastWorkerClient = await initializeCameraWorker(fastWorkerOptions);
+
+  let stream = null;
+  try {
+    stream = await navigator.mediaDevices.getUserMedia(
+      options.constraints ?? {
+        audio: false,
+        video: {
+          facingMode: { ideal: "environment" },
+          width: { ideal: 1280 },
+          height: { ideal: 720 },
+          frameRate: { ideal: 30 }
+        }
+      }
+    );
+    await improveCameraTrack(stream);
+
+    video.srcObject = stream;
+    video.setAttribute("playsinline", "");
+    video.muted = true;
+    await video.play();
+  } catch (error) {
+    fastWorkerClient.terminate();
+    for (const track of stream?.getTracks?.() ?? []) track.stop();
+    if (video.srcObject === stream) video.srcObject = null;
+    throw error;
+  }
+
+  const scanInterval = Math.max(24, Number(options.scanInterval ?? 33));
+  const fastCaptureMaxDimension = Math.max(480, Math.round(options.maxDimension ?? 640));
+  const recoveryCaptureMaxDimension = Math.max(
+    fastCaptureMaxDimension,
+    Math.round(options.cameraHighResolutionMaxDimension ?? 960)
+  );
+  const recoveryStrongFinderInterval = Math.max(80, Number(options.cameraRecoveryStrongFinderInterval ?? 120));
+  const recoveryWeakFinderInterval = Math.max(recoveryStrongFinderInterval, Number(options.cameraRecoveryWeakFinderInterval ?? 260));
+  const recoveryNoFinderInterval = Math.max(recoveryWeakFinderInterval, Number(options.cameraRecoveryNoFinderInterval ?? 850));
+  const useVideoFrameCallback = options.useVideoFrameCallback !== false &&
+    typeof video.requestVideoFrameCallback === "function";
+
+  let stopped = false;
+  let busy = false;
+  let recoveryBusy = false;
+  let recoveryWorkerClient = null;
+  let recoveryWorkerPromise = null;
+  let recoveryWorkerFailed = false;
+  let timer = null;
+  let frameCallbackId = null;
+  let lastScanStartedAt = -Infinity;
+  let lastRecoveryStartedAt = -Infinity;
+  let frameNumber = 0;
+  let requestToken = 0;
+  let recoveryToken = 0;
+
+  const diagnosticsEnabled = typeof options.onDiagnostic === "function";
+  const emitDiagnostic = (event) => {
+    if (!diagnosticsEnabled) return;
+    try {
+      options.onDiagnostic({
+        timestamp: Date.now(),
+        frame: event?.frame ?? frameNumber,
+        cameraWorker: true,
+        ...event
+      });
+    } catch {
+      // Diagnostics are UI-only and must never interrupt scanning.
+    }
+  };
+
+  const ensureRecoveryWorker = async () => {
+    if (recoveryWorkerClient) return recoveryWorkerClient;
+    if (recoveryWorkerFailed) return null;
+    if (!recoveryWorkerPromise) {
+      recoveryWorkerPromise = initializeCameraWorker({ ...options, cameraPipelineMode: "full" })
+        .then((client) => {
+          if (stopped) {
+            client.terminate();
+            return null;
+          }
+          recoveryWorkerClient = client;
+          return client;
+        })
+        .catch((error) => {
+          recoveryWorkerFailed = true;
+          emitDiagnostic({
+            type: "recovery-worker-error",
+            state: "fallback",
+            method: "camera-fast-worker",
+            message: `Parallel recovery worker unavailable · fast scanner remains active (${error?.message ?? String(error)})`
+          });
+          return null;
+        })
+        .finally(() => {
+          recoveryWorkerPromise = null;
+        });
+    }
+    return recoveryWorkerPromise;
+  };
+
+  const track = stream.getVideoTracks?.()[0];
+  const settings = track?.getSettings?.() ?? {};
+  emitDiagnostic({
+    type: "camera-ready",
+    method: "camera-dual-worker",
+    message: `Camera ready · ${settings.width ?? video.videoWidth}×${settings.height ?? video.videoHeight} · fast fresh-frame scanner + parallel recovery`,
+    camera: {
+      width: settings.width ?? video.videoWidth,
+      height: settings.height ?? video.videoHeight,
+      frameRate: settings.frameRate ?? null,
+      facingMode: settings.facingMode ?? null
+    },
+    worker: fastWorkerClient.state,
+    scanMaxDimension: fastCaptureMaxDimension,
+    recoveryMaxDimension: recoveryCaptureMaxDimension
+  });
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    requestToken++;
+    recoveryToken++;
+    if (timer) clearTimeout(timer);
+    if (frameCallbackId != null && typeof video.cancelVideoFrameCallback === "function") {
+      try { video.cancelVideoFrameCallback(frameCallbackId); } catch {}
+    }
+    timer = null;
+    frameCallbackId = null;
+    fastWorkerClient.terminate();
+    if (recoveryWorkerClient) {
+      recoveryWorkerClient.terminate();
+      recoveryWorkerClient = null;
+    } else if (recoveryWorkerPromise) {
+      void recoveryWorkerPromise.then((client) => client?.terminate()).catch(() => {});
+    }
+    for (const cameraTrack of stream.getTracks()) cameraTrack.stop();
+    if (video.srcObject === stream) video.srcObject = null;
+  };
+
+  // Preserve the historical immediate/manual helper as a synchronous scan of
+  // the current video element. The continuous scanner itself stays off-thread.
+  const scanNow = () => scanVideoFrame(video, {
+    ...options,
+    maxDimension: fastCaptureMaxDimension
+  });
+
+  const emitResult = (result, frameMeta = null) => {
+    if (stopped) return true;
+    const normalizedMeta = frameMeta
+      ? { frame: frameMeta.frame ?? frameNumber, ...frameMeta }
+      : null;
+    options.onResult?.(result, normalizedMeta);
+    options.onDecode?.(result, normalizedMeta);
+    if (options.stopOnResult ?? true) {
+      stop();
+      return true;
+    }
+    return false;
+  };
+
+  const runRecovery = async (triggerFrame, finderCount) => {
+    if (stopped || recoveryBusy) return;
+    recoveryBusy = true;
+    lastRecoveryStartedAt = nowMs();
+    const token = ++recoveryToken;
+    let bitmap = null;
+    try {
+      const client = await ensureRecoveryWorker();
+      if (stopped || token !== recoveryToken) return;
+      const recoveryClient = client ?? fastWorkerClient;
+      const singleWorkerFallback = !client;
+
+      // Capture only after the recovery execution path is ready. This guarantees
+      // the expensive path receives a fresh frame rather than a bitmap that sat
+      // in memory while a recovery worker was starting.
+      const visibleSource = visibleVideoSourceRect(video, options);
+      const captured = await captureCameraBitmap(video, visibleSource, recoveryCaptureMaxDimension);
+      bitmap = captured.bitmap;
+      if (stopped || token !== recoveryToken) {
+        bitmap.close?.();
+        return;
+      }
+
+      emitDiagnostic({
+        type: "recovery-dispatch",
+        state: "trying",
+        method: "parallel-full-recovery",
+        frame: triggerFrame,
+        finderCount,
+        message: finderCount > 0
+          ? `Fast frame saw ${finderCount} finder${finderCount === 1 ? "" : "s"} · full recovery running in parallel`
+          : "Periodic full recovery running in parallel while fast fresh-frame scanning continues"
+      });
+
+      const recoveryPayload = { bitmap, source: captured.source, frame: triggerFrame };
+      if (singleWorkerFallback) recoveryPayload.options = serializableCameraWorkerOptions(options);
+      const workerResult = await recoveryClient.request(
+        singleWorkerFallback ? "scan-full" : "scan",
+        recoveryPayload,
+        [bitmap]
+      );
+      bitmap = null;
+      if (stopped || token !== recoveryToken) return;
+
+      for (const diagnostic of workerResult?.diagnostics ?? []) {
+        emitDiagnostic({
+          ...diagnostic,
+          recoveryWorker: !singleWorkerFallback,
+          singleWorkerRecoveryFallback: singleWorkerFallback,
+          frame: triggerFrame
+        });
+      }
+      if (workerResult?.ok) {
+        emitResult(workerResult.result, { ...workerResult.frameMeta, frame: triggerFrame });
+      }
+    } catch (error) {
+      try { bitmap?.close?.(); } catch {}
+      if (!stopped) {
+        emitDiagnostic({
+          type: "recovery-worker-error",
+          state: "error",
+          method: "parallel-full-recovery",
+          frame: triggerFrame,
+          message: error?.message ?? String(error)
+        });
+      }
+    } finally {
+      recoveryBusy = false;
+    }
+  };
+
+  const maybeDispatchRecovery = (workerResult, triggerFrame) => {
+    if (stopped || recoveryBusy) return;
+    const finderCount = maximumFinderCount(workerResult);
+    const elapsed = nowMs() - lastRecoveryStartedAt;
+    const minimumInterval = finderCount >= 2
+      ? recoveryStrongFinderInterval
+      : finderCount === 1
+        ? recoveryWeakFinderInterval
+        : recoveryNoFinderInterval;
+    if (elapsed >= minimumInterval) void runRecovery(triggerFrame, finderCount);
+  };
+
+  const scheduleNextScan = () => {
+    if (stopped) return;
+    const runWhenDue = () => {
+      frameCallbackId = null;
+      if (stopped) return;
+      const remaining = scanInterval - (nowMs() - lastScanStartedAt);
+      if (remaining > 1) {
+        timer = setTimeout(() => {
+          timer = null;
+          scheduleNextScan();
+        }, remaining);
+        return;
+      }
+      void loop();
+    };
+
+    if (useVideoFrameCallback) {
+      frameCallbackId = video.requestVideoFrameCallback(runWhenDue);
+    } else {
+      const remaining = Math.max(0, scanInterval - (nowMs() - lastScanStartedAt));
+      timer = setTimeout(() => {
+        timer = null;
+        runWhenDue();
+      }, remaining);
+    }
+  };
+
+  const loop = async () => {
+    if (stopped) return;
+    if (!busy && video.readyState >= 2) {
+      busy = true;
+      frameNumber++;
+      const currentFrame = frameNumber;
+      lastScanStartedAt = nowMs();
+      const token = ++requestToken;
+      let bitmap = null;
+      try {
+        const visibleSource = visibleVideoSourceRect(video, options);
+        const captured = await captureCameraBitmap(video, visibleSource, fastCaptureMaxDimension);
+        bitmap = captured.bitmap;
+        if (stopped || token !== requestToken) {
+          bitmap.close?.();
+          return;
+        }
+        const workerResult = await fastWorkerClient.request(
+          "scan",
+          { bitmap, source: captured.source, frame: currentFrame },
+          [bitmap]
+        );
+        bitmap = null;
+        if (stopped || token !== requestToken) return;
+
+        for (const diagnostic of workerResult?.diagnostics ?? []) {
+          emitDiagnostic({ ...diagnostic, fastWorker: true, frame: currentFrame });
+        }
+        if (workerResult?.ok) {
+          if (emitResult(workerResult.result, { ...workerResult.frameMeta, frame: currentFrame })) return;
+        } else {
+          // Full perspective/color/damage recovery runs independently. Do not
+          // await it here: the next camera callback must remain free to inspect
+          // a newer frame immediately.
+          maybeDispatchRecovery(workerResult, currentFrame);
+          const error = new Error(workerResult?.error?.message ?? "Unable to decode QuadQR frame.");
+          error.name = workerResult?.error?.name ?? "Error";
+          error.debug = workerResult?.error?.debug ?? null;
+          options.onScanMiss?.(error);
+        }
+      } catch (error) {
+        try { bitmap?.close?.(); } catch {}
+        if (!stopped) {
+          emitDiagnostic({
+            type: "worker-error",
+            state: "error",
+            method: "camera-fast-worker",
+            frame: currentFrame,
+            message: error?.message ?? String(error)
+          });
+          options.onScanMiss?.(error);
+        }
+      } finally {
+        busy = false;
+      }
+    }
+    scheduleNextScan();
+  };
+
+  scheduleNextScan();
+  return {
+    stream,
+    stop,
+    scanNow,
+    video,
+    worker: true,
+    workerMode: "dual-pipeline",
+    workerState: fastWorkerClient.state
+  };
+}
+
+/**
+ * Start continuous camera scanning. Modern browsers use a dedicated module
+ * worker by default so the complete recovery pipeline can remain enabled
+ * without blocking rendering/input. Unsupported/CSP-restricted environments
+ * automatically fall back to the original main-thread scanner.
+ */
+async function startCameraScanner(video, options = {}) {
+  if (cameraWorkerSupported(options)) {
+    try {
+      return await startCameraScannerWorker(video, options);
+    } catch (error) {
+      if (options.cameraWorkerRequired) throw error;
+      try {
+        options.onDiagnostic?.({
+          timestamp: Date.now(),
+          frame: 0,
+          type: "worker-fallback",
+          state: "fallback",
+          method: "camera-main-thread",
+          message: `Background scanner unavailable · using main-thread fallback (${error?.message ?? String(error)})`
+        });
+      } catch {}
+    }
+  }
+  return startCameraScannerMainThread(video, options);
+}
+
 function rectifyDetectedCode(imageData, options = {}) {
   const candidates = detectCodeGeometry(imageData, {
     minVersion: options.minVersion ?? MIN_VERSION,
@@ -11486,7 +13043,7 @@ const internals = Object.freeze({
   SECURE_FLAG
 });
 
-return { compressPayload, decompressPayload, compressDeflatePayload, decompressDeflatePayload, compressBrotliPayload, decompressBrotliPayload, deriveSigningKeyId, generateSigningKeyPair, installCrc32Accelerator, crc32, getVersionInfo, encodeText, encodeBytes, encodeUint8Array, encodeSignedBytes, encodeSignedText, encodeSecureText, encodeSecureBytes, decryptDecoded, decodeMatrix, decodeUint8Array, verifyDecodedSignature, estimateSafeLogoSize, findMaxSafeLogoSize, getPrintGuidance, renderToCanvas, renderToImageData, renderToSVG, applyStressDistortion, runImageStressTest, runReliabilityLab, runPerspectiveSweep, assessScanability, debugScanImageData, scanImageData, scanFile, scanVideoFrame, startCameraScanner, rectifyDetectedCode, rotateMatrix, FORMAT_VERSION, MIN_VERSION, MAX_VERSION, DEFAULT_ECC_LEVEL, RENDER_MODES, CELL_ENCODINGS, PRINT_PALETTE, COMPRESSION_MODES, LZ_LEVEL_MIN, LZ_LEVEL_MAX, DEFAULT_LZ_LEVEL, COMPRESSION_LEVELS, SIGNATURE_ALGORITHMS, CELL, DEFAULT_PALETTE, RENDER_STYLES, ECC_LEVELS, STRESS_PROFILES, RELIABILITY_PROFILES, internals, SECURITY_MODES, SECURITY_ALGORITHMS, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, generateRaw256Key, normalizeRaw256Key, bytesToHex };
+return { compressPayload, decompressPayload, compressDeflatePayload, decompressDeflatePayload, compressBrotliPayload, decompressBrotliPayload, deriveSigningKeyId, generateSigningKeyPair, installCrc32Accelerator, crc32, getVersionInfo, encodeText, encodeBytes, encodeUint8Array, encodeSignedBytes, encodeSignedText, encodeSecureText, encodeSecureBytes, decryptDecoded, decodeMatrix, decodeUint8Array, verifyDecodedSignature, estimateSafeLogoSize, findMaxSafeLogoSize, getPrintGuidance, renderToCanvas, renderToImageData, renderToSVG, applyStressDistortion, runImageStressTest, runReliabilityLab, runPerspectiveSweep, assessScanability, debugScanImageData, scanImageData, scanFile, scanVideoFrame, startCameraScanner, rectifyDetectedCode, rotateMatrix, FORMAT_VERSION, LEGACY_FORMAT_VERSION, MIN_VERSION, MAX_VERSION, DEFAULT_ECC_LEVEL, RENDER_MODES, CELL_ENCODINGS, PRINT_PALETTE, COMPRESSION_MODES, LZ_LEVEL_MIN, LZ_LEVEL_MAX, DEFAULT_LZ_LEVEL, COMPRESSION_LEVELS, SIGNATURE_ALGORITHMS, CELL, DEFAULT_PALETTE, RENDER_STYLES, ECC_LEVELS, STRESS_PROFILES, RELIABILITY_PROFILES, internals, SECURITY_MODES, SECURITY_ALGORITHMS, SECURE_PAYLOAD_VERSION, DEFAULT_PBKDF2_ITERATIONS, generateRaw256Key, normalizeRaw256Key, bytesToHex };
 })();
 const QuadQR = __qqr_quadqr_js;
 
@@ -11507,19 +13064,67 @@ QuadQR.initWasm = async function initWasm(options = {}) {
   const instance = result.instance;
   const memory = instance.exports.memory;
   const crc32Bytes = instance.exports.crc32_bytes;
+  const buildBinaryRgba = instance.exports.build_binary_rgba;
   const heapExport = instance.exports.__heap_base;
   const heapBase = Number((heapExport && heapExport.value) || heapExport || 65536);
   if (!(memory instanceof WebAssembly.Memory) || typeof crc32Bytes !== "function") {
     throw new Error("QuadQR WASM exports are invalid.");
   }
+  const ensureMemory = function (required) {
+    if (required > memory.buffer.byteLength) memory.grow(Math.ceil((required - memory.buffer.byteLength) / 65536));
+  };
   QuadQR.installCrc32Accelerator(function (input) {
-    const data = input instanceof Uint8Array ? input : new Uint8Array(input);
+    const data = input instanceof Uint8Array
+      ? input
+      : ArrayBuffer.isView(input)
+        ? new Uint8Array(input.buffer, input.byteOffset, input.byteLength)
+        : new Uint8Array(input);
     const required = heapBase + data.length;
-    if (required > memory.buffer.byteLength) memory.grow(Math.ceil((required - memory.buffer.byteLength) / 65536));
+    ensureMemory(required);
     new Uint8Array(memory.buffer, heapBase, data.length).set(data);
     return crc32Bytes(heapBase, data.length) >>> 0;
   });
-  return Object.freeze({ enabled: true, module: "quadqr-core", accelerators: Object.freeze(["crc32"]), bytes: bytes.length });
+  const accelerators = ["crc32"];
+  if (typeof buildBinaryRgba === "function") {
+    const align16 = function (value) { return (value + 15) & ~15; };
+    __qqr_vision_js.installVisionAccelerator({
+      buildBinary: function (imageData, scanOptions = {}) {
+        const width = Number(imageData && imageData.width) || 0;
+        const height = Number(imageData && imageData.height) || 0;
+        const pixels = width * height;
+        if (!pixels || !imageData || !imageData.data || imageData.data.length < pixels * 4) {
+          throw new Error("Valid ImageData is required for WASM preprocessing.");
+        }
+        const raw = imageData.data;
+        const rgba = raw instanceof Uint8Array
+          ? raw
+          : new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+        const rgbaBytes = pixels * 4;
+        const inputPtr = align16(heapBase);
+        const grayPtr = align16(inputPtr + rgbaBytes);
+        const binaryPtr = align16(grayPtr + pixels);
+        ensureMemory(binaryPtr + pixels);
+        new Uint8Array(memory.buffer, inputPtr, rgbaBytes).set(rgba.subarray(0, rgbaBytes));
+        const mode = scanOptions.grayMode === "value" ? 0 : 1;
+        const offset = Math.round(Number(scanOptions.thresholdOffset) || 0);
+        const packed = buildBinaryRgba(inputPtr, pixels, mode, offset, grayPtr, binaryPtr) >>> 0;
+        const gray = new Uint8Array(pixels);
+        const binary = new Uint8Array(pixels);
+        gray.set(new Uint8Array(memory.buffer, grayPtr, pixels));
+        binary.set(new Uint8Array(memory.buffer, binaryPtr, pixels));
+        return {
+          gray: gray,
+          binary: binary,
+          threshold: packed & 255,
+          baseThreshold: (packed >>> 8) & 255,
+          grayMode: scanOptions.grayMode || "luminance",
+          accelerated: "wasm"
+        };
+      }
+    });
+    accelerators.push("scanner-preprocess");
+  }
+  return Object.freeze({ enabled: true, module: "quadqr-core", accelerators: Object.freeze(accelerators), bytes: bytes.length });
 };
 global.QuadQR = QuadQR;
 })(typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : this);