tapirscan 1.0.0

package/dist/multiformat/scanner.js

@@ -0,0 +1,258 @@
+import { ReleaseDetailScanner, fitLimits } from "../detail.js";
+import { IndependentScanner } from "../multiformat-host.js";
+import { policy } from "../policy.js";
+import { rectify, project, distinctReads, polygonOverlap } from "./geometry.js";
+import { toGray } from "./pixels.js";
+import { maskFor, resolveFormats, linearFormats as supportedLinearFormats, } from "./formats.js";
+/** Frozen EAN13 Medium plus project-owned opt-in readers. No reference decoder. */
+export class MediumMultiformatScanner {
+    medium;
+    mode = "medium";
+    extra;
+    handle = 0;
+    disposed = false;
+    constructor() { }
+    static async create(mediumBytes, extraBytes, mode = "medium", recoveryBytes) {
+        const scanner = new MediumMultiformatScanner();
+        try {
+            scanner.mode = mode;
+            scanner.medium =
+                mode !== "low" && recoveryBytes
+                    ? await ReleaseDetailScanner.create(mediumBytes, recoveryBytes, mode)
+                    : await IndependentScanner.create(mediumBytes);
+            if (extraBytes) {
+                const instance = await WebAssembly.instantiate(extraBytes, {});
+                const e = instance.instance.exports;
+                for (const name of [
+                    "multi_new",
+                    "multi_free",
+                    "multi_prepare",
+                    "multi_input",
+                    "multi_scan",
+                    "multi_output",
+                    "multi_output_len",
+                ]) {
+                    if (typeof e[name] !== "function")
+                        throw Error(`Invalid multiformat WASM export: ${name}`);
+                }
+                if (!(e.memory instanceof WebAssembly.Memory))
+                    throw Error("Invalid multiformat WASM memory.");
+                scanner.extra = e;
+                scanner.handle = e.multi_new();
+                if (!scanner.handle)
+                    throw Error("Could not create additional reader session.");
+            }
+            return scanner;
+        }
+        catch (error) {
+            scanner.dispose();
+            throw error;
+        }
+    }
+    scan(image, inputFormats, options = {}) {
+        if (this.disposed)
+            throw Error("Scanner is disposed.");
+        const medium = this.medium;
+        if (!medium)
+            throw Error("Medium reader has not been initialized.");
+        const formats = resolveFormats(inputFormats);
+        const eanAddOnSymbol = options.eanAddOnSymbol ?? "Ignore";
+        if (!["Ignore", "Read", "Require"].includes(eanAddOnSymbol))
+            throw Error("Unknown EAN add-on policy.");
+        const requestedStrategy = options.linearStrategy ?? "scanlines";
+        if (!["scanlines", "medium-localized"].includes(requestedStrategy))
+            throw Error("Unknown linear strategy.");
+        // Supplements extend beyond the frozen Medium crop, so they require the
+        // full-frame supplemental pass. Default EAN13 remains untouched.
+        const linearStrategy = eanAddOnSymbol === "Ignore" ? requestedStrategy : "scanlines";
+        const localized = linearStrategy === "medium-localized" &&
+            formats.some((f) => f !== "EAN13" && f !== "UPCA" && supportedLinearFormats.includes(f));
+        let proposals = [];
+        const start = performance.now();
+        const { width, height, channels, stride, data } = image;
+        if (!Number.isSafeInteger(width) ||
+            !Number.isSafeInteger(height) ||
+            width < 3 ||
+            height < 3 ||
+            width * height > 32 * 1024 * 1024 ||
+            ![1, 3, 4].includes(channels) ||
+            !Number.isSafeInteger(stride) ||
+            stride < width * channels ||
+            !(data instanceof Uint8Array) ||
+            data.length < (height - 1) * stride + width * channels)
+            throw Error("Invalid image dimensions or buffer.");
+        const barcodes = [], regions = [];
+        let unfinished = false, mediumMs = 0, additionalMs = 0, preparationMs = 0, localizationMs = 0;
+        if (formats.includes("EAN13") || formats.includes("UPCA")) {
+            const begin = performance.now();
+            const found = medium.scanLocalized(image, policy, fitLimits[this.mode], true);
+            const localization = found.localization;
+            proposals = localization.proposals;
+            localizationMs = found.localizationMs;
+            for (const b of found.scan.barcodes) {
+                if (formats.includes("UPCA") && b.text.startsWith("0"))
+                    barcodes.push({
+                        format: "UPCA",
+                        text: b.text.slice(1),
+                        polygon: b.polygon,
+                        support: b.support,
+                    });
+                else if (formats.includes("EAN13"))
+                    barcodes.push({ format: "EAN13", text: b.text, polygon: b.polygon, support: b.support });
+            }
+            const decoded = new Set(found.scan.barcodes.flatMap((b) => b.candidate_indices));
+            localization.proposals.forEach((p, i) => {
+                if (!decoded.has(i))
+                    regions.push({ format: "Unknown", text: "", polygon: p.polygon, support: 0 });
+            });
+            if ("recovery" in found) {
+                const recovery = found.recovery;
+                for (const attempt of recovery.attempts) {
+                    const accepted = new Set(attempt.reads.flatMap((b) => b.candidate_indices));
+                    attempt.proposals.forEach((p, i) => {
+                        if (!accepted.has(i))
+                            regions.push({ format: "Unknown", text: "", polygon: p.polygon, support: 0 });
+                    });
+                }
+            }
+            unfinished =
+                found.scan.unfinished ||
+                    Boolean(localization.workLimited) ||
+                    (localization.omitted ?? 0) > 0;
+            mediumMs = performance.now() - begin;
+        }
+        if (localized && !formats.includes("EAN13") && !formats.includes("UPCA")) {
+            const begin = performance.now();
+            const found = medium.scanLocalized(image, policy, fitLimits[this.mode], true)
+                .localization;
+            proposals = found.proposals;
+            unfinished ||= Boolean(found.workLimited) || (found.omitted ?? 0) > 0;
+            localizationMs = performance.now() - begin;
+        }
+        // UPC-A has the same optical structure as zero-prefixed EAN13, so the
+        // frozen Medium reader handles it without a second optical search.
+        const extraFormats = formats.filter((f) => eanAddOnSymbol !== "Ignore" || (f !== "EAN13" && f !== "UPCA"));
+        if (extraFormats.length) {
+            if (!this.extra || !this.handle)
+                throw Error("Additional readers have not been loaded.");
+            const begin = performance.now();
+            const gray = toGray(image);
+            preparationMs = performance.now() - begin;
+            const matrixFormats = extraFormats.filter((f) => !supportedLinearFormats.includes(f));
+            const linearFormats = extraFormats.filter((f) => supportedLinearFormats.includes(f));
+            const run = (pixels, w, h, enabled, effort) => {
+                const start = performance.now();
+                const result = this.scanExtra(pixels, w, h, enabled, effort, eanAddOnSymbol);
+                additionalMs += performance.now() - start;
+                unfinished ||= result.unfinished;
+                return result;
+            };
+            if (!localized || !proposals.length) {
+                const result = run(gray, width, height, extraFormats, 1);
+                barcodes.push(...result.barcodes);
+                regions.push(...(result.regions ?? []));
+            }
+            else {
+                if (matrixFormats.length) {
+                    const result = run(gray, width, height, matrixFormats, 1);
+                    barcodes.push(...result.barcodes);
+                    regions.push(...(result.regions ?? []));
+                }
+                for (const proposal of proposals) {
+                    const start = performance.now();
+                    let crop;
+                    try {
+                        crop = rectify(gray, width, height, proposal.polygon);
+                    }
+                    catch {
+                        unfinished = true;
+                        regions.push({ format: "Unknown", text: "", polygon: proposal.polygon, support: 0 });
+                        continue;
+                    }
+                    preparationMs += performance.now() - start;
+                    const result = run(crop.data, crop.width, crop.height, linearFormats, 0);
+                    const reads = result.barcodes;
+                    if (!reads.length)
+                        regions.push({ format: "Unknown", text: "", polygon: proposal.polygon, support: 0 });
+                    for (const read of [...reads, ...(result.regions ?? [])]) {
+                        const p = read.polygon;
+                        const mapped = (p) => project(crop.transform, p[0], p[1]);
+                        read.polygon = [mapped(p[0]), mapped(p[1]), mapped(p[2]), mapped(p[3])];
+                        if (read.text)
+                            barcodes.push(read);
+                        else
+                            regions.push(read);
+                    }
+                }
+            }
+        }
+        if (extraFormats.length) {
+            for (const read of barcodes.filter((b) => b.eanAddOn)) {
+                for (const base of barcodes) {
+                    if (base.format === read.format &&
+                        base.text === read.text &&
+                        !base.eanAddOn &&
+                        polygonOverlap(base.polygon, read.polygon).smaller >= 0.65)
+                        base.eanAddOn = read.eanAddOn;
+                }
+            }
+            if (eanAddOnSymbol === "Require") {
+                for (let i = barcodes.length - 1; i >= 0; i--) {
+                    const b = barcodes[i];
+                    if (["EAN13", "UPCA", "EAN8", "UPCE"].includes(b.format) && !b.eanAddOn) {
+                        regions.push({ ...b, text: "" });
+                        barcodes.splice(i, 1);
+                    }
+                }
+            }
+            const distinct = distinctReads(barcodes);
+            barcodes.splice(0, barcodes.length, ...distinct);
+            const remaining = regions.filter((region) => !barcodes.some((b) => polygonOverlap(region.polygon, b.polygon).a >= 0.65));
+            regions.splice(0, regions.length, ...distinctReads(remaining));
+        }
+        barcodes.sort((a, b) => b.support - a.support);
+        barcodes.forEach((b, i) => {
+            b.rank = i + 1;
+        });
+        return {
+            barcodes,
+            eanAddOnSymbol,
+            regions: [...barcodes, ...regions],
+            formats,
+            unfinished,
+            scanMs: performance.now() - start,
+            mediumMs,
+            additionalMs,
+            preparationMs,
+            localizationMs,
+            linearStrategy,
+        };
+    }
+    scanExtra(gray, width, height, formats, effort, eanAddOnSymbol) {
+        const e = this.extra;
+        if (!e || !this.handle)
+            throw Error("Additional readers have not been loaded.");
+        if (e.multi_prepare(this.handle, width, height) !== 0)
+            throw Error("Additional reader rejected image size.");
+        new Uint8Array(e.memory.buffer, e.multi_input(this.handle), width * height).set(gray);
+        const mask = maskFor(formats) |
+            (eanAddOnSymbol === "Read" ? 32768 : eanAddOnSymbol === "Require" ? 65536 : 0);
+        if (e.multi_scan(this.handle, mask, effort) !== 0)
+            throw Error("Additional scanner failed.");
+        const bytes = new Uint8Array(e.memory.buffer, e.multi_output(this.handle), e.multi_output_len(this.handle));
+        const found = JSON.parse(new TextDecoder().decode(bytes));
+        for (const b of [...found.barcodes, ...(found.regions ?? [])])
+            if (!formats.includes(b.format))
+                throw Error("Scanner returned a disabled format.");
+        return found;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.medium?.dispose();
+        if (this.handle)
+            this.extra?.multi_free(this.handle);
+        this.handle = 0;
+        this.disposed = true;
+    }
+}

