tapirscan 1.0.0 → 1.2.0

package/README.md

@@ -1,7 +1,12 @@
 # Tapirscan for JavaScript and TypeScript
 
+This guide describes the 1.2.0 API revision. See [migration](../../docs/API_MIGRATION.md).
+Build/install this checkout using [the development guide](../../docs/DEVELOPMENT.md)
+to use these changes before publication; older registry packages use their own
+versioned API.
+
 Scan image pixels in a browser or Node with the same Rust/WASM core.
-[Quick start](#quick-start) · [WASM loading](#wasm-loading) · [Functions](#functions) · [All options](#all-options) · [Results](#results)
+[Try the live demo](https://tapirscan.netlify.app) · [Quick start](#quick-start) · [WASM loading](#wasm-loading) · [Functions](#functions) · [All options](#all-options) · [Results](#results)
 
 ## Quick start
 
@@ -9,9 +14,9 @@ Scan image pixels in a browser or Node with the same Rust/WASM core.
 npm install tapirscan
 ```
 
-Registry publication is pending; until then, install a tarball from the
-[local build guide](../../docs/DEVELOPMENT.md). TypeScript declarations and WASM
-binaries are included. Your runtime must support WebAssembly SIMD.
+TypeScript declarations and WASM binaries are included in the
+[npm package](https://www.npmjs.com/package/tapirscan). Your runtime must support
+WebAssembly SIMD.
 
 Pass a canvas's `ImageData` directly:
 
@@ -46,9 +51,14 @@ try {
 ```
 
 Here `image` is the `ImageData` above. `formats: "1D"` enables all supported linear
-formats; additional readers are experimental. Settings also work with the helper:
+formats; readers outside the retail group remain experimental. Settings also work with the helper:
 `await scan(image, { mode: "high", formats: "1D" })`.
 
+`formats: "retail"` selects EAN13, UPCA,
+EAN8 and UPCE. `"common1D"` adds Code128, Code39 and ITF; `"common"` adds
+QRCode and DataMatrix to `"common1D"`. See
+[format presets and runtime behavior](../../docs/FORMATS.md).
+
 ## WASM loading
 
 In Node, the default loader reads assets from the installed package. Decode your
@@ -69,17 +79,10 @@ mkdir -p public/tapirscan
 cp node_modules/tapirscan/wasm/*.wasm public/tapirscan/
 ```
 
-Then supply a loader pointing at those files:
+Then point the scanner at that directory:
 
 ```js
-const scanner = await Scanner.create({
-  loadWasm: async (url) => {
-    const filename = url.pathname.split("/").pop();
-    const response = await fetch(`/tapirscan/${filename}`);
-    if (!response.ok) throw new Error(`Could not load scanner: ${response.status}`);
-    return response.arrayBuffer();
-  },
-});
+const scanner = await Scanner.create({ wasmBaseUrl: "/tapirscan/" });
 try {
   console.log(scanner.scan(image).values);
 } finally {
@@ -87,12 +90,30 @@ try {
 }
 ```
 
+The one-shot helper accepts the same option:
+`await scan(image, { wasmBaseUrl: "/tapirscan/" })`.
+`wasmBaseUrl` accepts a string or URL, with or without a trailing slash. Relative
+URLs resolve against the page/worker URL in browsers and the package module in
+Node; use an absolute URL for an unambiguous location. For authenticated requests
+or custom storage, use `loadWasm: async (url) => arrayBuffer`. The callback receives
+URLs resolved against `wasmBaseUrl` when both options are supplied. Only engines needed by the selected formats are loaded.
+
 Use the deployed base path if your app is hosted below a subpath. Copy all current
-WASMs: Medium/High/Very high also load the Low recovery decoder. The demo and its
+WASMs: EAN13/UPCA scanning in Medium/High/Very high also loads the Low recovery decoder. The demo and its
 comparison engines are not needed in your app.
 
 ## Camera and worker use
 
+A standalone [worker client](examples/worker-client.mjs), [worker](examples/scan-worker.mjs)
+and [camera page](examples/camera.html) are included in the package. From this
+binding directory (or the installed package directory), run `python3 -m http.server`
+and open `/examples/camera.html` on localhost. The example handles initialization,
+frame ownership transfer, one frame in flight, errors and shutdown. It transfers
+pixel buffers; callers must not reuse the transferred buffer. Worker messages
+produce independent mutable result copies through structured cloning. Custom
+`loadWasm` functions must be configured inside the worker; functions cannot be sent
+in a message. Adjust the worker import and WASM asset path for your bundler.
+
 Initialization is asynchronous; scanning is synchronous. For a responsive browser
 UI, initialize one scanner inside a Web Worker and transfer an owned frame buffer.
 Capture the next frame after the previous result arrives. Avoid racing scanner
@@ -100,77 +121,37 @@ initialization or modifying pixels during scanning. The [demo worker](../../demo
 shows a complete integration. Camera capture belongs to your app and requires
 HTTPS (localhost works for development).
 
-## Moving from ZXing
-
-For [`zxing-wasm`](https://github.com/Sec-ant/zxing-wasm), you can keep your
-existing ImageData and replace the decoding call:
-
-```js
-// Before:
-import { readBarcodes } from "zxing-wasm/reader";
-const reads = await readBarcodes(image, { formats: ["EAN13"] });
-const oldValues = reads.filter((read) => read.isValid).map((read) => read.text);
-
-// After:
-import { scan } from "tapirscan";
-const result = await scan(image, { formats: ["EAN13"] });
-const values = result.values;
-```
-
-Here `image` is decoded ImageData. Keep an explicit format selection during
-migration; Tapirscan defaults to EAN13. For successive frames, initialize a
-`Scanner` once and scan inside a worker, as shown above.
-
-| Existing ZXing integration               | Tapirscan equivalent or difference                                                          |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------- |
-| Array of reads                           | `result.barcodes`, or `result.values` for strings.                                          |
-| `read.text`                              | `barcode.text`.                                                                             |
-| `read.position`                          | `barcode.polygon` as four [x, y] corners, or `barcode.rect`.                                |
-| `tryHarder`, `tryRotate`, `tryDownscale` | No direct option mapping. Select an effort mode and measure your images.                    |
-| `maxNumberOfSymbols`                     | No arbitrary count limit; `multiple: false` selects one after the scan, without early exit. |
-| Blob or encoded image input              | Decode to ImageData or a supported byte buffer before scanning.                             |
-| WASM overrides/asset paths               | Use Tapirscan's `loadWasm` and packaged assets.                                             |
-
-[`@zxing/browser`](https://github.com/zxing-js/browser) also manages browser image
-and video acquisition. Tapirscan's scanner accepts pixels; it does not replace
-camera-device helpers or continuous-scan callbacks. Keep your capture loop,
-draw frames to a canvas, and pass ImageData to a reusable scanner. Stop media
-tracks when capture ends, and dispose the scanner when finished. See the
-[demo](../../demo/README.md) for capture behavior.
-
-Check supported formats and reader-specific metadata before switching. Additional
-formats are experimental, and Tapirscan is not a drop-in replacement for every
-ZXing package. Run both readers on representative inputs before replacing one.
-
 ## Functions
 
-| Function                            | Return type            | Behavior                                                                                                                  |
-| ----------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `scan(image, options = {})`         | `Promise<ScanResult>`  | One image with automatic scanner creation and disposal, including on failure. Accepts creation and scan options together. |
-| `Scanner.create(options = {})`      | `Promise<Scanner>`     | Initialize a reusable scanner. Mode and formats are fixed for its lifetime.                                               |
-| `scanner.scan(image, options = {})` | `ScanResult`           | Synchronously scan pixels. Accepts scan options only.                                                                     |
-| `scanner.best(result)`              | `Barcode \| undefined` | Convenience alias for `result.best`.                                                                                      |
-| `scanner.dispose()`                 | `void`                 | Release WASM sessions. Repeated disposal is safe; do not scan after disposal.                                             |
+| Function                            | Return type           | Behavior                                                                                                                  |
+| ----------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `scan(image, options = {})`         | `Promise<ScanResult>` | One image with automatic scanner creation and disposal, including on failure. Accepts creation and scan options together. |
+| `Scanner.create(options = {})`      | `Promise<Scanner>`    | Initialize a reusable scanner. Mode is fixed; formats define defaults and allowed per-call subsets.                       |
+| `scanner.scan(image, options = {})` | `ScanResult`          | Synchronously scan pixels. Accepts scan options only.                                                                     |
+| `scanner.dispose()`                 | `void`                | Release WASM sessions. Repeated disposal is safe; do not scan after disposal.                                             |
 
 `image` is required for either scan function. All options are optional. Reuse a
 scanner for successive frames to avoid repeated initialization; create another
-to change effort or formats. Previously returned results survive disposal.
+to change effort or enable formats outside its configured selection. A per-call
+subset such as `scanner.scan(image, { formats: "EAN13" })` applies only to that
+call and does not change the default formats. Previously returned results survive disposal. `scanner.formats` exposes the frozen creation selection.
 
 ## All options
 
-| Option           | Where    | Default                | Meaning                                                                                                    |
-| ---------------- | -------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `mode`           | Creation | `"medium"`             | `"low"`, `"medium"`, `"high"`, `"very-high"`.                                                              |
-| `formats`        | Creation | `["EAN13"]`            | `"1D"`, `"2D"`, `"all"`, or a nonempty array of exact identifiers.                                         |
-| `loadWasm`       | Creation | Module-relative loader | `(url: URL) => Promise<ArrayBuffer>`. Uses HTTP fetch in browsers and filesystem reads for Node file URLs. |
-| `multiple`       | Scan     | `true`                 | False keeps at most the highest-support read after scanning; it does not provide an early exit.            |
-| `debug`          | Scan     | `false`                | Include search evidence under `result.debug`. Decoded polygons are always returned.                        |
-| `includeRegions` | Scan     | Unset                  | Compatibility alias for `debug`; prefer `debug` in new code. Conflicting values are rejected.              |
-
-Format presets cover supported symbologies. Exports `linearFormats`, `matrixFormats`
+| Option           | Where               | Default                | Meaning                                                                                                                                                           |
+| ---------------- | ------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`           | Creation            | `"medium"`             | `"low"`, `"medium"`, `"high"`, `"very-high"`.                                                                                                                     |
+| `formats`        | Creation / scan     | `["EAN13"]`            | A single identifier, `"retail"`, `"common1D"`, `"common"`, `"1D"`, `"2D"`, `"all"`, or a nonempty array. Per-call selections must be subsets of creation formats. |
+| `wasmBaseUrl`    | Creation            | Module-relative assets | Directory URL for packaged WASMs. Use this for normal browser hosting.                                                                                            |
+| `loadWasm`       | Creation            | Module-relative loader | `(url: URL) => Promise<ArrayBuffer>`. Uses HTTP fetch in browsers and filesystem reads for Node file URLs.                                                        |
+| `eanAddOnPolicy` | Creation / one-shot | `"Ignore"`             | `"Ignore"`, `"Read"`, `"Require"`; optional EAN/UPC supplement policy.                                                                                            |
+| `extendedBudget` | Scan / one-shot     | `false`                | Allow extra reader work for any format. Exact budgets may evolve.                                                                                                 |
+| `debug`          | Scan                | `false`                | Include search evidence under `result.debug`. Decoded polygons are always returned.                                                                               |
+
+Format presets cover supported symbologies. Exports `commonFormats`, `commonLinearFormats`, `linearFormats`, `matrixFormats`
 and `retailFormats` let you compose custom selections; `formatBits` provides their
 native bit mapping. See [identifiers and coverage](../../docs/FORMATS.md).
-The four effort modes tune EAN13/UPCA; additional readers use fixed effort.
+The four effort modes tune EAN13/UPCA, Common1D and QR Code; other matrix readers use fixed effort.
 
 Resolution, camera capture, preprocessing rotation, ROI, confidence thresholds,
 timeouts and exact work budgets are not public scan options. Demo capture and
@@ -181,57 +162,135 @@ resize settings belong to the application.
 `PixelImage` accepts `ImageData` (or its data/width/height fields) or an explicit
 `Image` buffer:
 
-| Field             | Type          | Meaning                                                                                                 |
-| ----------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
-| `data`            | `Uint8Array`  | Decoded pixels. ImageData instead uses `Uint8ClampedArray` and implies tightly packed RGBA.             |
-| `width`, `height` | `number`      | Integer input dimensions, at least 3 pixels each.                                                       |
-| `channels`        | `1 \| 3 \| 4` | Grayscale, RGB or RGBA. Alpha is ignored. Required for explicit buffers.                                |
-| `stride`          | `number`      | Bytes between row starts, at least width × channels. Required for explicit buffers; padding is allowed. |
+| Field             | Type          | Meaning                                                                                                          |
+| ----------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `data`            | `Uint8Array`  | Decoded pixels. ImageData instead uses `Uint8ClampedArray` and implies tightly packed RGBA.                      |
+| `width`, `height` | `number`      | Integer input dimensions, at least 3 pixels each.                                                                |
+| `channels`        | `1 \| 3 \| 4` | Grayscale, RGB or RGBA. Alpha is ignored. Required for explicit buffers.                                         |
+| `stride`          | `number`      | Bytes between row starts, at least width × channels. Optional; defaults to width × channels. Padding is allowed. |
 
-Input is limited to 128 MiB of addressed pixels. Keep the buffer stable during the
+Input is limited to 32 megapixels and 128 MiB of addressed pixels. Keep the buffer stable during the
 call. Convert DOM image elements or encoded images to pixels before scanning.
 
 ## Results
 
-| Field               | Type                                                           | Meaning                                                                           |
-| ------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `result.values`     | `string[]`                                                     | Decoded strings.                                                                  |
-| `result.barcodes`   | `Barcode[]`                                                    | Decoded values with format and geometry.                                          |
-| `result.best`       | `Barcode \| undefined`                                         | Highest-support read, or undefined when empty.                                    |
-| `result.image`      | `{ width: number, height: number }`                            | Dimensions of supplied pixels.                                                    |
-| `result.mode`       | `Mode`                                                         | Selected effort.                                                                  |
-| `result.elapsedMs`  | `number`                                                       | Host scan time in milliseconds; excludes file loading and scanner initialization. |
-| `result.unfinished` | `boolean`                                                      | Incomplete work; returned reads may still be useful.                              |
-| `result.debug`      | `Diagnostics \| undefined`                                     | Requested diagnostic evidence; absent by default.                                 |
-| `barcode.text`      | `string`                                                       | Decoded text.                                                                     |
-| `barcode.format`    | `Format \| "Unknown"`                                          | Symbology identifier.                                                             |
-| `barcode.polygon`   | `Quad`                                                         | Four `[x, y]` corners in input-image coordinates.                                 |
-| `barcode.rect`      | `{ left: number, top: number, width: number, height: number }` | Enclosing integer rectangle.                                                      |
-
-Both result arrays are empty when nothing is decoded. Coordinates start at the
+| Field                          | Type                                                           | Meaning                                                                                                    |
+| ------------------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `result.values`                | `readonly string[]`                                            | Decoded strings.                                                                                           |
+| `result.barcodes`              | `readonly Barcode[]`                                           | Decoded values with format and geometry.                                                                   |
+| `result.best`                  | `Barcode \| undefined`                                         | Highest-support read, or undefined when empty.                                                             |
+| `result.image`                 | `{ width: number, height: number }`                            | Dimensions of supplied pixels.                                                                             |
+| `result.mode`                  | `Mode`                                                         | Selected effort.                                                                                           |
+| `result.elapsedMs`             | `number`                                                       | Host scan time in milliseconds; excludes file loading and scanner initialization.                          |
+| `result.unfinished`            | `boolean`                                                      | Incomplete work; returned reads may still be useful.                                                       |
+| `result.undecoded`             | `readonly UndecodedRegion[]`                                   | Localized proposals without accepted decodes; always available.                                            |
+| `result.debug`                 | `Diagnostics \| undefined`                                     | Requested diagnostic evidence; absent by default.                                                          |
+| `barcode.payloadBytes`         | `readonly number[] \| undefined`                               | Original decoded matrix payload bytes when available; use `Uint8Array.from(...)` for an owned byte buffer. |
+| `barcode.text`                 | `string`                                                       | Decoded text.                                                                                              |
+| `barcode.format`               | `Format \| "Unknown"`                                          | Symbology identifier.                                                                                      |
+| `barcode.polygon`              | `Quad`                                                         | Four `[x, y]` corners in input-image coordinates.                                                          |
+| `barcode.rect`                 | `{ left: number, top: number, width: number, height: number }` | Enclosing integer rectangle.                                                                               |
+| `barcode.support`              | `number`                                                       | Reader-specific ranking evidence; not confidence or a probability.                                         |
+| `barcode.gs1`                  | `boolean \| undefined`                                         | GS1 indicator when supplied by the reader.                                                                 |
+| `barcode.readerInitialization` | `boolean \| undefined`                                         | Reader initialization data indicator; never executed.                                                      |
+| `barcode.structuredAppend`     | `StructuredAppend \| undefined`                                | Immutable multipart metadata: one-based `index`, `count`, optional `id` and `parity`.                      |
+| `barcode.eanAddOn`             | `string \| undefined`                                          | Optional EAN supplement; populated when `eanAddOnPolicy` is `"Read"` or `"Require"`.                       |
+
+Results, including nested geometry and requested diagnostics, are immutable at
+runtime and in TypeScript. Use `structuredClone(result)` if you need a mutable
+copy. `barcodes` and `values` are empty when nothing is decoded; `undecoded` may still
+contain proposals. Use `result.best` for
+one read, or `undefined` when empty. All decoded instances remain available,
+including separate copies of the same value. Coordinates start at the
 top left, x rightward and y downward. Geometry is returned, not a cropped bitmap.
 Map coordinates back yourself if you resize/rotate before scanning. Support is a
 ranking heuristic, not a probability.
 
-The package exports `ScannerOptions`, `ScanOptions`, `ScanResult`, `Barcode`,
-`PixelImage`, `Image`, `Quad`, `Mode`, `Format`, `FormatSelection`, `Diagnostics`
-and `DiagnosticBarcode` types. TypeScript infers results from calls; runtime
+The package exports `EanAddOnPolicy`, `ScannerOptions`, `ScanOptions`, `ScanResult`, `Barcode`,
+`PixelImage`, `Image`, `Quad`, `Mode`, `Format`, `FormatSelection`, `Diagnostics`,
+`StructuredAppend` and `DiagnosticBarcode` types. TypeScript infers results from calls; runtime
 checks still validate pixel buffers and dimensions.
 
+## EAN/UPC supplements
+
+Set `eanAddOnPolicy: "Read"` when creating a scanner or calling one-shot `scan()`.
+The policy is fixed for that scanner; its default is `"Ignore"`.
+
+| Policy      | Behavior                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------ |
+| `"Ignore"`  | Decode the main barcode without reading its supplement.                                          |
+| `"Read"`    | Try reading the two- or five-digit supplement; keep the main barcode if none is readable.        |
+| `"Require"` | Return an EAN/UPC barcode only when its supplement is readable. Other formats remain unaffected. |
+
+`barcode.polygon` and `barcode.rect` describe the main barcode, excluding the
+supplement. Supplement geometry is not exposed separately.
+
+The supplement appears separately in `barcode.eanAddOn`; `barcode.text` remains
+the main payload. Reading supplements enables additional decoding
+work independently of the effort mode. Retail reads rejected
+by `"Require"` remain available in `result.undecoded`.
+
+## Evidence and work limits
+
+Most applications need `barcode.text`, `.format`, `.polygon` and `.rect`.
+`barcode.support` exposes the evidence used by `.best`. It is an uncalibrated,
+reader-specific ranking heuristic, not a certainty percentage; values are not
+comparable confidence across formats or effort modes. Consequently, `.best` means the largest support value,
+not the most reliable barcode in a mixed-format image. Select by the format or
+payload your application needs when that distinction matters. Checksums and consistency
+checks reduce wrong reads but cannot guarantee that every returned decode is correct.
+
+Select EAN13/UPCA, Common1D and QR Code search effort with `mode: "low"` through `"very-high"` at creation.
+Other matrix readers use fixed effort. `result.unfinished` is available without debug and
+combines reported decoding and localization limits. Returned reads are still usable.
+Candidate, retry and parsing caps are reported, including bounded searches that
+also returned reads. False does not promise exhaustive scanning. Exact budgets and interruptible timeouts are not public options.
+
+`debug: true` adds attempted search windows, localization proposals, candidate
+outcomes and engine traces. It is unnecessary for drawing decoded barcode locations.
+
+### Switching between retail and QR scanning
+
+```js
+const scanner = await Scanner.create({ formats: "common" });
+try {
+  console.log(scanner.formats);
+  const retail = scanner.scan(image, { formats: "retail" });
+  const qr = scanner.scan(image, { formats: "QRCode" });
+} finally {
+  scanner.dispose();
+}
+```
+
+`payloadBytes` is supplied by QR Code, Data Matrix, Aztec, PDF417 and MaxiCode.
+It contains decoded data bytes before character-set interpretation, not raw symbol
+codewords. Aztec Rune represents its numeric value as decimal ASCII. Other readers
+leave it absent. Encoding `.text` as UTF-8 does not reconstruct original bytes.
+Unsupported character encodings can still prevent decoding; reader behavior is
+unchanged. The frozen number array is directly JSON-compatible.
+
 ## Diagnostics and errors
 
 ```js
 const result = scanner.scan(image, { debug: true });
 if (result.debug) {
-  console.log(result.debug.localization, result.debug.searchWindows);
+  console.log(result.debug.regions.proposals, result.debug.regions.searchWindows);
+  console.log(result.debug.regions.undecoded);
   console.log(result.debug.scan.barcodes);
 }
 ```
 
-Diagnostics retain the raw schema-2 result: `scan` includes support and candidate
+`debug.regions` has a stable shape across creation formats: `proposals` and
+`searchWindows` contain evidence or null when unavailable, and `undecoded` contains
+unread source-image geometry as immutable `UndecodedRegion` objects (`format` hint
+and `polygon`, with no decoded text). Empty arrays mean available evidence with no entries.
+EAN evidence remains available when a scanner also enables additional readers.
+
+Diagnostics also retain the raw schema-2 result: `scan` includes support and candidate
 evidence, and `localizationLimited` reports localization limits. Depending on the
 reader, `localization`, `searchWindows`, `recovery` and `detailRegions` may be
-present. Raw metadata includes GS1 and structured append where supported.
+present. GS1, reader initialization and structured append are available directly on
+barcodes without debug; raw metadata also retains these fields where supported.
 Candidate indices inside recovery crops are local to the crop and are not
 identifiers for tracking between frames.
 
@@ -239,3 +298,23 @@ Invalid options can raise TypeError. Scanner validation and engine failures can
 raise the exported `ScannerError` with a `.code` and `.message`. Loader/fetch
 errors propagate to the caller; creation and the one-shot helper reject their
 promises on failure. Always dispose reusable scanners with `finally`.
+
+## Extended work budget
+
+Use `scanner.scan(image, { extendedBudget: true })` to allow additional reader work. The default
+is false. This option is valid for every format; the exact budgets and stages are
+implementation details that may evolve. Effort mode remains a separate setting.
+
+Today this relaxes shared EAN-13/UPC-A retry and association limits. Other readers
+currently retain their existing budgets. Per-candidate limits and intentional
+deferrals remain; `unfinished` can still be true. This is not unlimited search,
+an exhaustiveness guarantee or a wall-clock deadline. Custom primary-reader
+engines must support the extended-work capability or report an error.
+
+## Undecoded regions
+
+`result.undecoded` is always available, independently of `debug`. Each entry has
+a source-image polygon and a format hint. It is a localized proposal without an
+accepted decode, not proof of a real or permanently unreadable barcode. Entries
+can overlap or describe false candidates. An empty collection does not prove
+that every barcode was found. Raw candidate attempts remain in debug diagnostics.

package/dist/completion-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): {
+        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/completion-host.mjs

@@ -0,0 +1,188 @@
+/** 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) {
+        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');
+        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]; }));
+        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));
+        }
+    }
+}