quadqr-js 1.0.0 → 1.0.2

package/docs/WASM.md

@@ -1,67 +1,67 @@
-# WebAssembly
-
-QuadQR includes an optional prebuilt WebAssembly module at:
-
-```text
-dist/wasm/quadqr-core.wasm
-```
-
-The normal JavaScript implementation works without WASM. Applications can opt in when they want to use the bundled accelerator.
-
-## Enable WASM
-
-```js
-import { initWasm } from "quadqr-js";
-
-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.
-
-## Check the current state
-
-```js
-import { getWasmState } from "quadqr-js";
-
-console.log(getWasmState());
-```
-
-Before initialization, or after disabling WASM, the result is `null`.
-
-## Disable WASM
-
-```js
-import { disableWasm } from "quadqr-js";
-
-disableWasm();
-```
-
-QuadQR immediately returns to the JavaScript implementation.
-
-## Custom WASM URL
-
-Browser and CDN applications can override the asset location:
-
-```js
-await initWasm({
-  url: "https://example.com/assets/quadqr-core.wasm"
-});
-```
-
-You can also provide WASM bytes directly through the `bytes` option.
-
-## CDN behavior
-
-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.0/dist/quadqr.min.js"></script>
-<script>
-  await QuadQR.initWasm();
-</script>
-```
-
-## Fallback behavior
-
-WASM is never required for the QuadQR wire format. If your environment cannot load WebAssembly, simply do not call `initWasm()` and continue using the JavaScript implementation.
+# WebAssembly
+
+QuadQR includes an optional prebuilt WebAssembly module at:
+
+```text
+dist/wasm/quadqr-core.wasm
+```
+
+The normal JavaScript implementation works without WASM. Applications can opt in when they want to use the bundled accelerator.
+
+## Enable WASM
+
+```js
+import { initWasm } from "quadqr-js";
+
+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.
+
+## Check the current state
+
+```js
+import { getWasmState } from "quadqr-js";
+
+console.log(getWasmState());
+```
+
+Before initialization, or after disabling WASM, the result is `null`.
+
+## Disable WASM
+
+```js
+import { disableWasm } from "quadqr-js";
+
+disableWasm();
+```
+
+QuadQR immediately returns to the JavaScript implementation.
+
+## Custom WASM URL
+
+Browser and CDN applications can override the asset location:
+
+```js
+await initWasm({
+  url: "https://example.com/assets/quadqr-core.wasm"
+});
+```
+
+You can also provide WASM bytes directly through the `bytes` option.
+
+## CDN behavior
+
+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>
+  await QuadQR.initWasm();
+</script>
+```
+
+## Fallback behavior
+
+WASM is never required for the QuadQR wire format. If your environment cannot load WebAssembly, simply do not call `initWasm()` and continue using the JavaScript implementation.

package/package.json

