tapirscan 1.2.1 → 1.3.0

package/dist/multiformat/formats.js

@@ -1,44 +1,10 @@
 /** Explicit opt-in formats for the independent Medium extension. */
-export const formatBits = {
-    EAN13: 1,
-    UPCA: 2,
-    EAN8: 4,
-    UPCE: 8,
-    Code128: 16,
-    Code39: 32,
-    ITF: 64,
-    Codabar: 128,
-    Code93: 256,
-    QRCode: 512,
-    DataMatrix: 1024,
-    PDF417: 2048,
-    Aztec: 4096,
-    DataBar: 8192,
-    DataBarExpanded: 16384,
-    MaxiCode: 131072,
-};
-export const retailFormats = ["EAN13", "UPCA", "EAN8", "UPCE"];
-export const commonLinearFormats = [
-    ...retailFormats,
-    "Code128",
-    "Code39",
-    "ITF",
-];
-export const commonFormats = [...commonLinearFormats, "QRCode", "DataMatrix"];
-export const linearFormats = [
-    ...commonLinearFormats,
-    "Codabar",
-    "Code93",
-    "DataBar",
-    "DataBarExpanded",
-];
-export const matrixFormats = [
-    "QRCode",
-    "DataMatrix",
-    "PDF417",
-    "Aztec",
-    "MaxiCode",
-];
+import { commonFormats, commonLinearFormats, formatBits, linearFormats, matrixFormats, retailFormats, } from "./format-registry.js";
+export { commonFormats, commonLinearFormats, formatBits, linearFormats, matrixFormats, retailFormats, };
+/** Own-property check that works in Chrome 91 (`Object.hasOwn` needs Chrome 93). */
+export function hasKey(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
 export function resolveFormats(input) {
     if (input === "retail")
         return [...retailFormats];
@@ -54,15 +20,18 @@ export function resolveFormats(input) {
         return [...linearFormats, ...matrixFormats];
     if (input === undefined)
         return [...retailFormats];
-    if (typeof input === "string" && Object.hasOwn(formatBits, input))
-        return [input];
+    if (typeof input === "string") {
+        if (hasKey(formatBits, input))
+            return [input];
+        throw new TypeError(`Unsupported barcode format or preset: ${input}`);
+    }
     if (!Array.isArray(input) || input.length === 0)
-        throw Error("Choose at least one barcode format.");
+        throw new TypeError("Choose at least one barcode format.");
     for (const value of input) {
         if (typeof value !== "string")
-            throw Error("Barcode format must be a string.");
-        if (!Object.hasOwn(formatBits, value))
-            throw Error(`Unsupported barcode format: ${value}`);
+            throw new TypeError("Barcode format must be a string.");
+        if (!hasKey(formatBits, value))
+            throw new TypeError(`Unsupported barcode format: ${value}`);
     }
     return [...new Set(input)];
 }

package/dist/rust-session.d.ts

@@ -0,0 +1,19 @@
+export declare class ScannerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class RustScannerSession {
+    private exports;
+    private handle;
+    private constructor();
+    static create(bytes: ArrayBuffer, mode: number, formats: number, addOnPolicy: number, experimentalTurbo?: number): Promise<RustScannerSession>;
+    scan(image: {
+        data: Uint8Array;
+        width: number;
+        height: number;
+        channels: number;
+        stride: number;
+    }, flags: number, formats: number): unknown;
+    dispose(): void;
+    private activeExports;
+}

package/dist/rust-session.js

@@ -0,0 +1,102 @@
+// Stateless for complete inputs, so one decoder serves every scan.
+const outputDecoder = new TextDecoder();
+export class ScannerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ScannerError";
+    }
+}
+const exportNames = [
+    "tapirscan_abi_version",
+    "tapirscan_mode",
+    "tapirscan_create",
+    "tapirscan_destroy",
+    "tapirscan_prepare",
+    "tapirscan_input_ptr",
+    "tapirscan_input_len",
+    "tapirscan_scan",
+    "tapirscan_output_ptr",
+    "tapirscan_output_len",
+];
+function status(code, operation) {
+    if (code === 0)
+        return;
+    const names = {
+        1: "invalid_input",
+        2: "disposed",
+        4: "engine",
+        5: "capacity",
+    };
+    throw new ScannerError(names[code] ?? `core_${String(code)}`, `${operation} failed (${String(code)})`);
+}
+export class RustScannerSession {
+    exports;
+    handle;
+    constructor(exports, handle) {
+        this.exports = exports;
+        this.handle = handle;
+    }
+    static async create(bytes, mode, formats, addOnPolicy, experimentalTurbo = 0) {
+        const instance = await WebAssembly.instantiate(bytes, {});
+        const exports = instance.instance.exports;
+        if (!(exports.memory instanceof WebAssembly.Memory))
+            throw new ScannerError("abi_shape", "Missing WASM memory");
+        for (const name of exportNames)
+            if (typeof exports[name] !== "function")
+                throw new ScannerError("abi_shape", `Missing WASM export: ${name}`);
+        if (exports.tapirscan_abi_version() !== 2)
+            throw new ScannerError("abi_version", "Unsupported scanner ABI");
+        if (exports.tapirscan_mode() !== mode)
+            throw new ScannerError("abi_mode", "Scanner WASM mode does not match the requested mode");
+        const tier = exports.tapirscan_experimental_turbo;
+        const actualTurbo = typeof tier === "function" ? tier() : 0;
+        if (actualTurbo !== experimentalTurbo)
+            throw new ScannerError("abi_turbo", "Scanner WASM does not match the requested experimentalTurbo preset");
+        const handle = exports.tapirscan_create(mode, formats, addOnPolicy);
+        if (!handle)
+            throw new ScannerError("capacity", "Could not create scanner session");
+        return new RustScannerSession(exports, handle);
+    }
+    scan(image, flags, formats) {
+        const exports = this.activeExports();
+        status(exports.tapirscan_prepare(this.handle, image.width, image.height, image.channels, image.stride), "Image preparation");
+        const length = exports.tapirscan_input_len(this.handle);
+        const expected = (image.height - 1) * image.stride + image.width * image.channels;
+        if (length !== expected)
+            throw new ScannerError("abi_shape", "Input allocation mismatch");
+        new Uint8Array(exports.memory.buffer, exports.tapirscan_input_ptr(this.handle), length).set(image.data.subarray(0, length));
+        const result = exports.tapirscan_scan(this.handle, flags, formats);
+        const output = new Uint8Array(exports.memory.buffer, exports.tapirscan_output_ptr(this.handle), exports.tapirscan_output_len(this.handle));
+        let decoded;
+        try {
+            decoded = JSON.parse(outputDecoder.decode(output));
+        }
+        catch {
+            throw new ScannerError("invalid_output", "Scanner returned invalid JSON");
+        }
+        if (result !== 0) {
+            const message = decoded && typeof decoded === "object" && "error" in decoded
+                ? String(decoded.error)
+                : `Scan failed (${String(result)})`;
+            throw new ScannerError(result === 4 ? "engine" : `core_${String(result)}`, message);
+        }
+        return decoded;
+    }
+    dispose() {
+        if (!this.handle || !this.exports)
+            return;
+        const exports = this.exports;
+        const handle = this.handle;
+        // WASM memory never shrinks: drop the instance so a retained scanner frees it.
+        this.exports = undefined;
+        this.handle = 0;
+        status(exports.tapirscan_destroy(handle), "Scanner disposal");
+    }
+    activeExports() {
+        if (!this.handle || !this.exports)
+            throw new ScannerError("disposed", "Scanner is disposed");
+        return this.exports;
+    }
+}

