tapirscan 1.0.0 → 1.2.0

package/dist/detail-runtime/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, coverage?: any[]): {
+    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-runtime/direct-recovery.mjs

@@ -0,0 +1,142 @@
+import { makeCanvas } from "../detail-canvas.js";
+import { detailProposals } from "../detail-20260914/detail-proposals-rich.mjs";
+import { sourceEvidence } from "../detail-20260914/source-evidence.mjs";
+import { coveredByContinuousBars } from "../detail-20260914/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, coverage = []) {
+    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 (coverage.some((quad) => containsPoint([seed.x, seed.y], quad)))
+            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,
+    };
+}
+import { containsPoint } from "../multiformat/coverage.js";

package/dist/detail-runtime/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-runtime/host.mjs

@@ -0,0 +1,282 @@
+/** 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");
+        if (policy.finishCandidates && e.regions_completion_supported?.() !== 1)
+            throw new Error("This WASM build does not support finishCandidates");
+        const flags = (policy.transitionCleanup ? 1 : 0) |
+            (policy.sourceIdentity ? 2 : 0) |
+            (policy.interiorNormalization ? 4 : 0) |
+            (policy.guardBias ? 8 : 0) |
+            (policy.allowSingleRow ? 16 : 0) | (policy.finishCandidates ? 32 : 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-runtime/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, coverage?: any[]): any;
+    dispose(): void;
+}

package/dist/detail-runtime/scanner.mjs

@@ -0,0 +1,70 @@
+import { IndependentScanner } from "./host.mjs";
+import { evidencePlan } from "../detail-20260914/source-evidence.mjs";
+import { recoverDirectSeed } from "./direct-recovery.mjs";
+import { uncoveredRetryMask } from "../multiformat/coverage.js";
+/** Workbench composition. Each crop keeps its own candidate-index namespace. */
+export class DetailScanner {
+    constructor(primary, recovery, directions) {
+        this.primary = primary;
+        this.recovery = recovery;
+        this.directions = directions;
+    }
+    static async create(primaryBytes, recoveryBytes, directions) {
+        if (![1, 2, 3].includes(directions))
+            throw new Error("Invalid recovery direction budget");
+        const primary = await IndependentScanner.create(primaryBytes);
+        try {
+            return new DetailScanner(primary, await IndependentScanner.create(recoveryBytes), directions);
+        }
+        catch (error) {
+            primary.dispose();
+            throw error;
+        }
+    }
+    scanLocalized(image, policy, fitLimit, fullFrame, coverage = []) {
+        // The source samplers use tightly packed RGBA, as supplied by the camera worker.
+        if (image.channels !== 4 || image.stride !== image.width * 4)
+            throw new Error("Detail discovery requires tightly packed RGBA");
+        const start = performance.now();
+        const found = this.primary.scanLocalized(image, policy, fitLimit, fullFrame, (localization) => {
+            const plan = evidencePlan(image, localization, 48);
+            return coverage.length
+                ? { ...plan, retryMask: uncoveredRetryMask(plan.proposals, coverage, plan.retryMask) }
+                : plan;
+        });
+        const recovery = recoverDirectSeed(image, this.recovery, policy, found, 64, 3, true, true, 1, this.directions, coverage);
+        return {
+            ...found,
+            // Do not concatenate crop-local candidate indices into the primary frame.
+            // Consumers use detailRegions; raw frames and coordinate transforms stay inspectable.
+            recovery,
+            detailRegions: detailRegions(found, recovery),
+            scanMs: performance.now() - start,
+        };
+    }
+    dispose() {
+        this.primary.dispose();
+        this.recovery.dispose();
+    }
+}
+/** Preserve undecoded geometry without assigning crop indices to primary proposals. */
+export function detailRegions(found, recovery) {
+    const decoded = new Set(found.scan.barcodes.flatMap((barcode) => barcode.candidate_indices));
+    const regions = recovery.barcodes.map((barcode) => ({
+        text: barcode.text,
+        polygon: barcode.polygon,
+        support: barcode.support,
+    }));
+    found.localization.proposals.forEach((proposal, index) => {
+        if (!decoded.has(index))
+            regions.push({ text: "", polygon: proposal.polygon, score: proposal.score });
+    });
+    for (const attempt of recovery.attempts) {
+        const accepted = new Set(attempt.reads.flatMap((barcode) => barcode.candidate_indices));
+        attempt.proposals.forEach((proposal, index) => {
+            if (!accepted.has(index))
+                regions.push({ text: "", polygon: proposal.polygon, score: proposal.score });
+        });
+    }
+    return regions;
+}

package/dist/detail.d.ts

@@ -1,5 +1,5 @@
-import { type DetailResult } from "./detail-20260914/scanner.mjs";
-import { IndependentScanner, type Image, type ScanFrame } from "./host.js";
+import { type DetailResult } from "./detail-runtime/scanner.mjs";
+import { IndependentScanner, type Image, type Quad } from "./host.js";
 import type { Mode } from "./index.js";
 export declare const fitLimits: {
     readonly low: 0;
@@ -13,7 +13,6 @@ export declare class ReleaseDetailScanner {
     private disposed;
     private constructor();
     static create(primary: ArrayBuffer, low: ArrayBuffer, mode: Exclude<Mode, "low">): Promise<ReleaseDetailScanner>;
-    scanLocalized(image: Image, policy: Parameters<IndependentScanner["scanLocalized"]>[1], fit: number, full: boolean): DetailResult;
-    best(frame: ScanFrame): import("./host.js").Barcode | undefined;
+    scanLocalized(image: Image, policy: Parameters<IndependentScanner["scanLocalized"]>[1], fit: number, full: boolean, coverage?: readonly Quad[]): DetailResult;
     dispose(): void;
 }

package/dist/detail.js

@@ -1,4 +1,4 @@
-import { DetailScanner } from "./detail-20260914/scanner.mjs";
+import { DetailScanner } from "./detail-runtime/scanner.mjs";
 export const fitLimits = { low: 0, medium: 1, high: 4, "very-high": 1 };
 /** Preserve the public gray/RGB/RGBA and padded-stride image contract. */
 function packed(image) {
@@ -49,10 +49,10 @@ export class ReleaseDetailScanner {
     static async create(primary, low, mode) {
         return new ReleaseDetailScanner(await DetailScanner.create(primary, low, mode === "medium" ? 1 : 2));
     }
-    scanLocalized(image, policy, fit, full) {
+    scanLocalized(image, policy, fit, full, coverage = []) {
         if (this.disposed)
             throw Error("Scanner is disposed");
-        const result = this.scanner.scanLocalized(packed(image), policy ?? {}, fit, full);
+        const result = this.scanner.scanLocalized(packed(image), policy ?? {}, fit, full, coverage);
         const primaryCount = result.scan.barcodes.length;
         const barcodes = result.recovery.barcodes.map((b, i) => i < primaryCount ? b : { ...b, candidate_indices: [] });
         const localization = result.localization;
@@ -75,9 +75,6 @@ export class ReleaseDetailScanner {
             },
         };
     }
-    best(frame) {
-        return frame.barcodes.reduce((best, b) => (!best || b.support > best.support ? b : best), undefined);
-    }
     dispose() {
         if (!this.disposed) {
             this.scanner.dispose();