@chipmobilesdk/rn-camera 0.1.0 → 0.2.0

package/src/core/controller.ts

@@ -47,7 +47,10 @@ export interface CameraControllerOptions {
 	 * Injectable so lifecycle rules are testable without an app (FR-015).
 	 */
 	readonly subscribeToAppState?: (listener: (status: AppStatus) => void) => () => void;
-	/** Set false to skip the initialization sweep (tests). Defaults to true. */
+	/**
+	 * Set false to skip the sweep that runs when the controller is first used
+	 * (tests). Defaults to true.
+	 */
 	readonly sweepOnInit?: boolean;
 }
 
@@ -72,7 +75,12 @@ export interface CameraController {
 
 	/** Marks the preview surface mounted, enabling foreground auto-restart. */
 	setSurfaceMounted(mounted: boolean): void;
-	/** Releases ports, listeners, and the camera. Safe to call twice. */
+	/**
+	 * Releases ports, listeners, and the camera. Safe to call twice. Afterwards
+	 * `start`, `resume`, `capture` and the permission and capability reads reject
+	 * with `notReady`; `stop`, `pause` and `cleanup` stay safe no-ops so teardown
+	 * code never has to check.
+	 */
 	dispose(): Promise<void>;
 }
 
@@ -112,6 +120,15 @@ export function createCameraController(
 	let torchEnabled = false;
 	let surfaceMounted = false;
 	let disposed = false;
+	let appStatus: AppStatus = 'active';
+	// Set only when backgrounding cut a running session short. Foregrounding
+	// used to restart from any idle or stopped session, so a camera the user had
+	// stopped — or never started, or no longer had permission for — came back on
+	// with the app.
+	let resumeOnForeground = false;
+	let releasing: Promise<void> | null = null;
+	let warnedUnmanaged = false;
+	let detach: (() => void) | null = null;
 
 	const capture = new SingleFlight();
 	const listeners = new Set<(state: CameraState) => void>();
@@ -140,7 +157,13 @@ export function createCameraController(
 	function emit(): void {
 		current = snapshot();
 		for (const listener of listeners) {
-			listener(current);
+			// One throwing subscriber must not starve the others, nor unwind into
+			// the transition that emitted — that left the controller half-updated.
+			try {
+				listener(current);
+			} catch {
+				logger.log({ type: 'session', code: 'listener-threw' });
+			}
 		}
 	}
 
@@ -173,6 +196,11 @@ export function createCameraController(
 
 	async function releaseCamera(): Promise<void> {
 		await forceTorchOff();
+		// Nothing to release. Going through STOP/STOPPED here turned an idle
+		// controller into `stopped` on every preview unmount.
+		if (session.status === 'idle' || session.status === 'stopped') {
+			return;
+		}
 		dispatch({ type: 'STOP' });
 		try {
 			await engine.stop();
@@ -182,31 +210,6 @@ export function createCameraController(
 		}
 	}
 
-	const unsubscribePermission = permissions.subscribe(next => {
-		permission = next;
-		logger.log({ type: 'permission', code: next });
-		emit();
-		// A revocation while running must tear the session down, not leave a
-		// frozen preview on screen (FR-007).
-		if (next !== 'granted' && session.status !== 'idle' && session.status !== 'stopped') {
-			releaseCamera().catch(() => undefined);
-		}
-	});
-
-	const unsubscribeAppState = (options.subscribeToAppState ?? defaultAppStateSubscribe)(
-		status => {
-			if (status === 'background') {
-				dispatch({ type: 'BACKGROUND' });
-				releaseCamera().catch(() => undefined);
-			} else {
-				dispatch({ type: 'FOREGROUND', surfaceMounted });
-				if (surfaceMounted && session.status === 'starting') {
-					startEngine().catch(() => undefined);
-				}
-			}
-		},
-	);
-
 	async function startEngine(startOptions: StartOptions = {}): Promise<void> {
 		try {
 			await engine.start({ cameraPosition: startOptions.cameraPosition ?? cameraPosition });
@@ -216,19 +219,110 @@ export function createCameraController(
 		}
 	}
 
-	// FR-029: sweep our own temp directory once per process, asynchronously, so
-	// it can never add latency to the capture path or the preview start.
-	if (store && options.sweepOnInit !== false) {
-		store
-			.sweep(ttlMs)
-			.then(removed => {
-				if (removed > 0) {
-					logger.log({ type: 'cleanup', code: `swept:${removed}` });
+	function resumeAfterForeground(): void {
+		if (disposed || appStatus !== 'active' || !resumeOnForeground) {
+			return;
+		}
+		resumeOnForeground = false;
+		if (!surfaceMounted || permission !== 'granted') {
+			return;
+		}
+		dispatch({ type: 'FOREGROUND', surfaceMounted });
+		if (session.status === 'starting') {
+			startEngine().catch(() => undefined);
+		}
+	}
+
+	function onAppState(status: AppStatus): void {
+		appStatus = status;
+		if (status === 'background') {
+			resumeOnForeground ||= session.status === 'active' || session.status === 'starting';
+			dispatch({ type: 'BACKGROUND' });
+			releasing = releaseCamera().catch(() => undefined);
+		} else {
+			// Wait for a release still in flight, or the restart lands on a
+			// `stopping` session and is dropped.
+			(releasing ?? Promise.resolve()).then(resumeAfterForeground).catch(() => undefined);
+		}
+	}
+
+	/**
+	 * Subscribes to permission and app-state changes and runs the sweep, on first
+	 * use rather than at construction. React may build a controller during a
+	 * render it then throws away (StrictMode does so on purpose); construction
+	 * that subscribed leaked a listener pair every time.
+	 */
+	function attach(): void {
+		if (detach || disposed) {
+			return;
+		}
+		const unsubscribePermission = permissions.subscribe(next => {
+			permission = next;
+			logger.log({ type: 'permission', code: next });
+			emit();
+			// A revocation while running must tear the session down, not leave a
+			// frozen preview on screen (FR-007).
+			if (next !== 'granted') {
+				resumeOnForeground = false;
+				if (session.status !== 'idle' && session.status !== 'stopped') {
+					releaseCamera().catch(() => undefined);
 				}
-			})
-			.catch(() => {
-				// A failed sweep must never block startup.
-			});
+			}
+		});
+		const unsubscribeAppState = (options.subscribeToAppState ?? defaultAppStateSubscribe)(
+			onAppState,
+		);
+		detach = () => {
+			unsubscribePermission();
+			unsubscribeAppState();
+		};
+
+		// FR-029: sweep our own temp directory once, asynchronously, so it can
+		// never add latency to the capture path or the preview start.
+		if (store && options.sweepOnInit !== false) {
+			store
+				.sweep(ttlMs)
+				.then(removed => {
+					if (removed > 0) {
+						logger.log({ type: 'cleanup', code: `swept:${removed}` });
+					}
+				})
+				.catch(() => {
+					// A failed sweep must never block startup.
+				});
+		}
+	}
+
+	/** Entry guard for operations that need a live controller. */
+	function live(operation: string): void {
+		if (disposed) {
+			throw new CameraError('notReady', `${operation}() called on a disposed camera controller`);
+		}
+		attach();
+	}
+
+	/**
+	 * Puts a package-temporary capture under the store so `cleanup()` and the
+	 * sweep can reach it. Never throws: the capture itself succeeded, and a file
+	 * the store cannot manage is still a usable photo.
+	 */
+	async function manage(image: CapturedImage): Promise<CapturedImage> {
+		if (image.ownership !== 'packageTemporary') {
+			return image;
+		}
+		if (store?.adopt) {
+			try {
+				return { ...image, uri: await store.adopt(image.uri) };
+			} catch {
+				logger.log({ type: 'cleanup', code: 'adopt-failed' });
+				return image;
+			}
+		}
+		if (!store?.owns(image.uri) && !warnedUnmanaged) {
+			warnedUnmanaged = true;
+			logger.log({ type: 'cleanup', code: store ? 'unmanaged:store-cannot-adopt' : 'unmanaged:no-store' });
+		}
+		return image;
 	}
 
 	const controller: CameraController = {
@@ -237,6 +331,10 @@ export function createCameraController(
 		},
 
 		subscribe(listener) {
+			if (disposed) {
+				return () => undefined;
+			}
+			attach();
 			listeners.add(listener);
 			return () => {
 				listeners.delete(listener);
@@ -244,12 +342,14 @@ export function createCameraController(
 		},
 
 		async getPermission() {
+			live('getPermission');
 			permission = await permissions.getStatus();
 			emit();
 			return permission;
 		},
 
 		async requestPermission() {
+			live('requestPermission');
 			permission = 'requesting';
 			emit();
 			permission = await permissions.request();
@@ -258,6 +358,7 @@ export function createCameraController(
 		},
 
 		async start(startOptions: StartOptions = {}) {
+			live('start');
 			if (permission !== 'granted') {
 				dispatch({ type: 'FAIL', code: 'permissionDenied' });
 				throw new CameraError('permissionDenied', 'Camera permission is not granted');
@@ -276,11 +377,15 @@ export function createCameraController(
 		},
 
 		async pause() {
+			if (disposed) {
+				return;
+			}
 			await forceTorchOff();
 			dispatch({ type: 'PAUSE' });
 		},
 
 		async resume() {
+			live('resume');
 			dispatch({ type: 'RESUME' });
 			if (session.status === 'starting') {
 				await startEngine();
@@ -288,10 +393,16 @@ export function createCameraController(
 		},
 
 		async stop() {
+			// An explicit stop is the user's decision; foregrounding must not undo it.
+			resumeOnForeground = false;
+			if (disposed) {
+				return;
+			}
 			await releaseCamera();
 		},
 
 		async capture(request: CaptureRequest = {}) {
+			live('capture');
 			const context: CaptureContext = {
 				engine,
 				sessionStatus: session.status,
@@ -304,18 +415,31 @@ export function createCameraController(
 			// request cannot block a subsequent legal one.
 			assertCaptureAllowed(context, request);
 
-			const result = await capture.run(async () => {
-				emit();
-				const raw = await engine.capture({
-					...request,
-					flashMode: request.flashMode ?? flashMode,
-					cameraPosition: request.cameraPosition ?? cameraPosition,
+			try {
+				const result = await capture.run(async () => {
+					emit();
+					const raw = await engine.capture({
+						...request,
+						flashMode: request.flashMode ?? flashMode,
+						cameraPosition: request.cameraPosition ?? cameraPosition,
+					});
+					return manage(finalizeResult(raw, request, context));
 				});
-				return finalizeResult(raw, request, context);
-			});
-			logger.log({ type: 'capture', code: 'succeeded' });
-			emit();
-			return result;
+				logger.log({ type: 'capture', code: 'succeeded' });
+				return result;
+			} catch (error) {
+				// The contract promises a CameraError; a raw native error carries
+				// no code to branch on and its message may hold a file path.
+				const failure = isCameraError(error)
+					? error
+					: new CameraError('captureFailed', 'The camera failed to capture a photo');
+				logger.log({ type: 'capture', code: failure.code, recoverable: failure.recoverable });
+				throw failure;
+			} finally {
+				// Without this a failed capture left `capturing: true` published
+				// until some unrelated change emitted again.
+				emit();
+			}
 		},
 
 		async cleanup(image: CapturedImage | string) {
@@ -334,6 +458,7 @@ export function createCameraController(
 		},
 
 		async getCapabilities() {
+			live('getCapabilities');
 			try {
 				capabilities = await engine.getCapabilities();
 			} catch {
@@ -357,6 +482,10 @@ export function createCameraController(
 		},
 
 		async setTorch(enabled: boolean) {
+			if (disposed && !enabled) {
+				return;
+			}
+			live('setTorch');
 			if (enabled) {
 				assertSupported(supportsTorch(capabilities), 'torch');
 			}
@@ -366,6 +495,9 @@ export function createCameraController(
 		},
 
 		setSurfaceMounted(mounted: boolean) {
+			if (disposed) {
+				return;
+			}
 			surfaceMounted = mounted;
 		},
 
@@ -374,8 +506,9 @@ export function createCameraController(
 				return;
 			}
 			disposed = true;
-			unsubscribePermission();
-			unsubscribeAppState();
+			resumeOnForeground = false;
+			detach?.();
+			detach = null;
 			await releaseCamera();
 			listeners.clear();
 		},

package/src/react/CameraPreview.tsx

@@ -18,6 +18,7 @@ import {
 
 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 {
@@ -46,10 +47,14 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 	children,
 }) => {
 	const [layout, setLayout] = useState<{ width: number; height: number } | null>(null);
-	const state = controller.state;
+	// 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).
+	// 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 () => {