@chipmobilesdk/rn-camera 0.1.1 → 0.2.1

package/src/react/CameraPreview.tsx

@@ -1,120 +1,126 @@
-/**
- * Camera preview surface (FR-009..FR-013, UX-001, UX-003).
- *
- * Renders the camera feed and nothing else: no shutter button, no permission
- * copy, no error text, and no theme dependency. Consuming apps draw their own
- * controls and overlays through `children`, positioned with the geometry
- * reported by `onGeometryChange`.
- */
-
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
-import {
-	View,
-	type AccessibilityRole,
-	type LayoutChangeEvent,
-	type StyleProp,
-	type ViewStyle,
-} from 'react-native';
-
-import type { PreviewGeometry, ResizeMode } from '../config/types';
-import type { CameraController } from '../core/controller';
-import type { VisionCameraFeedProps } from './VisionCameraFeed';
-
-export interface CameraPreviewProps {
-	readonly controller: CameraController;
-	readonly resizeMode?: ResizeMode;
-	readonly style?: StyleProp<ViewStyle>;
-	readonly onGeometryChange?: (geometry: PreviewGeometry) => void;
-	/** Forwarded untouched; the package never overrides consumer a11y (UX-003). */
-	readonly accessibilityLabel?: string;
-	readonly accessibilityRole?: AccessibilityRole;
-	/** Overlay layer rendered above the feed. */
-	readonly children?: React.ReactNode;
-}
-
-/** Nominal capture dimensions until the engine reports the real format. */
-const DEFAULT_IMAGE_WIDTH = 1920;
-const DEFAULT_IMAGE_HEIGHT = 1080;
-
-export const CameraPreview: React.FC<CameraPreviewProps> = ({
-	controller,
-	resizeMode = 'cover',
-	style,
-	onGeometryChange,
-	accessibilityLabel,
-	accessibilityRole,
-	children,
-}) => {
-	const [layout, setLayout] = useState<{ width: number; height: number } | null>(null);
-	const state = controller.state;
-
-	// Tell the controller a surface exists so foregrounding can restart the
-	// session, and clear it on unmount so the camera is released (FR-016).
-	useEffect(() => {
-		controller.setSurfaceMounted(true);
-		return () => {
-			controller.setSurfaceMounted(false);
-			controller.stop().catch(() => undefined);
-		};
-	}, [controller]);
-
-	const onLayout = useCallback((event: LayoutChangeEvent) => {
-		const { width, height } = event.nativeEvent.layout;
-		setLayout({ width, height });
-	}, []);
-
-	const geometry = useMemo<PreviewGeometry | null>(() => {
-		if (!layout || layout.width === 0 || layout.height === 0) {
-			return null;
-		}
-		return {
-			imageWidth: DEFAULT_IMAGE_WIDTH,
-			imageHeight: DEFAULT_IMAGE_HEIGHT,
-			previewWidth: layout.width,
-			previewHeight: layout.height,
-			resizeMode,
-			orientation: 0,
-			isMirrored: state.cameraPosition === 'front',
-		};
-	}, [layout, resizeMode, state.cameraPosition]);
-
-	useEffect(() => {
-		if (geometry && onGeometryChange) {
-			onGeometryChange(geometry);
-		}
-	}, [geometry, onGeometryChange]);
-
-	const feedRequested = state.session === 'active' && state.permission === 'granted';
-
-	// Lazy require so importing this package never pulls in the native module
-	// for consumers that only use the pure utilities or the test adapter.
-	const Feed = useMemo(() => {
-		if (!feedRequested) {
-			return null;
-		}
-		try {
-			return require('./VisionCameraFeed')
-				.VisionCameraFeed as React.ComponentType<VisionCameraFeedProps>;
-		} catch {
-			return null;
-		}
-	}, [feedRequested]);
-
-	return (
-		<View
-			style={style}
-			onLayout={onLayout}
-			accessibilityLabel={accessibilityLabel}
-			accessibilityRole={accessibilityRole}
-			testID="rn-camera-preview">
-			{Feed ? (
-				<Feed
-					cameraPosition={state.cameraPosition}
-					resizeMode={resizeMode}
-					torchEnabled={state.torchEnabled}
-				/>
-			) : null}
-			{children}
-		</View>
-	);
-};
+/**
+ * Camera preview surface (FR-009..FR-013, UX-001, UX-003).
+ *
+ * Renders the camera feed and nothing else: no shutter button, no permission
+ * copy, no error text, and no theme dependency. Consuming apps draw their own
+ * controls and overlays through `children`, positioned with the geometry
+ * reported by `onGeometryChange`.
+ */
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+	View,
+	type AccessibilityRole,
+	type LayoutChangeEvent,
+	type StyleProp,
+	type ViewStyle,
+} from 'react-native';
+
+import type { PreviewGeometry, ResizeMode } from '../config/types';
+import type { CameraController } from '../core/controller';
+import { useCameraState } from './hooks';
+import type { VisionCameraFeedProps } from './VisionCameraFeed';
+
+export interface CameraPreviewProps {
+	readonly controller: CameraController;
+	readonly resizeMode?: ResizeMode;
+	readonly style?: StyleProp<ViewStyle>;
+	readonly onGeometryChange?: (geometry: PreviewGeometry) => void;
+	/** Forwarded untouched; the package never overrides consumer a11y (UX-003). */
+	readonly accessibilityLabel?: string;
+	readonly accessibilityRole?: AccessibilityRole;
+	/** Overlay layer rendered above the feed. */
+	readonly children?: React.ReactNode;
+}
+
+/** Nominal capture dimensions until the engine reports the real format. */
+const DEFAULT_IMAGE_WIDTH = 1920;
+const DEFAULT_IMAGE_HEIGHT = 1080;
+
+export const CameraPreview: React.FC<CameraPreviewProps> = ({
+	controller,
+	resizeMode = 'cover',
+	style,
+	onGeometryChange,
+	accessibilityLabel,
+	accessibilityRole,
+	children,
+}) => {
+	const [layout, setLayout] = useState<{ width: number; height: number } | null>(null);
+	// Subscribed, not read once: a plain `controller.state` read only refreshed
+	// when the parent happened to re-render, so the feed could stay unmounted
+	// after the session became active (or stay mounted after it stopped).
+	const state = useCameraState(controller);
+
+	// Tell the controller a surface exists so foregrounding can restart the
+	// session, and clear it on unmount so the camera is released (FR-016). Both
+	// calls are no-ops on an idle or disposed controller.
+	useEffect(() => {
+		controller.setSurfaceMounted(true);
+		return () => {
+			controller.setSurfaceMounted(false);
+			controller.stop().catch(() => undefined);
+		};
+	}, [controller]);
+
+	const onLayout = useCallback((event: LayoutChangeEvent) => {
+		const { width, height } = event.nativeEvent.layout;
+		setLayout({ width, height });
+	}, []);
+
+	const geometry = useMemo<PreviewGeometry | null>(() => {
+		if (!layout || layout.width === 0 || layout.height === 0) {
+			return null;
+		}
+		return {
+			imageWidth: DEFAULT_IMAGE_WIDTH,
+			imageHeight: DEFAULT_IMAGE_HEIGHT,
+			previewWidth: layout.width,
+			previewHeight: layout.height,
+			resizeMode,
+			orientation: 0,
+			isMirrored: state.cameraPosition === 'front',
+		};
+	}, [layout, resizeMode, state.cameraPosition]);
+
+	useEffect(() => {
+		if (geometry && onGeometryChange) {
+			onGeometryChange(geometry);
+		}
+	}, [geometry, onGeometryChange]);
+
+	const feedRequested = state.session === 'active' && state.permission === 'granted';
+
+	// Lazy require so importing this package never pulls in the native module
+	// for consumers that only use the pure utilities or the test adapter.
+	const Feed = useMemo(() => {
+		if (!feedRequested) {
+			return null;
+		}
+		try {
+			return require('./VisionCameraFeed')
+				.VisionCameraFeed as React.ComponentType<VisionCameraFeedProps>;
+		} catch {
+			return null;
+		}
+	}, [feedRequested]);
+
+	return (
+		<View
+			style={style}
+			onLayout={onLayout}
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole={accessibilityRole}
+			testID="rn-camera-preview"
+		>
+			{Feed ? (
+				<Feed
+					cameraPosition={state.cameraPosition}
+					resizeMode={resizeMode}
+					torchEnabled={state.torchEnabled}
+				/>
+			) : null}
+			{children}
+		</View>
+	);
+};