@@ -1,95 +1,95 @@
-{
-  "name": "quadqr-js",
-  "version": "1.0.0",
-  "description": "QuadQR: experimental four-state RGBW matrix code with Spectrum ECC, browser/Node scanning, CDN builds, and optional AES-256-GCM secure payloads.",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "browser": "./dist/browser.js",
-  "types": "./types/index.d.ts",
-  "unpkg": "./dist/quadqr.min.js",
-  "jsdelivr": "./dist/quadqr.min.js",
-  "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "default": "./dist/index.js"
-    },
-    "./browser": {
-      "types": "./types/index.d.ts",
-      "import": "./dist/browser.js",
-      "default": "./dist/browser.js"
-    },
-    "./node": {
-      "types": "./types/node.d.ts",
-      "import": "./dist/node.js",
-      "require": "./dist/node.cjs",
-      "default": "./dist/node.js"
-    },
-    "./benchmark": {
-      "types": "./types/benchmark.d.ts",
-      "import": "./dist/benchmark.js",
-      "require": "./dist/benchmark.cjs",
-      "default": "./dist/benchmark.js"
-    },
-    "./quadqr.js": "./dist/quadqr.js",
-    "./quadqr.min.js": "./dist/quadqr.min.js",
-    "./wasm/quadqr-core.wasm": "./dist/wasm/quadqr-core.wasm",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "types",
-    "bin",
-    "docs",
-    "FORMAT.md",
-    "README.md",
-    "LICENSE"
-  ],
-  "bin": {
-    "quadqr": "./bin/quadqr.js"
-  },
-  "scripts": {
-    "build": "node scripts/build.js",
-    "start": "node scripts/serve.js",
-    "demo": "node scripts/serve.js",
-    "docs": "node scripts/serve.js --docs",
-    "test": "node tests/self-test.js && node tests/package-test.js",
-    "benchmark": "node scripts/benchmark.js",
-    "pack:check": "npm run build && npm pack --dry-run",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "engines": {
-    "node": ">=20.19"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/akanshsirohi/QuadQR.git"
-  },
-  "bugs": {
-    "url": "https://github.com/akanshsirohi/QuadQR/issues"
-  },
-  "homepage": "https://github.com/akanshsirohi/QuadQR#readme",
-  "author": "Akansh Sirohi",
-  "license": "AGPL-3.0-only",
-  "keywords": [
-    "quadqr",
-    "qr",
-    "rgb",
-    "rgbw",
-    "matrix-code",
-    "barcode",
-    "reed-solomon",
-    "ecc",
-    "scanner",
-    "camera-scanner",
-    "encryption",
-    "aes-gcm",
-    "wasm"
-  ],
-  "sideEffects": false
-}
+{
+  "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.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "browser": "./dist/browser.js",
+  "types": "./types/index.d.ts",
+  "unpkg": "./dist/quadqr.min.js",
+  "jsdelivr": "./dist/quadqr.min.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./types/node.d.ts",
+      "import": "./dist/node.js",
+      "require": "./dist/node.cjs",
+      "default": "./dist/node.js"
+    },
+    "./benchmark": {
+      "types": "./types/benchmark.d.ts",
+      "import": "./dist/benchmark.js",
+      "require": "./dist/benchmark.cjs",
+      "default": "./dist/benchmark.js"
+    },
+    "./quadqr.js": "./dist/quadqr.js",
+    "./quadqr.min.js": "./dist/quadqr.min.js",
+    "./wasm/quadqr-core.wasm": "./dist/wasm/quadqr-core.wasm",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "types",
+    "bin",
+    "docs",
+    "FORMAT.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "quadqr": "./bin/quadqr.js"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "start": "node scripts/serve.js",
+    "demo": "node scripts/serve.js",
+    "docs": "node scripts/serve.js --docs",
+    "test": "node tests/self-test.js && node tests/package-test.js",
+    "benchmark": "node scripts/benchmark.js",
+    "pack:check": "npm run build && npm pack --dry-run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akanshsirohi/QuadQR.git"
+  },
+  "bugs": {
+    "url": "https://github.com/akanshsirohi/QuadQR/issues"
+  },
+  "homepage": "https://github.com/akanshsirohi/QuadQR#readme",
+  "author": "Akansh Sirohi",
+  "license": "AGPL-3.0-only",
+  "keywords": [
+    "quadqr",
+    "qr",
+    "rgb",
+    "rgbw",
+    "matrix-code",
+    "barcode",
+    "reed-solomon",
+    "ecc",
+    "scanner",
+    "camera-scanner",
+    "encryption",
+    "aes-gcm",
+    "wasm"
+  ],
+  "sideEffects": false
+}

package/types/index.d.ts

@@ -82,6 +82,51 @@ export interface ImageDataLike {
   data: Uint8ClampedArray | Uint8Array;
 }
 
