@chipmobilesdk/rn-camera 0.3.0 → 0.4.0

package/src/core/sessionRuntime.ts

@@ -0,0 +1,242 @@
+/**
+ * The session's own I/O: starting it, waiting for frames, releasing it, and
+ * following the app in and out of the foreground.
+ *
+ * Split out of `controller.ts`, which had grown to hold three jobs at once:
+ * publishing state, running the session, and serving the public API. The
+ * decisions still live in `sessionMachine` (pure); this is the part that
+ * actually awaits the engine, and the controller composes it.
+ *
+ * It reads and writes the controller's state through `SessionContext` rather
+ * than owning it: one snapshot reaches subscribers, whichever part of the
+ * controller changed it.
+ */
+
+import type { StartOptions } from '../config/types';
+import { isCameraError, type CameraErrorCode } from '../diagnostics/errors';
+import type { CameraLogger } from '../diagnostics/logger';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { SurfaceInfo } from '../native/visionSurface';
+import type { SessionEvent, SessionSnapshot } from './sessionMachine';
+
+/** What the runtime needs from the controller that owns the state. */
+export interface SessionContext {
+	readonly engine: CameraEngine;
+	readonly logger: CameraLogger;
+	/** How long to wait for a preview surface to report frames. */
+	readonly startTimeoutMs: number;
+	readonly scheduler: {
+		setTimeout(callback: () => void, ms: number): unknown;
+		clearTimeout(handle: unknown): void;
+	};
+	session(): SessionSnapshot;
+	dispatch(event: SessionEvent): void;
+	emit(): void;
+	cameraPosition(): 'front' | 'back';
+	setCameraPosition(position: 'front' | 'back'): void;
+	torchEnabled(): boolean;
+	setTorchEnabled(enabled: boolean): void;
+	surfaceMounted(): boolean;
+	permissionGranted(): boolean;
+	disposed(): boolean;
+}
+
+export interface SessionRuntime {
+	/** Starts the engine and, where the surface owns the session, waits for frames. */
+	start(options?: StartOptions): Promise<void>;
+	/** Turns the torch off and releases the camera. Safe from any state. */
+	release(): Promise<void>;
+	/** Torch off, whatever the session is doing. */
+	forceTorchOff(): Promise<void>;
+	/** The app went to the background or came back. */
+	onAppState(status: 'active' | 'background'): void;
+	/** The preview reported frames; carries what the mounted device turned out to be. */
+	reportSurfaceStarted(info: SurfaceInfo): void;
+	/** The preview's own session failed, or the OS took the camera. */
+	reportSurfaceFailed(code: CameraErrorCode): void;
+	/** The engine lost the camera: another app, a call, a disconnected device. */
+	onInterruption(code: CameraErrorCode): void;
+	/** What the surface last reported, for the published state. */
+	surfaceInfo(): SurfaceInfo | null;
+	/** Set when the app foregrounds with a surface mounted, so the session restarts. */
+	armResumeOnForeground(): void;
+	/** A release still in flight, so a restart can wait for it. */
+	pending(): Promise<void> | undefined;
+}
+
+export function createSessionRuntime(context: SessionContext): SessionRuntime {
+	let surfaceInfo: SurfaceInfo | null = null;
+	/** Resolved by the surface's own report, or by the start timeout. */
+	let pendingStart: { settle(): void; fail(code: CameraErrorCode): void } | null = null;
+	let appStatus: 'active' | 'background' = 'active';
+	let resumeOnForeground = false;
+	let releasing: Promise<void> | undefined;
+
+	/** Torch must never survive leaving the active state (FR-034b). */
+	async function forceTorchOff(): Promise<void> {
+		if (!context.torchEnabled()) {
+			return;
+		}
+		context.setTorchEnabled(false);
+		try {
+			await context.engine.setTorch(false);
+		} catch {
+			// Torch-off is best effort; the session is going away regardless.
+		}
+		context.emit();
+	}
+
+	async function release(): Promise<void> {
+		await forceTorchOff();
+		// Nothing to release. Going through STOP/STOPPED here turned an idle
+		// controller into `stopped` on every preview unmount.
+		const status = context.session().status;
+		if (status === 'idle' || status === 'stopped') {
+			return;
+		}
+		context.dispatch({ type: 'STOP' });
+		try {
+			await context.engine.stop();
+			context.dispatch({ type: 'STOPPED' });
+		} catch (error) {
+			context.dispatch({
+				type: 'FAIL',
+				code: isCameraError(error) ? error.code : 'captureFailed',
+			});
+		}
+	}
+
+	/**
+	 * Waits for the mounted preview to report frames.
+	 *
+	 * `engine.start()` only confirms a device exists for the VisionCamera
+	 * adapter: the session belongs to the `<Camera>` view. Calling the session
+	 * active there made `capture()` right after `start()` fail with `notReady`,
+	 * and a camera that never produced a frame left the session in `starting`
+	 * forever (CAM-08).
+	 */
+	function awaitSurfaceStart(): Promise<void> {
+		return new Promise<void>(resolve => {
+			const timer = context.scheduler.setTimeout(() => {
+				if (pendingStart) {
+					pendingStart = null;
+					context.dispatch({ type: 'START_TIMEOUT' });
+					resolve();
+				}
+			}, context.startTimeoutMs);
+			const finish = () => {
+				context.scheduler.clearTimeout(timer);
+				pendingStart = null;
+				resolve();
+			};
+			pendingStart = {
+				settle: () => {
+					context.dispatch({ type: 'STARTED' });
+					finish();
+				},
+				fail: code => {
+					context.dispatch({ type: 'FAIL', code });
+					finish();
+				},
+			};
+		});
+	}
+
+	async function start(options: StartOptions = {}): Promise<void> {
+		try {
+			await context.engine.start({
+				cameraPosition: options.cameraPosition ?? context.cameraPosition(),
+			});
+		} catch (error) {
+			context.dispatch({
+				type: 'FAIL',
+				code: isCameraError(error) ? error.code : 'cameraUnavailable',
+			});
+			return;
+		}
+		if (context.engine.awaitsSurfaceStart !== true || !context.surfaceMounted()) {
+			// The engine owns its session, or there is no preview to wait for.
+			context.dispatch({ type: 'STARTED' });
+			return;
+		}
+		await awaitSurfaceStart();
+	}
+
+	function resumeAfterForeground(): void {
+		if (context.disposed() || appStatus !== 'active' || !resumeOnForeground) {
+			return;
+		}
+		resumeOnForeground = false;
+		if (!context.surfaceMounted() || !context.permissionGranted()) {
+			return;
+		}
+		context.dispatch({ type: 'FOREGROUND', surfaceMounted: true });
+		if (context.session().status === 'starting') {
+			start().catch(() => undefined);
+		}
+	}
+
+	return {
+		start,
+		release,
+		forceTorchOff,
+
+		onAppState(status) {
+			appStatus = status;
+			if (status === 'background') {
+				const running = context.session().status;
+				resumeOnForeground ||= running === 'active' || running === 'starting';
+				context.dispatch({ type: 'BACKGROUND' });
+				releasing = release().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);
+			}
+		},
+
+		reportSurfaceStarted(info) {
+			surfaceInfo = info;
+			if (info.cameraPosition !== context.cameraPosition()) {
+				// The device that mounted is the one taking the photos.
+				context.setCameraPosition(info.cameraPosition);
+			}
+			if (pendingStart) {
+				pendingStart.settle();
+			} else if (context.session().status === 'starting') {
+				context.dispatch({ type: 'STARTED' });
+			} else {
+				context.emit();
+			}
+		},
+
+		reportSurfaceFailed(code) {
+			if (pendingStart) {
+				pendingStart.fail(code);
+				return;
+			}
+			context.dispatch({ type: 'FAIL', code });
+		},
+
+		onInterruption(code) {
+			context.logger.log({ type: 'session', code });
+			if (pendingStart) {
+				pendingStart.fail(code);
+				return;
+			}
+			const status = context.session().status;
+			if (status !== 'idle' && status !== 'stopped') {
+				context.dispatch({ type: 'FAIL', code });
+				release().catch(() => undefined);
+			}
+		},
+
+		surfaceInfo: () => surfaceInfo,
+
+		armResumeOnForeground() {
+			resumeOnForeground = false;
+		},
+
+		pending: () => releasing,
+	};
+}

