quadqr-js 1.4.2 → 1.5.2

package/docs/NODE.md

@@ -1,159 +1,159 @@
-# 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.
-
-## Server-side compression
-
-Compression uses the same synchronous JavaScript codec on Node.js as it does in the browser. No DOM API, browser `CompressionStream`, or Node `zlib` call is required by the QuadQR payload codec.
-
-```js
-import { encodeText, decodeMatrix } from "quadqr-js";
-
-const code = encodeText("hello ".repeat(1000), {
-  compression: "auto"
-});
-
-const smallest = encodeText("structured payload ".repeat(500), {
-  compression: "smart"
-});
-
-const decoded = decodeMatrix(code.matrix);
-console.log(decoded.compression); // usually "brotli" for repetitive data
-console.log(decoded.text);
-```
-
-`compression: "auto"` performs one balanced comparison using LZ level 6, DEFLATE level 6, and Brotli quality 6. `compression: "smart"` is the opt-in CPU-heavy mode and escalates to stronger levels only when a smaller QuadQR version is realistically reachable. Explicit `lz` and `deflate` accept `compressionLevel: 1..9` (default 6), while explicit `brotli` accepts `compressionLevel: 0..11` (default 11). `lzLevel`, `deflateLevel`, and `brotliQuality` are available as algorithm-specific aliases.
-
-## 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.
+
+## Server-side compression
+
+Compression uses the same synchronous JavaScript codec on Node.js as it does in the browser. No DOM API, browser `CompressionStream`, or Node `zlib` call is required by the QuadQR payload codec.
+
+```js
+import { encodeText, decodeMatrix } from "quadqr-js";
+
+const code = encodeText("hello ".repeat(1000), {
+  compression: "auto"
+});
+
+const smallest = encodeText("structured payload ".repeat(500), {
+  compression: "smart"
+});
+
+const decoded = decodeMatrix(code.matrix);
+console.log(decoded.compression); // usually "brotli" for repetitive data
+console.log(decoded.text);
+```
+
+`compression: "auto"` performs one balanced comparison using LZ level 6, DEFLATE level 6, and Brotli quality 6. `compression: "smart"` is the opt-in CPU-heavy mode and escalates to stronger levels only when a smaller QuadQR version is realistically reachable. Explicit `lz` and `deflate` accept `compressionLevel: 1..9` (default 6), while explicit `brotli` accepts `compressionLevel: 0..11` (default 11). `lzLevel`, `deflateLevel`, and `brotliQuality` are available as algorithm-specific aliases.
+
+## 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,62 +1,62 @@
-# 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, and optional prebuilt WebAssembly acceleration.
-
-## Live links
-
-- [Documentation Site](https://akanshsirohi.github.io/QuadQR/documentation/)
-- [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)
-- [Compression 3.0](./COMPRESSION.md)
-- [High Density Mode (Experimental)](./HIGH_DENSITY_MODE.md)
-- [Reliability Lab](./RELIABILITY_LAB.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 Compression 3.0;
-- bundled synchronous Brotli + portable DEFLATE + level-aware legacy LZ compatibility;
-- 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;
-- a dedicated browser Reliability Lab with 3D perspective sweeps, plus the capacity calculator.
-
-See [`../SPECIFICATION.md`](../SPECIFICATION.md) for the layering and interoperability rules and [`API.md`](./API.md) for the public APIs.
+# 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, and optional prebuilt WebAssembly acceleration.
+
+## Live links
+
+- [Documentation Site](https://akanshsirohi.github.io/QuadQR/documentation/)
+- [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)
+- [Compression 3.0](./COMPRESSION.md)
+- [High Density Mode (Experimental)](./HIGH_DENSITY_MODE.md)
+- [Reliability Lab](./RELIABILITY_LAB.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 Compression 3.0;
+- bundled synchronous Brotli + portable DEFLATE + level-aware legacy LZ compatibility;
+- 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;
+- a dedicated browser Reliability Lab with 3D perspective sweeps, plus the capacity calculator.
+
+See [`../SPECIFICATION.md`](../SPECIFICATION.md) for the layering and interoperability rules and [`API.md`](./API.md) for the public APIs.

package/docs/RELIABILITY_LAB.md

@@ -1,64 +1,64 @@
-# Reliability Lab
-
-QuadQR includes a deterministic Reliability Lab for regression testing generated symbols against camera-style damage. It is intended for comparing scanner changes, render settings, ECC profiles, output size, and the experimental High Density Mode under repeatable conditions.
-
-The lab verifies the decoded payload CRC. Finding three locators is not counted as success unless the final payload is recovered correctly.
-
-## Browser demo
-
-Open the **Reliability Lab** tab after generating a QuadQR. The lab provides:
-
-- Quick, Full, and Extreme suites;
-- per-scenario pass/fail, confidence, Reed-Solomon correction count, and decode time;
-- category-level scoring for optics, lighting, color, resampling, sensor damage, and perspective;
-- a 3D perspective playground with X pitch, Y yaw, and Z rotation controls;
-- angle sweeps to find the largest tested pitch, yaw, or Z rotation that still decodes.
-
-X pitch and Y yaw simulate a code plane tilting in depth. Z rotation is an in-plane rotation. The controls can be combined.
-
-## Public API
-
-```js
-import {
-  applyStressDistortion,
-  runReliabilityLab,
-  runPerspectiveSweep
-} from "quadqr-js";
-
-const transformed = applyStressDistortion(imageData, "perspective-3d", 0.5, {
-  pitchDegrees: 20,
-  yawDegrees: 45,
-  rollDegrees: 15
-});
-
-const report = runReliabilityLab(imageData, {
-  version: encoded.version,
-  crc32: encoded.crc32
-}, {
-  suite: "full"
-});
-
-const sweep = runPerspectiveSweep(imageData, {
-  version: encoded.version,
-  crc32: encoded.crc32
-}, {
-  axis: "yaw",
-  angles: [0, 15, 25, 35, 45, 55]
-});
-```
-
-## Suites
-
-The Reliability Lab extends the smaller scanability suite with deterministic cases for lens blur, motion blur, low/high exposure, gradient shadow, glare, warm/cool color casts, contrast loss, sensor noise, JPEG-like damage, downscaling, projective skew, 3D pitch/yaw, Z rotation, and combined 3D tilt.
-
-The **Extreme** suite adds stronger perspective cases. These are deliberately demanding and may fail at low pixels-per-module even when the same angle succeeds at a larger rendered size.
-
-## Perspective scanner recovery
-
-The scanner keeps its normal fast path for ordinary frames. When locator scale differences indicate projective foreshortening, the geometry stage can perform a bounded coarse-to-fine search for the primary alignment reference. The fine stage uses denser sub-cell scoring so payload cells are less likely to impersonate the alignment marker. This improves steep-angle recovery without weakening normal structure checks globally.
-
-Distributed secondary alignment references are still used to validate the resulting homography.
-
-## Interpreting results
-
-Synthetic results are regression aids, not a substitute for real phone-camera and print testing. A useful practical metric is the largest reliable angle at the intended physical size and scanning distance, not only the theoretical bits per cell.
+# Reliability Lab
+
+QuadQR includes a deterministic Reliability Lab for regression testing generated symbols against camera-style damage. It is intended for comparing scanner changes, render settings, ECC profiles, output size, and the experimental High Density Mode under repeatable conditions.
+
+The lab verifies the decoded payload CRC. Finding three locators is not counted as success unless the final payload is recovered correctly.
+
+## Browser demo
+
+Open the **Reliability Lab** tab after generating a QuadQR. The lab provides:
+
+- Quick, Full, and Extreme suites;
+- per-scenario pass/fail, confidence, Reed-Solomon correction count, and decode time;
+- category-level scoring for optics, lighting, color, resampling, sensor damage, and perspective;
+- a 3D perspective playground with X pitch, Y yaw, and Z rotation controls;
+- angle sweeps to find the largest tested pitch, yaw, or Z rotation that still decodes.
+
+X pitch and Y yaw simulate a code plane tilting in depth. Z rotation is an in-plane rotation. The controls can be combined.
+
+## Public API
+
+```js
+import {
+  applyStressDistortion,
+  runReliabilityLab,
+  runPerspectiveSweep
+} from "quadqr-js";
+
+const transformed = applyStressDistortion(imageData, "perspective-3d", 0.5, {
+  pitchDegrees: 20,
+  yawDegrees: 45,
+  rollDegrees: 15
+});
+
+const report = runReliabilityLab(imageData, {
+  version: encoded.version,
+  crc32: encoded.crc32
+}, {
+  suite: "full"
+});
+
+const sweep = runPerspectiveSweep(imageData, {
+  version: encoded.version,
+  crc32: encoded.crc32
+}, {
+  axis: "yaw",
+  angles: [0, 15, 25, 35, 45, 55]
+});
+```
+
+## Suites
+
+The Reliability Lab extends the smaller scanability suite with deterministic cases for lens blur, motion blur, low/high exposure, gradient shadow, glare, warm/cool color casts, contrast loss, sensor noise, JPEG-like damage, downscaling, projective skew, 3D pitch/yaw, Z rotation, and combined 3D tilt.
+
+The **Extreme** suite adds stronger perspective cases. These are deliberately demanding and may fail at low pixels-per-module even when the same angle succeeds at a larger rendered size.
+
+## Perspective scanner recovery
+
+The scanner keeps its normal fast path for ordinary frames. When locator scale differences indicate projective foreshortening, the geometry stage can perform a bounded coarse-to-fine search for the primary alignment reference. The fine stage uses denser sub-cell scoring so payload cells are less likely to impersonate the alignment marker. This improves steep-angle recovery without weakening normal structure checks globally.
+
+Distributed secondary alignment references are still used to validate the resulting homography.
+
+## Interpreting results
+
+Synthetic results are regression aids, not a substitute for real phone-camera and print testing. A useful practical metric is the largest reliable angle at the intended physical size and scanning distance, not only the theoretical bits per cell.