quadqr-js 1.0.2 → 1.2.0

package/FORMAT.md

@@ -388,3 +388,14 @@ Format v5 is intentionally incompatible with standard QR scanners and with the p
 ## Rendering profiles are not part of the wire format
 
 The canonical QuadQR matrix is independent of presentation style. Renderers may offer styles such as `classic`, `depth`, `soft`, or `inset`, provided structural finder/timing/alignment/calibration references remain sufficiently faithful for decoding. Style selection is not encoded in the payload/header and does not change matrix cell values.
+
+## Compression and signature flags
+
+Format v5 keeps the physical matrix and ECC framing unchanged while reserving two protected-header flags for optional internal payload metadata:
+
+```text
+bit 4 = internal payload-extension metadata present
+bit 5 = signed-payload hint
+```
+
+These bits are not a public payload-type mode. Applications continue to encode normal UTF-8 text or arbitrary bytes. Compression and Ed25519 signing use a compact internal extension envelope only when metadata is required. The envelope, print profile, diagnostics, and scanability test model are specified in [`SPECIFICATION.md`](./SPECIFICATION.md). None of these features changes RGBW cell mapping or Spectrum ECC.

package/README.md

@@ -21,7 +21,9 @@
   ·
   <a href="docs/README.md">Markdown Docs</a>
   ·
-  <a href="FORMAT.md">Format Specification</a>
+  <a href="FORMAT.md">Matrix Format</a>
+  ·
+  <a href="SPECIFICATION.md">Technical Specification</a>
 </p>
 
 **QuadQR** is an experimental open-source 2D matrix code that uses four visible data states instead of the two states used by a traditional black-and-white QR module.
@@ -179,6 +181,56 @@ The scanner never expects the secret to be embedded in the QuadQR itself. Raw-ke
 
 ---
 
+## Compression, signatures, and robustness tooling
+
+QuadQR keeps the application payload simple: **text stays text and bytes stay bytes**. There is no public payload-type registry to maintain. Compression and signing metadata are added only as internal implementation details when those features are enabled.
+
+```js
+import {
+  encodeText,
+  encodeSignedText,
+  generateSigningKeyPair,
+  decodeMatrix,
+  verifyDecodedSignature
+} from "quadqr-js";
+
+// Auto compression is zero-overhead when it does not help.
+const compressed = encodeText("repeated repeated repeated", {
+  compression: "auto",
+  ecc: "M"
+});
+
+const keys = await generateSigningKeyPair();
+const signed = await encodeSignedText("verified offline", {
+  compression: "auto",
+  privateKey: keys.privateKey,
+  keyId: keys.keyId
+});
+
+const decoded = decodeMatrix(signed.matrix);
+const verified = await verifyDecodedSignature(decoded, {
+  publicKey: keys.publicKey
+});
+console.log(verified.signatureVerified); // true
+console.log(verified.signatureTrusted);  // true
+```
+
+Compression modes are `none`, `auto`, and `lz`. `auto` keeps the original payload untouched when compression would not save space. Ed25519 signing stores the signature plus an optional compact `keyId`; the public verification key stays outside the QuadQR by default. Applications do not need to choose or maintain content types.
+
+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.
+
+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.
+
+Scanner results include normalized diagnostics such as `confidence`, `geometryConfidence`, `calibrationConfidence`, `structureConfidence`, `eccUtilization`, and `correctedErrors`. Set `debug: true` or call `debugScanImageData()` to inspect finder/geometry candidates, the sampled matrix, color-confidence data, ECC stages, and the stage that failed.
+
+For regression and demo testing, `runImageStressTest()` / `assessScanability()` apply deterministic blur, brightness, exposure, shadow, contrast, perspective, JPEG-like artifacts, and downscaling. The browser demo exposes the same tools as an interactive stress-test lab and shows an overall scanability rating.
+
+The interoperability details are documented in [`SPECIFICATION.md`](./SPECIFICATION.md).
+
+---
+
 ## Current benchmark
 
 Run:
