quadqr-js 0.7.0 → 1.0.0

package/docs/GETTING_STARTED.md

@@ -1,28 +1,87 @@
 # Getting Started
 
-## Install from npm
+## Install
 
 ```bash
-npm install quadqr
+npm install quadqr-js
 ```
 
-QuadQR 0.7.x targets Node.js 20.19 or newer for the full ESM/CommonJS distribution behavior.
+Node.js usage targets Node.js 20.19 or newer. Browser use works through a bundler, direct ESM, or the prebuilt CDN/global bundle.
 
-## Generate and decode a matrix
+## Encode and decode text
 
 ```js
-import { encodeText, decodeMatrix } from "quadqr";
+import { encodeText, decodeMatrix } from "quadqr-js";
 
-const code = encodeText("Hello from QuadQR", { ecc: "M" });
-const decoded = decodeMatrix(code.matrix);
+const code = encodeText("Hello from QuadQR", {
+  ecc: "M"
+});
+
+const result = decodeMatrix(code.matrix);
+console.log(result.text);
+```
+
+If no version is supplied, QuadQR automatically chooses the smallest version that fits the payload.
+
+## Render in the browser
+
+```js
+import {
+  encodeText,
+  renderToCanvas
+} from "quadqr-js/browser";
+
+const code = encodeText("Rendered in the browser");
+
+renderToCanvas(code, document.querySelector("#qr"), {
+  moduleSize: 12,
+  quietZone: 4,
+  style: "classic"
+});
+```
 
-console.log(decoded.text);
+Available presentation styles are `classic`, `depth`, `soft`, and `inset`. Styling does not change the encoded matrix.
+
+## Scan an uploaded image
+
+```js
+import { scanFile } from "quadqr-js/browser";
+
+const file = document.querySelector("#image").files[0];
+const result = await scanFile(file);
+
+console.log(result.text);
 ```
 
+## Scan from the camera
+
+```js
+import { startCameraScanner } from "quadqr-js/browser";
+
+let scanner;
+scanner = await startCameraScanner(
+  document.querySelector("#video"),
+  {
+    onDecode(result) {
+      console.log(result);
+      scanner.stop();
+    }
+  }
+);
+```
+
+Camera access requires HTTPS or localhost.
+
 ## Secure password mode
 
+Secure payloads are optional. Password mode is the simplest choice when a person will provide the secret during decryption.
+
 ```js
-import { encodeSecureText, decodeMatrix, decryptDecoded } from "quadqr";
+import {
+  encodeSecureText,
+  decodeMatrix,
+  decryptDecoded
+} from "quadqr-js";
 
 const code = await encodeSecureText("Private payload", {
   ecc: "M",
@@ -33,6 +92,7 @@ const code = await encodeSecureText("Private payload", {
 });
 
 const locked = decodeMatrix(code.matrix);
+
 const unlocked = await decryptDecoded(locked, {
   password: "correct horse battery staple"
 });
@@ -40,19 +100,21 @@ const unlocked = await decryptDecoded(locked, {
 console.log(unlocked.text);
 ```
 
-## Raw 256-bit key mode
+A secure image or camera scan follows the same pattern: scanning returns a locked result, then `decryptDecoded()` reveals plaintext only after successful authentication.
+
+## Secure raw-key mode
+
+Use raw-key mode when an application already manages its own cryptographic keys.
 
 ```js
 import {
-  bytesToHex,
   encodeSecureText,
   generateRaw256Key
-} from "quadqr";
+} from "quadqr-js";
 
 const key = generateRaw256Key();
-console.log(bytesToHex(key));
 
-const code = await encodeSecureText("Machine-readable secret", {
+const code = await encodeSecureText("Application-managed secret", {
   security: {
     mode: "raw-key",
     key
@@ -60,15 +122,16 @@ const code = await encodeSecureText("Machine-readable secret", {
 });
 ```
 
-Never place the raw encryption key inside the same QuadQR payload.
+The key must be exactly 32 bytes. Never embed the secret key inside the same QuadQR payload.
 
