capacitor-camera-view 2.4.0 → 3.0.0

package/dist/esm/web.js

@@ -11,13 +11,52 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
 };
 var _CameraViewWeb_isRunning;
 import { WebPlugin } from '@capacitor/core';
-import { calculateVisibleArea, canvasToBase64, drawVisibleAreaToCanvas, transformBarcodeBoundingBox } from './utils';
+import { applyCssZoomCrop, calculateFullFrameArea, calculateVisibleArea, canvasToBase64, drawVisibleAreaToCanvas, transformBarcodeBoundingBox, } from './utils';
+/**
+ * Suppression window in milliseconds during which a repeat of the same barcode
+ * (identical value + type) is not re-emitted. A genuinely new code still emits
+ * immediately. Kept consistent with the iOS and Android implementations.
+ */
+export const BARCODE_SUPPRESSION_WINDOW_MS = 500;
+/**
+ * Once the per-key dedupe map grows past this size, expired entries are pruned
+ * so a long session scanning many different codes stays bounded. Kept
+ * consistent with the iOS and Android implementations.
+ */
+export const BARCODE_DEDUPE_MAP_PRUNE_THRESHOLD = 64;
+/**
+ * Backstop for the "wait until the video is ready" step in
+ * {@link CameraViewWeb.startBarcodeDetection}. If the video element never
+ * fires `loadeddata` (e.g. a stalled stream), the wait settles anyway after
+ * this many milliseconds instead of leaving a dangling listener and a
+ * permanently pending promise.
+ */
+export const BARCODE_VIDEO_READY_TIMEOUT_MS = 5000;
+/**
+ * Baseline `ideal` capture resolution requested from `getUserMedia` in
+ * {@link CameraViewWeb.start}. Without any width/height hint, browsers default
+ * to a low-resolution stream (often 640x480), which caps capture quality.
+ *
+ * These are `ideal` (not `exact`/`min`) so devices that cannot deliver
+ * 1080p-class video still start at their best available resolution rather
+ * than failing acquisition.
+ */
+export const DEFAULT_IDEAL_CAPTURE_WIDTH = 1920;
+export const DEFAULT_IDEAL_CAPTURE_HEIGHT = 1080;
+/**
+ * Bounds for the CSS `transform: scale()` zoom simulation used when the browser
+ * does not expose a native `zoom` track capability. `getZoom` reports this
+ * range and `setZoom` clamps the applied scale to it in fallback mode.
+ */
+export const SIMULATED_ZOOM_MIN = 1.0;
+export const SIMULATED_ZOOM_MAX = 3.0;
 export const BARCODE_TYPE_TO_WEB_FORMAT = {
     qr: 'qr_code',
     code128: 'code_128',
     code39: 'code_39',
     code39Mod43: null,
     code93: 'code_93',
+    codabar: 'codabar',
     ean8: 'ean_8',
     ean13: 'ean_13',
     interleaved2of5: 'itf',
@@ -25,8 +64,63 @@ export const BARCODE_TYPE_TO_WEB_FORMAT = {
     pdf417: 'pdf417',
     aztec: 'aztec',
     dataMatrix: 'data_matrix',
+    upcA: 'upc_a',
     upce: 'upc_e',
 };
+/**
+ * Inverse of {@link BARCODE_TYPE_TO_WEB_FORMAT}: maps the web BarcodeDetector
+ * format back onto the cross-platform {@link BarcodeType} vocabulary so the
+ * `barcodeDetected` event emits the same `type` values as iOS and Android.
+ *
+ * Note: `interleaved2of5` and `itf14` both map to the web format `itf`, so the
+ * inversion has a collision that is resolved by insertion order — `itf14` comes
+ * last in {@link BARCODE_TYPE_TO_WEB_FORMAT} and wins, which is the intended
+ * result for `itf` detections.
+ */
+export const WEB_FORMAT_TO_BARCODE_TYPE = Object.entries(BARCODE_TYPE_TO_WEB_FORMAT).reduce((acc, [barcodeType, webFormat]) => {
+    if (webFormat) {
+        acc[webFormat] = barcodeType;
+    }
+    return acc;
+}, {});
+/**
+ * Error thrown by the web implementation for a rejected plugin call.
+ *
+ * Carries a stable `code` from the {@link CameraErrorCode} vocabulary, the
+ * same public contract iOS and Android provide, so consumers can `switch` on
+ * `error.code` instead of matching on the human-readable `message`.
+ *
+ * Methods that reject via `WebPlugin.unimplemented()` are the one exception:
+ * those keep Capacitor's own `UNIMPLEMENTED` convention.
+ */
+export class CameraViewError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = 'CameraViewError';
+        this.code = code;
+    }
+}
+/**
+ * Classifies a `getUserMedia` failure into the closest-fitting
+ * {@link CameraErrorCode}, shared by every acquisition site.
+ *
+ * `kind` selects which media type's dedicated codes apply for `NotFoundError`/
+ * `NotReadableError` so a missing/busy camera and a missing/busy microphone
+ * aren't conflated. Anything unmappable falls back to `UNKNOWN_ERROR`.
+ */
+export function classifyGetUserMediaErrorCode(err, kind) {
+    if (err instanceof DOMException) {
+        switch (err.name) {
+            case 'NotAllowedError':
+                return 'PERMISSION_DENIED';
+            case 'NotFoundError':
+                return kind === 'camera' ? 'CAMERA_UNAVAILABLE' : 'AUDIO_DEVICE_UNAVAILABLE';
+            case 'NotReadableError':
+                return kind === 'camera' ? 'DEVICE_LOCKED' : 'AUDIO_INPUT_ADDITION_FAILED';
+        }
+    }
+    return 'UNKNOWN_ERROR';
+}
 /**
  * Web implementation of the CameraViewPlugin.
  * Optimized for performance and battery efficiency.
@@ -43,10 +137,38 @@ export class CameraViewWeb extends WebPlugin {
         // Configuration state
         this.currentCamera = 'environment'; // Default to back camera
         this.currentZoom = 1.0;
+        // Whether the current zoom is applied through the native track `zoom`
+        // capability (`applyConstraints`) rather than the CSS `transform: scale()`
+        // simulation. Capture only needs to compensate for the transform in the
+        // CSS-fallback case.
+        this.usingNativeZoom = false;
         this.currentFlashMode = 'off';
+        // The aspect ratio the current session was started with, or null when the
+        // option was omitted. Selects the capture contract: with an explicit ratio,
+        // capture() returns the full sensor-ratio frame (cross-platform contract);
+        // without it, the legacy web behavior of capturing the visible
+        // (cover-cropped) preview region is preserved.
+        this.sessionAspectRatio = null;
+        // How the current session scales the preview into its container. `'fit'`
+        // (object-fit: contain) letterboxes the whole frame; `'cover'` (the default)
+        // center-crops it. Selects the barcode-transform variant and, together with
+        // the aspect ratio, the capture crop.
+        this.sessionPreviewScaleMode = 'cover';
+        // Resolution/aspect-ratio constraints of the current session, kept so
+        // flipCamera() re-acquires the stream with the same resolution contract
+        // instead of falling back to the browser default.
+        this.sessionResolutionConstraints = {};
         // Barcode detection support
         this.barcodeDetectionSupported = false;
         this.barcodeDetector = null;
+        // Scopes the barcode detection loop to a single start()/stop() session so a
+        // rapid stop() -> start() can't let the old loop mistake the new session's
+        // running flag for its own and keep polling a detached video element.
+        this.barcodeDetectionAbortController = null;
+        // The most recently scheduled `requestAnimationFrame` id for the barcode
+        // detection loop, so `stop()` can cancel a queued-but-not-yet-run frame
+        // outright.
+        this.barcodeAnimationFrameId = null;
         // Recording state
         this.mediaRecorder = null;
         this.recordedChunks = [];
@@ -59,41 +181,88 @@ export class CameraViewWeb extends WebPlugin {
      * Start the camera with the given configuration
      */
     async start(options) {
+        var _a, _b, _c, _d;
+        // A session is already running. Per the cross-platform contract, reject
+        // instead of silently reconfiguring or no-op'ing: callers who need a
+        // different configuration (e.g. a different position or resolution) must
+        // call `stop()` first and then `start()` again with the new options.
         if (__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f")) {
-            return;
-        }
-        const permissionStatus = await this.requestPermissions();
-        if (permissionStatus.camera !== 'granted') {
-            throw new Error('Camera permission was not granted');
+            throw new CameraViewError('Camera session is already running. Call stop() first.', 'SESSION_ALREADY_RUNNING');
         }
         try {
             // Set up video element if it doesn't exist
             if (!this.videoElement) {
                 await this.setupVideoElement(options === null || options === void 0 ? void 0 : options.containerElementId);
             }
-            // Set up video constraints based on options
-            const videoConstraints = {};
-            // Prefer deviceId if specified
-            if (options === null || options === void 0 ? void 0 : options.deviceId) {
-                videoConstraints.deviceId = { exact: options.deviceId };
-                // Remember the current camera mode (though we're using a specific device)
-                this.currentCamera = (options === null || options === void 0 ? void 0 : options.position) === 'front' ? 'user' : 'environment';
-            }
-            else {
-                // Fall back to facing mode
-                const facingMode = (options === null || options === void 0 ? void 0 : options.position) === 'front' ? 'user' : 'environment';
-                this.currentCamera = facingMode;
-                videoConstraints.facingMode = facingMode;
-            }
-            const constraints = {
-                video: videoConstraints,
-                audio: false,
-            };
+        }
+        catch (err) {
+            // The only failure path in setupVideoElement() is the target container
+            // element not being found, which is the web equivalent of "could not
+            // find the view to render the camera preview into".
+            throw new CameraViewError(`Failed to start camera: ${this.formatError(err)}`, 'WEBVIEW_UNAVAILABLE');
+        }
+        // Apply the preview scale mode to the video element. `'fit'` letterboxes
+        // the whole frame (object-fit: contain); the empty bars show the container's
+        // own background. `'cover'` keeps the long-standing center-cropped preview.
+        this.sessionPreviewScaleMode = (_a = options === null || options === void 0 ? void 0 : options.previewScaleMode) !== null && _a !== void 0 ? _a : 'cover';
+        if (this.videoElement) {
+            this.videoElement.style.objectFit = this.sessionPreviewScaleMode === 'fit' ? 'contain' : 'cover';
+        }
+        // Set up video constraints based on options
+        this.sessionAspectRatio = (_b = options === null || options === void 0 ? void 0 : options.aspectRatio) !== null && _b !== void 0 ? _b : null;
+        this.sessionResolutionConstraints = this.buildResolutionConstraints(options);
+        const videoConstraints = Object.assign({}, this.sessionResolutionConstraints);
+        // Prefer deviceId if specified
+        if (options === null || options === void 0 ? void 0 : options.deviceId) {
+            videoConstraints.deviceId = { exact: options.deviceId };
+            // Remember the current camera mode (though we're using a specific device)
+            this.currentCamera = (options === null || options === void 0 ? void 0 : options.position) === 'front' ? 'user' : 'environment';
+        }
+        else {
+            // Fall back to facing mode
+            const facingMode = (options === null || options === void 0 ? void 0 : options.position) === 'front' ? 'user' : 'environment';
+            this.currentCamera = facingMode;
+            videoConstraints.facingMode = facingMode;
+        }
+        const constraints = {
+            video: videoConstraints,
+            audio: false,
+        };
+        // Acquire the camera exactly once, using the real constraints, and derive
+        // the permission outcome from this single call. Probing permission with a
+        // throwaway acquisition first would double startup latency, flash the
+        // camera indicator twice, and risk a spurious NotReadableError on devices
+        // where the camera is exclusive.
+        try {
             this.stream = await navigator.mediaDevices.getUserMedia(constraints);
+        }
+        catch (err) {
+            throw this.mapStartAcquisitionError(err);
+        }
+        try {
             if (this.videoElement) {
                 this.videoElement.srcObject = this.stream;
-                this.videoElement.play();
+                // Some browsers' autoplay policies can reject `play()` (e.g. lack of a
+                // recent user gesture). The element is muted + playsInline, which satisfies
+                // autoplay policies in virtually all cases, but a rejection must still be
+                // handled here rather than left as an unhandled promise rejection.
+                try {
+                    await this.videoElement.play();
+                }
+                catch (err) {
+                    console.warn('[CameraView] Failed to autoplay the video preview', err);
+                }
                 __classPrivateFieldSet(this, _CameraViewWeb_isRunning, true, "f");
+                // Apply the initial zoom. This also re-establishes zoom on the freshly
+                // created video element after a stop()/start() cycle, keeping the
+                // applied zoom in sync with `currentZoom` instead of silently resetting
+                // to an untransformed element. A zoom failure must not abort start().
+                try {
+                    await this.setZoom({ level: (_c = options === null || options === void 0 ? void 0 : options.zoomFactor) !== null && _c !== void 0 ? _c : 1.0 });
+                }
+                catch (err) {
+                    console.warn('[CameraView] Failed to apply initial zoom factor', err);
+                }
                 // If barcode detection is enabled and supported, start detection
                 if (options === null || options === void 0 ? void 0 : options.enableBarcodeDetection) {
                     await this.checkBarcodeDetectionSupport();
@@ -105,22 +274,90 @@ export class CameraViewWeb extends WebPlugin {
             }
         }
         catch (err) {
-            throw new Error(`Failed to start camera: ${this.formatError(err)}`);
+            // The stream was already acquired here, so its tracks are still live.
+            // Tear down the partially-initialized session state so the thrown error
+            // leaves a clean slate for a subsequent start().
+            (_d = this.stream) === null || _d === void 0 ? void 0 : _d.getTracks().forEach((track) => track.stop());
+            this.stream = null;
+            __classPrivateFieldSet(this, _CameraViewWeb_isRunning, false, "f");
+            if (this.videoElement) {
+                this.videoElement.srcObject = null;
+            }
+            throw new CameraViewError(`Failed to start camera: ${this.formatError(err)}`, 'UNKNOWN_ERROR');
         }
     }
+    /**
+     * Builds the resolution/aspect-ratio part of the `getUserMedia` video
+     * constraints for a session.
+     *
+     * `captureMaxDimension` replaces the ideal width (the longer edge in the
+     * stream's landscape-oriented coordinate space) and the ideal height is
+     * derived from the configured ratio. Everything stays `ideal` so acquisition
+     * degrades gracefully on devices that cannot deliver the request.
+     */
+    buildResolutionConstraints(options) {
+        var _a;
+        const ratio = (options === null || options === void 0 ? void 0 : options.aspectRatio) === '4:3' ? 4 / 3 : 16 / 9;
+        const idealWidth = (_a = options === null || options === void 0 ? void 0 : options.captureMaxDimension) !== null && _a !== void 0 ? _a : DEFAULT_IDEAL_CAPTURE_WIDTH;
+        const idealHeight = Math.round(idealWidth / ratio);
+        const constraints = {
+            width: { ideal: idealWidth },
+            height: { ideal: idealHeight },
+        };
+        if (options === null || options === void 0 ? void 0 : options.aspectRatio) {
+            constraints.aspectRatio = { ideal: ratio };
+        }
+        return constraints;
+    }
+    /**
+     * Map a `getUserMedia` failure from the real-constraints acquisition in
+     * `start()` onto the plugin's error contract.
+     *
+     * `NotAllowedError` maps to `PERMISSION_DENIED`, `NotFoundError` (no
+     * matching device) to `CAMERA_UNAVAILABLE`, and `NotReadableError` (device
+     * claimed by another process) to `DEVICE_LOCKED`, matching the codes
+     * iOS/Android use. Anything else falls back to `UNKNOWN_ERROR`.
+     */
+    mapStartAcquisitionError(err) {
+        if (err instanceof DOMException) {
+            switch (err.name) {
+                case 'NotAllowedError':
+                    return new CameraViewError('Camera permission was not granted', 'PERMISSION_DENIED');
+                case 'NotFoundError':
+                    return new CameraViewError('Failed to start camera: No camera matching the requested configuration was found.', 'CAMERA_UNAVAILABLE');
+                case 'NotReadableError':
+                    return new CameraViewError('Failed to start camera: The camera could not be started, possibly because it is already in use by another application.', 'DEVICE_LOCKED');
+            }
+        }
+        return new CameraViewError(`Failed to start camera: ${this.formatError(err)}`, 'UNKNOWN_ERROR');
+    }
     /**
      * Stop the camera and release resources
      */
     async stop() {
-        var _a;
+        var _a, _b, _c;
         if (!__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f")) {
             return;
         }
         try {
+            // Tear down the barcode detection session tied to this camera session
+            // first: abort settles any pending video-ready wait in
+            // startBarcodeDetection, and cancelling the animation frame stops a
+            // queued detectFrame call from ever running. Together these ensure no
+            // stale loop can survive into a subsequent start().
+            (_a = this.barcodeDetectionAbortController) === null || _a === void 0 ? void 0 : _a.abort();
+            this.barcodeDetectionAbortController = null;
+            if (this.barcodeAnimationFrameId !== null) {
+                cancelAnimationFrame(this.barcodeAnimationFrameId);
+                this.barcodeAnimationFrameId = null;
+            }
             // Stop any active recording
             if (this.mediaRecorder && this.mediaRecorder.state !== 'inactive') {
-                // Reject any pending stopRecording promise since we're force-stopping
-                (_a = this.recordingReject) === null || _a === void 0 ? void 0 : _a.call(this, new Error('Camera session stopped while recording'));
+                // Reject any pending stopRecording promise since we're force-stopping.
+                // There is no dedicated code for this case, so it falls back to
+                // UNKNOWN_ERROR per the plugin's documented "anything unmappable"
+                // contract.
+                (_b = this.recordingReject) === null || _b === void 0 ? void 0 : _b.call(this, new CameraViewError('Camera session stopped while recording', 'UNKNOWN_ERROR'));
                 this.recordingResolve = null;
                 this.recordingReject = null;
                 this.mediaRecorder.stop();
@@ -136,14 +373,19 @@ export class CameraViewWeb extends WebPlugin {
                 this.stream.getTracks().forEach((track) => track.stop());
                 this.stream = null;
             }
-            // Clear video source
+            // Detach the stream and remove the video element from the DOM
             if (this.videoElement) {
+                this.videoElement.pause();
+                this.videoElement.srcObject = null;
+                (_c = this.videoElement.parentNode) === null || _c === void 0 ? void 0 : _c.removeChild(this.videoElement);
                 this.videoElement = null;
             }
             __classPrivateFieldSet(this, _CameraViewWeb_isRunning, false, "f");
         }
         catch (err) {
-            throw new Error(`Failed to stop camera: ${this.formatError(err)}`);
+            // No dedicated code for a teardown failure; falls back to UNKNOWN_ERROR
+            // per the plugin's documented "anything unmappable" contract.
+            throw new CameraViewError(`Failed to stop camera: ${this.formatError(err)}`, 'UNKNOWN_ERROR');
         }
     }
     /**
@@ -157,22 +399,41 @@ export class CameraViewWeb extends WebPlugin {
      * Preserves what the user actually sees in the UI, including cropping from object-fit: cover.
      */
     async capture(options) {
+        var _a;
         const videoElement = this.videoElement;
         if (!__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f") || !videoElement) {
-            throw new Error('Camera is not running');
+            throw new CameraViewError('Camera is not running', 'SESSION_NOT_RUNNING');
         }
         try {
             const canvas = this.getCanvasElement();
-            const visibleArea = calculateVisibleArea(videoElement);
+            // `fit` mode letterboxes the whole frame and an explicit `aspectRatio`
+            // contractually returns the full sensor-ratio frame, so both capture
+            // uncropped. Otherwise capture the visible (cover-cropped) region so the
+            // output matches what the user sees.
+            const captureArea = this.sessionPreviewScaleMode === 'fit' || this.sessionAspectRatio
+                ? calculateFullFrameArea(videoElement)
+                : calculateVisibleArea(videoElement);
+            // In CSS-fallback zoom mode the preview is magnified about its center via
+            // `transform: scale()`, so tighten the source crop to match the zoomed
+            // viewport (this preserves the frame's aspect ratio). Native-zoom mode
+            // needs no compensation: the track already delivers the zoomed frame.
+            const visibleArea = applyCssZoomCrop(captureArea, this.getCssZoomScale());
             drawVisibleAreaToCanvas(canvas, videoElement, visibleArea);
-            const quality = Math.min(1.0, Math.max(0.1, options.quality / 100));
-            if (options.saveToFile) {
+            // Mirror the native platforms' default: `quality` is optional and defaults
+            // to 90 when omitted. Without this, `options?.quality / 100` would be
+            // `NaN` for an undefined quality, which is passed silently to `toBlob`/
+            // `toDataURL` (both treat an invalid quality as "use the default"), so a
+            // caller relying on the documented default would get a different result
+            // on web than on iOS/Android.
+            const requestedQuality = (_a = options === null || options === void 0 ? void 0 : options.quality) !== null && _a !== void 0 ? _a : 90;
+            const quality = Math.min(1.0, Math.max(0.1, requestedQuality / 100));
+            if (options === null || options === void 0 ? void 0 : options.saveToFile) {
                 // Create a blob from canvas and return a blob URL.
                 // `path` is native-only (no filesystem path on web), so it is omitted here.
                 return new Promise((resolve, reject) => {
                     canvas.toBlob((blob) => {
                         if (!blob) {
-                            reject(new Error('Failed to create blob from canvas'));
+                            reject(new CameraViewError('Failed to create blob from canvas', 'IMAGE_COMPRESSION_FAILED'));
                             return;
                         }
                         const url = URL.createObjectURL(blob);
@@ -187,7 +448,7 @@ export class CameraViewWeb extends WebPlugin {
             }
         }
         catch (err) {
-            throw new Error(`Failed to capture photo: ${this.formatError(err)}`);
+            throw new CameraViewError(`Failed to capture photo: ${this.formatError(err)}`, 'FRAME_CAPTURE_ERROR');
         }
     }
     /**
@@ -201,10 +462,10 @@ export class CameraViewWeb extends WebPlugin {
      */
     async startRecording(options) {
         if (!__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f") || !this.videoElement) {
-            throw new Error('Camera is not running');
+            throw new CameraViewError('Camera is not running', 'SESSION_NOT_RUNNING');
         }
         if (this.mediaRecorder) {
-            throw new Error('Recording is already in progress');
+            throw new CameraViewError('Recording is already in progress', 'RECORDING_ALREADY_IN_PROGRESS');
         }
         try {
             let stream = this.stream;
@@ -254,7 +515,10 @@ export class CameraViewWeb extends WebPlugin {
                 this.mediaRecorder = null;
                 this.recordedChunks = [];
                 const errorMessage = (_b = (_a = event.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : 'Unknown recording error';
-                (_c = this.recordingReject) === null || _c === void 0 ? void 0 : _c.call(this, new Error('Recording error: ' + errorMessage));
+                // A generic MediaRecorder runtime failure has no dedicated code, so
+                // it falls back to UNKNOWN_ERROR per the plugin's documented
+                // "anything unmappable" contract.
+                (_c = this.recordingReject) === null || _c === void 0 ? void 0 : _c.call(this, new CameraViewError('Recording error: ' + errorMessage, 'UNKNOWN_ERROR'));
                 this.recordingResolve = null;
                 this.recordingReject = null;
             };
@@ -267,15 +531,43 @@ export class CameraViewWeb extends WebPlugin {
             }
             this.mediaRecorder = null;
             this.recordedChunks = [];
-            throw new Error(`Failed to start recording: ${this.formatError(err)}`);
+            throw new CameraViewError(`Failed to start recording: ${this.formatError(err)}`, this.mapRecordingStartErrorCode(err));
         }
     }
+    /**
+     * Maps a failure caught by `startRecording()`'s try/catch onto the closest-
+     * fitting `CameraErrorCode`, without altering the existing wrapped message.
+     *
+     * A `DOMException` here can only come from the microphone `getUserMedia`
+     * call, so it is classified with `kind: 'microphone'`. The two other
+     * distinguishable failures are plain `Error`s matched by message text.
+     */
+    mapRecordingStartErrorCode(err) {
+        if (err instanceof DOMException) {
+            return classifyGetUserMediaErrorCode(err, 'microphone');
+        }
+        if (err instanceof Error) {
+            if (err.message === 'No camera stream available') {
+                return 'CAMERA_UNAVAILABLE';
+            }
+            if (err.message === 'No supported video recording format found') {
+                return 'CONFIGURATION_FAILED';
+            }
+        }
+        return 'UNKNOWN_ERROR';
+    }
     /**
      * Stop the current video recording
      */
     async stopRecording() {
         if (!this.mediaRecorder) {
-            throw new Error('No recording is in progress');
+            throw new CameraViewError('No recording is in progress', 'NO_RECORDING_IN_PROGRESS');
+        }
+        // A stop is already pending. Reject this second call instead of
+        // overwriting the pending callbacks, which would orphan the first caller's
+        // promise forever.
+        if (this.recordingResolve || this.recordingReject) {
+            throw new CameraViewError('stopRecording() is already pending', 'UNKNOWN_ERROR');
         }
         return new Promise((resolve, reject) => {
             var _a;
@@ -288,45 +580,95 @@ export class CameraViewWeb extends WebPlugin {
      * Flip between front and back camera
      */
     async flipCamera() {
+        var _a;
         if (!__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f")) {
-            throw new Error('Camera is not running');
+            throw new CameraViewError('Camera is not running', 'SESSION_NOT_RUNNING');
+        }
+        // Flipping restarts the stream and stops the tracks the MediaRecorder is
+        // consuming, which would silently freeze an in-progress recording. Reject
+        // instead so the caller can stop recording first; the recording stays
+        // intact.
+        if (this.mediaRecorder && this.mediaRecorder.state !== 'inactive') {
+            throw new CameraViewError('Cannot flip camera while a recording is in progress', 'RECORDING_ALREADY_IN_PROGRESS');
         }
+        // The candidate facing mode, kept local until the new stream is actually
+        // live: `currentCamera` (and the previous stream) must not be touched
+        // before that point, or a failed re-acquisition below would leave the
+        // session state pointing at a camera that isn't running while the
+        // previous camera's tracks have already been stopped.
+        const nextCamera = this.currentCamera === 'user' ? 'environment' : 'user';
+        // Acquire the new-facing stream with the new facing mode, keeping the
+        // session's resolution/aspect-ratio constraints so the flipped stream
+        // honors the same contract as the one it replaces.
+        const constraints = {
+            video: Object.assign(Object.assign({}, this.sessionResolutionConstraints), { facingMode: nextCamera }),
+            audio: false,
+        };
+        let newStream;
         try {
-            // Switch current camera
-            this.currentCamera = this.currentCamera === 'user' ? 'environment' : 'user';
-            // Stop current stream
-            if (this.stream) {
-                this.stream.getTracks().forEach((track) => track.stop());
-            }
-            // Restart with new facing mode
-            const constraints = {
-                video: {
-                    facingMode: this.currentCamera,
-                },
-                audio: false,
-            };
-            this.stream = await navigator.mediaDevices.getUserMedia(constraints);
-            if (this.videoElement) {
-                this.videoElement.srcObject = this.stream;
-            }
+            newStream = await navigator.mediaDevices.getUserMedia(constraints);
         }
         catch (err) {
-            throw new Error(`Failed to flip camera: ${this.formatError(err)}`);
+            // Acquisition failed: `stream`/`currentCamera` haven't been touched, so
+            // the previous camera is still attached and running. Just surface the
+            // error. The only `getUserMedia` call in this method re-acquires the
+            // camera (never the microphone), so classify with kind: 'camera'.
+            throw new CameraViewError(`Failed to flip camera: ${this.formatError(err)}`, classifyGetUserMediaErrorCode(err, 'camera'));
+        }
+        // The new stream is live: safe to stop the previous stream's tracks and
+        // commit the flipped state.
+        (_a = this.stream) === null || _a === void 0 ? void 0 : _a.getTracks().forEach((track) => track.stop());
+        this.stream = newStream;
+        this.currentCamera = nextCamera;
+        if (this.videoElement) {
+            this.videoElement.srcObject = newStream;
+        }
+        // Re-apply the session's zoom level to the new stream through the normal
+        // setZoom() path - a flip otherwise silently drops native-zoom's applied
+        // constraint (reset on the fresh track) or leaves CSS-fallback's
+        // transform stale against the fresh element state. Best-effort: a zoom
+        // failure must not fail the flip itself.
+        try {
+            await this.setZoom({ level: this.currentZoom });
+        }
+        catch (err) {
+            console.warn('[CameraView] Failed to re-apply zoom after flipping camera', err);
         }
     }
     /**
-     * Get available camera devices
+     * Get available camera devices.
+     *
+     * Position detection prefers the `facingMode` capability of the active video
+     * track, since it is a standardized signal rather than a locale-dependent
+     * string. Every other device falls back to matching the English word "front"
+     * in `device.label` — which is empty for all devices until camera permission
+     * has been granted once, so the fallback resolves to `'back'` in that case.
      */
     async getAvailableDevices() {
+        var _a;
         try {
             const devices = await navigator.mediaDevices.enumerateDevices();
             const videoDevices = devices.filter((device) => device.kind === 'videoinput');
+            const activeTrack = this.getVideoTrack();
+            const activeDeviceId = activeTrack === null || activeTrack === void 0 ? void 0 : activeTrack.getSettings().deviceId;
+            const activeFacingMode = activeTrack && typeof activeTrack.getCapabilities === 'function'
+                ? (_a = activeTrack.getCapabilities().facingMode) === null || _a === void 0 ? void 0 : _a[0]
+                : undefined;
             return {
-                devices: videoDevices.map((device) => ({
-                    id: device.deviceId,
-                    name: device.label || `Camera ${device.deviceId.substring(0, 5)}`,
-                    position: device.label.toLowerCase().includes('front') ? 'front' : 'back',
-                })),
+                devices: videoDevices.map((device) => {
+                    const position = device.deviceId === activeDeviceId && activeFacingMode
+                        ? activeFacingMode === 'user'
+                            ? 'front'
+                            : 'back'
+                        : device.label.toLowerCase().includes('front')
+                            ? 'front'
+                            : 'back';
+                    return {
+                        id: device.deviceId,
+                        name: device.label || `Camera ${device.deviceId.substring(0, 5)}`,
+                        position,
+                    };
+                }),
             };
         }
         catch (err) {
@@ -335,31 +677,106 @@ export class CameraViewWeb extends WebPlugin {
         }
     }
     /**
-     * Get current zoom information (web has limited zoom support)
+     * Get current zoom information.
+     *
+     * When the active video track exposes a native `zoom` capability (Chromium
+     * on capable cameras), the real min/max/current are reported. Otherwise the
+     * simulated CSS-scale range is returned.
      */
     async getZoom() {
-        // Web has limited zoom capabilities in most browsers,
-        // we fake zoomin by scaling the video element
+        const track = this.getVideoTrack();
+        const capability = this.getNativeZoomCapability(track);
+        if (track && capability) {
+            const settings = track.getSettings();
+            return {
+                min: capability.min,
+                max: capability.max,
+                current: typeof settings.zoom === 'number' ? settings.zoom : this.currentZoom,
+            };
+        }
+        // No native zoom: report the simulated CSS-scale range.
         return {
-            min: 1.0,
-            max: 3.0,
+            min: SIMULATED_ZOOM_MIN,
+            max: SIMULATED_ZOOM_MAX,
             current: this.currentZoom,
         };
     }
     /**
-     * Set zoom level (limited support in web)
+     * Set the zoom level.
+     *
+     * Prefers real zoom via `track.applyConstraints({ advanced: [{ zoom }] })`
+     * when the browser exposes the native `zoom` capability, clamping to the
+     * reported range. Falls back to a CSS `transform: scale()` simulation
+     * otherwise.
      */
     async setZoom(options) {
-        // Store the requested zoom level
+        const track = this.getVideoTrack();
+        const capability = this.getNativeZoomCapability(track);
+        if (track && capability) {
+            const clamped = Math.max(capability.min, Math.min(options.level, capability.max));
+            await track.applyConstraints({ advanced: [{ zoom: clamped }] });
+            this.currentZoom = clamped;
+            this.usingNativeZoom = true;
+            // Clear any CSS transform left over from a previous fallback so the two
+            // zoom mechanisms can't stack.
+            if (this.videoElement) {
+                this.videoElement.style.transform = '';
+            }
+            return;
+        }
+        // CSS-transform fallback.
+        this.usingNativeZoom = false;
         this.currentZoom = options.level;
-        // Apply visual zoom using CSS transform when native zoom isn't supported
         if (this.videoElement) {
             this.videoElement.style.transition = options.ramp ? 'transform 0.2s ease-in-out' : 'none';
-            const scale = Math.max(1.0, Math.min(options.level, 3.0)); // Limit scale to reasonable bounds
-            this.videoElement.style.transform = `scale(${scale})`;
+            this.videoElement.style.transform = `scale(${this.getCssZoomScale()})`;
             this.videoElement.style.transformOrigin = 'center';
         }
     }
+    /**
+     * The video track backing the active stream, or `null`.
+     */
+    getVideoTrack() {
+        var _a, _b;
+        return (_b = (_a = this.stream) === null || _a === void 0 ? void 0 : _a.getVideoTracks()[0]) !== null && _b !== void 0 ? _b : null;
+    }
+    /**
+     * Reads the native `zoom` capability off a track, if the browser both
+     * supports `getCapabilities()` and exposes a usable `zoom` range on this
+     * device. Returns `null` when native zoom is unavailable (CSS fallback).
+     */
+    getNativeZoomCapability(track) {
+        if (!track || typeof track.getCapabilities !== 'function') {
+            return null;
+        }
+        const zoom = track.getCapabilities().zoom;
+        if (zoom && typeof zoom.min === 'number' && typeof zoom.max === 'number' && zoom.max > zoom.min) {
+            return zoom;
+        }
+        return null;
+    }
+    /**
+     * The effective CSS `transform: scale()` factor currently applied to the
+     * preview: `1` when native zoom is in use (no transform), otherwise
+     * `currentZoom` clamped to the simulated range. Used both to set the
+     * transform and to compensate captures for it.
+     */
+    getCssZoomScale() {
+        if (this.usingNativeZoom) {
+            return 1;
+        }
+        return Math.max(SIMULATED_ZOOM_MIN, Math.min(this.currentZoom, SIMULATED_ZOOM_MAX));
+    }
+    /**
+     * Set the focus/metering point (not supported in web).
+     *
+     * The `pointsOfInterest` media-track constraint has effectively no browser
+     * support, so this rejects with `unimplemented` rather than silently doing
+     * nothing. Left as a hook for a future implementation.
+     */
+    async setFocusPoint() {
+        throw this.unimplemented('Focus point control is not supported in the web implementation.');
+    }
     /**
      * Get current flash mode
      */
@@ -374,11 +791,16 @@ export class CameraViewWeb extends WebPlugin {
         return { flashModes: ['off'] };
     }
     /**
-     * Set flash mode (limited support in web)
+     * Set flash mode (limited support in web).
+     *
+     * Only `'off'` is supported on web; any other mode rejects rather than
+     * silently accepting a mode it cannot apply.
      */
     async setFlashMode(options) {
-        this.currentFlashMode = options.mode;
-        console.warn('Flash mode control is not fully supported in the web implementation');
+        if (options.mode !== 'off') {
+            throw this.unimplemented('Flash mode control is not supported in the web implementation.');
+        }
+        this.currentFlashMode = 'off';
     }
     /**
      * Check if torch is available (not supported in web)
@@ -388,11 +810,14 @@ export class CameraViewWeb extends WebPlugin {
         return { available: false };
     }
     /**
-     * Get torch mode (not supported in web)
+     * Get torch mode (not supported in web).
+     *
+     * Follows the documented contract for `getTorchMode()`: callers must check
+     * `isTorchAvailable()` first, which always reports `false` on web, so this throws
+     * rather than returning a fabricated "off" state.
      */
     async getTorchMode() {
-        // Torch is not supported in web implementation
-        return { enabled: false, level: 0.0 };
+        throw this.unimplemented('Torch control is not supported in web implementation.');
     }
     /**
      * Set torch mode (not supported in web)
@@ -405,35 +830,38 @@ export class CameraViewWeb extends WebPlugin {
      * Check camera and microphone permission without requesting
      */
     async checkPermissions() {
-        try {
-            // Use Permissions API if available
-            if (navigator.permissions) {
-                const [cameraResult, microphoneResult] = await Promise.all([
-                    navigator.permissions.query({ name: 'camera' }),
-                    navigator.permissions.query({ name: 'microphone' }),
-                ]);
-                return {
-                    camera: cameraResult.state === 'granted' ? 'granted' : cameraResult.state === 'denied' ? 'denied' : 'prompt',
-                    microphone: microphoneResult.state === 'granted'
-                        ? 'granted'
-                        : microphoneResult.state === 'denied'
-                            ? 'denied'
-                            : 'prompt',
-                };
+        const [camera, microphone] = await Promise.all([
+            this.checkSinglePermission('camera'),
+            this.checkSinglePermission('microphone'),
+        ]);
+        return { camera, microphone };
+    }
+    /**
+     * Resolves the current state of a single permission.
+     *
+     * Queried independently per permission name so one unsupported query (e.g.
+     * Firefox does not support querying `'microphone'`) rejects on its own
+     * instead of collapsing *both* permissions to `'prompt'`.
+     */
+    async checkSinglePermission(name) {
+        if (navigator.permissions) {
+            try {
+                const result = await navigator.permissions.query({ name: name });
+                return result.state === 'granted' ? 'granted' : result.state === 'denied' ? 'denied' : 'prompt';
+            }
+            catch (_a) {
+                // This permission name is not supported by the Permissions API in this
+                // browser; fall through to the best-effort fallback below instead of
+                // failing the other permission's check too.
             }
-            // If Permissions API is not available, fall back to checking the active stream
-            return {
-                camera: this.stream ? 'granted' : 'prompt',
-                microphone: 'prompt',
-            };
         }
-        catch (err) {
-            // If permissions API is not supported or fails
-            return {
-                camera: 'prompt',
-                microphone: 'prompt',
-            };
+        // If the Permissions API is unavailable/unsupported for this name, fall back to
+        // checking the active stream for camera; there is no equivalent signal for
+        // microphone without an active audio track, so it stays 'prompt'.
+        if (name === 'camera') {
+            return this.stream ? 'granted' : 'prompt';
         }
+        return 'prompt';
     }
     /**
      * Request camera and/or microphone permissions from the user.
@@ -478,70 +906,125 @@ export class CameraViewWeb extends WebPlugin {
      * Start barcode detection if supported
      */
     async startBarcodeDetection() {
+        var _a;
         const barcodeDetector = this.barcodeDetector;
         const videoElement = this.videoElement;
         if (!this.barcodeDetectionSupported || !barcodeDetector || !videoElement) {
             return;
         }
-        // Make sure video is fully loaded before starting detection
+        // Scope this loop to its own session. Aborting the previous controller
+        // (defensive - start() only calls in here once per session) and handing
+        // out a fresh signal means a stale detectFrame closure from an earlier
+        // session can never mistake a later session's #isRunning === true for
+        // its own "keep going" signal.
+        (_a = this.barcodeDetectionAbortController) === null || _a === void 0 ? void 0 : _a.abort();
+        const abortController = new AbortController();
+        this.barcodeDetectionAbortController = abortController;
+        const { signal } = abortController;
+        // Make sure video is fully loaded before starting detection. The wait
+        // settles - without starting detection - as soon as the session is
+        // stopped (`signal` aborts), and a timeout backstops the case where the
+        // video never fires `loadeddata` at all, so neither path leaves a
+        // dangling listener or a permanently pending promise.
         if (videoElement.readyState < 2) {
-            await new Promise((resolve) => {
-                const loadHandler = () => {
+            const videoReady = await new Promise((resolve) => {
+                const cleanup = () => {
                     videoElement.removeEventListener('loadeddata', loadHandler);
-                    resolve();
+                    signal.removeEventListener('abort', abortHandler);
+                    clearTimeout(timeoutId);
+                };
+                const loadHandler = () => {
+                    cleanup();
+                    resolve(true);
+                };
+                const abortHandler = () => {
+                    cleanup();
+                    resolve(false);
                 };
+                const timeoutId = setTimeout(() => {
+                    cleanup();
+                    resolve(false);
+                }, BARCODE_VIDEO_READY_TIMEOUT_MS);
                 videoElement.addEventListener('loadeddata', loadHandler);
+                signal.addEventListener('abort', abortHandler);
             });
+            if (!videoReady || signal.aborted) {
+                return;
+            }
+        }
+        if (signal.aborted) {
+            return;
         }
         // Add throttling to reduce CPU usage
         let lastDetectionTime = 0;
         const minTimeBetweenDetections = 100; // ms
+        // Dedupe state: timestamps of recently emitted barcodes keyed by value +
+        // type. A per-key map (rather than a single "last" slot) is required so
+        // multiple codes in frame can't alternate and defeat the suppression
+        // window. Closure-local, so it resets on every start().
+        const recentBarcodeEmitTimes = new Map();
         // Set up periodic frame analysis for barcode detection
         const detectFrame = async () => {
-            if (!__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f") || !videoElement || !barcodeDetector) {
+            var _a;
+            // `signal.aborted` is this loop's own session check: it stays true for
+            // this closure even if a rapid stop() -> start() flips #isRunning back
+            // to true for a *new* session before this frame runs. `#isRunning` is
+            // kept as a defensive secondary check.
+            if (signal.aborted || !__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f") || !videoElement || !barcodeDetector) {
                 return;
             }
-            const now = Date.now();
+            // Monotonic clock: a backward wall-clock jump must not extend the
+            // throttle or suppression windows arbitrarily.
+            const now = performance.now();
             if (now - lastDetectionTime >= minTimeBetweenDetections) {
                 try {
                     const barcodes = await barcodeDetector.detect(videoElement);
                     lastDetectionTime = now;
                     if (barcodes.length > 0) {
                         const barcode = barcodes[0];
-                        // Transform barcode coordinates using the utility function
-                        const boundingRect = transformBarcodeBoundingBox(barcode.boundingBox, videoElement);
-                        this.notifyListeners('barcodeDetected', {
-                            value: barcode.rawValue,
-                            type: barcode.format.toLowerCase(),
-                            boundingRect,
-                        });
+                        // Normalize the web BarcodeDetector format onto the shared BarcodeType
+                        // vocabulary. Fall back to the raw format for the few detector formats
+                        // that have no BarcodeType equivalent (e.g. 'unknown'); the emitted
+                        // `type` is therefore `BarcodeType | string`.
+                        const type = (_a = WEB_FORMAT_TO_BARCODE_TYPE[barcode.format]) !== null && _a !== void 0 ? _a : barcode.format;
+                        // Rate control: suppress re-emission of the same code (value + type)
+                        // within the suppression window. A genuinely new code has a different
+                        // key and emits immediately. Timestamps are tracked per key so
+                        // multiple codes in frame can't alternate and defeat the window.
+                        const barcodeKey = `${type}\u0000${barcode.rawValue}`;
+                        const lastEmit = recentBarcodeEmitTimes.get(barcodeKey);
+                        if (lastEmit === undefined || now - lastEmit >= BARCODE_SUPPRESSION_WINDOW_MS) {
+                            // Prune expired entries once the map grows, keeping it bounded
+                            // during long sessions that scan many different codes.
+                            if (recentBarcodeEmitTimes.size > BARCODE_DEDUPE_MAP_PRUNE_THRESHOLD) {
+                                for (const [key, emitTime] of recentBarcodeEmitTimes) {
+                                    if (now - emitTime >= BARCODE_SUPPRESSION_WINDOW_MS) {
+                                        recentBarcodeEmitTimes.delete(key);
+                                    }
+                                }
+                            }
+                            recentBarcodeEmitTimes.set(barcodeKey, now);
+                            // Transform barcode coordinates using the utility function,
+                            // accounting for the session's preview scale mode (cover crops,
+                            // fit letterboxes) so the rect lands over the on-screen barcode.
+                            const boundingRect = transformBarcodeBoundingBox(barcode.boundingBox, videoElement, this.sessionPreviewScaleMode);
+                            this.notifyListeners('barcodeDetected', {
+                                value: barcode.rawValue,
+                                type,
+                                boundingRect,
+                            });
+                        }
                     }
                 }
                 catch (err) {
                     console.error('Barcode detection error', err);
                 }
             }
-            if (__classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f")) {
-                requestAnimationFrame(detectFrame);
+            if (!signal.aborted && __classPrivateFieldGet(this, _CameraViewWeb_isRunning, "f")) {
+                this.barcodeAnimationFrameId = requestAnimationFrame(detectFrame);
             }
         };
-        requestAnimationFrame(detectFrame);
-    }
-    /**
-     * Clean up resources when the plugin is disposed
-     */
-    async handleOnDestroy() {
-        var _a;
-        await this.stop();
-        // Remove elements from DOM
-        if ((_a = this.videoElement) === null || _a === void 0 ? void 0 : _a.parentNode) {
-            this.videoElement.parentNode.removeChild(this.videoElement);
-            this.videoElement = null;
-        }
-        if (this.canvasElement) {
-            this.canvasElement = null;
-        }
-        this.barcodeDetector = null;
+        this.barcodeAnimationFrameId = requestAnimationFrame(detectFrame);
     }
     /**
      * Check if barcode detection is supported in this browser