@cflorioluis/barcodereader 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# BarCodeReader
+
+A dependency-free 1D/2D barcode & QR decoder with **one core** that runs
+everywhere JavaScript runs — and, later, everywhere native FFI reaches.
+
+## The idea
+
+The decoding logic is written **once** in pure Rust (`core/`). It knows nothing
+about cameras, files or platforms: it takes a grayscale pixel buffer and returns
+the decoded symbols. Every platform is a thin binding on top:
+
+```
+core (Rust, pure, no I/O)
+  decode_luma(pixels, width, height) -> Vec<Symbol>
+        │
+        ├── wasm/   → wasm-pack → npm → Angular, React, Vue, Electron, Capacitor   ← we are here
+        ├── ffi/    → .so/.dll/.dylib (C ABI) → Flutter (dart:ffi), PHP (FFI), Python   (step 2)
+        └── uniffi  → Swift + Kotlin → native iOS / Android                              (step 3)
+```
+
+Each platform only supplies pixels its own way (getUserMedia on web,
+AVFoundation on iOS, CameraX on Android). The hard part — finder patterns,
+perspective sampling, Reed-Solomon, payload decoding — lives in the core and is
+tested once.
+
+## Layout
+
+| Path | What it is |
+|------|-----------|
+| `core/` | Pure-Rust decoder. Image handling, binarization, QR pipeline. |
+| `wasm/` | `wasm-bindgen` wrappers → npm package (via `wasm-pack`). |
+| `js/` | Framework-agnostic camera glue + high-level `BarcodeScanner`. |
+| `docs/` | Integration guides (Angular, React, Capacitor, WASM bundling). |
+| `demo/` | Runnable apps: React, Angular, Capacitor (+ `examples/web`). |
+| `examples/web/` | Minimal browser demo driving the camera, zero build. |
+| `ROADMAP.md` | Staged build plan and current status of each pipeline stage. |
+
+## Status
+
+QR decoding works end-to-end from camera/image pixels: binarization (adaptive +
+Otsu), finder detection, affine + perspective sampling, format info, Reed-Solomon,
+and payload decode (numeric / alphanumeric / byte / ECI). Verified against
+generated QR codes across versions 1–27, all EC levels, and a real photographed
+thermal-receipt fixture. 1D symbologies and native FFI bindings are next — see
+`ROADMAP.md`.
+
+**New here? Start with [docs/getting-started.md](docs/getting-started.md).**
+
+## Build (once the Rust toolchain is installed)
+
+```bash
+# 1. Toolchain (one-time)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+cargo install wasm-pack
+
+# 2. Run core tests
+cargo test -p barcode-core
+
+# 3. Build the npm/WASM package
+wasm-pack build wasm --target web --out-dir pkg
+# → wasm/pkg/ is a ready-to-import ES module + .wasm
+```
+
+Then import from any framework:
+
+```ts
+import { BarcodeScanner } from "@cflorioluis/barcodereader";
+
+const scanner = new BarcodeScanner();
+await scanner.start((r) => console.log(r.format, r.text)); // call from a click
+```
+
+## Platform notes
+
+- **iOS Safari**: HTTPS (or localhost) + a user gesture to start. `playsinline`
+  is set on the video element (required).
+- **Android Chrome / desktop**: works out of the box on HTTPS/localhost.
+- **Capacitor**: runs in the WebView using the same WASM path.
+- **Electron**: same WASM path (Chromium runtime).

package/js/camera.d.ts

