@chipmobilesdk/rn-camera 0.2.0 → 0.3.0

package/src/react/CameraPreview.tsx

@@ -1,125 +1,137 @@
-/**
- * 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>
-	);
-};
+/**
+ * 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;
+}
+
+/** The feed module failed to load; distinct from `null`, which means not requested. */
+const FEED_UNAVAILABLE = 'unavailable' as const;
+
+/** 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 {
+			// Reported, not swallowed (CAM-21): the session fails with
+			// `cameraUnavailable` instead of showing a black preview.
+			return FEED_UNAVAILABLE;
+		}
+	}, [feedRequested]);
+
+	useEffect(() => {
+		if (Feed === FEED_UNAVAILABLE) {
+			controller.reportSurfaceUnavailable();
+		}
+	}, [Feed, controller]);
+
+	return (
+		<View
+			style={style}
+			onLayout={onLayout}
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole={accessibilityRole}
+			testID="rn-camera-preview"
+		>
+			{Feed && Feed !== FEED_UNAVAILABLE ? (
+				<Feed
+					cameraPosition={state.cameraPosition}
+					resizeMode={resizeMode}
+					torchEnabled={state.torchEnabled}
+				/>
+			) : null}
+			{children}
+		</View>
+	);
+};

package/src/react/VisionCameraFeed.tsx

@@ -1,178 +1,181 @@
-/**
- * The live VisionCamera surface rendered inside `CameraPreview`.
- *
- * Split into its own module so `CameraPreview` can require it lazily: consumers
- * that only use the pure utilities or the test adapter never load the native
- * module, while the hooks this component needs (`useCameraDevice`,
- * `usePhotoOutput`) can still be called normally.
- *
- * It also owns capture. In VisionCamera v5 the photo output belongs to the
- * session the `<Camera>` view configures, so the output only exists while this
- * surface is mounted; it is published to the engine through `visionSurface`.
- */
-
-import React, { useEffect, useMemo, useState } from 'react';
-import { StyleSheet } from 'react-native';
-import {
-	Camera,
-	useCameraDevice,
-	usePhotoOutput,
-	type CameraPhotoOutput,
-} from 'react-native-vision-camera';
-
-import {
-	known,
-	unavailable,
-	type CameraPosition,
-	type CapturedImage,
-	type CaptureRequest,
-	type ResizeMode,
-} from '../config/types';
-import { DEFAULT_QUALITY } from '../core/captureController';
-import { CameraError, isCameraError } from '../diagnostics/errors';
-import { registerVisionSurface } from '../native/visionSurface';
-
-export interface VisionCameraFeedProps {
-	readonly cameraPosition: CameraPosition;
-	readonly resizeMode: ResizeMode;
-	readonly torchEnabled: boolean;
-}
-
-const styles = StyleSheet.create({
-	feed: { flex: 1 },
-});
-
-const MIME_TYPES: Record<string, string> = {
-	jpeg: 'image/jpeg',
-	heic: 'image/heic',
-	dng: 'image/x-adobe-dng',
-	tiff: 'image/tiff',
-};
-
-/** VisionCamera reports orientation as a compass value; the contract wants degrees. */
-const ORIENTATION_DEGREES: Record<string, number> = {
-	up: 0,
-	right: 90,
-	down: 180,
-	left: 270,
-};
-
-function toFileUri(path: string): string {
-	return path.startsWith('file://') ? path : `file://${path}`;
-}
-
-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> {
-	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).
-		let path: string;
-		if (request.destination) {
-			try {
-				await photo.saveToFileAsync(toFilePath(request.destination));
-			} catch {
-				throw new CameraError(
-					'storageFailure',
-					'Could not write the capture to the requested destination',
-				);
-			}
-			path = request.destination;
-		} else {
-			// 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 {
-			uri: toFileUri(path),
-			mimeType: MIME_TYPES[photo.containerFormat] ?? 'application/octet-stream',
-			width: photo.width,
-			height: photo.height,
-			timestamp: Date.now(),
-			cameraPosition: request.cameraPosition ?? cameraPosition,
-			// 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',
-			// 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(),
-			orientation:
-				photo.orientation in ORIENTATION_DEGREES
-					? known(ORIENTATION_DEGREES[photo.orientation])
-					: unavailable(),
-		};
-	} finally {
-		// Large native buffers must not wait for the JS GC.
-		photo.dispose();
-	}
-}
-
-export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
-	cameraPosition,
-	resizeMode,
-	torchEnabled,
-}) => {
-	const device = useCameraDevice(cameraPosition);
-	const photoOutput = usePhotoOutput({ quality: DEFAULT_QUALITY });
-
-	const surface = useMemo(
-		() => ({
-			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;
-	}
-
-	return (
-		<Camera
-			style={styles.feed}
-			device={device}
-			outputs={[photoOutput]}
-			isActive={true}
-			resizeMode={resizeMode}
-			torchMode={torchMode}
-		/>
-	);
-};
+/**
+ * The live VisionCamera surface rendered inside `CameraPreview`.
+ *
+ * Split into its own module so `CameraPreview` can require it lazily: consumers
+ * that only use the pure utilities or the test adapter never load the native
+ * module, while the hooks this component needs (`useCameraDevice`,
+ * `usePhotoOutput`) can still be called normally.
+ *
+ * It also owns capture. In VisionCamera v5 the photo output belongs to the
+ * session the `<Camera>` view configures, so the output only exists while this
+ * surface is mounted; it is published to the engine through `visionSurface`.
+ */
+
+import React, { useEffect, useMemo, useState } from 'react';
+import { StyleSheet } from 'react-native';
+import {
+	Camera,
+	useCameraDevice,
+	usePhotoOutput,
+	type CameraPhotoOutput,
+} from 'react-native-vision-camera';
+
+import {
+	known,
+	unavailable,
+	type CameraPosition,
+	type CapturedImage,
+	type CaptureRequest,
+	type Maybe,
+	type ResizeMode,
+} from '../config/types';
+import { DEFAULT_QUALITY } from '../core/captureController';
+import { CameraError, isCameraError } from '../diagnostics/errors';
+import { registerVisionSurface } from '../native/visionSurface';
+
+export interface VisionCameraFeedProps {
+	readonly cameraPosition: CameraPosition;
+	readonly resizeMode: ResizeMode;
+	readonly torchEnabled: boolean;
+}
+
+const styles = StyleSheet.create({
+	feed: { flex: 1 },
+});
+
+const MIME_TYPES: Record<string, string> = {
+	jpeg: 'image/jpeg',
+	heic: 'image/heic',
+	dng: 'image/x-adobe-dng',
+	tiff: 'image/tiff',
+};
+
+/** VisionCamera reports orientation as a compass value; the contract wants degrees. */
+const ORIENTATION_DEGREES: Record<string, number> = {
+	up: 0,
+	right: 90,
+	down: 180,
+	left: 270,
+};
+
+function orientationOf(orientation: string): Maybe<number> {
+	const degrees = ORIENTATION_DEGREES[orientation];
+	return degrees === undefined ? unavailable() : known(degrees);
+}
+
+function toFileUri(path: string): string {
+	return path.startsWith('file://') ? path : `file://${path}`;
+}
+
+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> {
+	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).
+		let path: string;
+		if (request.destination) {
+			try {
+				await photo.saveToFileAsync(toFilePath(request.destination));
+			} catch {
+				throw new CameraError(
+					'storageFailure',
+					'Could not write the capture to the requested destination',
+				);
+			}
+			path = request.destination;
+		} else {
+			// 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 {
+			uri: toFileUri(path),
+			mimeType: MIME_TYPES[photo.containerFormat] ?? 'application/octet-stream',
+			width: photo.width,
+			height: photo.height,
+			timestamp: Date.now(),
+			cameraPosition: request.cameraPosition ?? cameraPosition,
+			// 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',
+			// 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(),
+			orientation: orientationOf(photo.orientation),
+		};
+	} finally {
+		// Large native buffers must not wait for the JS GC.
+		photo.dispose();
+	}
+}
+
+export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
+	cameraPosition,
+	resizeMode,
+	torchEnabled,
+}) => {
+	const device = useCameraDevice(cameraPosition);
+	const photoOutput = usePhotoOutput({ quality: DEFAULT_QUALITY });
+
+	const surface = useMemo(
+		() => ({
+			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;
+	}
+
+	return (
+		<Camera
+			style={styles.feed}
+			device={device}
+			outputs={[photoOutput]}
+			isActive={true}
+			resizeMode={resizeMode}
+			// Left unset until the app first touches the torch, so the device's own default stands.
+			{...(torchMode === undefined ? {} : { torchMode })}
+		/>
+	);
+};