package/dist/multiformat-host.d.ts

@@ -0,0 +1,121 @@
+/** Independent EAN-13 supplied-region scanner. Experimental; no localizer or
+ * reference decoder is imported. All result confidence remains uncalibrated. */
+export type Point = readonly [number, number];
+export type Quad = readonly [Point, Point, Point, Point];
+export interface Image {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    channels: 1 | 3 | 4;
+    stride: number;
+}
+export interface Policy {
+    transitionCleanup?: boolean;
+    sourceIdentity?: boolean;
+    interiorNormalization?: boolean;
+    guardBias?: boolean;
+    /** Experimental: accept one full-quiet scanline; increases false-read risk. Default false. */
+    allowSingleRow?: boolean;
+    maxRetryPathsPerCandidate?: number;
+    maxRetryPathsPerFrame?: number;
+    maxAssociationChecks?: number;
+    maxAssociationPixels?: number;
+    maxResults?: number;
+}
+export interface Detection {
+    text: string;
+    polygon: Quad;
+    support: number;
+    axis: number;
+}
+export interface Barcode extends Detection {
+    candidate_indices: number[];
+}
+export interface Observation {
+    text: string;
+    axis: number;
+    fraction: number;
+    left: number;
+    right: number;
+    cost: number;
+    gap: number;
+}
+export interface Candidate {
+    candidate_index: number;
+    coverage: readonly (readonly [number | null, number | null])[];
+    error: boolean;
+    error_detail: 'invalid_geometry' | 'sampling_error' | null;
+    unfinished: boolean;
+    ms: number;
+    work: Record<string, number>;
+    detections: Detection[];
+    observations: Observation[];
+}
+export interface ScanFrame {
+    unfinished: boolean;
+    candidates: Candidate[];
+    barcodes: Barcode[];
+    reconciliation: {
+        comparisons: number;
+        merged: number;
+        ambiguous: number;
+        conflicting: number;
+        pending_observations: number;
+        truncated: boolean;
+        source_pairs: number;
+        source_matches: number;
+        source_pixels: number;
+        source_capped: number;
+        pending_coverage_checks: number;
+        pending_quarantined: number;
+    };
+}
+export interface ScanResult extends ScanFrame {
+    /** This WASM build has no internal clock. Candidate ms values are unavailable zeros. */
+    candidateTimingsAvailable: false;
+    /** Actual host wall time, including validation, preparation/copies, decode and JSON parsing. */
+    elapsedMs: number;
+}
+/** Explicit indices reject sparse arrays; nonfinite numeric geometry reaches Rust. */
+export declare function isQuadShape(value: unknown): value is Quad;
+export declare class ScannerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Validate before asynchronous work; returned bytes are owned by the caller. */
+export declare function snapshotImage(image: Image): Image;
+export declare function snapshotPolicy(policy: Policy): Policy;
+/** Uncalibrated support ordering; ties preserve spatial output order. */
+export declare function rankBarcodes(barcodes: readonly Barcode[]): Barcode[];
+export declare class IndependentScanner {
+    #private;
+    private constructor();
+    static create(bytes: BufferSource): Promise<IndependentScanner>;
+    /** Localization-only entry point for opt-in independent linear decoders. */
+    localizeOnly(image: Image, fitLimit?: number): {
+        proposals: {
+            polygon: Quad;
+            score?: number;
+        }[];
+        workLimited?: boolean;
+        omitted?: number;
+    };
+    /** All supplied regions receive the cheap pass; successful reads do not end scanning. */
+    scan(image: Image, quads: readonly Quad[], policy?: Policy): ScanResult;
+    /** Synchronous transaction: upload once, localize, decode the same owned pixels. */
+    scanLocalized(image: Image, policy?: Policy, fitLimit?: number, fullFrame?: boolean): {
+        localization: any;
+        searchWindows: {
+            kind: string;
+            polygon: number[][];
+            candidateIndex: any;
+        }[];
+        scan: ScanResult;
+        localizationMs: number;
+        decodingMs: number;
+        scanMs: number;
+    };
+    /** Separate convenience; it never changes find-all work or suppresses frame evidence. */
+    best(result: ScanFrame): Barcode | undefined;
+    dispose(): void;
+}