@@ -0,0 +1,66 @@
+export interface CameraOptions {
+    /** "environment" = rear camera (default for scanning), "user" = front.
+     *  Ignored when `deviceId` is set. */
+    facingMode?: "environment" | "user";
+    /** Open a specific camera by id (from `listCameras()`). Overrides facingMode. */
+    deviceId?: string;
+    /** Desired capture width; the browser may pick the nearest supported. */
+    width?: number;
+    height?: number;
+}
+export interface Frame {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+/** A camera the device exposes. `label` is empty until permission is granted. */
+export interface CameraInfo {
+    deviceId: string;
+    label: string;
+}
+/**
+ * Opens the camera and yields frames on demand. iOS constraints: must run on
+ * HTTPS (or localhost) and be started from a user gesture (a click/tap).
+ */
+export declare class CameraSource {
+    private stream;
+    private video;
+    private canvas;
+    private ctx;
+    private opts;
+    private keepAlive;
+    constructor();
+    private ensureAttached;
+    /** The live `<video>` element. Append it to the DOM to show the feed. */
+    get element(): HTMLVideoElement;
+    /** True while a camera stream is open. */
+    get active(): boolean;
+    start(opts?: CameraOptions): Promise<void>;
+    private open;
+    private stopTracks;
+    /** List available video cameras. Call after a first grant so labels fill in. */
+    listCameras(): Promise<CameraInfo[]>;
+    /** Switch to another camera without tearing down the video element. */
+    switchTo(deviceId: string): Promise<void>;
+    private videoTrack;
+    /** Whether the active camera supports the torch/flash (Android rear cameras;
+     *  not iOS Safari). Returns false if no camera is open. */
+    torchAvailable(): boolean;
+    /** Turn the torch on/off. Returns true if applied, false if unsupported. */
+    setTorch(on: boolean): Promise<boolean>;
+    /**
+     * Grab the current frame as a transferable `ImageBitmap`. This is GPU-backed
+     * and does no pixel copy on the main thread, so the heavy drawImage +
+     * getImageData work can be handed to a worker (via `OffscreenCanvas`) and the
+     * preview never stutters. The caller downscales when rasterising.
+     */
+    grabBitmap(): Promise<ImageBitmap>;
+    /**
+     * Grab the current frame as RGBA pixels, optionally downscaled so the largest
+     * side is at most `maxSize`. Decoding a full 1080p+ frame every tick saturates
+     * the main thread and makes the preview stutter; QR detection is happy at
+     * ~600–800px, which is far cheaper.
+     */
+    grab(maxSize?: number): Frame;
+    stop(): void;
+}

package/js/camera.js

@@ -0,0 +1,163 @@
+// Cross-platform camera glue for the web target.
+//
+// This is the "how each platform gets pixels" layer described in the README.
+// It uses only standard web APIs (getUserMedia + canvas), so it behaves the
+// same in Chrome (Android/desktop), Safari (iOS 14.3+), Electron and any
+// Capacitor WebView. It never touches decoding — it hands raw pixels to WASM.
+/**
+ * Opens the camera and yields frames on demand. iOS constraints: must run on
+ * HTTPS (or localhost) and be started from a user gesture (a click/tap).
+ */
+export class CameraSource {
+    constructor() {
+        this.stream = null;
+        this.opts = {};
+        this.keepAlive = null;
+        this.video = document.createElement("video");
+        this.video.setAttribute("playsinline", "true"); // required by iOS Safari
+        this.video.muted = true;
+        this.video.autoplay = true;
+        this.video.style.width = "100%";
+        this.video.style.height = "100%";
+        this.video.style.objectFit = "cover";
+        this.canvas = document.createElement("canvas");
+        const ctx = this.canvas.getContext("2d", { willReadFrequently: true });
+        if (!ctx)
+            throw new Error("2D canvas context unavailable");
+        this.ctx = ctx;
+    }
+    // A tiny, off-screen host that keeps the <video> attached to the DOM. Mobile
+    // browsers (iOS especially) pause a video that isn't in the document, which
+    // freezes frame capture — so we always park it here when the app isn't
+    // showing it. drawImage still reads full-resolution frames regardless of the
+    // element's on-screen size.
+    ensureAttached() {
+        if (typeof document === "undefined" || this.video.isConnected)
+            return;
+        if (!this.keepAlive) {
+            const host = document.createElement("div");
+            host.style.cssText =
+                "position:fixed;top:0;left:0;width:1px;height:1px;overflow:hidden;" +
+                    "opacity:0;pointer-events:none;z-index:-1;";
+            document.body.appendChild(host);
+            this.keepAlive = host;
+        }
+        this.keepAlive.appendChild(this.video);
+        void this.video.play().catch(() => { });
+    }
+    /** The live `<video>` element. Append it to the DOM to show the feed. */
+    get element() {
+        return this.video;
+    }
+    /** True while a camera stream is open. */
+    get active() {
+        return this.stream !== null;
+    }
+    async start(opts = {}) {
+        this.opts = opts;
+        await this.open();
+    }
+    async open() {
+        if (!navigator.mediaDevices?.getUserMedia) {
+            throw new Error("getUserMedia is not available in this environment");
+        }
+        const video = {
+            width: this.opts.width ? { ideal: this.opts.width } : undefined,
+            height: this.opts.height ? { ideal: this.opts.height } : undefined,
+        };
+        if (this.opts.deviceId) {
+            video.deviceId = { exact: this.opts.deviceId };
+        }
+        else {
+            video.facingMode = this.opts.facingMode ?? "environment";
+        }
+        this.stream = await navigator.mediaDevices.getUserMedia({ audio: false, video });
+        this.video.srcObject = this.stream;
+        this.ensureAttached(); // keep it live even if the app never shows it
+        await this.video.play();
+        this.canvas.width = this.video.videoWidth;
+        this.canvas.height = this.video.videoHeight;
+    }
+    stopTracks() {
+        this.stream?.getTracks().forEach((t) => t.stop());
+        this.stream = null;
+    }
+    /** List available video cameras. Call after a first grant so labels fill in. */
+    async listCameras() {
+        if (!navigator.mediaDevices?.enumerateDevices)
+            return [];
+        const devices = await navigator.mediaDevices.enumerateDevices();
+        return devices
+            .filter((d) => d.kind === "videoinput")
+            .map((d, i) => ({ deviceId: d.deviceId, label: d.label || `Camera ${i + 1}` }));
+    }
+    /** Switch to another camera without tearing down the video element. */
+    async switchTo(deviceId) {
+        this.opts = { ...this.opts, deviceId };
+        this.stopTracks();
+        await this.open();
+    }
+    videoTrack() {
+        return this.stream?.getVideoTracks()[0];
+    }
+    /** Whether the active camera supports the torch/flash (Android rear cameras;
+     *  not iOS Safari). Returns false if no camera is open. */
+    torchAvailable() {
+        const caps = this.videoTrack()?.getCapabilities?.();
+        return !!caps?.torch;
+    }
+    /** Turn the torch on/off. Returns true if applied, false if unsupported. */
+    async setTorch(on) {
+        const track = this.videoTrack();
+        if (!track || !this.torchAvailable())
+            return false;
+        await track.applyConstraints({ advanced: [{ torch: on }] });
+        return true;
+    }
+    /**
+     * Grab the current frame as a transferable `ImageBitmap`. This is GPU-backed
+     * and does no pixel copy on the main thread, so the heavy drawImage +
+     * getImageData work can be handed to a worker (via `OffscreenCanvas`) and the
+     * preview never stutters. The caller downscales when rasterising.
+     */
+    async grabBitmap() {
+        this.ensureAttached();
+        const { videoWidth: w, videoHeight: h } = this.video;
+        if (w === 0 || h === 0) {
+            throw new Error("Camera not ready yet");
+        }
+        return createImageBitmap(this.video);
+    }
+    /**
+     * Grab the current frame as RGBA pixels, optionally downscaled so the largest
+     * side is at most `maxSize`. Decoding a full 1080p+ frame every tick saturates
+     * the main thread and makes the preview stutter; QR detection is happy at
+     * ~600–800px, which is far cheaper.
+     */
+    grab(maxSize) {
+        // If the app removed the video from the DOM (e.g. "hide preview"), park it
+        // back in the keep-alive host so it keeps producing frames.
+        this.ensureAttached();
+        const { videoWidth: vw, videoHeight: vh } = this.video;
+        if (vw === 0 || vh === 0) {
+            throw new Error("Camera not ready yet");
+        }
+        const scale = maxSize ? Math.min(1, maxSize / Math.max(vw, vh)) : 1;
+        const w = Math.max(1, Math.round(vw * scale));
+        const h = Math.max(1, Math.round(vh * scale));
+        if (this.canvas.width !== w || this.canvas.height !== h) {
+            this.canvas.width = w;
+            this.canvas.height = h;
+        }
+        this.ctx.drawImage(this.video, 0, 0, w, h);
+        const img = this.ctx.getImageData(0, 0, w, h);
+        return { data: img.data, width: w, height: h };
+    }
+    stop() {
+        this.stopTracks();
+        this.video.srcObject = null;
+        // Tear down the keep-alive host so nothing lingers in the DOM.
+        this.keepAlive?.remove();
+        this.keepAlive = null;
+    }
+}

package/js/index.d.ts

@@ -0,0 +1,92 @@
+import { type CameraOptions, type CameraInfo } from "./camera.js";
+export interface ScanResult {
+    format: string;
+    text: string;
+}
+export type OnResult = (result: ScanResult) => void;
+/**
+ * Optional one-time configuration. Call before the first scan.
+ *
+ * `wasmPath` points at the `barcode_wasm_bg.wasm` binary. Set it when your
+ * bundler (Angular, webpack, some Vite setups) serves the WASM as a static
+ * asset instead of resolving the package's relative path — e.g. after copying
+ * `wasm/pkg/barcode_wasm_bg.wasm` into your app's assets:
+ *
+ *   configure({ wasmPath: "/assets/barcode_wasm_bg.wasm" });
+ */
+export declare function configure(opts: {
+    wasmPath?: string;
+}): void;
+/** Decode any drawable image source (image element, bitmap, canvas, video). */
+export declare function scanImageSource(source: CanvasImageSource, width: number, height: number): Promise<ScanResult[]>;
+/** Decode a still image from a File/Blob (e.g. an <input type=file>). */
+export declare function scanFile(file: Blob): Promise<ScanResult[]>;
+/** Decode a still image from a URL. */
+export declare function scanUrl(url: string): Promise<ScanResult[]>;
+export interface ScanOptions extends CameraOptions {
+    /** Stop the camera automatically after the first successful decode. Ideal
+     *  for the "scan a code, run one action, close" flow. Default: false. */
+    once?: boolean;
+    /** Suppress repeated identical results within this many milliseconds, so a
+     *  code held in view fires your action once, not every frame. Default: 1500.
+     *  Set to 0 to fire on every frame. */
+    dedupeMs?: number;
+    /** Downscale each frame to this max side before decoding. Keeps the preview
+     *  smooth on high-res phone cameras; QR detection is fine at this size.
+     *  Default: 800. */
+    maxScanSize?: number;
+    /** Minimum milliseconds between decode attempts. Decoding every animation
+     *  frame saturates the main thread and makes the preview lag; 10 fps is
+     *  plenty for scanning. Default: 100. */
+    scanIntervalMs?: number;
+    /** Decode in a Web Worker (off the main thread) so the preview never stutters.
+     *  Default: true. Falls back to the main thread automatically if a worker
+     *  can't be created. Set false to force main-thread decoding. */
+    useWorker?: boolean;
+    /** Restrict which symbologies fire `onResult`, by their `format` string
+     *  (e.g. `["QR"]`, `["EAN-13", "UPC-A"]`). Omit to accept every format. */
+    formats?: string[];
+}
+export declare class BarcodeScanner {
+    private camera;
+    private running;
+    private lastText;
+    private lastAt;
+    private lastDecodeAt;
+    private onResult;
+    private opts;
+    private worker;
+    private workerReady;
+    private workerOffscreen;
+    private busy;
+    /** The live `<video>` element — append it to the DOM to show the feed. */
+    get video(): HTMLVideoElement;
+    /** True while the camera is open and scanning. */
+    get active(): boolean;
+    /** List the device's cameras. Call after `start()` so labels are populated. */
+    listCameras(): Promise<CameraInfo[]>;
+    /** Switch to another camera by id (from `listCameras()`) while scanning. */
+    switchCamera(deviceId: string): Promise<void>;
+    /** Whether the active camera has a torch/flash (Android rear; not iOS). */
+    torchAvailable(): boolean;
+    /** Turn the torch on/off. Returns true if applied, false if unsupported. */
+    setTorch(on: boolean): Promise<boolean>;
+    /**
+     * Start scanning. `onResult` fires when a code is decoded — this is where you
+     * run your action (validate a ticket, open a URL, check someone in, ...).
+     *
+     * The library gives you the primitive; your UI (the button, the overlay) is
+     * entirely yours. A minimal "scan once then act" flow:
+     *
+     *   await scanner.start(r => myAction(r.text), { once: true });
+     */
+    start(onResult: OnResult, opts?: ScanOptions): Promise<void>;
+    private initWorker;
+    private now;
+    private hidden;
+    private handle;
+    private loop;
+    stop(): void;
+}
+export { CameraSource } from "./camera.js";
+export type { CameraOptions, CameraInfo } from "./camera.js";

package/js/index.js

@@ -0,0 +1,277 @@
+// High-level scanner API for the web target.
+//
+// Combines the WASM decoder with two pixel sources:
+//   * live camera (BarcodeScanner) — for real devices.
+//   * still images (scanImageSource / scanFile) — decode a photo, screenshot
+//     or uploaded file. Works everywhere, no camera needed.
+//
+// Any framework (Angular, React, Vue, Electron, Capacitor) can drive these.
+// The WASM module is loaded lazily and shared across both paths.
+import { CameraSource } from "./camera.js";
+let wasmPromise = null;
+let wasmPath;
+/**
+ * Optional one-time configuration. Call before the first scan.
+ *
+ * `wasmPath` points at the `barcode_wasm_bg.wasm` binary. Set it when your
+ * bundler (Angular, webpack, some Vite setups) serves the WASM as a static
+ * asset instead of resolving the package's relative path — e.g. after copying
+ * `wasm/pkg/barcode_wasm_bg.wasm` into your app's assets:
+ *
+ *   configure({ wasmPath: "/assets/barcode_wasm_bg.wasm" });
+ */
+export function configure(opts) {
+    wasmPath = opts.wasmPath;
+}
+async function wasm() {
+    if (!wasmPromise) {
+        wasmPromise = (async () => {
+            // Path is the wasm-pack output package, relative to this module.
+            const mod = (await import("../wasm/pkg/barcode_wasm.js"));
+            // With no explicit path the glue fetches the .wasm next to itself, which
+            // works for direct ES-module use and most Vite setups.
+            await mod.default(wasmPath ? { module_or_path: wasmPath } : undefined);
+            return mod;
+        })();
+    }
+    return wasmPromise;
+}
+// A canvas reused for still-image decoding.
+let scratch = null;
+function scratchCtx(w, h) {
+    scratch ?? (scratch = document.createElement("canvas"));
+    scratch.width = w;
+    scratch.height = h;
+    const ctx = scratch.getContext("2d", { willReadFrequently: true });
+    if (!ctx)
+        throw new Error("2D canvas context unavailable");
+    return ctx;
+}
+// Decode RGBA pixels on the main thread, returning plain objects and freeing
+// the wasm-bindgen results so they don't accumulate over a long session.
+async function decodeRgba(rgba, w, h) {
+    const m = await wasm();
+    const raw = m.scan_rgba(rgba, w, h);
+    return raw.map((r) => {
+        const out = { format: r.format, text: r.text };
+        r.free?.();
+        return out;
+    });
+}
+/** Decode any drawable image source (image element, bitmap, canvas, video). */
+export async function scanImageSource(source, width, height) {
+    const ctx = scratchCtx(width, height);
+    ctx.drawImage(source, 0, 0, width, height);
+    const img = ctx.getImageData(0, 0, width, height);
+    return decodeRgba(new Uint8Array(img.data.buffer), width, height);
+}
+/** Decode a still image from a File/Blob (e.g. an <input type=file>). */
+export async function scanFile(file) {
+    const bitmap = await createImageBitmap(file);
+    try {
+        return await scanImageSource(bitmap, bitmap.width, bitmap.height);
+    }
+    finally {
+        bitmap.close();
+    }
+}
+/** Decode a still image from a URL. */
+export async function scanUrl(url) {
+    const res = await fetch(url);
+    return scanFile(await res.blob());
+}
+export class BarcodeScanner {
+    constructor() {
+        this.camera = new CameraSource();
+        this.running = false;
+        this.lastText = "";
+        this.lastAt = 0;
+        this.lastDecodeAt = 0;
+        this.onResult = () => { };
+        this.opts = {};
+        this.worker = null;
+        this.workerReady = false;
+        this.workerOffscreen = false; // worker can rasterise ImageBitmaps itself
+        this.busy = false; // a frame is currently being decoded by the worker
+    }
+    /** The live `<video>` element — append it to the DOM to show the feed. */
+    get video() {
+        return this.camera.element;
+    }
+    /** True while the camera is open and scanning. */
+    get active() {
+        return this.camera.active;
+    }
+    /** List the device's cameras. Call after `start()` so labels are populated. */
+    listCameras() {
+        return this.camera.listCameras();
+    }
+    /** Switch to another camera by id (from `listCameras()`) while scanning. */
+    switchCamera(deviceId) {
+        return this.camera.switchTo(deviceId);
+    }
+    /** Whether the active camera has a torch/flash (Android rear; not iOS). */
+    torchAvailable() {
+        return this.camera.torchAvailable();
+    }
+    /** Turn the torch on/off. Returns true if applied, false if unsupported. */
+    setTorch(on) {
+        return this.camera.setTorch(on);
+    }
+    /**
+     * Start scanning. `onResult` fires when a code is decoded — this is where you
+     * run your action (validate a ticket, open a URL, check someone in, ...).
+     *
+     * The library gives you the primitive; your UI (the button, the overlay) is
+     * entirely yours. A minimal "scan once then act" flow:
+     *
+     *   await scanner.start(r => myAction(r.text), { once: true });
+     */
+    async start(onResult, opts = {}) {
+        this.onResult = onResult;
+        this.opts = opts;
+        await wasm(); // warms the still-image path + main-thread fallback
+        await this.camera.start(opts);
+        this.running = true;
+        this.lastText = "";
+        this.lastAt = 0;
+        this.lastDecodeAt = 0;
+        this.busy = false;
+        if (opts.useWorker !== false)
+            await this.initWorker();
+        this.loop();
+    }
+    // Spin up the decode worker and wait until its WASM is ready. On any failure
+    // (workers blocked, bundler couldn't emit it) we silently fall back to the
+    // main thread — scanning still works, just without the off-thread win.
+    async initWorker() {
+        try {
+            const worker = new Worker(new URL("./worker.js", import.meta.url), {
+                type: "module",
+            });
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => reject(new Error("worker init timeout")), 5000);
+                worker.addEventListener("message", (e) => {
+                    const data = e.data;
+                    if (data?.type === "ready") {
+                        this.workerOffscreen = data.offscreen === true;
+                        clearTimeout(timer);
+                        resolve();
+                    }
+                });
+                worker.addEventListener("error", (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                });
+                worker.postMessage({ type: "init", wasmPath });
+            });
+            worker.addEventListener("message", (e) => {
+                const data = e.data;
+                if (data?.type === "result") {
+                    this.busy = false;
+                    this.handle(data.results ?? []);
+                }
+            });
+            this.worker = worker;
+            this.workerReady = true;
+        }
+        catch {
+            this.worker = null;
+            this.workerReady = false;
+        }
+    }
+    now() {
+        return typeof performance !== "undefined" ? performance.now() : 0;
+    }
+    hidden() {
+        return typeof document !== "undefined" && document.hidden;
+    }
+    // Apply dedupe, fire the caller's action, honour `once`.
+    handle(results) {
+        const dedupeMs = this.opts.dedupeMs ?? 1500;
+        const formats = this.opts.formats;
+        for (const r of results) {
+            if (!r.text)
+                continue;
+            if (formats && formats.length > 0 && !formats.includes(r.format))
+                continue;
+            const t = this.now();
+            if (r.text === this.lastText && t - this.lastAt < dedupeMs)
+                continue;
+            this.lastText = r.text;
+            this.lastAt = t;
+            this.onResult(r);
+            if (this.opts.once) {
+                this.stop();
+                return;
+            }
+        }
+    }
+    async loop() {
+        if (!this.running)
+            return;
+        const intervalMs = this.opts.scanIntervalMs ?? 100;
+        const maxScanSize = this.opts.maxScanSize ?? 800;
+        const now = this.now();
+        // Pause decoding while the page is hidden — saves battery. The camera stays
+        // open so resuming is instant.
+        if (!this.hidden() && now - this.lastDecodeAt >= intervalMs) {
+            if (this.worker && this.workerReady && this.workerOffscreen && typeof createImageBitmap !== "undefined") {
+                // Lightest path: hand the worker a GPU-backed ImageBitmap and let it do
+                // the drawImage + getImageData on its own OffscreenCanvas. The main
+                // thread does almost nothing per frame, so the preview never stutters.
+                if (!this.busy) {
+                    this.busy = true;
+                    this.lastDecodeAt = now;
+                    this.camera
+                        .grabBitmap()
+                        .then((bitmap) => {
+                        this.worker.postMessage({ type: "decodeBitmap", bitmap, maxSize: maxScanSize }, [bitmap]);
+                    })
+                        .catch(() => {
+                        this.busy = false; // camera not ready yet
+                    });
+                }
+            }
+            else if (this.worker && this.workerReady) {
+                // Off-thread but no OffscreenCanvas: rasterise on the main thread and
+                // transfer the pixel buffer (zero-copy).
+                if (!this.busy) {
+                    try {
+                        const frame = this.camera.grab(maxScanSize);
+                        this.busy = true;
+                        this.lastDecodeAt = now;
+                        this.worker.postMessage({ type: "decode", buf: frame.data.buffer, w: frame.width, h: frame.height }, [frame.data.buffer]);
+                    }
+                    catch {
+                        this.busy = false; // camera not ready yet
+                    }
+                }
+            }
+            else {
+                // Main-thread fallback.
+                this.lastDecodeAt = now;
+                try {
+                    const frame = this.camera.grab(maxScanSize);
+                    const results = await decodeRgba(new Uint8Array(frame.data.buffer), frame.width, frame.height);
+                    this.handle(results);
+                }
+                catch {
+                    // not ready
+                }
+            }
+        }
+        requestAnimationFrame(() => this.loop());
+    }
+    stop() {
+        this.running = false;
+        this.busy = false;
+        this.camera.stop();
+        if (this.worker) {
+            this.worker.terminate();
+            this.worker = null;
+            this.workerReady = false;
+        }
+    }
+}
+export { CameraSource } from "./camera.js";