@@ -508,7 +560,7 @@ The `inset` style preserves the exact encoded R/G/B/W color around the center of
 
 ```js
 renderToCanvas(code, canvas, {
-  moduleSize: 12,
+  imageSize: 720,
   quietZone: 4,
   style: "inset" // classic | depth | soft | inset
 });
@@ -516,13 +568,58 @@ renderToCanvas(code, canvas, {
 
 The styling is deterministic. Generating the same matrix with the same style produces the same visual tile treatment rather than changing randomly on every render.
 
+`imageSize` sets the exact square output size in pixels. When neither `imageSize` nor `moduleSize` is supplied, QuadQR renders at **720 × 720 px** by default. `moduleSize` remains available as the lower-level legacy sizing control; when `imageSize` is supplied, the exact image size takes precedence.
+
+### Logo overlays, quiet zones, and SVG export
+
+The renderer can place a centered logo over the symbol. Transparent pixels in the logo stay transparent, so the QuadQR modules remain visible through those areas. Enable `clearBackground` when you want a clean padded white area behind the logo instead.
+
+```js
+const logoImage = new Image();
+logoImage.src = "/brand-mark.png";
+await logoImage.decode();
+
+renderToCanvas(code, canvas, {
+  imageSize: 720,
+  quietZone: 6,
+  style: "classic",
+  logo: {
+    source: logoImage,
+    size: 0.12,
+    clearBackground: true,
+    padding: 0.65,
+    radius: 0.8
+  }
+});
+```
+
+`quietZone` is measured in modules and can be set to `0` or increased for print/camera use. Four modules remains the recommended default.
+
+SVG uses the same matrix, palette, styles, quiet-zone size, and logo geometry:
+
+```js
+import { renderToSVG } from "quadqr-js";
+
+const svg = renderToSVG(code, {
+  imageSize: 720,
+  quietZone: 4,
+  logo: {
+    source: "data:image/png;base64,...",
+    size: 0.12,
+    clearBackground: true
+  }
+});
+```
+
+Logo overlays intentionally consume some ECC margin because they cover encoded cells. Keep logos conservative, especially with `L`/`M` ECC. The browser demo verifies the final rendered image before enabling downloads.
+
 ---
 
 ## Demo
 
 **Live demo:** https://akanshsirohi.github.io/QuadQR/demo/
 
-The browser demo runs directly on GitHub Pages and is split into separate views so the interface does not become overloaded.
+The browser demo runs directly on GitHub Pages and is split into separate views so the interface does not become overloaded. The generator keeps only payload, version, and ECC visible by default; optional capabilities are grouped into independent advanced accordions.
 
 ### Generator & Image Scanner
 
@@ -531,9 +628,13 @@ Use this tab to:
 - enter text/data;
 - generate a QuadQR code;
 - select ECC;
+- open Output & Rendering controls for image size, quiet zone, style, and print mode;
+- open the Center Logo accordion for branding;
+- enable internal automatic compression without choosing a payload type;
+- optionally add an Ed25519 signature;
 - optionally encrypt using a password or raw 256-bit key;
 - inspect version and capacity;
-- download the generated image;
+- download PNG or SVG output;
 - scan an uploaded image.
 
 ### Camera Scanner
@@ -552,7 +653,43 @@ The benchmark tab provides an easier visual view of:
 - comparison with standard QR;
 - byte gain;
 - capacity ratio;
-- codec timing.
+- codec timing;
+- capacity planning;
+- interactive stress testing.
+
+Benchmark tools are also separated into accordions so the page stays compact until a tool is needed.
+
+---
+
+## New API highlights
+
+```js
+import {
+  encodeText,
+  encodeUint8Array,
+  decodeUint8Array,
+  renderToImageData,
+  assessScanability,
+  getPrintGuidance
+} from "quadqr-js";
+
+const binary = encodeUint8Array(new Uint8Array([1, 2, 3, 4]), { ecc: "M" });
+const bytes = decodeUint8Array(binary.matrix);
+
+const code = encodeText("Hello hello hello hello", {
+  compression: "auto",
+  ecc: "Q"
+});
+
+const printImage = renderToImageData(code, {
+  imageSize: 1200,
+  mode: "print",
+  logo: { source: logoImageData, size: "auto", clearBackground: true }
+});
+
+console.log(getPrintGuidance(code, { physicalSizeMm: 45, dpi: 300 }));
+console.log(assessScanability(code, { imageSize: 480 }));
+```
 
 ---
 
@@ -583,14 +720,15 @@ const result = decodeMatrix(code.matrix);
 console.log(result.text);
 ```
 
