tapirscan 1.2.2 → 1.3.0

package/dist/index.js

@@ -1,51 +1,61 @@
-import { maskFor, resolveFormats, } from "./multiformat/formats.js";
+import { hasKey, maskFor, resolveFormats, } from "./multiformat/formats.js";
+import { freeze } from "./freeze.js";
+import { pixelLayout } from "./layout.js";
 import { RustScannerSession, ScannerError } from "./rust-session.js";
-export { commonFormats, commonLinearFormats, formatBits, linearFormats, matrixFormats, retailFormats, } from "./multiformat/formats.js";
+export { commonFormats, commonLinearFormats, linearFormats, matrixFormats, retailFormats, } from "./multiformat/formats.js";
 export { ScannerError } from "./rust-session.js";
 const modes = {
-    low: { id: 0, file: "low-release-1.2.2-public-low-r2.wasm" },
-    medium: { id: 1, file: "medium-release-1.2.2-public-low-r2.wasm" },
-    high: { id: 2, file: "high-release-1.2.2-public-low-r2.wasm" },
-    "very-high": { id: 3, file: "very-high-release-1.2.2-public-low-r2.wasm" },
+    low: { id: 0, file: "low.wasm" },
+    medium: { id: 1, file: "medium.wasm" },
+    high: { id: 2, file: "high.wasm" },
+    "very-high": { id: 3, file: "very-high.wasm" },
 };
-const addOnPolicies = { Ignore: 0, Read: 1, Require: 2 };
+const turboFiles = {
+    2: "experimental-turbo2.wasm",
+    4: "experimental-turbo4.wasm",
+    8: "experimental-turbo8.wasm",
+    16: "experimental-turbo16.wasm",
+};
+const addOnPolicies = { ignore: 0, read: 1, require: 2 };
 function pixels(image) {
-    const input = image;
-    if (input === null || typeof input !== "object")
-        throw new TypeError("Expected ImageData or decoded pixels");
-    const explicit = "channels" in image;
-    if (!explicit && !(image.data instanceof Uint8ClampedArray))
-        throw new TypeError("Use ImageData or an explicit buffer with channels");
-    const channels = explicit ? image.channels : 4;
-    const stride = explicit ? (image.stride ?? image.width * channels) : image.width * 4;
-    const required = (image.height - 1) * stride + image.width * channels;
-    if (!Number.isSafeInteger(image.width) ||
-        !Number.isSafeInteger(image.height) ||
-        image.width < 3 ||
-        image.height < 3 ||
-        image.width * image.height > 32 * 1024 * 1024 ||
-        ![1, 3, 4].includes(channels) ||
-        !Number.isSafeInteger(stride) ||
-        stride < image.width * channels ||
-        required > 128 * 1024 * 1024 ||
-        !(image.data instanceof Uint8Array || image.data instanceof Uint8ClampedArray) ||
-        image.data.byteLength < required)
-        throw new TypeError("Invalid image dimensions, channels, stride or buffer (maximum 128 MiB)");
+    const { data, width, height, channels, stride } = pixelLayout(image);
     return {
-        data: new Uint8Array(image.data.buffer, image.data.byteOffset, image.data.byteLength),
-        width: image.width,
-        height: image.height,
+        data: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+        width,
+        height,
         channels,
         stride,
     };
 }
