capacitor-camera-view 2.4.0 → 3.0.0

package/dist/esm/web.d.ts

@@ -1,6 +1,94 @@
 import { WebPlugin } from '@capacitor/core';
-import type { CameraSessionConfiguration, CameraViewPlugin, CameraPermissionType, GetAvailableDevicesResponse, GetFlashModeResponse, GetSupportedFlashModesResponse, GetTorchModeResponse, GetZoomResponse, IsTorchAvailableResponse, IsRunningResponse, PermissionStatus, CaptureResponse, FlashMode, CaptureOptions, VideoRecordingOptions, VideoRecordingResponse, BarcodeType } from './definitions';
-export declare const BARCODE_TYPE_TO_WEB_FORMAT: Readonly<Record<BarcodeType, BarcodeFormat | null>>;
+import type { CameraSessionConfiguration, CameraViewPlugin, CameraErrorCode, CameraPermissionType, GetAvailableDevicesResponse, GetFlashModeResponse, GetSupportedFlashModesResponse, GetTorchModeResponse, GetZoomResponse, IsTorchAvailableResponse, IsRunningResponse, PermissionStatus, CaptureResponse, FlashMode, CaptureOptions, VideoRecordingOptions, VideoRecordingResponse, BarcodeType } from './definitions';
+/**
+ * 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 declare 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 declare 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 declare 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 declare const DEFAULT_IDEAL_CAPTURE_WIDTH = 1920;
+export declare 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 declare const SIMULATED_ZOOM_MIN = 1;
+export declare const SIMULATED_ZOOM_MAX = 3;
+export declare 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";
+    itf14: "itf";
+    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 declare const WEB_FORMAT_TO_BARCODE_TYPE: Readonly<Partial<Record<BarcodeFormat, BarcodeType>>>;
+/**
+ * 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 declare class CameraViewError extends Error {
+    readonly code: CameraErrorCode;
+    constructor(message: string, code: CameraErrorCode);
+}
+/**
+ * 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 declare function classifyGetUserMediaErrorCode(err: unknown, kind: 'camera' | 'microphone'): CameraErrorCode;
 /**
  * Web implementation of the CameraViewPlugin.
  * Optimized for performance and battery efficiency.
@@ -12,9 +100,15 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
     private stream;
     private currentCamera;
     private currentZoom;
+    private usingNativeZoom;
     private currentFlashMode;
+    private sessionAspectRatio;
+    private sessionPreviewScaleMode;
+    private sessionResolutionConstraints;
     private barcodeDetectionSupported;
     private barcodeDetector;
+    private barcodeDetectionAbortController;
+    private barcodeAnimationFrameId;
     private mediaRecorder;
     private recordedChunks;
     private recordingAudioTrack;
@@ -25,6 +119,26 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
      * Start the camera with the given configuration
      */
     start(options?: CameraSessionConfiguration): Promise<void>;
+    /**
+     * 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.
+     */
+    private buildResolutionConstraints;
+    /**
+     * 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`.
+     */
+    private mapStartAcquisitionError;
     /**
      * Stop the camera and release resources
      */
@@ -37,15 +151,28 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
      * Capture a photo using the camera and return it as a base64-encoded JPEG image.
      * Preserves what the user actually sees in the UI, including cropping from object-fit: cover.
      */
-    capture<T extends CaptureOptions>(options: T): Promise<CaptureResponse<T>>;
+    capture<T extends CaptureOptions = CaptureOptions & {
+        saveToFile?: undefined;
+    }>(options?: T): Promise<CaptureResponse<T>>;
     /**
      * Web implementation already uses images from the video stream, so this is the same as `capture()`
      */
-    captureSample<T extends CaptureOptions>(options: T): Promise<CaptureResponse<T>>;
+    captureSample<T extends CaptureOptions = CaptureOptions & {
+        saveToFile?: undefined;
+    }>(options?: T): Promise<CaptureResponse<T>>;
     /**
      * Start recording video using MediaRecorder API
      */
     startRecording(options?: VideoRecordingOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    private mapRecordingStartErrorCode;
     /**
      * Stop the current video recording
      */
@@ -55,20 +182,60 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
      */
     flipCamera(): Promise<void>;
     /**
-     * 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.
      */
     getAvailableDevices(): Promise<GetAvailableDevicesResponse>;
     /**
-     * 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.
      */
     getZoom(): Promise<GetZoomResponse>;
     /**
-     * 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.
      */
     setZoom(options: {
         level: number;
         ramp?: boolean;
     }): Promise<void>;
+    /**
+     * The video track backing the active stream, or `null`.
+     */
+    private getVideoTrack;
+    /**
+     * 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).
+     */
+    private getNativeZoomCapability;
+    /**
+     * 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.
+     */
+    private getCssZoomScale;
+    /**
+     * 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.
+     */
+    setFocusPoint(): Promise<void>;
     /**
      * Get current flash mode
      */
@@ -78,7 +245,10 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
      */
     getSupportedFlashModes(): Promise<GetSupportedFlashModesResponse>;
     /**
-     * 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.
      */
     setFlashMode(options: {
         mode: FlashMode;
@@ -88,7 +258,11 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
      */
     isTorchAvailable(): Promise<IsTorchAvailableResponse>;
     /**
-     * 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.
      */
     getTorchMode(): Promise<GetTorchModeResponse>;
     /**
@@ -99,6 +273,14 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
      * Check camera and microphone permission without requesting
      */
     checkPermissions(): Promise<PermissionStatus>;
+    /**
+     * 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'`.
+     */
+    private checkSinglePermission;
     /**
      * Request camera and/or microphone permissions from the user.
      * By default, only camera permission is requested.
@@ -110,10 +292,6 @@ export declare class CameraViewWeb extends WebPlugin implements CameraViewPlugin
      * Start barcode detection if supported
      */
     private startBarcodeDetection;
-    /**
-     * Clean up resources when the plugin is disposed
-     */
-    handleOnDestroy(): Promise<void>;
     /**
      * Check if barcode detection is supported in this browser
      */