quadqr-js 1.0.2 → 1.2.0

package/docs/API.md

@@ -110,12 +110,32 @@ Renders to an HTML canvas.
 
 ```js
 renderToCanvas(code, canvas, {
-  moduleSize: 12,
+  imageSize: 720,
   quietZone: 4,
-  style: "classic"
+  style: "classic",
+  logo: {
+    source: loadedImage,
+    size: 0.12,
+    clearBackground: true,
+    padding: 0.65,
+    radius: 0.8
+  }
 });
 ```
 
+`imageSize` sets the exact square output width/height in pixels. The default is `720` when neither `imageSize` nor `moduleSize` is provided. `moduleSize` remains supported as a lower-level pixels-per-module sizing option and is used when `imageSize` is omitted.
+
+`quietZone` is measured in modules. The default is `4`.
+
+Logo options:
+
+- `source`: loaded CanvasImageSource for canvas rendering, ImageData-like RGBA data for `renderToImageData()`, or URL/data URL for SVG.
+- `size`: fraction of the matrix width/height, clamped to `0.05..0.30`. Default `0.18`.
+- `clearBackground`: clears modules behind the logo using a solid background before drawing the logo.
+- `padding`: clear-background padding in modules. Default `0.65`.
+- `radius`: clear-background corner radius in modules. Default `0.8`.
+- `backgroundColor`: background color when clearing. Defaults to palette white.
+
 Supported styles:
 
 - `classic`
