@wirunrom/hqr-generate 0.2.23 → 0.3.11

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Wirunrom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,151 +1,230 @@
-# @wirunrom/hqr-generate
-
-A **stable black-and-white QR Code generator** that returns **PNG Data URLs or PNG bytes**, powered by **Rust + WebAssembly (WASM)**.
-
-This library is designed with a **scan-reliability-first** mindset and a **frontend-first API**, making it easy to use in modern web applications without additional configuration.
-
----
-
-## Features
-
-- High-contrast **black & white only** output (maximum scan compatibility)
-- Optimized for both **old and new mobile devices**
-- Deterministic and consistent QR output
-- Lightweight and fast (**Rust + WASM**)
-- Supports:
-  - **PNG Data URL** (simple usage)
-  - **PNG raw bytes** (best performance, no Base64 overhead)
-- Works out of the box with:
-  - Plain HTML / JavaScript
-  - React
-  - Next.js (Pages Router & App Router)
-  - Modern bundlers (Vite, Webpack, etc.)
-
----
-
-## Installation
-
-```bash
-npm install @wirunrom/hqr-generate
-```
-
-## Basic Usage (Bundler / React / Next.js)
-
-**Generate PNG Data URL**
-
-Simple and widely compatible. Recommended for most use cases.
-
-```ts
-import { qrPngDataUrl } from "@wirunrom/hqr-generate";
-
-const src = await qrPngDataUrl("hello world", {
-  size: 320,
-  margin: 4,
-  ecc: "Q",
-});
-
-<img src={src} alt="QR Code" />
-```
-
-**Generate PNG Bytes (Best Performance)**
-
-Using raw bytes avoids Base64 overhead and is more memory-efficient.
-
-```ts
-import { qrPngBytes } from "@wirunrom/hqr-generate";
-
-const bytes = await qrPngBytes("hello world", {
-  size: 320,
-  margin: 4,
-  ecc: "Q",
-});
-
-const url = URL.createObjectURL(
-  new Blob([bytes], { type: "image/png" })
-);
-
-<img src={url} alt="QR Code" />
-
-```
-
-## React Hook Helper (/react)
-
-For React or Next.js applications, the library provides idiomatic React hooks that automatically update when inputs change.
-
-**useQrPngDataUrl**
-
-Generates a PNG Data URL and updates automatically when dependencies change.
-
-```ts
-import { useQrPngDataUrl } from "@wirunrom/hqr-generate/react";
-
-function QR() {
-  const src = useQrPngDataUrl("hello world", {
-    size: 320,
-    margin: 4,
-    ecc: "Q",
-  });
-
-  if (!src) return null;
-  return <img src={src} alt="QR Code" />;
-}
-```
-
-**useQrPngBlobUrl**
-
-Generates a Blob URL instead of a Base64 Data URL.
-Recommended for larger QR codes or frequent updates.
-
-```ts
-import { useQrPngBlobUrl } from "@wirunrom/hqr-generate/react";
-
-function QR() {
-  const src = useQrPngBlobUrl("hello world", {
-    size: 320,
-    margin: 4,
-    ecc: "Q",
-  });
-
-  if (!src) return null;
-  return <img src={src} alt="QR Code" />;
-}
-```
-
-## Plain HTML / No Bundler (/web)
-
-Use this entry when working with static HTML, CDN, or environments without a bundler.
-
-```html
-<script type="module">
-  import { qr_png_bytes, qr_png_data_url } from "@wirunrom/hqr-generate/web";
-
-  const src = await qr_png_bytes("hello world", {
-    size: 320,
-    margin: 4,
-    ecc: "Q",
-  });
-
-  // or
-
-  const src = await qr_png_data_url("hello world", {
-    size: 320,
-    margin: 4,
-    ecc: "Q",
-  });
-
-  document.getElementById("qr").src = src;
-</script>
-
-<img id="qr" />
-```
-
-## API Reference
-
-Generate a QR code and return a PNG Data URL.
-
-| Name   | Type                       | Default | Description                  |
-| ------ | -------------------------- | ------- | ---------------------------- |
-| text   | `string`                   | —       | Text to encode               |
-| size   | `number`                   | `320`   | Image size in pixels         |
-| margin | `number`                   | `4`     | Quiet zone (recommended ≥ 4) |
-| ecc    | `"L" \| "M" \| "Q" \| "H"` | `"Q"`   | Error correction level       |
+# @wirunrom/hqr-generate
+
+A high-performance **QR Code generator and decoder** with
+**black-and-white only output**, powered by **Rust + WebAssembly (WASM)**.
+
+Supports both **QR generation** and **QR decoding (scan)** in modern web applications.
+
+This library is designed with a **scan-reliability-first** mindset and a **frontend-first API**, making it easy to use in modern web applications without additional configuration.
+
+---
+
+## Features
+
+- High-contrast **black & white only** output (maximum scan compatibility)
+- Optimized for both **old and new mobile devices**
+- Deterministic and consistent QR output
+- Lightweight and fast (**Rust + WASM**)
+- QR decoding (scan) from browser ImageData
+- Supports:
+  - **PNG Data URL** (simple usage)
+  - **PNG raw bytes** (best performance, no Base64 overhead)
+- Works out of the box with:
+  - Plain HTML / JavaScript
+  - React
+  - Next.js Client Component (Pages Router & App Router)
+  - Modern bundlers (Vite, Webpack, etc.)
+
+---
+
+## Installation
+
+```bash
+npm install @wirunrom/hqr-generate
+```
+
+## API Reference (GenerateQR)
+
+Generate a QR code and return a PNG Data URL.
+
+Parameters
+
+| Name   | Type                       | Default | Description                  |
+| ------ | -------------------------- | ------- | ---------------------------- |
+| text   | `string`                   | —       | Text to encode               |
+| size   | `number`                   | `320`   | Image size in pixels         |
+| margin | `number`                   | `4`     | Quiet zone (recommended ≥ 4) |
+| ecc    | `"L" \| "M" \| "Q" \| "H"` | `"Q"`   | Error correction level       |
+
+## Basic Usage [Bundler / React / Next.js (Client)]
+
+**Generate PNG Data URL**
+
+Simple and widely compatible. Recommended for most use cases.
+
+```ts
+import { qr_png_data_url } from "@wirunrom/hqr-generate";
+
+const src = await qr_png_data_url("hello world", 320, 4, "Q");
+
+<img src={src} alt="QR Code" />
+```
+
+**Generate PNG Bytes (Best Performance)**
+
+Using raw bytes avoids Base64 overhead and is more memory-efficient.
+
+```ts
+import { qr_png_bytes } from "@wirunrom/hqr-generate";
+
+const bytes = await qr_png_bytes("hello world", 320, 4, "Q");
+
+const url = URL.createObjectURL(
+  new Blob([bytes], { type: "image/png" })
+);
+
+<img src={url} alt="QR Code" />
+```
+
+**Decode QR Code**
+
+Decode a QR code from browser ImageData (Canvas / camera / image upload friendly).
+
+```ts
+import { qr_decode_from_image } from "@wirunrom/hqr-generate";
+
+const imageData = ctx.getImageData(0, 0, width, height);
+const text = await qr_decode_from_image(imageData);
+
+console.log(text);
+```
+
+Decode runs entirely in WASM and does not require server-side processing.
+
+## React Hook Helper (/react)
+
+For React or Next.js applications, the library provides idiomatic React hooks that manage async state automatically.
+
+**useQrPngDataUrl**
+
+Generates a PNG Data URL and updates automatically when inputs change.
+
+```ts
+import { useQrPngDataUrl } from "@wirunrom/hqr-generate/react";
+
+function QR() {
+  const src = useQrPngDataUrl("hello world", {
+    size: 320,
+    margin: 4,
+    ecc: "Q",
+  });
+
+  if (!src) return null;
+  return <img src={src} alt="QR Code" />;
+}
+```
+
+**useQrPngBlobUrl**
+
+Generates a Blob URL instead of a Base64 Data URL.
+Recommended for larger QR codes or frequent updates.
+
+```ts
+import { useQrPngBlobUrl } from "@wirunrom/hqr-generate/react";
+
+function QR() {
+  const src = useQrPngBlobUrl("hello world", {
+    size: 320,
+    margin: 4,
+    ecc: "Q",
+  });
+
+  if (!src) return null;
+  return <img src={src} alt="QR Code" />;
+}
+```
+
+**useQrDecodeFromImageData**
+
+Decode a QR code from browser ImageData.
+
+```ts
+import { useQrDecodeFromImageData } from "@wirunrom/hqr-generate/react";
+
+function Scanner({ image }: { image: ImageData | null }) {
+  const { text, loading, error } = useQrDecodeFromImageData(image);
+
+  if (loading) return <div>Scanning…</div>;
+  if (error) return <div>Error</div>;
+  if (!text) return null;
+
+  return <div>QR: {text}</div>;
+}
+```
+
+Parameters
+
+| Name  | Type        | Description                                 |
+| ----- | ----------- | ------------------------------------------- |
+| image | `ImageData` | RGBA image data from Canvas or Camera frame |
+
+Returns
+
+- `Promise<string>`
+  - Resolves with decoded QR text
+  - Rejects if no QR code is detected or image is invalid
+
+Notes
+
+- Input must be RGBA ImageData
+- Decode runs entirely in WASM
+- No server or backend required
+- Best results with:
+  - High-contrast QR codes
+  - Minimal blur
+  - Proper quiet zone
+
+**useQrDecodeFromImageSrc**
+
+Decode a QR code from your image path.
+
+```ts
+import { useQrDecodeFromImageSrc } from "@wirunrom/hqr-generate/react";
+
+function DecodeQR({ imagePath }: { imagePath: string | null }) {
+  const { text } = useQrDecodeFromImageSrc(imagePath);
+
+  if (!text) return null;
+
+  return <div>Decode QR: {text}</div>;
+}
+```
+
+Parameters
+
+| Name | Type     | Description     |
+| ---- | -------- | --------------- |
+| src  | `string` | Your image path |
+
+Returns
+
+- `Promise<string>`
+  - Resolves with decoded QR text
+
+## Plain HTML / No Bundler (/web)
+
+Use this entry when working with static HTML, CDN, or environments without a bundler.
+
+```html
+<script type="module">
+  import {
+    qr_png_bytes,
+    qr_png_data_url,
+    qr_decode_from_image_data,
+  } from "@wirunrom/hqr-generate/web";
+
+  const src = await qr_png_data_url("hello world", 320, 4, "Q");
+  document.getElementById("qr").src = src;
+
+  // decode example (canvas)
+  const canvas = document.getElementById("c");
+  const ctx = canvas.getContext("2d");
+  const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+
+  const text = await qr_decode_from_image_data(imageData);
+  console.log(text);
+</script>
+
+<img id="qr" />
+<canvas id="c" hidden></canvas>
+```

