tapirscan 1.0.0

package/dist/detail-20260914/continuity.mjs

@@ -0,0 +1,62 @@
+/** A bounded physical continuity claim; equal text alone never establishes identity. */
+export function coveredByContinuousBars(image, point, barcode) {
+    const polygon = barcode.polygon;
+    const left = [(polygon[0][0] + polygon[3][0]) / 2, (polygon[0][1] + polygon[3][1]) / 2];
+    const right = [(polygon[1][0] + polygon[2][0]) / 2, (polygon[1][1] + polygon[2][1]) / 2];
+    const dx = right[0] - left[0], dy = right[1] - left[1], width = Math.hypot(dx, dy);
+    if (width < 45)
+        return false;
+    const nx = -dy / width, ny = dx / width;
+    const along = ((point[0] - left[0]) * dx + (point[1] - left[1]) * dy) / (width * width);
+    const offset = (point[0] - left[0]) * nx + (point[1] - left[1]) * ny;
+    if (along < 0 || along > 1 || Math.abs(offset) > Math.min(128, width * 0.5))
+        return false;
+    const { data, width: iw, height: ih } = image;
+    const gray = (x, y) => {
+        x = Math.max(0, Math.min(iw - 1, x));
+        y = Math.max(0, Math.min(ih - 1, y));
+        const x0 = Math.floor(x), y0 = Math.floor(y), x1 = Math.min(iw - 1, x0 + 1), y1 = Math.min(ih - 1, y0 + 1), fx = x - x0, fy = y - y0;
+        const sample = (a, b) => {
+            const k = (b * iw + a) * 4;
+            return (77 * data[k] + 150 * data[k + 1] + 29 * data[k + 2]) / 256;
+        };
+        return ((sample(x0, y0) * (1 - fx) + sample(x1, y0) * fx) * (1 - fy) +
+            (sample(x0, y1) * (1 - fx) + sample(x1, y1) * fx) * fy);
+    };
+    const count = Math.min(256, Math.max(95, Math.round(width * 1.5)));
+    const profile = (displacement) => {
+        const values = new Float64Array(count);
+        let sum = 0, energy = 0;
+        for (let i = 0; i < count; i++) {
+            const fraction = 0.02 + (0.96 * i) / (count - 1);
+            const v = gray(left[0] + dx * fraction + nx * displacement, left[1] + dy * fraction + ny * displacement);
+            values[i] = v;
+            sum += v;
+            energy += v * v;
+        }
+        return {
+            values,
+            mean: sum / count,
+            deviation: Math.sqrt(Math.max(0, energy / count - (sum / count) ** 2)),
+        };
+    };
+    const reference = profile(0);
+    if (reference.deviation < 5)
+        return false;
+    const agrees = (displacement) => {
+        const row = profile(displacement);
+        if (row.deviation < reference.deviation * 0.65 || row.deviation < 5)
+            return false;
+        let covariance = 0;
+        for (let i = 0; i < count; i++)
+            covariance += (reference.values[i] - reference.mean) * (row.values[i] - row.mean);
+        return covariance / (count * reference.deviation * row.deviation) > 0.8;
+    };
+    if (!agrees(offset) || !agrees(offset / 2))
+        return false;
+    const steps = Math.ceil(Math.abs(offset) * 2);
+    for (let i = 1; i < steps; i++)
+        if (!agrees((offset * i) / steps))
+            return false;
+    return true;
+}

package/dist/detail-20260914/detail-proposals-rich.d.mts

@@ -0,0 +1,13 @@
+/** Source-resolution directional texture proposals. No labels or decoded text as inputs. */
+export function detailProposals(image: any, count?: number, tileSize?: number, sampleStep?: number): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    score: number;
+    coherence: number;
+    energy: number;
+    angle: number;
+}[];

package/dist/detail-20260914/detail-proposals-rich.mjs

