@wirunrom/hqr-generate 0.2.23 → 0.3.11

package/pkg/web/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/pkg/web/hqr_generate.d.ts

@@ -1,6 +1,8 @@
 /* tslint:disable */
 /* eslint-disable */
 
+export function qr_decode_from_rgba(width: number, height: number, rgba: Uint8Array): string;
+
 export function qr_png_bytes(text: string, size: number, margin: number, ecc: number): Uint8Array;
 
 export function qr_png_data_url(text: string, size: number, margin: number, ecc: number): string;
@@ -9,13 +11,14 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly qr_decode_from_rgba: (a: number, b: number, c: any) => [number, number, number, number];
     readonly qr_png_bytes: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
     readonly qr_png_data_url: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
-    readonly __wbindgen_malloc: (a: number, b: number) => number;
-    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __externref_table_dealloc: (a: number) => void;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_start: () => void;
 }
 

package/pkg/web/hqr_generate.js

@@ -1,5 +1,30 @@
 /* @ts-self-types="./hqr_generate.d.ts" */
 
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array} rgba
+ * @returns {string}
+ */
+export function qr_decode_from_rgba(width, height, rgba) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ret = wasm.qr_decode_from_rgba(width, height, rgba);
+        var ptr1 = ret[0];
+        var len1 = ret[1];
+        if (ret[3]) {
+            ptr1 = 0; len1 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * @param {string} text
  * @param {number} size
@@ -51,10 +76,17 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_be289d5034ed271b: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
+        __wbg_length_32ed9a279acd054c: function(arg0) {
+            const ret = arg0.length;
+            return ret;
+        },
         __wbg_new_from_slice_a3d2629dc1826784: function(arg0, arg1) {
             const ret = new Uint8Array(getArrayU8FromWasm0(arg0, arg1));
             return ret;
         },
+        __wbg_prototypesetcall_bdcdcc5842e4d77d: function(arg0, arg1, arg2) {
+            Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
+        },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);

package/pkg/web/hqr_generate_bg.wasm.d.ts

@@ -1,11 +1,12 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const qr_decode_from_rgba: (a: number, b: number, c: any) => [number, number, number, number];
 export const qr_png_bytes: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const qr_png_data_url: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
-export const __wbindgen_malloc: (a: number, b: number) => number;
-export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __externref_table_dealloc: (a: number) => void;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_start: () => void;

package/pkg/web/package.json

@@ -2,7 +2,7 @@
   "name": "hqr-generate",
   "type": "module",
   "description": "Stable black/white QR code generator (PNG data URL) powered by Rust + WASM",