-## Node.js PNG
+## Generate and scan PNG files in Node.js
 
 ```js
-import { encodeText } from "quadqr";
-import { savePNG, scanFile } from "quadqr/node";
+import { encodeText } from "quadqr-js";
+import { savePNG, scanFile } from "quadqr-js/node";
 
 const code = encodeText("Generated on Node.js");
+
 await savePNG(code, "quadqr.png", {
   moduleSize: 12,
   quietZone: 4
@@ -78,14 +141,33 @@ const result = await scanFile("quadqr.png");
 console.log(result.text);
 ```
 
-## Browser script tag
+PNG generation and decoding are built into the Node.js adapter.
+
+## Use a script tag
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/quadqr@0.7.0/dist/quadqr.min.js"></script>
+<canvas id="qr"></canvas>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.0.0/dist/quadqr.min.js"></script>
 <script>
   const code = QuadQR.encodeText("No build step");
-  console.log(code.version, code.matrix);
+  QuadQR.renderToCanvas(code, document.querySelector("#qr"));
 </script>
 ```
 
-For production sites, pin the exact package version in the CDN URL.
+Pin an exact package version in production.
+
+## Use the CLI
+
+```bash
+npx quadqr-js encode "Hello QuadQR" -o hello.png
+npx quadqr-js decode hello.png
+```
+
+Password-protected CLI workflow:
+
+```bash
+npx quadqr-js encode "Private data" --password "my-password" -o secure.png
+npx quadqr-js decode secure.png --password "my-password"
+```
+
+See [CLI.md](./CLI.md) for the full command reference.

package/docs/NODE.md

@@ -1,78 +1,80 @@
 # 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.
+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
 
-The package targets Node.js 20.19 or newer.
+Node.js 20.19 or newer.
 
 ## ESM
 
 ```js
-import { encodeText } from "quadqr";
-import { savePNG, scanFile } from "quadqr/node";
+import { encodeText } from "quadqr-js";
+import { savePNG, scanFile } from "quadqr-js/node";
 ```
 
 ## CommonJS
 
-On supported modern Node versions:
-
 ```js
