quadqr-js 1.0.2 → 1.3.0

package/FORMAT.md

@@ -4,7 +4,7 @@
 
 Experimental custom symbology. It is not ISO QR Code.
 
-Only this RGBW format is implemented. Earlier RGB/ternary formats are intentionally not supported.
+Normal mode uses the default 4-state RGBW data cells. An optional experimental **High Density Mode** uses the 16-state Triangle16 physical layout for payload/body cells. Earlier RGB/ternary formats are intentionally not supported.
 
 ## Matrix sizes
 
@@ -33,6 +33,17 @@ Four data states:
 
 Structural white and data white intentionally share the same visible/internal value. Reserved-position geometry distinguishes their roles.
 
+### High Density Mode (Triangle16)
+
+High Density Mode is identified by header flag bit 6 and implemented with Triangle16 cells. Each non-reserved payload module is split by a fixed `/` diagonal into an upper-left triangle and a lower-right triangle. Each triangle independently uses the RGBW 2-bit alphabet. The packed internal value is:
+
+```text
+cell = (upperLeftColor << 2) | lowerRightColor
+range = 0..15
+```
+
+Therefore Triangle16 has 16 visible states and carries 4 raw bits per body data cell. Same-color pairs such as R/R or B/B render as a visually solid module. Structural modules never use Triangle16 packing.
+
 ## Finder structures
 
 Three 7×7 black/white finder structures are placed at top-left, top-right, and bottom-left, with white separator cells where they fit inside the matrix.
@@ -99,6 +110,18 @@ Therefore:
 1 RGBW data cell = exactly 2 raw bits
 ```
 
+For Triangle16 ECC/body bytes:
+
+```text
+bits 7..4 -> Triangle16 cell 0
+bits 3..0 -> Triangle16 cell 1
+
+1 byte = exactly 2 Triangle16 body cells
+1 Triangle16 body cell = exactly 4 raw bits
+```
+
+The protected header remains encoded as four solid-color RGBW-equivalent cells per byte even when Triangle16 is selected. Internally those solid header cells are represented as R/R, G/G, B/B, or W/W. This keeps the bootstrap/header substantially easier to recover from blur and perspective distortion.
+
 ## Masks
 
 Four masks are defined. Each returns a 2-bit value 0..3:
@@ -117,7 +140,7 @@ visible = raw XOR mask
 raw     = visible XOR mask
 ```
 
-The encoder evaluates all four masks using run-length and four-state balance penalties. The mask ID is not serialized. The decoder tries all four and accepts only a path whose protected header, ECC, and CRC validate.
+The encoder evaluates all four masks using run-length and color-balance penalties. In Triangle16 body cells, two deterministic 2-bit masks are packed into one 4-bit XOR mask; protected solid-color header cells use the normal RGBW mask on both halves so they remain solid. The mask ID is not serialized. The decoder tries all four and accepts only a path whose protected header, ECC, and CRC validate.
 
 ## Header
 
@@ -167,7 +190,10 @@ Flags for both header forms:
 bit 0      UTF-8 text flag
 bits 1..2  ECC profile id
 bit 3      Secure Payload envelope flag