package/index.bundler.js

@@ -1,34 +1,59 @@
-import init, {
-  qr_png_data_url as _qr_png_data_url,
-  qr_png_bytes as _qr_png_bytes,
-} from "./pkg/bundler/hqr_generate.js";
-
-let _initPromise;
-
-function eccToU8(ecc) {
-  switch (ecc) {
-    case "L":
-      return 0;
-    case "M":
-      return 1;
-    case "H":
-      return 3;
-    default:
-      return 2;
-  }
-}
-
-async function ensureInit() {
-  if (!_initPromise) _initPromise = init();
-  await _initPromise;
-}
-
-export async function qr_png_data_url(text, size = 320, margin = 4, ecc = "Q") {
-  await ensureInit();
-  return _qr_png_data_url(text, size, margin, eccToU8(ecc));
-}
-
-export async function qr_png_bytes(text, size = 320, margin = 4, ecc = "Q") {
-  await ensureInit();
-  return _qr_png_bytes(text, size, margin, eccToU8(ecc));
-}
+import init, {
+  qr_png_data_url as _qr_png_data_url,
+  qr_png_bytes as _qr_png_bytes,
+  qr_decode_from_rgba as _qr_decode_from_rgba,
+} from "./pkg/bundler/hqr_generate.js";
+
+let _initPromise;
+
+function eccToU8(ecc) {
+  switch (ecc) {
+    case "L":
+      return 0;
+    case "M":
+      return 1;
+    case "H":
+      return 3;
+    default:
+      return 2;
+  }
+}
+
+/** @returns {Promise<void>} */
+async function ensureInit() {
+  _initPromise ??= init();
+  return _initPromise;
+}
+
+/**
+ * @param {string} text
+ * @param {number} [size=320]
+ * @param {number} [margin=4]
+ * @param {"L"|"M"|"Q"|"H"} [ecc="Q"]
+ * @returns {Promise<string>}
+ */
+export async function qr_png_data_url(text, size = 320, margin = 4, ecc = "Q") {
+  await ensureInit();
+  return _qr_png_data_url(text, size, margin, eccToU8(ecc));
+}
+
+/**
+ * @param {string} text
+ * @param {number} [size=320]
+ * @param {number} [margin=4]
+ * @param {"L"|"M"|"Q"|"H"} [ecc="Q"]
+ * @returns {Promise<Uint8Array>}
+ */
+export async function qr_png_bytes(text, size = 320, margin = 4, ecc = "Q") {
+  await ensureInit();
+  return _qr_png_bytes(text, size, margin, eccToU8(ecc));
+}
+
+/**
+ * @param {ImageData} image
+ * @returns {Promise<string>}
+ */
+export async function qr_decode_from_image_data(image) {
+  await ensureInit();
+  return _qr_decode_from_rgba(image.width, image.height, image.data);
+}