+export interface CameraFinderDiagnostic {
+  x: number;
+  y: number;
+  moduleSize: number;
+  confirmations?: number;
+  score?: number;
+}
+
+export interface CameraGeometryDiagnostic {
+  version: number;
+  size: number;
+  score: number;
+  estimatedSize?: number;
+  alignmentScore?: number;
+  alignmentGridScore?: number;
+  finders?: {
+    topLeft: CameraFinderDiagnostic;
+    topRight: CameraFinderDiagnostic;
+    bottomLeft: CameraFinderDiagnostic;
+  };
+  [key: string]: unknown;
+}
+
+export interface CameraDiagnosticEvent {
+  type: "camera-ready" | "frame" | "method" | "success" | string;
+  timestamp: number;
+  frame: number;
+  state?: "trying" | "miss" | "failed" | "decoded" | string;
+  method?: string;
+  message?: string;
+  elapsedMs?: number;
+  missStreak?: number;
+  scanWidth?: number;
+  scanHeight?: number;
+  frameWidth?: number;
+  frameHeight?: number;
+  scanRect?: { x: number; y: number; width: number; height: number };
+  finderCount?: number;
+  finders?: CameraFinderDiagnostic[];
+  finderMethod?: string | null;
+  finderPasses?: Array<{ method: string; finderCount: number; threshold?: number; geometryCount?: number }>;
+  geometry?: CameraGeometryDiagnostic | null;
+  [key: string]: unknown;
+}
+
 export interface RenderOptions {
   moduleSize?: number;
   quietZone?: number;
@@ -95,9 +140,86 @@ export interface ScanOptions {
   maxVersion?: number;
   perspective?: boolean;
   axisAlignedFallback?: boolean;
+  maxDimension?: number;
+  sampleRadius?: number;
+  robustSampleRadius?: number;
+  adaptiveSampling?: boolean;
+  spatialColorNormalization?: boolean;
+  structureTolerance?: number;
+  maxErasureConfidence?: number;
+  geometryRefinement?: boolean;
+  finderRecovery?: boolean;
+  finderAutoColorBlackClip?: number;
+  finderAutoColorWhiteClip?: number;
+  finderAutoColorHighlightPercentile?: number;
+  finderAutoColorOutputHighlight?: number;
+  finderAutoColorAnalysisInset?: number;
+  finderAutoColorAnalysisInsets?: number[];
+  finderAutoColorMinimumInputRange?: number;
+  finderAutoColorTargetSamples?: number;
+  autoEnhanceRecovery?: boolean;
+  autoEnhanceWhenNoGeometry?: boolean;
+  autoEnhanceBlackClip?: number;
+  autoEnhanceWhiteClip?: number;
+  autoEnhanceSaturation?: number;
+  autoEnhanceTargetSamples?: number;
+  fullFrameAutoEnhanceRecovery?: boolean;
+  rectifiedAutoEnhanceRecovery?: boolean;
+  rectifiedRecoveryModuleSize?: number;
+  rectifiedRecoveryRadiusRatio?: number;
+  rectifiedAutoEnhanceBlackClip?: number;
+  rectifiedAutoEnhanceWhiteClip?: number;
+  rectifiedAutoEnhanceSaturation?: number;
+  rectifiedAutoEnhanceHighlightFraction?: number;
+  videoCropMode?: "visible" | "full";
+  videoObjectFit?: string;
+  videoObjectPosition?: string;
+  videoCropInset?: number;
+  refinementOffset?: number;
+  refinementStructureThreshold?: number;
+  refinementDecodeThreshold?: number;
+  refinementDecodeCandidates?: number;
   [key: string]: unknown;
 }
 
+export interface CameraFrameMeta {
+  frame: number;
+  imageData: ImageDataLike;
+  scanWidth: number;
+  scanHeight: number;
+  sourceRect?: { x: number; y: number; width: number; height: number; cropped?: boolean } | null;
+  enhancedImageData?: ImageDataLike | null;
+  enhancedRect?: { x: number; y: number; width: number; height: number } | null;
+  enhancement?: { method?: string; cropInset?: number; analysisInset?: number; [key: string]: unknown } | null;
+  diagnostic?: Record<string, unknown> | null;
+}
+
+export interface CameraScanOptions extends ScanOptions {
+  scanInterval?: number;
+  stopOnResult?: boolean;
+  multiFrame?: boolean;
+  multiFrameWindow?: number;
+  multiFrameMinFrames?: number;
+  cameraAutoColorRecovery?: boolean;
+  cameraAutoColorEvery?: number;
+  cameraAutoColorBlackClip?: number;
+  cameraAutoColorWhiteClip?: number;
+  cameraAutoColorHighlightPercentile?: number;
+  cameraAutoColorOutputHighlight?: number;
+  cameraAutoColorAnalysisInset?: number;
+  cameraAutoColorAnalysisInsets?: number[];
+  cameraAutoColorCropInsets?: number[];
+  cameraAutoColorMinimumInputRange?: number;
+  cameraAutoColorTargetSamples?: number;
+  cameraAutoEnhanceEvery?: number;
+  cameraFinderRecoveryEvery?: number;
+  constraints?: MediaStreamConstraints;
+  onResult?: (result: DecodeResult, frame?: CameraFrameMeta | null) => void | Promise<void>;
+  onDecode?: (result: DecodeResult, frame?: CameraFrameMeta | null) => void | Promise<void>;
+  onScanMiss?: (error: Error) => void;
+  onDiagnostic?: (event: CameraDiagnosticEvent) => void;
+}
+
 export const FORMAT_VERSION: number;
 export const MIN_VERSION: number;
 export const MAX_VERSION: number;
@@ -122,7 +244,7 @@ export function renderToImageData(codeOrMatrix: QuadQRCode | number[][], options
 export function scanImageData(imageData: ImageDataLike, options?: ScanOptions): DecodeResult;
 export function scanFile(file: Blob, options?: ScanOptions): Promise<DecodeResult>;
 export function scanVideoFrame(video: HTMLVideoElement, options?: ScanOptions): DecodeResult;
-export function startCameraScanner(video: HTMLVideoElement, options?: ScanOptions & { onDecode?: (result: DecodeResult) => void | Promise<void>; onError?: (error: Error) => void; scanInterval?: number; constraints?: MediaStreamConstraints }): Promise<{ stop(): void; scanNow(): DecodeResult; stream: MediaStream }>;
+export function startCameraScanner(video: HTMLVideoElement, options?: CameraScanOptions): Promise<{ stop(): void; scanNow(): DecodeResult; stream: MediaStream; video: HTMLVideoElement }>;
 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>;

package/docs/PUBLISHING.md

@@ -1,109 +0,0 @@
-# Publishing QuadQR to npm
-
-QuadQR is published on npm as [`quadqr-js`](https://www.npmjs.com/package/quadqr-js). The repository package name is `quadqr-js`.
-
-The QuadQR project/brand, browser global (`QuadQR`), CLI executable (`quadqr`), and generated filenames remain unchanged. Only the npm package identifier is `quadqr-js`.
-
-## 1. Create/sign in to npm
-
-Create an account at https://www.npmjs.com/ and enable two-factor authentication.
-
-Then authenticate the CLI:
-
-```bash
-npm login
-```
-
-Check the active account:
-
-```bash
-npm whoami
-```
-
-## 2. Install repository dependencies
-
-QuadQR currently has no runtime dependencies, but run:
-
-```bash
-npm install
-```
-
-so your local package lock and npm metadata are synchronized.
-
-## 3. Verify the package metadata
-
-```bash
-npm view quadqr-js
-```
-
-Confirm the published package and current version before releasing an update.
-
-## 4. Run the full release checks
-
-```bash
-npm test
-npm run benchmark
-npm run pack:check
-```
-
-`pack:check` rebuilds `dist/` and displays exactly what npm will include.
-
-You can inspect the final tarball too:
-
-```bash
-npm pack
-```
-
-## 5. Publish
-
-The package is an unscoped public package and `publishConfig.access` is already set to `public`, so publish with:
-
-```bash
-npm publish
-```
-
-npm publishing requires an account that satisfies npm's current 2FA/authentication requirements.
-
-## 6. Verify installation from a clean directory
-
-```bash
-mkdir quadqr-consumer-test
-cd quadqr-consumer-test
-npm init -y
-npm install quadqr-js
-```
-
-Then test ESM, Node PNG, and the CLI.
-
-```bash
-npx quadqr-js keygen
-npx quadqr-js encode "Hello from npm" -o hello.png
-npx quadqr-js decode hello.png
-```
-
-## 7. Verify CDN availability
-
-After npm and CDN caches update, test:
-
-```text
-https://cdn.jsdelivr.net/npm/quadqr-js@1.0.0/dist/quadqr.min.js
-https://unpkg.com/quadqr-js@1.0.0/dist/quadqr.min.js
-```
-
-Then call `QuadQR.encodeText(...)` from a plain HTML page.
-
-## Releasing the next version
-
-Use semantic versioning:
-
-```bash
-npm version patch
-# or
-npm version minor
-# or
-npm version major
-```
-
-Then run the release checks again and publish.
-
-Never reuse an npm version that has already been published. Published package versions are immutable.