quadqr-js 1.3.0 → 1.4.2

package/docs/API.md

@@ -179,7 +179,7 @@ const svg = renderToSVG(code, {
 
 ### `scanImageData(imageData, options?)`
 
-Scans an ImageData-like RGBA object. The scanner automatically attempts both normal RGBW center sampling and Triangle16 dual-region sampling when geometry is found. When normal projective geometry is locatable but too coarse for half-cell Triangle16 regions, one bounded precise-alignment recovery pass refines the alignment center at sub-module resolution. Clean frames use the normal observed-RGB path first. Difficult frames then get bounded fallback attempts using per-channel white balancing, spatial black/white normalization, tighter centre sampling, module-grid Auto Tone / Auto Contrast / Auto Color recovery, a rectified QR-region pixel enhancement pass, and sub-module geometry micro-refinement before the scan is rejected. Dense versions also use their distributed alignment markers to refine a noisy four-point projective solution when the initial alignment-grid score is plausible but imperfect. If exactly two strong finder patterns survive a steep angle, a bounded perspective-tolerant third-finder recovery pass is attempted before heavier color recovery.
+Scans an ImageData-like RGBA object. The scanner automatically attempts both normal RGBW center sampling and Triangle16 dual-region sampling when geometry is found. When normal projective geometry is locatable but too coarse for half-cell Triangle16 regions, one bounded precise-alignment recovery pass refines the alignment center at sub-module resolution. Clean frames use the normal observed-RGB path first. Difficult frames then get bounded fallback attempts using per-channel white balancing, spatial black/white normalization, tighter centre sampling, QuadQR module-grid Auto Tone / Auto Contrast / Auto Color recovery, a rectified QR-region pixel enhancement pass, and sub-module geometry micro-refinement before the scan is rejected. Dense versions also use their distributed alignment markers to refine a noisy four-point projective solution when the initial alignment-grid score is plausible but imperfect. If exactly two strong finder patterns survive a steep angle, a bounded perspective-tolerant third-finder recovery pass is attempted before heavier color recovery.
 
 ```js
 const result = scanImageData({
@@ -189,7 +189,7 @@ const result = scanImageData({
 });
 ```
 
-Useful scanner options include `sampleRadius`, `robustSampleRadius`, `adaptiveSampling`, `spatialColorNormalization`, `autoEnhanceRecovery`, `rectifiedAutoEnhanceRecovery`, `rectifiedRecoveryModuleSize`, `autoEnhanceBlackClip`, `autoEnhanceWhiteClip`, `autoEnhanceSaturation`, `geometryRefinement`, `alignmentRefinement`, `alignmentRefinePatternThreshold`, `refinementOffset`, `structureTolerance`, and `maxErasureConfidence`. Auto enhancement and geometry refinement are enabled by default, but bounded recovery work only runs when the normal scan path or initial geometry needs it.
+Useful scanner options include `sampleRadius`, `robustSampleRadius`, `adaptiveSampling`, `spatialColorNormalization`, `autoEnhanceRecovery`, `rectifiedAutoEnhanceRecovery`, `rectifiedRecoveryModuleSize`, `geometryRefinement`, `alignmentRefinement`, `structureTolerance`, `maxErasureConfidence`, `softDecoding`, `softDecodeConfidence`, `softDecodeMaxCells`, and `softDecodePairCells`. Spectrum ECC 2.0 soft decoding is bounded and only runs after ordinary hard/error-erasure decoding fails.
 
 ### Browser `scanFile(file, options?)`
 
@@ -209,13 +209,15 @@ 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 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 Auto Color and Otsu thresholds. Each crop uses the Photoshop-style per-channel shadow/highlight correction with a neutral mid-high highlight target (190 by default). Finder-only recovery also tries multiple center-weighted 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 the stronger color/geometry recovery, and consecutive failed frames can still be combined with confidence-weighted module voting.
+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.
 
 ```js
 const scanner = await startCameraScanner(video, {
   scanInterval: 120,
   multiFrame: true,
   multiFrameWindow: 4,
+  multiFrameMinFrames: 2,
+  softDecoding: true,
   cameraAutoColorEvery: 1,
   cameraAutoColorCropInsets: [0.08, 0.16, 0.22, 0],
   cameraAutoColorHighlightPercentile: 0.95,
@@ -410,17 +412,38 @@ const code = QuadQR.encodeText("hello hello hello", {
 });
 ```
 
-`compression` may be `none`, `auto`, or `lz`.
+`compression` may be `none`, `auto`, `smart`, `brotli`, `deflate`, or `lz`.
 
 - `none` stores the payload directly.
-- `auto` compresses only when the result is meaningfully smaller. If compression does not help, no internal envelope is added.
-- `lz` always stores the payload through QuadQR's portable LZ compressor.
+- `auto` is the fast balanced mode: one pass each of LZ level 6, DEFLATE level 6, and Brotli quality 6, followed by a complete stored-size comparison including envelope overhead.
+- `smart` is the CPU-heavy mode. It starts with the Auto 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.
+- `brotli` always stores the payload using QuadQR's bundled synchronous Brotli codec.
+- `deflate` always stores the payload using QuadQR's synchronous pure-JavaScript raw DEFLATE codec.
+- `lz` always stores the payload through the original portable LZSS-style compressor for backward compatibility.
+
+Explicit LZ, DEFLATE, and Brotli support `compressionLevel`:
+
+```js
+encodeText(text, { compression: "lz", compressionLevel: 9 }); // 1..9, default 6
+encodeText(text, { compression: "deflate", compressionLevel: 9 }); // 1..9, default 6
+encodeText(text, { compression: "brotli", compressionLevel: 11 }); // 0..11, default 11
+```
+
+`lzLevel`, `deflateLevel`, and `brotliQuality` are accepted as algorithm-specific aliases. Levels affect encoder effort only and are not serialized because the decoder does not need them. Generated code objects expose `compressionLevel`, `compressionStrategy`, and Smart-mode diagnostics; scanned symbols only need the stored compression algorithm ID.
 
 There is no public content-type registry. Text remains text and byte arrays remain byte arrays.
 
-### `compressPayload(input)` / `decompressPayload(input, expectedLength?)`
+### `compressPayload(input, options?)` / `decompressPayload(input, expectedLength?)`
+
+Legacy portable synchronous LZSS-style compression helpers. `options.level` accepts integers `1..9` and defaults to 6. Higher levels walk deeper candidate history and may use bounded lazy matching; level 6 preserves the historical QuadQR search depth. The LZ wire format and decoder are unchanged at every level.
+
+### `compressDeflatePayload(input, options?)` / `decompressDeflatePayload(input, expectedLength?)`
 
-Portable synchronous LZSS-style compression helpers. They do not require Node zlib or browser `CompressionStream`.
+Raw-DEFLATE helpers. `options.level` accepts integers `1..9` and defaults to 6. Higher levels spend more CPU on deeper LZ77 candidate search and lazy matching. The compressor emits standard RFC 1951 fixed-Huffman blocks with a 32 KiB match window and matches up to 258 bytes. The implementation is pure JavaScript and synchronous, so the same core works in browsers, Node.js servers, workers, and other JavaScript runtimes without `node:zlib`, `CompressionStream`, DOM APIs, or native dependencies.
+
+### `compressBrotliPayload(input, options?)` / `decompressBrotliPayload(input, expectedLength?)`
+
+Bundled synchronous Brotli helpers. `compressBrotliPayload()` accepts an optional `{ quality }` setting from 0 through 11 for direct codec use. The generated stream is standard Brotli and the decoder accepts standard Brotli streams. QuadQR does not require `node:zlib`, browser `CompressionStream`, DOM APIs, a native addon, or a runtime dependency for this path.
 
 ## Binary convenience APIs
 
@@ -536,9 +559,9 @@ Use `scanImageData(image, { debug: true })` for detailed geometry/sampling infor
 
 ## Scanability and stress testing
 
-### `applyStressDistortion(imageData, type, severity?)`
+### `applyStressDistortion(imageData, type, severity?, options?)`
 
-Deterministically applies a selected synthetic distortion.
+Deterministically applies a selected synthetic distortion. In addition to the original blur/exposure/shadow/resampling profiles, `perspective-3d` accepts `pitchDegrees`, `yawDegrees`, and `rollDegrees` for camera-angle testing.
 
 ### `runImageStressTest(imageData, expected?, options?)`
 
@@ -548,4 +571,12 @@ Runs the standard torture profiles and returns a 0–100 score plus per-scenario
 
 Renders a code and runs the standard test suite. It returns `Excellent`, `Good`, `Risky`, or `Likely unscannable` together with recommendations.
 
-Synthetic scores are regression aids and do not replace physical camera/print testing.
+### `runReliabilityLab(imageData, expected?, options?)`
+
+Runs the broader Reliability Lab suite. `options.suite` can be `quick`, `full`, or `extreme`. Results include overall score, per-scenario CRC verification, category scores, confidence, RS corrections, and timing.
+
+### `runPerspectiveSweep(imageData, expected?, options?)`
+
+Sweeps `yaw`, `pitch`, or `roll`/Z rotation across a list of angles and reports the largest tested angle that decoded successfully.
+
+Synthetic scores are regression aids and do not replace physical camera/print testing. See [`RELIABILITY_LAB.md`](./RELIABILITY_LAB.md).

package/docs/BROWSER_CDN.md

@@ -54,6 +54,10 @@ const compressed = encodeText("repeat repeat repeat repeat", {
   compression: "auto"
 });
 
+const smallest = encodeText("structured payload ".repeat(500), {
+  compression: "smart"
+});
+
 const keys = await generateSigningKeyPair();
 const signed = await encodeSignedText("ticket", {
   compression: "auto",
@@ -72,7 +76,7 @@ const report = assessScanability(compressed, { imageSize: 480 });
 console.log(report.score, report.rating);
 ```
 
-Compression and signing use internal metadata only when required. There is no public content-type mode to configure. The private key signs, while the public verification key stays outside the QuadQR by default. Use the stored `keyId` to select an application-trusted public key. Scanability testing is deterministic synthetic regression testing and should be supplemented with real devices and print samples.
+Compression uses bundled synchronous Brotli/DEFLATE/LZ implementations with explicit codec levels, fast Auto, and CPU-heavy Smart modes and signing uses internal metadata only when required. The repository demo keeps heavy encoding, verification, stress testing, perspective sweeps, image scanning, and benchmarks off the UI thread with module Web Workers, while the public library API itself remains synchronous where documented. There is no public content-type mode to configure. The private key signs, while the public verification key stays outside the QuadQR by default. Use the stored `keyId` to select an application-trusted public key. Scanability testing is deterministic synthetic regression testing and should be supplemented with real devices and print samples.
 
 ## Scan an uploaded image
 
@@ -133,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.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 CDN");
 
@@ -147,7 +151,7 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
 ## unpkg
 
 ```html
-<script src="https://unpkg.com/quadqr-js@1.1.0/dist/quadqr.min.js"></script>
+<script src="https://unpkg.com/quadqr-js@1.4.1/dist/quadqr.min.js"></script>
 ```
 
 ## Direct CDN ESM
@@ -157,7 +161,7 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
   import {
     encodeText,
     renderToCanvas
-  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.1.0/dist/browser.js";
+  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.4.1/dist/browser.js";
 
   const code = encodeText("ES module CDN");
   renderToCanvas(code, document.querySelector("#qr"));
@@ -184,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.1.0` 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.4.1` in CDN URLs so an existing site does not silently change when a newer package version becomes available.

package/docs/CLI.md

@@ -33,7 +33,17 @@ npx quadqr-js encode "repeat repeat repeat repeat" \
   -o compressed.png
 ```
 
-Compression modes are `none`, `auto`, and `lz`. `auto` keeps the original payload untouched when compression does not make it smaller. No separate payload mode is required.
+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
 
@@ -133,7 +143,8 @@ npx quadqr-js decode secure-key.png --key <64-hex-key>
 | `-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`, or `lz`. 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 |

package/docs/COMPRESSION.md

@@ -0,0 +1,170 @@
+# Compression 3.0
+
+QuadQR keeps compression as an internal transport detail around normal text or byte payloads. It does not introduce a payload type system, and the decompressor does not need to know which compression level was used.
+
+## Modes
+
+```js
+encodeText(text, { compression: "none" });
+encodeText(text, { compression: "auto" });
+encodeText(text, { compression: "smart" });
+encodeText(text, { compression: "brotli" });
+encodeText(text, { compression: "deflate" });
+encodeText(text, { compression: "lz" });
+```
+
+- `none` stores the application payload directly.
+- `auto` is the fast balanced mode. It performs one pass with LZ level 6, DEFLATE level 6, and Brotli quality 6, compares the complete stored sizes, and keeps the smallest result.
+- `smart` is the opt-in CPU-heavy mode. It starts with the same balanced candidates as `auto`, checks the resulting QuadQR version, and only spends more CPU on stronger DEFLATE/Brotli passes when a smaller physical QuadQR is realistically reachable.
+- `brotli` forces the bundled Brotli codec.
+- `deflate` forces the portable raw-DEFLATE codec.
+- `lz` forces the original QuadQR LZSS-style stream for compatibility and testing.
+
+For unsigned payloads, `auto` and `smart` include the 16-byte internal extension-envelope cost when deciding whether compression helps. If compression would not make the complete stored representation smaller, the original payload is kept with no compression envelope. Signed payloads already require the extension envelope, so their comparison includes the fixed signing metadata automatically. Secure payload planning also includes the fixed encryption-envelope overhead when Smart evaluates version boundaries.
+
+## Auto versus Smart
+
+`auto` intentionally avoids expensive maximum-quality passes:
+
+```text
+Raw
+LZ level 6
+DEFLATE level 6
+Brotli quality 6
+       ↓
+smallest final representation
+```
+
+`smart` begins the same way, then considers the next smaller QuadQR version. When that boundary is close enough to be plausible, it escalates in stages:
+
+```text
+Balanced pass
+  LZ 6
+  DEFLATE 6
+  Brotli 6
+      ↓
+Is a smaller QuadQR version realistically reachable?
+      ↓ yes
+Strong pass
+  DEFLATE 8
+  Brotli 9
+      ↓
+Still close to another/same smaller-version boundary?
+      ↓ yes
+Maximum pass
+  DEFLATE 9
+  Brotli 11
+```
+
+Smart is deliberately CPU-heavy and should be used when minimizing the physical matrix matters more than generation time. If an exact `version` is requested and the balanced pass does not fit, Smart may also escalate to stronger levels when that can plausibly make the requested version fit. The current plausibility gates are intentionally conservative: the strong stage is considered when the next boundary is within 30% of the current stored size or 192 bytes, and the maximum stage when it is within 16% or 96 bytes. The demo runs Smart in a Web Worker so the browser UI remains responsive.
+
+The generated code object includes generation-only diagnostics such as `compressionLevel`, `compressionStrategy`, and `smartCompression`. Compression level is not stored in the QuadQR because LZ, DEFLATE, and Brotli decoders do not need it.
+
+## Explicit compression levels
+
+Use the generic `compressionLevel` option when you explicitly select LZ, DEFLATE, or Brotli:
+
+```js
+const lz = encodeText(text, {
+  compression: "lz",
+  compressionLevel: 9
+});
+
+const deflated = encodeText(text, {
+  compression: "deflate",
+  compressionLevel: 9
+});
+
+const brotlied = encodeText(text, {
+  compression: "brotli",
+  compressionLevel: 11
+});
+```
+
+Ranges and defaults:
+
+| Algorithm | Range | Explicit default |
+| --- | ---: | ---: |
+| Legacy LZ | 1..9 | 6 |
+| DEFLATE | 1..9 | 6 |
+| Brotli | 0..11 | 11 |
+
+Algorithm-specific aliases are also accepted: `lzLevel`, `deflateLevel`, and `brotliQuality`. `compressionLevel` is the recommended public option.
+
+Levels only affect encoder CPU/search effort and output size. They do not change the compression ID or decoder behavior.
+
+## Legacy LZ profile
+
+Compression ID `1` keeps the original QuadQR LZSS-style wire format. Levels `1..9` only control how much encoder work is spent walking candidate history and, at stronger levels, bounded lazy-match lookahead. Level 6 preserves the historical 32-candidate QuadQR search depth, so existing callers that do not pass a level keep the same default behavior.
+
+The direct helpers are:
+
+```js
+compressPayload(bytes, { level: 9 });
+decompressPayload(compressedBytes, originalLength);
+```
+
+The LZ window remains 4095 bytes and each back-reference still represents a 3..18 byte match. The compressed stream format is identical at every level, so the level is never serialized and old/new LZ decoders remain compatible. Auto and Smart use LZ level 6; Smart does not escalate LZ because its additional staged CPU budget is reserved for the stronger DEFLATE/Brotli candidates.
+
+## Brotli profile
+
+Compression ID `3` is a standard Brotli stream. QuadQR vendors the codec into the library so Brotli compression and decompression are synchronous and available in browser ESM, the classic browser bundle, Web Workers, and server-side Node.js without a runtime package or native binding.
+
+The direct helpers are:
+
+```js
+compressBrotliPayload(bytes, { quality: 9 });
+decompressBrotliPayload(compressedBytes, originalLength);
+```
+
+Brotli quality accepts integers `0..11`. Explicit `compression: "brotli"` defaults to quality 11 for backward compatibility. `auto` starts at quality 6. `smart` starts at 6 and may test 9 and 11 when a smaller QuadQR version is plausible.
+
+## Portable DEFLATE profile
+
+Compression ID `2` is a raw RFC 1951 DEFLATE stream. QuadQR's bundled encoder uses a fixed-Huffman block with level-dependent LZ77 match-search effort. It supports:
+
+- a 32 KiB LZ77 window;
+- match distances up to 32768 bytes;
+- match lengths up to 258 bytes;
+- DEFLATE levels `1..9`;
+- progressively deeper candidate search and lazy matching at stronger levels;
+- deterministic synchronous output;
+- no runtime dependency.
+
+The direct helpers are:
+
+```js
+compressDeflatePayload(bytes, { level: 9 });
+decompressDeflatePayload(compressedBytes, originalLength);
+```
+
+The stream remains standard raw DEFLATE at every level. The level is not serialized.
+
+## Node.js and browser portability
+
+All payload compression paths are bundled JavaScript. The library does not import `node:zlib`, use browser `CompressionStream`, depend on DOM APIs, or fetch a codec at runtime.
+
+```js
+import { encodeText, decodeMatrix } from "quadqr-js";
+
+const code = encodeText("hello ".repeat(1000), {
+  compression: "smart"
+});
+
+const decoded = decodeMatrix(code.matrix);
+console.log(code.compression, code.compressionLevel);
+console.log(decoded.compression); // decoder only needs the algorithm ID
+```
+
+## Compression IDs and compatibility
+
+The internal envelope keeps the stable IDs:
+
+```text
+0 = none
+1 = legacy LZ
+2 = raw DEFLATE
+3 = Brotli
+```
+
+Compression level is intentionally not part of the envelope. Existing LZ, DEFLATE, and Brotli decoders remain compatible with streams produced at any supported level.

package/docs/GETTING_STARTED.md

@@ -163,7 +163,7 @@ PNG generation/decoding and SVG generation are built into the Node.js adapter.
 
 ```html
 <canvas id="qr"></canvas>
-<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("No build step");
   QuadQR.renderToCanvas(code, document.querySelector("#qr"));
@@ -201,7 +201,17 @@ const code = encodeText("repeat repeat repeat repeat", {
 });
 ```
 
-`auto` keeps the original payload untouched when compression would not save space.
+`auto` is the fast default: it compares LZ level 6, DEFLATE level 6, and Brotli quality 6 once, then keeps the smallest complete representation. `smart` is the CPU-heavy option; it starts with the same pass and only tries DEFLATE 8/9 and Brotli 9/11 when stronger compression can realistically reduce the QuadQR version.
+
+When you explicitly choose a codec, `compressionLevel` controls encoder effort:
+
+```js
+encodeText(text, { compression: "lz", compressionLevel: 9 }); // 1..9
+encodeText(text, { compression: "deflate", compressionLevel: 9 }); // 1..9
+encodeText(text, { compression: "brotli", compressionLevel: 11 }); // 0..11
+```
+
+LZ defaults to level 6, DEFLATE defaults to level 6, and Brotli defaults to quality 11. The level is not stored in the symbol because decoding does not depend on it.
 
 For offline integrity verification:
 

package/docs/HIGH_DENSITY_MODE.md

@@ -46,9 +46,9 @@ This uses four cells per protected header byte, exactly like RGBW, but makes it
 
 ## Scanner sampling
 
-The scanner does not sample the diagonal or the exact module center. For each data cell it samples two small regions well inside the triangles, approximately around `(0.28, 0.28)` and `(0.72, 0.72)` in normalized module coordinates.
+The scanner does not sample the diagonal or the exact module center. Each triangle now uses a small **three-anchor sampling cluster** positioned safely inside its region. The cluster is robustly aggregated, and the variation between the three anchors is retained as a spatial-stability signal. This is less sensitive to blur, resampling, small homography offsets, and diagonal color bleed than relying on one point per triangle.
 
-Each triangle is classified independently against the calibrated RGBW palette. The cell confidence is the weaker of the two triangle confidences. That confidence feeds the existing confidence-aware Spectrum ECC path, allowing an ambiguous triangle pair to become a useful erasure candidate instead of an arbitrary hard error.
+Each triangle is classified independently against the calibrated RGBW palette. The cell confidence combines the weaker color-classification confidence with the measured within-triangle sample stability. The scanner also retains the most plausible alternate Triangle16 state by changing the less reliable of the two regions first. Those confidence and alternate-state signals feed Spectrum ECC 2.0 for erasure and bounded soft-decision recovery.
 
 The normal image and camera scanner automatically detects High Density Mode and attempts Triangle16 dual-region sampling when needed. No separate scan mode is required. If ordinary finder/alignment geometry is good enough to locate the symbol but not precise enough to decode the half-cell regions, the scanner performs one bounded **precise-alignment recovery** pass. That pass uses denser alignment-pattern probes and a finer sub-module search, then retries the same dual-triangle classifier.
 

package/docs/NODE.md

@@ -68,6 +68,28 @@ const result = await QuadQRNode.scanBuffer(pngBuffer);
 
 PNG generation and decoding do not require external native dependencies.
 
+## Server-side compression
+
+Compression uses the same synchronous JavaScript codec on Node.js as it does in the browser. No DOM API, browser `CompressionStream`, or Node `zlib` call is required by the QuadQR payload codec.
+
+```js
+import { encodeText, decodeMatrix } from "quadqr-js";
+
+const code = encodeText("hello ".repeat(1000), {
+  compression: "auto"
+});
+
+const smallest = encodeText("structured payload ".repeat(500), {
+  compression: "smart"
+});
+
+const decoded = decodeMatrix(code.matrix);
+console.log(decoded.compression); // usually "brotli" for repetitive data
+console.log(decoded.text);
+```
+
+`compression: "auto"` performs one balanced comparison using LZ level 6, DEFLATE level 6, and Brotli quality 6. `compression: "smart"` is the opt-in CPU-heavy mode and escalates to stronger levels only when a smaller QuadQR version is realistically reachable. Explicit `lz` and `deflate` accept `compressionLevel: 1..9` (default 6), while explicit `brotli` accepts `compressionLevel: 0..11` (default 11). `lzLevel`, `deflateLevel`, and `brotliQuality` are available as algorithm-specific aliases.
+
 ## Other image formats
 
 For JPEG, WebP, or AVIF input, the Node adapter can use `sharp` when the consuming application has it installed:

package/docs/README.md

@@ -1,10 +1,10 @@
 # QuadQR Documentation
 
-QuadQR is an experimental RGBW matrix symbology. Default RGBW cells carry two bits using red, green, blue, or white. The experimental High Density Mode splits payload cells into two RGBW triangles and carries four raw bits per body data cell. The JavaScript library supports encoding, canvas/RGBA/SVG rendering, adjustable quiet zones, optional centered logos with transparent or cleared backgrounds, matrix decoding, image and camera scanning, Spectrum ECC, optional authenticated encryption, Node.js PNG/SVG workflows, CDN usage, a CLI, TypeScript declarations, and optional prebuilt WebAssembly acceleration.
+QuadQR is an experimental RGBW matrix symbology. Default RGBW cells carry two bits using red, green, blue, or white. The experimental High Density Mode splits payload cells into two RGBW triangles and carries four raw bits per body data cell. The JavaScript library supports encoding, canvas/RGBA/SVG rendering, adjustable quiet zones, optional centered logos with transparent or cleared backgrounds, matrix decoding, image and camera scanning, Spectrum ECC, optional authenticated encryption, Node.js PNG/SVG workflows, CDN usage, a CLI, and optional prebuilt WebAssembly acceleration.
 
 ## Live links
 
-- [Documentation Site](https://akanshsirohi.github.io/QuadQR/docs-site/)
+- [Documentation Site](https://akanshsirohi.github.io/QuadQR/documentation/)
 - [Interactive Demo](https://akanshsirohi.github.io/QuadQR/demo/)
 - [quadqr-js on npm](https://www.npmjs.com/package/quadqr-js)
 - [GitHub Repository](https://github.com/akanshsirohi/QuadQR)
@@ -13,7 +13,9 @@ QuadQR is an experimental RGBW matrix symbology. Default RGBW cells carry two bi
 
 - [Getting Started](./GETTING_STARTED.md)
 - [API Reference](./API.md)
+- [Compression 3.0](./COMPRESSION.md)
 - [High Density Mode (Experimental)](./HIGH_DENSITY_MODE.md)
+- [Reliability Lab](./RELIABILITY_LAB.md)
 - [Browser and CDN](./BROWSER_CDN.md)
 - [Node.js](./NODE.md)
 - [CLI](./CLI.md)
@@ -46,8 +48,8 @@ QuadQR is licensed under AGPL-3.0. See [`LICENSE`](../LICENSE).
 
 The current library also includes:
 
-- normal text/byte payloads with optional internal LZ compression;
-- portable automatic LZ compression;
+- normal text/byte payloads with optional internal Compression 3.0;
+- bundled synchronous Brotli + portable DEFLATE + level-aware legacy LZ compatibility;
 - first-class binary `Uint8Array` APIs;
 - Ed25519 signed QuadQR payloads and trusted-key verification;
 - signed + AES-256-GCM encrypted composition;
@@ -55,6 +57,6 @@ The current library also includes:
 - ECC-aware automatic logo sizing;
 - normalized scanner confidence and detailed debug mode;
 - deterministic scanability/torture testing;
-- an interactive browser stress-test lab and capacity calculator.
+- a dedicated browser Reliability Lab with 3D perspective sweeps, plus the capacity calculator.
 
 See [`../SPECIFICATION.md`](../SPECIFICATION.md) for the layering and interoperability rules and [`API.md`](./API.md) for the public APIs.

package/docs/RELIABILITY_LAB.md

@@ -0,0 +1,64 @@
+# Reliability Lab
+
+QuadQR includes a deterministic Reliability Lab for regression testing generated symbols against camera-style damage. It is intended for comparing scanner changes, render settings, ECC profiles, output size, and the experimental High Density Mode under repeatable conditions.
+
+The lab verifies the decoded payload CRC. Finding three locators is not counted as success unless the final payload is recovered correctly.
+
+## Browser demo
+
+Open the **Reliability Lab** tab after generating a QuadQR. The lab provides:
+
+- Quick, Full, and Extreme suites;
+- per-scenario pass/fail, confidence, Reed-Solomon correction count, and decode time;
+- category-level scoring for optics, lighting, color, resampling, sensor damage, and perspective;
+- a 3D perspective playground with X pitch, Y yaw, and Z rotation controls;
+- angle sweeps to find the largest tested pitch, yaw, or Z rotation that still decodes.
+
+X pitch and Y yaw simulate a code plane tilting in depth. Z rotation is an in-plane rotation. The controls can be combined.
+
+## Public API
+
+```js
+import {
+  applyStressDistortion,
+  runReliabilityLab,
+  runPerspectiveSweep
+} from "quadqr-js";
+
+const transformed = applyStressDistortion(imageData, "perspective-3d", 0.5, {
+  pitchDegrees: 20,
+  yawDegrees: 45,
+  rollDegrees: 15
+});
+
+const report = runReliabilityLab(imageData, {
+  version: encoded.version,
+  crc32: encoded.crc32
+}, {
+  suite: "full"
+});
+
+const sweep = runPerspectiveSweep(imageData, {
+  version: encoded.version,
+  crc32: encoded.crc32
+}, {
+  axis: "yaw",
+  angles: [0, 15, 25, 35, 45, 55]
+});
+```
+
+## Suites
+
+The Reliability Lab extends the smaller scanability suite with deterministic cases for lens blur, motion blur, low/high exposure, gradient shadow, glare, warm/cool color casts, contrast loss, sensor noise, JPEG-like damage, downscaling, projective skew, 3D pitch/yaw, Z rotation, and combined 3D tilt.
+
+The **Extreme** suite adds stronger perspective cases. These are deliberately demanding and may fail at low pixels-per-module even when the same angle succeeds at a larger rendered size.
+
+## Perspective scanner recovery
+
+The scanner keeps its normal fast path for ordinary frames. When locator scale differences indicate projective foreshortening, the geometry stage can perform a bounded coarse-to-fine search for the primary alignment reference. The fine stage uses denser sub-cell scoring so payload cells are less likely to impersonate the alignment marker. This improves steep-angle recovery without weakening normal structure checks globally.
+
+Distributed secondary alignment references are still used to validate the resulting homography.
+
+## Interpreting results
+
+Synthetic results are regression aids, not a substitute for real phone-camera and print testing. A useful practical metric is the largest reliable angle at the intended physical size and scanning distance, not only the theoretical bits per cell.

package/docs/TRIANGLE16.md

@@ -1,6 +1,6 @@
-# Triangle16 experimental data-cell profile
+# Triangle16 internals for High Density Mode
 
-Triangle16 is an experimental QuadQR data-cell encoding for the high-density branch. It keeps the existing QuadQR geometry, finder patterns, timing pattern, alignment patterns, calibration, Spectrum ECC, CRC, security envelope, compression, and signing behavior, but changes how payload data cells are represented.
+Triangle16 is the experimental physical cell layout used internally by QuadQR **High Density Mode**. It keeps the existing QuadQR geometry, finder patterns, timing pattern, alignment patterns, calibration, Spectrum ECC, CRC, security envelope, compression, and signing behavior, but changes how payload data cells are represented.
 
 ## Physical cell
 
@@ -46,9 +46,7 @@ This uses four cells per protected header byte, exactly like RGBW, but makes it
 
 ## Scanner sampling
 
-The scanner does not sample the diagonal or the exact module center. For each data cell it samples two small regions well inside the triangles, approximately around `(0.28, 0.28)` and `(0.72, 0.72)` in normalized module coordinates.
-
-Each triangle is classified independently against the calibrated RGBW palette. The cell confidence is the weaker of the two triangle confidences. That confidence feeds the existing confidence-aware Spectrum ECC path, allowing an ambiguous triangle pair to become a useful erasure candidate instead of an arbitrary hard error.
+The scanner does not sample the diagonal or the exact module center. Each triangle uses three protected interior sample anchors, robust aggregation, and a spatial-stability score. The weaker/less stable region lowers the cell confidence and supplies the first alternate state for Spectrum ECC 2.0 soft recovery.
 
 The normal image and camera scanner automatically attempts Triangle16 sampling. No separate scan mode is required. If ordinary finder/alignment geometry is good enough to locate the symbol but not precise enough to decode the half-cell regions, the scanner performs one bounded **precise-alignment recovery** pass. That pass uses denser alignment-pattern probes and a finer sub-module search, then retries the same dual-triangle classifier.
 
@@ -61,23 +59,15 @@ PNG/ImageData, Canvas, SVG, browser, and Node rendering all support Triangle16.
 ## API
 
 ```js
-import { encodeText, CELL_ENCODINGS } from "quadqr-js";
+import { encodeText } from "quadqr-js";
 
 const code = encodeText("High-density QuadQR", {
   ecc: "M",
-  cellEncoding: CELL_ENCODINGS.TRIANGLE16
-});
-```
-
-The string form is also accepted:
-
-```js
-const code = encodeText("High-density QuadQR", {
-  cellEncoding: "triangle16"
+  highDensity: true
 });
 ```
 
-`rgbw` remains the library default so existing callers are not silently moved to an experimental physical format.
+High Density Mode is disabled by default. `Triangle16` is an internal/technical name for the current experimental physical layout, not a separate public mode selector.
 
 ## Capacity
 
@@ -90,7 +80,7 @@ Triangle16 16 states  4 bits/body cell
 
 The protected header remains RGBW-equivalent, and ECC/CRC overhead is unchanged at the byte level, so usable payload capacity is close to but not exactly 2x for a fixed matrix version.
 
-Use `getVersionInfo(version, { ecc, cellEncoding: "triangle16" })` or the demo capacity calculator for the exact value.
+Use `getVersionInfo(version, { ecc, highDensity: true })` or the demo capacity calculator for the exact value.
 
 ## Reliability caveat
 

package/docs/WASM.md

@@ -56,7 +56,7 @@ You can also provide WASM bytes directly through the `bytes` option.
 When the classic `quadqr.min.js` global build is loaded from a CDN, `QuadQR.initWasm()` resolves the bundled sibling WASM asset from the same package/version location.
 
 ```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>
   await QuadQR.initWasm();
 </script>