@marianmeres/scanner 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Meres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# @marianmeres/scanner
+
+[![NPM](https://img.shields.io/npm/v/@marianmeres/scanner)](https://www.npmjs.com/package/@marianmeres/scanner)
+[![JSR](https://jsr.io/badges/@marianmeres/scanner)](https://jsr.io/@marianmeres/scanner)
+[![License](https://img.shields.io/npm/l/@marianmeres/scanner)](LICENSE)
+
+Low-level, framework-agnostic browser primitive for scanning QR codes (and other
+barcodes) from a live camera stream. Headless controller with reactive state, plus an
+optional mountable "stage" UI (viewfinder overlay, corner guides, control buttons) at
+the `/stage` subpath.
+
+Decoding is done by the [`barcode-detector`](https://github.com/Sec-ant/barcode-detector)
+ponyfill (zxing-cpp compiled to wasm) — used unconditionally, the native
+`BarcodeDetector` is deliberately ignored (platform-inconsistent, historically buggy).
+
+## Installation
+
+```bash
+# Deno / JSR
+deno add jsr:@marianmeres/scanner
+
+# npm
+npm install @marianmeres/scanner
+```
+
+## Usage
+
+### Quick start
+
+```typescript
+import { createScanner } from "@marianmeres/scanner";
+import { createScannerStage } from "@marianmeres/scanner/stage";
+
+const scanner = createScanner({
+	onScan: (result) => console.log(result.value),
+});
+
+// optional built-in UI — mounts the camera preview + viewfinder into your element
+const stage = createScannerStage(scanner, {
+	container: document.getElementById("scan")!,
+	controls: { cancel: true, torch: true, cameraSwitch: true },
+});
+
+// scanning must be started explicitly (ideally from a user gesture — never
+// auto-started on mount; iOS Safari permission-prompt rules)
+const result = await scanner.start(); // single-shot: resolves with the first hit
+console.log(result?.value); // null when cancelled or failed (check state.error)
+
+stage.destroy(); // does NOT destroy the scanner
+scanner.destroy();
+```
+
+### Single vs continuous mode
+
+```typescript
+// "single" (default): auto-stop after the first detection — onScan fires,
+// the start() promise resolves with the result, camera is released.
+const scanner = createScanner({ mode: "single" });
+const result = await scanner.start();
+
+// "continuous": keep scanning until stop()/destroy() — every detection fires
+// onScan (identical values suppressed for dedupeMs, default 1500 ms);
+// start() resolves null when stopped.
+const scanner2 = createScanner({
+	mode: "continuous",
+	onScan: (r) => console.log(r.format, r.value),
+});
+// do NOT `await` inline here — in continuous mode the promise resolves only
+// once the scanner is stopped
+const done = scanner2.start();
+// ... later, e.g. from a "done" button handler:
+scanner2.stop();
+await done; // resolves null
+```
+
+### Scan a still image (no camera)
+
+```typescript
+import { scanImage } from "@marianmeres/scanner";
+
+// File | Blob | ImageData | ImageBitmap | <img> | <canvas> | <video> | url
+const results = await scanImage(file);
+if (results.length) console.log(results[0].value);
+```
+
+Useful for file uploads, drag & drop, or as a fallback where `getUserMedia` is
+unavailable. Unlike the scanner instance methods, `scanImage` THROWS on fetch/decode
+failure; an image without any recognizable code resolves with `[]`.
+
+### Torch (flashlight) and camera switching
+
+```typescript
+const ok = await scanner.setTorch(true); // resolves false where unsupported
+
+const cameras = await scanner.listCameras(); // [{ deviceId, label, facing }]
+await scanner.setCamera(cameras[1].deviceId); // live-switch while scanning
+```
+
+### Reactive state
+
+```typescript
+// Svelte $store compatible — the callback fires immediately with current state
+const unsub = scanner.subscribe((state) => {
+	state.status; // "idle" | "initializing" | "scanning" | "stopped"
+	state.error; // { code, message } | null — methods never throw
+	state.permission; // "unknown" | "prompt" | "granted" | "denied"
+	state.torch; // { supported: boolean, on: boolean }
+	state.cameras; // CameraInfo[] (labels need granted permission)
+	state.activeCameraId; // string | null
+	state.lastResult; // ScanResult | null
+});
+```
+
+### Configuration
+
+```typescript
+const scanner = createScanner({
+	video: myVideoEl, // created lazily when omitted
+	formats: ["qr_code", "ean_13"], // default ["qr_code"]
+	mode: "single", // "single" (default) | "continuous"
+	onScan: (result) => {},
+	onError: (error) => {},
+	preferredCamera: "environment", // "environment" (default) | "user" | deviceId
+	scanIntervalMs: 100, // decode throttle, default 100 (~10 fps)
+	dedupeMs: 1500, // continuous-mode per-value cooldown
+	adapter: myCameraAdapter, // camera seam (see below)
+	detector: myDetector, // decode-engine seam (tests / engine swap)
+	wasmOverrides: { locateFile: (path, prefix) => `/assets/${path}` },
+	logger: console, // @marianmeres/clog compatible
+});
+```
+
+## Semantics
+
+- **Explicit `start()`, never auto-start.** Call it from a user gesture where possible
+  — mobile browsers (esp. iOS Safari) tie the permission prompt and playback to
+  gestures.
+- **HTTPS required.** `getUserMedia` only exists in secure contexts — serve over HTTPS
+  (or `localhost` during development). On insecure origins browsers typically don't
+  expose `navigator.mediaDevices` at all, so the scanner reports `NOT_SUPPORTED`;
+  `INSECURE_CONTEXT` appears when `getUserMedia` itself throws `SecurityError`
+  (e.g. a blocking Permissions-Policy).
+- **Methods never throw.** `start()` never rejects; errors land in `state.error`
+  (`{ code, message }`) and fire `onError`. `setTorch()` resolves `false` instead of
+  rejecting. The standalone `scanImage()` is the documented exception — it throws.
+- **Permission denial is state, not UI.** A denied prompt sets
+  `state.permission = "denied"` plus a `PERMISSION_DENIED` error; the package ships no
+  messaging UI for it. For a full "re-enable camera access" walkthrough compose
+  [`@marianmeres/mediaperms/reenable-guide`](https://jsr.io/@marianmeres/mediaperms)
+  next to the scanner.
+- **Single-shot picks the first detection** when several codes share a frame;
+  `onScan` fires, `start()` resolves, the loop and all tracks stop
+  (`status: "stopped"`).
+- **Continuous mode dedupes** identical `format|value` pairs within `dedupeMs`
+  (default 1500 ms) and runs until `stop()`/`destroy()`.
+- **Concurrent `start()` calls coalesce** — re-entrant calls return the same in-flight
+  promise.
+- **The detection loop is throttled and visibility-aware.** Frames are scheduled via
+  `requestVideoFrameCallback` (rAF fallback), decoded at most every `scanIntervalMs`
+  (default 100 ms ≈ 10 fps), and detection pauses while
+  `document.visibilityState === "hidden"`.
+- **Formats default to `["qr_code"]`.** Fewer enabled formats means faster per-frame
+  decode and fewer false positives — enable more (`"ean_13"`, `"code_128"`,
+  `"data_matrix"`, … or the `"any"` shortcut) only when needed.
+- **Repeated detector failures stop the scan.** After 5 consecutive `detect()` throws
+  the scanner sets `DETECTOR_FAILED` and stops.
+- **A dying camera track stops the scan.** When the OS/browser ends the video track
+  outside the scanner's control (permission revoked mid-scan, USB camera unplugged,
+  a native app preempting the camera), the scanner sets `REQUEST_FAILED` and stops
+  instead of hanging in `"scanning"`.
+
+### Error codes
+
+Machine-readable codes on `state.error.code` (see
+[`ScannerErrorCode`](API.md#scannererrorcode)):
+
+| Code                | Cause                                                                                |
+| ------------------- | ------------------------------------------------------------------------------------ |
+| `NO_DEVICE`         | `getUserMedia` threw `NotFoundError` — no camera available                           |
+| `INSECURE_CONTEXT`  | `SecurityError` — origin not HTTPS, or Permissions-Policy blocks it                  |
+| `DEVICE_BUSY`       | `NotReadableError` — hardware held by another consumer                               |
+| `PERMISSION_DENIED` | camera access denied by the user or platform policy                                  |
+| `REQUEST_FAILED`    | acquisition failed with a non-classified error, or the live track ended unexpectedly |
+| `NOT_SUPPORTED`     | required platform API missing (no `mediaDevices`, no DOM, …)                         |
+| `DETECTOR_FAILED`   | the barcode detector threw repeatedly (or failed to construct)                       |
+
+## Wasm: CDN default, self-hosting, CSP
+
+The zxing-cpp decoder is a ~1 MB `.wasm` binary fetched **lazily** (on the first
+decode) from the **jsDelivr CDN** by default — zero configuration needed.
+
+If your CSP does not allow `cdn.jsdelivr.net` (or you need offline support), self-host
+the binary and point the engine at it via `wasmOverrides.locateFile` (passed through to
+zxing-wasm's `prepareZXingModule`):
+
+```typescript
+const scanner = createScanner({
+	wasmOverrides: {
+		locateFile: (path: string, prefix: string) => `/assets/${path}`,
+	},
+});
+```
+
+Copy the `zxing_reader.wasm` file from the `zxing-wasm` npm package (a dependency of
+`barcode-detector`) into your static assets. Note that executing wasm also requires
+`'wasm-unsafe-eval'` in `script-src` under a strict CSP.
+
+## The `CameraAdapter` seam
+
+All camera acquisition goes through an injectable `CameraAdapter` interface
+(`getStream`, `enumerateVideoDevices`, `queryPermission`, `onPermissionChange`,
+optional `destroy`). The default implementation wraps `navigator.mediaDevices` for
+stream acquisition/enumeration and delegates the permission lifecycle to
+[`@marianmeres/mediaperms`](https://jsr.io/@marianmeres/mediaperms) — which brings
+platform detection, Android-WebView sticky-denial coercion, and bfcache/app-resume
+permission rechecks for free.
+
+```typescript
+const scanner = createScanner({ adapter: myAdapter }); // fully custom seam
+
+// or share your app's existing mediaperms instance with the default adapter:
+import { createCamPerms } from "@marianmeres/mediaperms";
+import { createDefaultCameraAdapter, createScanner } from "@marianmeres/scanner";
+
+const perms = createCamPerms(); // app-owned (adapter will not destroy it)
+const scanner = createScanner({ adapter: createDefaultCameraAdapter({ perms }) });
+```
+
+The adapter seam is also how tests run without real browser APIs.
+
+Unlike `@marianmeres/mediaperms` (which probes permission and stops tracks immediately),
+the scanner RETAINS the acquired `MediaStream` for the live preview — all tracks are
+stopped on `stop()`/`destroy()`.
+
+## Stage UI: `@marianmeres/scanner/stage`
+
+`createScannerStage(scanner, options)` mounts a self-contained, dependency-free DOM
+stage into a container: cover-fit `<video>` preview, dimmed overlay with a rounded
+viewfinder cutout and corner guides, an optional scan-line animation
+(`prefers-reduced-motion` honored), a brief green flash on detection, and opt-in
+control buttons.
+
+```typescript
+import { createScannerStage } from "@marianmeres/scanner/stage";
+
+const stage = createScannerStage(scanner, {
+	container: document.getElementById("scan")!,
+	controls: { cancel: true, torch: true, cameraSwitch: true }, // default { cancel: true }
+	scanLine: true, // default true
+	theme: "auto", // "auto" (default, follows prefers-color-scheme) | "light" | "dark"
+	accent: "#e11d48", // any CSS color, sets --mms-accent
+	onCancel: () => console.log("user cancelled"),
+});
+
+// later
+stage.destroy(); // unmounts the stage; the scanner keeps working independently
+```
+
+Buttons for unsupported features hide automatically (torch without capability, camera
+switch with a single camera). Theming via scoped CSS custom properties (`--mms-accent`,
+`--mms-dim`, `--mms-frame-size`, `--mms-radius`, …) — see
+[API.md](API.md#stage-theming-css-custom-properties). The stage is just one consumer of
+the headless controller: destroying the stage does not stop or destroy the scanner (and
+vice versa).
+
+## API
+
+See [API.md](API.md) for complete API documentation.
+
+## License
+
+[MIT](LICENSE)

package/dist/camera-adapter.d.ts

@@ -0,0 +1,31 @@
+import { type MediaPerms, type MediaPermsConfig } from "@marianmeres/mediaperms";
+import type { CameraAdapter, CameraFacing } from "./types.js";
+/** Best-effort facing detection from a device label. */
+export declare function detectFacing(label: string): CameraFacing | null;
+/** Options for {@linkcode createDefaultCameraAdapter}. */
+export interface CreateDefaultCameraAdapterOptions {
+    /**
+     * Share an existing `@marianmeres/mediaperms` instance (camera kind).
+     * When omitted, the adapter lazily creates its own via `createCamPerms()`
+     * and destroys it in {@linkcode CameraAdapter.destroy}. Pass a shared
+     * instance when the app already manages one (it will NOT be destroyed by
+     * the adapter).
+     */
+    perms?: MediaPerms;
+    /**
+     * Config forwarded to `createCamPerms()` when the adapter creates its own
+     * instance (platform hints, webview bridges, logger...). Ignored when
+     * {@linkcode CreateDefaultCameraAdapterOptions.perms} is provided.
+     */
+    permsConfig?: MediaPermsConfig;
+}
+/**
+ * Default {@linkcode CameraAdapter}.
+ *
+ * Stream acquisition and device enumeration wrap `navigator.mediaDevices`
+ * directly (the scanner needs to RETAIN the stream — deliberately out of
+ * mediaperms' scope). The permission lifecycle (query + change tracking,
+ * incl. Android-WebView sticky-denial coercion and bfcache/app-resume
+ * rechecks) is delegated to `@marianmeres/mediaperms`.
+ */
+export declare function createDefaultCameraAdapter(options?: CreateDefaultCameraAdapterOptions): CameraAdapter;

package/dist/camera-adapter.js

@@ -0,0 +1,96 @@
+// deno-lint-ignore-file no-explicit-any
+import { createCamPerms, } from "@marianmeres/mediaperms";
+const _g = globalThis;
+/** Best-effort facing detection from a device label. */
+export function detectFacing(label) {
+    if (/back|rear|environment/i.test(label))
+        return "environment";
+    // NOTE: no bare "face" — it would match "facing" (e.g. "camera 2, facing external")
+    if (/front|user|facetime|selfie/i.test(label))
+        return "user";
+    return null;
+}
+function mediaDevices() {
+    return _g?.navigator?.mediaDevices ?? null;
+}
+/**
+ * Default {@linkcode CameraAdapter}.
+ *
+ * Stream acquisition and device enumeration wrap `navigator.mediaDevices`
+ * directly (the scanner needs to RETAIN the stream — deliberately out of
+ * mediaperms' scope). The permission lifecycle (query + change tracking,
+ * incl. Android-WebView sticky-denial coercion and bfcache/app-resume
+ * rechecks) is delegated to `@marianmeres/mediaperms`.
+ */
+export function createDefaultCameraAdapter(options = {}) {
+    let perms = options.perms ?? null;
+    let ownsPerms = false;
+    let destroyed = false;
+    function getPerms() {
+        if (!perms) {
+            perms = createCamPerms(options.permsConfig);
+            ownsPerms = true;
+        }
+        return perms;
+    }
+    return {
+        getStream(constraints) {
+            const md = mediaDevices();
+            if (!md?.getUserMedia) {
+                const err = new Error("navigator.mediaDevices.getUserMedia unavailable");
+                err.name = "NotSupportedError";
+                return Promise.reject(err);
+            }
+            return md.getUserMedia(constraints);
+        },
+        async enumerateVideoDevices() {
+            const md = mediaDevices();
+            if (!md?.enumerateDevices)
+                return [];
+            const devices = await md.enumerateDevices();
+            return devices
+                .filter((d) => d.kind === "videoinput")
+                .map((d) => ({
+                deviceId: d.deviceId,
+                label: d.label ?? "",
+                facing: detectFacing(d.label ?? ""),
+            }));
+        },
+        async queryPermission() {
+            if (destroyed)
+                return null;
+            try {
+                const status = await getPerms().check();
+                // "unknown" carries no information for the scanner — treat as
+                // "could not determine" so the scanner keeps its own state
+                return status === "unknown" ? null : status;
+            }
+            catch (_e) {
+                return null;
+            }
+        },
+        onPermissionChange(cb) {
+            if (destroyed)
+                return null;
+            // mediaperms subscribe fires immediately — skip that first emission
+            // (queryPermission covers the initial value) and forward changes only
+            let last = null;
+            let first = true;
+            return getPerms().subscribe((s) => {
+                const status = s.status;
+                if (!first && status !== last)
+                    cb(status);
+                first = false;
+                last = status;
+            });
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            if (ownsPerms)
+                perms?.destroy();
+            perms = null;
+        },
+    };
+}

package/dist/detector.d.ts

@@ -0,0 +1,25 @@
+import type { BarcodeFormat, DetectedBarcodeLike, Detector, ScanResult } from "./types.js";
+/** Options for {@linkcode createDefaultDetector}. */
+export interface CreateDefaultDetectorOptions {
+    /** Formats to detect. Default `["qr_code"]`. */
+    formats?: BarcodeFormat[];
+    /**
+     * Overrides passed to zxing-wasm's `prepareZXingModule` — most notably
+     * `locateFile` for self-hosting the `.wasm` binary. See
+     * {@linkcode ScannerConfig.wasmOverrides}.
+     */
+    wasmOverrides?: Record<string, unknown>;
+}
+/** Default formats — QR only (the fastest and the primary use case). */
+export declare const DEFAULT_FORMATS: BarcodeFormat[];
+/**
+ * Default {@linkcode Detector} wrapping the `barcode-detector` ponyfill
+ * (zxing-cpp wasm engine, all major 1D/2D formats).
+ *
+ * NOTE: the ~1 MB decoder `.wasm` is fetched lazily (on first `detect()`)
+ * from the jsDelivr CDN by default — pass `wasmOverrides.locateFile` to
+ * self-host it.
+ */
+export declare function createDefaultDetector(options?: CreateDefaultDetectorOptions): Detector;
+/** Map a raw detection to the public {@linkcode ScanResult} shape. */
+export declare function toScanResult(d: DetectedBarcodeLike, timestamp?: number): ScanResult;

package/dist/detector.js

@@ -0,0 +1,36 @@
+// deno-lint-ignore-file no-explicit-any
+import { BarcodeDetector, prepareZXingModule } from "barcode-detector/ponyfill";
+/** Default formats — QR only (the fastest and the primary use case). */
+export const DEFAULT_FORMATS = ["qr_code"];
+/**
+ * Default {@linkcode Detector} wrapping the `barcode-detector` ponyfill
+ * (zxing-cpp wasm engine, all major 1D/2D formats).
+ *
+ * NOTE: the ~1 MB decoder `.wasm` is fetched lazily (on first `detect()`)
+ * from the jsDelivr CDN by default — pass `wasmOverrides.locateFile` to
+ * self-host it.
+ */
+export function createDefaultDetector(options = {}) {
+    if (options.wasmOverrides) {
+        prepareZXingModule({ overrides: options.wasmOverrides });
+    }
+    const detector = new BarcodeDetector({
+        formats: (options.formats ?? DEFAULT_FORMATS),
+    });
+    return {
+        async detect(source) {
+            const detections = await detector.detect(source);
+            return detections;
+        },
+    };
+}
+/** Map a raw detection to the public {@linkcode ScanResult} shape. */
+export function toScanResult(d, timestamp = Date.now()) {
+    return {
+        value: d.rawValue,
+        format: d.format,
+        cornerPoints: (d.cornerPoints ?? []).map((p) => ({ x: p.x, y: p.y })),
+        boundingBox: d.boundingBox,
+        timestamp,
+    };
+}

package/dist/mod.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./camera-adapter.js";
+export * from "./detector.js";
+export * from "./scanner.js";
+export * from "./scan-image.js";

package/dist/mod.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./camera-adapter.js";
+export * from "./detector.js";
+export * from "./scanner.js";
+export * from "./scan-image.js";

package/dist/scan-image.d.ts

@@ -0,0 +1,24 @@
+import type { BarcodeFormat, Detector, DetectorSource, ScanResult } from "./types.js";
+/** Options for {@linkcode scanImage}. */
+export interface ScanImageOptions {
+    /** Formats to detect. Default `["qr_code"]`. */
+    formats?: BarcodeFormat[];
+    /** Decoding engine seam. Default wraps the `barcode-detector` ponyfill. */
+    detector?: Detector;
+    /** See {@linkcode ScannerConfig.wasmOverrides}. */
+    wasmOverrides?: Record<string, unknown>;
+}
+/**
+ * Decode barcodes from a still image — no camera involved. Useful for file
+ * uploads, drag & drop, or as a fallback where `getUserMedia` is unavailable.
+ *
+ * Unlike the scanner instance methods (which never throw), this standalone
+ * utility THROWS on fetch/decode failure. An image without any recognizable
+ * code resolves with `[]` (not an error).
+ *
+ * ```ts
+ * const results = await scanImage(file); // File | Blob | ImageData | <img> | url
+ * if (results.length) console.log(results[0].value);
+ * ```
+ */
+export declare function scanImage(source: DetectorSource | string, options?: ScanImageOptions): Promise<ScanResult[]>;

package/dist/scan-image.js

@@ -0,0 +1,35 @@
+import { createDefaultDetector, toScanResult } from "./detector.js";
+/**
+ * Decode barcodes from a still image — no camera involved. Useful for file
+ * uploads, drag & drop, or as a fallback where `getUserMedia` is unavailable.
+ *
+ * Unlike the scanner instance methods (which never throw), this standalone
+ * utility THROWS on fetch/decode failure. An image without any recognizable
+ * code resolves with `[]` (not an error).
+ *
+ * ```ts
+ * const results = await scanImage(file); // File | Blob | ImageData | <img> | url
+ * if (results.length) console.log(results[0].value);
+ * ```
+ */
+export async function scanImage(source, options = {}) {
+    const detector = options.detector ??
+        createDefaultDetector({
+            formats: options.formats,
+            wasmOverrides: options.wasmOverrides,
+        });
+    let src;
+    if (typeof source === "string") {
+        const resp = await fetch(source);
+        if (!resp.ok) {
+            throw new Error(`Failed to fetch image (${resp.status}): ${source}`);
+        }
+        src = await resp.blob();
+    }
+    else {
+        src = source;
+    }
+    const detections = await detector.detect(src);
+    const now = Date.now();
+    return detections.map((d) => toScanResult(d, now));
+}

package/dist/scanner.d.ts

@@ -0,0 +1,17 @@
+import type { Scanner, ScannerConfig, ScannerError } from "./types.js";
+/** Classify a getUserMedia (or adapter) rejection into a {@linkcode ScannerError}. */
+export declare function classifyAcquireError(e: unknown): ScannerError;
+/**
+ * Create a headless (no UI) camera barcode scanner.
+ *
+ * Reactive state is exposed via the svelte-store-compatible
+ * `subscribe`/`get`. Methods never throw — errors land in `state.error`
+ * (see {@linkcode ScannerErrorCode}).
+ *
+ * ```ts
+ * const scanner = createScanner({ onScan: (r) => console.log(r.value) });
+ * const result = await scanner.start(); // single-shot: auto-stops on first hit
+ * scanner.destroy();
+ * ```
+ */
+export declare function createScanner(config?: ScannerConfig): Scanner;