quadqr-js 0.7.0

package/docs/API.md

@@ -0,0 +1,188 @@
+# API Reference
+
+## Core encoding
+
+### `encodeText(text, options?)`
+
+Synchronously encodes UTF-8 text.
+
+```js
+const code = encodeText("Hello", {
+  ecc: "M",
+  version: 5
+});
+```
+
+If `version` is omitted, QuadQR selects the smallest version that fits.
+
+### `encodeBytes(bytes, options?)`
+
+Encodes arbitrary bytes.
+
+```js
+const code = encodeBytes(new Uint8Array([1, 2, 3, 4]), { ecc: "Q" });
+```
+
+## Secure encoding
+
+### `encodeSecureText(text, options)`
+
+Encrypts text using Secure Payload v1 and then encodes the encrypted envelope.
+
+```js
+const code = await encodeSecureText("secret", {
+  security: {
+    mode: "password",
+    password: "example-password"
+  }
+});
+```
+
+### `encodeSecureBytes(bytes, options)`
+
+The byte-oriented equivalent of `encodeSecureText`.
+
+### `decryptDecoded(result, credentials)`
+
+Decrypts a result returned by `decodeMatrix`, `scanImageData`, browser scanning, or Node scanning.
+
+```js
+const result = await decryptDecoded(locked, { password: "example-password" });
+```
+
+For raw-key mode:
+
+```js
+const result = await decryptDecoded(locked, { key: raw256BitKey });
+```
+
+## Decoding
+
+### `decodeMatrix(matrix, options?)`
+
+Decodes an already sampled QuadQR matrix.
+
+Secure results are intentionally returned in a locked state:
+
+```js
+{
+  secure: true,
+  requiresDecryption: true,
+  payload: Uint8Array(...),
+  security: {
+    mode: "password",
+    algorithm: "AES-256-GCM"
+  }
+}
+```
+
+## Rendering
+
+### `renderToCanvas(codeOrMatrix, canvas, options?)`
+
+Browser canvas renderer.
+
+### `renderToImageData(codeOrMatrix, options?)`
+
+Runtime-neutral RGBA renderer. The result has:
+
+```js
+{
+  width,
+  height,
+  data: Uint8ClampedArray
+}
+```
+
+Useful render options include:
+
+- `moduleSize`
+- `quietZone`
+- `style`: `classic`, `depth`, `soft`, or `inset`
+- custom palette values
+
+## Image scanning
+
+### `scanImageData(imageData, options?)`
+
+Runtime-neutral scanner that accepts RGBA pixels.
+
+### Browser `scanFile(file, options?)`
+
+Available from `quadqr` and `quadqr/browser`. Accepts a browser `File`/`Blob`.
+
+### `scanVideoFrame(video, options?)`
+
+Scans the current browser video frame.
+
+### `startCameraScanner(video, options?)`
+
+Starts a live camera scanner and repeatedly scans frames.
+
+## Node helpers
+
+Import from `quadqr/node`.
+
+### `toPNG(codeOrMatrix, options?)`
+
+Returns a Node `Buffer` containing a PNG.
+
+### `savePNG(codeOrMatrix, filename, options?)`
+
+Writes a PNG file.
+
+### `scanBuffer(buffer, options?)`
+
+PNG works with no dependencies. Other image formats can use the consuming application's optional `sharp` installation.
+
+### Node `scanFile(filename, options?)`
+
+Reads an image path and scans it.
+
+### `decodePNG(buffer)` / `encodePNG(imageData)`
+
+Dependency-free PNG pixel helpers.
+
+## Security utilities
+
+- `generateRaw256Key()`
+- `normalizeRaw256Key(key)`
+- `bytesToHex(bytes)`
+- `SECURITY_MODES`
+- `SECURITY_ALGORITHMS`
+- `DEFAULT_PBKDF2_ITERATIONS`
+
+## WASM
+
+### `initWasm(options?)`
+
+Loads the bundled optional WASM accelerator and installs it into the normal codec path.
+
+```js
+import { initWasm } from "quadqr";
+
+await initWasm();
+```
+
+### `getWasmState()`
+
+Returns the active WASM state or `null`.
+
+### `disableWasm()`
+
+Returns the codec to its JavaScript fallback.
+
+## Version/capacity utilities
+
+### `getVersionInfo(version, options?)`
+
+Returns matrix and payload information for a specific QuadQR version/ECC profile.
+
+## Benchmark entry
+
+```js
+import {
+  buildCapacityComparison,
+  benchmarkCodec
+} from "quadqr/benchmark";
+```