@@ -135,6 +155,23 @@ Returns runtime-neutral RGBA pixels:
 }
 ```
 
+### `renderToSVG(codeOrMatrix, options?)`
+
+Returns a standalone SVG string. It supports the same exact `imageSize`, palette, render style, quiet-zone, and logo geometry options as the browser canvas renderer. Because the preview/export is vector, it stays sharp when displayed above or below its nominal pixel size.
+
+```js
+const svg = renderToSVG(code, {
+  imageSize: 720,
+  quietZone: 6,
+  style: "soft",
+  logo: {
+    source: "data:image/png;base64,...",
+    size: 0.12,
+    clearBackground: true
+  }
+});
+```
+
 ## Image and camera scanning
 
 ### `scanImageData(imageData, options?)`
@@ -225,7 +262,22 @@ Writes a PNG file.
 
 ```js
 await savePNG(code, "quadqr.png", {
-  moduleSize: 12,
+  imageSize: 720,
+  quietZone: 4
+});
+```
+
+### `toSVG(codeOrMatrix, options?)`
+
+Returns the standalone SVG string from the Node entry point.
+
+### `saveSVG(codeOrMatrix, filename, options?)`
+
+Writes SVG directly to disk.
+
+```js
+await saveSVG(code, "quadqr.svg", {
+  imageSize: 720,
   quietZone: 4
 });
 ```
@@ -315,6 +367,10 @@ Common exported constants include:
 - `CELL`
 - `DEFAULT_PALETTE`
 - `RENDER_STYLES`
+- `RENDER_MODES`
+- `COMPRESSION_MODES`
+- `SIGNATURE_ALGORITHMS`
+- `STRESS_PROFILES`
 - `ECC_LEVELS`
 
 ## Benchmark entry
@@ -324,6 +380,166 @@ Benchmark helpers are available from `quadqr-js/benchmark`:
 ```js
 import {
   buildCapacityComparison,
-  benchmarkCodec
+  benchmarkCodec,
+  calculateCapacityPlan
 } from "quadqr-js/benchmark";
 ```
+
+### `calculateCapacityPlan(options)`
+
+Estimates the smallest QuadQR version for a byte count or concrete payload and reports remaining capacity plus the standard QR byte-mode version at the same nominal ECC letter. When only a byte count is known, compression gain is intentionally not guessed.
+
+---
+
+## Compression
+
+### `encodeText(text, options?)` / `encodeBytes(input, options?)`
+
+Both normal encoding APIs accept an optional compression mode:
+
+```js
+const code = QuadQR.encodeText("hello hello hello", {
+  compression: "auto",
+  ecc: "M"
+});
+```
+
+`compression` may be `none`, `auto`, 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.
+
+There is no public content-type registry. Text remains text and byte arrays remain byte arrays.
+
+### `compressPayload(input)` / `decompressPayload(input, expectedLength?)`
+
+Portable synchronous LZSS-style compression helpers. They do not require Node zlib or browser `CompressionStream`.
+
+## Binary convenience APIs
+
+### `encodeUint8Array(input, options?)`
+
+Explicit byte-oriented alias of `encodeBytes()`. It supports the same optional `compression` setting.
+
+### `decodeUint8Array(matrix, options?)`
+
+Decodes a matrix and returns only the application payload bytes.
+
+## Signed QuadQR
+
+### `generateSigningKeyPair()`
+
+Generates an extractable Ed25519 key pair using Web Crypto and returns the CryptoKeys, raw public-key bytes, PKCS#8 private-key bytes, and a compact SHA-256-derived `keyId`.
+
+### `encodeSignedText(text, options)` / `encodeSignedBytes(input, options)`
+
+Signs the normal application payload with Ed25519. Any required signature and compression metadata is handled internally.
+
+```js
+const pair = await QuadQR.generateSigningKeyPair();
+const code = await QuadQR.encodeSignedText("certificate payload", {
+  ecc: "Q",
+  compression: "auto",
+  privateKey: pair.privateKey,
+  keyId: pair.keyId
+});
+```
+
+Only the private key is required for signing. `publicKey` is accepted only for the explicit `embedPublicKey: true` compatibility mode.
+
+### `verifyDecodedSignature(result, options?)`
+
+Verifies a signed decode result against a trusted external Ed25519 public key.
+
+```js
+const decoded = QuadQR.decodeMatrix(code.matrix);
+const verified = await QuadQR.verifyDecodedSignature(decoded, {
+  publicKey: knownPublicKey
+});
+```
+
+For multiple issuers, pass a `trustedKeys` object or `Map` keyed by the embedded `keyId`:
+
+```js
+const verified = await QuadQR.verifyDecodedSignature(decoded, {
+  trustedKeys: {
+    [decoded.signingKeyId]: knownPublicKey
+  }
+});
+```
+
+`signatureVerified: true` means the signature is mathematically valid. `signatureTrusted: true` means it was checked using an external trusted key. `allowEmbeddedKey: true` may be used for compatibility/self-contained integrity checks, but such a result is not considered a trusted signer.
+
+### Signing + encryption
+
+`encodeSecureText()` and `encodeSecureBytes()` accept an optional `signing` object alongside `security` and `compression`. The internal pipeline is compression → signing → AES-256-GCM → Spectrum ECC.
+
+```js
+const code = await QuadQR.encodeSecureText("private signed payload", {
+  compression: "auto",
+  security: { mode: "password", password: "secret" },
+  signing: {
+    privateKey: pair.privateKey,
+    keyId: pair.keyId
+  }
+});
+```
+
+## Print rendering
+
+All render APIs accept:
+
+```js
+{ 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.
+
+### `getPrintGuidance(codeOrMatrix, options?)`
+
+Returns physical module size, pixels/module at a DPI, recommended minimum physical size, and print recommendations.
+
+## Automatic logo safety
+
+A logo can use:
+
+```js
+logo: {
+  source: logo,
+  size: "auto",
+  clearBackground: true
+}
+```
+
+`estimateSafeLogoSize()` exposes the conservative ratio used by auto mode. `findMaxSafeLogoSize()` performs an empirical binary search when the logo source is ImageData-like.
+
+## Scanner confidence and debug mode
+
+Normal successful scans now include:
+
+- `confidence`
+- `geometryConfidence`
+- `calibrationConfidence`
+- `structureConfidence`
+- `eccUtilization`
+- `correctedErrors`
+- `diagnostics`
+
+Use `scanImageData(image, { debug: true })` for detailed geometry/sampling information. `debugScanImageData()` is a non-throwing helper that returns `{ ok, result, debug }` or `{ ok: false, error, debug }`.
+
+## Scanability and stress testing
+
+### `applyStressDistortion(imageData, type, severity?)`
+
+Deterministically applies a selected synthetic distortion.
+
+### `runImageStressTest(imageData, expected?, options?)`
+
+Runs the standard torture profiles and returns a 0–100 score plus per-scenario decode results.
+
+### `assessScanability(code, renderOptions?, options?)`
+
+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.

package/docs/BROWSER_CDN.md

@@ -8,6 +8,7 @@ With Vite, webpack, Rollup, Next.js client code, or another browser bundler:
 import {
   encodeText,
   renderToCanvas,
+  renderToSVG,
   scanFile,
   startCameraScanner
 } from "quadqr-js/browser";
@@ -21,14 +22,58 @@ The main `quadqr-js` entry also works in modern browser bundlers for runtime-neu
 const code = encodeText("Hello browser");
 
 renderToCanvas(code, document.querySelector("#qr"), {
-  moduleSize: 12,
+  imageSize: 720,
   quietZone: 4,
   style: "classic"
 });
+
+const svg = renderToSVG(code, {
+  imageSize: 720,
+  quietZone: 4
+});
 ```
 
+`imageSize` controls the exact square output size. If neither `imageSize` nor `moduleSize` is supplied, the renderer defaults to 720 × 720 px.
+
 Available styles are `classic`, `depth`, `soft`, and `inset`.
 
+## Compressed, signed, and print-safe output
+
+```js
+import {
+  assessScanability,
+  decodeMatrix,
+  encodeText,
+  encodeSignedText,
+  generateSigningKeyPair,
+  renderToCanvas,
+  verifyDecodedSignature
+} from "quadqr-js/browser";
+
+const compressed = encodeText("repeat repeat repeat repeat", {
+  compression: "auto"
+});
+
+const keys = await generateSigningKeyPair();
+const signed = await encodeSignedText("ticket", {
+  compression: "auto",
+  privateKey: keys.privateKey,
+  keyId: keys.keyId
+});
+
+const checked = await verifyDecodedSignature(decodeMatrix(signed.matrix), {
+  publicKey: keys.publicKey
+});
+console.log(checked.signatureVerified, checked.signatureTrusted);
+
+const canvas = document.querySelector("#qr");
+renderToCanvas(compressed, canvas, { mode: "print", imageSize: 720 });
+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.
+
 ## Scan an uploaded image
 
 ```js
@@ -88,12 +133,12 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
 
 ```html
 <canvas id="qr"></canvas>
-<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 CDN");
 
   QuadQR.renderToCanvas(code, document.querySelector("#qr"), {
-    moduleSize: 12,
+    imageSize: 720,
     quietZone: 4
   });
 </script>
@@ -102,7 +147,7 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
 ## unpkg
 
 ```html
-<script src="https://unpkg.com/quadqr-js@1.0.1/dist/quadqr.min.js"></script>
+<script src="https://unpkg.com/quadqr-js@1.1.0/dist/quadqr.min.js"></script>
 ```
 
 ## Direct CDN ESM
@@ -112,7 +157,7 @@ The global browser build exposes `window.QuadQR` / `globalThis.QuadQR`.
   import {
     encodeText,
     renderToCanvas
-  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.0.1/dist/browser.js";
+  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.1.0/dist/browser.js";
 
   const code = encodeText("ES module CDN");
   renderToCanvas(code, document.querySelector("#qr"));
@@ -139,4 +184,4 @@ WASM is optional. The normal JavaScript implementation remains available if it c
 
 ## Production recommendation
 
-Pin a concrete package version such as `@1.0.1` 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.1.0` in CDN URLs so an existing site does not silently change when a newer package version becomes available.

package/docs/CLI.md

@@ -1,76 +1,150 @@
-# 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
-```
-
-Optional encoding controls:
-
-```bash
-npx quadqr-js encode "Hello" --ecc M --version auto --module-size 12 --quiet-zone 4 -o hello.png
-```
-
-## Decode an image
-
-```bash
-npx quadqr-js decode hello.png
-```
-
-For an unencrypted text payload, the decoded text is printed to stdout.
-
-## 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 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 path. Default: `quadqr.png` |
-| `--ecc <L|M|Q|H>` | QuadQR ECC profile. Default: `M` |
-| `--version <auto|1..40>` | Symbol version. Default: `auto` |
-| `--password <text>` | Password-mode encryption/decryption |
-| `--key <hex>` | Raw 256-bit key encryption/decryption |
-| `--module-size <px>` | PNG pixels per module. Default: `12` |
-| `--quiet-zone <modules>` | Quiet-zone size. Default: `4` |
-| `-h, --help` | Show CLI help |
-
-Password mode and raw-key mode are mutually exclusive for a single operation.
+# 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`, and `lz`. `auto` keeps the original payload untouched when compression does not make it smaller. No separate payload mode is required.
+
+## 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`, or `lz`. Default: `auto` |
+| `--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.