quadqr-js 1.2.0 → 1.4.2

package/docs/API.md

@@ -11,12 +11,15 @@ import { encodeText } from "quadqr-js";
 
 const code = encodeText("Hello", {
   ecc: "M",
-  version: 5
+  version: 5,
+  highDensity: true // optional experimental 4-bit cells
 });
 ```
 
 If `version` is omitted, QuadQR selects the smallest version that fits.
 
+`highDensity` is a boolean. It defaults to `false`. Set `highDensity: true` to enable the experimental Triangle16 layout with two RGBW triangles, 16 states, and 4 raw bits per body cell. The protected header remains solid-color in High Density Mode. Image and camera scanners auto-detect it.
+
 ### `encodeBytes(bytes, options?)`
 
 Encodes arbitrary bytes.
@@ -176,7 +179,7 @@ const svg = renderToSVG(code, {
 
 ### `scanImageData(imageData, options?)`
 
-Scans an ImageData-like RGBA object. 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.
+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({
@@ -186,7 +189,7 @@ const result = scanImageData({
 });
 ```
 
-Useful scanner options include `sampleRadius`, `robustSampleRadius`, `adaptiveSampling`, `spatialColorNormalization`, `autoEnhanceRecovery`, `rectifiedAutoEnhanceRecovery`, `rectifiedRecoveryModuleSize`, `autoEnhanceBlackClip`, `autoEnhanceWhiteClip`, `autoEnhanceSaturation`, `geometryRefinement`, `refinementOffset`, `structureTolerance`, and `maxErasureConfidence`. Auto enhancement and geometry refinement are enabled by default, but only run after the normal scan path fails.
+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?)`
 
@@ -206,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 that fast pass fails, the **same captured frame** is retried through code-centric Auto Color recovery before finder detection. 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,
@@ -220,6 +225,9 @@ const scanner = await startCameraScanner(video, {
   cameraAutoColorAnalysisInset: 0.10,
   cameraAutoEnhanceEvery: 2,
   cameraFinderRecoveryEvery: 2,
+  cameraHighResolutionRecovery: true,
+  cameraHighResolutionMaxDimension: 1600,
+  cameraHighResolutionEvery: 2,
   onResult(result) {
     console.log(result);
   },
@@ -404,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.
 
-Portable synchronous LZSS-style compression helpers. They do not require Node zlib or browser `CompressionStream`.
+### `compressDeflatePayload(input, options?)` / `decompressDeflatePayload(input, expectedLength?)`
+
+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
 
@@ -530,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?)`
 
@@ -542,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,9 @@ 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 |
 | `--embed-public-key` | Explicit compatibility mode that embeds the public key |
@@ -148,3 +160,8 @@ npx quadqr-js decode secure-key.png --key <64-hex-key>
 | `-h, --help` | Show CLI help |
 
 Password mode and raw-key mode are mutually exclusive for a single operation.
+
+
+## High Density Mode (Experimental)
+
+Use `--high-density` to enable the experimental Triangle16 layout with 16 states and 4 raw bits per body cell. Decode is automatic; no matching decode flag is required.

package/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

@@ -0,0 +1,100 @@
+# High Density Mode (Experimental)
+
+High Density Mode is an experimental QuadQR option implemented with the Triangle16 cell layout. 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
+
+A Triangle16 payload cell is split by one fixed `/` diagonal:
+
+```text
++---------+
+| AAAAAA /|
+| AAAAA /B|
+| AAAA /BB|
+| AAA /BBB|
+| AA /BBBB|
+| A /BBBBB|
+| /BBBBBBB|
++---------+
+```
+
+`A` is the upper-left triangle and `B` is the lower-right triangle. Each triangle independently uses the existing RGBW alphabet:
+
+```text
+R = 00
+G = 01
+B = 10
+W = 11
+```
+
+The pair therefore has 16 states:
+
+```text
+R/R  R/G  R/B  R/W
+G/R  G/G  G/B  G/W
+B/R  B/G  B/B  B/W
+W/R  W/G  W/B  W/W
+```
+
+The first triangle carries the high 2 bits and the second triangle carries the low 2 bits. One Triangle16 body cell therefore carries 4 raw bits, so one byte occupies two body cells instead of four RGBW cells.
+
+## Protected header stays solid
+
+The protected bootstrap/header intentionally does not use mixed-color triangles. Its normal RGBW header cells are represented as same-color pairs such as `R/R`, `G/G`, `B/B`, and `W/W`.
+
+This uses four cells per protected header byte, exactly like RGBW, but makes it much easier for the decoder to recover the mode flag when the image is blurred, skewed, resized, or color-shifted. Header flag bit 6 declares Triangle16 for the ECC-protected body.
+
+## Scanner sampling
+
+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 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.
+
+## Rendering rules
+
+High Density Mode uses exact hard-edged Triangle16 payload cells. Decorative payload styles are intentionally bypassed in this experimental mode because rounded, inset, soft, or depth effects can reduce the usable sampling area or contaminate the diagonal boundary. Structural modules keep the normal QuadQR rendering behavior.
+
+PNG/ImageData, Canvas, SVG, browser, and Node rendering all support Triangle16.
+
+## API
+
+```js
+import { encodeText } from "quadqr-js";
+
+const code = encodeText("High-density QuadQR", {
+  ecc: "M",
+  highDensity: true
+});
+```
+
+High Density Mode is disabled by default. Existing callers remain on normal RGBW mode unless `highDensity: true` is explicitly supplied.
+
+## Capacity
+
+Raw body density is:
+
+```text
+RGBW       4 states   2 bits/body cell
+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, highDensity: true })` or the demo capacity calculator for the exact value.
+
+## Reliability caveat
+
+Triangle16 doubles raw body bits per cell, but it also halves the spatial area available to each independently classified color. Its meaningful real-world metric is not only bits per matrix cell. It is reliable payload bytes at a fixed physical size, camera distance, angle, lighting condition, resize/compression pipeline, and print quality.
+
+The branch should therefore be stress-tested before treating High Density Mode as stable. Important cases include:
+
+- perspective and partial finder degradation;
+- defocus and motion blur;
+- low camera pixel coverage per module;
+- JPEG compression and repeated image resizing;
+- shadows, glare, white-balance shifts, and saturation changes;
+- cheap printing, ink spread, paper tint, and camera recapture.
+
+If full 16-state reliability becomes the limiting factor, a restricted triangle alphabet can be explored later without changing the basic physical-cell experiment.

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 four-state RGBW matrix symbology. Each data cell carries exactly two bits using red, green, blue, or white. 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,6 +13,9 @@ QuadQR is an experimental four-state RGBW matrix symbology. Each data cell carri
 
 - [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)
@@ -45,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;
@@ -54,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.