quadqr-js 1.0.0 → 1.0.2

package/docs/BROWSER_CDN.md

@@ -1,137 +1,142 @@
-# Browser and CDN Usage
-
-## Browser ESM
-
-With Vite, webpack, Rollup, Next.js client code, or another browser bundler:
-
-```js
-import {
-  encodeText,
-  renderToCanvas,
-  scanFile,
-  startCameraScanner
-} from "quadqr-js/browser";
-```
-
-The main `quadqr-js` entry also works in modern browser bundlers for runtime-neutral APIs.
-
-## Render to canvas
-
-```js
-const code = encodeText("Hello browser");
-
-renderToCanvas(code, document.querySelector("#qr"), {
-  moduleSize: 12,
-  quietZone: 4,
-  style: "classic"
-});
-```
-
-Available styles are `classic`, `depth`, `soft`, and `inset`.
-
-## Scan an uploaded image
-
-```js
-const input = document.querySelector("#image");
-const result = await scanFile(input.files[0]);
-
-console.log(result.text);
-```
-
-If the symbol uses Secure Payload, the scan result has `secure: true` and `requiresDecryption: true` until it is successfully unlocked.
-
-## Live camera scanning
-
-```js
-const video = document.querySelector("#camera");
-
-const scanner = await startCameraScanner(video, {
-  scanInterval: 120,
-  async onDecode(result) {
-    console.log(result);
-    scanner.stop();
-  },
-  onError(error) {
-    console.error(error);
-  }
-});
-```
-
-Camera access requires HTTPS or localhost.
-
-## Decrypt a secure scan
-
-```js
-import { decryptDecoded } from "quadqr-js/browser";
-
-const locked = await scanFile(file);
-
-if (locked.secure) {
-  const unlocked = await decryptDecoded(locked, {
-    password: "my-password"
-  });
-
-  console.log(unlocked.text);
-}
-```
-
-Raw-key mode uses `{ key }` instead of `{ password }`.
-
-## Classic script tag
-
-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.0/dist/quadqr.min.js"></script>
-<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-js@1.0.0/dist/quadqr.min.js"></script>
-```
-
-## Direct CDN ESM
-
-```html
-<script type="module">
-  import {
-    encodeText,
-    renderToCanvas
-  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.0.0/dist/browser.js";
-
-  const code = encodeText("ES module CDN");
-  renderToCanvas(code, document.querySelector("#qr"));
-</script>
-```
-
-## Optional WASM from a CDN
-
-The classic global build can resolve the bundled WASM asset relative to its own script URL:
-
-```js
-await QuadQR.initWasm();
-```
-
-You can also provide a custom URL:
-
-```js
-await QuadQR.initWasm({
-  url: "https://example.com/assets/quadqr-core.wasm"
-});
-```
-
-WASM is optional. The normal JavaScript implementation remains available if it cannot load.
-
-## Production recommendation
-
-Pin a concrete package version such as `@1.0.0` in CDN URLs so an existing site does not silently change when a newer package version becomes available.
+# Browser and CDN Usage
+
+## Browser ESM
+
+With Vite, webpack, Rollup, Next.js client code, or another browser bundler:
+
+```js
+import {
+  encodeText,
+  renderToCanvas,
+  scanFile,
+  startCameraScanner
+} from "quadqr-js/browser";
+```
+
+The main `quadqr-js` entry also works in modern browser bundlers for runtime-neutral APIs.
+
+## Render to canvas
+
+```js
+const code = encodeText("Hello browser");
+
+renderToCanvas(code, document.querySelector("#qr"), {
+  moduleSize: 12,
+  quietZone: 4,
+  style: "classic"
+});
+```
+
+Available styles are `classic`, `depth`, `soft`, and `inset`.
+
+## Scan an uploaded image
+
+```js
+const input = document.querySelector("#image");
+const result = await scanFile(input.files[0]);
+
+console.log(result.text);
+```
+
+If the symbol uses Secure Payload, the scan result has `secure: true` and `requiresDecryption: true` until it is successfully unlocked.
+
+## Live camera scanning
+
+```js
+const video = document.querySelector("#camera");
+
+const scanner = await startCameraScanner(video, {
+  scanInterval: 120,
+  cameraFinderRecoveryEvery: 2,
+  async onResult(result) {
+    console.log(result);
+    scanner.stop();
+  },
+  onScanMiss() {
+    // Keep searching.
+  },
+  onDiagnostic(event) {
+    // Useful for live finder overlays and scanner debug logs.
+    console.log(event.method, event.finderMethod, event.finderCount, event.geometry?.version);
+  }
+});
+```
+
+Camera access requires HTTPS or localhost. QuadQR scans the part of an `object-fit: cover` video that is actually visible to the user. The fast finder pass uses the RGB value channel (`max(R,G,B)`) so saturated data colors are less likely to be mistaken for structural black. After misses, throttled recovery frames can try alternate finder thresholds before stronger color correction. `onDiagnostic` exposes the finder method and geometry work already performed by the scanner.
+
+## Decrypt a secure scan
+
+```js
+import { decryptDecoded } from "quadqr-js/browser";
+
+const locked = await scanFile(file);
+
+if (locked.secure) {
+  const unlocked = await decryptDecoded(locked, {
+    password: "my-password"
+  });
+
+  console.log(unlocked.text);
+}
+```
+
+Raw-key mode uses `{ key }` instead of `{ password }`.
+
+## Classic script tag
+
+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>
+  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-js@1.0.1/dist/quadqr.min.js"></script>
+```
+
+## Direct CDN ESM
+
+```html
+<script type="module">
+  import {
+    encodeText,
+    renderToCanvas
+  } from "https://cdn.jsdelivr.net/npm/quadqr-js@1.0.1/dist/browser.js";
+
+  const code = encodeText("ES module CDN");
+  renderToCanvas(code, document.querySelector("#qr"));
+</script>
+```
+
+## Optional WASM from a CDN
+
+The classic global build can resolve the bundled WASM asset relative to its own script URL:
+
+```js
+await QuadQR.initWasm();
+```
+
+You can also provide a custom URL:
+
+```js
+await QuadQR.initWasm({
+  url: "https://example.com/assets/quadqr-core.wasm"
+});
+```
+
+WASM is optional. The normal JavaScript implementation remains available if it cannot load.
+
+## 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.

package/docs/GETTING_STARTED.md

@@ -1,173 +1,174 @@
-# Getting Started
-
-## Install
-
-```bash
-npm install quadqr-js
-```
-
-Node.js usage targets Node.js 20.19 or newer. Browser use works through a bundler, direct ESM, or the prebuilt CDN/global bundle.
-
-## Encode and decode text
-
-```js
-import { encodeText, decodeMatrix } from "quadqr-js";
-
-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"
-});
-```
-
-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-js";
-
-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);
-```
-
-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 {
-  encodeSecureText,
-  generateRaw256Key
-} from "quadqr-js";
-
-const key = generateRaw256Key();
-
-const code = await encodeSecureText("Application-managed secret", {
-  security: {
-    mode: "raw-key",
-    key
-  }
-});
-```
-
-The key must be exactly 32 bytes. Never embed the secret key inside the same QuadQR payload.
-
-## Generate and scan PNG files in Node.js
-
-```js
-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
-});
-
-const result = await scanFile("quadqr.png");
-console.log(result.text);
-```
-
-PNG generation and decoding are built into the Node.js adapter.
-
-## Use a script tag
-
-```html
-<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");
-  QuadQR.renderToCanvas(code, document.querySelector("#qr"));
-</script>
-```
-
-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.
+# Getting Started
+
+## Install
+
+```bash
+npm install quadqr-js
+```
+
+Node.js usage targets Node.js 20.19 or newer. Browser use works through a bundler, direct ESM, or the prebuilt CDN/global bundle.
+
+## Encode and decode text
+
+```js
+import { encodeText, decodeMatrix } from "quadqr-js";
+
+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"
+});
+```
+
+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"),
+  {
+    cameraFinderRecoveryEvery: 2,
+    onResult(result) {
+      console.log(result);
+      scanner.stop();
+    }
+  }
+);
+```
+
+Camera access requires HTTPS or localhost. Finder detection uses a QuadQR-specific RGB value pass first, then throttled threshold recovery when the fast pass cannot lock onto all three finder patterns.
+
+## 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-js";
+
+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);
+```
+
+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 {
+  encodeSecureText,
+  generateRaw256Key
+} from "quadqr-js";
+
+const key = generateRaw256Key();
+
+const code = await encodeSecureText("Application-managed secret", {
+  security: {
+    mode: "raw-key",
+    key
+  }
+});
+```
+
+The key must be exactly 32 bytes. Never embed the secret key inside the same QuadQR payload.
+
+## Generate and scan PNG files in Node.js
+
+```js
+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
+});
+
+const result = await scanFile("quadqr.png");
+console.log(result.text);
+```
+
+PNG generation and decoding are built into the Node.js adapter.
+
+## Use a script tag
+
+```html
+<canvas id="qr"></canvas>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.0.1/dist/quadqr.min.js"></script>
+<script>
+  const code = QuadQR.encodeText("No build step");
+  QuadQR.renderToCanvas(code, document.querySelector("#qr"));
+</script>
+```
+
+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.