-bits 4..7  reserved
+bit 4      internal payload-extension metadata present
+bit 5      signed-payload hint
+bit 6      High Density Mode flag
+bit 7      reserved
 ```
 
 ECC ids:
@@ -388,3 +414,14 @@ Format v5 is intentionally incompatible with standard QR scanners and with the p
 ## Rendering profiles are not part of the wire format
 
 The canonical QuadQR matrix is independent of presentation style. Renderers may offer styles such as `classic`, `depth`, `soft`, or `inset`, provided structural finder/timing/alignment/calibration references remain sufficiently faithful for decoding. Style selection is not encoded in the payload/header and does not change matrix cell values.
+
+## Compression and signature flags
+
+Format v5 keeps the physical matrix and ECC framing unchanged while reserving two protected-header flags for optional internal payload metadata:
+
+```text
+bit 4 = internal payload-extension metadata present
+bit 5 = signed-payload hint
+```
+
+These bits are not a public payload-type mode. Applications continue to encode normal UTF-8 text or arbitrary bytes. Compression and Ed25519 signing use a compact internal extension envelope only when metadata is required. The envelope, print profile, diagnostics, and scanability test model are specified in [`SPECIFICATION.md`](./SPECIFICATION.md). None of these features changes RGBW cell mapping or Spectrum ECC.

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>Four visible states. Two bits per data cell. A modern experiment in high-density matrix codes.</strong>
+  <strong>Normal RGBW mode by default, with an optional experimental High Density Mode using Triangle16 split cells.</strong>
 </p>
 
 <p align="center">
@@ -21,12 +21,14 @@
   ·
   <a href="docs/README.md">Markdown Docs</a>
   ·
-  <a href="FORMAT.md">Format Specification</a>
+  <a href="FORMAT.md">Matrix Format</a>
+  ·
+  <a href="SPECIFICATION.md">Technical Specification</a>
 </p>
 
-**QuadQR** is an experimental open-source 2D matrix code that uses four visible data states instead of the two states used by a traditional black-and-white QR module.
+**QuadQR** is an experimental open-source 2D matrix code that uses RGBW color states instead of the two states used by a traditional black-and-white QR module. Normal mode stores **2 bits per RGBW data cell**. This experimental branch also includes an optional **High Density Mode**, implemented with Triangle16 split cells, that stores **4 raw bits per body cell**. High Density Mode is disabled by default.
 
-Each QuadQR data cell represents exactly **2 bits**:
+Default RGBW mapping:
 
 | Color | Bits |
 |---|---|
@@ -37,6 +39,28 @@ Each QuadQR data cell represents exactly **2 bits**:
 
 That gives QuadQR a four-symbol alphabet and a raw density of **2 bits per data cell**.
 
+### Experimental High Density Mode
+
+When `highDensity: true` is enabled, Triangle16 splits each payload cell along one fixed `/` diagonal. The upper-left and lower-right triangles independently use Red, Green, Blue, or White:
+
+```text
+4 colors × 4 colors = 16 states
+log2(16) = 4 bits per data cell
+```
+
+The protected bootstrap/header deliberately remains solid-color even in High Density Mode, while the ECC-protected body uses the full 16-state alphabet. This sacrifices a small amount of theoretical capacity to make mode detection and damaged-camera recovery more reliable. Finder, timing, alignment, calibration, ECC, CRC, and matrix dimensions remain unchanged.
+
+```js
+const code = encodeText("High-density QuadQR", {
+  ecc: "M",
+  highDensity: true
+});
+```
+
+Image and camera scanning automatically detect High Density Mode, so a separate scanner mode is not required. High Density Mode is experimental and should be stress-tested at the intended physical size and camera distance.
+
+See [`docs/HIGH_DENSITY_MODE.md`](docs/HIGH_DENSITY_MODE.md) for the physical cell mapping, protected-header strategy, scanner sampling rules, and reliability caveats.
+
 QuadQR keeps the parts that make QR-like codes practical, such as a square matrix, finder patterns, timing structures, error correction, masking, perspective recovery, and camera scanning, while experimenting with a higher-density color-based data layer.
 
 > **Important:** QuadQR is an experimental custom format. It is **not ISO QR Code**, and normal QR scanner apps cannot decode it.
@@ -129,7 +153,8 @@ So at the raw data-cell level:
 | Format | States per data cell | Raw information |
 |---|---:|---:|
 | Binary QR | 2 | 1 bit |
-| QuadQR | 4 | 2 bits |
+| QuadQR RGBW | 4 | 2 bits |
+| QuadQR High Density Mode (Triangle16) | 16 | 4 bits |
 
 This is a **2× raw symbol-density advantage**.
 
@@ -179,6 +204,56 @@ The scanner never expects the secret to be embedded in the QuadQR itself. Raw-ke
 
 ---
 
+## Compression, signatures, and robustness tooling
+
+QuadQR keeps the application payload simple: **text stays text and bytes stay bytes**. There is no public payload-type registry to maintain. Compression and signing metadata are added only as internal implementation details when those features are enabled.
+
+```js
+import {
+  encodeText,
+  encodeSignedText,
+  generateSigningKeyPair,
+  decodeMatrix,
+  verifyDecodedSignature
+} from "quadqr-js";
+
+// Auto compression is zero-overhead when it does not help.
+const compressed = encodeText("repeated repeated repeated", {
+  compression: "auto",
+  ecc: "M"
+});
+
+const keys = await generateSigningKeyPair();
+const signed = await encodeSignedText("verified offline", {
+  compression: "auto",
+  privateKey: keys.privateKey,
+  keyId: keys.keyId
+});
+
+const decoded = decodeMatrix(signed.matrix);
+const verified = await verifyDecodedSignature(decoded, {
+  publicKey: keys.publicKey
+});
+console.log(verified.signatureVerified); // true
+console.log(verified.signatureTrusted);  // true
+```
+
+Compression modes are `none`, `auto`, and `lz`. `auto` keeps the original payload untouched when compression would not save space. Ed25519 signing stores the signature plus an optional compact `keyId`; the public verification key stays outside the QuadQR by default. Applications do not need to choose or maintain content types.
+
+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.
+
+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.
+
+Scanner results include normalized diagnostics such as `confidence`, `geometryConfidence`, `calibrationConfidence`, `structureConfidence`, `eccUtilization`, and `correctedErrors`. Set `debug: true` or call `debugScanImageData()` to inspect finder/geometry candidates, the sampled matrix, color-confidence data, ECC stages, and the stage that failed.
+
+For regression and demo testing, `runImageStressTest()` / `assessScanability()` apply deterministic blur, brightness, exposure, shadow, contrast, perspective, JPEG-like artifacts, and downscaling. The browser demo exposes the same tools as an interactive stress-test lab and shows an overall scanability rating.
+
+The interoperability details are documented in [`SPECIFICATION.md`](./SPECIFICATION.md).
+
+---
+
 ## Current benchmark
 
 Run:
@@ -228,7 +303,7 @@ Therefore:
 
 > The capacity benchmark is a same-dimension and same-label comparison, not yet an equal-damage-tolerance comparison.
 
-The raw QuadQR data alphabet is exactly **2 bits per data cell**. Ratios approaching ~3× in the current usable-payload benchmark are caused by differences in total structural and ECC overhead between the two formats, not because a QuadQR cell contains 3 bits.
+The published baseline benchmark uses **normal RGBW mode at exactly 2 bits per data cell**. Ratios approaching ~3× in that RGBW usable-payload benchmark are caused by differences in total structural and ECC overhead between the two formats, not because an RGBW QuadQR cell contains 3 bits. The experimental **Triangle16** profile is a separate 4-bit/body-cell mode and should be benchmarked independently because its real-world advantage depends on camera resolution, perspective, blur, resizing, and print quality.
 
 A future goal is to add **equal-reliability benchmarking**, where QuadQR and standard QR are compared after calibrating both to similar real-world damage recovery.
 
@@ -390,7 +465,7 @@ White → (255, 255, 255)
 
 Real camera input is not expected to match those exact values.
 
-QuadQR includes calibration and nearest-color classification so the scanner can work with observed colors after lighting, camera processing, perspective changes, and other image transformations. The clean-frame path stays fast: QuadQR tries the normal detected geometry and observed palette first. Only after that fails does it progressively try stronger recovery, including white balancing, spatial normalization, Auto Tone / Auto Contrast / Auto Color-style enhancement, and bounded sub-module geometry refinement. For live video, QuadQR scans the CSS-visible `object-fit: cover` camera region instead of the hidden full sensor frame, so the code keeps the same apparent size/resolution the user sees in the guide. If finder geometry is already strong but color decoding fails, a QR-only rectified pixel enhancement retry is performed immediately; whole-frame enhancement remains reserved for harder locator failures.
+QuadQR includes calibration and nearest-color classification so the scanner can work with observed colors after lighting, camera processing, perspective changes, and other image transformations. The clean-frame path stays fast: QuadQR tries the normal detected geometry and observed palette first. Dense versions can refine an imperfect four-point homography with reliable secondary alignment markers already present in the matrix, without reserving any new cells. If a steep angle leaves exactly two strong finder patterns, a bounded looser third-finder pass runs before heavier color recovery. Only after geometry/color decoding still fails does QuadQR progressively try stronger recovery, including white balancing, spatial normalization, Auto Tone / Auto Contrast / Auto Color-style enhancement, and bounded sub-module geometry refinement. For live video, QuadQR scans the CSS-visible `object-fit: cover` camera region instead of the hidden full sensor frame, so the code keeps the same apparent size/resolution the user sees in the guide. When a dense frame already exposes at least two finders, the camera scanner can also retry the visible ROI at up to 1600 px before expensive color recovery. If finder geometry is already strong but color decoding fails, a QR-only rectified pixel enhancement retry is performed immediately; whole-frame enhancement remains reserved for harder locator failures.
 
 ---
 
@@ -452,9 +527,11 @@ version hypothesis
   ↓
 primary alignment search
   ↓
-homography / perspective correction
+initial homography / perspective correction
   ↓
 distributed alignment-grid validation
+  ↓ (when geometry is plausible but imperfect)
+secondary alignment multi-point homography refinement
   ↓
 module-grid reconstruction
   ↓
@@ -508,7 +585,7 @@ The `inset` style preserves the exact encoded R/G/B/W color around the center of
 
 ```js
 renderToCanvas(code, canvas, {
-  moduleSize: 12,
+  imageSize: 720,
   quietZone: 4,
   style: "inset" // classic | depth | soft | inset
 });