-Node PNG usage:
+Node PNG/SVG usage:
 
 ```js
 import { encodeText } from "quadqr-js";
-import { savePNG, scanFile } from "quadqr-js/node";
+import { savePNG, saveSVG, scanFile } from "quadqr-js/node";
 
 const code = encodeText("Generated on Node.js");
-await savePNG(code, "quadqr.png", { moduleSize: 12, quietZone: 4 });
+await savePNG(code, "quadqr.png", { imageSize: 720, quietZone: 4 });
+await saveSVG(code, "quadqr.svg", { imageSize: 720, quietZone: 4 });
 
 const result = await scanFile("quadqr.png");
 console.log(result.text);
@@ -601,7 +739,7 @@ console.log(result.text);
 The `quadqr-js` package can be loaded directly from npm-backed CDNs:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.0.1/dist/quadqr.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.1.0/dist/quadqr.min.js"></script>
 <script>
   const code = QuadQR.encodeText("Hello from a script tag");
 </script>
@@ -618,6 +756,16 @@ npx quadqr-js encode "Hello QuadQR" -o hello.png
 npx quadqr-js decode hello.png
 ```
 
+Compressed, print-safe, and signed output are also available:
+
+```bash
+npx quadqr-js encode "repeat repeat repeat" --compression auto -o compressed.svg
+npx quadqr-js encode "Print me" --print -o print.svg
+npx quadqr-js signkeygen -o signing-key.json
+npx quadqr-js encode "Verified ticket" --sign-key signing-key.json -o signed.png
+npx quadqr-js decode signed.png --verify-key signing-key.json
+```
+
 Password-protected payloads use the same commands:
 
 ```bash
@@ -625,7 +773,7 @@ npx quadqr-js encode "Private data" --password "my-password" -o secure.png
 npx quadqr-js decode secure.png --password "my-password"
 ```
 
-See [`docs/CLI.md`](docs/CLI.md) for all CLI options, including raw 256-bit key mode.
+See [`docs/CLI.md`](docs/CLI.md) for all CLI options, including compression, raw 256-bit key mode, signing, print mode, and scanner diagnostics.
 
 ### Run from source
 
@@ -862,7 +1010,7 @@ The result reports fields such as `spectralInterleaving`, `confidenceAssisted`,
 
 ### `renderToCanvas(codeOrMatrix, canvas, options?)`
 
-Renders a QuadQR symbol into a browser canvas. `options.style` supports `classic`, `depth`, `soft`, and `inset`.
+Renders a QuadQR symbol into a browser canvas. `imageSize` sets the exact square pixel output and defaults to 720 when neither sizing option is supplied. `moduleSize` remains available for legacy pixels-per-module sizing. `options.style` supports `classic`, `depth`, `soft`, and `inset`. `quietZone` controls the border in modules. `logo` accepts a loaded image/canvas source or `{ source, size, clearBackground, padding, radius, backgroundColor }`.
 
 ### `renderToImageData(codeOrMatrix, options?)`
 