-const QuadQR = require("quadqr");
-const QuadQRNode = require("quadqr/node");
+const QuadQR = require("quadqr-js");
+const QuadQRNode = require("quadqr-js/node");
 ```
 
-## Generate PNG
+## Generate a 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:
+Use `toPNG()` when you need an in-memory `Buffer`:
 
 ```js
 const png = QuadQRNode.toPNG(code);
 ```
 
-This is useful for HTTP responses, object storage, email attachments, or database/blob workflows.
+This works well for HTTP responses, object storage, attachments, and other buffer-based workflows.
 
-## Scan PNG
+## Scan a PNG file
 
 ```js
 const result = await QuadQRNode.scanFile("output.png");
 console.log(result.text);
 ```
 
-Or scan an in-memory buffer:
+Or scan a 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.
+PNG generation and decoding do not require external native dependencies.
 
-## JPEG, WebP, and AVIF
+## Other image formats
 
-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.
+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, pass decoded RGBA pixels directly to `scanImageData()` or use PNG input.
+If `sharp` is not installed, decode the image to RGBA in your own image pipeline and pass the pixels to `scanImageData()`.
 
-## Secure Node workflow
+## Secure password workflow
 
 ```js
 import {
   decryptDecoded,
   encodeSecureText
-} from "quadqr";
-import { savePNG, scanFile } from "quadqr/node";
+} from "quadqr-js";
+import {
+  savePNG,
+  scanFile
+} from "quadqr-js/node";
 
 const code = await encodeSecureText("private", {
   security: {
@@ -84,9 +86,38 @@ const code = await encodeSecureText("private", {
 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/PUBLISHING.md

@@ -1,8 +1,8 @@
 # Publishing QuadQR to npm
 
-This repository is already configured as a public npm package named `quadqr` at version `0.7.0`.
+QuadQR is published on npm as [`quadqr-js`](https://www.npmjs.com/package/quadqr-js). The repository package name is `quadqr-js`.
 
-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.
+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
 
@@ -30,13 +30,13 @@ npm install
 
 so your local package lock and npm metadata are synchronized.
 
-## 3. Verify the package name
+## 3. Verify the package metadata
 
 ```bash
-npm view quadqr
+npm view quadqr-js
 ```
 
-If npm returns a package owned by somebody else, do not publish over it. Change `package.json` to a scoped name that you own.
+Confirm the published package and current version before releasing an update.
 
 ## 4. Run the full release checks
 
@@ -56,18 +56,12 @@ npm pack
 
 ## 5. Publish
 
-For the current unscoped public package:
+The package is an unscoped public package and `publishConfig.access` is already set to `public`, so publish with:
 
 ```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
@@ -76,15 +70,15 @@ npm publishing requires an account that satisfies npm's current 2FA/authenticati
 mkdir quadqr-consumer-test
 cd quadqr-consumer-test
 npm init -y
-npm install quadqr
+npm install quadqr-js
 ```
 
 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
+npx quadqr-js keygen
+npx quadqr-js encode "Hello from npm" -o hello.png
+npx quadqr-js decode hello.png
 ```
 
 ## 7. Verify CDN availability
@@ -92,8 +86,8 @@ npx quadqr decode hello.png
 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
+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.

package/docs/README.md

@@ -1,26 +1,41 @@
 # 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.
+QuadQR is an experimental four-state RGBW matrix symbology. Each data cell carries exactly two bits using red, green, blue, or white. The JavaScript library supports encoding, rendering, matrix decoding, image and camera scanning, Spectrum ECC, optional authenticated encryption, Node.js PNG workflows, CDN usage, a CLI, TypeScript declarations, and optional prebuilt WebAssembly acceleration.
 
-## Documentation map
+## Live links
+
+- [Documentation Site](https://akanshsirohi.github.io/QuadQR/docs-site/)
+- [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)
 - [Browser and CDN](./BROWSER_CDN.md)
 - [Node.js](./NODE.md)
+- [CLI](./CLI.md)
 - [Secure Payloads](./SECURITY.md)
-- [WASM](./WASM.md)
-- [Publishing to npm](./PUBLISHING.md)
+- [WebAssembly](./WASM.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 |
+| `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, 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
 
-The package is designed so the matrix codec is shared across all runtimes. Browser and Node adapters only handle runtime-specific input/output.
+QuadQR is licensed under AGPL-3.0. See [`LICENSE`](../LICENSE).

package/docs/SECURITY.md

@@ -1,17 +1,26 @@
 # Secure Payloads
 
-QuadQR Secure Payload v1 is an optional layer above the matrix codec and Spectrum ECC.
+QuadQR Secure Payload v1 is an optional authenticated-encryption layer above the matrix codec and Spectrum ECC.
 
 ```text
 plaintext
-  -> encryption/authentication
+  -> encryption + authentication
   -> secure envelope
   -> QuadQR framing
   -> Spectrum ECC
   -> RGBW matrix
 ```
 
-Scanning and error correction therefore remain independent from encryption.
+Normal QuadQR symbols are unencrypted by default. Secure Payload is used only when explicitly requested.
+
+## Which mode should I use?
+
+| Mode | Use it when |
+| --- | --- |
+| Password | A person will enter or share a secret password to unlock the payload |
+| Raw 256-bit key | Your application, service, device, or scanner already manages cryptographic keys |
+
+Both modes use AES-256-GCM for confidentiality and authenticated integrity.
 
 ## Password mode
 
@@ -22,9 +31,11 @@ Password mode uses:
 - configurable iteration count, default 600,000
 - AES-256-GCM
 - random 12-byte nonce
-- authenticated metadata
+- authenticated envelope metadata
 
 ```js
+import { encodeSecureText } from "quadqr-js";
+
 const code = await encodeSecureText("private", {
   security: {
     mode: "password",
@@ -37,9 +48,14 @@ The password is never stored in the QuadQR symbol.
 
 ## Raw 256-bit key mode
 
-Raw-key mode accepts exactly 32 random bytes.
+Raw-key mode accepts exactly 32 secret bytes, either as bytes or a 64-character hexadecimal string.
 
 ```js
+import {
+  encodeSecureText,
+  generateRaw256Key
+} from "quadqr-js";
+
 const key = generateRaw256Key();
 
 const code = await encodeSecureText("machine secret", {
@@ -50,29 +66,64 @@ const code = await encodeSecureText("machine secret", {
 });
 ```
 
-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.
+By default, the secure envelope can include a short SHA-256 key fingerprint/key ID. This is a non-secret routing hint that can help an application choose the correct key. The actual secret key is never embedded in the symbol.
 
-## Decryption
+## Scanning secure QuadQR
 
-A secure scan stays locked:
+Scanning does not automatically reveal protected plaintext. The scanner first returns a locked result:
 
 ```js
-const locked = scanImageData(imageData);
+const locked = await scanFile(file);
 
-if (locked.secure) {
-  const unlocked = await decryptDecoded(locked, {
-    password: "long unique password"
-  });
-}
+console.log(locked.secure);              // true
+console.log(locked.requiresDecryption);  // true
+console.log(locked.security.mode);       // password | raw-key
+console.log(locked.text);                // null
+```
+
+Then unlock it with the correct credential:
+
+```js
+const unlocked = await decryptDecoded(locked, {
+  password: "long unique password"
+});
+
+console.log(unlocked.text);
 ```
 
-AES-GCM authentication rejects an incorrect password/key or modified ciphertext.
+For raw-key mode:
+
+```js
+const unlocked = await decryptDecoded(locked, { key });
+```
+
+Image upload, camera, matrix, RGBA, and Node.js scan results all use the same secure-result model.
+
+## Authentication behavior
+
+AES-GCM authentication rejects:
+
+- an incorrect password;
+- an incorrect raw key;
+- modified ciphertext;
+- modified authenticated secure-envelope metadata.
+
+QuadQR's CRC and Spectrum ECC still handle matrix/image corruption before decryption is attempted. Cryptographic authentication is a separate final security check.
+
+## Key management guidance
+
+- Use long, unique passwords for password mode.
+- Generate raw keys with `generateRaw256Key()` or another cryptographically secure random source.
+- Store long-lived raw keys in an appropriate secret manager, operating-system key store, HSM, or equivalent secure storage for your application.
+- Do not put the secret password or raw key inside the same QuadQR symbol.
+- Do not hard-code a long-lived raw key in public client-side JavaScript if it is intended to remain secret.
+
+## Security boundaries
 
-## Threat model notes
+Secure Payload protects payload confidentiality and integrity, but it does not solve every application-security problem:
 
-- 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.
+- A photographed symbol can still be copied.
+- Encryption by itself is not replay protection.
+- Ticket/access systems should use server-side state, nonces, expiry, signatures, or another replay-control mechanism appropriate to the application.
+- Decoded plaintext is still untrusted application input and should be validated before use.

package/docs/WASM.md

@@ -1,36 +1,67 @@
 # WebAssembly
 
-QuadQR ships a small precompiled WebAssembly module at:
+QuadQR includes an optional prebuilt 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.
+The normal JavaScript implementation works without WASM. Applications can opt in when they want to use the bundled accelerator.
 
-## Enable it
+## Enable WASM
 
 ```js
-import { initWasm } from "quadqr";
+import { initWasm } from "quadqr-js";
 
 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.
+In QuadQR 0.7.x, the WASM module accelerates CRC-32. Once initialized, normal encode/decode operations automatically use the installed accelerator.
 
-## Why start small?
+## Check the current state
 
-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.
+```js
+import { getWasmState } from "quadqr-js";
+
+console.log(getWasmState());
+```
 
-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.
+Before initialization, or after disabling WASM, the result is `null`.
 
-## Disable
+## Disable WASM
 
 ```js
-import { disableWasm } from "quadqr";
+import { disableWasm } from "quadqr-js";
 
 disableWasm();
 ```
 
-The JavaScript fallback is restored immediately.
+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.