-function freeze(value) {
-    for (const child of Object.values(value))
-        if (child !== null && typeof child === "object")
-            freeze(child);
-    return Object.freeze(value);
+// The package's wasm/ directory. Bundlers (Turbopack, webpack, Vite) resolve
+// `new URL("literal", import.meta.url)` as a file and fail on a directory; browser
+// bundles load WASM through tapirscan/browser's static per-file URLs instead.
+function packagedWasm() {
+    const url = new URL(import.meta.url);
+    url.pathname = url.pathname.replace(/[^/]*\/[^/]*$/, "wasm/");
+    return url;
+}
+// Bound retained WASM bytes across stable modes, experimental presets and custom URLs.
+const wasmLoads = new Map();
+function loadDefault(url) {
+    const key = url.href;
+    const cached = wasmLoads.get(key);
+    if (cached)
+        return cached;
+    const pending = readWasm(url).catch((error) => {
+        if (wasmLoads.get(key) === pending)
+            wasmLoads.delete(key);
+        throw error;
+    });
+    wasmLoads.set(key, pending);
+    if (wasmLoads.size > 4) {
+        const oldest = wasmLoads.keys().next().value;
+        if (oldest !== undefined)
+            wasmLoads.delete(oldest);
+    }
+    return pending;
 }
-async function loadDefault(url) {
+async function readWasm(url) {
     if (url.protocol === "file:") {
         const nodeFs = "node:fs/promises";
         const fs = (await import(/* @vite-ignore */ nodeFs));
@@ -61,44 +71,39 @@ function wireResult(value) {
         typeof value !== "object" ||
         !("barcodes" in value) ||
         !Array.isArray(value.barcodes) ||
-        !("bestIndex" in value) ||
-        (value.bestIndex !== null &&
-            (!Number.isInteger(value.bestIndex) ||
-                value.bestIndex < 0 ||
-                value.bestIndex >= value.barcodes.length)) ||
         !("undecoded" in value) ||
         !Array.isArray(value.undecoded) ||
         !("image" in value) ||
         value.image === null ||
         typeof value.image !== "object" ||
         !("mode" in value) ||
-        !Object.hasOwn(modes, String(value.mode)) ||
-        !("unfinished" in value) ||
-        typeof value.unfinished !== "boolean")
+        typeof value.mode !== "string" ||
+        !hasKey(modes, value.mode))
         throw new ScannerError("invalid_output", "Scanner returned an invalid result");
     return value;
 }
-function publicResult(raw, elapsedMs, debug) {
+function publicResult(raw, elapsedMs, experimentalTurbo) {
+    if (!raw.debug)
+        throw new ScannerError("invalid_output", "Scanner omitted requested diagnostics");
     const barcodes = raw.barcodes;
     const undecoded = raw.undecoded.map(({ format, polygon }) => ({
         format: format ?? "Unknown",
         polygon,
     }));
     const regions = {
-        proposals: raw.debug?.localization?.proposals ?? null,
-        searchWindows: raw.debug?.searchWindows ?? null,
+        proposals: raw.debug.localization?.proposals ?? null,
+        searchWindows: raw.debug.searchWindows ?? null,
         undecoded,
     };
     return freeze({
         barcodes,
         values: barcodes.map((b) => b.text),
-        best: raw.bestIndex === null ? undefined : barcodes[raw.bestIndex],
+        best: bestOf(barcodes),
         image: raw.image,
-        mode: raw.mode,
+        ...(experimentalTurbo === undefined ? { mode: raw.mode } : { experimentalTurbo }),
         elapsedMs,
-        unfinished: raw.unfinished,
         undecoded,
-        ...(debug && raw.debug ? { debug: { ...raw.debug, regions } } : {}),
+        diagnostics: { ...raw.debug, regions },
     });
 }
 /** A reusable scanner. Results own their data and remain valid after later scans or disposal. */
@@ -107,14 +112,20 @@ export class Scanner {
     mode;
     configuredFormats;
     addOnPolicy;
-    constructor(host, mode, configuredFormats, addOnPolicy) {
+    experimentalTurbo;
+    constructor(host, 
+    /** Effort mode, fixed at creation; undefined for Turbo presets. */
+    mode, configuredFormats, addOnPolicy, 
+    /** @experimental Selected Turbo preset, fixed at creation. */
+    experimentalTurbo) {
         this.host = host;
         this.mode = mode;
         this.configuredFormats = configuredFormats;
         this.addOnPolicy = addOnPolicy;
+        this.experimentalTurbo = experimentalTurbo;
         Object.freeze(configuredFormats);
     }
-    /** Formats available for scanning, fixed at creation. */
+    /** Default formats, fixed at creation; individual scans may override them. */
     get formats() {
         return this.configuredFormats;
     }
@@ -126,15 +137,33 @@ export class Scanner {
         if (input === null || typeof input !== "object" || Array.isArray(input))
             throw new TypeError("Invalid scanner options");
         for (const key of Object.keys(options))
-            if (!["mode", "formats", "wasmBaseUrl", "loadWasm", "eanAddOnPolicy"].includes(key))
+            if (![
+                "mode",
+                "experimentalTurbo",
+                "formats",
+                "wasmBaseUrl",
+                "loadWasm",
+                "eanAddOnPolicy",
+            ].includes(key))
                 throw new TypeError(`Unknown scanner option: ${key}`);
-        const mode = options.mode ?? "medium";
-        if (!Object.hasOwn(modes, mode))
+        const turbo = options.experimentalTurbo;
+        if (turbo !== undefined) {
+            if (typeof turbo !== "number" || !hasKey(turboFiles, turbo))
+                throw new TypeError("experimentalTurbo must be 2, 4, 8 or 16");
+            if (options.mode !== undefined)
+                throw new TypeError("Choose mode or experimentalTurbo, not both");
+            if (options.eanAddOnPolicy !== undefined && options.eanAddOnPolicy !== "ignore")
+                throw new TypeError('experimentalTurbo requires eanAddOnPolicy: "ignore"');
+        }
+        // Only undefined or a supported string: null or objects that stringify to a mode are errors.
+        if (options.mode !== undefined &&
+            (typeof options.mode !== "string" || !hasKey(modes, options.mode)))
             throw new TypeError("Unknown scanner mode");
+        const mode = turbo === undefined ? (options.mode ?? "medium") : "low";
         const formats = resolveFormats(options.formats);
-        const addOnPolicy = options.eanAddOnPolicy === undefined ? "Ignore" : options.eanAddOnPolicy;
-        if (!Object.hasOwn(addOnPolicies, addOnPolicy))
-            throw new TypeError("eanAddOnPolicy must be Ignore, Read or Require");
+        const addOnPolicy = options.eanAddOnPolicy === undefined ? "ignore" : options.eanAddOnPolicy;
+        if (typeof addOnPolicy !== "string" || !hasKey(addOnPolicies, addOnPolicy))
+            throw new TypeError('eanAddOnPolicy must be "ignore", "read" or "require"');
         if (options.loadWasm !== undefined && typeof options.loadWasm !== "function")
             throw new TypeError("loadWasm must be a function");
         if (options.wasmBaseUrl !== undefined &&
@@ -142,54 +171,76 @@ export class Scanner {
             !(options.wasmBaseUrl instanceof URL))
             throw new TypeError("wasmBaseUrl must be a string or URL");
         const base = options.wasmBaseUrl === undefined
-            ? new URL(/* @vite-ignore */ "../wasm/", import.meta.url)
+            ? packagedWasm()
             : new URL(options.wasmBaseUrl, typeof location === "undefined" ? import.meta.url : location.href);
         if (!base.pathname.endsWith("/"))
             base.pathname += "/";
         const selected = modes[mode];
-        const bytes = await (options.loadWasm ?? loadDefault)(new URL(selected.file, base));
-        const host = await RustScannerSession.create(bytes, selected.id, maskFor(formats), addOnPolicies[addOnPolicy]);
-        return new Scanner(host, mode, formats, addOnPolicy);
+        const bytes = await (options.loadWasm ?? loadDefault)(new URL(turbo === undefined ? selected.file : turboFiles[turbo], base));
+        const host = await RustScannerSession.create(bytes, selected.id, maskFor(formats), addOnPolicies[addOnPolicy], turbo);
+        // Turbo presets run in the Low engine slot but have no effort mode of their own.
+        return new Scanner(host, turbo === undefined ? mode : undefined, formats, addOnPolicy, turbo);
     }
+    /** Decode barcodes with positions. Use inspect() for diagnostic evidence. */
     scan(inputImage, options = {}) {
+        const raw = this.run(inputImage, options, false);
+        if (raw === null ||
+            typeof raw !== "object" ||
+            !("barcodes" in raw) ||
+            !Array.isArray(raw.barcodes))
+            throw new ScannerError("invalid_output", "Scanner returned an invalid barcode list");
+        const barcodes = raw.barcodes;
+        return freeze({
+            barcodes,
+            values: barcodes.map((barcode) => barcode.text),
+            best: bestOf(barcodes),
+        });
+    }
+    /** Inspect barcodes, unread regions, timing and engine diagnostics. */
+    inspect(inputImage, options = {}) {
+        const start = performance.now();
+        const raw = wireResult(this.run(inputImage, options, true));
+        return publicResult(raw, performance.now() - start, this.experimentalTurbo);
+    }
+    run(inputImage, options, inspect) {
         const image = pixels(inputImage);
         const input = options;
         if (input === null || typeof input !== "object" || Array.isArray(input))
             throw new TypeError("Invalid scan options");
         for (const key of Object.keys(options))
-            if (!["debug", "formats", "extendedBudget"].includes(key))
+            if (key !== "formats")
                 throw new TypeError(`Unknown scan option: ${key}`);
-        if (options.debug !== undefined && typeof options.debug !== "boolean")
-            throw new TypeError("debug must be a boolean");
-        if (options.extendedBudget !== undefined && typeof options.extendedBudget !== "boolean")
-            throw new TypeError("extendedBudget must be a boolean");
-        const formats = options.formats === undefined ? this.formats : resolveFormats(options.formats);
-        if (formats.some((format) => !this.formats.includes(format)))
-            throw new TypeError(`Scan formats must be a subset of configured formats. Requested: ${formats.join(", ")}; configured: ${this.formats.join(", ")}`);
-        const debug = options.debug ?? false;
-        const flags = (options.extendedBudget ? 1 : 0) | (debug ? 2 : 0);
-        const start = performance.now();
-        const raw = wireResult(this.host.scan(image, flags, options.formats === undefined ? 0 : maskFor(formats)));
-        if (debug && !raw.debug)
-            throw new ScannerError("invalid_output", "Scanner omitted requested diagnostics");
-        return publicResult(raw, performance.now() - start, debug);
+        const mask = options.formats === undefined ? 0 : maskFor(resolveFormats(options.formats));
+        return this.host.scan(image, inspect ? 2 : 0, mask);
     }
     /** Release the WASM session. Repeated disposal is safe; scanning afterward fails. */
     dispose() {
         this.host.dispose();
     }
 }
+/** Highest support, keeping the first read on ties; undefined when empty. */
+function bestOf(barcodes) {
+    let winner;
+    for (const barcode of barcodes)
+        if (!winner || barcode.support > winner.support)
+            winner = barcode;
+    return winner;
+}
 /** Scan one image with automatic cleanup. Reuse Scanner for a stream of images. */
 export async function scan(image, options = {}) {
-    const input = options;
-    if (input === null || typeof input !== "object" || Array.isArray(input))
-        throw new TypeError("Invalid scan options");
-    const { debug, extendedBudget, ...creation } = options;
-    if (debug !== undefined && typeof debug !== "boolean")
-        throw new TypeError("debug must be a boolean");
-    const scanner = await Scanner.create(creation);
+    const scanner = await Scanner.create(options);
+    try {
+        return scanner.scan(image);
+    }
+    finally {
+        scanner.dispose();
+    }
+}
+/** Inspect one image with automatic cleanup. */
+export async function inspect(image, options = {}) {
+    const scanner = await Scanner.create(options);
     try {
-        return scanner.scan(image, { debug, extendedBudget });
+        return scanner.inspect(image);
     }
     finally {
         scanner.dispose();

package/dist/layout.d.ts

@@ -0,0 +1,19 @@
+/** Decoded pixels: `ImageData` or an explicit gray, RGB or RGBA buffer. */
+export interface PixelInput {
+    readonly data: Uint8Array | Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly channels?: 1 | 3 | 4;
+    readonly stride?: number;
+}
+/** A validated layout; `addressed` bytes from the start of `data` hold the image. */
+export interface PixelLayout {
+    readonly data: Uint8Array | Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly channels: 1 | 3 | 4;
+    readonly stride: number;
+    readonly addressed: number;
+}
+/** Validate decoded pixels against the scanner limits without copying them. */
+export declare function pixelLayout(image: unknown): PixelLayout;

package/dist/layout.js

@@ -0,0 +1,27 @@
+// Pixel layout rules shared by the core and the browser entry. No WASM imports, so
+// the browser entry can validate on the page without loading the core.
+/** Validate decoded pixels against the scanner limits without copying them. */
+export function pixelLayout(image) {
+    if (image === null || typeof image !== "object" || !("data" in image))
+        throw new TypeError("Expected ImageData or decoded pixels");
+    const { data, width, height } = image;
+    const explicit = "channels" in image;
+    if (!explicit && !(data instanceof Uint8ClampedArray))
+        throw new TypeError("Use ImageData or an explicit buffer with channels");
+    const channels = explicit ? image.channels : 4;
+    const stride = (explicit ? image.stride : undefined) ?? width * (channels ?? 0);
+    const addressed = (height - 1) * stride + width * (channels ?? 0);
+    if (!Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width < 3 ||
+        height < 3 ||
+        width * height > 32 * 1024 * 1024 ||
+        (channels !== 1 && channels !== 3 && channels !== 4) ||
+        !Number.isSafeInteger(stride) ||
+        stride < width * channels ||
+        addressed > 128 * 1024 * 1024 ||
+        !(data instanceof Uint8Array || data instanceof Uint8ClampedArray) ||
+        data.byteLength < addressed)
+        throw new TypeError("Invalid image dimensions, channels, stride or buffer (maximum 128 MiB)");
+    return { data, width, height, channels, stride, addressed };
+}

package/dist/multiformat/format-registry.d.ts

@@ -1,4 +1,4 @@
-export declare const formatBits: {
+export declare const formatBits: Readonly<{
     readonly EAN13: 1;
     readonly UPCA: 2;
     readonly EAN8: 4;
@@ -15,7 +15,7 @@ export declare const formatBits: {
     readonly DataBar: 8192;
     readonly DataBarExpanded: 16384;
     readonly MaxiCode: 131072;
-};
+}>;
 export type Format = keyof typeof formatBits;
 export declare const retailFormats: readonly Format[];
 export declare const commonLinearFormats: readonly Format[];

package/dist/multiformat/format-registry.js

@@ -1,5 +1,6 @@
 // Generated by scripts/generate_formats.py from config/formats.json. Do not edit.
-export const formatBits = {
+// Frozen: these shared constants also back the scanner defaults.
+export const formatBits = Object.freeze({
     EAN13: 1,
     UPCA: 2,
     EAN8: 4,
@@ -16,9 +17,9 @@ export const formatBits = {
     DataBar: 8192,
     DataBarExpanded: 16384,
     MaxiCode: 131072,
-};
-export const retailFormats = ["EAN13", "UPCA", "EAN8", "UPCE"];
-export const commonLinearFormats = [
+});
+export const retailFormats = Object.freeze(["EAN13", "UPCA", "EAN8", "UPCE"]);
+export const commonLinearFormats = Object.freeze([
     "EAN13",
     "UPCA",
     "EAN8",
@@ -26,8 +27,8 @@ export const commonLinearFormats = [
     "Code128",
     "Code39",
     "ITF",
-];
-export const commonFormats = [
+]);
+export const commonFormats = Object.freeze([
     "EAN13",
     "UPCA",
     "EAN8",
@@ -37,8 +38,8 @@ export const commonFormats = [
     "ITF",
     "QRCode",
     "DataMatrix",
-];
-export const linearFormats = [
+]);
+export const linearFormats = Object.freeze([
     "EAN13",
     "UPCA",
     "EAN8",
@@ -50,13 +51,13 @@ export const linearFormats = [
     "Code93",
     "DataBar",
     "DataBarExpanded",
-];
-export const matrixFormats = [
+]);
+export const matrixFormats = Object.freeze([
     "QRCode",
     "DataMatrix",
     "PDF417",
     "Aztec",
     "MaxiCode",
-];
+]);
 export const eanAddOnReadFlag = 32768;
 export const eanAddOnRequireFlag = 65536;

package/dist/multiformat/formats.d.ts

@@ -1,6 +1,8 @@
 /** Explicit opt-in formats for the independent Medium extension. */
 import { commonFormats, commonLinearFormats, formatBits, linearFormats, matrixFormats, retailFormats, type Format } from "./format-registry.js";
 export { commonFormats, commonLinearFormats, formatBits, linearFormats, matrixFormats, retailFormats, type Format, };
+/** Own-property check that works in Chrome 91 (`Object.hasOwn` needs Chrome 93). */
+export declare function hasKey(object: object, key: PropertyKey): boolean;
 export type FormatSelection = Format | readonly Format[] | "retail" | "common1D" | "common" | "1D" | "2D" | "all";
 export declare function resolveFormats(input?: readonly string[] | string): Format[];
 export declare function maskFor(formats: readonly Format[]): number;

package/dist/multiformat/formats.js

@@ -1,6 +1,10 @@
 /** Explicit opt-in formats for the independent Medium extension. */
 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];
@@ -16,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

@@ -3,10 +3,10 @@ export declare class ScannerError extends Error {
     constructor(code: string, message: string);
 }
 export declare class RustScannerSession {
-    private readonly exports;
+    private exports;
     private handle;
     private constructor();
-    static create(bytes: ArrayBuffer, mode: number, formats: number, addOnPolicy: number): Promise<RustScannerSession>;
+    static create(bytes: ArrayBuffer, mode: number, formats: number, addOnPolicy: number, experimentalTurbo?: number): Promise<RustScannerSession>;
     scan(image: {
         data: Uint8Array;
         width: number;

package/dist/rust-session.js

@@ -1,3 +1,5 @@
+// Stateless for complete inputs, so one decoder serves every scan.
+const outputDecoder = new TextDecoder();
 export class ScannerError extends Error {
     code;
     constructor(code, message) {
@@ -36,7 +38,7 @@ export class RustScannerSession {
         this.exports = exports;
         this.handle = handle;
     }
-    static async create(bytes, mode, formats, addOnPolicy) {
+    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))
@@ -44,10 +46,14 @@ export class RustScannerSession {
         for (const name of exportNames)
             if (typeof exports[name] !== "function")
                 throw new ScannerError("abi_shape", `Missing WASM export: ${name}`);
-        if (exports.tapirscan_abi_version() !== 1)
+        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");
@@ -65,7 +71,7 @@ export class RustScannerSession {
         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(new TextDecoder().decode(output));
+            decoded = JSON.parse(outputDecoder.decode(output));
         }
         catch {
             throw new ScannerError("invalid_output", "Scanner returned invalid JSON");
@@ -79,13 +85,17 @@ export class RustScannerSession {
         return decoded;
     }
     dispose() {
-        if (!this.handle)
+        if (!this.handle || !this.exports)
             return;
-        status(this.exports.tapirscan_destroy(this.handle), "Scanner disposal");
+        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)
+        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;