quadqr-js 1.0.2 → 1.3.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/HIGH_DENSITY_MODE.md

@@ -0,0 +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. For each data cell it samples two small regions well inside the triangles, approximately around `(0.28, 0.28)` and `(0.72, 0.72)` in normalized module coordinates.
+
+Each triangle is classified independently against the calibrated RGBW palette. The cell confidence is the weaker of the two triangle confidences. That confidence feeds the existing confidence-aware Spectrum ECC path, allowing an ambiguous triangle pair to become a useful erasure candidate instead of an arbitrary hard error.
+
+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.

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,60 @@
-# 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 RGBW matrix symbology. Default RGBW cells carry two bits using red, green, blue, or white. The experimental High Density Mode splits payload cells into two RGBW triangles and carries four raw bits per body data cell. 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)
+- [High Density Mode (Experimental)](./HIGH_DENSITY_MODE.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.