quadqr-js 1.3.0 → 1.4.2

package/FORMAT.md

@@ -361,13 +361,13 @@ The decoder also tries legacy physical order as a fallback for older QuadQR matr
 
 Unused data positions are filled with deterministic pseudo-random values in the range 0..3. Padding is not semantically decoded.
 
-## Confidence-aware error/erasure decoding
+## Spectrum ECC 2.0 confidence-aware and soft decoding
 
-For image/camera scans, classification retains more than the winning RGBW state. Each sampled module also receives a confidence score derived from the separation between its nearest and second-nearest calibrated palette states.
+For image/camera scans, classification retains more than the winning RGBW/Triangle16 state. Each sampled data cell receives a confidence score and a bounded second hypothesis derived from the calibrated palette classification. Triangle16 also incorporates the measured disagreement between its three interior samples per triangle so edge bleed or sub-module geometry instability lowers confidence instead of becoming false certainty.
 
-One GF(256) symbol corresponds to four 2-bit data cells. The symbol confidence is the minimum confidence of those four constituent cells because an error in any one cell changes the reconstructed byte.
+In normal RGBW mode, one GF(256) byte symbol corresponds to four 2-bit cells. In High Density Mode, a body byte corresponds to two 4-bit Triangle16 cells, while the protected header remains four solid RGBW-equivalent cells per byte. Symbol confidence is the minimum confidence of its constituent cells because an error in any constituent cell changes the reconstructed byte.
 
-Decoding first attempts normal hard-decision Reed-Solomon correction. If that fails, low-confidence byte positions are progressively promoted to known erasures and the decoder retries error/erasure RS correction. Valid correction requires syndrome verification and the complete QuadQR payload still must pass CRC-32.
+Decoding first attempts normal hard-decision Reed-Solomon correction. If that fails, low-confidence byte positions are progressively promoted to known erasures and the decoder retries error/erasure RS correction. If that still fails and scanner second hypotheses are available, Spectrum ECC 2.0 performs a bounded Chase-style search over the least-confident cells, trying single alternate substitutions and then a small pair set. Every candidate is passed through the unchanged RS and CRC validation path.
 
 The RS budget follows the usual error/erasure relationship:
 
@@ -391,11 +391,13 @@ RGB frame
   -> distributed alignment-grid validation
   -> projective module sampling
   -> observed black/white/R/G/B calibration
-  -> nearest calibrated RGBW classification + confidence
+  -> observed-palette / white-balance / affine calibration attempts
+  -> RGBW or Triangle16 classification + confidence + second hypothesis
   -> four-state XOR unmasking
   -> reverse spectral-spatial permutation
   -> protected header GF(256) hard RS decode
   -> confidence-guided error/erasure retry when needed
+  -> bounded second-hypothesis soft retry when needed
   -> body block deinterleaving
   -> body GF(256) error/erasure correction
   -> CRC-32 verification
@@ -424,4 +426,4 @@ 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.
+These bits are not a public payload-type mode. Applications continue to encode normal UTF-8 text or arbitrary bytes. Compression 3.0 (fast Auto, CPU-heavy Smart, explicit LZ/DEFLATE/Brotli levels with legacy LZ wire compatibility) 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

@@ -11,7 +11,7 @@
 <p align="center">
   <a href="https://akanshsirohi.github.io/QuadQR/demo/"><strong>Try the Live Demo</strong></a>
   ·
-  <a href="https://akanshsirohi.github.io/QuadQR/docs-site/"><strong>Documentation Site</strong></a>
+  <a href="https://akanshsirohi.github.io/QuadQR/documentation/"><strong>Documentation Site</strong></a>
   ·
   <a href="https://www.npmjs.com/package/quadqr-js">npm</a>
   ·
@@ -19,11 +19,9 @@
   ·
   <a href="#getting-started">Use the Library</a>
   ·
-  <a href="docs/README.md">Markdown Docs</a>
+  <a href="https://akanshsirohi.github.io/QuadQR/documentation/format.html">Format Reference</a>
   ·