package/dist/multiformat-host.js

@@ -0,0 +1,207 @@
+/** Explicit indices reject sparse arrays; nonfinite numeric geometry reaches Rust. */
+export function isQuadShape(value) {
+    if (!Array.isArray(value) || value.length !== 4)
+        return false;
+    for (let i = 0; i < 4; i++) {
+        if (!Object.hasOwn(value, i))
+            return false;
+        const point = value[i];
+        if (!Array.isArray(point) || point.length !== 2)
+            return false;
+        for (let j = 0; j < 2; j++)
+            if (!Object.hasOwn(point, j) || typeof point[j] !== 'number')
+                return false;
+    }
+    return true;
+}
+export class ScannerError extends Error {
+    code;
+    constructor(code, message) { super(message); this.name = 'ScannerError'; this.code = code; }
+}
+function integer(value, min, max, name) {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new ScannerError('invalid_input', `Invalid ${name}`);
+    return value;
+}
+function status(code) {
+    if (code !== 0)
+        throw new ScannerError(`core_${code}`, `Independent scanner rejected operation (${code})`);
+}
+function parseFrame(text, count) {
+    const v = JSON.parse(text);
+    if (!v || typeof v !== 'object')
+        throw new ScannerError('invalid_output', 'Expected frame object');
+    const f = v;
+    if (!Array.isArray(f.candidates) || f.candidates.length !== count || !Array.isArray(f.barcodes) || typeof f.unfinished !== 'boolean' || !f.reconciliation)
+        throw new ScannerError('invalid_output', 'Invalid frame shape');
+    for (let i = 0; i < f.candidates.length; i++) {
+        const c = f.candidates[i];
+        if (c.candidate_index !== i || !Array.isArray(c.coverage) || c.coverage.length !== 4 || !Array.isArray(c.observations) || !Array.isArray(c.detections) || typeof c.error !== 'boolean')
+            throw new ScannerError('invalid_output', 'Invalid candidate shape');
+    }
+    for (const b of f.barcodes)
+        if (!/^\d{13}$/.test(b.text) || !Array.isArray(b.polygon) || b.polygon.length !== 4 || !Array.isArray(b.candidate_indices) || b.candidate_indices.some(i => !Number.isInteger(i) || i < 0 || i >= count))
+            throw new ScannerError('invalid_output', 'Invalid barcode shape');
+    return f;
+}
+/** Validate before asynchronous work; returned bytes are owned by the caller. */
+export function snapshotImage(image) {
+    if (!image || typeof image !== 'object')
+        throw new ScannerError('invalid_input', 'Invalid image');
+    const width = integer(image.width, 1, 0xffffffff, 'width'), height = integer(image.height, 1, 0xffffffff, 'height');
+    if (![1, 3, 4].includes(image.channels) || !(image.data instanceof Uint8Array))
+        throw new ScannerError('invalid_input', 'Invalid image buffer/channels');
+    const stride = integer(image.stride, width * image.channels, 0xffffffff, 'stride');
+    const required = integer((height - 1) * stride + width * image.channels, 1, 128 * 1024 * 1024, 'image length');
+    if (image.data.byteLength < required)
+        throw new ScannerError('invalid_input', 'Image buffer is too short');
+    return { data: new Uint8Array(image.data.subarray(0, required)), width, height, channels: image.channels, stride };
+}
+export function snapshotPolicy(policy) {
+    if (!policy || typeof policy !== 'object')
+        throw new ScannerError('invalid_input', 'Invalid policy');
+    const copy = { ...policy };
+    for (const key of ['transitionCleanup', 'sourceIdentity', 'interiorNormalization', 'guardBias', 'allowSingleRow'])
+        if (copy[key] !== undefined && typeof copy[key] !== 'boolean')
+            throw new ScannerError('invalid_input', `Invalid ${key}`);
+    integer(copy.maxRetryPathsPerCandidate ?? 512, 0, 4096, 'candidate budget');
+    integer(copy.maxRetryPathsPerFrame ?? 8192, 0, 65536, 'frame budget');
+    integer(copy.maxAssociationChecks ?? 200000, 0, 2000000, 'comparison budget');
+    integer(copy.maxAssociationPixels ?? 2000000, 0, 16000000, 'pixel budget');
+    integer(copy.maxResults ?? 1024, 1, 4096, 'result budget');
+    return copy;
+}
+/** Uncalibrated support ordering; ties preserve spatial output order. */
+export function rankBarcodes(barcodes) {
+    return [...barcodes].sort((a, b) => b.support - a.support);
+}
+export class IndependentScanner {
+    #exports;
+    #handle;
+    constructor(exports) {
+        this.#exports = exports;
+        if (exports.regions_version() !== 1)
+            throw new ScannerError('abi_version', 'Unsupported scanner ABI');
+        this.#handle = exports.regions_new();
+        if (!this.#handle)
+            throw new ScannerError('capacity', 'Scanner handle capacity exhausted');
+    }
+    static async create(bytes) {
+        const module = await WebAssembly.compile(bytes);
+        const instance = await WebAssembly.instantiate(module, {});
+        const exports = instance.exports;
+        for (const name of ['regions_localize', 'regions_version', 'regions_new', 'regions_destroy', 'regions_prepare', 'regions_input_ptr', 'regions_input_len', 'regions_quads_ptr', 'regions_output_ptr', 'regions_output_len', 'regions_scan']) {
+            if (typeof instance.exports[name] !== 'function')
+                throw new ScannerError('abi_shape', `Missing ${name}`);
+        }
+        if (!(exports.memory instanceof WebAssembly.Memory))
+            throw new ScannerError('abi_shape', 'Missing memory');
+        return new IndependentScanner(exports);
+    }
+    /** Localization-only entry point for opt-in independent linear decoders. */
+    localizeOnly(image, fitLimit = 8) {
+        if (!this.#handle)
+            throw new ScannerError('disposed', 'Scanner is disposed');
+        const width = integer(image.width, 3, 0xffffffff, 'width'), height = integer(image.height, 3, 0xffffffff, 'height');
+        if (![1, 3, 4].includes(image.channels) || !(image.data instanceof Uint8Array))
+            throw new ScannerError('invalid_input', 'Invalid image buffer/channels');
+        const stride = integer(image.stride, width * image.channels, 0xffffffff, 'stride');
+        const required = integer((height - 1) * stride + width * image.channels, 1, 128 * 1024 * 1024, 'image length');
+        if (image.data.byteLength < required)
+            throw new ScannerError('invalid_input', 'Image buffer is too short');
+        integer(fitLimit, 0, 8, 'shear limit');
+        const e = this.#exports, id = this.#handle;
+        status(e.regions_prepare(id, width, height, image.channels, stride));
+        if (e.regions_input_len(id) !== required)
+            throw new ScannerError('abi_shape', 'Input allocation mismatch');
+        new Uint8Array(e.memory.buffer, e.regions_input_ptr(id), required).set(image.data.subarray(0, required));
+        status(e.regions_localize(id, fitLimit));
+        const localization = JSON.parse(new TextDecoder().decode(new Uint8Array(e.memory.buffer, e.regions_output_ptr(id), e.regions_output_len(id))));
+        if (!Array.isArray(localization.proposals) || localization.proposals.length > 32 || localization.proposals.some(p => !isQuadShape(p.polygon)))
+            throw new ScannerError('abi_shape', 'Invalid localization');
+        return localization;
+    }
+    /** All supplied regions receive the cheap pass; successful reads do not end scanning. */
+    scan(image, quads, policy = {}) {
+        return this.#scan(image, quads, policy, false);
+    }
+    /** Synchronous transaction: upload once, localize, decode the same owned pixels. */
+    scanLocalized(image, policy = {}, fitLimit = 8, fullFrame = false) {
+        const start = performance.now();
+        if (!this.#handle)
+            throw new ScannerError('disposed', 'Scanner is disposed');
+        if (!image || typeof image !== 'object')
+            throw new ScannerError('invalid_input', 'Invalid image');
+        const width = integer(image.width, 3, 0xffffffff, 'width'), height = integer(image.height, 3, 0xffffffff, 'height');
+        if (![1, 3, 4].includes(image.channels) || !(image.data instanceof Uint8Array))
+            throw new ScannerError('invalid_input', 'Invalid image buffer/channels');
+        const stride = integer(image.stride, width * image.channels, 0xffffffff, 'stride');
+        const required = integer((height - 1) * stride + width * image.channels, 1, 128 * 1024 * 1024, 'image length');
+        if (image.data.byteLength < required)
+            throw new ScannerError('invalid_input', 'Image buffer is too short');
+        integer(fitLimit, 0, 8, 'shear limit');
+        const e = this.#exports, id = this.#handle;
+        status(e.regions_prepare(id, width, height, image.channels, stride));
+        if (e.regions_input_len(id) !== required)
+            throw new ScannerError('abi_shape', 'Input allocation mismatch');
+        new Uint8Array(e.memory.buffer, e.regions_input_ptr(id), required).set(image.data.subarray(0, required));
+        status(e.regions_localize(id, fitLimit));
+        const localization = JSON.parse(new TextDecoder().decode(new Uint8Array(e.memory.buffer, e.regions_output_ptr(id), e.regions_output_len(id))));
+        if (!Array.isArray(localization.proposals) || localization.proposals.length > 32 || localization.proposals.some((p) => !isQuadShape(p.polygon)))
+            throw new ScannerError('abi_shape', 'Invalid localization');
+        const searchWindows = fullFrame ? [{ kind: 'full_frame_search', polygon: [[0, 0], [width - 1, 0], [width - 1, height - 1], [0, height - 1]], candidateIndex: localization.proposals.length }] : [];
+        const localizationMs = performance.now() - start, decodeStart = performance.now();
+        const scan = this.#scan(image, [...localization.proposals.map((p) => p.polygon), ...searchWindows.map(p => p.polygon)], policy, true);
+        return { localization, searchWindows, scan, localizationMs, decodingMs: performance.now() - decodeStart, scanMs: performance.now() - start };
+    }
+    #scan(image, quads, policy, prepared) {
+        const start = performance.now();
+        if (!this.#handle)
+            throw new ScannerError('disposed', 'Scanner is disposed');
+        if (!image || typeof image !== 'object' || !Array.isArray(quads) || !policy || typeof policy !== 'object')
+            throw new ScannerError('invalid_input', 'Invalid scan arguments');
+        for (const key of ['transitionCleanup', 'sourceIdentity', 'interiorNormalization', 'guardBias', 'allowSingleRow'])
+            if (policy[key] !== undefined && typeof policy[key] !== 'boolean')
+                throw new ScannerError('invalid_input', `Invalid ${key}`);
+        const e = this.#exports, id = this.#handle;
+        const width = integer(image.width, 1, 0xffffffff, 'width'), height = integer(image.height, 1, 0xffffffff, 'height');
+        if (![1, 3, 4].includes(image.channels) || !(image.data instanceof Uint8Array))
+            throw new ScannerError('invalid_input', 'Invalid image buffer/channels');
+        const stride = integer(image.stride, width * image.channels, 0xffffffff, 'stride');
+        const required = integer((height - 1) * stride + width * image.channels, 1, 128 * 1024 * 1024, 'image length');
+        if (image.data.byteLength < required)
+            throw new ScannerError('invalid_input', 'Image buffer is too short');
+        integer(quads.length, 0, 64, 'candidate count');
+        for (const q of quads)
+            if (!isQuadShape(q))
+                throw new ScannerError('invalid_input', 'Invalid quad shape');
+        const perCandidate = integer(policy.maxRetryPathsPerCandidate ?? 512, 0, 4096, 'candidate budget');
+        const perFrame = integer(policy.maxRetryPathsPerFrame ?? 8192, 0, 65536, 'frame budget');
+        const checks = integer(policy.maxAssociationChecks ?? 200000, 0, 2000000, 'comparison budget');
+        const pixels = integer(policy.maxAssociationPixels ?? 2000000, 0, 16000000, 'pixel budget');
+        const results = integer(policy.maxResults ?? 1024, 1, 4096, 'result budget');
+        const flags = (policy.transitionCleanup ? 1 : 0) | (policy.sourceIdentity ? 2 : 0) | (policy.interiorNormalization ? 4 : 0) | (policy.guardBias ? 8 : 0) | (policy.allowSingleRow ? 16 : 0);
+        if (!prepared) {
+            status(e.regions_prepare(id, width, height, image.channels, stride));
+            if (e.regions_input_len(id) !== required)
+                throw new ScannerError('abi_shape', 'Input allocation mismatch');
+            new Uint8Array(e.memory.buffer, e.regions_input_ptr(id), required).set(image.data.subarray(0, required));
+        }
+        const coordinates = new Float64Array(e.memory.buffer, e.regions_quads_ptr(id), 512);
+        quads.forEach((q, i) => q.forEach((p, j) => { coordinates[i * 8 + j * 2] = p[0]; coordinates[i * 8 + j * 2 + 1] = p[1]; }));
+        status(e.regions_scan(id, quads.length, flags, perCandidate, perFrame, checks, pixels, results));
+        // Scan can grow memory. Never reuse the earlier input/coordinate views.
+        const output = new Uint8Array(e.memory.buffer, e.regions_output_ptr(id), e.regions_output_len(id)).slice();
+        const frame = parseFrame(new TextDecoder().decode(output), quads.length);
+        return { ...frame, candidateTimingsAvailable: false, elapsedMs: performance.now() - start };
+    }
+    /** Separate convenience; it never changes find-all work or suppresses frame evidence. */
+    best(result) {
+        return rankBarcodes(result.barcodes)[0];
+    }
+    dispose() { if (this.#handle) {
+        const id = this.#handle;
+        this.#handle = 0;
+        status(this.#exports.regions_destroy(id));
+    } }
+}

package/dist/policy.d.ts

@@ -0,0 +1,12 @@
+export declare const policy: Readonly<{
+    transitionCleanup: true;
+    sourceIdentity: true;
+    interiorNormalization: true;
+    guardBias: true;
+    allowSingleRow: false;
+    maxRetryPathsPerCandidate: 512;
+    maxRetryPathsPerFrame: 8192;
+    maxAssociationChecks: 200000;
+    maxAssociationPixels: 2000000;
+    maxResults: 1024;
+}>;

package/dist/policy.js

@@ -0,0 +1,12 @@
+export const policy = Object.freeze({
+    transitionCleanup: true,
+    sourceIdentity: true,
+    interiorNormalization: true,
+    guardBias: true,
+    allowSingleRow: false,
+    maxRetryPathsPerCandidate: 512,
+    maxRetryPathsPerFrame: 8192,
+    maxAssociationChecks: 200000,
+    maxAssociationPixels: 2000000,
+    maxResults: 1024,
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "tapirscan",
+  "version": "1.0.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"
+    }
+  },
+  "files": [
+    "dist",
+    "wasm/multiformat.json",
+    "THIRD_PARTY_NOTICES.md",
+    "wasm/low-release-20260915.wasm",
+    "wasm/medium-release-20260915.wasm",
+    "wasm/high-release-20260915.wasm",
+    "wasm/very-high-release-20260915.wasm",
+    "wasm/multiformat.wasm"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/scanner.mjs",
+    "prepack": "npm run build && node scripts/verify-package.mjs"
+  },
+  "devDependencies": {
+    "typescript": "5.8.3"
+  },
+  "keywords": [
+    "barcode",
+    "ean13",
+    "scanner",
+    "wasm",
+    "computer-vision",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Florian Nick",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kleinicke/tapirscan.git",
+    "directory": "bindings/javascript"
+  },
+  "homepage": "https://github.com/kleinicke/tapirscan#readme",
+  "bugs": {
+    "url": "https://github.com/kleinicke/tapirscan/issues"
+  }
+}