quadqr-js 1.0.2 → 1.2.0

package/docs/GETTING_STARTED.md

@@ -28,20 +28,30 @@ If no version is supplied, QuadQR automatically chooses the smallest version tha
 ```js
 import {
   encodeText,
-  renderToCanvas
+  renderToCanvas,
+  renderToSVG
 } from "quadqr-js/browser";
 
 const code = encodeText("Rendered in the browser");
 
 renderToCanvas(code, document.querySelector("#qr"), {
-  moduleSize: 12,
+  imageSize: 720,
   quietZone: 4,
   style: "classic"
 });
+
+const svg = renderToSVG(code, {
+  imageSize: 720,
+  quietZone: 4
+});
 ```
 
 Available presentation styles are `classic`, `depth`, `soft`, and `inset`. Styling does not change the encoded matrix.
 
+`imageSize` is the exact square output dimension in pixels. If you omit both `imageSize` and `moduleSize`, the renderer defaults to 720 × 720 px. `moduleSize` is still available for low-level pixels-per-module sizing.
+
+To add a centered logo, load it as an `Image` and pass it as `logo.source`. Transparent logo pixels remain transparent. Use `clearBackground: true` when you want a padded white area behind the logo. `quietZone` is measured in modules and defaults to `4`.
+
 ## Scan an uploaded image
 
 ```js
@@ -125,16 +135,21 @@ const code = await encodeSecureText("Application-managed secret", {
 
 The key must be exactly 32 bytes. Never embed the secret key inside the same QuadQR payload.
 
-## Generate and scan PNG files in Node.js
+## Generate PNG and SVG files in Node.js
 
 ```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,
+  imageSize: 720,
+  quietZone: 4
+});
+
+await saveSVG(code, "quadqr.svg", {
+  imageSize: 720,
   quietZone: 4
 });
 
@@ -142,13 +157,13 @@ const result = await scanFile("quadqr.png");
 console.log(result.text);
 ```
 
-PNG generation and decoding are built into the Node.js adapter.
+PNG generation/decoding and SVG generation are built into the Node.js adapter.
 
 ## Use a script tag
 
 ```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("No build step");
   QuadQR.renderToCanvas(code, document.querySelector("#qr"));
