quadqr-js 1.0.2 → 1.3.0

package/docs/TRIANGLE16.md

@@ -0,0 +1,108 @@
+# Triangle16 experimental data-cell profile
+
+Triangle16 is an experimental QuadQR data-cell encoding for the high-density branch. 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 attempts Triangle16 sampling. 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
+
+Triangle16 uses exact hard-edged triangular payload cells. Decorative payload styles are intentionally bypassed in this profile 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, CELL_ENCODINGS } from "quadqr-js";
+
+const code = encodeText("High-density QuadQR", {
+  ecc: "M",
+  cellEncoding: CELL_ENCODINGS.TRIANGLE16
+});
+```
+
+The string form is also accepted:
+
+```js
+const code = encodeText("High-density QuadQR", {
+  cellEncoding: "triangle16"
+});
+```
+
+`rgbw` remains the library default so existing callers are not silently moved to an experimental physical format.
+
+## 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, cellEncoding: "triangle16" })` 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 Triangle16 as a stable format. 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/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.3.0",
+  "description": "QuadQR: experimental RGBW matrix code with optional experimental High Density Mode, Spectrum ECC, browser/Node scanning, compression, signing, diagnostics, stress testing, and 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"
   ],
@@ -81,6 +82,8 @@
     "qr",
     "rgb",
     "rgbw",
+    "high-density",
+    "triangle16",
     "matrix-code",
     "barcode",
     "reed-solomon",