@@ -0,0 +1,53 @@
+/** Source-resolution directional texture proposals. No labels or decoded text as inputs. */
+export function detailProposals(image, count = 4, tileSize = 320, sampleStep = 2) {
+    const { data, width, height } = image;
+    const size = 24, step = sampleStep, cells = [];
+    const gray = (x, y) => {
+        const i = (y * width + x) * 4;
+        return (77 * data[i] + 150 * data[i + 1] + 29 * data[i + 2]) / 256;
+    };
+    for (let y = 1; y + size < height; y += size)
+        for (let x = 1; x + size < width; x += size) {
+            let xx = 0, yy = 0, xy = 0, sx = 0, sy = 0, n = 0;
+            for (let j = y; j < y + size; j += step)
+                for (let i = x; i < x + size; i += step) {
+                    const v = gray(i, j), gx = gray(i + 1, j) - v, gy = gray(i, j + 1) - v;
+                    xx += gx * gx;
+                    yy += gy * gy;
+                    xy += gx * gy;
+                    sx += gx;
+                    sy += gy;
+                    n++;
+                }
+            xx = Math.max(0, xx - (sx * sx) / n);
+            yy = Math.max(0, yy - (sy * sy) / n);
+            xy -= (sx * sy) / n;
+            const energy = (xx + yy) / n, coherence = Math.sqrt((xx - yy) ** 2 + 4 * xy * xy) / (xx + yy + 1);
+            const score = Math.sqrt(energy) * coherence * coherence;
+            if (score > 5)
+                cells.push({
+                    x: x + size / 2,
+                    y: y + size / 2,
+                    score,
+                    coherence,
+                    energy,
+                    angle: 0.5 * Math.atan2(2 * xy, xx - yy),
+                });
+        }
+    cells.sort((a, b) => b.score - a.score);
+    const selected = [];
+    for (const c of cells) {
+        if (selected.some((s) => Math.hypot(s.x - c.x, s.y - c.y) < 128))
+            continue;
+        selected.push({
+            ...c,
+            left: Math.max(0, Math.min(width - tileSize, Math.round(c.x - tileSize / 2))),
+            top: Math.max(0, Math.min(height - tileSize, Math.round(c.y - tileSize / 2))),
+            width: Math.min(width, tileSize),
+            height: Math.min(height, tileSize),
+        });
+        if (selected.length === count)
+            break;
+    }
+    return selected;
+}

package/dist/detail-20260914/direct-recovery.d.mts

@@ -0,0 +1,28 @@
+/** Bounded source-guided hypotheses, without another localizer/shear search per crop. */
+export function recoverDirectSeed(image: any, scanner: any, policy: any, baseline: any, budget?: number, factor?: number, sequential?: boolean, scharr?: boolean, minimumSpan?: number, maxDirections?: number): {
+    barcodes: any[];
+    additions: any[];
+    attempts: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        factor: number;
+        frame: any;
+        reads: any;
+        deferredReads: any;
+        proposals: {
+            polygon: number[][];
+            score: number;
+            text: string;
+        }[];
+        unfinished: any;
+    }[];
+    proposals: {
+        polygon: number[][];
+        score: number;
+        text: string;
+    }[];
+    extraMs: number;
+    searchLimited: boolean;
+};

package/dist/detail-20260914/direct-recovery.mjs

