quadqr-js 1.5.2 → 1.5.3

package/README.md

@@ -1104,7 +1104,7 @@ Scans one frame from an HTML video element. By default, if the video is displaye
 
 ### `startCameraScanner(video, options?)`
 
-Starts a reusable live-camera scanning loop. On supported browsers it requests continuous focus/exposure/white-balance camera modes and scans the CSS-visible preview crop. Modern browsers use a **dual-worker camera engine**: a lightweight fresh-frame worker continuously runs normal finder/geometry/decode attempts, while an independent recovery worker retains the complete high-resolution, Auto Color, precise-alignment, perspective, multi-frame, ECC, and damaged-code recovery stack. A slow recovery attempt therefore cannot prevent the fast worker from inspecting a newer camera frame. Finder detection remains JavaScript; optional WASM accelerates grayscale/binary preprocessing and CRC beneath the same detector. The scheduler uses `requestVideoFrameCallback()` when available and does not queue stale fast-path frames. Normal camera acquisition requests an environment camera around 1280×720 and crops/resizes the visible preview to a 640 px working bitmap **before** transferring it to the worker. Once a candidate validates structure, Spectrum ECC, and CRC, scanning returns immediately. If the fast worker misses, full recovery runs concurrently on a fresh frame at up to 960 px. Strong finder evidence dispatches recovery quickly; finder-less frames still receive periodic full recovery so severe color casts or damaged locators retain the same rescue paths. QuadQR Auto Color crop profiles, center-weighted histograms, threshold bracketing, precise alignment, projective recovery, QR-region enhancement, multi-frame confidence fusion, and soft-decision Spectrum ECC are unchanged. `cameraHighResolutionMaxDimension` defaults to 960. The optional `onDiagnostic(event)` callback exposes whether an event came from the fast or recovery worker, finder candidates, active locator method, crop/geometry/version hypothesis, recovery method, timing, and scan dimensions. `onResult(result, frame)` receives the exact frame that decoded, including enhanced recovery pixels when applicable, so UIs can keep the frozen frame and finder overlay aligned.
+Starts a reusable live-camera scanning loop. On supported browsers it requests continuous focus/exposure/white-balance camera modes and scans the CSS-visible preview crop. Modern browsers use a **dual-worker camera engine**: a lightweight fresh-frame worker continuously runs normal finder/geometry/decode attempts, while an independent recovery worker retains the complete high-resolution, Auto Color, precise-alignment, perspective, multi-frame, ECC, and damaged-code recovery stack. A slow recovery attempt therefore cannot prevent the fast worker from inspecting a newer camera frame. Finder detection remains JavaScript; optional WASM accelerates grayscale/binary preprocessing and CRC beneath the same detector. The scheduler uses `requestVideoFrameCallback()` when available and does not queue stale fast-path frames. Normal camera acquisition requests an environment camera around 1280×720 and crops/resizes the visible preview to a 640 px working bitmap **before** transferring it to the worker. Once a candidate validates structure, Spectrum ECC, and CRC, scanning returns immediately. If the fast worker misses, full recovery runs concurrently on a fresh frame at up to 960 px. Strong finder evidence dispatches recovery quickly. Finder-less frames remain on the lightweight fresh-frame detector only, so pointing the camera at an empty scene never starts Auto Color or deeper recovery work. QuadQR Auto Color crop profiles, center-weighted histograms, threshold bracketing, precise alignment, projective recovery, QR-region enhancement, multi-frame confidence fusion, and soft-decision Spectrum ECC are unchanged. `cameraHighResolutionMaxDimension` defaults to 960. The optional `onDiagnostic(event)` callback exposes whether an event came from the fast or recovery worker, finder candidates, active locator method, crop/geometry/version hypothesis, recovery method, timing, and scan dimensions. `onResult(result, frame)` receives the exact frame that decoded, including enhanced recovery pixels when applicable, so UIs can keep the frozen frame and finder overlay aligned.
 
 ### `getVersionInfo(version, options?)`
 

package/dist/camera-scanner-worker.js