@@ -89,7 +92,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, options?: { highDensity?: boolean }): Record<string, number | string | null>;
+export function calculateCapacityPlan(options?: { payload?: string | Uint8Array; payloadBytes?: number; ecc?: EccLevel; highDensity?: boolean; compression?: "none" | "auto" | "lz"; signed?: boolean; keyId?: string; embedPublicKey?: boolean }): Record<string, unknown>;
+export function buildCapacityComparison(options?: { ecc?: EccLevel; highDensity?: boolean; 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>;

package/types/index.d.ts

@@ -1,5 +1,7 @@
 export type EccLevel = "L" | "M" | "Q" | "H";
 export type RenderStyle = "classic" | "depth" | "soft" | "inset";
+export type RenderMode = "screen" | "print";
+export type CompressionMode = "none" | "auto" | "lz";
 export type SecurityMode = "password" | "raw-key";
 
 export interface Palette {
@@ -11,12 +13,30 @@ export interface Palette {
 }
 
 export interface EncodeOptions {
-  version?: number;
+  version?: number | "auto";
+  minVersion?: number;
+  maxVersion?: number;
   ecc?: EccLevel;
+  /** Enable the experimental High Density Mode. Default: false. Uses Triangle16 payload cells at 4 raw bits/body cell. */
+  highDensity?: boolean;
   maskId?: number;
   text?: boolean;
+  compression?: CompressionMode;
 }
 
+export interface SigningOptions {
+  /** Private Ed25519 key used to create the signature. Never embed or distribute it. */
+  privateKey: CryptoKey | Uint8Array | ArrayBuffer;
+  /** Optional compact identifier stored with the signature so a verifier can select a trusted public key. */
+  keyId?: string;
+  /** Optional public key used only when embedPublicKey is explicitly enabled. */
+  publicKey?: CryptoKey | Uint8Array | ArrayBuffer;
+  /** Embed the public key for self-contained integrity checks. Default: false. */
+  embedPublicKey?: boolean;
+}
+
+export interface SignedEncodeOptions extends EncodeOptions, SigningOptions {}
+
 export interface PasswordSecurity {
   mode: "password";
   password: string;
@@ -32,6 +52,7 @@ export interface RawKeySecurity {
 
 export interface SecureEncodeOptions extends EncodeOptions {
   security: PasswordSecurity | RawKeySecurity;
+  signing?: SigningOptions;
 }
 
 export interface QuadQRCode {
@@ -40,9 +61,15 @@ export interface QuadQRCode {
   size: number;
   formatVersion: number;
   eccLevel: EccLevel;
+  highDensity?: boolean;
+  bitsPerDataCell?: 2 | 4;
+  statesPerDataCell?: 4 | 16;
   payloadBytes: number;
   capacityBytes: number;
   secure?: boolean;
+  compressed?: boolean;
+  compression?: "none" | "lz";
+  signed?: boolean;
   security?: SecurityMetadata | null;
   [key: string]: unknown;
 }
@@ -61,6 +88,22 @@ export interface SecurityMetadata {
   [key: string]: unknown;
 }
 
+export interface ScanDiagnostics {
+  confidence: number;
+  cellConfidence: number;
+  structureConfidence: number;
+  geometryConfidence: number;
+  calibrationConfidence: number;
+  eccUtilization: number;
+  correctedErrors: number;
+  erasureSymbols: number;
+  stages?: Record<string, boolean>;
+  failedStage?: string | null;
+  geometryCandidates?: unknown[];
+  sampled?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+
 export interface DecodeResult {
   payload: Uint8Array;
   text: string | null;
@@ -68,11 +111,32 @@ export interface DecodeResult {
   size: number;
   formatVersion: number;
   eccLevel: EccLevel;
+  highDensity?: boolean;
+  bitsPerDataCell?: 2 | 4;
+  statesPerDataCell?: 4 | 16;
   secure: boolean;
   requiresDecryption?: boolean;
   decrypted?: boolean;
   security?: SecurityMetadata | null;
   encryptedPayload?: Uint8Array;
+  protectedPayload?: Uint8Array;
+  compressed?: boolean;
+  compression?: "none" | "lz";
+  signed?: boolean;
+  /** Legacy v1 signer label, if decoding an older signed symbol. */
+  signer?: string | null;
+  signingKeyId?: string | null;
+  hasEmbeddedPublicKey?: boolean;
+  signatureVerified?: boolean | null;
+  signatureTrusted?: boolean | null;
+  signatureTrustSource?: "external" | "embedded" | null;
+  confidence?: number;
+  geometryConfidence?: number;
+  calibrationConfidence?: number;
+  structureConfidence?: number;
+  correctedErrors?: number;
+  eccUtilization?: number;
+  diagnostics?: ScanDiagnostics;
   [key: string]: unknown;
 }
 
@@ -82,6 +146,21 @@ export interface ImageDataLike {
   data: Uint8ClampedArray | Uint8Array;
 }
 
+export interface LogoRenderOptions {
+  /** Loaded CanvasImageSource in canvas rendering, ImageDataLike in pixel rendering, or URL/data URL in SVG rendering. */
+  source: CanvasImageSource | ImageDataLike | string;
+  /** Logo width/height as a fraction of the symbol area. Clamped to 0.05..0.30. Default: 0.18. */
+  size?: number | "auto";
+  /** Clear the modules behind the logo with a solid background before drawing it. */
+  clearBackground?: boolean;
+  /** Background padding around the logo in modules. Default: 0.65. */
+  padding?: number;
+  /** Rounded background corner radius in modules. Default: 0.8. */
+  radius?: number;
+  /** Background color used when clearBackground is enabled. Default: palette white. */
+  backgroundColor?: string;
+}
+
 export interface CameraFinderDiagnostic {
   x: number;
   y: number;
@@ -128,14 +207,30 @@ export interface CameraDiagnosticEvent {
 }
 
 export interface RenderOptions {
+  /** Exact square output size in pixels. If neither imageSize nor moduleSize is supplied, defaults to 720. */
+  imageSize?: number;
+  /** Legacy/low-level pixels per module sizing. Used when imageSize is not supplied. */
   moduleSize?: number;
   quietZone?: number;
   palette?: Palette;
   style?: RenderStyle;
+  /** Screen defaults or print-safe palette/quiet-zone/classic-style behavior. */
+  mode?: RenderMode;
+  renderMode?: RenderMode;
+  allowStyledPrint?: boolean;
+  allowUnsafePrintQuietZone?: boolean;
+  logo?: CanvasImageSource | ImageDataLike | string | LogoRenderOptions;
+  logoSize?: number;
+  logoClearBackground?: boolean;
+  logoPadding?: number;
+  logoRadius?: number;
+  logoBackgroundColor?: string;
   [key: string]: unknown;
 }
 
 export interface ScanOptions {
+  debug?: boolean;
+  debugMatrices?: boolean;
   minVersion?: number;
   maxVersion?: number;
   perspective?: boolean;
@@ -143,12 +238,27 @@ export interface ScanOptions {
   maxDimension?: number;
   sampleRadius?: number;
   robustSampleRadius?: number;
+  /** Disable automatic High Density Mode dual-region sampling. Default: enabled. */
+  highDensitySampling?: boolean;
+  /** Position of the two High Density Mode samples inside each module. Default: 0.28. */
+  highDensitySampleInset?: number;
+  /** Radius used around each High Density Mode sample point. */
+  highDensitySampleRadius?: number;
+  /** Retry failed perspective scans with finer alignment localization. Default: true. */
+  preciseAlignmentRecovery?: boolean;
   adaptiveSampling?: boolean;
   spatialColorNormalization?: boolean;
   structureTolerance?: number;
   maxErasureConfidence?: number;
   geometryRefinement?: boolean;
   finderRecovery?: boolean;
+  /** Refine a valid projective solution with reliable secondary alignment markers on dense versions. */
+  alignmentRefinement?: boolean;
+  alignmentRefinePatternThreshold?: number;
+  alignmentRefineMaxPoints?: number;
+  alignmentRefineMaxDisplacement?: number;
+  alignmentRefineCandidateMargin?: number;
+  alignmentRefineSkipScore?: number;
   finderAutoColorBlackClip?: number;
   finderAutoColorWhiteClip?: number;
   finderAutoColorHighlightPercentile?: number;
@@ -213,6 +323,11 @@ export interface CameraScanOptions extends ScanOptions {
   cameraAutoColorTargetSamples?: number;
   cameraAutoEnhanceEvery?: number;
   cameraFinderRecoveryEvery?: number;
+  /** Retry a dense/partial geometry frame at higher resolution after at least two finders are detected. */
+  cameraHighResolutionRecovery?: boolean;
+  cameraHighResolutionMaxDimension?: number;
+  cameraHighResolutionEvery?: number;
+  cameraHighResolutionMinFinders?: number;
   constraints?: MediaStreamConstraints;
   onResult?: (result: DecodeResult, frame?: CameraFrameMeta | null) => void | Promise<void>;
   onDecode?: (result: DecodeResult, frame?: CameraFrameMeta | null) => void | Promise<void>;
@@ -224,6 +339,10 @@ export const FORMAT_VERSION: number;
 export const MIN_VERSION: number;
 export const MAX_VERSION: number;
 export const DEFAULT_ECC_LEVEL: EccLevel;
+export const RENDER_MODES: Readonly<{ SCREEN: "screen"; PRINT: "print" }>;
+export const PRINT_PALETTE: Readonly<Required<Palette>>;
+export const COMPRESSION_MODES: Readonly<Record<string, CompressionMode>>;
+export const SIGNATURE_ALGORITHMS: Readonly<{ ED25519: "Ed25519" }>;
 export const CELL: Readonly<{ BLACK: -1; RED: 0; GREEN: 1; BLUE: 2; WHITE: 3 }>;
 export const DEFAULT_PALETTE: Readonly<Required<Palette>>;
 export const RENDER_STYLES: Readonly<Record<string, RenderStyle>>;
@@ -235,19 +354,42 @@ export const DEFAULT_PBKDF2_ITERATIONS: number;
 
 export function encodeText(text: string, options?: EncodeOptions): QuadQRCode;
 export function encodeBytes(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options?: EncodeOptions): QuadQRCode;
+export function encodeUint8Array(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options?: EncodeOptions): QuadQRCode;
+export function encodeSignedText(text: string, options: SignedEncodeOptions): Promise<QuadQRCode>;
+export function encodeSignedBytes(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options: SignedEncodeOptions): Promise<QuadQRCode>;
 export function encodeSecureText(text: string, options: SecureEncodeOptions): Promise<QuadQRCode>;
 export function encodeSecureBytes(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options: SecureEncodeOptions): Promise<QuadQRCode>;
+export function compressPayload(input: Uint8Array | ArrayBuffer | ArrayLike<number>): Uint8Array;
+export function decompressPayload(input: Uint8Array | ArrayBuffer | ArrayLike<number>, expectedLength?: number | null): Uint8Array;
+export function deriveSigningKeyId(publicKey: CryptoKey | Uint8Array | ArrayBuffer, bytes?: number): Promise<string>;
+export function generateSigningKeyPair(): Promise<{ privateKey: CryptoKey; publicKey: CryptoKey; privateKeyPkcs8: Uint8Array; publicKeyBytes: Uint8Array; keyId: string; algorithm: "Ed25519" }>;
 export function decodeMatrix(matrix: number[][], options?: Record<string, unknown>): DecodeResult;
+export function decodeUint8Array(matrix: number[][], options?: Record<string, unknown>): Uint8Array;
 export function decryptDecoded(result: DecodeResult, credentials: { password: string } | { key: string | Uint8Array | ArrayBuffer }): Promise<DecodeResult>;
+export function verifyDecodedSignature(result: DecodeResult, options?: {
+  publicKey?: CryptoKey | Uint8Array | ArrayBuffer;
+  trustedPublicKey?: CryptoKey | Uint8Array | ArrayBuffer;
+  trustedKeys?: Record<string, CryptoKey | Uint8Array | ArrayBuffer> | Map<string, CryptoKey | Uint8Array | ArrayBuffer>;
+  allowEmbeddedKey?: boolean;
+}): Promise<DecodeResult>;
 export function renderToCanvas(codeOrMatrix: QuadQRCode | number[][], canvas: HTMLCanvasElement, options?: RenderOptions): HTMLCanvasElement;
 export function renderToImageData(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions): ImageDataLike;
+export function renderToSVG(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions): string;
+export function estimateSafeLogoSize(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions & { ecc?: EccLevel; utilization?: number }): number;
+export function findMaxSafeLogoSize(code: QuadQRCode, options: RenderOptions & { minSize?: number; maxSize?: number; iterations?: number }): { safeSize: number; testedMax: number; iterations: number; empirical: boolean };
+export function getPrintGuidance(codeOrMatrix: QuadQRCode | number[][], options?: { quietZone?: number; physicalSizeMm?: number; dpi?: number; minimumModuleMm?: number }): Record<string, unknown>;
 export function scanImageData(imageData: ImageDataLike, options?: ScanOptions): DecodeResult;
+export function debugScanImageData(imageData: ImageDataLike, options?: ScanOptions): { ok: boolean; result?: DecodeResult; error?: string; debug?: ScanDiagnostics | null };
 export function scanFile(file: Blob, options?: ScanOptions): Promise<DecodeResult>;
 export function scanVideoFrame(video: HTMLVideoElement, options?: ScanOptions): DecodeResult;
 export function startCameraScanner(video: HTMLVideoElement, options?: CameraScanOptions): Promise<{ stop(): void; scanNow(): DecodeResult; stream: MediaStream; video: HTMLVideoElement }>;
+export function applyStressDistortion(imageData: ImageDataLike, type: string, severity?: number, options?: Record<string, unknown>): ImageDataLike;
+export const STRESS_PROFILES: readonly Readonly<{ id: string; label: string; type: string; severity: number; weight: number }>[];
+export function runImageStressTest(imageData: ImageDataLike, expected?: { version?: number; crc32?: number }, options?: Record<string, unknown>): Record<string, unknown>;
+export function assessScanability(code: QuadQRCode, renderOptions?: RenderOptions, options?: Record<string, unknown>): Record<string, unknown>;
 export function rectifyDetectedCode(imageData: ImageDataLike, options?: Record<string, unknown>): ImageDataLike;
 export function rotateMatrix(matrix: number[][], quarterTurns?: number): number[][];
-export function getVersionInfo(version: number, options?: { ecc?: EccLevel }): Record<string, unknown>;
+export function getVersionInfo(version: number, options?: { ecc?: EccLevel; highDensity?: boolean }): Record<string, unknown>;
 export function crc32(bytes: Uint8Array): number;
 export function installCrc32Accelerator(accelerator?: ((bytes: Uint8Array) => number) | null): void;
 export function generateRaw256Key(): Uint8Array;

package/types/node.d.ts

@@ -5,5 +5,7 @@ export function decodePNG(input: Uint8Array | ArrayBuffer): ImageDataLike;
 export function encodePNG(imageData: ImageDataLike, options?: { compressionLevel?: number }): Buffer;
 export function toPNG(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions & { compressionLevel?: number }): Buffer;
 export function savePNG(codeOrMatrix: QuadQRCode | number[][], filename: string | URL, options?: RenderOptions & { compressionLevel?: number }): Promise<{ filename: string | URL; bytes: number }>;
+export function toSVG(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions): string;
+export function saveSVG(codeOrMatrix: QuadQRCode | number[][], filename: string | URL, options?: RenderOptions): Promise<{ filename: string | URL; bytes: number }>;
 export function scanBuffer(input: Uint8Array | ArrayBuffer, options?: ScanOptions): Promise<DecodeResult>;
 export function scanFile(filename: string | URL, options?: ScanOptions): Promise<DecodeResult>;