package/examples/camera.html

@@ -1,60 +1,59 @@
 <!doctype html>
 <html lang="en">
   <meta charset="utf-8" />
-  <title>Tapirscan worker example</title>
+  <title>Tapirscan camera example</title>
   <button id="start">Start camera</button>
   <button id="stop" disabled>Stop</button>
   <video autoplay muted playsinline style="max-width: 100%"></video>
   <pre role="status"></pre>
   <script type="module">
-    import { createScannerWorker } from "./worker-client.mjs";
+    // Serve this package directory and open /examples/camera.html on localhost.
+    import { Scanner } from "../dist/browser.js";
     const video = document.querySelector("video");
     const status = document.querySelector("pre");
     const start = document.querySelector("#start");
     const stop = document.querySelector("#stop");
-    const canvas = document.createElement("canvas");
-    const context = canvas.getContext("2d", { willReadFrequently: true });
-    let running = false;
     let scanner;
     let stream;
+
     function shutdown() {
-      running = false;
       scanner?.dispose();
-      scanner = undefined;
       stream?.getTracks().forEach((track) => track.stop());
-      stream = undefined;
+      scanner = stream = undefined;
       video.srcObject = null;
+      start.disabled = false;
+      stop.disabled = true;
     }
+
     start.onclick = async () => {
       start.disabled = true;
-      running = true;
+      let current;
       try {
-        scanner = await createScannerWorker({ formats: ["EAN13", "QRCode"] });
-        if (!running) return;
-        stream = await navigator.mediaDevices.getUserMedia({
+        // Loads in a worker while the camera starts.
+        current = scanner = new Scanner({ formats: ["EAN13", "QRCode"] });
+        const camera = await navigator.mediaDevices.getUserMedia({
           video: { facingMode: "environment" },
         });
-        if (!running) return;
+        if (scanner !== current) {
+          camera.getTracks().forEach((track) => track.stop());
+          return;
+        }
+        stream = camera;
         video.srcObject = stream;
-        await video.play();
         stop.disabled = false;
-        while (running) {
-          canvas.width = video.videoWidth;
-          canvas.height = video.videoHeight;
-          context.drawImage(video, 0, 0);
-          const result = await scanner.scan(
-            context.getImageData(0, 0, canvas.width, canvas.height),
-          );
-          status.textContent = JSON.stringify(result.values);
-          // Backpressure: capture only after the previous scan has completed.
-          await new Promise(requestAnimationFrame);
+        while (scanner === current) {
+          // Scan each new frame at most once; awaiting the scan avoids a backlog.
+          await new Promise((resolve) => video.requestVideoFrameCallback(resolve));
+          if (scanner !== current) break;
+          const barcodes = await current.scan(video);
+          if (scanner === current) status.textContent = JSON.stringify(barcodes.values);
         }
       } catch (error) {
-        if (running) status.textContent = error.message;
-      } finally {
-        shutdown();
-        start.disabled = false;
-        stop.disabled = true;
+        // Also reached when construction fails: report it and re-enable Start.
+        if (scanner === current) {
+          status.textContent = error.message;
+          shutdown();
+        }
       }
     };
     stop.onclick = shutdown;

package/examples/vite/README.md

@@ -0,0 +1,31 @@
+# Vite example
+
+Copy this directory into your application workspace, then run:
+
+```sh
+npm install
+npm run dev
+```
+
+Choose a barcode photo. `tapirscan/browser` decodes the file and scans it in a
+worker; Vite bundles the worker and WASM files without plugins or copy steps.
+The only configuration is `optimizeDeps.exclude` in `vite.config.js`, which the
+development server needs to serve those files from the package. Retail formats
+are enabled by default.
+
+To test a locally built package, install its npm tarball instead of
+the registry dependency before running the example:
+
+```sh
+npm install /absolute/path/to/tapirscan-X.Y.Z.tgz
+```
+
+Test production hosting, including a subpath:
+
+```sh
+npm run build -- --base=/scanner/
+npm run preview -- --base=/scanner/
+```
+
+Open `/scanner/` on the preview server. For Svelte and SvelteKit, see the
+[package README](../../README.md#browser-apps-react-and-svelte).

package/examples/vite/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Tapirscan with Vite</title>
+  </head>
+  <body>
+    <h1>Scan a barcode photo</h1>
+    <input type="file" accept="image/*" aria-label="Barcode photo" disabled />
+    <pre role="status">Loading scanner…</pre>
+    <script type="module" src="/main.js"></script>
+  </body>
+</html>

package/examples/vite/main.js

@@ -0,0 +1,33 @@
+import { Scanner } from "tapirscan/browser";
+
+const input = document.querySelector("input");
+const status = document.querySelector('[role="status"]');
+// Scanning runs in a worker, so the page stays responsive.
+const scanner = new Scanner();
+
+scanner.ready.then(
+  () => {
+    input.disabled = false;
+    status.textContent = "Choose a photo.";
+  },
+  (error) => {
+    status.textContent = error.message;
+  },
+);
+// Only the latest selection may update the page; scans can finish out of order.
+let latest = 0;
+input.onchange = async () => {
+  const file = input.files[0];
+  if (!file) return;
+  const request = ++latest;
+  status.textContent = "Scanning…";
+  try {
+    const { barcodes } = await scanner.scan(file);
+    if (request !== latest) return;
+    status.textContent = barcodes.length
+      ? barcodes.map((barcode) => `${barcode.format} ${barcode.text}`).join("\n")
+      : "No barcode found.";
+  } catch (error) {
+    if (request === latest) status.textContent = error.message;
+  }
+};

package/examples/vite/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "tapirscan-vite-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "tapirscan": "^1.3.0"
+  },
+  "devDependencies": {
+    "vite": "^6.3.5"
+  }
+}

package/examples/vite/vite.config.js

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  // The dev server must serve Tapirscan's worker and WASM files from the package.
+  optimizeDeps: { exclude: ["tapirscan"] },
+});

