@marianmeres/scanner 1.0.1

package/dist/stage.js

@@ -0,0 +1,334 @@
+/**
+ * Framework-agnostic DOM "stage" for the scanner — a mountable camera
+ * preview with the typical scanning UX: dimmed overlay with a viewfinder
+ * cutout, corner guides, optional scan-line animation and opt-in control
+ * buttons (cancel / torch / camera switch).
+ *
+ * The stage is a pure consumer of the headless {@linkcode Scanner} — it
+ * renders its video element and reflects its reactive state. Destroying the
+ * stage does NOT stop or destroy the scanner (and vice versa).
+ *
+ * @module
+ */
+const STYLE_ID = "mms-styles";
+const FLASH_MS = 400;
+const ICONS = {
+    cancel: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18"/></svg>`,
+    torch: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2L4.5 13.5H11L10 22l8.5-11.5H12L13 2z"/></svg>`,
+    switch: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 8v4h4M21 16v-4h-4"/><path d="M3.5 12a8.5 8.5 0 0 1 14.9-4.5M20.5 12a8.5 8.5 0 0 1-14.9 4.5"/></svg>`,
+};
+const CSS = `
+.mms-stage {
+	position: relative;
+	overflow: hidden;
+	width: 100%;
+	height: 100%;
+	min-height: 200px;
+	background: #000;
+	border-radius: var(--mms-radius, 0);
+	--mms-dim: rgba(0, 0, 0, 0.55);
+	--mms-accent: #3b82f6;
+	--mms-success: #22c55e;
+	--mms-corner-color: rgba(255, 255, 255, 0.9);
+	--mms-corner-size: 26px;
+	--mms-corner-width: 4px;
+	--mms-frame-size: min(65%, 65vmin);
+	--mms-btn-bg: rgba(0, 0, 0, 0.5);
+	--mms-btn-fg: #fff;
+}
+.mms-stage[data-theme="light"] {
+	--mms-btn-bg: rgba(255, 255, 255, 0.7);
+	--mms-btn-fg: #111;
+}
+.mms-video {
+	position: absolute;
+	inset: 0;
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+}
+.mms-overlay {
+	position: absolute;
+	inset: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	pointer-events: none;
+}
+.mms-frame {
+	position: relative;
+	width: var(--mms-frame-size);
+	aspect-ratio: 1 / 1;
+	border-radius: 12px;
+	/* the dim around the cutout */
+	box-shadow: 0 0 0 200vmax var(--mms-dim);
+	transition: box-shadow 0.2s;
+}
+.mms-corner {
+	position: absolute;
+	width: var(--mms-corner-size);
+	height: var(--mms-corner-size);
+	border: 0 solid var(--mms-corner-color);
+	transition: border-color 0.2s;
+}
+.mms-corner--tl { top: 0; left: 0; border-top-width: var(--mms-corner-width); border-left-width: var(--mms-corner-width); border-top-left-radius: 12px; }
+.mms-corner--tr { top: 0; right: 0; border-top-width: var(--mms-corner-width); border-right-width: var(--mms-corner-width); border-top-right-radius: 12px; }
+.mms-corner--bl { bottom: 0; left: 0; border-bottom-width: var(--mms-corner-width); border-left-width: var(--mms-corner-width); border-bottom-left-radius: 12px; }
+.mms-corner--br { bottom: 0; right: 0; border-bottom-width: var(--mms-corner-width); border-right-width: var(--mms-corner-width); border-bottom-right-radius: 12px; }
+.mms-scanline {
+	position: absolute;
+	left: 6%;
+	right: 6%;
+	top: 10%;
+	height: 2px;
+	border-radius: 1px;
+	background: var(--mms-accent);
+	box-shadow: 0 0 8px var(--mms-accent);
+	opacity: 0;
+}
+.mms-stage[data-status="scanning"] .mms-scanline {
+	opacity: 0.9;
+	animation: mms-scan 2.2s ease-in-out infinite;
+}
+@keyframes mms-scan {
+	0%, 100% { top: 10%; }
+	50% { top: calc(90% - 2px); }
+}
+@media (prefers-reduced-motion: reduce) {
+	.mms-stage[data-status="scanning"] .mms-scanline { animation: none; top: 49%; }
+}
+.mms-stage.mms-flash .mms-corner { border-color: var(--mms-success); }
+.mms-stage.mms-flash .mms-frame {
+	box-shadow: 0 0 0 200vmax var(--mms-dim), inset 0 0 24px var(--mms-success);
+}
+.mms-controls button {
+	position: absolute;
+	z-index: 2;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 44px;
+	height: 44px;
+	padding: 10px;
+	border: 0;
+	border-radius: 50%;
+	background: var(--mms-btn-bg);
+	color: var(--mms-btn-fg);
+	cursor: pointer;
+	-webkit-tap-highlight-color: transparent;
+}
+.mms-controls button:active { transform: scale(0.94); }
+.mms-controls button svg { width: 100%; height: 100%; }
+.mms-controls [hidden] { display: none; }
+.mms-btn-cancel { top: 12px; right: 12px; }
+.mms-btn-torch { bottom: 12px; left: 12px; }
+.mms-btn-torch[aria-pressed="true"] {
+	background: var(--mms-accent);
+	color: #fff;
+}
+.mms-btn-switch { bottom: 12px; right: 12px; }
+`;
+function ensureStyles(doc) {
+    // per-document — a stage mounted into an iframe/popup needs the CSS in
+    // ITS document, not the opener's
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = CSS;
+    doc.head.appendChild(style);
+}
+function resolveTheme(theme) {
+    if (theme !== "auto")
+        return theme;
+    try {
+        return globalThis.matchMedia?.("(prefers-color-scheme: dark)")?.matches
+            ? "dark"
+            : "light";
+    }
+    catch (_e) {
+        return "dark";
+    }
+}
+function setHidden(el, hidden) {
+    if (hidden)
+        el.setAttribute("hidden", "");
+    else
+        el.removeAttribute("hidden");
+}
+function button(doc, cls, label, icon) {
+    const btn = doc.createElement("button");
+    btn.type = "button";
+    btn.className = `mms-btn ${cls}`;
+    btn.setAttribute("aria-label", label);
+    btn.innerHTML = icon;
+    return btn;
+}
+/**
+ * Mount the scanning stage UI into `options.container`.
+ *
+ * ```ts
+ * const scanner = createScanner();
+ * const stage = createScannerStage(scanner, { container: el });
+ * const result = await scanner.start();
+ * stage.destroy();
+ * ```
+ *
+ * Styling is themable via scoped CSS custom properties (`--mms-*`), e.g.
+ * `--mms-accent`, `--mms-dim`, `--mms-frame-size`, `--mms-radius`.
+ */
+export function createScannerStage(scanner, options) {
+    const container = options?.container;
+    if (!container)
+        throw new Error("options.container is required");
+    // derive the document from the mount point — supports iframes/popups
+    const doc = container.ownerDocument ??
+        (typeof document !== "undefined" ? document : null);
+    if (!doc)
+        throw new Error("createScannerStage requires a DOM environment");
+    const video = scanner.getVideo();
+    if (!video) {
+        throw new Error("Scanner could not provide a video element");
+    }
+    ensureStyles(doc);
+    const controls = { cancel: true, ...options.controls };
+    const cleanups = [];
+    // --- dom ----------------------------------------------------------------
+    const el = doc.createElement("div");
+    el.className = "mms-stage";
+    el.setAttribute("data-theme", resolveTheme(options.theme ?? "auto"));
+    if (options.accent)
+        el.style.setProperty("--mms-accent", options.accent);
+    video.classList.add("mms-video");
+    el.appendChild(video);
+    const overlay = doc.createElement("div");
+    overlay.className = "mms-overlay";
+    const frame = doc.createElement("div");
+    frame.className = "mms-frame";
+    for (const pos of ["tl", "tr", "bl", "br"]) {
+        const corner = doc.createElement("span");
+        corner.className = `mms-corner mms-corner--${pos}`;
+        frame.appendChild(corner);
+    }
+    if (options.scanLine ?? true) {
+        const line = doc.createElement("div");
+        line.className = "mms-scanline";
+        frame.appendChild(line);
+    }
+    overlay.appendChild(frame);
+    el.appendChild(overlay);
+    const controlsEl = doc.createElement("div");
+    controlsEl.className = "mms-controls";
+    let cancelBtn = null;
+    let torchBtn = null;
+    let switchBtn = null;
+    if (controls.cancel) {
+        cancelBtn = button(doc, "mms-btn-cancel", "Cancel scanning", ICONS.cancel);
+        cancelBtn.addEventListener("click", () => {
+            scanner.stop();
+            options.onCancel?.();
+        });
+        controlsEl.appendChild(cancelBtn);
+    }
+    if (controls.torch) {
+        torchBtn = button(doc, "mms-btn-torch", "Toggle flashlight", ICONS.torch);
+        setHidden(torchBtn, true);
+        torchBtn.addEventListener("click", () => {
+            void scanner.setTorch(!scanner.get().torch.on);
+        });
+        controlsEl.appendChild(torchBtn);
+    }
+    if (controls.cameraSwitch) {
+        switchBtn = button(doc, "mms-btn-switch", "Switch camera", ICONS.switch);
+        setHidden(switchBtn, true);
+        switchBtn.addEventListener("click", () => {
+            const { cameras, activeCameraId } = scanner.get();
+            if (cameras.length < 2)
+                return;
+            const idx = cameras.findIndex((c) => c.deviceId === activeCameraId);
+            const next = cameras[(idx + 1) % cameras.length];
+            void scanner.setCamera(next.deviceId);
+        });
+        controlsEl.appendChild(switchBtn);
+    }
+    el.appendChild(controlsEl);
+    // --- theme (auto) ---------------------------------------------------------
+    if ((options.theme ?? "auto") === "auto") {
+        try {
+            const mq = globalThis.matchMedia?.("(prefers-color-scheme: dark)");
+            const onChange = () => {
+                el.setAttribute("data-theme", mq?.matches ? "dark" : "light");
+            };
+            mq?.addEventListener?.("change", onChange);
+            if (mq)
+                cleanups.push(() => mq.removeEventListener?.("change", onChange));
+        }
+        catch (_e) {
+            /* noop */
+        }
+    }
+    // --- reactive wiring ------------------------------------------------------
+    let flashTimer = null;
+    let lastFlashTs = 0;
+    const unsub = scanner.subscribe((state) => {
+        el.setAttribute("data-status", state.status);
+        if (torchBtn) {
+            setHidden(torchBtn, !state.torch.supported);
+            torchBtn.setAttribute("aria-pressed", String(state.torch.on));
+        }
+        if (switchBtn)
+            setHidden(switchBtn, state.cameras.length < 2);
+        if (state.lastResult && state.lastResult.timestamp !== lastFlashTs) {
+            lastFlashTs = state.lastResult.timestamp;
+            el.classList.add("mms-flash");
+            if (flashTimer)
+                clearTimeout(flashTimer);
+            flashTimer = setTimeout(() => el.classList.remove("mms-flash"), FLASH_MS);
+        }
+    });
+    cleanups.push(unsub);
+    cleanups.push(() => {
+        if (flashTimer)
+            clearTimeout(flashTimer);
+    });
+    // --- mount ----------------------------------------------------------------
+    // the stage is absolutely positioned inside the container — make sure the
+    // container establishes a positioning context (computed style respected,
+    // reverted on destroy if we set it)
+    let containerPositionSet = false;
+    try {
+        const computed = globalThis.getComputedStyle?.(container)?.position;
+        const pos = computed ?? container.style?.position;
+        if (!pos || pos === "static") {
+            container.style.position = "relative";
+            containerPositionSet = true;
+        }
+    }
+    catch (_e) {
+        /* non-browser DOM without style support — leave positioning to the app */
+    }
+    container.appendChild(el);
+    return {
+        el,
+        destroy() {
+            cleanups.forEach((fn) => {
+                try {
+                    fn();
+                }
+                catch (_e) {
+                    /* noop */
+                }
+            });
+            cleanups.length = 0;
+            if (containerPositionSet) {
+                try {
+                    container.style.position = "";
+                }
+                catch (_e) {
+                    /* noop */
+                }
+            }
+            el.remove();
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,262 @@
+import type { Unsubscribe } from "@marianmeres/store";
+/**
+ * Barcode formats supported by the underlying zxing-cpp engine (via
+ * `barcode-detector`). The default is `["qr_code"]` — fewer enabled formats
+ * means faster per-frame decode and fewer false positives.
+ *
+ * The special values `"linear_codes"`, `"matrix_codes"` and `"any"` are
+ * engine-level shortcuts expanding to the respective format groups.
+ */
+export type BarcodeFormat = "aztec" | "codabar" | "code_39" | "code_93" | "code_128" | "data_matrix" | "databar" | "databar_expanded" | "databar_limited" | "dx_film_edge" | "ean_8" | "ean_13" | "itf" | "maxi_code" | "micro_qr_code" | "pdf417" | "qr_code" | "rm_qr_code" | "upc_a" | "upc_e" | "linear_codes" | "matrix_codes" | "any" | (string & Record<never, never>);
+/** A 2D point in source-image coordinates. */
+export interface Point2D {
+    x: number;
+    y: number;
+}
+/** Camera permission status (mirrors the micperms taxonomy). */
+export type CameraPermissionStatus = "unknown" | "prompt" | "granted" | "denied";
+/** Camera facing direction (best-effort, derived from device label). */
+export type CameraFacing = "user" | "environment";
+/** Info about an available video input device. */
+export interface CameraInfo {
+    /** Device id usable with {@linkcode Scanner.setCamera}. */
+    deviceId: string;
+    /**
+     * Human readable label. NOTE: browsers return empty labels until
+     * camera permission has been granted at least once.
+     */
+    label: string;
+    /** Best-effort facing direction derived from the label, or `null`. */
+    facing: CameraFacing | null;
+}
+/**
+ * Machine-readable error codes attached to {@linkcode ScannerState.error}.
+ *
+ * - `NO_DEVICE` — getUserMedia threw `NotFoundError` / `DevicesNotFoundError`.
+ *   No camera is available.
+ * - `INSECURE_CONTEXT` — getUserMedia threw `SecurityError`. Origin is not
+ *   secure (camera requires HTTPS) or a Permissions-Policy blocks the API.
+ * - `DEVICE_BUSY` — getUserMedia threw `NotReadableError` / `TrackStartError`.
+ *   Hardware is held by another consumer.
+ * - `PERMISSION_DENIED` — getUserMedia threw `NotAllowedError` /
+ *   `PermissionDeniedError`. The user (or platform policy) denied camera
+ *   access; `state.permission` is set to `"denied"` as well.
+ * - `REQUEST_FAILED` — camera acquisition failed with a non-classified error,
+ *   or the live camera track ended unexpectedly (permission revoked
+ *   mid-scan, device unplugged, camera preempted by a native app).
+ * - `NOT_SUPPORTED` — required platform API is missing (no `mediaDevices`,
+ *   no DOM for the video element, ...).
+ * - `DETECTOR_FAILED` — the barcode detector threw repeatedly.
+ */
+export declare const ScannerErrorCode: {
+    readonly NoDevice: "NO_DEVICE";
+    readonly InsecureContext: "INSECURE_CONTEXT";
+    readonly DeviceBusy: "DEVICE_BUSY";
+    readonly PermissionDenied: "PERMISSION_DENIED";
+    readonly RequestFailed: "REQUEST_FAILED";
+    readonly NotSupported: "NOT_SUPPORTED";
+    readonly DetectorFailed: "DETECTOR_FAILED";
+};
+export type ScannerErrorCode = typeof ScannerErrorCode[keyof typeof ScannerErrorCode];
+/** Error attached to {@linkcode ScannerState.error}. */
+export interface ScannerError {
+    /** Machine-readable error code. See {@linkcode ScannerErrorCode}. */
+    code: ScannerErrorCode;
+    /** Human-readable error message (typically forwarded from underlying API). */
+    message: string;
+}
+/** Scanner lifecycle status. */
+export type ScannerStatus = "idle" | "initializing" | "scanning" | "stopped";
+/** A single successful barcode detection. */
+export interface ScanResult {
+    /** The decoded payload. */
+    value: string;
+    /** Detected barcode format (e.g. `"qr_code"`). */
+    format: BarcodeFormat;
+    /** Corner points of the detected symbol in source coordinates. */
+    cornerPoints: Point2D[];
+    /** Bounding box of the detected symbol in source coordinates. */
+    boundingBox: DOMRectReadOnly;
+    /** Detection timestamp (`Date.now()`). */
+    timestamp: number;
+}
+/** Reactive state of the scanner. */
+export interface ScannerState {
+    /** Current lifecycle status. */
+    status: ScannerStatus;
+    /** Last error, or `null`. Methods never throw — errors land here. */
+    error: ScannerError | null;
+    /**
+     * Camera permission status, best effort (Permissions API where available,
+     * otherwise updated from getUserMedia outcomes).
+     */
+    permission: CameraPermissionStatus;
+    /** Torch (flashlight) capability + current state of the active track. */
+    torch: {
+        supported: boolean;
+        on: boolean;
+    };
+    /**
+     * Available cameras. Populated on {@linkcode Scanner.listCameras} and
+     * after successful {@linkcode Scanner.start} (labels require permission).
+     */
+    cameras: CameraInfo[];
+    /** Device id of the currently active camera, or `null`. */
+    activeCameraId: string | null;
+    /** Most recent successful detection, or `null`. */
+    lastResult: ScanResult | null;
+}
+/**
+ * The raw detection shape produced by a {@linkcode Detector} — structurally
+ * compatible with the W3C `DetectedBarcode`.
+ */
+export interface DetectedBarcodeLike {
+    rawValue: string;
+    format: string;
+    cornerPoints: Point2D[];
+    boundingBox: DOMRectReadOnly;
+}
+/** Anything a {@linkcode Detector} can decode. */
+export type DetectorSource = HTMLVideoElement | HTMLImageElement | HTMLCanvasElement | ImageBitmap | ImageData | Blob;
+/**
+ * Abstraction over the barcode decoding engine — shaped like the W3C
+ * `BarcodeDetector`. Injectable for testing or engine swaps. The default
+ * implementation wraps the `barcode-detector` ponyfill (zxing-cpp wasm).
+ */
+export interface Detector {
+    detect(source: DetectorSource): Promise<DetectedBarcodeLike[]>;
+}
+/**
+ * Abstraction over camera acquisition. Injectable for testing or replacement.
+ * The default implementation wraps `navigator.mediaDevices` for stream
+ * acquisition/enumeration and delegates the permission lifecycle to
+ * `@marianmeres/mediaperms`.
+ *
+ * NOTE (difference vs micperms): the scanner RETAINS the acquired stream for
+ * the live preview — the adapter must return a live `MediaStream`, the
+ * scanner is responsible for stopping its tracks.
+ */
+export interface CameraAdapter {
+    /** Acquire a camera stream. May prompt. Rejections are classified by the scanner. */
+    getStream(constraints: MediaStreamConstraints): Promise<MediaStream>;
+    /** List available video input devices. */
+    enumerateVideoDevices(): Promise<CameraInfo[]>;
+    /**
+     * Query camera permission via the Permissions API without prompting.
+     * Returns `null` when the Permissions API is unavailable/unsupported.
+     */
+    queryPermission(): Promise<CameraPermissionStatus | null>;
+    /**
+     * Subscribe to permission changes. Returns an unsubscribe fn, or `null`
+     * when not supported.
+     */
+    onPermissionChange(cb: (status: CameraPermissionStatus) => void): (() => void) | null;
+    /**
+     * Release adapter-owned resources (e.g. an internally created mediaperms
+     * instance). Called by {@linkcode Scanner.destroy} ONLY when the scanner
+     * created the adapter itself — a consumer-provided adapter is owned (and
+     * destroyed) by the consumer.
+     */
+    destroy?(): void;
+}
+/** Scanning mode. See {@linkcode ScannerConfig.mode}. */
+export type ScanMode = "single" | "continuous";
+/**
+ * Logger shape — method-only, so both `@marianmeres/clog` instances and the
+ * plain `console` satisfy it.
+ */
+export interface LoggerLike {
+    debug: (...args: unknown[]) => unknown;
+    warn: (...args: unknown[]) => unknown;
+    error: (...args: unknown[]) => unknown;
+}
+/** Configuration for {@linkcode createScanner}. */
+export interface ScannerConfig {
+    /**
+     * Video element to play the camera stream in. Created lazily when omitted
+     * (requires DOM). The shipped stage UI uses {@linkcode Scanner.getVideo}.
+     */
+    video?: HTMLVideoElement;
+    /** Formats to detect. Default `["qr_code"]`. */
+    formats?: BarcodeFormat[];
+    /**
+     * - `"single"` (default): auto-stop after the first detection, which is
+     *   passed to `onScan` and resolves the `start()` promise.
+     * - `"continuous"`: keep scanning; every detection fires `onScan`
+     *   (deduped within {@linkcode ScannerConfig.dedupeMs}); `start()`
+     *   resolves `null` when stopped.
+     */
+    mode?: ScanMode;
+    /** Called for every successful detection. */
+    onScan?: (result: ScanResult) => void;
+    /** Called whenever an error is set on the state. */
+    onError?: (error: ScannerError) => void;
+    /**
+     * `"environment"` (default) / `"user"` facing hint, or a concrete
+     * `deviceId`.
+     */
+    preferredCamera?: CameraFacing | (string & Record<never, never>);
+    /** Minimal interval between decode attempts in ms. Default `100` (~10 fps). */
+    scanIntervalMs?: number;
+    /**
+     * Continuous mode: suppress repeated detections of the identical value
+     * within this window (ms). Default `1500`.
+     */
+    dedupeMs?: number;
+    /** Camera acquisition seam. Default wraps `navigator.mediaDevices`. */
+    adapter?: CameraAdapter;
+    /** Decoding engine seam. Default wraps the `barcode-detector` ponyfill. */
+    detector?: Detector;
+    /**
+     * Overrides passed to zxing-wasm's `prepareZXingModule` — most notably
+     * `locateFile` for self-hosting the `.wasm` binary (CSP-strict or offline
+     * apps). By default the wasm is fetched lazily from the jsDelivr CDN.
+     *
+     * ```ts
+     * wasmOverrides: { locateFile: (path, prefix) => `/assets/${path}` }
+     * ```
+     */
+    wasmOverrides?: Record<string, unknown>;
+    /** Custom logger (`@marianmeres/clog` compatible). */
+    logger?: LoggerLike;
+}
+/** The scanner instance created by {@linkcode createScanner}. */
+export interface Scanner {
+    /**
+     * Subscribe to reactive state. Svelte store contract — the callback fires
+     * immediately with the current state. Returns an idempotent unsubscribe fn
+     * that also implements `Symbol.dispose` (usable with `using`).
+     */
+    subscribe(cb: (state: ScannerState) => void): Unsubscribe;
+    /** Get current state snapshot. */
+    get(): ScannerState;
+    /**
+     * Acquire the camera and start scanning. Never rejects.
+     *
+     * - `"single"` mode: resolves with the first {@linkcode ScanResult}, or
+     *   `null` when cancelled via {@linkcode Scanner.stop} (or on failure —
+     *   check `state.error`).
+     * - `"continuous"` mode: resolves `null` when stopped.
+     *
+     * Concurrent calls while active return the same in-flight promise.
+     */
+    start(): Promise<ScanResult | null>;
+    /** Cancel: stop the loop, release the camera. Resolves pending `start()` with `null`. */
+    stop(): void;
+    /** List available cameras (also updates `state.cameras`). */
+    listCameras(): Promise<CameraInfo[]>;
+    /** Switch to another camera (live-switch while scanning is supported). */
+    setCamera(deviceId: string): Promise<void>;
+    /**
+     * Turn the torch (flashlight) on/off. Resolves `true` on success, `false`
+     * when unsupported or failed (never rejects).
+     */
+    setTorch(on: boolean): Promise<boolean>;
+    /**
+     * The video element used for the live preview. Lazily created when none
+     * was configured (returns `null` in non-DOM environments).
+     */
+    getVideo(): HTMLVideoElement | null;
+    /** Stop everything and release all resources/listeners. Idempotent. */
+    destroy(): void;
+}

package/dist/types.js

@@ -0,0 +1,28 @@
+/**
+ * Machine-readable error codes attached to {@linkcode ScannerState.error}.
+ *
+ * - `NO_DEVICE` — getUserMedia threw `NotFoundError` / `DevicesNotFoundError`.
+ *   No camera is available.
+ * - `INSECURE_CONTEXT` — getUserMedia threw `SecurityError`. Origin is not
+ *   secure (camera requires HTTPS) or a Permissions-Policy blocks the API.
+ * - `DEVICE_BUSY` — getUserMedia threw `NotReadableError` / `TrackStartError`.
+ *   Hardware is held by another consumer.
+ * - `PERMISSION_DENIED` — getUserMedia threw `NotAllowedError` /
+ *   `PermissionDeniedError`. The user (or platform policy) denied camera
+ *   access; `state.permission` is set to `"denied"` as well.
+ * - `REQUEST_FAILED` — camera acquisition failed with a non-classified error,
+ *   or the live camera track ended unexpectedly (permission revoked
+ *   mid-scan, device unplugged, camera preempted by a native app).
+ * - `NOT_SUPPORTED` — required platform API is missing (no `mediaDevices`,
+ *   no DOM for the video element, ...).
+ * - `DETECTOR_FAILED` — the barcode detector threw repeatedly.
+ */
+export const ScannerErrorCode = {
+    NoDevice: "NO_DEVICE",
+    InsecureContext: "INSECURE_CONTEXT",
+    DeviceBusy: "DEVICE_BUSY",
+    PermissionDenied: "PERMISSION_DENIED",
+    RequestFailed: "REQUEST_FAILED",
+    NotSupported: "NOT_SUPPORTED",
+    DetectorFailed: "DETECTOR_FAILED",
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@marianmeres/scanner",
+	"version": "1.0.1",
+	"type": "module",
+	"main": "dist/mod.js",
+	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		},
+		"./stage": {
+			"types": "./dist/stage.d.ts",
+			"import": "./dist/stage.js"
+		}
+	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md",
+		"CLAUDE.md"
+	],
+	"author": "Marian Meres",
+	"license": "MIT",
+	"dependencies": {
+		"@marianmeres/clog": "^3.21.0",
+		"@marianmeres/mediaperms": "^1.2.0",
+		"@marianmeres/store": "^3.0.1",
+		"barcode-detector": "^3.2.1"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/marianmeres/scanner.git"
+	},
+	"bugs": {
+		"url": "https://github.com/marianmeres/scanner/issues"
+	}
+}