package/docs/BROWSER_CDN.md

@@ -0,0 +1,83 @@
+# Browser and CDN Usage
+
+## ESM with a bundler
+
+```js
+import {
+  encodeText,
+  renderToCanvas,
+  scanFile,
+  startCameraScanner
+} from "quadqr/browser";
+```
+
+The normal `quadqr` entry also works in modern browser bundlers.
+
+## Classic script tag
+
+QuadQR publishes a global build that exposes `window.QuadQR` / `globalThis.QuadQR`.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/quadqr@0.7.0/dist/quadqr.min.js"></script>
+```
+
+Then:
+
+```html
+<script>
+  const code = QuadQR.encodeText("Hello CDN");
+  QuadQR.renderToCanvas(code, document.querySelector("#qr"), {
+    moduleSize: 12,
+    quietZone: 4
+  });
+</script>
+```
+
+## unpkg
+
+```html
+<script src="https://unpkg.com/quadqr@0.7.0/dist/quadqr.min.js"></script>
+```
+
+## CDN ESM
+
+You may also load the ESM file directly:
+
+```html
+<script type="module">
+  import { encodeText } from "https://cdn.jsdelivr.net/npm/quadqr@0.7.0/dist/browser.js";
+  console.log(encodeText("ES module CDN"));
+</script>
+```
+
+## WASM from a CDN
+
+The classic global build remembers its own script URL. Calling:
+
+```js
+await QuadQR.initWasm();
+```
+
+loads the sibling asset:
+
+```text
+dist/wasm/quadqr-core.wasm
+```
+
+from the same package/version URL.
+
+You can override the location:
+
+```js
+await QuadQR.initWasm({
+  url: "https://example.com/assets/quadqr-core.wasm"
+});
+```
+
+## Camera requirements
+
+Live camera access requires a secure browser context, normally HTTPS or localhost.
+
+## Production recommendation
+
+Pin a concrete version such as `@0.7.0` instead of using an unversioned CDN URL. This prevents a future package release from changing a production site unexpectedly.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,91 @@
+# Getting Started
+
+## Install from npm
+
+```bash
+npm install quadqr
+```
+
+QuadQR 0.7.x targets Node.js 20.19 or newer for the full ESM/CommonJS distribution behavior.
+
+## Generate and decode a matrix
+
+```js
+import { encodeText, decodeMatrix } from "quadqr";
+
+const code = encodeText("Hello from QuadQR", { ecc: "M" });
+const decoded = decodeMatrix(code.matrix);
+
+console.log(decoded.text);
+```
+
+## Secure password mode
+
+```js
+import { encodeSecureText, decodeMatrix, decryptDecoded } from "quadqr";
+
+const code = await encodeSecureText("Private payload", {
+  ecc: "M",
+  security: {
+    mode: "password",
+    password: "correct horse battery staple"
+  }
+});
+
+const locked = decodeMatrix(code.matrix);
+const unlocked = await decryptDecoded(locked, {
+  password: "correct horse battery staple"
+});
+
+console.log(unlocked.text);
+```
+
+## Raw 256-bit key mode
+
+```js
+import {
+  bytesToHex,
+  encodeSecureText,
+  generateRaw256Key
+} from "quadqr";
+
+const key = generateRaw256Key();
+console.log(bytesToHex(key));
+
+const code = await encodeSecureText("Machine-readable secret", {
+  security: {
+    mode: "raw-key",
+    key
+  }
+});
+```
+
+Never place the raw encryption key inside the same QuadQR payload.
+
+## Node.js PNG
+
+```js
+import { encodeText } from "quadqr";
+import { savePNG, scanFile } from "quadqr/node";
+
+const code = encodeText("Generated on Node.js");
+await savePNG(code, "quadqr.png", {
+  moduleSize: 12,
+  quietZone: 4
+});
+
+const result = await scanFile("quadqr.png");
+console.log(result.text);
+```
+
+## Browser script tag
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/quadqr@0.7.0/dist/quadqr.min.js"></script>
+<script>
+  const code = QuadQR.encodeText("No build step");
+  console.log(code.version, code.matrix);
+</script>
+```
+
+For production sites, pin the exact package version in the CDN URL.