@@ -326,9 +326,10 @@ function processFrame(bitmap, source, frameNumber) {
   let allowFinderRecovery = false;
   let allowAutoEnhance = false;
   try {
-    allowFinderRecovery = scanOptions.finderRecovery !== false &&
+    const fastPipeline = scanOptions.cameraPipelineMode === "fast";
+    allowFinderRecovery = !fastPipeline && scanOptions.finderRecovery !== false &&
       missStreak > 0 && ((missStreak - 1) % cameraFinderRecoveryEvery === 0);
-    allowAutoEnhance = scanOptions.autoEnhanceRecovery !== false &&
+    allowAutoEnhance = !fastPipeline && scanOptions.autoEnhanceRecovery !== false &&
       missStreak > 0 && ((missStreak - 1) % cameraAutoEnhanceEvery === 0);
     const method = allowAutoEnhance
       ? "progressive-color-recovery"

package/dist/esm/camera-scanner-worker.js

@@ -326,9 +326,10 @@ function processFrame(bitmap, source, frameNumber) {
   let allowFinderRecovery = false;
   let allowAutoEnhance = false;
   try {
-    allowFinderRecovery = scanOptions.finderRecovery !== false &&
+    const fastPipeline = scanOptions.cameraPipelineMode === "fast";
+    allowFinderRecovery = !fastPipeline && scanOptions.finderRecovery !== false &&
       missStreak > 0 && ((missStreak - 1) % cameraFinderRecoveryEvery === 0);
-    allowAutoEnhance = scanOptions.autoEnhanceRecovery !== false &&
+    allowAutoEnhance = !fastPipeline && scanOptions.autoEnhanceRecovery !== false &&
       missStreak > 0 && ((missStreak - 1) % cameraAutoEnhanceEvery === 0);
     const method = allowAutoEnhance
       ? "progressive-color-recovery"

package/dist/esm/quadqr.js

@@ -6422,6 +6422,12 @@ async function startCameraScannerWorker(video, options = {}) {
   const fastWorkerOptions = {
     ...options,
     cameraPipelineMode: "fast",
+    // The fresh-frame worker is intentionally detection/decode only. Recovery
+    // must never become more expensive merely because the camera has been
+    // looking at an empty scene for a while. The parallel recovery worker is
+    // armed only after finder/geometry evidence says a QuadQR candidate is in
+    // view.
+    finderRecovery: false,
     cameraHighResolutionRecovery: false,
     cameraAutoColorRecovery: false,
     autoEnhanceRecovery: false,
@@ -6464,7 +6470,7 @@ async function startCameraScannerWorker(video, options = {}) {
   );
   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 recoveryWeakFinderFrames = Math.max(2, Math.round(options.cameraRecoveryWeakFinderFrames ?? 2));
   const useVideoFrameCallback = options.useVideoFrameCallback !== false &&
     typeof video.requestVideoFrameCallback === "function";
 
@@ -6481,6 +6487,7 @@ async function startCameraScannerWorker(video, options = {}) {
   let frameNumber = 0;
   let requestToken = 0;
   let recoveryToken = 0;
+  let weakFinderStreak = 0;
 
   const diagnosticsEnabled = typeof options.onDiagnostic === "function";
   const emitDiagnostic = (event) => {
@@ -6532,7 +6539,7 @@ async function startCameraScannerWorker(video, options = {}) {
   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`,
+    message: `Camera ready · ${settings.width ?? video.videoWidth}×${settings.height ?? video.videoHeight} · fast fresh-frame scanner + candidate-gated parallel recovery`,
     camera: {
       width: settings.width ?? video.videoWidth,
       height: settings.height ?? video.videoHeight,
@@ -6616,9 +6623,7 @@ async function startCameraScannerWorker(video, options = {}) {
         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"
+        message: `QuadQR candidate detected (${finderCount} finder${finderCount === 1 ? "" : "s"}) · full recovery running in parallel`
       });
 
       const recoveryPayload = { bitmap, source: captured.source, frame: triggerFrame };
@@ -6661,12 +6666,26 @@ async function startCameraScannerWorker(video, options = {}) {
   const maybeDispatchRecovery = (workerResult, triggerFrame) => {
     if (stopped || recoveryBusy) return;
     const finderCount = maximumFinderCount(workerResult);
+
+    // Do not run Auto Color, high-resolution, multi-frame, or damaged-code
+    // recovery just because time has passed. An empty scene stays on the cheap
+    // fresh-frame detector forever. Two or more finders are strong evidence and
+    // arm recovery immediately. One finder is treated as weak evidence and must
+    // persist across consecutive fresh frames before recovery is allowed.
+    let minimumInterval = null;
+    if (finderCount >= 2) {
+      weakFinderStreak = 0;
+      minimumInterval = recoveryStrongFinderInterval;
+    } else if (finderCount === 1) {
+      weakFinderStreak++;
+      if (weakFinderStreak < recoveryWeakFinderFrames) return;
+      minimumInterval = recoveryWeakFinderInterval;
+    } else {
+      weakFinderStreak = 0;
+      return;
+    }
+
     const elapsed = nowMs() - lastRecoveryStartedAt;
-    const minimumInterval = finderCount >= 2
-      ? recoveryStrongFinderInterval
-      : finderCount === 1
-        ? recoveryWeakFinderInterval
-        : recoveryNoFinderInterval;
     if (elapsed >= minimumInterval) void runRecovery(triggerFrame, finderCount);
   };
 

package/dist/quadqr.js

@@ -12607,6 +12607,12 @@ async function startCameraScannerWorker(video, options = {}) {
   const fastWorkerOptions = {
     ...options,
     cameraPipelineMode: "fast",
+    // The fresh-frame worker is intentionally detection/decode only. Recovery
+    // must never become more expensive merely because the camera has been
+    // looking at an empty scene for a while. The parallel recovery worker is
+    // armed only after finder/geometry evidence says a QuadQR candidate is in
+    // view.
+    finderRecovery: false,
     cameraHighResolutionRecovery: false,
     cameraAutoColorRecovery: false,
     autoEnhanceRecovery: false,
@@ -12649,7 +12655,7 @@ async function startCameraScannerWorker(video, options = {}) {
   );
   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 recoveryWeakFinderFrames = Math.max(2, Math.round(options.cameraRecoveryWeakFinderFrames ?? 2));
   const useVideoFrameCallback = options.useVideoFrameCallback !== false &&
     typeof video.requestVideoFrameCallback === "function";
 
@@ -12666,6 +12672,7 @@ async function startCameraScannerWorker(video, options = {}) {
   let frameNumber = 0;
   let requestToken = 0;
   let recoveryToken = 0;
+  let weakFinderStreak = 0;
 
   const diagnosticsEnabled = typeof options.onDiagnostic === "function";
   const emitDiagnostic = (event) => {
@@ -12717,7 +12724,7 @@ async function startCameraScannerWorker(video, options = {}) {
   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`,
+    message: `Camera ready · ${settings.width ?? video.videoWidth}×${settings.height ?? video.videoHeight} · fast fresh-frame scanner + candidate-gated parallel recovery`,
     camera: {
       width: settings.width ?? video.videoWidth,
       height: settings.height ?? video.videoHeight,
@@ -12801,9 +12808,7 @@ async function startCameraScannerWorker(video, options = {}) {
         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"
+        message: `QuadQR candidate detected (${finderCount} finder${finderCount === 1 ? "" : "s"}) · full recovery running in parallel`
       });
 
       const recoveryPayload = { bitmap, source: captured.source, frame: triggerFrame };
@@ -12846,12 +12851,26 @@ async function startCameraScannerWorker(video, options = {}) {
   const maybeDispatchRecovery = (workerResult, triggerFrame) => {
     if (stopped || recoveryBusy) return;
     const finderCount = maximumFinderCount(workerResult);
+
+    // Do not run Auto Color, high-resolution, multi-frame, or damaged-code
+    // recovery just because time has passed. An empty scene stays on the cheap
+    // fresh-frame detector forever. Two or more finders are strong evidence and
+    // arm recovery immediately. One finder is treated as weak evidence and must
+    // persist across consecutive fresh frames before recovery is allowed.
+    let minimumInterval = null;
+    if (finderCount >= 2) {
+      weakFinderStreak = 0;
+      minimumInterval = recoveryStrongFinderInterval;
+    } else if (finderCount === 1) {
+      weakFinderStreak++;
+      if (weakFinderStreak < recoveryWeakFinderFrames) return;
+      minimumInterval = recoveryWeakFinderInterval;
+    } else {
+      weakFinderStreak = 0;
+      return;
+    }
+
     const elapsed = nowMs() - lastRecoveryStartedAt;
-    const minimumInterval = finderCount >= 2
-      ? recoveryStrongFinderInterval
-      : finderCount === 1
-        ? recoveryWeakFinderInterval
-        : recoveryNoFinderInterval;
     if (elapsed >= minimumInterval) void runRecovery(triggerFrame, finderCount);
   };
 

package/dist/quadqr.min.js

@@ -12428,6 +12428,12 @@ async function startCameraScannerWorker(video, options = {}) {
   const fastWorkerOptions = {
     ...options,
     cameraPipelineMode: "fast",
+    // The fresh-frame worker is intentionally detection/decode only. Recovery
+    // must never become more expensive merely because the camera has been
+    // looking at an empty scene for a while. The parallel recovery worker is
+    // armed only after finder/geometry evidence says a QuadQR candidate is in
+    // view.
+    finderRecovery: false,
     cameraHighResolutionRecovery: false,
     cameraAutoColorRecovery: false,
     autoEnhanceRecovery: false,
@@ -12470,7 +12476,7 @@ async function startCameraScannerWorker(video, options = {}) {
   );
   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 recoveryWeakFinderFrames = Math.max(2, Math.round(options.cameraRecoveryWeakFinderFrames ?? 2));
   const useVideoFrameCallback = options.useVideoFrameCallback !== false &&
     typeof video.requestVideoFrameCallback === "function";
 
@@ -12487,6 +12493,7 @@ async function startCameraScannerWorker(video, options = {}) {
   let frameNumber = 0;
   let requestToken = 0;
   let recoveryToken = 0;
+  let weakFinderStreak = 0;
 
   const diagnosticsEnabled = typeof options.onDiagnostic === "function";
   const emitDiagnostic = (event) => {
@@ -12538,7 +12545,7 @@ async function startCameraScannerWorker(video, options = {}) {
   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`,
+    message: `Camera ready · ${settings.width ?? video.videoWidth}×${settings.height ?? video.videoHeight} · fast fresh-frame scanner + candidate-gated parallel recovery`,
     camera: {
       width: settings.width ?? video.videoWidth,
       height: settings.height ?? video.videoHeight,
@@ -12622,9 +12629,7 @@ async function startCameraScannerWorker(video, options = {}) {
         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"
+        message: `QuadQR candidate detected (${finderCount} finder${finderCount === 1 ? "" : "s"}) · full recovery running in parallel`
       });
 
       const recoveryPayload = { bitmap, source: captured.source, frame: triggerFrame };
@@ -12667,12 +12672,26 @@ async function startCameraScannerWorker(video, options = {}) {
   const maybeDispatchRecovery = (workerResult, triggerFrame) => {
     if (stopped || recoveryBusy) return;
     const finderCount = maximumFinderCount(workerResult);
+
+    // Do not run Auto Color, high-resolution, multi-frame, or damaged-code
+    // recovery just because time has passed. An empty scene stays on the cheap
+    // fresh-frame detector forever. Two or more finders are strong evidence and
+    // arm recovery immediately. One finder is treated as weak evidence and must
+    // persist across consecutive fresh frames before recovery is allowed.
+    let minimumInterval = null;
+    if (finderCount >= 2) {
+      weakFinderStreak = 0;
+      minimumInterval = recoveryStrongFinderInterval;
+    } else if (finderCount === 1) {
+      weakFinderStreak++;
+      if (weakFinderStreak < recoveryWeakFinderFrames) return;
+      minimumInterval = recoveryWeakFinderInterval;
+    } else {
+      weakFinderStreak = 0;
+      return;
+    }
+
     const elapsed = nowMs() - lastRecoveryStartedAt;
-    const minimumInterval = finderCount >= 2
-      ? recoveryStrongFinderInterval
-      : finderCount === 1
-        ? recoveryWeakFinderInterval
-        : recoveryNoFinderInterval;
     if (elapsed >= minimumInterval) void runRecovery(triggerFrame, finderCount);
   };
 

package/docs/API.md

@@ -209,7 +209,7 @@ const result = scanVideoFrame(video);
 
 ### `startCameraScanner(video, options?)`
 
-Starts live camera scanning. On browsers that expose camera controls, QuadQR requests continuous autofocus, exposure, and white balance. Modern browsers use two module Web Workers by default: a **fast fresh-frame worker** for normal finder/geometry/decode attempts and a separate **full-recovery worker** for the same perspective, color, high-resolution, ECC, damaged-code, and multi-frame recovery stack used by the main scanner. The recovery worker is lazy and independent, so a difficult old frame cannot block the fast worker from inspecting a newer camera frame. Finder detection itself is JavaScript; WASM only accelerates deterministic grayscale/binary preprocessing and CRC. The loop uses `requestVideoFrameCallback()` when available, drops stale fast-path frames, and measures `scanInterval` from scan start. Worker mode defaults to a 33 ms minimum cadence; automatic main-thread fallback uses 80 ms. The default camera request is approximately 1280×720, while the CSS-visible preview crop is resized to a 640 px working bitmap before crossing the worker boundary. Finder acquisition uses the streaming 1:1:3:1:1 RGB-value pass, direct cross-checks, local-threshold fallback, and directional module-size/version estimation. Once a geometry candidate validates structure, ECC, and CRC, it returns immediately. A miss with strong finder evidence dispatches parallel full recovery quickly; frames with weak or zero finder evidence still receive periodic full recovery so color-cast/damaged locator cases remain recoverable. That recovery can use up to 960 px and retains the full QuadQR Auto Color crop sequence, center-weighted color recovery, threshold bracketing, precise alignment, perspective recovery, affine cross-channel calibration, QR-region enhancement, multi-frame confidence fusion, erasure decoding, and soft-decision Spectrum ECC.
+Starts live camera scanning. On browsers that expose camera controls, QuadQR requests continuous autofocus, exposure, and white balance. Modern browsers use two module Web Workers by default: a **fast fresh-frame worker** for normal finder/geometry/decode attempts and a separate **full-recovery worker** for the same perspective, color, high-resolution, ECC, damaged-code, and multi-frame recovery stack used by the main scanner. The recovery worker is lazy and independent, so a difficult old frame cannot block the fast worker from inspecting a newer camera frame. Finder detection itself is JavaScript; WASM only accelerates deterministic grayscale/binary preprocessing and CRC. The loop uses `requestVideoFrameCallback()` when available, drops stale fast-path frames, and measures `scanInterval` from scan start. Worker mode defaults to a 33 ms minimum cadence; automatic main-thread fallback uses 80 ms. The default camera request is approximately 1280×720, while the CSS-visible preview crop is resized to a 640 px working bitmap before crossing the worker boundary. Finder acquisition uses the streaming 1:1:3:1:1 RGB-value pass, direct cross-checks, local-threshold fallback, and directional module-size/version estimation. Once a geometry candidate validates structure, ECC, and CRC, it returns immediately. A miss with strong finder evidence dispatches parallel full recovery quickly. One finder must persist across consecutive fresh frames before recovery is armed, while zero-finder frames stay on the lightweight detector only. That recovery can use up to 960 px and retains the full QuadQR Auto Color crop sequence, center-weighted color recovery, threshold bracketing, precise alignment, perspective recovery, affine cross-channel calibration, QR-region enhancement, multi-frame confidence fusion, erasure decoding, and soft-decision Spectrum ECC.
 
 ```js
 const scanner = await startCameraScanner(video, {
@@ -235,7 +235,7 @@ const scanner = await startCameraScanner(video, {
   cameraHighResolutionEvery: 2,
   cameraRecoveryStrongFinderInterval: 120,
   cameraRecoveryWeakFinderInterval: 260,
-  cameraRecoveryNoFinderInterval: 850,
+  cameraRecoveryWeakFinderFrames: 2,
   onResult(result) {
     console.log(result);
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quadqr-js",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "QuadQR: experimental RGBW matrix code with optional experimental High Density Mode, Spectrum ECC 2.0, multi-frame camera scanning, advanced calibration, Reliability Lab, and 3D perspective recovery.",
   "type": "module",
   "main": "./dist/index.cjs",