@@ -516,13 +593,58 @@ renderToCanvas(code, canvas, {
 
 The styling is deterministic. Generating the same matrix with the same style produces the same visual tile treatment rather than changing randomly on every render.
 
+`imageSize` sets the exact square output size in pixels. When neither `imageSize` nor `moduleSize` is supplied, QuadQR renders at **720 × 720 px** by default. `moduleSize` remains available as the lower-level legacy sizing control; when `imageSize` is supplied, the exact image size takes precedence.
+
+### Logo overlays, quiet zones, and SVG export
+
+The renderer can place a centered logo over the symbol. Transparent pixels in the logo stay transparent, so the QuadQR modules remain visible through those areas. Enable `clearBackground` when you want a clean padded white area behind the logo instead.
+
+```js
+const logoImage = new Image();
+logoImage.src = "/brand-mark.png";
+await logoImage.decode();
+
+renderToCanvas(code, canvas, {
+  imageSize: 720,
+  quietZone: 6,
+  style: "classic",
+  logo: {
+    source: logoImage,
+    size: 0.12,
+    clearBackground: true,
+    padding: 0.65,
+    radius: 0.8
+  }
+});
+```
+
+`quietZone` is measured in modules and can be set to `0` or increased for print/camera use. Four modules remains the recommended default.
+
+SVG uses the same matrix, palette, styles, quiet-zone size, and logo geometry:
+
+```js
+import { renderToSVG } from "quadqr-js";
+
+const svg = renderToSVG(code, {
+  imageSize: 720,
+  quietZone: 4,
+  logo: {
+    source: "data:image/png;base64,...",
+    size: 0.12,
+    clearBackground: true
+  }
+});
+```
+
+Logo overlays intentionally consume some ECC margin because they cover encoded cells. Keep logos conservative, especially with `L`/`M` ECC. The browser demo verifies the final rendered image before enabling downloads.
+
 ---
 
 ## Demo
 
 **Live demo:** https://akanshsirohi.github.io/QuadQR/demo/
 
-The browser demo runs directly on GitHub Pages and is split into separate views so the interface does not become overloaded.
+The browser demo runs directly on GitHub Pages and is split into separate views so the interface does not become overloaded. The generator keeps only payload, version, and ECC visible by default; optional capabilities are grouped into independent advanced accordions.
 
 ### Generator & Image Scanner
 
@@ -531,9 +653,13 @@ Use this tab to:
 - enter text/data;
 - generate a QuadQR code;
 - select ECC;
+- open Output & Rendering controls for image size, quiet zone, style, and print mode;
+- open the Center Logo accordion for branding;
+- enable internal automatic compression without choosing a payload type;
+- optionally add an Ed25519 signature;
 - optionally encrypt using a password or raw 256-bit key;
 - inspect version and capacity;
-- download the generated image;
+- download PNG or SVG output;
 - scan an uploaded image.
 
 ### Camera Scanner
@@ -552,7 +678,43 @@ The benchmark tab provides an easier visual view of:
 - comparison with standard QR;
 - byte gain;
 - capacity ratio;
-- codec timing.
+- codec timing;
+- capacity planning;
+- interactive stress testing.
+
+Benchmark tools are also separated into accordions so the page stays compact until a tool is needed.
+
+---
+
+## New API highlights
+
+```js
+import {
+  encodeText,
+  encodeUint8Array,
+  decodeUint8Array,
+  renderToImageData,
+  assessScanability,
+  getPrintGuidance
+} from "quadqr-js";
+
+const binary = encodeUint8Array(new Uint8Array([1, 2, 3, 4]), { ecc: "M" });
+const bytes = decodeUint8Array(binary.matrix);
+
+const code = encodeText("Hello hello hello hello", {
+  compression: "auto",
+  ecc: "Q"
+});
+
+const printImage = renderToImageData(code, {
+  imageSize: 1200,
+  mode: "print",
+  logo: { source: logoImageData, size: "auto", clearBackground: true }
+});
+
+console.log(getPrintGuidance(code, { physicalSizeMm: 45, dpi: 300 }));
+console.log(assessScanability(code, { imageSize: 480 }));
+```
 
 ---
 
@@ -583,14 +745,15 @@ const result = decodeMatrix(code.matrix);
 console.log(result.text);
 ```
 
-Node PNG usage:
+Node PNG/SVG usage:
 
 ```js
 import { encodeText } from "quadqr-js";
-import { savePNG, scanFile } from "quadqr-js/node";
+import { savePNG, saveSVG, scanFile } from "quadqr-js/node";
 
 const code = encodeText("Generated on Node.js");
-await savePNG(code, "quadqr.png", { moduleSize: 12, quietZone: 4 });
+await savePNG(code, "quadqr.png", { imageSize: 720, quietZone: 4 });
+await saveSVG(code, "quadqr.svg", { imageSize: 720, quietZone: 4 });
 
 const result = await scanFile("quadqr.png");
 console.log(result.text);
@@ -601,7 +764,7 @@ console.log(result.text);
 The `quadqr-js` package can be loaded directly from npm-backed CDNs:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.0.1/dist/quadqr.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.1.0/dist/quadqr.min.js"></script>
 <script>
   const code = QuadQR.encodeText("Hello from a script tag");
 </script>
@@ -618,6 +781,16 @@ npx quadqr-js encode "Hello QuadQR" -o hello.png
 npx quadqr-js decode hello.png
 ```
 
+Compressed, print-safe, and signed output are also available:
+
+```bash
+npx quadqr-js encode "repeat repeat repeat" --compression auto -o compressed.svg
+npx quadqr-js encode "Print me" --print -o print.svg
+npx quadqr-js signkeygen -o signing-key.json
+npx quadqr-js encode "Verified ticket" --sign-key signing-key.json -o signed.png
+npx quadqr-js decode signed.png --verify-key signing-key.json
+```
+
 Password-protected payloads use the same commands:
 
 ```bash
@@ -625,7 +798,7 @@ npx quadqr-js encode "Private data" --password "my-password" -o secure.png
 npx quadqr-js decode secure.png --password "my-password"
 ```
 
-See [`docs/CLI.md`](docs/CLI.md) for all CLI options, including raw 256-bit key mode.
+See [`docs/CLI.md`](docs/CLI.md) for all CLI options, including compression, raw 256-bit key mode, signing, print mode, and scanner diagnostics.
 
 ### Run from source
 
@@ -862,7 +1035,7 @@ The result reports fields such as `spectralInterleaving`, `confidenceAssisted`,
 
 ### `renderToCanvas(codeOrMatrix, canvas, options?)`
 
-Renders a QuadQR symbol into a browser canvas. `options.style` supports `classic`, `depth`, `soft`, and `inset`.
+Renders a QuadQR symbol into a browser canvas. `imageSize` sets the exact square pixel output and defaults to 720 when neither sizing option is supplied. `moduleSize` remains available for legacy pixels-per-module sizing. `options.style` supports `classic`, `depth`, `soft`, and `inset`. `quietZone` controls the border in modules. `logo` accepts a loaded image/canvas source or `{ source, size, clearBackground, padding, radius, backgroundColor }`.
 
 ### `renderToImageData(codeOrMatrix, options?)`
 
@@ -878,9 +1051,15 @@ Returns an ImageData-like object and supports the same rendering styles as `rend
 
 This is also useful for tests and non-DOM workflows.
 
+When a logo is used with `renderToImageData()`, its source must be an ImageData-like `{ width, height, data }` object so the renderer can composite it without DOM APIs.
+
+### `renderToSVG(codeOrMatrix, options?)`
+
+Returns a standalone SVG string using the same exact `imageSize`, render styles, and quiet-zone controls. SVG logo sources can be a URL/data URL string or an object with a `src` string. The SVG remains vector-sharp regardless of how large the preview is displayed.
+
 ### `scanImageData(imageData, options?)`
 
-Runs the complete perspective-aware and color-aware image scanner. The scanner first tries the normal detected geometry with the observed RGB palette, preserving the fast path for clean images. Only after that fails does it progressively fall back to per-channel white balancing, spatial black/white normalization, tighter centre sampling, a cheap module-grid Auto Tone / Auto Contrast / Auto Color-style recovery, a rectified QR-region pixel enhancement pass, and finally bounded sub-module geometry micro-refinement. If locator detection itself is weakened by a flat/yellow frame, a full-image enhancement retry is also available. RGBW confidence values are carried into Reed-Solomon so ambiguous cells can be treated as erasures when ordinary hard-decision ECC is insufficient.
+Runs the complete perspective-aware and color-aware image scanner. The scanner first tries the normal detected geometry with the observed RGB palette, preserving the fast path for clean images. Dense versions use distributed alignment markers to refine a plausible but imperfect projective solution, and a two-finder recovery pass can rescue a third locator that has been stretched by perspective. Only after that fails does it progressively fall back to per-channel white balancing, spatial black/white normalization, tighter centre sampling, a cheap module-grid Auto Tone / Auto Contrast / Auto Color-style recovery, a rectified QR-region pixel enhancement pass, and finally bounded sub-module geometry micro-refinement. If locator detection itself is weakened by a flat/yellow frame, a full-image enhancement retry is also available. RGBW confidence values are carried into Reed-Solomon so ambiguous cells can be treated as erasures when ordinary hard-decision ECC is insufficient.
 
 ### `scanFile(file, options?)`
 
@@ -892,7 +1071,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. A normal frame always gets the fast RGB-value finder pass first. If that fails, the **same captured frame** enters a QR-guide recovery path: QuadQR progressively crops away 8%, 16%, and 22% of the surrounding camera frame (then tries the full frame as a final fallback), applies the Photoshop-style Auto Color correction inside that code-centric region, and runs finder detection again. This matters because a live preview can contain dark room pixels, browser chrome, a monitor bezel, or other content that completely changes global Auto Color/Otsu statistics even though a manually cropped screenshot scans instantly. Normal scanning stays unchanged and fast because these recovery crops run only after a miss. Finder-only recovery also tries multiple center-weighted Auto Color histograms before threshold bracketing. `cameraAutoColorEvery` defaults to 1 so the same-frame Auto Color recovery is attempted immediately after each fast miss. Multi-frame voting remains enabled by default with a four-frame history. The optional `onDiagnostic(event)` callback exposes finder candidates, active locator method, crop/geometry/version hypothesis, recovery method, timing, and scan dimensions. `onResult(result, frame)` receives the exact raw decoded camera frame and, when Auto Color was used, the enhanced recovery pixels and their crop rectangle, 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. A normal frame always gets the fast RGB-value finder pass first. If a miss still exposes at least two strong finder patterns, QuadQR retries the visible camera ROI at up to 1600 px by default so dense symbols retain more pixels per module. This high-resolution retry is bounded and does not run on empty frames. If it still fails, the **same captured frame** enters a QR-guide recovery path: QuadQR progressively crops away 8%, 16%, and 22% of the surrounding camera frame (then tries the full frame as a final fallback), applies the Photoshop-style Auto Color correction inside that code-centric region, and runs finder detection again. This matters because a live preview can contain dark room pixels, browser chrome, a monitor bezel, or other content that completely changes global Auto Color/Otsu statistics even though a manually cropped screenshot scans instantly. Normal scanning stays unchanged and fast because these recovery paths run only after a miss. Finder-only recovery also tries multiple center-weighted Auto Color histograms before threshold bracketing. `cameraHighResolutionMaxDimension` defaults to 1600, `cameraHighResolutionEvery` defaults to 2, and `cameraAutoColorEvery` defaults to 1. Multi-frame voting remains enabled by default with a four-frame history. The optional `onDiagnostic(event)` callback exposes finder candidates, active locator method, crop/geometry/version hypothesis, recovery method, timing, and scan dimensions. `onResult(result, frame)` receives the exact raw decoded camera frame and, when Auto Color was used, the enhanced recovery pixels and their crop rectangle, so UIs can keep the frozen frame and finder overlay aligned.
 
 ### `getVersionInfo(version, options?)`