package/js/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/js/worker.js

@@ -0,0 +1,65 @@
+// Decoder Web Worker: runs the WASM decode OFF the main thread so the camera
+// preview never stutters, no matter how heavy a frame is.
+//
+// Two input paths:
+//   * decodeBitmap — the main thread transfers a GPU-backed ImageBitmap; this
+//     worker rasterises it on an OffscreenCanvas and reads the pixels here, so
+//     the (costly) drawImage + getImageData never touch the UI thread.
+//   * decode — a pre-rasterised RGBA buffer, transferred zero-copy. Fallback
+//     for engines without OffscreenCanvas.
+//
+// It also frees each wasm-bindgen `ScanResult` after reading it — otherwise the
+// Rust-side objects accumulate over a long session and the app slows down.
+import init, { scan_rgba } from "../wasm/pkg/barcode_wasm.js";
+const ctx = self;
+let ready = false;
+const hasOffscreen = typeof OffscreenCanvas !== "undefined";
+let canvas = null;
+let canvasCtx = null;
+function decodeRgba(rgba, w, h) {
+    const raw = scan_rgba(rgba, w, h);
+    return raw.map((r) => {
+        const out = { format: r.format, text: r.text };
+        r.free?.(); // release the Rust-side object deterministically
+        return out;
+    });
+}
+ctx.addEventListener("message", async (e) => {
+    const msg = e.data;
+    if (msg.type === "init") {
+        await init(msg.wasmPath ? { module_or_path: msg.wasmPath } : undefined);
+        ready = true;
+        ctx.postMessage({ type: "ready", offscreen: hasOffscreen });
+        return;
+    }
+    if (msg.type === "decode") {
+        const results = ready ? decodeRgba(new Uint8Array(msg.buf), msg.w, msg.h) : [];
+        ctx.postMessage({ type: "result", results });
+        return;
+    }
+    if (msg.type === "decodeBitmap") {
+        let results = [];
+        if (ready && hasOffscreen) {
+            const bmp = msg.bitmap;
+            const scale = Math.min(1, msg.maxSize / Math.max(bmp.width, bmp.height));
+            const w = Math.max(1, Math.round(bmp.width * scale));
+            const h = Math.max(1, Math.round(bmp.height * scale));
+            if (!canvas) {
+                canvas = new OffscreenCanvas(w, h);
+                canvasCtx = canvas.getContext("2d", {
+                    willReadFrequently: true,
+                });
+            }
+            canvas.width = w;
+            canvas.height = h;
+            canvasCtx.drawImage(bmp, 0, 0, w, h);
+            bmp.close();
+            const img = canvasCtx.getImageData(0, 0, w, h);
+            results = decodeRgba(new Uint8Array(img.data.buffer), w, h);
+        }
+        else {
+            msg.bitmap.close?.();
+        }
+        ctx.postMessage({ type: "result", results });
+    }
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@cflorioluis/barcodereader",
+  "version": "0.1.0",
+  "description": "Dependency-free 1D/2D barcode & QR decoder. One Rust core, WASM for web (Angular/React/Vue/Electron/Capacitor), native FFI later.",
+  "type": "module",
+  "main": "js/index.js",
+  "types": "js/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./js/index.d.ts",
+      "default": "./js/index.js"
+    }
+  },
+  "files": ["js/**/*.js", "js/**/*.d.ts", "wasm/pkg", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:wasm": "wasm-pack build wasm --target web --out-dir pkg && rm -f wasm/pkg/.gitignore",
+    "build:js": "tsc -p tsconfig.json",
+    "build": "npm run build:wasm && npm run build:js",
+    "prepublishOnly": "npm run build",
+    "test:core": "cargo test -p barcode-core"
+  },
+  "keywords": ["qr", "barcode", "scanner", "wasm", "rust", "camera"],
+  "license": "MIT"
+}