package/package.json

@@ -1,31 +1,48 @@
 {
   "name": "tapirscan",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "type": "module",
   "description": "Orientation-aware barcode scanning with a Rust/WASM core and four effort modes",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./wasm/low.wasm": "./wasm/low.wasm",
+    "./wasm/medium.wasm": "./wasm/medium.wasm",
+    "./wasm/high.wasm": "./wasm/high.wasm",
+    "./wasm/very-high.wasm": "./wasm/very-high.wasm",
+    "./wasm/experimental-turbo2.wasm": "./wasm/experimental-turbo2.wasm",
+    "./wasm/experimental-turbo4.wasm": "./wasm/experimental-turbo4.wasm",
+    "./wasm/experimental-turbo8.wasm": "./wasm/experimental-turbo8.wasm",
+    "./wasm/experimental-turbo16.wasm": "./wasm/experimental-turbo16.wasm"
   },
   "files": [
     "dist",
     "examples",
-    "wasm/multiformat.json",
     "THIRD_PARTY_NOTICES.md",
-    "wasm/low-shared-retail-portable-20260919.wasm",
-    "wasm/medium-shared-retail-portable-20260919.wasm",
-    "wasm/high-shared-retail-portable-20260919.wasm",
-    "wasm/very-high-shared-retail-portable-20260919.wasm",
-    "wasm/multiformat.wasm"
+    "wasm/low.wasm",
+    "wasm/medium.wasm",
+    "wasm/high.wasm",
+    "wasm/very-high.wasm",
+    "wasm/experimental-turbo2.wasm",
+    "wasm/experimental-turbo4.wasm",
+    "wasm/experimental-turbo8.wasm",
+    "wasm/experimental-turbo16.wasm",
+    "wasm/build.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "node --test test/scanner.mjs test/linear-duplicates.mjs test/shared-retail.mjs && tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext test/api-types.ts",
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "test": "node --test test/camera-example.mjs test/scanner.mjs test/shared-retail.mjs test/loading.mjs test/turbo.mjs test/packaging.mjs && tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext test/api-types.ts",
+    "test:browser": "node --test --test-timeout=120000 test/browser.mjs",
     "prepack": "npm run build && node scripts/verify-package.mjs"
   },
   "devDependencies": {
+    "playwright-core": "1.63.0",
     "typescript": "5.8.3"
   },
   "keywords": [
@@ -39,7 +56,7 @@
   "engines": {
     "node": ">=20"
   },
-  "license": "MIT",
+  "license": "MIT OR Apache-2.0",
   "author": "Florian Nick",
   "repository": {
     "type": "git",