@@ -172,3 +187,61 @@ npx quadqr-js decode secure.png --password "my-password"
 ```
 
 See [CLI.md](./CLI.md) for the full command reference.
+
+## Compression and signed payloads
+
+Compression is available directly on the normal encode APIs. You do not need to select a payload type or use a separate payload mode:
+
+```js
+import { encodeText } from "quadqr-js";
+
+const code = encodeText("repeat repeat repeat repeat", {
+  compression: "auto",
+  ecc: "Q"
+});
+```
+
+`auto` keeps the original payload untouched when compression would not save space.
+
+For offline integrity verification:
+
+```js
+import { generateSigningKeyPair, encodeSignedText, decodeMatrix, verifyDecodedSignature } from "quadqr-js";
+
+const keys = await generateSigningKeyPair();
+const signed = await encodeSignedText("ticket data", {
+  compression: "auto",
+  privateKey: keys.privateKey,
+  keyId: keys.keyId
+});
+
+const result = await verifyDecodedSignature(decodeMatrix(signed.matrix), {
+  publicKey: keys.publicKey
+});
+console.log(result.signatureVerified, result.signatureTrusted);
+```
+
+Signing metadata is internal. The private key signs; the trusted public key verifies and remains outside the QuadQR by default. The optional `keyId` lets applications select the correct trusted public key without embedding it in every symbol.
+
+## Print mode
+
+```js
+renderToCanvas(code, canvas, {
+  imageSize: 1200,
+  mode: "print",
+  quietZone: 4
+});
+```
+
+Print mode uses safer defaults but should still be tested with the actual printer, paper, physical size, and target phones.
+
+## Scanability testing
+
+```js
+import { assessScanability } from "quadqr-js";
+
+const report = assessScanability(code, { imageSize: 480 });
+console.log(report.score, report.rating);
+```
+
+The browser demo includes an interactive stress lab for testing one distortion at a time or running the full suite.

package/docs/NODE.md

@@ -1,123 +1,137 @@
-# Node.js
-
-QuadQR uses the same matrix codec and scanner core in Node.js and the browser. The `quadqr-js/node` entry adds Node-specific PNG, file, and buffer helpers.
-
-## Requirements
-
-Node.js 20.19 or newer.
-
-## ESM
-
-```js
-import { encodeText } from "quadqr-js";
-import { savePNG, scanFile } from "quadqr-js/node";
-```
-
-## CommonJS
-
-```js
-const QuadQR = require("quadqr-js");
-const QuadQRNode = require("quadqr-js/node");
-```
-
-## Generate a PNG
-
-```js
-const code = QuadQR.encodeText("Server generated");
-
-await QuadQRNode.savePNG(code, "output.png", {
-  moduleSize: 12,
-  quietZone: 4
-});
-```
-
-Use `toPNG()` when you need an in-memory `Buffer`:
-
-```js
-const png = QuadQRNode.toPNG(code);
-```
-
-This works well for HTTP responses, object storage, attachments, and other buffer-based workflows.
-
-## Scan a PNG file
-
-```js
-const result = await QuadQRNode.scanFile("output.png");
-console.log(result.text);
-```
-
-Or scan a buffer:
-
-```js
-const result = await QuadQRNode.scanBuffer(pngBuffer);
-```
-
-PNG generation and decoding do not require external native dependencies.
-
-## Other image formats
-
-For JPEG, WebP, or AVIF input, the Node adapter can use `sharp` when the consuming application has it installed:
-
-```bash
-npm install sharp
-```
-
-If `sharp` is not installed, decode the image to RGBA in your own image pipeline and pass the pixels to `scanImageData()`.
-
-## Secure password workflow
-
-```js
-import {
-  decryptDecoded,
-  encodeSecureText
-} from "quadqr-js";
-import {
-  savePNG,
-  scanFile
-} from "quadqr-js/node";
-
-const code = await encodeSecureText("private", {
-  security: {
-    mode: "password",
-    password: process.env.QUADQR_PASSWORD
-  }
-});
-
-await savePNG(code, "secure.png");
-
-const locked = await scanFile("secure.png");
-
-const unlocked = await decryptDecoded(locked, {
-  password: process.env.QUADQR_PASSWORD
-});
-
-console.log(unlocked.text);
-```
-
-## Secure raw-key workflow
-
-```js
-import {
-  decryptDecoded,
-  encodeSecureText,
-  generateRaw256Key
-} from "quadqr-js";
-import { toPNG, scanBuffer } from "quadqr-js/node";
-
-const key = generateRaw256Key();
-
-const code = await encodeSecureText("machine secret", {
-  security: {
-    mode: "raw-key",
-    key
-  }
-});
-
-const png = toPNG(code);
-const locked = await scanBuffer(png);
-const unlocked = await decryptDecoded(locked, { key });
-
-console.log(unlocked.text);
-```
-
-Keep long-lived application keys in an appropriate secret-management or platform key-storage system.
+# Node.js
+
+QuadQR uses the same matrix codec and scanner core in Node.js and the browser. The `quadqr-js/node` entry adds Node-specific PNG, file, and buffer helpers.
+
+## Requirements
+
+Node.js 20.19 or newer.
+
+## ESM
+
+```js
+import { encodeText } from "quadqr-js";
+import { savePNG, saveSVG, scanFile } from "quadqr-js/node";
+```
+
+## CommonJS
+
+```js
+const QuadQR = require("quadqr-js");
+const QuadQRNode = require("quadqr-js/node");
+```
+
+## Generate a PNG
+
+```js
+const code = QuadQR.encodeText("Server generated");
+
+await QuadQRNode.savePNG(code, "output.png", {
+  imageSize: 720,
+  quietZone: 4
+});
+```
+
+## Generate an SVG
+
+```js
+await QuadQRNode.saveSVG(code, "output.svg", {
+  imageSize: 720,
+  quietZone: 4,
+  style: "classic"
+});
+```
+
+`imageSize` is the exact PNG/SVG output dimension in pixels. If you omit both `imageSize` and `moduleSize`, rendering defaults to 720 × 720 px. `moduleSize` remains available for legacy pixels-per-module sizing.
+
+Use `toSVG()` when you need the SVG string in memory. SVG logo sources can be URL/data URL strings. For PNG generation with a logo through `renderToImageData()`, pass decoded ImageData-like RGBA pixels as the logo source.
+
+Use `toPNG()` when you need an in-memory `Buffer`:
+
+```js
+const png = QuadQRNode.toPNG(code);
+```
+
+This works well for HTTP responses, object storage, attachments, and other buffer-based workflows.
+
+## Scan a PNG file
+
+```js
+const result = await QuadQRNode.scanFile("output.png");
+console.log(result.text);
+```
+
+Or scan a buffer:
+
+```js
+const result = await QuadQRNode.scanBuffer(pngBuffer);
+```
+
+PNG generation and decoding do not require external native dependencies.
+
+## Other image formats
+
+For JPEG, WebP, or AVIF input, the Node adapter can use `sharp` when the consuming application has it installed:
+
+```bash
+npm install sharp
+```
+
+If `sharp` is not installed, decode the image to RGBA in your own image pipeline and pass the pixels to `scanImageData()`.
+
+## Secure password workflow
+
+```js
+import {
+  decryptDecoded,
+  encodeSecureText
+} from "quadqr-js";
+import {
+  savePNG,
+  scanFile
+} from "quadqr-js/node";
+
+const code = await encodeSecureText("private", {
+  security: {
+    mode: "password",
+    password: process.env.QUADQR_PASSWORD
+  }
+});
+
+await savePNG(code, "secure.png");
+
+const locked = await scanFile("secure.png");
+
+const unlocked = await decryptDecoded(locked, {
+  password: process.env.QUADQR_PASSWORD
+});
+
+console.log(unlocked.text);
+```
+
+## Secure raw-key workflow
+
+```js
+import {
+  decryptDecoded,
+  encodeSecureText,
+  generateRaw256Key
+} from "quadqr-js";
+import { toPNG, scanBuffer } from "quadqr-js/node";
+
+const key = generateRaw256Key();
+
+const code = await encodeSecureText("machine secret", {
+  security: {
+    mode: "raw-key",
+    key
+  }
+});
+
+const png = toPNG(code);
+const locked = await scanBuffer(png);
+const unlocked = await decryptDecoded(locked, { key });
+
+console.log(unlocked.text);
+```
+
+Keep long-lived application keys in an appropriate secret-management or platform key-storage system.

package/docs/README.md

@@ -1,41 +1,59 @@
-# 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, rendering, matrix decoding, image and camera scanning, Spectrum ECC, optional authenticated encryption, Node.js PNG workflows, CDN usage, a CLI, TypeScript declarations, and optional prebuilt WebAssembly acceleration.
-
-## Live links
-
-- [Documentation Site](https://akanshsirohi.github.io/QuadQR/docs-site/)
-- [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)
-
-## Documentation
-
-- [Getting Started](./GETTING_STARTED.md)
-- [API Reference](./API.md)
-- [Browser and CDN](./BROWSER_CDN.md)
-- [Node.js](./NODE.md)
-- [CLI](./CLI.md)
-- [Secure Payloads](./SECURITY.md)
-- [WebAssembly](./WASM.md)
-- [Wire Format](../FORMAT.md)
-
-## Package entry points
-
-| Entry | Purpose |
-| --- | --- |
-| `quadqr-js` | Runtime-neutral core API, rendering, scanning, secure payloads, utilities, and optional WASM |
-| `quadqr-js/browser` | Browser ESM entry for canvas, files, video, and camera workflows |
-| `quadqr-js/node` | Node.js core plus PNG, file, and buffer helpers |
-| `quadqr-js/benchmark` | Capacity and codec benchmark helpers |
-| `quadqr-js/quadqr.min.js` | Classic browser global bundle for CDN/script-tag usage |
-
-The matrix codec is shared across runtimes. Browser and Node.js adapters only handle environment-specific input and output.
-
-## Compatibility note
-
-QuadQR is a custom experimental format, not ISO QR Code. Standard QR scanner applications cannot decode QuadQR symbols.
-
-## License
-
-QuadQR is licensed under AGPL-3.0. See [`LICENSE`](../LICENSE).
+# 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.
+
+## Live links
+
+- [Documentation Site](https://akanshsirohi.github.io/QuadQR/docs-site/)
+- [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)
+
+## Documentation
+
+- [Getting Started](./GETTING_STARTED.md)
+- [API Reference](./API.md)
+- [Browser and CDN](./BROWSER_CDN.md)
+- [Node.js](./NODE.md)
+- [CLI](./CLI.md)
+- [Secure Payloads](./SECURITY.md)
+- [WebAssembly](./WASM.md)
+- [Wire Format](../FORMAT.md)
+- [Technical Specification](../SPECIFICATION.md)
+
+## Package entry points
+
+| Entry | Purpose |
+| --- | --- |
+| `quadqr-js` | Runtime-neutral core API, rendering, scanning, secure payloads, utilities, and optional WASM |
+| `quadqr-js/browser` | Browser ESM entry for canvas, files, video, and camera workflows |
+| `quadqr-js/node` | Node.js core plus PNG/SVG, file, and buffer helpers |
+| `quadqr-js/benchmark` | Capacity and codec benchmark helpers |
+| `quadqr-js/quadqr.min.js` | Classic browser global bundle for CDN/script-tag usage |
+
+The matrix codec is shared across runtimes. Browser and Node.js adapters only handle environment-specific input and output.
+
+## Compatibility note
+
+QuadQR is a custom experimental format, not ISO QR Code. Standard QR scanner applications cannot decode QuadQR symbols.
+
+## License
+
+QuadQR is licensed under AGPL-3.0. See [`LICENSE`](../LICENSE).
+
+## Advanced reliability and payload features
+
+The current library also includes:
+
+- normal text/byte payloads with optional internal LZ compression;
+- portable automatic LZ compression;
+- first-class binary `Uint8Array` APIs;
+- Ed25519 signed QuadQR payloads and trusted-key verification;
+- signed + AES-256-GCM encrypted composition;
+- screen and print rendering modes;
+- 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.
+
+See [`../SPECIFICATION.md`](../SPECIFICATION.md) for the layering and interoperability rules and [`API.md`](./API.md) for the public APIs.

package/docs/WASM.md

@@ -17,7 +17,7 @@ const state = await initWasm();
 console.log(state);
 ```
 