package/wasm/pkg/barcode_wasm.d.ts

@@ -0,0 +1,74 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A decoded symbol, shaped for JS consumption.
+ */
+export class ScanResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Symbology, e.g. "QR".
+     */
+    format: string;
+    /**
+     * Decoded text payload.
+     */
+    text: string;
+}
+
+/**
+ * Decode barcodes from a grayscale luminance buffer (one byte per pixel).
+ *
+ * Callers that have RGBA (e.g. from a `<canvas>` `ImageData`) should use
+ * `scan_rgba` instead, which converts to luminance first.
+ */
+export function scan_luma(pixels: Uint8Array, width: number, height: number): ScanResult[];
+
+/**
+ * Decode barcodes directly from RGBA pixels (canvas `ImageData.data`).
+ * Converts to luminance with the Rec. 601 weights, then decodes.
+ */
+export function scan_rgba(rgba: Uint8Array, width: number, height: number): ScanResult[];
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_get_scanresult_format: (a: number) => [number, number];
+    readonly __wbg_get_scanresult_text: (a: number) => [number, number];
+    readonly __wbg_scanresult_free: (a: number, b: number) => void;
+    readonly __wbg_set_scanresult_format: (a: number, b: number, c: number) => void;
+    readonly __wbg_set_scanresult_text: (a: number, b: number, c: number) => void;
+    readonly scan_luma: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly scan_rgba: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __externref_drop_slice: (a: number, b: number) => void;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;

