tapirscan 1.2.2 → 1.3.0

package/dist/browser-worker.d.ts

@@ -0,0 +1,33 @@
+import { type EanAddOnPolicy, type ExperimentalTurbo, type FormatSelection, type Mode, type PixelImage, type ScanOptions } from "./index.js";
+/** Scanner options that can cross the worker boundary. */
+export interface WorkerScannerOptions {
+    mode?: Mode;
+    formats?: FormatSelection;
+    eanAddOnPolicy?: EanAddOnPolicy;
+    experimentalTurbo?: ExperimentalTurbo;
+    /** Absolute URL of a directory serving the packaged WASM files. */
+    wasmBaseUrl?: string;
+}
+/** Inputs that are cheap to send: everything else becomes an ImageBitmap first. */
+export type WorkerSource = Blob | ImageBitmap | PixelImage;
+export type WorkerRequest = {
+    id: number;
+    type: "create";
+    options: WorkerScannerOptions;
+} | {
+    id: number;
+    type: "scan" | "inspect";
+    source: WorkerSource;
+    options: ScanOptions;
+};
+export type WorkerResponse = {
+    id: number;
+    value: unknown;
+} | {
+    id: number;
+    error: {
+        name: string;
+        message: string;
+        code?: string;
+    };
+};

package/dist/browser-worker.js

@@ -0,0 +1,83 @@
+// Worker side of tapirscan/browser: one core Scanner, fed with decoded pixels.
+import { Scanner, } from "./index.js";
+// Literal URLs let bundlers such as Vite and webpack emit these assets without
+// configuration. Keep the file names in sync with index.ts (verify-package checks).
+const wasm = {
+    low: new URL("../wasm/low.wasm", import.meta.url),
+    medium: new URL("../wasm/medium.wasm", import.meta.url),
+    high: new URL("../wasm/high.wasm", import.meta.url),
+    "very-high": new URL("../wasm/very-high.wasm", import.meta.url),
+};
+const turboWasm = {
+    2: new URL("../wasm/experimental-turbo2.wasm", import.meta.url),
+    4: new URL("../wasm/experimental-turbo4.wasm", import.meta.url),
+    8: new URL("../wasm/experimental-turbo8.wasm", import.meta.url),
+    16: new URL("../wasm/experimental-turbo16.wasm", import.meta.url),
+};
+// Typed locally: the DOM and WebWorker libraries cannot share one compilation.
+const scope = globalThis;
+let scanner;
+async function load(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`WASM load failed: ${String(response.status)} ${url.href}`);
+    return response.arrayBuffer();
+}
+/** Decode a Blob or ImageBitmap onto white RGBA pixels; pixel inputs pass through. */
+async function pixels(source) {
+    if (!(source instanceof Blob) && !(source instanceof ImageBitmap))
+        return source;
+    const bitmap = source instanceof Blob ? await createImageBitmap(source) : source;
+    try {
+        const { width, height } = bitmap;
+        // Reject before allocating a canvas; the scanner enforces the same limits.
+        if (width < 3 || height < 3 || width * height > 32 * 1024 * 1024)
+            throw new TypeError(`Images must be 3×3 to 32 megapixels, got ${String(width)}×${String(height)}`);
+        const context = new OffscreenCanvas(width, height).getContext("2d", {
+            willReadFrequently: true,
+        });
+        if (!context)
+            throw new Error("2D canvas is unavailable in this browser's workers");
+        // Composite onto white, as images are displayed: the scanner ignores alpha, so
+        // transparent areas would otherwise read as black.
+        context.fillStyle = "#fff";
+        context.fillRect(0, 0, width, height);
+        context.drawImage(bitmap, 0, 0);
+        return context.getImageData(0, 0, width, height);
+    }
+    finally {
+        bitmap.close();
+    }
+}
+async function handle(request) {
+    if (request.type === "create") {
+        const { wasmBaseUrl, ...options } = request.options;
+        const { experimentalTurbo: turbo, mode = "medium" } = options;
+        // The core validates options before loading; a custom base URL uses its loader.
+        // Invalid modes or presets fail validation, so the lookup below is never used for them.
+        const asset = turbo === undefined ? wasm[mode] : turboWasm[turbo];
+        scanner = await Scanner.create(wasmBaseUrl === undefined
+            ? { ...options, loadWasm: () => load(asset) }
+            : { ...options, wasmBaseUrl });
+        return { mode: scanner.mode, formats: scanner.formats, eanAddOnPolicy: scanner.eanAddOnPolicy };
+    }
+    if (!scanner)
+        throw new Error("Scanner is not created");
+    const image = await pixels(request.source);
+    return request.type === "scan"
+        ? scanner.scan(image, request.options)
+        : scanner.inspect(image, request.options);
+}
+scope.onmessage = ({ data: request }) => {
+    handle(request).then((value) => {
+        scope.postMessage({ id: request.id, value });
+    }, (error) => {
+        const { name, message, code } = error instanceof Error
+            ? error
+            : { name: "Error", message: String(error), code: undefined };
+        scope.postMessage({
+            id: request.id,
+            error: { name, message, ...(typeof code === "string" ? { code } : {}) },
+        });
+    });
+};