package/src/index.ts

@@ -39,7 +39,9 @@ export { createCameraController, DEFAULT_TEMPORARY_TTL_MS } from './core/control
 export type { AppStatus, CameraController, CameraControllerOptions } from './core/controller';
 
 // Ports + default adapters
-export type { CameraEngine, EngineOptions } from './native/cameraEngine';
+export type { CameraEngine } from './native/cameraEngine';
+export type { SurfaceInfo, SurfaceRegistry, VisionSurface } from './native/visionSurface';
+export { createSurfaceRegistry } from './native/visionSurface';
 export { createVisionCameraEngine } from './native/cameraEngine';
 export type { PermissionPort } from './permissions/permissionPort';
 export { createVisionCameraPermissions } from './permissions/permissionPort';

package/src/native/cameraEngine.ts

@@ -21,8 +21,9 @@ import type {
 	CaptureRequest,
 	StartOptions,
 } from '../config/types';
+import type { CameraErrorCode } from '../diagnostics/errors';
 import { CameraError } from '../diagnostics/errors';
-import { getActiveVisionSurface } from './visionSurface';
+import { createSurfaceRegistry, type VisionSurface } from './visionSurface';
 
 export interface CameraEngine {
 	start(options: StartOptions): Promise<void>;
@@ -30,11 +31,24 @@ export interface CameraEngine {
 	capture(request: CaptureRequest): Promise<CapturedImage>;
 	setTorch(enabled: boolean): Promise<void>;
 	getCapabilities(): Promise<CapabilityProfile>;
-}
-
-export interface EngineOptions {
-	/** Overrides device discovery. Primarily an escape hatch for diagnostics. */
-	readonly preferredPosition?: 'front' | 'back';
+	/**
+	 * True when `start()` only prepares the engine and the session becomes
+	 * active once a mounted preview surface reports frames. The controller then
+	 * waits for that report instead of calling the session active immediately,
+	 * and times out rather than sitting in `starting` forever (CAM-08).
+	 */
+	readonly awaitsSurfaceStart?: boolean;
+	/**
+	 * Attaches the mounted preview surface this engine captures through.
+	 * Returns the detach function. Engines that own their own session omit it.
+	 */
+	attachSurface?(surface: VisionSurface): () => void;
+	/**
+	 * The engine lost the camera: another app took it, a call came in, the
+	 * device was disconnected. The controller tears the session down with this
+	 * code rather than leaving a frozen preview (CAM-19).
+	 */
+	subscribeToInterruptions?(listener: (code: CameraErrorCode) => void): () => void;
 }
 
 /** The subset of VisionCamera's `CameraDevice` this adapter reads. */
@@ -49,7 +63,9 @@ interface DiscoveredDevice {
  * component, so this adapter owns capability discovery while `CameraPreview`
  * owns the rendered surface and the photo output that capture runs through.
  */
-export function createVisionCameraEngine(_options: EngineOptions = {}): CameraEngine {
+export function createVisionCameraEngine(): CameraEngine {
+	// One registry per engine, so two controllers never share a surface.
+	const surfaces = createSurfaceRegistry();
 	// Loaded when the default adapter is created; a missing peer is `cameraUnavailable`.
 	const { VisionCamera } = loadVisionCamera<{
 		VisionCamera: {
@@ -67,6 +83,10 @@ export function createVisionCameraEngine(_options: EngineOptions = {}): CameraEn
 	}
 
 	return {
+		awaitsSurfaceStart: true,
+
+		attachSurface: surface => surfaces.attach(surface),
+
 		async start() {
 			// The preview component owns session activation; the engine only needs
 			// to confirm a device exists before the surface mounts.
@@ -81,7 +101,7 @@ export function createVisionCameraEngine(_options: EngineOptions = {}): CameraEn
 		},
 
 		async capture(request: CaptureRequest) {
-			const surface = getActiveVisionSurface();
+			const surface = surfaces.current();
 			if (!surface) {
 				throw new CameraError(
 					'notReady',

package/src/native/visionSurface.ts

@@ -1,34 +1,59 @@
 /**
- * Bridge between the mounted VisionCamera preview surface and the default
- * engine adapter.
+ * The port between a mounted preview surface and an engine.
  *
- * VisionCamera v5 owns capture through the session that the `<Camera>` view
+ * VisionCamera v5 owns capture through the session the `<Camera>` view
  * configures, so the photo output only exists while a surface is mounted. The
- * engine is created by the app before any surface exists, so the surface
- * registers itself here on mount and the engine reads it back at capture time.
+ * engine is created before any surface exists, so the surface attaches itself
+ * to the engine and the engine reads it back at capture time.
  *
- * A single registration slot is deliberate: one camera session can be active at
- * a time, so a second surface replacing the first is the correct behaviour.
+ * The registry belongs to an engine instance, not to the module. A module-level
+ * slot meant two controllers — two screens in a stack — shared one, so a
+ * capture could run through the other screen's surface (CAM-20).
  */
 
+import type { CameraErrorCode } from '../diagnostics/errors';
 import type { CapturedImage, CaptureRequest } from '../config/types';
 
+/** What the mounted preview actually is, once the device and format are known. */
+export interface SurfaceInfo {
+	/** Capture dimensions of the selected format, in pixels. */
+	readonly imageWidth: number;
+	readonly imageHeight: number;
+	/** Clockwise degrees the image is rotated relative to the preview. */
+	readonly orientation: number;
+	/** The position of the device actually mounted, whatever was asked for. */
+	readonly cameraPosition: 'front' | 'back';
+}
+
 export interface VisionSurface {
 	capture(request: CaptureRequest): Promise<CapturedImage>;
 }
 
-let active: VisionSurface | null = null;
+/** What a surface reports back about its own session. */
+export interface SurfaceEvents {
+	/** The preview is running: frames are arriving. */
+	onStarted(info: SurfaceInfo): void;
+	/** The session failed or was taken away (another app, a phone call). */
+	onFailed(code: CameraErrorCode): void;
+}
 
-/** Registers the mounted surface. Returns an unregister function. */
-export function registerVisionSurface(surface: VisionSurface): () => void {
-	active = surface;
-	return () => {
-		if (active === surface) {
-			active = null;
-		}
-	};
+export interface SurfaceRegistry {
+	/** Attaches the mounted surface. Returns the detach function. */
+	attach(surface: VisionSurface): () => void;
+	current(): VisionSurface | null;
 }
 
-export function getActiveVisionSurface(): VisionSurface | null {
-	return active;
+export function createSurfaceRegistry(): SurfaceRegistry {
+	let active: VisionSurface | null = null;
+	return {
+		attach(surface) {
+			active = surface;
+			return () => {
+				if (active === surface) {
+					active = null;
+				}
+			};
+		},
+		current: () => active,
+	};
 }

package/src/react/CameraPreview.tsx

@@ -18,6 +18,8 @@ import {
 
 import type { PreviewGeometry, ResizeMode } from '../config/types';
 import type { CameraController } from '../core/controller';
+import type { CameraErrorCode } from '../diagnostics/errors';
+import type { SurfaceInfo, VisionSurface } from '../native/visionSurface';
 import { useCameraState } from './hooks';
 import type { VisionCameraFeedProps } from './VisionCameraFeed';
 
@@ -36,7 +38,15 @@ export interface CameraPreviewProps {
 /** 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. */
+/**
+ * Nominal capture dimensions, until the mounted surface reports its own.
+ *
+ * Geometry built on these was landscape on a portrait phone, so every mapped
+ * rectangle was wrong on a real device (CAM-10). `onGeometryChange` now fires
+ * again with the real numbers as soon as the preview reports them, and apps
+ * that map coordinates should wait for `state.surface` rather than the first
+ * geometry.
+ */
 const DEFAULT_IMAGE_WIDTH = 1920;
 const DEFAULT_IMAGE_HEIGHT = 1080;
 
@@ -66,6 +76,19 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 		};
 	}, [controller]);
 
+	const attachSurface = useCallback(
+		(surface: VisionSurface) => controller.attachSurface(surface),
+		[controller],
+	);
+	const onSurfaceStarted = useCallback(
+		(info: SurfaceInfo) => controller.reportSurfaceStarted(info),
+		[controller],
+	);
+	const onSurfaceFailed = useCallback(
+		(code: CameraErrorCode) => controller.reportSurfaceFailed(code),
+		[controller],
+	);
+
 	const onLayout = useCallback((event: LayoutChangeEvent) => {
 		const { width, height } = event.nativeEvent.layout;
 		setLayout({ width, height });
@@ -75,16 +98,17 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 		if (!layout || layout.width === 0 || layout.height === 0) {
 			return null;
 		}
+		const surface = state.surface;
 		return {
-			imageWidth: DEFAULT_IMAGE_WIDTH,
-			imageHeight: DEFAULT_IMAGE_HEIGHT,
+			imageWidth: surface && surface.imageWidth > 0 ? surface.imageWidth : DEFAULT_IMAGE_WIDTH,
+			imageHeight: surface && surface.imageHeight > 0 ? surface.imageHeight : DEFAULT_IMAGE_HEIGHT,
 			previewWidth: layout.width,
 			previewHeight: layout.height,
 			resizeMode,
-			orientation: 0,
-			isMirrored: state.cameraPosition === 'front',
+			orientation: surface?.orientation ?? 0,
+			isMirrored: (surface?.cameraPosition ?? state.cameraPosition) === 'front',
 		};
-	}, [layout, resizeMode, state.cameraPosition]);
+	}, [layout, resizeMode, state.cameraPosition, state.surface]);
 
 	useEffect(() => {
 		if (geometry && onGeometryChange) {
@@ -92,7 +116,12 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 		}
 	}, [geometry, onGeometryChange]);
 
-	const feedRequested = state.session === 'active' && state.permission === 'granted';
+	// Mounted while the session is coming up, running, or paused: the surface is
+	// what makes it come up at all, and unmounting it on a pause meant rebuilding
+	// the device, the session and the photo output on every resume (CAM-08, CAM-09).
+	const feedRequested =
+		state.permission === 'granted' &&
+		(state.session === 'starting' || state.session === 'active' || state.session === 'paused');
 
 	// Lazy require so importing this package never pulls in the native module
 	// for consumers that only use the pure utilities or the test adapter.
@@ -129,6 +158,10 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 					cameraPosition={state.cameraPosition}
 					resizeMode={resizeMode}
 					torchEnabled={state.torchEnabled}
+					isActive={state.session !== 'paused'}
+					attachSurface={attachSurface}
+					onStarted={onSurfaceStarted}
+					onFailed={onSurfaceFailed}
 				/>
 			) : null}
 			{children}

package/src/react/VisionCameraFeed.tsx

@@ -30,13 +30,21 @@ import {
 	type ResizeMode,
 } from '../config/types';
 import { DEFAULT_QUALITY } from '../core/captureController';
-import { CameraError, isCameraError } from '../diagnostics/errors';
-import { registerVisionSurface } from '../native/visionSurface';
+import { CameraError, isCameraError, type CameraErrorCode } from '../diagnostics/errors';
+import type { SurfaceInfo, VisionSurface } from '../native/visionSurface';
 
 export interface VisionCameraFeedProps {
 	readonly cameraPosition: CameraPosition;
 	readonly resizeMode: ResizeMode;
 	readonly torchEnabled: boolean;
+	/** False while the session is paused: the view stays mounted, the camera stops. */
+	readonly isActive: boolean;
+	/** Attaches this surface to the engine that captures through it. */
+	readonly attachSurface: (surface: VisionSurface) => () => void;
+	/** The preview is running; carries what the mounted device turned out to be. */
+	readonly onStarted: (info: SurfaceInfo) => void;
+	/** The session failed or the camera was taken away. */
+	readonly onFailed: (code: CameraErrorCode) => void;
 }
 
 const styles = StyleSheet.create({
@@ -71,6 +79,20 @@ function toFilePath(uri: string): string {
 	return uri.startsWith('file://') ? uri.slice('file://'.length) : uri;
 }
 
+/**
+ * What a native session error means, from the code VisionCamera reports
+ * (CAM-08). Anything unrecognised is an interruption: the session is gone, and
+ * the app may try again.
+ */
+function nativeSessionCode(error: unknown): CameraErrorCode {
+	const code = String((error as { code?: unknown })?.code ?? '').toLowerCase();
+	if (code.includes('permission')) return 'permissionDenied';
+	if (code.includes('in-use') || code.includes('already-in-use')) return 'cameraInUse';
+	if (code.includes('unavailable') || code.includes('no-device')) return 'cameraUnavailable';
+	if (code.includes('restricted') || code.includes('blocked')) return 'cameraBlocked';
+	return 'interrupted';
+}
+
 /** 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);
@@ -79,6 +101,7 @@ function asCameraError(error: unknown, code: 'captureFailed' | 'storageFailure')
 async function capturePhoto(
 	photoOutput: CameraPhotoOutput,
 	request: CaptureRequest,
+	/** The device actually mounted; the request cannot ask for another one. */
 	cameraPosition: CameraPosition,
 ): Promise<CapturedImage> {
 	let photo: Awaited<ReturnType<CameraPhotoOutput['capturePhoto']>>;
@@ -117,7 +140,8 @@ async function capturePhoto(
 			width: photo.width,
 			height: photo.height,
 			timestamp: Date.now(),
-			cameraPosition: request.cameraPosition ?? cameraPosition,
+			// The camera that took it, not the one the request named (CAM-06).
+			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',
@@ -136,10 +160,37 @@ async function capturePhoto(
 	}
 }
 
+/** What the device actually is, for coordinate mapping (CAM-10). */
+function surfaceInfoOf(
+	device: { readonly position?: string; readonly formats?: readonly DeviceFormat[] } | undefined,
+	fallback: CameraPosition,
+): SurfaceInfo {
+	const format = device?.formats?.[0];
+	return {
+		imageWidth: format?.photoWidth ?? format?.videoWidth ?? 0,
+		imageHeight: format?.photoHeight ?? format?.videoHeight ?? 0,
+		orientation: 0,
+		cameraPosition:
+			device?.position === 'front' || device?.position === 'back' ? device.position : fallback,
+	};
+}
+
+/** The slice of VisionCamera's `CameraDeviceFormat` the geometry needs. */
+interface DeviceFormat {
+	readonly photoWidth?: number;
+	readonly photoHeight?: number;
+	readonly videoWidth?: number;
+	readonly videoHeight?: number;
+}
+
 export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 	cameraPosition,
 	resizeMode,
 	torchEnabled,
+	isActive,
+	attachSurface,
+	onStarted,
+	onFailed,
 }) => {
 	const device = useCameraDevice(cameraPosition);
 	const photoOutput = usePhotoOutput({ quality: DEFAULT_QUALITY });
@@ -151,7 +202,7 @@ export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 		[photoOutput, cameraPosition],
 	);
 
-	useEffect(() => registerVisionSurface(surface), [surface]);
+	useEffect(() => attachSurface(surface), [attachSurface, surface]);
 
 	// VisionCamera applies `torchMode` on mount, before the camera is active, and
 	// leaves the native "Camera is not active" rejection unhandled — one red
@@ -172,7 +223,12 @@ export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 			style={styles.feed}
 			device={device}
 			outputs={[photoOutput]}
-			isActive={true}
+			// Mounted through `paused` and `starting`: unmounting the view tore the
+			// session down and rebuilding it cost the first-frame budget (CAM-09).
+			isActive={isActive}
+			// The session is active when frames arrive, not when it was asked for.
+			onStarted={() => onStarted(surfaceInfoOf(device, cameraPosition))}
+			onError={(error: unknown) => onFailed(nativeSessionCode(error))}
 			resizeMode={resizeMode}
 			// Left unset until the app first touches the torch, so the device's own default stands.
 			{...(torchMode === undefined ? {} : { torchMode })}

package/src/react/hooks.ts

@@ -15,7 +15,7 @@ import {
 	type CameraControllerOptions,
 } from '../core/controller';
 
-export function useCameraController(options: CameraControllerOptions = {}): CameraController {
+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);

package/src/storage/artifactStore.ts

@@ -7,6 +7,8 @@
  * the package can refuse to delete anything it did not create (FR-028).
  */
 
+import { CameraError } from '../diagnostics/errors';
+
 export interface ArtifactStore {
 	/** Absolute path of the package-owned temporary directory. */
 	temporaryDirectory(): string;
@@ -112,7 +114,10 @@ export function createArtifactStore(
 				return uri;
 			}
 			if (!fs.move) {
-				throw new Error('This FileSystemBridge has no move(), so it cannot adopt a capture');
+				throw new CameraError(
+					'storageFailure',
+					'This FileSystemBridge has no move(), so it cannot adopt a capture',
+				);
 			}
 			await fs.ensureDirectory(root);
 			const name = path.slice(path.lastIndexOf('/') + 1) || `capture-${Date.now()}.jpg`;
@@ -132,7 +137,9 @@ export function createArtifactStore(
 export function createCacheArtifactStore(options: StoreOptions = {}): ArtifactStore {
 	const fs = options.fs;
 	if (!fs) {
-		throw new Error(
+		// A typed error, like every other failure this package reports.
+		throw new CameraError(
+			'storageFailure',
 			'createCacheArtifactStore requires a FileSystemBridge. Pass `fs`, or use ' +
 				'createTestCamera() in tests.',
 		);