quadqr-js 1.4.2 → 1.5.2

package/docs/API.md

@@ -209,11 +209,16 @@ 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. It scans the CSS-visible preview region by default. Finder detection uses a QuadQR-specific RGB value channel (`max(R,G,B)`) on the fast pass so saturated blue/red/green data cells are not mistaken for structural black. If a miss still contains at least two strong finder patterns, the scanner can retry the visible ROI at up to 1600 px before heavier recovery, which preserves more pixels per module for dense versions. If that does not decode, the **same captured frame** is retried through QuadQR code-centric Auto Color recovery. The default recovery sequence crops 8%, 16%, and 22% from the camera-frame edges, then falls back to the full frame. This prevents dark room pixels, browser UI, or monitor bezels outside the guide from controlling QuadQR Auto Color and Otsu thresholds. Each crop uses the QuadQR-specific per-channel shadow/highlight correction with a neutral mid-high highlight target (190 by default). Finder-only recovery also tries multiple center-weighted QuadQR Auto Color histogram windows before raw threshold bracketing. The normal fast path is untouched; these extra passes run only after a miss. If geometry is found but color decoding fails, the captured ROI is retried with stronger color/geometry recovery, including affine cross-channel calibration. Consecutive failed frames can then be combined with tracked-symbol **confidence fusion**: cell evidence is weighted by source confidence, frame quality, and recency, and second hypotheses are carried forward into Spectrum ECC 2.0.
+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.
 
 ```js
 const scanner = await startCameraScanner(video, {
-  scanInterval: 120,
+  cameraWorker: true,
+  maxDimension: 640,
+  scanInterval: 33,
+  useVideoFrameCallback: true,
+  cameraGeometryReuse: true,
+  cameraGeometryReuseMaxMisses: 5,
   multiFrame: true,
   multiFrameWindow: 4,
   multiFrameMinFrames: 2,
@@ -226,8 +231,11 @@ const scanner = await startCameraScanner(video, {
   cameraAutoEnhanceEvery: 2,
   cameraFinderRecoveryEvery: 2,
   cameraHighResolutionRecovery: true,
-  cameraHighResolutionMaxDimension: 1600,
+  cameraHighResolutionMaxDimension: 960,
   cameraHighResolutionEvery: 2,
+  cameraRecoveryStrongFinderInterval: 120,
+  cameraRecoveryWeakFinderInterval: 260,
+  cameraRecoveryNoFinderInterval: 850,
   onResult(result) {
     console.log(result);
   },
@@ -331,14 +339,14 @@ Security constants include:
 
 ### `initWasm(options?)`
 
-Loads and activates the optional bundled WASM accelerator.
+Loads and activates the optional bundled WASM accelerator for CRC-32 and scanner pixel preprocessing (RGBA grayscale conversion, Otsu thresholding, and finder binary generation).
 
 ```js
 import { initWasm } from "quadqr-js";
 await initWasm();
 ```
 
-An explicit URL or byte buffer can also be supplied.
+An explicit URL or byte buffer can also be supplied. Initialize it once before performance-sensitive synchronous `scanImageData()` loops or before starting the camera scanner.
 
 ### `getWasmState()`
 

package/docs/BROWSER_CDN.md

@@ -95,7 +95,7 @@ If the symbol uses Secure Payload, the scan result has `secure: true` and `requi
 const video = document.querySelector("#camera");
 
 const scanner = await startCameraScanner(video, {
-  scanInterval: 120,
+  scanInterval: 33,
   cameraFinderRecoveryEvery: 2,
   async onResult(result) {
     console.log(result);
@@ -137,7 +137,7 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
 
 ```html
 <canvas id="qr"></canvas>
-<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.4.1/dist/quadqr.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.5.1/dist/quadqr.min.js"></script>
 <script>
   const code = QuadQR.encodeText("Hello CDN");
 
@@ -151,7 +151,7 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
 ## unpkg
 
 ```html
-<script src="https://unpkg.com/quadqr-js@1.4.1/dist/quadqr.min.js"></script>
+<script src="https://unpkg.com/quadqr-js@1.5.1/dist/quadqr.min.js"></script>
 ```
 
 ## Direct CDN ESM
@@ -161,7 +161,7 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
   import {
     encodeText,
     renderToCanvas
-  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.4.1/dist/browser.js";
+  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.5.1/dist/browser.js";
 
   const code = encodeText("ES module CDN");
   renderToCanvas(code, document.querySelector("#qr"));
@@ -188,4 +188,4 @@ WASM is optional. The normal JavaScript implementation remains available if it c
 
 ## Production recommendation
 
-Pin a concrete package version such as `@1.4.1` in CDN URLs so an existing site does not silently change when a newer package version becomes available.
+Pin a concrete package version such as `@1.5.1` in CDN URLs so an existing site does not silently change when a newer package version becomes available.

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 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.