package/dist/browser.d.ts

@@ -0,0 +1,44 @@
+import type { EanAddOnPolicy, ExperimentalTurbo, FormatSelection, Mode, PixelImage, ScanOptions, InspectionResult, ScanResult } from "./index.js";
+export { ScannerError } from "./rust-session.js";
+export type { Barcode, DiagnosticBarcode, Diagnostics, EanAddOnPolicy, ExperimentalTurbo, Format, FormatSelection, Image, Mode, PixelImage, Quad, RegionEvidence, ScanOptions, InspectionResult, ScanResult, StructuredAppend, UndecodedRegion, } from "./index.js";
+/**
+ * A file or blob (JPEG, PNG and other browser-decodable images), an `<img>`,
+ * `<video>` (its current frame), canvas, `ImageBitmap`, `VideoFrame`, `ImageData`
+ * or decoded pixels.
+ */
+export type ImageSource = ImageBitmapSource | PixelImage;
+export interface ScannerOptions {
+    /** Effort; defaults to "medium". */
+    mode?: Mode;
+    /** Formats to read; defaults to retail EAN/UPC. */
+    formats?: FormatSelection;
+    /** EAN/UPC supplement policy; defaults to "ignore". */
+    eanAddOnPolicy?: EanAddOnPolicy;
+    /** @experimental Faster 1D preset instead of a mode; may change in minor releases. */
+    experimentalTurbo?: ExperimentalTurbo;
+    /** Serve the packaged WASM files from another directory, such as a CDN. */
+    wasmBaseUrl?: string | URL;
+}
+/**
+ * A reusable scanner running in a dedicated worker, so scanning never blocks the
+ * page. Construction is synchronous and starts loading in the background; during
+ * server rendering it does nothing. Inputs and options are captured when a call
+ * starts, and calls reach the worker in call order. Results are deeply frozen and
+ * survive disposal. Call dispose() when done to stop the worker.
+ */
+export declare class Scanner {
+    #private;
+    /** Resolves once the scanner is loaded; rejects with the loading error. Optional. */
+    readonly ready: Promise<void>;
+    constructor(options?: ScannerOptions);
+    /** Decode barcodes with source-image positions. No detection returns empty values and barcodes. */
+    scan(source: ImageSource, options?: ScanOptions): Promise<ScanResult>;
+    /** Scan with unread regions, timing and engine diagnostics. */
+    inspect(source: ImageSource, options?: ScanOptions): Promise<InspectionResult>;
+    /** Stop the worker and reject queued scans. Repeated disposal is safe. */
+    dispose(): void;
+}
+/** Scan one image with a temporary scanner. Reuse a Scanner for several images. */
+export declare function scan(source: ImageSource, options?: ScannerOptions): Promise<ScanResult>;
+/** Inspect one image with a temporary scanner. */
+export declare function inspect(source: ImageSource, options?: ScannerOptions): Promise<InspectionResult>;

package/dist/browser.js