package/index.d.ts

@@ -1,22 +1,29 @@
-export type QrEcc = "L" | "M" | "Q" | "H";
-
-/**
- * Generate QR code PNG as Data URL (base64).
- */
-export declare function qr_png_data_url(
-  text: string,
-  size?: number,
-  margin?: number,
-  ecc?: QrEcc
-): Promise<string>;
-
-/**
- * Generate QR code PNG as raw bytes (Uint8Array).
- * Recommended for best performance (Blob URL, upload, caching).
- */
-export declare function qr_png_bytes(
-  text: string,
-  size?: number,
-  margin?: number,
-  ecc?: QrEcc
-): Promise<Uint8Array>;
+export type QrEcc = "L" | "M" | "Q" | "H";
+
+/**
+ * Generate QR code PNG as Data URL (base64).
+ */
+export declare function qr_png_data_url(
+  text: string,
+  size?: number,
+  margin?: number,
+  ecc?: QrEcc
+): Promise<string>;
+
+/**
+ * Generate QR code PNG as raw bytes (Uint8Array).
+ * Recommended for best performance (Blob URL, upload, caching).
+ */
+export declare function qr_png_bytes(
+  text: string,
+  size?: number,
+  margin?: number,
+  ecc?: QrEcc
+): Promise<Uint8Array>;
+
+/**
+ * Decode QR from browser ImageData
+ */
+export function qr_decode_from_image_data(
+  image: ImageData
+): Promise<string>;