@@ -0,0 +1,139 @@
+import { makeCanvas } from "../detail-canvas.js";
+import { detailProposals } from "./detail-proposals-rich.mjs";
+import { sourceEvidence } from "./source-evidence.mjs";
+import { coveredByContinuousBars } from "./continuity.mjs";
+function refinedAngle(image, seed) {
+    const gray = (x, y) => {
+        const i = (y * image.width + x) * 4;
+        return (77 * image.data[i] + 150 * image.data[i + 1] + 29 * image.data[i + 2]) / 256;
+    };
+    let xx = 0, yy = 0, xy = 0, sx = 0, sy = 0, n = 0;
+    for (let y = Math.max(1, Math.round(seed.y) - 12); y < Math.min(image.height - 1, seed.y + 12); y++)
+        for (let x = Math.max(1, Math.round(seed.x) - 12); x < Math.min(image.width - 1, seed.x + 12); x++) {
+            const a = gray(x - 1, y - 1), b = gray(x, y - 1), c = gray(x + 1, y - 1), d = gray(x - 1, y), e = gray(x + 1, y), f = gray(x - 1, y + 1), g = gray(x, y + 1), h = gray(x + 1, y + 1);
+            const gx = (3 * (c - a) + 10 * (e - d) + 3 * (h - f)) / 16, gy = (3 * (f - a) + 10 * (g - b) + 3 * (h - c)) / 16;
+            xx += gx * gx;
+            yy += gy * gy;
+            xy += gx * gy;
+            sx += gx;
+            sy += gy;
+            n++;
+        }
+    return 0.5 * Math.atan2(2 * (xy - (sx * sy) / n), xx - (sx * sx) / n - yy + (sy * sy) / n);
+}
+function contains(point, q) {
+    let hit = false;
+    for (let i = 0, j = q.length - 1; i < q.length; j = i++) {
+        if (q[i][1] > point[1] !== q[j][1] > point[1] &&
+            point[0] < ((q[j][0] - q[i][0]) * (point[1] - q[i][1])) / (q[j][1] - q[i][1]) + q[i][0])
+            hit = !hit;
+    }
+    return hit;
+}
+function covered(image, point, barcode) {
+    return contains(point, barcode.polygon) || coveredByContinuousBars(image, point, barcode);
+}
+function sourceSpan(p) {
+    const dx = p[1][0] - p[0][0], dy = p[1][1] - p[0][1];
+    return (Math.abs(dx * (p[3][1] - p[0][1]) - dy * (p[3][0] - p[0][0])) /
+        Math.max(1e-9, Math.hypot(dx, dy)));
+}
+/** Bounded source-guided hypotheses, without another localizer/shear search per crop. */
+export function recoverDirectSeed(image, scanner, policy, baseline, budget = 64, factor = 3, sequential = false, scharr = false, minimumSpan = 0, maxDirections = Infinity) {
+    const start = performance.now();
+    const seeds = detailProposals(image, 2, 256, 4);
+    const additions = [], attempts = [], proposals = [];
+    const tile = makeCanvas(1, 1), up = makeCanvas(1, 1);
+    const tc = tile.getContext("2d"), uc = up.getContext("2d", { willReadFrequently: true });
+    for (const seed of seeds) {
+        if (seed.score < seeds[0].score * 0.6)
+            continue;
+        if ([...baseline.scan.barcodes, ...additions].some((b) => covered(image, [seed.x, seed.y], b)))
+            continue;
+        const quads = [];
+        const initialAngle = scharr ? refinedAngle(image, seed) : seed.angle;
+        const directions = (scharr ? [0, -3, 3] : [0, -5, 5, -10, 10, -15, 15, -20, 20]).map((offset) => initialAngle + (offset * Math.PI) / 180);
+        for (const angle of directions) {
+            const c = Math.cos(angle), s = Math.sin(angle);
+            const polygon = [
+                [-96, -24],
+                [96, -24],
+                [96, 24],
+                [-96, 24],
+            ].map(([u, v]) => [seed.x + u * c - v * s, seed.y + u * s + v * c]);
+            const evidence = sourceEvidence(image, polygon, true, 32);
+            if (Math.max(evidence.transitions, evidence.localTransitions) >= 32)
+                quads.push(polygon);
+            if (quads.length >= maxDirections)
+                break;
+        }
+        if (!quads.length)
+            continue;
+        const size = 256, w = Math.min(size, image.width), h = Math.min(size, image.height);
+        const x = Math.max(0, Math.min(image.width - w, Math.round(seed.x - w / 2)));
+        const y = Math.max(0, Math.min(image.height - h, Math.round(seed.y - h / 2)));
+        const bytes = new Uint8ClampedArray(w * h * 4);
+        for (let row = 0; row < h; row++) {
+            const from = ((y + row) * image.width + x) * 4;
+            bytes.set(image.data.subarray(from, from + w * 4), row * w * 4);
+        }
+        tile.width = w;
+        tile.height = h;
+        tc.putImageData({ data: bytes, width: w, height: h }, 0, 0);
+        up.width = w * factor;
+        up.height = h * factor;
+        uc.imageSmoothingEnabled = true;
+        uc.drawImage(tile, 0, 0, up.width, up.height);
+        const pixels = uc.getImageData(0, 0, up.width, up.height);
+        const batches = sequential ? quads.map((q) => [q]) : [quads];
+        for (const batch of batches) {
+            const result = scanner.scan({
+                data: new Uint8Array(pixels.data.buffer),
+                width: up.width,
+                height: up.height,
+                channels: 4,
+                stride: up.width * 4,
+            }, batch.map((q) => q.map(([a, b]) => [(a - x) * factor, (b - y) * factor])), {
+                ...policy,
+                maxRetryPathsPerCandidate: budget,
+                maxRetryPathsPerFrame: budget * batch.length,
+            });
+            const allReads = result.barcodes.map((b) => ({
+                ...b,
+                polygon: b.polygon.map(([a, b]) => [x + a / factor, y + b / factor]),
+            }));
+            const reads = allReads.filter((b) => sourceSpan(b.polygon) >= minimumSpan);
+            const deferredReads = allReads.filter((b) => sourceSpan(b.polygon) < minimumSpan);
+            for (const read of reads) {
+                const center = read.polygon.reduce((a, p) => [a[0] + p[0] / 4, a[1] + p[1] / 4], [0, 0]);
+                if (![...baseline.scan.barcodes, ...additions].some((old) => old.text === read.text && covered(image, center, old)))
+                    additions.push(read);
+            }
+            const localized = batch.map((polygon) => ({ polygon, score: seed.score, text: "" }));
+            proposals.push(...localized);
+            attempts.push({
+                x,
+                y,
+                w,
+                h,
+                factor,
+                // Raw evidence remains in crop coordinates with this explicit transform.
+                frame: result,
+                reads,
+                deferredReads,
+                proposals: localized,
+                unfinished: result.unfinished || deferredReads.length > 0,
+            });
+            if (sequential && reads.some((b) => covered(image, [seed.x, seed.y], b)))
+                break;
+        }
+    }
+    return {
+        barcodes: [...baseline.scan.barcodes, ...additions],
+        additions,
+        attempts,
+        proposals,
+        extraMs: performance.now() - start,
+        searchLimited: true,
+    };
+}

