quadqr-js 1.5.3 → 1.5.4

package/README.md

@@ -258,7 +258,7 @@ Compression modes are `none`, `auto`, `smart`, `brotli`, `deflate`, and `lz`. `a
 
 Signing can also be composed with Secure Payload. QuadQR compresses if requested, signs the normal payload with the private key, then encrypts the protected bytes with AES-256-GCM. A verifier supplies the trusted public key separately, or resolves it from `keyId`.
 
-The renderer supports an explicit `mode: "print"`. Print mode enforces a minimum 4-module quiet zone, uses darker print-safe RGB defaults, and prefers Classic solid modules. `getPrintGuidance()` converts a chosen physical size into module millimeters/pixels so print layouts can be checked before production testing.
+The renderer supports an explicit `mode: "print"`. Print mode uses darker print-safe RGB defaults and prefers Classic solid modules, while `quietZone` behaves exactly as it does in screen mode. Four modules remains the recommended default. `getPrintGuidance()` converts a chosen physical size into module millimeters/pixels so print layouts can be checked before production testing.
 
 Centered logos support `size: "auto"`, which estimates a conservative ECC-aware ratio from code utilization and rendering choices. `findMaxSafeLogoSize()` can additionally probe ImageData output and empirically search for the largest size that still decodes.
 
@@ -1281,4 +1281,4 @@ AGPL v3.0. See `LICENSE`.
 
 **Experimental / research project**
 
-QuadQR is actively evolving. Format details may change between versions until the wire format is considered stable.
+QuadQR is actively evolving. Format details may change between versions until the wire format is considered stable.

package/SPECIFICATION.md

@@ -253,9 +253,9 @@ inset
 
 ### Print mode
 
-`mode: "print"` applies conservative defaults:
+`mode: "print"` applies print-oriented defaults:
 
-- minimum quiet zone of 4 modules unless explicitly overridden;
+- caller-controlled quiet-zone sizing, identical to screen mode (4 modules recommended by default);
 - print-safe darker RGB primaries;
 - Classic solid-module rendering by default;
 - physical-size guidance through `getPrintGuidance()`.

package/dist/esm/quadqr.js

@@ -3056,10 +3056,7 @@ function svgLogoHref(source) {
 
 function resolveRenderSizing(options, matrixSize) {
   const mode = normalizeRenderMode(options.mode ?? options.renderMode ?? RENDER_MODES.SCREEN);
-  const requestedQuietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
-  const quietZone = mode === RENDER_MODES.PRINT && options.allowUnsafePrintQuietZone !== true
-    ? Math.max(4, requestedQuietZone)
-    : requestedQuietZone;
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
   const totalModules = matrixSize + quietZone * 2;
   const hasImageSize = options.imageSize !== undefined && options.imageSize !== null;
   const hasModuleSize = options.moduleSize !== undefined && options.moduleSize !== null;

package/dist/quadqr.js

@@ -9241,10 +9241,7 @@ function svgLogoHref(source) {
 
 function resolveRenderSizing(options, matrixSize) {
   const mode = normalizeRenderMode(options.mode ?? options.renderMode ?? RENDER_MODES.SCREEN);
-  const requestedQuietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
-  const quietZone = mode === RENDER_MODES.PRINT && options.allowUnsafePrintQuietZone !== true
-    ? Math.max(4, requestedQuietZone)
-    : requestedQuietZone;
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
   const totalModules = matrixSize + quietZone * 2;
   const hasImageSize = options.imageSize !== undefined && options.imageSize !== null;
   const hasModuleSize = options.moduleSize !== undefined && options.moduleSize !== null;

package/dist/quadqr.min.js

@@ -9071,10 +9071,7 @@ function svgLogoHref(source) {
 
 function resolveRenderSizing(options, matrixSize) {
   const mode = normalizeRenderMode(options.mode ?? options.renderMode ?? RENDER_MODES.SCREEN);
-  const requestedQuietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
-  const quietZone = mode === RENDER_MODES.PRINT && options.allowUnsafePrintQuietZone !== true
-    ? Math.max(4, requestedQuietZone)
-    : requestedQuietZone;
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
   const totalModules = matrixSize + quietZone * 2;
   const hasImageSize = options.imageSize !== undefined && options.imageSize !== null;
   const hasModuleSize = options.moduleSize !== undefined && options.moduleSize !== null;

package/docs/API.md

@@ -531,7 +531,7 @@ All render APIs accept:
 { mode: "screen" | "print" }
 ```
 