package/index.web.js

@@ -1,42 +1,61 @@
-import init, {
-  qr_png_data_url as _qr_png_data_url,
-  qr_png_bytes as _qr_png_bytes,
-} from "./pkg/web/hqr_generate.js";
-
-let _initPromise;
-
-function eccToU8(ecc) {
-  switch (ecc) {
-    case "L":
-      return 0;
-    case "M":
-      return 1;
-    case "H":
-      return 3;
-    default:
-      return 2;
-  }
-}
-
-/** @returns {Promise<void>} */
-async function ensureInit() {
-  if (!_initPromise) _initPromise = init();
-  await _initPromise;
-}
-
-/**
- * @param {string} text
- * @param {number} [size=320]
- * @param {number} [margin=4]
- * @param {"L"|"M"|"Q"|"H"} [ecc="Q"]
- * @returns {Promise<string>}
- */
-export async function qr_png_data_url(text, size = 320, margin = 4, ecc = "Q") {
-  await ensureInit();
-  return _qr_png_data_url(text, size, margin, eccToU8(ecc));
-}
-
-export async function qr_png_bytes(text, size = 320, margin = 4, ecc = "Q") {
-  await ensureInit();
-  return _qr_png_bytes(text, size, margin, eccToU8(ecc));
-}
+import init, {
+  qr_png_data_url as _qr_png_data_url,
+  qr_png_bytes as _qr_png_bytes,
+  qr_decode_from_rgba as _qr_decode_from_rgba,
+} from "./pkg/web/hqr_generate.js";
+
+let _initPromise;
+
+function eccToU8(ecc) {
+  switch (ecc) {
+    case "L":
+      return 0;
+    case "M":
+      return 1;
+    case "H":
+      return 3;
+    default:
+      return 2;
+  }
+}
+
+/** @returns {Promise<void>} */
+async function ensureInit() {
+  _initPromise ??= init();
+  return _initPromise;
+}
+
+/**
+ * @param {string} text
+ * @param {number} [size=320]
+ * @param {number} [margin=4]
+ * @param {"L"|"M"|"Q"|"H"} [ecc="Q"]
+ * @returns {Promise<string>}
+ */
+export async function qr_png_data_url(text, size = 320, margin = 4, ecc = "Q") {
+  await ensureInit();
+  return _qr_png_data_url(text, size, margin, eccToU8(ecc));
+}
+
+/**
+ * @param {string} text
+ * @param {number} [size=320]
+ * @param {number} [margin=4]
+ * @param {"L"|"M"|"Q"|"H"} [ecc="Q"]
+ * @returns {Promise<Uint8Array>}
+ */
+export async function qr_png_bytes(text, size = 320, margin = 4, ecc = "Q") {
+  await ensureInit();
+  return _qr_png_bytes(text, size, margin, eccToU8(ecc));
+}
+
+/**
+ * Decode QR from Image (browser/canvas friendly)
+ *
+ * @param {ImageData} image
+ * @returns {Promise<string>}
+ */
+export async function qr_decode_from_image_data(image) {
+  await ensureInit();
+  return _qr_decode_from_rgba(image.width, image.height, image.data);
+}