package/dist/detail-20260914/host.d.mts

@@ -0,0 +1,40 @@
+/** Explicit indices reject sparse arrays; nonfinite numeric geometry reaches Rust. */
+export function isQuadShape(value: any): boolean;
+/** Validate before asynchronous work; returned bytes are owned by the caller. */
+export function snapshotImage(image: any): {
+    data: Uint8Array<any>;
+    width: any;
+    height: any;
+    channels: any;
+    stride: any;
+};
+export function snapshotPolicy(policy: any): any;
+/** Uncalibrated support ordering; ties preserve spatial output order. */
+export function rankBarcodes(barcodes: any): any[];
+export class ScannerError extends Error {
+    constructor(code: any, message: any);
+    code: any;
+}
+export class IndependentScanner {
+    static create(bytes: any): Promise<IndependentScanner>;
+    constructor(exports: any);
+    /** All supplied regions receive the cheap pass; successful reads do not end scanning. */
+    scan(image: any, quads: any, policy?: {}): any;
+    /** Synchronous transaction: upload once, localize, decode the same owned pixels. */
+    scanLocalized(image: any, policy?: {}, fitLimit?: number, fullFrame?: boolean, transform?: undefined): {
+        localization: any;
+        searchWindows: {
+            kind: string;
+            polygon: number[][];
+            candidateIndex: any;
+        }[];
+        scan: any;
+        localizationMs: number;
+        decodingMs: number;
+        scanMs: number;
+    };
+    /** Separate convenience; it never changes find-all work or suppresses frame evidence. */
+    best(result: any): any;
+    dispose(): void;
+    #private;
+}

package/dist/detail-20260914/host.mjs

@@ -0,0 +1,280 @@
+/** 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);
+    }
+    /** 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, transform = undefined) {
+        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));
+        let localization = JSON.parse(new TextDecoder().decode(new Uint8Array(e.memory.buffer, e.regions_output_ptr(id), e.regions_output_len(id))));
+        if (transform)
+            localization = transform(localization);
+        if (localization.retryMask)
+            policy = { ...policy, retryMask: localization.retryMask };
+        if (!Array.isArray(localization.proposals) ||
+            localization.proposals.length > (fullFrame ? 63 : 64) ||
+            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];
+        }));
+        const mask = policy.retryMask ?? [4294967295, 4294967295];
+        if (!Array.isArray(mask) || mask.length !== 2)
+            throw new ScannerError("invalid_input", "Invalid retry mask");
+        for (const value of mask)
+            integer(value, 0, 4294967295, "retry mask");
+        if (e.regions_scan_mask)
+            status(e.regions_scan_mask(id, quads.length, flags, perCandidate, perFrame, checks, pixels, results, mask[0], mask[1]));
+        else if (policy.retryMask)
+            throw new ScannerError("abi_shape", "Missing retry scheduling ABI");
+        else
+            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/detail-20260914/scanner.d.mts

@@ -0,0 +1,12 @@
+/** Preserve undecoded geometry without assigning crop indices to primary proposals. */
+export function detailRegions(found: any, recovery: any): any;
+/** Workbench composition. Each crop keeps its own candidate-index namespace. */
+export class DetailScanner {
+    static create(primaryBytes: any, recoveryBytes: any, directions: any): Promise<DetailScanner>;
+    constructor(primary: any, recovery: any, directions: any);
+    primary: any;
+    recovery: any;
+    directions: any;
+    scanLocalized(image: any, policy: any, fitLimit: any, fullFrame: any): any;
+    dispose(): void;
+}