package/docs/NODE.md

@@ -0,0 +1,92 @@
+# Node.js
+
+QuadQR uses the same matrix codec and image scanner in Node.js and the browser. The `quadqr/node` entry only adds Node-specific file and PNG helpers.
+
+## Requirements
+
+The package targets Node.js 20.19 or newer.
+
+## ESM
+
+```js
+import { encodeText } from "quadqr";
+import { savePNG, scanFile } from "quadqr/node";
+```
+
+## CommonJS
+
+On supported modern Node versions:
+
+```js
+const QuadQR = require("quadqr");
+const QuadQRNode = require("quadqr/node");
+```
+
+## Generate PNG
+
+```js
+const code = QuadQR.encodeText("Server generated");
+await QuadQRNode.savePNG(code, "output.png", {
+  moduleSize: 12,
+  quietZone: 4
+});
+```
+
+`toPNG()` returns a `Buffer` instead of writing it:
+
+```js
+const png = QuadQRNode.toPNG(code);
+```
+
+This is useful for HTTP responses, object storage, email attachments, or database/blob workflows.
+
+## Scan PNG
+
+```js
+const result = await QuadQRNode.scanFile("output.png");
+console.log(result.text);
+```
+
+Or scan an in-memory buffer:
+
+```js
+const result = await QuadQRNode.scanBuffer(pngBuffer);
+```
+
+PNG decoding is dependency-free and supports normal non-interlaced 8-bit RGB/RGBA PNGs plus indexed PNGs.
+
+## JPEG, WebP, and AVIF
+
+QuadQR does not force a native image dependency on every user. If your application already uses `sharp`, `scanBuffer()` / `scanFile()` can use it for formats other than PNG.
+
+```bash
+npm install sharp
+```
+
+If `sharp` is not installed, pass decoded RGBA pixels directly to `scanImageData()` or use PNG input.
+
+## Secure Node workflow
+
+```js
+import {
+  decryptDecoded,
+  encodeSecureText
+} from "quadqr";
+import { savePNG, scanFile } from "quadqr/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);
+```

package/docs/PUBLISHING.md

@@ -0,0 +1,115 @@
+# Publishing QuadQR to npm
+
+This repository is already configured as a public npm package named `quadqr` at version `0.7.0`.
+
+Before the first publish, confirm that the package name is available. If it is already owned by somebody else, use a scoped name such as `@akanshsirohi/quadqr` and update the CDN examples accordingly.
+
+## 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 name
+
+```bash
+npm view quadqr
+```
+
+If npm returns a package owned by somebody else, do not publish over it. Change `package.json` to a scoped name that you own.
+
+## 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
+
+For the current unscoped public package:
+
+```bash
+npm publish
+```
+
+For a scoped public package:
+
+```bash
+npm publish --access public
+```
+
+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
+```
+
+Then test ESM, Node PNG, and the CLI.
+
+```bash
+npx quadqr keygen
+npx quadqr encode "Hello from npm" -o hello.png
+npx quadqr decode hello.png
+```
+
+## 7. Verify CDN availability
+
+After npm and CDN caches update, test:
+
+```text
+https://cdn.jsdelivr.net/npm/quadqr@0.7.0/dist/quadqr.min.js
+https://unpkg.com/quadqr@0.7.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.

package/docs/README.md