package/src/react/VisionCameraFeed.tsx

@@ -11,7 +11,7 @@
  * surface is mounted; it is published to the engine through `visionSurface`.
  */
 
-import React, { useEffect, useMemo } from 'react';
+import React, { useEffect, useMemo, useState } from 'react';
 import { StyleSheet } from 'react-native';
 import {
 	Camera,
@@ -28,8 +28,8 @@ import {
 	type CaptureRequest,
 	type ResizeMode,
 } from '../config/types';
-import { clampMaxDimension, clampQuality } from '../core/captureController';
-import { CameraError } from '../diagnostics/errors';
+import { DEFAULT_QUALITY } from '../core/captureController';
+import { CameraError, isCameraError } from '../diagnostics/errors';
 import { registerVisionSurface } from '../native/visionSurface';
 
 export interface VisionCameraFeedProps {
@@ -65,15 +65,22 @@ function toFilePath(uri: string): string {
 	return uri.startsWith('file://') ? uri.slice('file://'.length) : uri;
 }
 
+/** Native failures carry no code and may name a file path; never surface them raw. */
+function asCameraError(error: unknown, code: 'captureFailed' | 'storageFailure'): CameraError {
+	return isCameraError(error) ? error : new CameraError(code);
+}
+
 async function capturePhoto(
 	photoOutput: CameraPhotoOutput,
 	request: CaptureRequest,
 	cameraPosition: CameraPosition,
 ): Promise<CapturedImage> {
-	const photo = await photoOutput.capturePhoto(
-		{ flashMode: request.flashMode ?? 'off' },
-		{},
-	);
+	let photo: Awaited<ReturnType<CameraPhotoOutput['capturePhoto']>>;
+	try {
+		photo = await photoOutput.capturePhoto({ flashMode: request.flashMode ?? 'off' }, {});
+	} catch (error) {
+		throw asCameraError(error, 'captureFailed');
+	}
 	try {
 		// A destination makes the artifact app-owned, so it is written straight
 		// there; otherwise it goes to a temporary file (FR-026a).
@@ -81,17 +88,21 @@ async function capturePhoto(
 		if (request.destination) {
 			try {
 				await photo.saveToFileAsync(toFilePath(request.destination));
-			} catch (error) {
+			} catch {
 				throw new CameraError(
 					'storageFailure',
-					`Could not write the capture to the requested destination: ${
-						error instanceof Error ? error.message : 'unknown error'
-					}`,
+					'Could not write the capture to the requested destination',
 				);
 			}
 			path = request.destination;
 		} else {
-			path = await photo.saveToTemporaryFileAsync();
+			// VisionCamera's own temporary directory. The controller moves the file
+			// into the artifact store, when it has one, so cleanup can reach it.
+			try {
+				path = await photo.saveToTemporaryFileAsync();
+			} catch (error) {
+				throw asCameraError(error, 'storageFailure');
+			}
 		}
 
 		return {
@@ -104,8 +115,10 @@ async function capturePhoto(
 			// Ownership is decided by the controller from the original request;
 			// this value is overwritten there and is only a safe default.
 			ownership: request.destination ? 'appOwned' : 'packageTemporary',
-			effectiveQuality: clampQuality(request.quality),
-			effectiveMaxDimension: clampMaxDimension(request.maxDimension),
+			// Quality is fixed on the photo output, not per capture, and nothing here
+			// resizes. Report what was actually applied rather than echo the hints.
+			effectiveQuality: DEFAULT_QUALITY,
+			effectiveMaxDimension: unavailable(),
 			// The native layer reports neither back after a save, and guessing them
 			// would be worse than saying so (FR-022).
 			fileSize: unavailable(),
@@ -126,18 +139,27 @@ export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 	torchEnabled,
 }) => {
 	const device = useCameraDevice(cameraPosition);
-	const photoOutput = usePhotoOutput();
+	const photoOutput = usePhotoOutput({ quality: DEFAULT_QUALITY });
 
 	const surface = useMemo(
 		() => ({
-			capture: (request: CaptureRequest) =>
-				capturePhoto(photoOutput, request, cameraPosition),
+			capture: (request: CaptureRequest) => capturePhoto(photoOutput, request, cameraPosition),
 		}),
 		[photoOutput, cameraPosition],
 	);
 
 	useEffect(() => registerVisionSurface(surface), [surface]);
 
+	// VisionCamera applies `torchMode` on mount, before the camera is active, and
+	// leaves the native "Camera is not active" rejection unhandled — one red
+	// error per session start. Leave the prop unset until the torch is first
+	// turned on; after that 'off' must be sent explicitly to turn it back off.
+	const [torchTouched, setTorchTouched] = useState(false);
+	if (torchEnabled && !torchTouched) {
+		setTorchTouched(true);
+	}
+	const torchMode = torchEnabled ? 'on' : torchTouched ? 'off' : undefined;
+
 	if (!device) {
 		return null;
 	}
@@ -149,7 +171,7 @@ export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 			outputs={[photoOutput]}
 			isActive={true}
 			resizeMode={resizeMode}
-			torchMode={torchEnabled ? 'on' : 'off'}
+			torchMode={torchMode}
 		/>
 	);
 };

package/src/react/hooks.ts

@@ -1,44 +1,56 @@
-/**
- * React bindings for the camera controller.
- *
- * `useCameraController` owns the controller lifetime and disposes it on
- * unmount, which is what guarantees the camera is released when a screen goes
- * away (FR-016).
- */
-
-import { useEffect, useMemo, useRef, useState } from 'react';
-
-import type { CameraState } from '../config/types';
-import {
-	createCameraController,
-	type CameraController,
-	type CameraControllerOptions,
-} from '../core/controller';
-
-export function useCameraController(
-	options: CameraControllerOptions = {},
-): CameraController {
-	// Options usually arrive as a fresh object literal each render; capturing
-	// them in a ref keeps the controller stable for the component's lifetime.
-	const optionsRef = useRef(options);
-	const controller = useMemo(() => createCameraController(optionsRef.current), []);
-
-	useEffect(() => {
-		return () => {
-			controller.dispose().catch(() => undefined);
-		};
-	}, [controller]);
-
-	return controller;
-}
-
-export function useCameraState(controller: CameraController): CameraState {
-	const [state, setState] = useState<CameraState>(controller.state);
-
-	useEffect(() => {
-		setState(controller.state);
-		return controller.subscribe(setState);
-	}, [controller]);
-
-	return state;
-}
+/**
+ * React bindings for the camera controller.
+ *
+ * `useCameraController` owns the controller lifetime and disposes it on
+ * unmount, which is what guarantees the camera is released when a screen goes
+ * away (FR-016).
+ */
+
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+
+import type { CameraState } from '../config/types';
+import {
+	createCameraController,
+	type CameraController,
+	type CameraControllerOptions,
+} from '../core/controller';
+
+export function useCameraController(options: CameraControllerOptions = {}): CameraController {
+	// Options usually arrive as a fresh object literal each render; capturing
+	// them in a ref keeps the controller stable for the component's lifetime.
+	const optionsRef = useRef(options);
+	// Construction has no side effects (the controller subscribes on first use),
+	// so a controller React builds and discards here costs nothing.
+	const [controller, setController] = useState(() => createCameraController(optionsRef.current));
+	const disposedRef = useRef(new WeakSet<CameraController>());
+
+	useEffect(() => {
+		// StrictMode, and React's planned offscreen reuse, run the cleanup and then
+		// this effect again on the same component. Disposal is final, so the old
+		// controller cannot be revived; replace it. Before this, the screen kept a
+		// dead controller after the remount and the camera never started.
+		const disposed = disposedRef.current;
+		if (disposed.has(controller)) {
+			setController(createCameraController(optionsRef.current));
+			return undefined;
+		}
+		return () => {
+			disposed.add(controller);
+			controller.dispose().catch(() => undefined);
+		};
+	}, [controller]);
+
+	return controller;
+}
+
+export function useCameraState(controller: CameraController): CameraState {
+	// `subscribe` is a property of the controller object, so it is stable for the
+	// controller's lifetime, which is what useSyncExternalStore requires. The
+	// store read is tear-free, unlike the previous useState copy, which could
+	// miss a change made between render and effect.
+	return useSyncExternalStore(
+		controller.subscribe,
+		() => controller.state,
+		() => controller.state,
+	);
+}