@@ -0,0 +1,211 @@
+import { freeze } from "./freeze.js";
+import { pixelLayout } from "./layout.js";
+import { ScannerError } from "./rust-session.js";
+export { ScannerError } from "./rust-session.js";
+const scannerOptions = ["mode", "formats", "eanAddOnPolicy", "experimentalTurbo", "wasmBaseUrl"];
+function revive({ name, message, code }) {
+    if (code !== undefined)
+        return new ScannerError(code, message);
+    return name === "TypeError" ? new TypeError(message) : new Error(message);
+}
+/** Snapshot mutable inputs before the first await; Blobs are immutable. */
+async function prepare(source) {
+    const input = source;
+    if (input === null || typeof input !== "object")
+        throw new TypeError("Expected an image source");
+    if (source instanceof Blob)
+        return [source, []];
+    if ("data" in source) {
+        // Validate first, then copy only the addressed rows of a larger backing buffer.
+        const { data, width, height, channels, stride, addressed } = pixelLayout(source);
+        const copy = new Uint8Array(data.subarray(0, addressed));
+        return [{ data: copy, width, height, channels, stride }, [copy.buffer]];
+    }
+    // A copy, so a caller's ImageBitmap stays usable after it is transferred.
+    const bitmap = await createImageBitmap(source);
+    return [bitmap, [bitmap]];
+}
+/**
+ * A reusable scanner running in a dedicated worker, so scanning never blocks the
+ * page. Construction is synchronous and starts loading in the background; during
+ * server rendering it does nothing. Inputs and options are captured when a call
+ * starts, and calls reach the worker in call order. Results are deeply frozen and
+ * survive disposal. Call dispose() when done to stop the worker.
+ */
+export class Scanner {
+    /** Resolves once the scanner is loaded; rejects with the loading error. Optional. */
+    ready;
+    #worker;
+    #pending = new Map();
+    #nextId = 0;
+    #closed;
+    /** Rejecters of calls still waiting; each removes itself when its wait ends. */
+    #waiting = new Set();
+    /** Settles once the previous call has been sent, keeping submissions in call order. */
+    #submitted = Promise.resolve();
+    constructor(options = {}) {
+        const input = options;
+        if (input === null || typeof input !== "object" || Array.isArray(input))
+            throw new TypeError("Invalid scanner options");
+        for (const key of Object.keys(options))
+            if (!scannerOptions.includes(key))
+                throw new TypeError(`Unknown scanner option: ${key}. Use the core "tapirscan" entry for loadWasm.`);
+        if (typeof Worker === "undefined") {
+            this.#closed = new Error("tapirscan/browser scans in browsers; this environment has no Worker");
+            this.ready = Promise.reject(this.#closed);
+        }
+        else {
+            const { wasmBaseUrl, ...rest } = options;
+            if (wasmBaseUrl !== undefined &&
+                typeof wasmBaseUrl !== "string" &&
+                !(wasmBaseUrl instanceof URL))
+                throw new TypeError("wasmBaseUrl must be a string or URL");
+            const base = typeof document === "undefined" ? location.href : document.baseURI;
+            const workerOptions = wasmBaseUrl === undefined
+                ? rest
+                : { ...rest, wasmBaseUrl: new URL(wasmBaseUrl, base).href };
+            const worker = new Worker(new URL("./browser-worker.js", import.meta.url), {
+                type: "module",
+            });
+            this.#worker = worker;
+            worker.onmessage = ({ data }) => {
+                const pending = this.#pending.get(data.id);
+                if (!pending)
+                    return;
+                this.#pending.delete(data.id);
+                if ("error" in data)
+                    pending.reject(revive(data.error));
+                else
+                    pending.resolve(data.value);
+            };
+            worker.onerror = (event) => {
+                event.preventDefault();
+                // A worker script that cannot load gives no message; name the usual cause.
+                this.#close(new Error(event.message ||
+                    'Scanner worker failed to start. With the Vite dev server, add optimizeDeps: { exclude: ["tapirscan"] } to vite.config.'));
+            };
+            worker.onmessageerror = () => {
+                this.#close(new Error("Could not read a scanner worker message"));
+            };
+            this.ready = this.#request({ type: "create", options: workerOptions }, []).then(() => undefined, (error) => {
+                this.#close(error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            });
+        }
+        // Loading errors also reject every scan; awaiting ready is optional.
+        this.ready.catch(() => undefined);
+    }
+    /** Decode barcodes with source-image positions. No detection returns empty values and barcodes. */
+    async scan(source, options = {}) {
+        return freeze((await this.#scan("scan", source, options)));
+    }
+    /** Scan with unread regions, timing and engine diagnostics. */
+    async inspect(source, options = {}) {
+        return freeze((await this.#scan("inspect", source, options)));
+    }
+    /** Stop the worker and reject queued scans. Repeated disposal is safe. */
+    dispose() {
+        // Same error as the core scanner, so one handler covers both entries.
+        this.#close(new ScannerError("disposed", "Scanner was disposed"));
+    }
+    async #scan(type, source, options) {
+        if (this.#closed)
+            throw this.#closed;
+        // Capture the options and the frame before any await, so later changes by the
+        // caller (a reused options object or buffer, the next video frame) cannot leak in.
+        // Plain copies (scan options hold at most a format selection); invalid values
+        // pass through unchanged for the core to reject.
+        const input = options;
+        const scanOptions = input !== null && typeof input === "object" && !Array.isArray(input)
+            ? {
+                ...options,
+                ...(typeof options.formats === "object" ? { formats: [...options.formats] } : {}),
+            }
+            : options;
+        const preparing = prepare(source);
+        const previous = this.#submitted;
+        let submitted = () => undefined;
+        this.#submitted = new Promise((resolve) => {
+            submitted = resolve;
+        });
+        try {
+            const [prepared, transfer] = await this.#untilClosed(preparing);
+            await this.#untilClosed(previous);
+            await this.#untilClosed(this.ready);
+            const result = this.#request({ type, source: prepared, options: scanOptions }, transfer);
+            submitted();
+            return await result;
+        }
+        finally {
+            // A failed call releases its successor only once its own predecessor was
+            // sent, so later calls never overtake earlier ones.
+            void previous.then(submitted);
+            // Release a bitmap snapshot that was not sent, including one still being prepared.
+            void preparing.then(([prepared]) => {
+                if (prepared instanceof ImageBitmap)
+                    prepared.close();
+            }, () => undefined);
+        }
+    }
+    /** Wait for `promise`, but reject at once on dispose. Leaves nothing behind. */
+    #untilClosed(promise) {
+        if (this.#closed)
+            return Promise.reject(this.#closed);
+        return new Promise((resolve, reject) => {
+            this.#waiting.add(reject);
+            promise
+                .then(resolve, reject)
+                .finally(() => this.#waiting.delete(reject))
+                .catch(() => undefined);
+        });
+    }
+    #request(message, transfer) {
+        const worker = this.#worker;
+        // Without a worker, the constructor has already recorded why.
+        if (this.#closed || !worker)
+            return Promise.reject(this.#closed ?? new Error("No scanner worker"));
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+            try {
+                worker.postMessage({ ...message, id }, transfer);
+            }
+            catch (error) {
+                this.#pending.delete(id);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    #close(reason) {
+        if (this.#closed)
+            return;
+        this.#closed = reason;
+        for (const reject of this.#waiting)
+            reject(reason);
+        this.#waiting.clear();
+        this.#worker?.terminate();
+        for (const pending of this.#pending.values())
+            pending.reject(reason);
+        this.#pending.clear();
+    }
+}
+/** Scan one image with a temporary scanner. Reuse a Scanner for several images. */
+export async function scan(source, options = {}) {
+    const scanner = new Scanner(options);
+    try {
+        return await scanner.scan(source);
+    }
+    finally {
+        scanner.dispose();
+    }
+}
+/** Inspect one image with a temporary scanner. */
+export async function inspect(source, options = {}) {
+    const scanner = new Scanner(options);
+    try {
+        return await scanner.inspect(source);
+    }
+    finally {
+        scanner.dispose();
+    }
+}

package/dist/freeze.d.ts

@@ -0,0 +1,6 @@
+/** Deeply readonly view of plain result data. */
+export type ReadonlyDeep<T> = T extends object ? {
+    readonly [K in keyof T]: ReadonlyDeep<T[K]>;
+} : T;
+/** Freeze plain result data in place, so results stay immutable at runtime. */
+export declare function freeze<T extends object>(value: T): ReadonlyDeep<T>;

package/dist/freeze.js

@@ -0,0 +1,7 @@
+/** Freeze plain result data in place, so results stay immutable at runtime. */
+export function freeze(value) {
+    for (const child of Object.values(value))
+        if (child !== null && typeof child === "object")
+            freeze(child);
+    return Object.freeze(value);
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type Format, type FormatSelection } from "./multiformat/formats.js";
-export { commonFormats, commonLinearFormats, formatBits, linearFormats, matrixFormats, retailFormats, } from "./multiformat/formats.js";
+import { type ReadonlyDeep } from "./freeze.js";
+export { commonFormats, commonLinearFormats, linearFormats, matrixFormats, retailFormats, } from "./multiformat/formats.js";
 export type { Format, FormatSelection } from "./multiformat/formats.js";
 export { ScannerError } from "./rust-session.js";
 export type Quad = readonly [
@@ -17,12 +18,8 @@ export interface Image {
 }
 export type Mode = "low" | "medium" | "high" | "very-high";
 export interface ScanOptions {
-    /** Allow reader-specific extra work. Supported for every format; exact budgets may evolve. */
-    extendedBudget?: boolean;
-    /** Per-call subset of the formats configured at creation. */
+    /** Formats for this call only; defaults to the scanner's formats. */
     formats?: FormatSelection;
-    /** Include raw engine diagnostics. Public barcodes and unread geometry are always included. */
-    debug?: boolean;
 }
 interface RawDiagnostics {
     scan: {
@@ -44,9 +41,6 @@ interface RawDiagnostics {
     }[];
     [key: string]: unknown;
 }
-type ReadonlyDeep<T> = T extends object ? {
-    readonly [K in keyof T]: ReadonlyDeep<T[K]>;
-} : T;
 interface RawDiagnosticBarcode {
     text: string;
     format: Format | "Unknown";
@@ -83,7 +77,8 @@ export interface Barcode {
     /** Payload bytes before character-set interpretation; absent when unavailable. */
     readonly payloadBytes?: readonly number[];
     readonly text: string;
-    readonly format: Format | "Unknown";
+    /** Decoded barcodes always have a known format; only undecoded regions report "Unknown". */
+    readonly format: Format;
     /** Reader-specific ranking evidence, not a probability or cross-reader confidence. */
     readonly support: number;
     readonly gs1?: boolean;
@@ -98,27 +93,35 @@ export interface Barcode {
         readonly height: number;
     };
 }
+/** Decoded values and their source-image locations. */
 export interface ScanResult {
     readonly barcodes: readonly Barcode[];
     readonly values: readonly string[];
     /** Largest reader-specific support; not a cross-format confidence comparison. */
     readonly best: Barcode | undefined;
+}
+export interface InspectionResult extends ScanResult {
     readonly image: {
         readonly width: number;
         readonly height: number;
     };
-    readonly mode: Mode;
+    /** Effort mode used; absent for Turbo presets, which report `experimentalTurbo`. */
+    readonly mode?: Mode;
+    /** @experimental Selected Turbo preset, when requested. */
+    readonly experimentalTurbo?: ExperimentalTurbo;
     /** Whole synchronous WASM call time measured by the JavaScript host. */
     readonly elapsedMs: number;
-    readonly unfinished: boolean;
     readonly undecoded: readonly UndecodedRegion[];
-    readonly debug?: Diagnostics;
+    readonly diagnostics: Diagnostics;
 }
-export type EanAddOnPolicy = "Ignore" | "Read" | "Require";
+export type EanAddOnPolicy = "ignore" | "read" | "require";
+export type ExperimentalTurbo = 2 | 4 | 8 | 16;
 export interface ScannerOptions {
+    mode?: Mode;
+    /** @experimental Targets faster 1D scanning, not 2D speedups. May change in minor releases. */
+    experimentalTurbo?: ExperimentalTurbo;
     /** Optional EAN/UPC supplement policy, fixed at creation. */
     eanAddOnPolicy?: EanAddOnPolicy;
-    mode?: Mode;
     formats?: FormatSelection;
     /** Directory containing the packaged WASMs; relative to the page in browsers. */
     wasmBaseUrl?: string | URL;
@@ -129,17 +132,26 @@ export type PixelImage = Image | Pick<ImageData, "data" | "width" | "height">;
 /** A reusable scanner. Results own their data and remain valid after later scans or disposal. */
 export declare class Scanner {
     private readonly host;
-    readonly mode: Mode;
+    /** Effort mode, fixed at creation; undefined for Turbo presets. */
+    readonly mode: Mode | undefined;
     private readonly configuredFormats;
     private readonly addOnPolicy;
+    /** @experimental Selected Turbo preset, fixed at creation. */
+    readonly experimentalTurbo?: ExperimentalTurbo | undefined;
     private constructor();
-    /** Formats available for scanning, fixed at creation. */
+    /** Default formats, fixed at creation; individual scans may override them. */
     get formats(): readonly Format[];
     get eanAddOnPolicy(): EanAddOnPolicy;
     static create(options?: ScannerOptions): Promise<Scanner>;
+    /** Decode barcodes with positions. Use inspect() for diagnostic evidence. */
     scan(inputImage: PixelImage, options?: ScanOptions): ScanResult;
+    /** Inspect barcodes, unread regions, timing and engine diagnostics. */
+    inspect(inputImage: PixelImage, options?: ScanOptions): InspectionResult;
+    private run;
     /** Release the WASM session. Repeated disposal is safe; scanning afterward fails. */
     dispose(): void;
 }
 /** Scan one image with automatic cleanup. Reuse Scanner for a stream of images. */
-export declare function scan(image: PixelImage, options?: ScannerOptions & ScanOptions): Promise<ScanResult>;
+export declare function scan(image: PixelImage, options?: ScannerOptions): Promise<ScanResult>;
+/** Inspect one image with automatic cleanup. */
+export declare function inspect(image: PixelImage, options?: ScannerOptions): Promise<InspectionResult>;