@@ -0,0 +1,26 @@
+# 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 library adds Spectrum ECC, perspective-aware scanning, optional authenticated encryption, browser camera support, Node.js PNG support, a CDN/global build, and an optional prebuilt WebAssembly accelerator.
+
+## Documentation map
+
+- [Getting Started](./GETTING_STARTED.md)
+- [API Reference](./API.md)
+- [Browser and CDN](./BROWSER_CDN.md)
+- [Node.js](./NODE.md)
+- [Secure Payloads](./SECURITY.md)
+- [WASM](./WASM.md)
+- [Publishing to npm](./PUBLISHING.md)
+- [Wire Format](../FORMAT.md)
+
+## Package entry points
+
+| Entry | Purpose |
+| --- | --- |
+| `quadqr` | Runtime-neutral core API plus optional WASM loader |
+| `quadqr/browser` | Browser ESM entry |
+| `quadqr/node` | Node.js core plus PNG/file helpers |
+| `quadqr/benchmark` | Capacity and codec benchmark helpers |
+| `quadqr/quadqr.min.js` | Classic browser global bundle for CDNs |
+
+The package is designed so the matrix codec is shared across all runtimes. Browser and Node adapters only handle runtime-specific input/output.

package/docs/SECURITY.md

@@ -0,0 +1,78 @@
+# Secure Payloads
+
+QuadQR Secure Payload v1 is an optional layer above the matrix codec and Spectrum ECC.
+
+```text
+plaintext
+  -> encryption/authentication
+  -> secure envelope
+  -> QuadQR framing
+  -> Spectrum ECC
+  -> RGBW matrix
+```
+
+Scanning and error correction therefore remain independent from encryption.
+
+## Password mode
+
+Password mode uses:
+
+- PBKDF2-HMAC-SHA-256
+- random 16-byte salt
+- configurable iteration count, default 600,000
+- AES-256-GCM
+- random 12-byte nonce
+- authenticated metadata
+
+```js
+const code = await encodeSecureText("private", {
+  security: {
+    mode: "password",
+    password: "long unique password"
+  }
+});
+```
+
+The password is never stored in the QuadQR symbol.
+
+## Raw 256-bit key mode
+
+Raw-key mode accepts exactly 32 random bytes.
+
+```js
+const key = generateRaw256Key();
+
+const code = await encodeSecureText("machine secret", {
+  security: {
+    mode: "raw-key",
+    key
+  }
+});
+```
+
+By default QuadQR stores only a short SHA-256 fingerprint/key ID so an application can identify the required key without embedding the actual secret.
+
+## Decryption
+
+A secure scan stays locked:
+
+```js
+const locked = scanImageData(imageData);
+
+if (locked.secure) {
+  const unlocked = await decryptDecoded(locked, {
+    password: "long unique password"
+  });
+}
+```
+
+AES-GCM authentication rejects an incorrect password/key or modified ciphertext.
+
+## Threat model notes
+
+- Secure Payload protects payload confidentiality and integrity.
+- It does not hide the fact that a QuadQR symbol exists.
+- Key IDs are routing hints, not secrets.
+- A photographed code can still be copied, so encryption alone is not anti-replay protection.
+- Applications needing ticket/access anti-replay should combine QuadQR with server-side nonce/state validation or signed short-lived tokens.
+- Do not hard-code long-lived raw keys in public client-side JavaScript if those keys are meant to remain secret.

package/docs/WASM.md

@@ -0,0 +1,36 @@
+# WebAssembly
+
+QuadQR ships a small precompiled WebAssembly module at:
+
+```text
+dist/wasm/quadqr-core.wasm
+```
+
+The normal JavaScript codec does not require it. This is intentional: installation, browser loading, serverless execution, and restricted environments should still work when WASM is unavailable.
+
+## Enable it
+
+```js
+import { initWasm } from "quadqr";
+
+const state = await initWasm();
+console.log(state);
+```
+
+Current 0.7.x acceleration covers CRC-32, which is used by QuadQR framing integrity checks. Once initialized, encode/decode calls automatically use the installed synchronous accelerator.
+
+## Why start small?
+
+QuadQR scanning and Spectrum ECC are still evolving. Keeping the first WASM ABI narrow lets the library ship a stable prebuilt binary without forcing the matrix format to depend on a specific compiler/runtime implementation.
+
+Future profiling can move heavier hot paths, such as image classification or selected ECC operations, behind the same optional acceleration layer without changing the public QuadQR wire format.
+
+## Disable
+
+```js
+import { disableWasm } from "quadqr";
+
+disableWasm();
+```
+
+The JavaScript fallback is restored immediately.