@@ -878,6 +1026,12 @@ Returns an ImageData-like object and supports the same rendering styles as `rend
 
 This is also useful for tests and non-DOM workflows.
 
+When a logo is used with `renderToImageData()`, its source must be an ImageData-like `{ width, height, data }` object so the renderer can composite it without DOM APIs.
+
+### `renderToSVG(codeOrMatrix, options?)`
+
+Returns a standalone SVG string using the same exact `imageSize`, render styles, and quiet-zone controls. SVG logo sources can be a URL/data URL string or an object with a `src` string. The SVG remains vector-sharp regardless of how large the preview is displayed.
+
 ### `scanImageData(imageData, options?)`
 
 Runs the complete perspective-aware and color-aware image scanner. The scanner first tries the normal detected geometry with the observed RGB palette, preserving the fast path for clean images. Only after that fails does it progressively fall back to per-channel white balancing, spatial black/white normalization, tighter centre sampling, a cheap module-grid Auto Tone / Auto Contrast / Auto Color-style recovery, a rectified QR-region pixel enhancement pass, and finally bounded sub-module geometry micro-refinement. If locator detection itself is weakened by a flat/yellow frame, a full-image enhancement retry is also available. RGBW confidence values are carried into Reed-Solomon so ambiguous cells can be treated as erasures when ordinary hard-decision ECC is insufficient.

package/SPECIFICATION.md

@@ -0,0 +1,332 @@
+# QuadQR Technical Specification
+
+## Status
+
+QuadQR is an experimental four-state RGBW matrix symbology. It is not ISO/IEC QR Code and is not intended to be decoded by standard QR readers.
+
+The physical matrix format remains **QuadQR Format v5**. Normal application data is always treated simply as UTF-8 text or arbitrary bytes. Compression, signatures, encryption, rendering, and diagnostics are optional features layered around that stable matrix codec.
+
+For exact matrix geometry and Reed-Solomon framing, see [`FORMAT.md`](./FORMAT.md).
+
+## 1. Layer model
+
+```text
+Application bytes / UTF-8 text
+        │
+        ├─ optional compression metadata (internal)
+        ├─ optional Ed25519 signature metadata (internal)
+        ├─ optional Secure Payload v1 (AES-256-GCM)
+        │
+        └─ QuadQR Format v5
+             ├─ protected header
+             ├─ CRC-32
+             ├─ GF(256) Reed-Solomon Spectrum ECC
+             ├─ spectral-spatial interleaving
+             └─ RGBW matrix
+```
+
+There is deliberately **no public payload-type registry**. Applications do not select URL, JSON, contact, Wi-Fi, or other semantic types. They encode text or bytes and interpret that data themselves.
+
+## 2. Physical cell alphabet
+
+Data modules use exactly four states:
+
+| State | Bits | Internal value |
+|---|---|---:|
+| Red | `00` | 0 |
+| Green | `01` | 1 |
+| Blue | `10` | 2 |
+| White | `11` | 3 |
+
+Structural black is separate from the data alphabet. One encoded byte maps to exactly four RGBW data cells.
+
+## 3. Matrix sizing
+
+```text
+size = 21 + 4 × (version - 1)
+version = 1..40
+```
+
+Three 7×7 finder patterns are always present. Version 1 has the legacy QuadQR 5×5 bottom-right alignment marker. Versions 2–40 use the distributed alignment schedule defined in `FORMAT.md`.
+
+## 4. Format v5 header flags
+
+The protected Format v5 header uses:
+
+```text
+bit 0      UTF-8 text flag
+bits 1..2  ECC profile id
+bit 3      Secure Payload v1 envelope
+bit 4      internal payload-extension metadata present
+bit 5      signed-payload hint
+bits 6..7  reserved
+```
+
+Bit 4 is an implementation/interoperability hint used only when compression or signing requires metadata. It is not a user-selectable payload mode.
+
+## 5. Spectrum ECC
+
+The field remains:
+
+```text
+GF(2^8) = GF(256)
+primitive polynomial = 0x11d
+```
+
+Version 2+ parity profiles:
+
+| Profile | Parity bytes/block | Correctable unknown byte errors/block |
+|---|---:|---:|
+| L | 12 | 6 |
+| M | 24 | 12 |
+| Q | 36 | 18 |
+| H | 48 | 24 |
+
+The decoder retains per-cell color confidence. Low-confidence bytes can be promoted to known erasures, allowing Reed-Solomon recovery to use the existing parity budget more efficiently.
+
+## 6. Internal payload extension envelope
+
+Compression and signing require a small amount of metadata. QuadQR stores that metadata in an **internal extension envelope** only when needed. Applications should normally use `encodeText()`, `encodeBytes()`, `encodeSignedText()`, or `encodeSignedBytes()` and never construct this envelope themselves.
+
+Current envelope magic:
+
+```text
+QPX1
+```
+
+Fixed header size: **16 bytes**.
+
+| Offset | Size | Field |
+|---:|---:|---|
+| 0 | 4 | ASCII magic `QPX1` |
+| 4 | 1 | Extension version (`2`; decoder also accepts legacy `1`) |
+| 5 | 1 | Flags |
+| 6 | 1 | Compression ID |
+| 7 | 1 | Signature algorithm ID |
+| 8 | 4 | Original application payload length, big-endian |
+| 12 | 1 | Signing key-ID length (v2); legacy signer-label length in v1 |
+| 13 | 1 | Optional embedded public-key length |
+| 14 | 1 | Signature length |
+| 15 | 1 | Reserved (`0`) |
+
+Variable bytes follow as:
+
+```text
+keyId || optionalPublicKey || signature || storedPayload
+```
+
+Envelope flags currently use:
+
+```text
+bit 0  signed
+bit 1  compressed
+bit 2  public key embedded
+```
+
+The envelope contains no semantic content type. The Format v5 text flag still determines whether the recovered application payload should be decoded as UTF-8 text.
+
+## 7. Compression
+
+Compression IDs:
+
+```text
+0 = none
+1 = QuadQR portable LZ
+```
+
+The portable LZ stream is an LZSS-style format with groups of up to eight tokens. Each group begins with one flag byte. A flag bit of `0` means a one-byte literal. A flag bit of `1` means a two-byte back-reference:
+
+```text
+12-bit offset: 1..4095 bytes
+4-bit length: stored value + 3, therefore 3..18 bytes
+```
+
+Public compression modes are:
+
+```text
+none
+auto
+lz
+```
+
+`compression: "auto"` uses compression only when it meaningfully reduces payload size. When it does not help and the payload is not signed, QuadQR stores the original payload directly with **no extension-envelope overhead**.
+
+Compression occurs before signing, encryption, and Format v5 ECC.
+
+## 8. Signed QuadQR
+
+Signature algorithm ID `1` is **Ed25519**.
+
+Signed payloads in extension v2 store:
+
+```text
+optional compact key ID
+64-byte Ed25519 signature
+optional 32-byte raw Ed25519 public key only when explicitly requested
+```
+
+The normal production profile does **not** embed the public key. The signature covers:
+
+```text
+16-byte extension header
+|| key ID
+|| optional embedded public key
+|| stored payload bytes
+```
+
+The signature field itself is excluded from the signed message.
+
+The private Ed25519 key is used only by the issuer to create signatures and must never be embedded in a QuadQR. Verification uses a trusted public key supplied externally by the application, server, certificate, or trusted-key registry. The optional key ID is only an identifier that helps the verifier select the correct trusted public key.
+
+For compatibility or self-contained integrity checks, implementations may set `embedPublicKey: true`. A signature verified only against a key embedded in the same QuadQR proves integrity and key possession, but does not establish a trusted signer identity. Such verification should be reported separately from verification against an external trust anchor.
+
+Legacy extension v1 symbols used a signer label and embedded public key. Decoders may continue to read and verify those symbols for backward compatibility.
+
+## 9. Secure + signed composition
+
+When compression, signing, and encryption are combined, QuadQR uses:
+
+```text
+application payload
+→ optional compression
+→ optional Ed25519 signature metadata
+→ AES-256-GCM Secure Payload v1
+→ Format v5 ECC/matrix
+```
+
+After scanning:
+
+```text
+Format v5 decode
+→ AES-GCM authentication/decryption
+→ internal compression/signature metadata processing
+→ application payload
+→ optional Ed25519 signature verification
+```
+
+This keeps signature metadata confidential when encryption is enabled while preserving offline verification after decryption.
+
+## 10. Text and binary APIs
+
+Text and bytes are first-class without semantic payload types:
+
+- `encodeText()` / `decodeMatrix().text` for UTF-8 text;
+- `encodeBytes()` for arbitrary bytes;
+- `encodeUint8Array()` / `decodeUint8Array()` as explicit byte-oriented convenience APIs.
+
+Compression works on both text and byte payloads through the same `compression` option.
+
+## 11. Rendering profiles
+
+Rendering does not modify the encoded matrix.
+
+### Screen mode
+
+Uses the normal RGBW palette and permits:
+
+```text
+classic
+soft
+depth
+inset
+```
+
+### Print mode
+
+`mode: "print"` applies conservative defaults:
+
+- minimum quiet zone of 4 modules unless explicitly overridden;
+- print-safe darker RGB primaries;
+- Classic solid-module rendering by default;
+- physical-size guidance through `getPrintGuidance()`.
+
+Recommended general-purpose starting module size is **0.40 mm/module**. Real printer, paper, ink/toner, lamination, lighting, and camera validation remains necessary for production deployments.
+
+## 12. Logo safety
+
+Logos are rendering overlays and never modify Format v5 data structures.
+
+`size: "auto"` estimates a conservative logo ratio from:
+
+- ECC profile;
+- encoded utilization;
+- version 1 compact-profile penalty;
+- clear-background usage;
+- screen vs print mode.
+
+`findMaxSafeLogoSize()` can empirically search the largest decodable logo size when an ImageData-like logo is available. Generated symbols should still be verified after final rendering.
+
+## 13. Scanner diagnostics
+
+Successful image scans expose normalized diagnostic fields including:
+
+```text
+confidence
+geometryConfidence
+calibrationConfidence
+structureConfidence
+eccUtilization
+correctedErrors
+erasureSymbols
+```
+
+With `debug: true`, the scanner can also report stage state, geometry candidates, finder/vision passes, latest sampled matrix, confidence matrix, color-normalization method, and the failed stage when decoding does not complete.
+
+Debug output is diagnostic evidence, not a cryptographic assurance score.
+
+## 14. Scanability score and torture testing
+
+`runImageStressTest()` and `assessScanability()` use deterministic synthetic distortions to estimate robustness against:
+
+- blur;
+- low brightness;
+- high exposure;
+- uneven shadow;
+- contrast loss;
+- perspective distortion;
+- JPEG-like quantization/block artifacts;
+- downscaling.
+
+Current rating bands:
+
+```text
+90–100  Excellent
+75–89   Good
+50–74   Risky
+0–49    Likely unscannable
+```
+
+These scores are regression/testing aids. They do not replace validation with real phone cameras, printers, displays, paper stocks, lighting conditions, and physical damage.
+
+## 15. Capacity planning
+
+Capacity is determined from the actual Format v5 layout, protected header, CRC, and Spectrum ECC plan. Compression can reduce stored payload bytes, while signatures and encryption add metadata bytes before the matrix codec.
+
+The benchmark helper can report:
+
+- minimum QuadQR version;
+- encoded bytes;
+- remaining capacity;
+- utilization;
+- approximate same-letter standard QR byte-mode version.
+
+When only a payload byte count is known, `compression: "auto"` cannot predict the gain because compressibility depends on the actual bytes.
+
+Standard QR comparisons use the same **nominal ECC letter only**. QuadQR and ISO QR recovery strengths are not equivalent and should not be presented as such.
+
+## 16. Compatibility principles
+
+Implementations should follow these rules:
+
+1. Keep RGBW mapping exactly `R=00, G=01, B=10, W=11`.
+2. Keep GF(256) Spectrum ECC and its errors+erasures behavior.
+3. Preserve Format v5 decoding for normal and Secure Payload symbols.
+4. Keep application semantics outside the QuadQR codec. Do not require a growing content-type registry.
+5. Treat compression/signature metadata as internal transport metadata, not a separate user payload mode.
+6. Treat `keyId` only as an identifier. Signer trust comes from an external trusted public-key binding.
+7. Keep rendering effects out of structural finder/timing/alignment/calibration modules.
+8. Validate public format changes with both matrix and rendered-image scanner tests.
+
+## 17. Reference implementation
+
+The JavaScript implementation in this repository is the current reference implementation. Public entry points are documented under `docs/` and exercised by `tests/self-test.js` and `tests/package-test.js`.