quadqr-js 1.5.2 → 1.5.4

package/README.md

@@ -258,7 +258,7 @@ Compression modes are `none`, `auto`, `smart`, `brotli`, `deflate`, and `lz`. `a
 
 Signing can also be composed with Secure Payload. QuadQR compresses if requested, signs the normal payload with the private key, then encrypts the protected bytes with AES-256-GCM. A verifier supplies the trusted public key separately, or resolves it from `keyId`.
 
-The renderer supports an explicit `mode: "print"`. Print mode enforces a minimum 4-module quiet zone, uses darker print-safe RGB defaults, and prefers Classic solid modules. `getPrintGuidance()` converts a chosen physical size into module millimeters/pixels so print layouts can be checked before production testing.
+The renderer supports an explicit `mode: "print"`. Print mode uses darker print-safe RGB defaults and prefers Classic solid modules, while `quietZone` behaves exactly as it does in screen mode. Four modules remains the recommended default. `getPrintGuidance()` converts a chosen physical size into module millimeters/pixels so print layouts can be checked before production testing.
 
 Centered logos support `size: "auto"`, which estimates a conservative ECC-aware ratio from code utilization and rendering choices. `findMaxSafeLogoSize()` can additionally probe ImageData output and empirically search for the largest size that still decodes.
 
@@ -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?)`
 
@@ -1281,4 +1281,4 @@ AGPL v3.0. See `LICENSE`.
 
 **Experimental / research project**
 
-QuadQR is actively evolving. Format details may change between versions until the wire format is considered stable.
+QuadQR is actively evolving. Format details may change between versions until the wire format is considered stable.

package/SPECIFICATION.md

@@ -253,9 +253,9 @@ inset
 
 ### Print mode
 
-`mode: "print"` applies conservative defaults:
+`mode: "print"` applies print-oriented defaults:
 
-- minimum quiet zone of 4 modules unless explicitly overridden;
+- caller-controlled quiet-zone sizing, identical to screen mode (4 modules recommended by default);
 - print-safe darker RGB primaries;
 - Classic solid-module rendering by default;
 - physical-size guidance through `getPrintGuidance()`.

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