package/wasm/pkg/barcode_wasm.js

@@ -0,0 +1,337 @@
+/* @ts-self-types="./barcode_wasm.d.ts" */
+
+/**
+ * A decoded symbol, shaped for JS consumption.
+ */
+export class ScanResult {
+    static __wrap(ptr) {
+        const obj = Object.create(ScanResult.prototype);
+        obj.__wbg_ptr = ptr;
+        ScanResultFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ScanResultFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_scanresult_free(ptr, 0);
+    }
+    /**
+     * Symbology, e.g. "QR".
+     * @returns {string}
+     */
+    get format() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.__wbg_get_scanresult_format(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Decoded text payload.
+     * @returns {string}
+     */
+    get text() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.__wbg_get_scanresult_text(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Symbology, e.g. "QR".
+     * @param {string} arg0
+     */
+    set format(arg0) {
+        const ptr0 = passStringToWasm0(arg0, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.__wbg_set_scanresult_format(this.__wbg_ptr, ptr0, len0);
+    }
+    /**
+     * Decoded text payload.
+     * @param {string} arg0
+     */
+    set text(arg0) {
+        const ptr0 = passStringToWasm0(arg0, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.__wbg_set_scanresult_text(this.__wbg_ptr, ptr0, len0);
+    }
+}
+if (Symbol.dispose) ScanResult.prototype[Symbol.dispose] = ScanResult.prototype.free;
+
+/**
+ * Decode barcodes from a grayscale luminance buffer (one byte per pixel).
+ *
+ * Callers that have RGBA (e.g. from a `<canvas>` `ImageData`) should use
+ * `scan_rgba` instead, which converts to luminance first.
+ * @param {Uint8Array} pixels
+ * @param {number} width
+ * @param {number} height
+ * @returns {ScanResult[]}
+ */
+export function scan_luma(pixels, width, height) {
+    const ptr0 = passArray8ToWasm0(pixels, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.scan_luma(ptr0, len0, width, height);
+    var v2 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v2;
+}
+
+/**
+ * Decode barcodes directly from RGBA pixels (canvas `ImageData.data`).
+ * Converts to luminance with the Rec. 601 weights, then decodes.
+ * @param {Uint8Array} rgba
+ * @param {number} width
+ * @param {number} height
+ * @returns {ScanResult[]}
+ */
+export function scan_rgba(rgba, width, height) {
+    const ptr0 = passArray8ToWasm0(rgba, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.scan_rgba(ptr0, len0, width, height);
+    var v2 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v2;
+}
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_throw_344f42d3211c4765: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_scanresult_new: function(arg0) {
+            const ret = ScanResult.__wrap(arg0);
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./barcode_wasm_bg.js": import0,
+    };
+}
+
+const ScanResultFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_scanresult_free(ptr, 1));
+
+function getArrayJsValueFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    const mem = getDataViewMemory0();
+    const result = [];
+    for (let i = ptr; i < ptr + 4 * len; i += 4) {
+        result.push(wasm.__wbindgen_externrefs.get(mem.getUint32(i, true)));
+    }
+    wasm.__externref_drop_slice(ptr, len);
+    return result;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasmInstance, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedDataViewMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    wasm.__wbindgen_start();
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = module.ok && expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('barcode_wasm_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/wasm/pkg/barcode_wasm_bg.wasm.d.ts

@@ -0,0 +1,16 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_get_scanresult_format: (a: number) => [number, number];
+export const __wbg_get_scanresult_text: (a: number) => [number, number];
+export const __wbg_scanresult_free: (a: number, b: number) => void;
+export const __wbg_set_scanresult_format: (a: number, b: number, c: number) => void;
+export const __wbg_set_scanresult_text: (a: number, b: number, c: number) => void;
+export const scan_luma: (a: number, b: number, c: number, d: number) => [number, number];
+export const scan_rgba: (a: number, b: number, c: number, d: number) => [number, number];
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __externref_drop_slice: (a: number, b: number) => void;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_start: () => void;

package/wasm/pkg/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "barcode-wasm",
+  "type": "module",
+  "description": "WASM bindings for barcode-core (wasm-pack -> npm).",
+  "version": "0.1.0",
+  "license": "MIT",
+  "files": [
+    "barcode_wasm_bg.wasm",
+    "barcode_wasm.js",
+    "barcode_wasm.d.ts"
+  ],
+  "main": "barcode_wasm.js",
+  "types": "barcode_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}