-  <a href="FORMAT.md">Matrix Format</a>
-  ·
-  <a href="SPECIFICATION.md">Technical Specification</a>
+  <a href="https://akanshsirohi.github.io/QuadQR/documentation/specification.html">Technical Specification</a>
 </p>
 
 **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.
@@ -59,7 +57,7 @@ const code = encodeText("High-density QuadQR", {
 
 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.
+See the [High Density Mode documentation](https://akanshsirohi.github.io/QuadQR/documentation/high-density.html) 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.
 
@@ -72,12 +70,12 @@ Below are QuadQR symbols generated with different error-correction profiles. The
 <table>
   <tr>
     <td align="center">
-      <img src="assets/quadqr-v2-L.png?raw=true" alt="QuadQR example using ECC profile L" width="320"><br>
-      <sub><strong>ECC L</strong> · Higher payload capacity</sub>
+      <img src="assets/quadqr-normal.png?raw=true" alt="QuadQR example using ECC profile L" width="320"><br>
+      <sub><strong>QuadQR</strong> · Normal (v3)</sub>
     </td>
     <td align="center">
-      <img src="assets/quadqr-v2-M.png?raw=true" alt="QuadQR example using ECC profile M" width="320"><br>
-      <sub><strong>ECC M</strong> · More error-correction redundancy</sub>
+      <img src="assets/quadqr-high-density.png?raw=true" alt="QuadQR example using ECC profile M" width="320"><br>
+      <sub><strong>QuadQR</strong> · Higher Data Density (v2)</sub>
     </td>
   </tr>
 </table>
@@ -158,13 +156,13 @@ So at the raw data-cell level:
 
 This is a **2× raw symbol-density advantage**.
 
-### Spectrum ECC: QuadQR-specific reliability without capacity loss
+### Spectrum ECC 2.0: confidence-aware + soft decoding
 
-QuadQR now uses a second idea that is possible because the scanner already measures calibrated color rather than only black/white state: **confidence-aware Reed-Solomon recovery**.
+QuadQR uses the fact that a color scanner knows more than only the winning state. For each sampled data cell it now retains the selected state, a confidence score, and a bounded second hypothesis. Triangle16 does the same after classifying both color regions.
 
-For every sampled RGBW data module, the scanner keeps both the selected state and a confidence score based on the distance to the nearest and second-nearest calibrated color states. Four module confidences are combined into the confidence of their GF(256) byte symbol.
+The first recovery layer is still confidence-aware GF(256) Reed-Solomon: if normal hard-decision decoding fails, the least-confident byte symbols can be promoted to **known erasures**, allowing the existing parity budget to be spent more efficiently.
 
-If normal hard-decision Reed-Solomon decoding fails, the least-confident byte symbols can be promoted to **known erasures**. Reed-Solomon can spend parity more efficiently on known erasure locations than on completely unknown errors. CRC-32 remains the final acceptance check.
+**Spectrum ECC 2.0** adds a bounded soft-decision fallback. If hard decoding and erasure decoding still fail, the decoder tries the second hypothesis for a small number of the least-confident data cells, first singly and then in tightly bounded pairs. Every candidate must still pass the normal Reed-Solomon checks and final CRC-32, so soft decoding does not relax integrity validation or add parity overhead.
 
 QuadQR also applies a deterministic **spectral-spatial interleaver** after ECC. Neighboring logical codeword cells are scattered across distant physical data positions, so a scratch, glare patch, shadow, or localized print defect tends to affect many different RS symbols instead of destroying a contiguous run. The permutation is reversible and consumes **zero extra data cells**.
 
@@ -223,6 +221,24 @@ const compressed = encodeText("repeated repeated repeated", {
   ecc: "M"
 });
 
+// Smart is CPU-heavy and only escalates when stronger compression can
+// realistically reduce the physical QuadQR version.
+const smart = encodeText(largeStructuredText, { compression: "smart" });
+
+// Explicit codecs can choose their encoder level.
+const lz = encodeText(largeStructuredText, {
+  compression: "lz",
+  compressionLevel: 9
+});
+const brotli = encodeText("hello ".repeat(1000), {
+  compression: "brotli",
+  compressionLevel: 11
+});
+const deflate = encodeText(largeStructuredText, {
+  compression: "deflate",
+  compressionLevel: 9
+});
+
 const keys = await generateSigningKeyPair();
 const signed = await encodeSignedText("verified offline", {
   compression: "auto",
@@ -238,7 +254,7 @@ 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.
+Compression modes are `none`, `auto`, `smart`, `brotli`, `deflate`, and `lz`. `auto` is the fast default: it compares LZ level 6, DEFLATE level 6, and Brotli quality 6 once, including envelope overhead, and keeps the smallest final representation. `smart` is an opt-in CPU-heavy mode. It starts with the same balanced pass, checks the resulting QuadQR version, and only escalates to DEFLATE 8 / Brotli 9 and then DEFLATE 9 / Brotli 11 when a smaller physical version is realistically reachable; LZ stays at its default level in Auto/Smart. Explicit `lz` accepts `compressionLevel: 1..9` with default 6, explicit `deflate` accepts `1..9` with default 6, and explicit `brotli` accepts `0..11` with default 11. Compression level is an encoder-only setting and is not stored in the symbol because the decoder does not need it. All codecs are synchronous and bundled with QuadQR, so the same compression path works in browsers and server-side Node.js without `node:zlib`, `CompressionStream`, or a runtime dependency. The demo keeps these CPU-heavy operations in module Web Workers so the browser UI remains responsive. See the [compression documentation](https://akanshsirohi.github.io/QuadQR/documentation/compression.html) for the exact Smart escalation policy and level API. 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`.
 
@@ -250,7 +266,7 @@ Scanner results include normalized diagnostics such as `confidence`, `geometryCo
 
 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).
+The interoperability details are covered in the [technical specification](https://akanshsirohi.github.io/QuadQR/documentation/specification.html).
 
 ---
 
@@ -465,7 +481,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. 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.
+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, a 3×4 affine color-calibration model learned from the known black/white/R/G/B references, spatial normalization, Auto Tone / Auto Contrast / QuadQR 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.
 
 ---
 
@@ -537,17 +553,17 @@ module-grid reconstruction
   ↓
 fast observed-RGB decode attempt
   ↓ (only if needed)
-white balance + spatial normalization
+white balance + affine cross-channel calibration + spatial normalization
   ↓ (only if still needed)
-Auto Tone / Auto Contrast / Auto Color-style recovery
+Auto Tone / Auto Contrast / QuadQR Auto Color-style recovery
   ↓ (only if still needed)
 sub-module geometry refinement
   ↓
 RGB + structural black/white calibration
   ↓
-nearest-color classification + confidence scoring
+RGBW/Triangle16 classification + confidence + second hypothesis
   ↓
-four-state unmasking
+unmasking
   ↓
 reverse spectral-spatial permutation
   ↓
@@ -555,6 +571,8 @@ protected header Reed-Solomon hard decode
   ↓
 confidence-guided erasure retry when needed
   ↓
+bounded Spectrum ECC 2.0 soft-hypothesis retry when needed
+  ↓
 body deinterleaving + error/erasure Reed-Solomon decode
   ↓
 CRC-32 verification
@@ -644,7 +662,7 @@ Logo overlays intentionally consume some ECC margin because they cover encoded c
 
 **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 generator keeps only payload, version, and ECC visible by default; optional capabilities are grouped into independent advanced accordions.
+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. CPU-heavy encoding/compression, rendered-image verification, uploaded-image scanning, scanability tests, Reliability Lab runs, perspective sweeps, and codec benchmarks are dispatched to module Web Workers. Generation shows explicit progress instead of freezing the browser, repeated UI changes are coalesced, and render-only changes reuse the already encoded matrix instead of recompressing the payload.
 
 ### Generator & Image Scanner
 
@@ -764,7 +782,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.1.0/dist/quadqr.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.4.1/dist/quadqr.min.js"></script>
 <script>
   const code = QuadQR.encodeText("Hello from a script tag");
 </script>
@@ -798,7 +816,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 compression, raw 256-bit key mode, signing, print mode, and scanner diagnostics.
+See the [CLI reference](https://akanshsirohi.github.io/QuadQR/documentation/cli.html) for all CLI options, including compression, raw 256-bit key mode, signing, print mode, and scanner diagnostics.
 
 ### Run from source
 
@@ -896,25 +914,29 @@ dist/
 
 demo/
   index.html         Interactive generator, image scanner, camera scanner, benchmark
-  app.js
+  app.js             Responsive UI + worker orchestration
+  compute-worker.js  Background encode/scan/reliability/benchmark tasks
   styles.css
 
-docs-site/
-  index.html         Standalone documentation website
-  app.js
-  styles.css
+documentation/
+  index.html         Documentation home
+  getting-started.html
+  browser.html
+  node.html
+  scanning.html
+  compression.html
+  security.html
+  high-density.html
+  reliability.html
+  api.html
+  cli.html
+  wasm.html
+  format.html
+  specification.html
+  app.js             Navigation, search, copy, and theme behavior
+  search-index.js    Client-side documentation search index
+  styles.css         Responsive documentation UI
 
-docs/
-  README.md          Markdown documentation index
-  GETTING_STARTED.md
-  API.md
-  BROWSER_CDN.md
-  NODE.md
-  SECURITY.md
-  CLI.md
-  WASM.md
-
-types/               TypeScript declarations for JavaScript consumers
 bin/                 `quadqr` CLI (`npx quadqr-js`)
 scripts/             Build, benchmark, and local server scripts
 tests/               Codec and package distribution tests
@@ -1059,7 +1081,7 @@ Returns a standalone SVG string using the same exact `imageSize`, render styles,
 
 ### `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. 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.
+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 / QuadQR 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?)`
 
@@ -1071,7 +1093,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 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.
+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 QuadQR-specific QuadQR 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 QuadQR 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 QuadQR Auto Color histograms before threshold bracketing. `cameraHighResolutionMaxDimension` defaults to 1600, `cameraHighResolutionEvery` defaults to 2, and `cameraAutoColorEvery` defaults to 1. Multi-frame confidence fusion remains enabled by default with a four-frame history. Frames are kept only when their high-confidence data cells are consistent with the current tracked symbol. Per-cell evidence is weighted by confidence, frame quality, and recency, while second hypotheses are retained for Spectrum ECC 2.0. 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 QuadQR 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?)`
 
@@ -1112,7 +1134,10 @@ The current test suite covers areas including:
 - color-cast scanning;
 - dirty-camera stress scanning with strong yellow cast, haze, blue-channel suppression, and blur;
 - low-contrast warm-camera regression where normal scanning fails but progressive Auto Tone / Contrast / Color recovery succeeds;
-- multi-frame classification voting;
+- multi-frame confidence fusion and tracked-symbol consistency;
+- Spectrum ECC 2.0 bounded soft-decision recovery;
+- affine cross-channel color calibration;
+- multi-point Triangle16 region sampling with instability-aware confidence;
 - benchmark reference data;
 - timed codec round trips;
 - password-mode secure round trips and wrong-password rejection;

package/SPECIFICATION.md

@@ -42,7 +42,7 @@ Structural black is separate from the data alphabet. One encoded byte maps to ex
 
 ### High Density Mode
 
-When `highDensity: true` is selected, each payload module has a fixed `/` diagonal and two independently classified RGBW regions. This creates 16 states and 4 raw bits per body cell. The protected header stays solid-color at 2 bits per cell for robust bootstrap recovery, then header flag bit 6 tells the decoder that the ECC/body stream uses Triangle16 packing. Scanner sampling uses two points well inside the triangles and excludes the diagonal boundary.
+When `highDensity: true` is selected, each payload module has a fixed `/` diagonal and two independently classified RGBW regions. This creates 16 states and 4 raw bits per body cell. The protected header stays solid-color at 2 bits per cell for robust bootstrap recovery, then header flag bit 6 tells the decoder that the ECC/body stream uses Triangle16 packing. Scanner sampling uses three interior anchors per triangle, robust aggregation, and a spatial-instability penalty while excluding the diagonal boundary.
 
 ## 3. Matrix sizing
 
@@ -87,7 +87,7 @@ Version 2+ parity profiles:
 | Q | 36 | 18 |
 | H | 48 | 24 |
 
-The decoder retains per-cell color confidence. Low-confidence bytes can be promoted to known erasures, allowing Reed-Solomon recovery to use the existing parity budget more efficiently.
+The decoder retains per-cell color confidence and one bounded alternate hypothesis from image/camera classification. Low-confidence bytes can first be promoted to known erasures, allowing Reed-Solomon recovery to use the existing parity budget more efficiently. If hard and error/erasure decoding still fail, Spectrum ECC 2.0 may try the alternate state for a bounded set of the least-confident cells. Candidate search is limited to single substitutions and a small pair set by default, and every successful path must still satisfy Reed-Solomon verification and CRC-32.
 
 ## 6. Internal payload extension envelope
 
@@ -104,12 +104,12 @@ Fixed header size: **16 bytes**.
 | Offset | Size | Field |
 |---:|---:|---|
 | 0 | 4 | ASCII magic `QPX1` |
-| 4 | 1 | Extension version (`2`; decoder also accepts legacy `1`) |
+| 4 | 1 | Extension version (`3`; decoder also accepts legacy `1` and `2`) |
 | 5 | 1 | Flags |
 | 6 | 1 | Compression ID |
 | 7 | 1 | Signature algorithm ID |
 | 8 | 4 | Original application payload length, big-endian |
-| 12 | 1 | Signing key-ID length (v2); legacy signer-label length in v1 |
+| 12 | 1 | Signing key-ID length (v2+); legacy signer-label length in v1 |
 | 13 | 1 | Optional embedded public-key length |
 | 14 | 1 | Signature length |
 | 15 | 1 | Reserved (`0`) |
@@ -136,25 +136,40 @@ Compression IDs:
 
 ```text
 0 = none
-1 = QuadQR portable LZ
+1 = QuadQR portable LZ (legacy)
+2 = QuadQR portable raw DEFLATE
+3 = bundled Brotli
 ```
 
-The portable LZ stream is an LZSS-style format with groups of up to eight tokens. Each group begins with one flag byte. A flag bit of `0` means a one-byte literal. A flag bit of `1` means a two-byte back-reference:
+Compression ID `1` is the original LZSS-style stream with groups of up to eight tokens. Each group begins with one flag byte. A flag bit of `0` means a one-byte literal. A flag bit of `1` means a two-byte back-reference:
 
 ```text
 12-bit offset: 1..4095 bytes
 4-bit length: stored value + 3, therefore 3..18 bytes
 ```
 
+Compression ID `1` keeps the original QuadQR LZSS-style stream. Encoder levels `1..9` control candidate-history depth and bounded lazy-match effort; level 6 preserves the historical 32-candidate search depth. The 4095-byte window, 3..18 byte back-reference format, and decoder remain unchanged, and the level is not serialized.
+
+Compression ID `2` is a raw RFC 1951 DEFLATE stream. QuadQR's portable encoder uses a deterministic fixed-Huffman block, a 32 KiB LZ77 window, distances up to 32768 bytes, and matches up to 258 bytes. Encoder levels `1..9` control candidate-chain depth and lazy-match effort; the level is not serialized and does not change decoder behavior. The QuadQR decoder accepts the stored/fixed block forms emitted by the library.
+
+Compression ID `3` is a standard Brotli stream produced and decoded by QuadQR's bundled synchronous JavaScript codec. It uses no Node `zlib`, browser `CompressionStream`, DOM API, native addon, or network-loaded codec at runtime. Brotli is especially effective for repetitive text and structured payloads, while DEFLATE and legacy LZ remain available for deterministic selection and backward compatibility.
+
 Public compression modes are:
 
 ```text
 none
 auto
+smart
+brotli
+deflate
 lz
 ```
 
-`compression: "auto"` uses compression only when it meaningfully reduces payload size. When it does not help and the payload is not signed, QuadQR stores the original payload directly with **no extension-envelope overhead**.
+`compression: "auto"` is the fast balanced policy. It evaluates LZ level 6, DEFLATE level 6, and Brotli quality 6 exactly once and chooses the smallest complete stored representation. For unsigned payloads that comparison includes the 16-byte extension-envelope cost, so Auto remains zero-overhead when compression is not useful.
+
+`compression: "smart"` is the opt-in CPU-heavy policy. It begins with the Auto candidates, computes the resulting Format v5 QuadQR version using the selected ECC/profile/version bounds, and only escalates when the next smaller matrix is plausibly reachable. The strong stage tests DEFLATE 8 and Brotli 9. If the symbol remains close to a smaller-version boundary, the maximum stage tests DEFLATE 9 and Brotli 11. With an explicitly requested fixed version, Smart does not chase a smaller matrix, but it may escalate when the balanced result does not fit and stronger compression can plausibly make that requested version fit. Signed and secure pipelines include their fixed envelope overhead when evaluating those version boundaries.
+
+Explicit `compression: "lz"` and `compression: "deflate"` accept `compressionLevel` `1..9` and default to 6. Explicit `compression: "brotli"` accepts `compressionLevel` `0..11` and defaults to 11. Compression levels are encoder-only parameters and are intentionally not stored in the extension envelope because LZ, RFC 1951, and Brotli decoders do not require them. Auto and Smart use LZ level 6; Smart's staged escalation remains focused on DEFLATE/Brotli.
 
 Compression occurs before signing, encryption, and Format v5 ECC.
 
@@ -162,7 +177,7 @@ Compression occurs before signing, encryption, and Format v5 ECC.
 
 Signature algorithm ID `1` is **Ed25519**.
 
-Signed payloads in extension v2 store:
+Signed payloads in extension v2/v3 store:
 
 ```text
 optional compact key ID

package/bin/quadqr.js

@@ -15,7 +15,7 @@ import {
 import { savePNG, saveSVG, scanFile } from "../dist/node.js";
 
 function help() {
-  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png|file.svg] [--ecc M] [--version auto|1..40] [--high-density]\n  quadqr encode <text> [--compression auto]\n  quadqr encode <text> --sign-key signing-key.json [--key-id issuer-main]\n  quadqr encode <text> --password <password> [-o file.png|file.svg]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>] [--verify-key signing-key.json] [--debug]\n  quadqr keygen\n  quadqr signkeygen [-o signing-key.json]\n\nOptions:\n  -o, --output <file>       Output PNG/SVG path, or signing-key JSON for signkeygen\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --compression <mode>      none|auto|lz (default: auto)\n  --high-density            Enable experimental Triangle16 High Density Mode\n  --sign-key <file>         Sign using a signkeygen JSON bundle\n  --key-id <id>             Override the signing key ID stored in the QuadQR\n  --embed-public-key        Also embed the public key for untrusted/self-contained checks\n  --verify-key <file>       Verify a signed QuadQR with a trusted key bundle\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --print                   Use the print-safe render profile\n  --image-size <px>         Exact square output size (default: 720)\n  --module-size <px>        Legacy pixels-per-module sizing\n  --quiet-zone <modules>    Quiet zone in modules (default: 4)\n  --debug                   Emit scanner diagnostics to stderr on decode\n  -h, --help                Show help\n`);
+  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png|file.svg] [--ecc M] [--version auto|1..40] [--high-density]\n  quadqr encode <text> [--compression auto]\n  quadqr encode <text> --sign-key signing-key.json [--key-id issuer-main]\n  quadqr encode <text> --password <password> [-o file.png|file.svg]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>] [--verify-key signing-key.json] [--debug]\n  quadqr keygen\n  quadqr signkeygen [-o signing-key.json]\n\nOptions:\n  -o, --output <file>       Output PNG/SVG path, or signing-key JSON for signkeygen\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --compression <mode>      none|auto|smart|brotli|deflate|lz (default: auto)\n  --compression-level <n>   Explicit LZ/DEFLATE 1..9 or Brotli 0..11 level\n  --high-density            Enable experimental Triangle16 High Density Mode\n  --sign-key <file>         Sign using a signkeygen JSON bundle\n  --key-id <id>             Override the signing key ID stored in the QuadQR\n  --embed-public-key        Also embed the public key for untrusted/self-contained checks\n  --verify-key <file>       Verify a signed QuadQR with a trusted key bundle\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --print                   Use the print-safe render profile\n  --image-size <px>         Exact square output size (default: 720)\n  --module-size <px>        Legacy pixels-per-module sizing\n  --quiet-zone <modules>    Quiet zone in modules (default: 4)\n  --debug                   Emit scanner diagnostics to stderr on decode\n  -h, --help                Show help\n`);
 }
 
 function parse(argv) {
@@ -31,6 +31,7 @@ function parse(argv) {
     else if (token === "--password") flags.password = argv[++i];
     else if (token === "--key") flags.key = argv[++i];
     else if (token === "--compression") flags.compression = argv[++i];
+    else if (token === "--compression-level") flags.compressionLevel = Number(argv[++i]);
     else if (token === "--sign-key") flags.signKey = argv[++i];
     else if (token === "--key-id") flags.keyId = argv[++i];
     else if (token === "--embed-public-key") flags.embedPublicKey = true;
@@ -104,6 +105,7 @@ async function main() {
       ecc: flags.ecc || "M",
       highDensity: Boolean(flags.highDensity),
       compression: flags.compression || "auto",
+      ...(Number.isFinite(flags.compressionLevel) ? { compressionLevel: flags.compressionLevel } : {}),
       ...(flags.version && flags.version !== "auto" ? { version: Number(flags.version) } : {})
     };
     const signingBundle = flags.signKey ? await readSigningBundle(flags.signKey) : null;
@@ -140,7 +142,7 @@ async function main() {
     const saved = output.toLowerCase().endsWith(".svg")
       ? await saveSVG(code, output, renderOptions)
       : await savePNG(code, output, renderOptions);
-    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ${code.highDensity ? "High Density experimental" : "Normal RGBW"}, ECC ${code.eccLevel}).`);
+    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ${code.highDensity ? "High Density experimental" : "Normal RGBW"}, ECC ${code.eccLevel}${code.compressed ? `, ${code.compression}${code.compressionLevel != null ? ` level ${code.compressionLevel}` : ""}` : ""}).`);
     return;
   }
 

package/dist/esm/benchmark.js

@@ -12,6 +12,8 @@ import {
   decodeMatrix,
   getVersionInfo,
   compressPayload,
+  compressDeflatePayload,
+  compressBrotliPayload,
   MAX_VERSION
 } from "./quadqr.js";
 
@@ -130,29 +132,57 @@ export function calculateCapacityPlan(options = {}) {
   else if (typeof options.payload === "string") sourceBytes = new TextEncoder().encode(options.payload);
   else sourceBytes = new Uint8Array(Math.max(0, Math.floor(options.payloadBytes ?? 0)));
 
-  const requestedCompression = options.compression ?? "none";
+  const requestedCompression = String(options.compression ?? "none").toLowerCase();
+  if (!["none", "auto", "smart", "lz", "deflate", "brotli"].includes(requestedCompression)) {
+    throw new Error("compression must be none, auto, smart, lz, deflate, or brotli.");
+  }
   const signed = Boolean(options.signed);
   const keyIdBytes = options.keyId ? new TextEncoder().encode(String(options.keyId)).length : 0;
   const envelopeHeaderBytes = 16;
   const signingBytes = signed ? 64 + keyIdBytes + (options.embedPublicKey ? 32 : 0) : 0;
   let compression = requestedCompression;
+  let compressionLevel = null;
   let storedBytes = sourceBytes.length;
   let compressed = false;
 
   if (requestedCompression !== "none" && hasConcretePayload) {
-    const candidate = compressPayload(sourceBytes);
-    if (requestedCompression === "lz" || candidate.length < sourceBytes.length - 2) {
-      storedBytes = candidate.length;
+    const candidates = [];
+    const explicitLevel = options.compressionLevel;
+    if (requestedCompression === "auto" || requestedCompression === "smart" || requestedCompression === "lz") {
+      const level = requestedCompression === "lz" ? (explicitLevel ?? options.lzLevel ?? 6) : 6;
+      candidates.push({ compression: "lz", bytes: compressPayload(sourceBytes, { level }).length, level });
+    }
+    if (requestedCompression === "auto") {
+      candidates.push({ compression: "deflate", bytes: compressDeflatePayload(sourceBytes, { level: 6 }).length, level: 6 });
+      candidates.push({ compression: "brotli", bytes: compressBrotliPayload(sourceBytes, { quality: 6 }).length, level: 6 });
+    } else if (requestedCompression === "smart") {
+      for (const level of [6, 8, 9]) candidates.push({ compression: "deflate", bytes: compressDeflatePayload(sourceBytes, { level }).length, level });
+      for (const level of [6, 9, 11]) candidates.push({ compression: "brotli", bytes: compressBrotliPayload(sourceBytes, { quality: level }).length, level });
+    } else if (requestedCompression === "deflate") {
+      const level = explicitLevel ?? options.deflateLevel ?? 6;
+      candidates.push({ compression: "deflate", bytes: compressDeflatePayload(sourceBytes, { level }).length, level });
+    } else if (requestedCompression === "brotli") {
+      const level = explicitLevel ?? options.brotliQuality ?? 11;
+      candidates.push({ compression: "brotli", bytes: compressBrotliPayload(sourceBytes, { quality: level }).length, level });
+    }
+    if (!candidates.length) throw new Error("compression must be none, auto, smart, lz, deflate, or brotli.");
+    candidates.sort((a, b) => a.bytes - b.bytes);
+    const best = candidates[0];
+    const compressionOverhead = signed ? 0 : envelopeHeaderBytes;
+    if (!["auto", "smart"].includes(requestedCompression) || best.bytes + compressionOverhead < sourceBytes.length) {
+      storedBytes = best.bytes;
       compressed = true;
-      compression = "lz";
+      compression = best.compression;
+      compressionLevel = best.level ?? null;
     } else {
       compression = "none";
+      compressionLevel = null;
     }
   } else if (requestedCompression !== "none" && !hasConcretePayload) {
     compression = "unknown";
   }
 
-  const needsEnvelope = signed || compressed || requestedCompression === "lz";
+  const needsEnvelope = signed || compressed || requestedCompression === "lz" || requestedCompression === "deflate" || requestedCompression === "brotli";
   const encodedBytes = storedBytes + (needsEnvelope ? envelopeHeaderBytes + signingBytes : 0);
   const extensionOverheadBytes = encodedBytes - storedBytes;
 
@@ -185,6 +215,7 @@ export function calculateCapacityPlan(options = {}) {
     storedBytes,
     extensionOverheadBytes,
     compression,
+    compressionLevel,
     compressed,
     signed,
     quadqrVersion,