@@ -3056,10 +3056,7 @@ function svgLogoHref(source) {
 
 function resolveRenderSizing(options, matrixSize) {
   const mode = normalizeRenderMode(options.mode ?? options.renderMode ?? RENDER_MODES.SCREEN);
-  const requestedQuietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
-  const quietZone = mode === RENDER_MODES.PRINT && options.allowUnsafePrintQuietZone !== true
-    ? Math.max(4, requestedQuietZone)
-    : requestedQuietZone;
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
   const totalModules = matrixSize + quietZone * 2;
   const hasImageSize = options.imageSize !== undefined && options.imageSize !== null;
   const hasModuleSize = options.moduleSize !== undefined && options.moduleSize !== null;
@@ -6422,6 +6419,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 +6467,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 +6484,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 +6536,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 +6620,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 +6663,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

@@ -9241,10 +9241,7 @@ function svgLogoHref(source) {
 
 function resolveRenderSizing(options, matrixSize) {
   const mode = normalizeRenderMode(options.mode ?? options.renderMode ?? RENDER_MODES.SCREEN);
-  const requestedQuietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
-  const quietZone = mode === RENDER_MODES.PRINT && options.allowUnsafePrintQuietZone !== true
-    ? Math.max(4, requestedQuietZone)
-    : requestedQuietZone;
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
   const totalModules = matrixSize + quietZone * 2;
   const hasImageSize = options.imageSize !== undefined && options.imageSize !== null;
   const hasModuleSize = options.moduleSize !== undefined && options.moduleSize !== null;
@@ -12607,6 +12604,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 +12652,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 +12669,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 +12721,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 +12805,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 +12848,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

@@ -9071,10 +9071,7 @@ function svgLogoHref(source) {
 
 function resolveRenderSizing(options, matrixSize) {
   const mode = normalizeRenderMode(options.mode ?? options.renderMode ?? RENDER_MODES.SCREEN);
-  const requestedQuietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
-  const quietZone = mode === RENDER_MODES.PRINT && options.allowUnsafePrintQuietZone !== true
-    ? Math.max(4, requestedQuietZone)
-    : requestedQuietZone;
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
   const totalModules = matrixSize + quietZone * 2;
   const hasImageSize = options.imageSize !== undefined && options.imageSize !== null;
   const hasModuleSize = options.moduleSize !== undefined && options.moduleSize !== null;
@@ -12428,6 +12425,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 +12473,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 +12490,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 +12542,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 +12626,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 +12669,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);
   },
@@ -531,7 +531,7 @@ All render APIs accept:
 { mode: "screen" | "print" }
 ```
 
-Print mode uses a darker print-safe palette, forces Classic modules by default, and enforces a minimum 4-module quiet zone unless `allowUnsafePrintQuietZone: true` is explicitly set.
+Print mode uses a darker print-safe palette and forces Classic modules by default. `quietZone` has the same behavior in print and screen modes, including support for values below the recommended four-module default.
 
 ### `getPrintGuidance(codeOrMatrix, options?)`
 

package/docs/CLI.md

@@ -1,167 +1,167 @@
-# Command Line Interface
-
-The npm package includes the `quadqr` executable and can be used directly through `npx`.
-
-## Encode text
-
-```bash
-npx quadqr-js encode "Hello QuadQR" -o hello.png
-npx quadqr-js encode "Hello QuadQR" -o hello.svg
-```
-
-Optional encoding controls:
-
-```bash
-npx quadqr-js encode "Hello" --ecc M --version auto --image-size 720 --quiet-zone 4 -o hello.png
-```
-
-Use the print-safe rendering profile when the symbol is intended for physical output:
-
-```bash
-npx quadqr-js encode "Print me" --print -o print.svg
-```
-
-Print mode enforces a minimum four-module quiet zone and uses the print-safe rendering defaults.
-
-## Compression
-
-Compression works directly with normal text payloads:
-
-```bash
-npx quadqr-js encode "repeat repeat repeat repeat" \
-  --compression auto \
-  -o compressed.png
-```
-
-Compression modes are `none`, `auto`, `smart`, `brotli`, `deflate`, and `lz`. `auto` performs one balanced comparison using LZ level 6, DEFLATE level 6, and Brotli quality 6. `smart` is CPU-heavy: it starts with the same pass and only escalates to stronger DEFLATE/Brotli levels when a smaller QuadQR version is realistically reachable. If envelope overhead would erase the gain, Auto/Smart leave the original payload untouched. No separate payload mode is required.
-
-Explicit codecs can select a level:
-
-```bash
-npx quadqr-js encode "structured payload" --compression lz --compression-level 9 -o lz.png
-npx quadqr-js encode "structured payload" --compression deflate --compression-level 9 -o deflate.png
-npx quadqr-js encode "structured payload" --compression brotli --compression-level 11 -o brotli.png
-```
-
-LZ and DEFLATE accept levels `1..9` and default to 6. Brotli accepts qualities `0..11` and defaults to 11. `--compression-level` is ignored by Auto/Smart because those modes manage their own staged levels.
-
-## Signed QuadQR
-
-Generate an Ed25519 signing-key bundle:
-
-```bash
-npx quadqr-js signkeygen -o quadqr-signing-key.json
-```
-
-Keep this file secret because it contains the private signing key. Encode a signed payload with:
-
-```bash
-npx quadqr-js encode "Offline-verifiable ticket" \
-  --sign-key quadqr-signing-key.json \
-  -o signed.png
-```
-
-The generated key bundle contains both keys plus a compact `keyId`. Only the private key signs. The public key is **not embedded** in the QuadQR by default and should be distributed separately to trusted scanners or stored in a trusted-key registry.
-
-To override the identifier stored in the symbol:
-
-```bash
-npx quadqr-js encode "Offline-verifiable ticket" \
-  --sign-key quadqr-signing-key.json \
-  --key-id event-main-2026 \
-  -o signed.png
-```
-
-Signing can be combined with password or raw-key encryption:
-
-```bash
-npx quadqr-js encode "Signed and private" \
-  --sign-key quadqr-signing-key.json \
-  --password "my-password" \
-  -o signed-secure.png
-```
-
-## Decode an image
-
-```bash
-npx quadqr-js decode hello.png
-npx quadqr-js decode signed.png --verify-key quadqr-signing-key.json
-```
-
-For an unencrypted text payload, the decoded text is printed to stdout. To verify a signed symbol against a trusted public key, pass the signing bundle with `--verify-key`.
-
-Add scanner diagnostics without changing the normal stdout payload:
-
-```bash
-npx quadqr-js decode hello.png --debug
-```
-
-Diagnostics are written to stderr and include confidence, geometry/color confidence, ECC utilization, signing state, and the scanner diagnostics object when available.
-
-## Password-protected payloads
-
-Encode:
-
-```bash
-npx quadqr-js encode "Private data" --password "my-password" -o secure.png
-```
-
-Decode:
-
-```bash
-npx quadqr-js decode secure.png --password "my-password"
-```
-
-If an encrypted symbol is decoded without a credential, the CLI reports that decryption is required instead of exposing plaintext.
-
-## Raw 256-bit key mode
-
-Generate a random 256-bit encryption key:
-
-```bash
-npx quadqr-js keygen
-```
-
-The output is a 64-character hexadecimal key. Store it securely and do not place it inside the same QuadQR symbol.
-
-Encode using the key:
-
-```bash
-npx quadqr-js encode "Application secret" --key <64-hex-key> -o secure-key.png
-```
-
-Decode using the key:
-
-```bash
-npx quadqr-js decode secure-key.png --key <64-hex-key>
-```
-
-## Options
-
-| Option | Purpose |
-| --- | --- |
-| `-o, --output <file>` | Output PNG/SVG path, or signing-key JSON path for `signkeygen` |
-| `--ecc <L|M|Q|H>` | QuadQR ECC profile. Default: `M` |
-| `--version <auto|1..40>` | Symbol version. Default: `auto` |
-| `--compression <mode>` | `none`, `auto`, `smart`, `brotli`, `deflate`, or `lz`. Default: `auto` |
-| `--compression-level <n>` | Explicit LZ/DEFLATE `1..9` or Brotli `0..11` encoder level |
-| `--high-density` | Enable experimental Triangle16 High Density Mode |
-| `--sign-key <file>` | Sign using a key bundle generated by `signkeygen` |
-| `--key-id <id>` | Override the signing key ID stored in the symbol |
-| `--embed-public-key` | Explicit compatibility mode that embeds the public key |
-| `--verify-key <file>` | Verify a signed symbol with a trusted Ed25519 key bundle |
-| `--password <text>` | Password-mode encryption/decryption |
-| `--key <hex>` | Raw 256-bit key encryption/decryption |
-| `--print` | Use the print-safe render profile |
-| `--image-size <px>` | Exact square output size in pixels. Default: `720` |
-| `--module-size <px>` | Legacy pixels-per-module sizing. Used when `--image-size` is omitted |
-| `--quiet-zone <modules>` | Quiet-zone size in modules. Default: `4` |
-| `--debug` | Emit scanner diagnostics to stderr when decoding |
-| `-h, --help` | Show CLI help |
-
-Password mode and raw-key mode are mutually exclusive for a single operation.
-
-
-## High Density Mode (Experimental)
-
-Use `--high-density` to enable the experimental Triangle16 layout with 16 states and 4 raw bits per body cell. Decode is automatic; no matching decode flag is required.
+# Command Line Interface
+
+The npm package includes the `quadqr` executable and can be used directly through `npx`.
+
+## Encode text
+
+```bash
+npx quadqr-js encode "Hello QuadQR" -o hello.png
+npx quadqr-js encode "Hello QuadQR" -o hello.svg
+```
+
+Optional encoding controls:
+
+```bash
+npx quadqr-js encode "Hello" --ecc M --version auto --image-size 720 --quiet-zone 4 -o hello.png
+```
+
+Use the print-safe rendering profile when the symbol is intended for physical output:
+
+```bash
+npx quadqr-js encode "Print me" --print -o print.svg
+```
+
+Print mode uses the print-safe palette and Classic rendering defaults. `--quiet-zone` is honored unchanged, just as it is in screen mode; four modules remains recommended.
+
+## Compression
+
+Compression works directly with normal text payloads:
+
+```bash
+npx quadqr-js encode "repeat repeat repeat repeat" \
+  --compression auto \
+  -o compressed.png
+```
+
+Compression modes are `none`, `auto`, `smart`, `brotli`, `deflate`, and `lz`. `auto` performs one balanced comparison using LZ level 6, DEFLATE level 6, and Brotli quality 6. `smart` is CPU-heavy: it starts with the same pass and only escalates to stronger DEFLATE/Brotli levels when a smaller QuadQR version is realistically reachable. If envelope overhead would erase the gain, Auto/Smart leave the original payload untouched. No separate payload mode is required.
+
+Explicit codecs can select a level:
+
+```bash
+npx quadqr-js encode "structured payload" --compression lz --compression-level 9 -o lz.png
+npx quadqr-js encode "structured payload" --compression deflate --compression-level 9 -o deflate.png
+npx quadqr-js encode "structured payload" --compression brotli --compression-level 11 -o brotli.png
+```
+
+LZ and DEFLATE accept levels `1..9` and default to 6. Brotli accepts qualities `0..11` and defaults to 11. `--compression-level` is ignored by Auto/Smart because those modes manage their own staged levels.
+
+## Signed QuadQR
+
+Generate an Ed25519 signing-key bundle:
+
+```bash
+npx quadqr-js signkeygen -o quadqr-signing-key.json
+```
+
+Keep this file secret because it contains the private signing key. Encode a signed payload with:
+
+```bash
+npx quadqr-js encode "Offline-verifiable ticket" \
+  --sign-key quadqr-signing-key.json \
+  -o signed.png
+```
+
+The generated key bundle contains both keys plus a compact `keyId`. Only the private key signs. The public key is **not embedded** in the QuadQR by default and should be distributed separately to trusted scanners or stored in a trusted-key registry.
+
+To override the identifier stored in the symbol:
+
+```bash
+npx quadqr-js encode "Offline-verifiable ticket" \
+  --sign-key quadqr-signing-key.json \
+  --key-id event-main-2026 \
+  -o signed.png
+```
+
+Signing can be combined with password or raw-key encryption:
+
+```bash
+npx quadqr-js encode "Signed and private" \
+  --sign-key quadqr-signing-key.json \
+  --password "my-password" \
+  -o signed-secure.png
+```
+
+## Decode an image
+
+```bash
+npx quadqr-js decode hello.png
+npx quadqr-js decode signed.png --verify-key quadqr-signing-key.json
+```
+
+For an unencrypted text payload, the decoded text is printed to stdout. To verify a signed symbol against a trusted public key, pass the signing bundle with `--verify-key`.
+
+Add scanner diagnostics without changing the normal stdout payload:
+
+```bash
+npx quadqr-js decode hello.png --debug
+```
+
+Diagnostics are written to stderr and include confidence, geometry/color confidence, ECC utilization, signing state, and the scanner diagnostics object when available.
+
+## Password-protected payloads
+
+Encode:
+
+```bash
+npx quadqr-js encode "Private data" --password "my-password" -o secure.png
+```
+
+Decode:
+
+```bash
+npx quadqr-js decode secure.png --password "my-password"
+```
+
+If an encrypted symbol is decoded without a credential, the CLI reports that decryption is required instead of exposing plaintext.
+
+## Raw 256-bit key mode
+
+Generate a random 256-bit encryption key:
+
+```bash
+npx quadqr-js keygen
+```
+
+The output is a 64-character hexadecimal key. Store it securely and do not place it inside the same QuadQR symbol.
+
+Encode using the key:
+
+```bash
+npx quadqr-js encode "Application secret" --key <64-hex-key> -o secure-key.png
+```
+
+Decode using the key:
+
+```bash
+npx quadqr-js decode secure-key.png --key <64-hex-key>
+```
+
+## Options
+
+| Option | Purpose |
+| --- | --- |
+| `-o, --output <file>` | Output PNG/SVG path, or signing-key JSON path for `signkeygen` |
+| `--ecc <L|M|Q|H>` | QuadQR ECC profile. Default: `M` |
+| `--version <auto|1..40>` | Symbol version. Default: `auto` |
+| `--compression <mode>` | `none`, `auto`, `smart`, `brotli`, `deflate`, or `lz`. Default: `auto` |
+| `--compression-level <n>` | Explicit LZ/DEFLATE `1..9` or Brotli `0..11` encoder level |
+| `--high-density` | Enable experimental Triangle16 High Density Mode |
+| `--sign-key <file>` | Sign using a key bundle generated by `signkeygen` |
+| `--key-id <id>` | Override the signing key ID stored in the symbol |
+| `--embed-public-key` | Explicit compatibility mode that embeds the public key |
+| `--verify-key <file>` | Verify a signed symbol with a trusted Ed25519 key bundle |
+| `--password <text>` | Password-mode encryption/decryption |
+| `--key <hex>` | Raw 256-bit key encryption/decryption |
+| `--print` | Use the print-safe render profile |
+| `--image-size <px>` | Exact square output size in pixels. Default: `720` |
+| `--module-size <px>` | Legacy pixels-per-module sizing. Used when `--image-size` is omitted |
+| `--quiet-zone <modules>` | Quiet-zone size in modules. Default: `4` |
+| `--debug` | Emit scanner diagnostics to stderr when decoding |
+| `-h, --help` | Show CLI help |
+
+Password mode and raw-key mode are mutually exclusive for a single operation.
+
+
+## High Density Mode (Experimental)
+
+Use `--high-density` to enable the experimental Triangle16 layout with 16 states and 4 raw bits per body cell. Decode is automatic; no matching decode flag is required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quadqr-js",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "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",