quadqr-js 1.4.2 → 1.5.2

package/docs/COMPRESSION.md

@@ -1,170 +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.
+# 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.4.1/dist/quadqr.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.5.1/dist/quadqr.min.js"></script>
 <script>
   const code = QuadQR.encodeText("No build step");
   QuadQR.renderToCanvas(code, document.querySelector("#qr"));

package/docs/HIGH_DENSITY_MODE.md

@@ -1,100 +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.
+# 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.