@elizaos/capacitor-camera 2.0.0-beta.1 → 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+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,142 @@
+# @elizaos/capacitor-camera
+
+Capacitor plugin for camera preview, photo capture, and video recording. Works across web (via the `MediaDevices` API), iOS (via AVFoundation), and Android (via Camera2).
+
+## What it does
+
+- **Live preview** — stream a camera feed into any DOM element with configurable resolution, frame rate, and mirror mode.
+- **Photo capture** — snapshot a JPEG, PNG, or WebP image as base64 from the active preview, with optional resize and quality control.
+- **Video recording** — record video with optional audio, configurable bitrate, and automatic stop on max duration or file size.
+- **Camera control** — zoom, focus point, exposure point, flash/torch mode, white balance.
+- **Device enumeration** — list available cameras with capabilities (direction, zoom range, resolutions, frame rates).
+- **Permissions** — check and request camera + microphone permissions.
+- **Events** — subscribe to `frame`, `error`, and `recordingState` events.
+
+## Installation
+
+This is a Capacitor plugin. Add it to a Capacitor project:
+
+```bash
+npm install @elizaos/capacitor-camera
+npx cap sync
+```
+
+### iOS
+
+The plugin uses `AVFoundation`, `Photos`, and `UIKit`. Add the following keys to `Info.plist`:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Camera access is required for photo and video capture.</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>Microphone access is required for video recording with audio.</string>
+<key>NSPhotoLibraryAddUsageDescription</key>
+<string>Photo library access is required to save captured media.</string>
+```
+
+Minimum deployment target: iOS 15.0.
+
+### Android
+
+Add the following permissions to `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+```
+
+## Usage
+
+```typescript
+import { Camera } from "@elizaos/capacitor-camera";
+
+// Check and request permissions
+const status = await Camera.checkPermissions();
+if (status.camera !== "granted") {
+  await Camera.requestPermissions();
+}
+
+// List available cameras
+const { devices } = await Camera.getDevices();
+
+// Start a preview in a DOM element
+const container = document.getElementById("camera-container");
+const result = await Camera.startPreview({
+  element: container,
+  direction: "back",
+  resolution: { width: 1920, height: 1080 },
+  frameRate: 30,
+});
+
+// Capture a photo
+const photo = await Camera.capturePhoto({ quality: 90, format: "jpeg" });
+// photo.base64 contains the image data
+
+// Record video
+await Camera.startRecording({ audio: true, quality: "high", maxDuration: 60 });
+// ... later ...
+const video = await Camera.stopRecording();
+// video.path is a blob: URL on web, or a file path on native
+
+// Stop preview and release camera
+await Camera.stopPreview();
+```
+
+### Camera settings
+
+```typescript
+// Zoom (1.0 = no zoom)
+await Camera.setZoom({ zoom: 2.0 });
+
+// Manual focus / exposure (normalized 0–1 coordinates)
+await Camera.setFocusPoint({ x: 0.5, y: 0.5 });
+await Camera.setExposurePoint({ x: 0.5, y: 0.5 });
+
+// Batch settings update
+await Camera.setSettings({
+  settings: {
+    flash: "auto",
+    whiteBalance: "daylight",
+    focusMode: "continuous",
+  },
+});
+```
+
+### Events
+
+```typescript
+const frameHandle = await Camera.addListener("frame", (event) => {
+  console.log(event.timestamp, event.width, event.height);
+});
+
+const stateHandle = await Camera.addListener("recordingState", (state) => {
+  console.log(state.isRecording, state.duration, state.fileSize);
+});
+
+// Clean up
+await Camera.removeAllListeners();
+```
+
+## API
+
+Full TypeScript definitions are in `src/definitions.ts`. Key types:
+
+| Type | Description |
+|---|---|
+| `CameraDevice` | Device info: id, label, direction, capabilities |
+| `CameraPreviewOptions` | Options for `startPreview` |
+| `PhotoCaptureOptions` | Options for `capturePhoto` (quality, format, size, gallery save) |
+| `PhotoResult` | base64 image, format, dimensions, optional EXIF |
+| `VideoCaptureOptions` | Options for `startRecording` (quality, duration, size, audio, bitrate) |
+| `VideoResult` | Path (blob URL or file path), duration, dimensions, file size, mime type |
+| `CameraSettings` | flash, zoom, focusMode, exposureMode, exposureCompensation, whiteBalance |
+| `CameraPermissionStatus` | camera / microphone: `"granted"` \| `"denied"` \| `"prompt"`; photos additionally allows `"limited"` |
+
+## Platform notes
+
+- **Web:** Flash/torch is not controllable via the `MediaDevices` API on most desktop browsers. Manual focus and exposure require the browser/device to report `"manual"` capability. Video is recorded as a `blob:` URL using `MediaRecorder`; preferred codec order is `vp9+opus` → `vp8+opus` → `webm` → `mp4`.
+- **iOS:** AVFoundation-backed. Requires iOS 15.0+, Swift 5.9.
+- **Android:** Camera2 API-backed.
+- **Node (Electrobun desktop):** Supported via Electrobun native modules.
+

package/android/build.gradle

@@ -8,6 +8,16 @@ ext {
 }
 
 apply plugin: 'com.android.library'
+// Explicitly apply the Kotlin Android plugin. The kotlin-gradle-plugin is on
+// the root buildscript classpath, but without applying it here AGP 8.13 falls
+// back to its "built-in Kotlin" compile path (build/intermediates/
+// built_in_kotlinc), which compiles the .kt sources but does NOT bundle the
+// resulting .class files into the *release* library jar. The app's
+// :app:assembleRelease then links a library AAR with zero plugin classes, so
+// the Capacitor plugin (and any manifest-declared component) is absent from
+// the release dex. Applying the standard Kotlin plugin wires Kotlin
+// compilation into both the debug and release jar-bundling tasks.
+apply plugin: 'org.jetbrains.kotlin.android'
 android {
     namespace = "ai.eliza.plugins.camera"
     compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
@@ -26,8 +36,12 @@ android {
     }
 
     compileOptions {
-        sourceCompatibility JavaVersion.VERSION_17
-        targetCompatibility JavaVersion.VERSION_17
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+
+    kotlinOptions {
+        jvmTarget = "21"
     }
 
 }

package/dist/esm/web.d.ts

@@ -17,7 +17,6 @@ export declare class CameraWeb extends WebPlugin {
         devices: CameraDevice[];
     }>;
     private inferDirection;
-    private getDeviceCapabilities;
     startPreview(options: CameraPreviewOptions): Promise<CameraPreviewResult>;
     stopPreview(): Promise<void>;
     switchCamera(options: {
@@ -37,6 +36,7 @@ export declare class CameraWeb extends WebPlugin {
     setZoom(options: {
         zoom: number;
     }): Promise<void>;
+    private assertValidZoom;
     private applyZoom;
     setFocusPoint(options: {
         x: number;
@@ -46,6 +46,7 @@ export declare class CameraWeb extends WebPlugin {
         x: number;
         y: number;
     }): Promise<void>;
+    private assertNormalizedPoint;
     checkPermissions(): Promise<CameraPermissionStatus>;
     requestPermissions(): Promise<CameraPermissionStatus>;
     addListener(eventName: string, listenerFunc: (event: CameraEventData) => void): Promise<{

package/dist/esm/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB,KAAK,eAAe,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,mBAAmB,CAAC;AAYxB,qBAAa,SAAU,SAAQ,SAAS;IACtC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,sBAAsB,CAA+C;IAC7E,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAOrB;IACF,OAAO,CAAC,eAAe,CAGf;IAEF,UAAU,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IA8BxD,OAAO,CAAC,cAAc;YAmBR,qBAAqB;IAmE7B,YAAY,CAChB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC;IA6DzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B,YAAY,CAAC,OAAO,EAAE;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAe1B,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAoDjE,cAAc,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkF5D,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;IA8DrC,iBAAiB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAgBjD,WAAW,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,cAAc,CAAA;KAAE,CAAC;IAIpD,WAAW,CAAC,OAAO,EAAE;QACzB,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQX,OAAO,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAUzC,SAAS;IAwBjB,aAAa,CAAC,OAAO,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B/D,gBAAgB,CAAC,OAAO,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlE,gBAAgB,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAkCnD,kBAAkB,IAAI,OAAO,CAAC,sBAAsB,CAAC;IA+CrD,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAC7C,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAWrC,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzC,SAAS,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI;CAO1E"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB,KAAK,eAAe,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,mBAAmB,CAAC;AAiDxB,qBAAa,SAAU,SAAQ,SAAS;IACtC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,sBAAsB,CAA+C;IAC7E,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAOrB;IACF,OAAO,CAAC,eAAe,CAGf;IAEF,UAAU,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IAgCxD,OAAO,CAAC,cAAc;IAmBhB,YAAY,CAChB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC;IAoEzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB5B,YAAY,CAAC,OAAO,EAAE;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAe1B,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAsEjE,cAAc,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoF5D,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;IA8DrC,iBAAiB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAgBjD,WAAW,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,cAAc,CAAA;KAAE,CAAC;IAIpD,WAAW,CAAC,OAAO,EAAE;QACzB,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBX,OAAO,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,OAAO,CAAC,eAAe;YAQT,SAAS;IAwBjB,aAAa,CAAC,OAAO,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B/D,gBAAgB,CAAC,OAAO,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BxE,OAAO,CAAC,qBAAqB;IAgBvB,gBAAgB,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAkCnD,kBAAkB,IAAI,OAAO,CAAC,sBAAsB,CAAC;IA+CrD,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAC7C,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAWrC,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzC,SAAS,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI;CAO1E"}

package/dist/esm/web.js

@@ -6,6 +6,37 @@ const VIDEO_MIME_TYPES = [
     "video/mp4",
 ];
 const getSupportedMimeType = () => VIDEO_MIME_TYPES.find((m) => MediaRecorder.isTypeSupported(m)) ?? null;
+const getMediaDevices = () => {
+    if (!navigator.mediaDevices?.getUserMedia) {
+        throw new Error("Camera media devices API is not available");
+    }
+    return navigator.mediaDevices;
+};
+const assertPositiveFinite = (value, name) => {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${name} must be a positive finite number`);
+    }
+};
+const assertRecordingOptions = (options) => {
+    if (!options)
+        return;
+    if (options.quality !== undefined &&
+        !["low", "medium", "high", "highest"].includes(options.quality)) {
+        throw new Error("quality must be one of low, medium, high, or highest");
+    }
+    if (options.maxDuration !== undefined) {
+        assertPositiveFinite(options.maxDuration, "maxDuration");
+    }
+    if (options.maxFileSize !== undefined) {
+        assertPositiveFinite(options.maxFileSize, "maxFileSize");
+    }
+    if (options.bitrate !== undefined) {
+        assertPositiveFinite(options.bitrate, "bitrate");
+    }
+    if (options.frameRate !== undefined) {
+        assertPositiveFinite(options.frameRate, "frameRate");
+    }
+};
 export class CameraWeb extends WebPlugin {
     constructor() {
         super(...arguments);
@@ -29,27 +60,29 @@ export class CameraWeb extends WebPlugin {
         this.pluginListeners = [];
     }
     async getDevices() {
-        // enumerateDevices() returns device stubs without labels unless the user
-        // has already granted camera permission via a prior getUserMedia() call.
+        // enumerateDevices() returns unlabeled device records unless the user has
+        // already granted camera permission via a prior getUserMedia() call.
         // We intentionally do NOT call getUserMedia() here because it requires a
         // user gesture and would throw NotAllowedError if called programmatically.
-        const allDevices = await navigator.mediaDevices.enumerateDevices();
+        const mediaDevices = getMediaDevices();
+        if (!mediaDevices.enumerateDevices) {
+            throw new Error("Camera device enumeration is not available");
+        }
+        const allDevices = await mediaDevices.enumerateDevices();
         const videoDevices = allDevices.filter((d) => d.kind === "videoinput");
-        const devices = await Promise.all(videoDevices.map(async (device, index) => {
-            const capabilities = await this.getDeviceCapabilities(device.deviceId);
-            return {
-                deviceId: device.deviceId,
-                label: device.label || `Camera ${index + 1}`,
-                direction: this.inferDirection(device.label),
-                // Flash detection not available via MediaDevices API on web
-                hasFlash: capabilities?.hasFlash ?? false,
-                hasZoom: !!capabilities?.zoom,
-                maxZoom: capabilities?.zoom?.max ?? 1,
-                // Return actual capabilities or empty array to indicate unknown
-                supportedResolutions: capabilities?.resolutions ?? [],
-                supportedFrameRates: capabilities?.frameRates ?? [],
-            };
-        }));
+        const devices = await Promise.all(videoDevices.map(async (device, index) => ({
+            deviceId: device.deviceId,
+            label: device.label || `Camera ${index + 1}`,
+            direction: this.inferDirection(device.label),
+            // Capability probing requires getUserMedia(), which can prompt for
+            // camera permission. Enumeration stays prompt-free and reports
+            // unknown capabilities until preview/capture has explicit access.
+            hasFlash: false,
+            hasZoom: false,
+            maxZoom: 1,
+            supportedResolutions: [],
+            supportedFrameRates: [],
+        })));
         return { devices };
     }
     inferDirection(label) {
@@ -66,60 +99,17 @@ export class CameraWeb extends WebPlugin {
         }
         return "external";
     }
-    async getDeviceCapabilities(deviceId) {
-        let stream;
-        try {
-            stream = await navigator.mediaDevices.getUserMedia({
-                video: { deviceId: { exact: deviceId } },
-            });
+    async startPreview(options) {
+        if (!options?.element?.appendChild) {
+            throw new Error("Preview element is required");
         }
-        catch {
-            return null; // Device not accessible
+        if (options.resolution) {
+            assertPositiveFinite(options.resolution.width, "resolution.width");
+            assertPositiveFinite(options.resolution.height, "resolution.height");
         }
-        const track = stream.getVideoTracks()[0];
-        if (!track) {
-            stream.getTracks().forEach((t) => {
-                t.stop();
-            });
-            return null;
+        if (options.frameRate !== undefined) {
+            assertPositiveFinite(options.frameRate, "frameRate");
         }
-        const capabilities = track.getCapabilities ? track.getCapabilities() : {};
-        stream.getTracks().forEach((t) => {
-            t.stop();
-        });
-        const caps = capabilities;
-        // Build resolutions from actual device capabilities only
-        const resolutions = [];
-        if (caps.width?.max && caps.height?.max) {
-            resolutions.push({ width: caps.width.max, height: caps.height.max });
-            // Add common lower resolutions only if device supports them
-            if (caps.width.max >= 1280 && caps.height.max >= 720) {
-                resolutions.push({ width: 1280, height: 720 });
-            }
-            if (caps.width.max >= 640 && caps.height.max >= 480) {
-                resolutions.push({ width: 640, height: 480 });
-            }
-        }
-        // Build frameRates from actual device capabilities only
-        const frameRates = [];
-        if (caps.frameRate?.max) {
-            if (caps.frameRate.max >= 60)
-                frameRates.push(60);
-            if (caps.frameRate.max >= 30)
-                frameRates.push(30);
-            if (caps.frameRate.max >= 24)
-                frameRates.push(24);
-            if (caps.frameRate.max >= 15)
-                frameRates.push(15);
-        }
-        return {
-            zoom: caps.zoom,
-            resolutions: resolutions.length > 0 ? resolutions : undefined,
-            frameRates: frameRates.length > 0 ? frameRates : undefined,
-            hasFlash: caps.torch === true, // Torch capability indicates flash support
-        };
-    }
-    async startPreview(options) {
         await this.stopPreview();
         const constraints = {
             video: {
@@ -141,13 +131,9 @@ export class CameraWeb extends WebPlugin {
             },
             audio: false,
         };
-        // PERMISSIONS_MIGRATION: this getUserMedia() call triggers the OS
-        // camera-permission dialog implicitly. New flow probes via
-        // `cameraProber` from
-        // `packages/agent/src/services/permissions/probers/camera.ts` first,
-        // then asks the user, only then opens the stream. Will be retired by
-        // the chat-surface migration agent.
-        this.mediaStream = await navigator.mediaDevices.getUserMedia(constraints);
+        // Browser camera permission is requested by opening the stream. Native
+        // permission probing is handled outside this Capacitor web fallback.
+        this.mediaStream = await getMediaDevices().getUserMedia(constraints);
         this.previewElement = options.element;
         this.videoElement = document.createElement("video");
         this.videoElement.srcObject = this.mediaStream;
@@ -181,8 +167,10 @@ export class CameraWeb extends WebPlugin {
             });
             this.mediaStream = null;
         }
-        if (this.videoElement && this.previewElement) {
-            this.previewElement.removeChild(this.videoElement);
+        if (this.videoElement) {
+            if (this.previewElement?.contains(this.videoElement)) {
+                this.previewElement.removeChild(this.videoElement);
+            }
             this.videoElement = null;
         }
         this.previewElement = null;
@@ -208,8 +196,18 @@ export class CameraWeb extends WebPlugin {
         const settings = track.getSettings();
         const videoWidth = settings.width || this.videoElement.videoWidth;
         const videoHeight = settings.height || this.videoElement.videoHeight;
+        assertPositiveFinite(videoWidth, "videoWidth");
+        assertPositiveFinite(videoHeight, "videoHeight");
         const targetWidth = options?.width || videoWidth;
         const targetHeight = options?.height || videoHeight;
+        assertPositiveFinite(targetWidth, "width");
+        assertPositiveFinite(targetHeight, "height");
+        if (options?.quality !== undefined &&
+            (!Number.isFinite(options.quality) ||
+                options.quality < 0 ||
+                options.quality > 100)) {
+            throw new Error("quality must be a finite number between 0 and 100");
+        }
         const canvas = document.createElement("canvas");
         canvas.width = targetWidth;
         canvas.height = targetHeight;
@@ -232,7 +230,11 @@ export class CameraWeb extends WebPlugin {
             : format === "webp"
                 ? "image/webp"
                 : "image/jpeg";
-        const base64 = canvas.toDataURL(mimeType, quality).split(",")[1];
+        const dataUrl = canvas.toDataURL(mimeType, quality);
+        const base64 = dataUrl.split(",")[1];
+        if (!base64) {
+            throw new Error("Failed to encode captured photo");
+        }
         return {
             base64,
             format,
@@ -247,9 +249,10 @@ export class CameraWeb extends WebPlugin {
         if (this.isRecording) {
             throw new Error("Recording already in progress");
         }
+        assertRecordingOptions(options);
         let streamToRecord = this.mediaStream;
         if (options?.audio !== false) {
-            const audioStream = await navigator.mediaDevices.getUserMedia({
+            const audioStream = await getMediaDevices().getUserMedia({
                 audio: true,
             });
             streamToRecord = new MediaStream([
@@ -371,17 +374,28 @@ export class CameraWeb extends WebPlugin {
         return { settings: { ...this.currentSettings } };
     }
     async setSettings(options) {
+        if (!options?.settings || typeof options.settings !== "object") {
+            throw new Error("settings object is required");
+        }
+        if (options.settings.zoom !== undefined) {
+            const zoom = options.settings.zoom;
+            this.assertValidZoom(zoom);
+        }
         this.currentSettings = { ...this.currentSettings, ...options.settings };
         if (this.mediaStream && options.settings.zoom !== undefined) {
             await this.applyZoom(options.settings.zoom);
         }
     }
     async setZoom(options) {
-        if (!Number.isFinite(options.zoom) || options.zoom < 0) {
-            throw new Error(`Invalid zoom value: ${options.zoom}. Must be a non-negative finite number.`);
+        const zoom = options?.zoom;
+        this.assertValidZoom(zoom);
+        await this.applyZoom(zoom);
+        this.currentSettings.zoom = zoom;
+    }
+    assertValidZoom(zoom) {
+        if (typeof zoom !== "number" || !Number.isFinite(zoom) || zoom < 0) {
+            throw new Error(`Invalid zoom value: ${zoom}. Must be a non-negative finite number.`);
         }
-        await this.applyZoom(options.zoom);
-        this.currentSettings.zoom = options.zoom;
     }
     async applyZoom(zoom) {
         if (!this.mediaStream)
@@ -401,6 +415,7 @@ export class CameraWeb extends WebPlugin {
     async setFocusPoint(options) {
         if (!this.mediaStream)
             throw new Error("Preview not started");
+        this.assertNormalizedPoint(options, "focus point");
         const track = this.mediaStream.getVideoTracks()[0];
         if (!track)
             throw new Error("No video track available");
@@ -426,6 +441,7 @@ export class CameraWeb extends WebPlugin {
     async setExposurePoint(options) {
         if (!this.mediaStream)
             throw new Error("Preview not started");
+        this.assertNormalizedPoint(options, "exposure point");
         const track = this.mediaStream.getVideoTracks()[0];
         if (!track)
             throw new Error("No video track available");
@@ -448,6 +464,16 @@ export class CameraWeb extends WebPlugin {
             throw new Error(`Failed to set exposure point: ${e instanceof Error ? e.message : "unknown error"}`);
         }
     }
+    assertNormalizedPoint(options, name) {
+        if (!Number.isFinite(options?.x) ||
+            !Number.isFinite(options?.y) ||
+            options.x < 0 ||
+            options.x > 1 ||
+            options.y < 0 ||
+            options.y > 1) {
+            throw new Error(`${name} must use finite x/y values between 0 and 1`);
+        }
+    }
     async checkPermissions() {
         let cameraStatus = "prompt";
         let microphoneStatus = "prompt";
@@ -481,7 +507,7 @@ export class CameraWeb extends WebPlugin {
         let cameraStatus = "denied";
         let microphoneStatus = "denied";
         try {
-            const stream = await navigator.mediaDevices.getUserMedia({
+            const stream = await getMediaDevices().getUserMedia({
                 video: true,
                 audio: true,
             });
@@ -493,7 +519,7 @@ export class CameraWeb extends WebPlugin {
         }
         catch {
             try {
-                const videoStream = await navigator.mediaDevices.getUserMedia({
+                const videoStream = await getMediaDevices().getUserMedia({
                     video: true,
                 });
                 videoStream.getTracks().forEach((track) => {
@@ -505,7 +531,7 @@ export class CameraWeb extends WebPlugin {
                 cameraStatus = "denied";
             }
             try {
-                const audioStream = await navigator.mediaDevices.getUserMedia({
+                const audioStream = await getMediaDevices().getUserMedia({
                     audio: true,
                 });
                 audioStream.getTracks().forEach((track) => {