-Print mode uses a darker print-safe palette, forces Classic modules by default, and enforces a minimum 4-module quiet zone unless `allowUnsafePrintQuietZone: true` is explicitly set.
+Print mode uses a darker print-safe palette and forces Classic modules by default. `quietZone` has the same behavior in print and screen modes, including support for values below the recommended four-module default.
 
 ### `getPrintGuidance(codeOrMatrix, options?)`
 

package/docs/CLI.md

@@ -1,167 +1,167 @@
-# Command Line Interface
-
-The npm package includes the `quadqr` executable and can be used directly through `npx`.
-
-## Encode text
-
-```bash
-npx quadqr-js encode "Hello QuadQR" -o hello.png
-npx quadqr-js encode "Hello QuadQR" -o hello.svg
-```
-
-Optional encoding controls:
-
-```bash
-npx quadqr-js encode "Hello" --ecc M --version auto --image-size 720 --quiet-zone 4 -o hello.png
-```
-
-Use the print-safe rendering profile when the symbol is intended for physical output:
-
-```bash
-npx quadqr-js encode "Print me" --print -o print.svg
-```
-
-Print mode enforces a minimum four-module quiet zone and uses the print-safe rendering defaults.
-
-## Compression
-
-Compression works directly with normal text payloads:
-
-```bash
-npx quadqr-js encode "repeat repeat repeat repeat" \
-  --compression auto \
-  -o compressed.png
-```
-
-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
-
-Generate an Ed25519 signing-key bundle:
-
-```bash
-npx quadqr-js signkeygen -o quadqr-signing-key.json
-```
-
-Keep this file secret because it contains the private signing key. Encode a signed payload with:
-
-```bash
-npx quadqr-js encode "Offline-verifiable ticket" \
-  --sign-key quadqr-signing-key.json \
-  -o signed.png
-```
-
-The generated key bundle contains both keys plus a compact `keyId`. Only the private key signs. The public key is **not embedded** in the QuadQR by default and should be distributed separately to trusted scanners or stored in a trusted-key registry.
-
-To override the identifier stored in the symbol:
-
-```bash
-npx quadqr-js encode "Offline-verifiable ticket" \
-  --sign-key quadqr-signing-key.json \
-  --key-id event-main-2026 \
-  -o signed.png
-```
-
-Signing can be combined with password or raw-key encryption:
-
-```bash
-npx quadqr-js encode "Signed and private" \
-  --sign-key quadqr-signing-key.json \
-  --password "my-password" \
-  -o signed-secure.png
-```
-
-## Decode an image
-
-```bash
-npx quadqr-js decode hello.png
-npx quadqr-js decode signed.png --verify-key quadqr-signing-key.json
-```
-
-For an unencrypted text payload, the decoded text is printed to stdout. To verify a signed symbol against a trusted public key, pass the signing bundle with `--verify-key`.
-
-Add scanner diagnostics without changing the normal stdout payload:
-
-```bash
-npx quadqr-js decode hello.png --debug
-```
-
-Diagnostics are written to stderr and include confidence, geometry/color confidence, ECC utilization, signing state, and the scanner diagnostics object when available.
-
-## Password-protected payloads
-
-Encode:
-
-```bash
-npx quadqr-js encode "Private data" --password "my-password" -o secure.png
-```
-
-Decode:
-
-```bash
-npx quadqr-js decode secure.png --password "my-password"
-```
-
-If an encrypted symbol is decoded without a credential, the CLI reports that decryption is required instead of exposing plaintext.
-
-## Raw 256-bit key mode
-
-Generate a random 256-bit encryption key:
-
-```bash
-npx quadqr-js keygen
-```
-
-The output is a 64-character hexadecimal key. Store it securely and do not place it inside the same QuadQR symbol.
-
-Encode using the key:
-
-```bash
-npx quadqr-js encode "Application secret" --key <64-hex-key> -o secure-key.png
-```
-
-Decode using the key:
-
-```bash
-npx quadqr-js decode secure-key.png --key <64-hex-key>
-```
-
-## Options
-
-| Option | Purpose |
-| --- | --- |
-| `-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`, `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 |
-| `--verify-key <file>` | Verify a signed symbol with a trusted Ed25519 key bundle |
-| `--password <text>` | Password-mode encryption/decryption |
-| `--key <hex>` | Raw 256-bit key encryption/decryption |
-| `--print` | Use the print-safe render profile |
-| `--image-size <px>` | Exact square output size in pixels. Default: `720` |
-| `--module-size <px>` | Legacy pixels-per-module sizing. Used when `--image-size` is omitted |
-| `--quiet-zone <modules>` | Quiet-zone size in modules. Default: `4` |
-| `--debug` | Emit scanner diagnostics to stderr when decoding |
-| `-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.
+# Command Line Interface
+
+The npm package includes the `quadqr` executable and can be used directly through `npx`.
+
+## Encode text
+
+```bash
+npx quadqr-js encode "Hello QuadQR" -o hello.png
+npx quadqr-js encode "Hello QuadQR" -o hello.svg
+```
+
+Optional encoding controls:
+
+```bash
+npx quadqr-js encode "Hello" --ecc M --version auto --image-size 720 --quiet-zone 4 -o hello.png
+```
+
+Use the print-safe rendering profile when the symbol is intended for physical output:
+
+```bash
+npx quadqr-js encode "Print me" --print -o print.svg
+```
+
+Print mode uses the print-safe palette and Classic rendering defaults. `--quiet-zone` is honored unchanged, just as it is in screen mode; four modules remains recommended.
+
+## Compression
+
+Compression works directly with normal text payloads:
+
+```bash
+npx quadqr-js encode "repeat repeat repeat repeat" \
+  --compression auto \
+  -o compressed.png
+```
+
+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
+
+Generate an Ed25519 signing-key bundle:
+
+```bash
+npx quadqr-js signkeygen -o quadqr-signing-key.json
+```
+
+Keep this file secret because it contains the private signing key. Encode a signed payload with:
+
+```bash
+npx quadqr-js encode "Offline-verifiable ticket" \
+  --sign-key quadqr-signing-key.json \
+  -o signed.png
+```
+
+The generated key bundle contains both keys plus a compact `keyId`. Only the private key signs. The public key is **not embedded** in the QuadQR by default and should be distributed separately to trusted scanners or stored in a trusted-key registry.
+
+To override the identifier stored in the symbol:
+
+```bash
+npx quadqr-js encode "Offline-verifiable ticket" \
+  --sign-key quadqr-signing-key.json \
+  --key-id event-main-2026 \
+  -o signed.png
+```
+
+Signing can be combined with password or raw-key encryption:
+
+```bash
+npx quadqr-js encode "Signed and private" \
+  --sign-key quadqr-signing-key.json \
+  --password "my-password" \
+  -o signed-secure.png
+```
+
+## Decode an image
+
+```bash
+npx quadqr-js decode hello.png
+npx quadqr-js decode signed.png --verify-key quadqr-signing-key.json
+```
+
+For an unencrypted text payload, the decoded text is printed to stdout. To verify a signed symbol against a trusted public key, pass the signing bundle with `--verify-key`.
+
+Add scanner diagnostics without changing the normal stdout payload:
+
+```bash
+npx quadqr-js decode hello.png --debug
+```
+
+Diagnostics are written to stderr and include confidence, geometry/color confidence, ECC utilization, signing state, and the scanner diagnostics object when available.
+
+## Password-protected payloads
+
+Encode:
+
+```bash
+npx quadqr-js encode "Private data" --password "my-password" -o secure.png
+```
+
+Decode:
+
+```bash
+npx quadqr-js decode secure.png --password "my-password"
+```
+
+If an encrypted symbol is decoded without a credential, the CLI reports that decryption is required instead of exposing plaintext.
+
+## Raw 256-bit key mode
+
+Generate a random 256-bit encryption key:
+
+```bash
+npx quadqr-js keygen
+```
+
+The output is a 64-character hexadecimal key. Store it securely and do not place it inside the same QuadQR symbol.
+
+Encode using the key:
+
+```bash
+npx quadqr-js encode "Application secret" --key <64-hex-key> -o secure-key.png
+```
+
+Decode using the key:
+
+```bash
+npx quadqr-js decode secure-key.png --key <64-hex-key>
+```
+
+## Options
+
+| Option | Purpose |
+| --- | --- |
+| `-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`, `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 |
+| `--verify-key <file>` | Verify a signed symbol with a trusted Ed25519 key bundle |
+| `--password <text>` | Password-mode encryption/decryption |
+| `--key <hex>` | Raw 256-bit key encryption/decryption |
+| `--print` | Use the print-safe render profile |
+| `--image-size <px>` | Exact square output size in pixels. Default: `720` |
+| `--module-size <px>` | Legacy pixels-per-module sizing. Used when `--image-size` is omitted |
+| `--quiet-zone <modules>` | Quiet-zone size in modules. Default: `4` |
+| `--debug` | Emit scanner diagnostics to stderr when decoding |
+| `-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quadqr-js",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "QuadQR: experimental RGBW matrix code with optional experimental High Density Mode, Spectrum ECC 2.0, multi-frame camera scanning, advanced calibration, Reliability Lab, and 3D perspective recovery.",
   "type": "module",
   "main": "./dist/index.cjs",