quadqr-js 1.0.2 → 1.3.0

package/docs/API.md

@@ -11,12 +11,15 @@ import { encodeText } from "quadqr-js";
 
 const code = encodeText("Hello", {
   ecc: "M",
-  version: 5
+  version: 5,
+  highDensity: true // optional experimental 4-bit cells
 });
 ```
 
 If `version` is omitted, QuadQR selects the smallest version that fits.
 
+`highDensity` is a boolean. It defaults to `false`. Set `highDensity: true` to enable the experimental Triangle16 layout with two RGBW triangles, 16 states, and 4 raw bits per body cell. The protected header remains solid-color in High Density Mode. Image and camera scanners auto-detect it.
+
 ### `encodeBytes(bytes, options?)`
 
 Encodes arbitrary bytes.
@@ -110,12 +113,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,11 +158,28 @@ 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?)`
 
-Scans an ImageData-like RGBA object. Clean frames use the normal observed-RGB path first. Difficult frames then get bounded fallback attempts using per-channel white balancing, spatial black/white normalization, tighter centre sampling, module-grid Auto Tone / Auto Contrast / Auto Color recovery, a rectified QR-region pixel enhancement pass, and sub-module geometry micro-refinement before the scan is rejected.
+Scans an ImageData-like RGBA object. The scanner automatically attempts both normal RGBW center sampling and Triangle16 dual-region sampling when geometry is found. When normal projective geometry is locatable but too coarse for half-cell Triangle16 regions, one bounded precise-alignment recovery pass refines the alignment center at sub-module resolution. Clean frames use the normal observed-RGB path first. Difficult frames then get bounded fallback attempts using per-channel white balancing, spatial black/white normalization, tighter centre sampling, module-grid Auto Tone / Auto Contrast / Auto Color recovery, a rectified QR-region pixel enhancement pass, and sub-module geometry micro-refinement before the scan is rejected. Dense versions also use their distributed alignment markers to refine a noisy four-point projective solution when the initial alignment-grid score is plausible but imperfect. If exactly two strong finder patterns survive a steep angle, a bounded perspective-tolerant third-finder recovery pass is attempted before heavier color recovery.
 
 ```js
 const result = scanImageData({
@@ -149,7 +189,7 @@ const result = scanImageData({
 });
 ```
 
-Useful scanner options include `sampleRadius`, `robustSampleRadius`, `adaptiveSampling`, `spatialColorNormalization`, `autoEnhanceRecovery`, `rectifiedAutoEnhanceRecovery`, `rectifiedRecoveryModuleSize`, `autoEnhanceBlackClip`, `autoEnhanceWhiteClip`, `autoEnhanceSaturation`, `geometryRefinement`, `refinementOffset`, `structureTolerance`, and `maxErasureConfidence`. Auto enhancement and geometry refinement are enabled by default, but only run after the normal scan path fails.
+Useful scanner options include `sampleRadius`, `robustSampleRadius`, `adaptiveSampling`, `spatialColorNormalization`, `autoEnhanceRecovery`, `rectifiedAutoEnhanceRecovery`, `rectifiedRecoveryModuleSize`, `autoEnhanceBlackClip`, `autoEnhanceWhiteClip`, `autoEnhanceSaturation`, `geometryRefinement`, `alignmentRefinement`, `alignmentRefinePatternThreshold`, `refinementOffset`, `structureTolerance`, and `maxErasureConfidence`. Auto enhancement and geometry refinement are enabled by default, but bounded recovery work only runs when the normal scan path or initial geometry needs it.
 
 ### Browser `scanFile(file, options?)`
 
@@ -169,7 +209,7 @@ const result = scanVideoFrame(video);
 
 ### `startCameraScanner(video, options?)`
 
-Starts live camera scanning. On browsers that expose camera controls, QuadQR requests continuous autofocus, exposure, and white balance. It scans the CSS-visible preview region by default. Finder detection uses a QuadQR-specific RGB value channel (`max(R,G,B)`) on the fast pass so saturated blue/red/green data cells are not mistaken for structural black. If that fast pass fails, the **same captured frame** is retried through code-centric Auto Color recovery before finder detection. The default recovery sequence crops 8%, 16%, and 22% from the camera-frame edges, then falls back to the full frame. This prevents dark room pixels, browser UI, or monitor bezels outside the guide from controlling Auto Color and Otsu thresholds. Each crop uses the Photoshop-style per-channel shadow/highlight correction with a neutral mid-high highlight target (190 by default). Finder-only recovery also tries multiple center-weighted Auto Color histogram windows before raw threshold bracketing. The normal fast path is untouched; these extra passes run only after a miss. If geometry is found but color decoding fails, the captured ROI is retried with the stronger color/geometry recovery, and consecutive failed frames can still be combined with confidence-weighted module voting.
+Starts live camera scanning. On browsers that expose camera controls, QuadQR requests continuous autofocus, exposure, and white balance. It scans the CSS-visible preview region by default. Finder detection uses a QuadQR-specific RGB value channel (`max(R,G,B)`) on the fast pass so saturated blue/red/green data cells are not mistaken for structural black. If a miss still contains at least two strong finder patterns, the scanner can retry the visible ROI at up to 1600 px before heavier recovery, which preserves more pixels per module for dense versions. If that does not decode, the **same captured frame** is retried through code-centric Auto Color recovery. The default recovery sequence crops 8%, 16%, and 22% from the camera-frame edges, then falls back to the full frame. This prevents dark room pixels, browser UI, or monitor bezels outside the guide from controlling Auto Color and Otsu thresholds. Each crop uses the Photoshop-style per-channel shadow/highlight correction with a neutral mid-high highlight target (190 by default). Finder-only recovery also tries multiple center-weighted Auto Color histogram windows before raw threshold bracketing. The normal fast path is untouched; these extra passes run only after a miss. If geometry is found but color decoding fails, the captured ROI is retried with the stronger color/geometry recovery, and consecutive failed frames can still be combined with confidence-weighted module voting.
 
 ```js
 const scanner = await startCameraScanner(video, {
@@ -183,6 +223,9 @@ const scanner = await startCameraScanner(video, {
   cameraAutoColorAnalysisInset: 0.10,
   cameraAutoEnhanceEvery: 2,
   cameraFinderRecoveryEvery: 2,
+  cameraHighResolutionRecovery: true,
+  cameraHighResolutionMaxDimension: 1600,
+  cameraHighResolutionEvery: 2,
   onResult(result) {
     console.log(result);
   },
@@ -225,7 +268,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 +373,10 @@ Common exported constants include:
 - `CELL`
 - `DEFAULT_PALETTE`
 - `RENDER_STYLES`
+- `RENDER_MODES`
+- `COMPRESSION_MODES`
+- `SIGNATURE_ALGORITHMS`
+- `STRESS_PROFILES`
 - `ECC_LEVELS`
 
 ## Benchmark entry
@@ -324,6 +386,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,156 @@
-# 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` |
+| `--high-density` | Enable experimental Triangle16 High Density Mode |
+| `--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.
+
+
+## High Density Mode (Experimental)
+
+Use `--high-density` to enable the experimental Triangle16 layout with 16 states and 4 raw bits per body cell. Decode is automatic; no matching decode flag is required.