-In QuadQR 0.7.x, the WASM module accelerates CRC-32. Once initialized, normal encode/decode operations automatically use the installed accelerator.
+In QuadQR 1.x, the WASM module accelerates CRC-32. Once initialized, normal encode/decode operations automatically use the installed accelerator.
 
 ## Check the current state
 
@@ -56,7 +56,7 @@ You can also provide WASM bytes directly through the `bytes` option.
 When the classic `quadqr.min.js` global build is loaded from a CDN, `QuadQR.initWasm()` resolves the bundled sibling WASM asset from the same package/version location.
 
 ```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>
   await QuadQR.initWasm();
 </script>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "quadqr-js",
-  "version": "1.0.2",
-  "description": "QuadQR: experimental four-state RGBW matrix code with Spectrum ECC, browser/Node scanning, CDN builds, and optional AES-256-GCM secure payloads.",
+  "version": "1.2.0",
+  "description": "QuadQR: experimental four-state RGBW matrix code with Spectrum ECC, compression, Ed25519 signing, browser/Node scanning, diagnostics, stress testing, and optional AES-256-GCM security.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -44,6 +44,7 @@
     "bin",
     "docs",
     "FORMAT.md",
+    "SPECIFICATION.md",
     "README.md",
     "LICENSE"
   ],
@@ -89,7 +90,11 @@
     "camera-scanner",
     "encryption",
     "aes-gcm",
-    "wasm"
+    "wasm",
+    "compression",
+    "ed25519",
+    "scan-diagnostics",
+    "print-qr"
   ],
   "sideEffects": false
 }

package/types/benchmark.d.ts

@@ -1,7 +1,8 @@
 import type { EccLevel } from "./index.js";
 export const STANDARD_QR_BYTE_CAPACITY: Readonly<Record<EccLevel, readonly number[]>>;
 export function getStandardQrByteCapacity(version: number, ecc?: EccLevel): number;
-export function compareCapacity(version: number, ecc?: EccLevel): Record<string, number | string>;
-export function buildCapacityComparison(options?: { ecc?: EccLevel; versions?: number[] }): Array<Record<string, number | string>>;
+export function compareCapacity(version: number, ecc?: EccLevel): Record<string, number | string | null>;
+export function calculateCapacityPlan(options?: { payload?: string | Uint8Array; payloadBytes?: number; ecc?: EccLevel; compression?: "none" | "auto" | "lz"; signed?: boolean; keyId?: string; embedPublicKey?: boolean }): Record<string, unknown>;
+export function buildCapacityComparison(options?: { ecc?: EccLevel; versions?: number[] }): Array<Record<string, number | string | null>>;
 export function benchmarkCodec(options?: Record<string, unknown>): Record<string, unknown>;
-export function benchmarkReport(options?: Record<string, unknown>): string;
+export function benchmarkReport(options?: Record<string, unknown>): Record<string, unknown>;