-  "version": "0.2.0",
+  "version": "0.3.11",
   "license": "MIT",
   "repository": {
     "type": "git",

package/react/index.d.ts

@@ -1,17 +1,12 @@
-import type { QrEcc } from "../index";
-
-export interface UseQrPngOptions {
-  size?: number;
-  margin?: number;
-  ecc?: QrEcc;
-}
-
-export declare function useQrPngDataUrl(
-  text: string,
-  opts?: UseQrPngOptions
-): string;
-
-export declare function useQrPngBlobUrl(
-  text: string,
-  opts?: UseQrPngOptions
-): string;
+import type { QrEcc } from "../index";
+
+export interface UseQrPngOptions {
+  size?: number;
+  margin?: number;
+  ecc?: QrEcc;
+}
+
+export * from "./useQrPngDataUrl";
+export * from "./useQrPngBlobUrl";
+export * from "./useQrDecodeFromImageData";
+export * from "./useQrDecodeFromImageSrc";

package/react/index.js

@@ -1,91 +1,4 @@
-import { useEffect, useState } from "react";
-import { qr_png_data_url, qr_png_bytes } from "../index.web.js";
-
-/**
- * React hook for QR Code Data URL (browser-only).
- * Backward-compatible, but heavier than Blob URL due to base64.
- * @param {string} text
- * @param {{size?:number, margin?:number, ecc?:"L"|"M"|"Q"|"H"}} [opts]
- */
-export function useQrPngDataUrl(text, opts) {
-  const size = opts?.size ?? 320;
-  const margin = opts?.margin ?? 4;
-  const ecc = opts?.ecc ?? "Q";
-
-  const [src, setSrc] = useState("");
-
-  useEffect(() => {
-    let alive = true;
-
-    if (!text) {
-      setSrc("");
-      return () => {
-        alive = false;
-      };
-    }
-
-    qr_png_data_url(text, size, margin, ecc)
-      .then((res) => {
-        if (alive) setSrc(res);
-      })
-      .catch(() => {
-        if (alive) setSrc("");
-      });
-
-    return () => {
-      alive = false;
-    };
-  }, [text, size, margin, ecc]);
-
-  return src;
-}
-
-/**
- * React hook for QR Code as Blob URL (browser-only).
- * Faster + lower memory than base64 data URL for frequent updates / large images.
- * @param {string} text
- * @param {{size?:number, margin?:number, ecc?:"L"|"M"|"Q"|"H"}} [opts]
- */
-export function useQrPngBlobUrl(text, opts) {
-  const size = opts?.size ?? 320;
-  const margin = opts?.margin ?? 4;
-  const ecc = opts?.ecc ?? "Q";
-
-  const [src, setSrc] = useState("");
-
-  useEffect(() => {
-    let alive = true;
-    let objectUrl = "";
-
-    if (!text) {
-      setSrc("");
-      return () => {
-        alive = false;
-        if (objectUrl) URL.revokeObjectURL(objectUrl);
-      };
-    }
-
-    qr_png_bytes(text, size, margin, ecc)
-      .then((bytes) => {
-        if (!alive) return;
-
-        // revoke old url (if any)
-        if (objectUrl) URL.revokeObjectURL(objectUrl);
-
-        objectUrl = URL.createObjectURL(
-          new Blob([bytes], { type: "image/png" }),
-        );
-        setSrc(objectUrl);
-      })
-      .catch(() => {
-        if (alive) setSrc("");
-      });
-
-    return () => {
-      alive = false;
-      if (objectUrl) URL.revokeObjectURL(objectUrl);
-    };
-  }, [text, size, margin, ecc]);
-
-  return src;
-}
+export { useQrPngDataUrl } from "./useQrPngDataUrl.js";
+export { useQrPngBlobUrl } from "./useQrPngBlobUrl.js";
+export { useQrDecodeFromImageData } from "./useQrDecodeFromImageData.js";
+export { useQrDecodeFromImageSrc } from "./useQrDecodeFromImageSrc.js";

package/react/useQrDecodeFromImageData.d.ts

@@ -0,0 +1,5 @@
+export declare function useQrDecodeFromImageData(image: ImageData | null): {
+  text: string | null;
+  error: unknown | null;
+  loading: boolean;
+};

package/react/useQrDecodeFromImageData.js

@@ -0,0 +1,47 @@
+import { useEffect, useState } from "react";
+import { qr_decode_from_image_data } from "../index.web.js";
+
+/**
+ * React hook for decoding QR code from ImageData.
+ *
+ * @param {ImageData | null} image
+ * @returns {{ text: string | null, error: unknown | null, loading: boolean }}
+ */
+export function useQrDecodeFromImageData(image) {
+  const [text, setText] = useState(null);
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    let alive = true;
+
+    if (!image) {
+      setText(null);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    qr_decode_from_image_data(image)
+      .then((res) => {
+        if (!alive) return;
+        setText(res);
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (!alive) return;
+        setText(null);
+        setError(err);
+        setLoading(false);
+      });
+
+    return () => {
+      alive = false;
+    };
+  }, [image]);
+
+  return { text, error, loading };
+}

package/react/useQrDecodeFromImageSrc.d.ts

@@ -0,0 +1,6 @@
+export declare function useQrDecodeFromImageSrc(src: string | null): {
+  text: string | null;
+  loading: boolean;
+  error: unknown | null;
+  loadError: unknown | null;
+};